Skip to content
AtomPRD

Phase 6 — Handoff & iterate

The spec is not done when authoring is done. Phase 6 covers everything that happens after features are written:

  • Snapshot — version-stamp the project before risky changes / stakeholder reviews / releases.
  • Mark ready — the gate from “draft authoring” to “engineering ready”.
  • Codegen — atoms → running code (SenLang, NestJS, custom targets).
  • MCP — wire the spec into a coding agent so the agent reads atoms as live context.
  • Audit log — who changed what, when.
  • Iterate — locks, re-runs, restoring snapshots.

Snapshots — /projects/:id/history

Section titled “Snapshots — /projects/:id/history”

Time-travel for the entire project tree.

What a snapshot captures

Section titled “What a snapshot captures”

The full project tree at a point in time:

  • Every decomposition_node row (atom block + parent edges + lexorank).
  • Every node_relation row (typed edges).
  • Every block’s metadata, intent, behavior, provenance jsonb.
  • The project’s settings (profile selection, tree mode).
  • Optional description (free-text, e.g. “Before W6 review”) and tag (v0.1, v1.0, …).

Snapshots are immutable. They never reflect later edits — you took a freeze.

The history page surfaces

Section titled “The history page surfaces”
┌── PageGuide ─────────────────────────────────────────────┐
│ ⏱ Why snapshots matter                                   │
│ Use them before risky AI rewrites, before sharing with   │
│ stakeholders, or to mark releases (v0.1, v1.0).          │
└──────────────────────────────────────────────────────────┘


┌── Take a snapshot ───────────────────────────────────────┐
│ Description (optional): [ Before W6 review        ]      │
│                                          [ 📸 Take ]     │
└──────────────────────────────────────────────────────────┘


┌── Snapshot list ─────────────────────────────────────────┐
│ ◯ 2026-05-03 14:21  "Before W6 review"   tag: —          │
│ ◯ 2026-05-02 18:00  (no description)     tag: v0.1       │
│ ◯ 2026-05-01 09:30  "Initial seed"        tag: —          │
│ ...                                                       │
│  Compare from: ◯ 2026-05-01   Compare to: ◯ 2026-05-03   │
│                                  [ View diff →]           │
└──────────────────────────────────────────────────────────┘

Per row:

  • Take a snapshot — POST /projects/:id/snapshots with optional description.
  • Tag — name a snapshot for release tracking (v0.1, v1.0). One tag per snapshot.
  • Compare — pick two via radios → View diff opens a modal with adds / removes / patches.
  • Restore — pick a row → 🔄 → confirms in a dialog → the project tree reverts.

Restoration is safe

Section titled “Restoration is safe”

Before any restore the API takes a pre-restore safety snapshot automatically:

1. POST /projects/:id/snapshots (silent, no description)
2. Apply restore from chosen snapshot.
3. If restore fails — pre-restore is intact, project state untouched.
4. If restore succeeds — pre-restore is the rollback target.

So restore is reversible. The user always has a back-button.

Mark ready

Section titled “Mark ready”

Already covered in Phase 4 → Mark ready. Recap:

  • Pill goes emerald-enabled at completeness ≥ 0.7.
  • Click → readiness checklist popover → Mark ready ✨ button.
  • Mutation PATCH /api/projects/:projectId/nodes/:blockId with metadata.ready_for_review: true + ready_at: <ISO>.
  • Pill becomes a passive emerald Ready badge.

This is the explicit handoff signal between the PM authoring lane and the engineering lane. Engineers wire on the ready_for_review flag — only “Ready” features get pulled into a sprint.

Codegen

Section titled “Codegen”
[atoms]   →   @atomprd/codegen-<target>   →   [running code]

The OSS half ships two targets today:

  • @atomprd/codegen-senlang v0.3.0 — Sen Document + RFC-0010 scenarios + RFC-0009 source map. The reference target.
  • @atomprd/codegen-nestjs — entities + controllers + migrations. WIP.

The Cloud surfaces /codegen as an in-app code-generation page; the UI is in early-access (“Coming soon”) in the current build. Until then, codegen runs from a user-side script:

import { PrdDocument } from "@atomprd/core";
import { runTemplate } from "@atomprd/codegen";
import { senlangTemplate } from "@atomprd/codegen-senlang";
import manifest from "./atoms/manifest.json" assert { type: "json" };


const doc = PrdDocument.load(manifest);
const result = await runTemplate(senlangTemplate, { doc, outDir: "./out" });

Pull the manifest:

  • Via MCP — see below; the get_export tool returns the latest export bundle.
  • Via REST — GET /api/projects/:id/export?target=senlang returns the manifest + scenarios + map zipped.

Custom targets follow the CodegenTemplate interface. See Codegen → Custom targets for the skeleton.

MCP integration

Section titled “MCP integration”

The right pane’s MCP sub-tab is the front-door for wiring the spec into a coding agent.

Issue a token

