Phase 4 — Workspace authoring

The cloud workspace at /projects/:id/workspace is built around one idea: a feature has a shape, and you should be able to see it at a glance. This page walks the moment-to-moment user experience inside the workspace — what shows up, why it shows up, and what each surface is doing under the hood.

If you want the editor reference (modal tabs, fields), see Authoring → Six-tab editor. If you want the recommended content order (vision → persona → module → feature → criteria), see Authoring → Workflow. This page is the moment-to-moment workspace experience.

1. First open — the 5-step tour

The first time you land in a project workspace, a dimming overlay appears with a spotlight and a tooltip. Five steps, each tied to a real element on screen via data-tour attributes:

Step	Spotlight target	What it tells you
1	`[data-tour='completeness-ring']`	”Feature completeness” — the ring shows how complete the feature is. Hover for breakdown.
2	`[data-tour='next-step-banner']`	”Next step suggestions” — AtomPRD watches your spec and tells you the highest-leverage next thing. Click Go to jump there.
3	`[data-tour='feature-sections']`	”Feature sections” — blocks group into Overview / Acceptance / Tasks / Risks / Fixtures / Architecture so you see the feature’s shape.
4	`[data-tour='view-toggle']`	”Sections vs Graph” — switch to the graph view to see how blocks connect.
5	`[data-tour='right-pane']`	”AI Critique + MCP” — Coach persona for gap-finding, Library for templates, Cursor / Claude Code via MCP.

The tour is dismissible at any step (✕ in the corner or the Skip tour link) and never reappears — dismissal is recorded in localStorage under atomprd:workspace-tour-seen. The tour also auto-skips a step if its target element doesn’t exist (e.g. you have no features yet) so it never blocks on a missing surface.

graph LR
  classDef step fill:#eef0ff,stroke:#4f46e5,color:#0a0a0a;
  S1[1. Ring]:::step --> S2[2. Banner]:::step --> S3[3. Sections]:::step --> S4[4. View toggle]:::step --> S5[5. Right pane]:::step --> Done[localStorage flag set]

2. Open an empty Feature

A new feature has no children yet. Three things happen:

Completeness ring is grey at 0%. The five-axis breakdown in the tooltip shows everything at 0/25, 0/25, 0/18, 0/12, 0/20.
Next-step banner appears in primary tone: “Start with a description — what does this feature does?” with a Go button.
Seven sections render with empty states. Each non-empty-eligible section (Overview, Acceptance criteria, Tasks, Risks & invariants, Test data / fixtures, Architecture decisions, plus a catch-all More) shows:
- A short coaching line (“Add JSON examples that verify your criteria…”).
- An Add <kind> button.
- Where applicable, a 💡 Try example chip seeded with a realistic atom — clicking inserts the example as a real block.

Click Try example under Overview → a description block appears with sensible TipTap content → ring jumps from 0% to 25%. The next-step banner flips to “Add 3+ acceptance criteria in EARS notation.”

This is the core loop: surface a single concrete next action; let the user act with one click; immediately reflect progress.

3. Add 3 criteria + 1 fixture — ring goes amber

Keep filling. Section by section:

3× Try example under Acceptance criteria → WHEN/IF/WHILE criteria. Ring climbs to ~50%.
1× Try example under Test data / fixtures → a valid_login payload. Ring hits ~60% in the amber zone (≥40%, <80%).
The next-step banner cycles: “Add 3+ criteria” → “Add fixtures so engineers can verify” → as completeness clears 80%, the banner flips to success tone: ”✨ Looks complete — open AI Critique on the right pane for a second opinion.”

The thresholds are weighted (see Completeness scoring below). The amber → emerald transition sits at 0.8 (80%), the Mark ready gate at 0.7 (70%).

4. Open Coach persona — AI lists 3-5 gaps

The right pane has three sub-tabs: AI Critique, Library, MCP. Open AI Critique. The 5 default personas (Coach 🎓, PM Critic 📋, Architect 🏗, QA 🔍, UX 🎨) are visible in a 2-column picker; click Coach then Critique this block with the feature selected.

Coach is the gap-finder — it looks at what’s missing (criteria, fixtures, error paths, edge cases) and returns 3-5 specific gaps with severity badges (🔴 / 🟡 / 🟢) and suggested next blocks.

Critiques are cached at sha256(persona + block + metadata + model). Repeated runs on an unchanged block are free and instant. See Phase 5 — AI assistance for the full persona catalog and how Pattern D suggestions plug into the Behavior tab of the editor modal.

5. Cross 70% — Mark ready

Once completeness ≥ 0.7 the Mark ready pill (top-right of the feature card) goes from disabled-grey to enabled-emerald. Click it:

A popover shows the readiness checklist — the same five axes, each with a ✓ / ○ + the earned/max ratio.
A Mark ready ✨ button at the bottom is disabled while <70% (the popover instead reads “Need ≥70% completeness. Currently <X%.”).
Click → mutation PATCH /api/projects/:projectId/nodes/:blockId with metadata.ready_for_review: true + ready_at: <ISO>.
On success a toast confirms; the pill is replaced by a passive emerald Ready badge.

The 70% threshold is a sensible-default — it triggers when you have description + 3 criteria + 1 task + 1 risk + 1 fixture. Adjustable per-project (post-launch).

6. Module view — feature cards with rings

Navigate up to the module in the left tree. Instead of a flat feature list you get a dashboard:

Counts strip at the top: Features (N) · Filter pills.
Filter pills: All, Needs criteria (criteria <3), Needs fixtures (fixtures = 0), Ready (≥80%, emerald).
Sort toggle: least complete (default) or A→Z.
Card grid (1 / 2 / 3 columns responsive). Each card:
- Completeness ring (42 px, same as the workspace).
- Title + arrow on hover.
- Mini-badge strip: desc, Nc (criteria count), Nt (tasks), risk, Nfx (fixtures). Each badge is emerald when the axis passes its bar, grey otherwise.
- Phase line: Just starting / In progress / Almost ready / Complete.

Click Needs fixtures filter → instantly see the cards weak on test data. Click a card → drop into that feature’s workspace.

The module dashboard is your triage surface — pre-grooming a sprint, scanning for spec drift, finding the weakest features before standup.

7. Toggle Graph view

Top of the feature workspace: a view toggle between Sections (default) and Graph. Flip to graph and the same feature renders as a 6-column SVG:

Overview  Criteria  Fixtures  Tasks  Risks  Decisions
   │         │          │       │      │        │
   └─ blocks render as rounded rectangles in their column
       └─ relations render as cubic-Bezier curves between rows
           └─ relation type (verifies, depends_on, …) labeled mid-edge

Clicking any node scrolls its corresponding block into view in the Sections panel + briefly highlights it. The graph is inline SVG — no Cytoscape, no D3, no extra dependency. Simple columnar layout grouped by atom-kind family.

If no relations are wired yet, an italic note prompts you to wire them via the block’s Relations tab.

This is where the feature’s “shape” becomes literally visible: criteria → fixtures → tasks → criteria. Spec coherence at a glance.

8. Hover a relation chip — feel the living spec

Back in Sections view, every block summary has a chip strip at the bottom showing outgoing + incoming relations:

→ verifies · feature · feat_login_aaaa
← implements · task · tsk_wire_form_bbbb

Interaction	Effect
Hover chip	The target block’s row glows / lifts (hover state).
Click chip	Smooth-scroll to the target block + 1.5s flash highlight.
Hover out	Highlight clears.
Click on a stale chip (target deleted)	No-op + greyed appearance.

Chip direction is encoded in the arrow: → outgoing (this block points elsewhere), ← incoming (something points at this block). Relation types render mono-spaced + uppercase; the kind is the lowercase label after the dot.

This is the move from “PRD as a document” to PRD as a living, navigable graph. Ranges of acceptance criteria, fixtures and tasks aren’t just listed — they’re cross-linked, and the cross-links are clickable.

Completeness scoring

The ring + readiness gate use a single weighted score across five axes:

Axis	Earned	Max	Done at
Description present	25	25	yes
Criteria count (linear up to 5)	5 each, capped 25	25	≥3
Tasks count (linear up to 3)	6 each, capped 18	18	≥1
Risk OR invariant present	12	12	yes
Fixtures (linear up to 5)	4 each, capped 20	20	≥ min(criteria, 5)

Total 100. Hits 100% when: description + 5 criteria + 3 tasks + 1 risk + ≥5 fixtures. Sensible “ready” sits at 70: description + 3 criteria + 1 task + 1 risk + 1 fixture.

Tone bands:

🟢 Emerald ≥ 0.8 — almost ready / complete.
🟡 Amber 0.4 – 0.8 — in progress.
⚪ Grey < 0.4 — just starting.

The score is recomputed in the browser whenever a child block is added / patched / deleted; no server round-trip. The same function powers the workspace ring, the module dashboard mini-rings, and the readiness checklist.

Next-step rule order

The banner picks the first matching rule in this order:

No description → “Start with a description — what does this feature does?”
<3 criteria → “Add N more criterion(s) (X/3 minimum).”
Fewer fixtures than criteria (capped 3) → “Add fixtures (JSON examples)…”
0 tasks → “Break this feature into tasks for implementation.”
No risk → “What could go wrong? Add a risk…”
Score ≥ 0.8 → success tone ”✨ Looks complete — open AI Critique…”
Otherwise — banner hides.

Each banner is dismissible per-(feature, step) — localStorage key atomprd:nextstep-dismissed:<featureId>:<stepId>. Power users can mute individual suggestions once they’ve internalised the workflow without losing the banner globally.

The Go button scrolls the relevant section into view + opens the section’s add-block form. Section refs are registered by the parent so the banner can target them precisely.

Three-pane layout

Beyond the rich feature view, the workspace as a whole is three panes:

┌─────────┬────────────────────────────┬─────────┐
│  Tree   │   Block editor (centre)    │ Right   │
│  pane   │   - sections / graph       │  pane   │
│  (left) │   - blocks                 │  - AI   │
│         │   - chips                  │  - Lib  │
│         │                            │  - MCP  │
└─────────┴────────────────────────────┴─────────┘

Left pane — module / feature tree. Drag-and-drop reorder. + Add per level.
Centre pane — the active block (feature, module, or any block kind). Sections or Graph view.
Right pane — three sub-tabs:
- AI Critique — see Phase 5.
- Library — curated module / feature templates seeded by the Cloud (e.g. “Auth”, “Billing”, “Settings”). One-click insert into the active module.
- MCP — connect-an-agent wizard. Issue a token, copy the IDE config, see the live MCP call log. See Phase 6 — Handoff.

Right pane is collapsible (≥ lg breakpoint) to free centre-pane width on smaller screens.