Section titled “Issue a token”
┌── MCP ────────────────────────────────────────┐
│ ① Issue a personal access token (PAT)         │
│    Name: [ claude-code on laptop          ]   │
│    Expires: ◉ 90 days   ○ 30   ○ never        │
│                              [ Issue token ]  │
│                                                │
│ ② Copy this — it's shown ONCE                 │
│    ┌──────────────────────────────────────┐   │
│    │ atom_pat_a1b2c3d4e5f6...             │   │
│    │                          [ 📋 Copy ] │   │
│    └──────────────────────────────────────┘   │
│                                                │
│ ③ Paste into your IDE config (see snippet     │
│    below) and restart the IDE.                │
└────────────────────────────────────────────────┘

Backend: POST /pats with { name, expiresInDays } returns the plaintext token once. The DB stores only a sha256 hash. Rotation = issue new + revoke old.

Copy IDE config

Section titled “Copy IDE config”

Below the token, the panel shows three tabbed config snippets — Cursor / Claude Code / Cline — pre-filled with the project ID + token. See MCP → Integration for the canonical snippets.

~/.claude/mcp.json
{
  "mcpServers": {
    "atomprd": {
      "command": "bunx",
      "args": [
        "@atomprd/mcp-server",
        "--project", "<project-id>",
        "--token",   "<PAT>"
      ]
    }
  }
}

Restart the IDE → tools appear (mcp__atomprd__list_atoms, mcp__atomprd__get_atom, mcp__atomprd__find_criteria, …).

The agent loop

Section titled “The agent loop”
1. Agent reads task: "Implement feat_create_habit_h14a"
2. Agent calls atomprd:get_atom → feature + Layer 2
3. Agent calls atomprd:find_criteria → acceptance criteria
4. Agent calls atomprd:query_relations (uses_entity) → entity refs
5. Agent calls atomprd:get_atom for each entity → fields
6. Agent writes code based on the slice it pulled
7. Agent calls atomprd:link_code_path to record the implementation
8. Agent calls atomprd:update_criterion_status to flip criteria done

The agent never sees the rest of the project — only what it asked for. Every write tool logs to audit_log.

Live MCP call log

Section titled “Live MCP call log”

The MCP sub-tab also surfaces the last ~20 MCP tool calls in real-time:

🤖 mcp__atomprd__get_atom         feat_create_habit_h14a   2s
🤖 mcp__atomprd__find_criteria    feat_create_habit_h14a   3s
🤖 mcp__atomprd__update_criterion_status   cri_first_load_h31a   12s

So you can watch the agent read your spec. Useful for debugging “why didn’t the agent see this criterion?” — the log shows it never asked.

Audit log — /org/audit

Section titled “Audit log — /org/audit”

(Coming soon in the early-access build — shipped at the API level, UI deferred.)

When live, the audit log surfaces:

  • Every block create / patch / delete + actor + atom kind + atom id.
  • Every snapshot taken / restored + actor.
  • Every MCP call + actor (token name) + tool + args summary.
  • Every billing change + actor.
  • Filter by date range, actor, project, atom kind.

Underlying table audit_log is already populated by every write across the API. The dashboard’s Live activity tail is a small slice of this.

Iteration loop

Section titled “Iteration loop”

The full lifecycle of a feature:

graph TD
  classDef active fill:#dcfce7,stroke:#16a34a,color:#0a0a0a;
  classDef wait   fill:#fef3c7,stroke:#f59e0b,color:#0a0a0a;
  classDef ship   fill:#dbeafe,stroke:#3b82f6,color:#0a0a0a;

  Auth[Author<br/>Layer 1 + Layer 2]:::active --> Snap[📸 Snapshot]:::wait
  Snap --> Crit[🤖 AI Critique<br/>Coach + 4 personas]:::active
  Crit --> Patch[Patch issues<br/>lock fields you trust]:::active
  Patch --> Ready{≥ 70% ?}
  Ready -- no --> Auth
  Ready -- yes --> Mark[Mark ready ✨]:::ship
  Mark --> MCP[Agent reads atoms<br/>via MCP]:::ship
  MCP --> Code[Code lands;<br/>link_code_path<br/>update_criterion_status]:::ship
  Code -. spec drift detected .-> Auth

Lock + iterate (Pattern A vs C/D, see Concepts → Four patterns → The lock flag) is the working loop. You hand-author the 20% that matters, automate the rest, and keep iterating.

What’s “Coming soon” in the early-access build

Section titled “What’s “Coming soon” in the early-access build”

These pages render <ComingSoonPage> placeholders today; the underlying API and packages exist:

RouteStatus
/codegenUI deferred. Run codegen from a user-side script (above) or via MCP get_export tool.
/integrationsUI deferred. MCP wiring lives in the workspace right pane (above).
/org/membersUI deferred. Single-user orgs work today.
/org/invitationsUI deferred.
/org/billingUI deferred. Plan upgrades via direct Lemon Squeezy link.
/org/auditUI deferred. Underlying log is populated.
/org/tokensUI deferred. PATs issued via the workspace MCP sub-tab today.

Watch the changelog for these landing pages going live.

See also

Section titled “See also”