@plazmodium/odin 0.3.4-beta → 0.3.5-beta

package/README.md

@@ -150,6 +150,12 @@ Your AI agent now has these tools available:
 | `odin.run_policy_checks` | Run deterministic policy checks for submitted claims |
 | `odin.verify_design` | Run formal design verification (TLA+ model checking) on a `.machine.ts` DSL file |
 | `odin.capture_learning` | Capture a reusable learning with semantic domain matching |
+| `odin.get_skill_proposal_queue` | Inspect repeated unresolved learning topics that may warrant a generated skill draft |
+| `odin.get_skill_proposals` | List drafted, approved, rejected, or published skill proposal records |
+| `odin.record_skill_proposal_draft` | Persist a drafted generated-skill proposal and run deterministic validation |
+| `odin.record_skill_proposal_decision` | Approve or reject a drafted skill proposal |
+| `odin.publish_skill_proposal` | Publish an approved skill proposal into `.odin/skills/generated/` |
+| `odin.sync_skill_proposal_candidates` | Persist the current deterministic proposal queue for later review/approval workflows |
 | `odin.get_feature_status` | Inspect feature state with workflow details |
 | `odin.verify_claims` | Check claim verification status |
 | `odin.get_claims_needing_review` | List claims waiting for watcher review |
@@ -333,6 +339,9 @@ Odin's learning system uses **semantic domain matching** to automatically route
 3. **Auto-targeting**: Matches passing both gates (≥ 1 strong keyword hit AND ≥ 0.60 relevance) are auto-declared as propagation targets. Weaker matches are returned as suggestions
 4. **Cross-feature corridors**: `odin.prepare_phase_context` retrieves related learnings from other features that share propagation targets, with tag intersection fallback
 5. **Resonance ranking**: Related learnings are ranked by domain density, corroboration (same-category learnings from different features), and recency — never modifying `confidence_score`
+6. **Proposal surfacing**: Repeated unresolved tags can be inspected via `odin.get_skill_proposal_queue` to identify candidate topics for governed skill drafting
+7. **Proposal persistence**: `odin.sync_skill_proposal_candidates` snapshots the current candidate queue into workflow state so later approval/draft flows and dashboard surfaces can build on stable relational state
+8. **Governed skill workflow**: draft generation, approval, and publish happen through `odin.record_skill_proposal_draft`, `odin.record_skill_proposal_decision`, and `odin.publish_skill_proposal` rather than automatic built-in self-modification
 
 ### Exploration
 

package/builtin/ODIN.md

@@ -1,7 +1,7 @@
 # ODIN.md
 
 > **Odin** is a Specification-Driven Development (SDD) framework for AI-assisted development.
-> It provides 12 specialized agents, adaptive complexity levels, a learnings system with
+> It provides 11 specialized workflow/support agents, adaptive complexity levels, a learnings system with
 > confidence scoring, EVALS for health monitoring, and Watcher verification for critical phases.
 
 ---
@@ -51,7 +51,7 @@ When developers use AI coding assistants without proper specifications:
 
 1. **Spec-First, Always**: Implementation code is never written without an approved specification. The spec is the contract.
 
-2. **Context Pulling > Context Pushing**: AI agents autonomously fetch what they need (via MCP) instead of developers manually copy-pasting files, schemas, and tickets.
+2. **Context Pulling > Context Pushing**: The orchestrator session pulls what agents need (via MCP and other tools) instead of developers manually copy-pasting files, schemas, and tickets.
 
 3. **Adaptive Complexity**: Not every task needs a 10-page specification. Match the spec depth to the task complexity.
 
@@ -61,7 +61,7 @@ When developers use AI coding assistants without proper specifications:
 - **Learnings system** with confidence scoring and multi-target propagation
 - **Development Evals** for pre/post-build behavior verification
 - **EVALS** for health monitoring and performance diagnostics
-- **11-phase workflow** with 12 specialized agents
+- **11-phase workflow** with 11 specialized workflow/support agents
 - **Watcher verification** - Policy Engine + LLM escalation for critical phases
 - **Skills system** with 36+ domain-specific knowledge modules
 
@@ -71,7 +71,7 @@ When developers use AI coding assistants without proper specifications:
 
 | Phase | Name | Agent | Watched? | Description |
 |-------|------|-------|----------|-------------|
-| 0 | Planning | Planner | No | Epic decomposition (L3 only) |
+| 0 | Planning | Planner | No | Planning kickoff; L3 decomposes epics, L1/L2 can stay brief |
 | 1 | Product | Product | No | PRD generation (complexity-gated) |
 | 2 | Discovery | Discovery | No | Requirements gathering |
 | 3 | Architect | Architect | No | Specification drafting |
@@ -92,7 +92,7 @@ All features: PLANNING -> PRODUCT -> DISCOVERY -> ARCHITECT -> GUARDIAN -> BUILD
 
 > **Watched agents** (Builder, Integrator, Release) emit structured claims that are verified by the Policy Engine and optionally the LLM Watcher. See [Watcher Verification](#watcher-verification).
 
-> **Detailed Documentation**: See [multi-agent-protocol.md](docs/framework/multi-agent-protocol.md)
+> **Detailed Documentation**: See `agents/definitions/` for phase prompts and [runtime/README.md](runtime/README.md) for runtime setup.
 
 ### Orchestrator Loop
 
@@ -311,7 +311,7 @@ Before implementation, score your spec:
 
 ---
 
-## The 12 Agents
+## The 11 Agents
 
 | Agent | Phases | Watched? | Role |
 |-------|--------|----------|------|
@@ -326,7 +326,6 @@ Before implementation, score your spec:
 | [Documenter](agents/definitions/documenter.md) | 8 | No | Documentation generation |
 | [Release](agents/definitions/release.md) | 9 | **YES** | PR creation and feature archival |
 | [Watcher](agents/definitions/watcher.md) | Any | - | LLM escalation for claim verification |
-| [Consultant](agents/definitions/spec-driven-dev-consultant.md) | Any | No | Spec refinement and analysis |
 
 All agents inherit shared context from [_shared-context.md](agents/definitions/_shared-context.md).
 
@@ -483,7 +482,8 @@ odin.verify_claims({ feature_id: "FEAT-001" })
 | `CODE_DELETED` | Builder | File removed |
 | `TEST_PASSED` | Builder | Tests pass |
 | `BUILD_SUCCEEDED` | Builder | Build completes |
-| `INTEGRATION_VERIFIED` | Integrator | Merge + tests + runtime verified |
+| `TEST_ADDED` | Builder | Tests added for acceptance/regression coverage |
+| `INTEGRATION_VERIFIED` | Integrator | Feature branch build/tests/runtime verified |
 | `PR_CREATED` | Release | Pull request created |
 | `ARCHIVE_CREATED` | Release | Feature archived |
 
@@ -597,8 +597,8 @@ The `dev_initials` and `author` parameters in `odin.start_feature` identify the
 4. Each phase: `odin.prepare_phase_context` → agent work → `odin.record_phase_artifact` → `odin.record_phase_result`
 5. `odin.prepare_phase_context` starts the phase invocation timer; `odin.record_phase_result` completes it
 6. Release phase creates PR via `gh pr create`, then records it with `odin.record_pr`
-7. After the human merges the PR, record the merge with `odin.record_merge`
-6. Human reviews and merges (NEVER the agent)
+7. Human reviews and merges the PR (NEVER the agent)
+8. After the human merges the PR, record the merge with `odin.record_merge`
 
 > **CRITICAL**: Create the git branch BEFORE calling `odin.start_feature`. If branch creation fails (e.g., branch already exists, git error), do NOT create the feature — you would have a dead DB record with no branch. The branch is the real artifact; the DB record is tracking.
 
@@ -666,7 +666,7 @@ The runtime handles file upload (to Supabase Storage) and database recording aut
 - **Knowledge base**: Reference past specs for similar features
 - **Debugging**: Understand original requirements when bugs arise
 
-> **Setup**: See [SUPABASE-SETUP.md](docs/guides/SUPABASE-SETUP.md) for Edge Function deployment.
+> **Setup**: See [SUPABASE-SETUP.md](docs/guides/SUPABASE-SETUP.md) for Supabase migrations and private archive bucket setup.
 
 ---
 
@@ -837,7 +837,7 @@ The `odin` server is the Odin MCP Runtime. It provides all `odin.*` tools, manag
 
 | Tool | Purpose | When Used |
 |------|---------|-----------|
-| `context7` | Library docs lookup | Architect, Builder |
+| `context7` | Library docs lookup | Orchestrator on behalf of Architect/Builder |
 | `sequentialthinking` | Complex multi-step reasoning | Any complex task |
 | `memory` | Knowledge graph | Optional knowledge backup |
 
@@ -854,7 +854,7 @@ The `odin` server is the Odin MCP Runtime. It provides all `odin.*` tools, manag
 
 ### Security Rules
 
-- Odin runtime handles database access — agents use `odin.*` tools, not raw SQL
+- Odin runtime handles database access - the orchestrator uses `odin.*` tools on behalf of agents, never raw SQL in normal workflow execution
 - Docker Gateway: only invoke tools documented in agent definitions
 
 ---
@@ -1002,6 +1002,28 @@ odin.capture_learning({
 odin.explore_knowledge({
   tags: ["nextjs", "caching"]
 })
+
+odin.get_skill_proposal_queue({
+  statuses: ["DRAFT_READY", "CANDIDATE"],
+  limit: 10
+})
+
+odin.record_skill_proposal_draft({
+  topic_key: "artifactsigning",
+  drafted_by: "skill-creator-agent",
+  draft_markdown: "---\nname: artifact-signing\ndescription: Guidance for deterministic artifact signing.\ncategory: backend\n---\n\n# Artifact Signing\n"
+})
+
+odin.record_skill_proposal_decision({
+  topic_key: "artifactsigning",
+  status: "APPROVED",
+  decided_by: "guardian-agent"
+})
+
+odin.publish_skill_proposal({
+  topic_key: "artifactsigning",
+  published_by: "release-agent"
+})
 ```
 
 ### Status & Release
@@ -1035,7 +1057,7 @@ odin.record_merge({
 
 1. **Read the framework**: [SDD-framework.md](docs/framework/SDD-framework.md)
 2. **Set up the runtime**: [runtime/README.md](runtime/README.md)
-3. **Understand agents**: [multi-agent-protocol.md](docs/framework/multi-agent-protocol.md)
+3. **Understand agents**: `agents/definitions/`
 4. **See an example**: [example-workflow.md](docs/guides/example-workflow.md)
 5. **Database setup**: [SUPABASE-SETUP.md](docs/guides/SUPABASE-SETUP.md)
 6. **Explore skills**: [SKILLS-SYSTEM.md](docs/reference/SKILLS-SYSTEM.md)

package/builtin/agent-definitions/README.md

@@ -93,7 +93,7 @@ The Watcher agent is called via LLM escalation when the Policy Engine cannot mak
   - HIGH risk claims
   - Claims with missing evidence
   - Policy Engine inconclusive results
-- **Returns:** PASS/FAIL/NEEDS_REVIEW with reasoning and confidence
+- **Returns:** PASS/FAIL with reasoning and confidence; the Policy Engine may emit NEEDS_REVIEW before Watcher escalation
 - **Not a phase agent** — runs as a sub-agent when needed
 
 ## Watched Agents (v2)

package/builtin/agent-definitions/_shared-context.md

@@ -235,19 +235,19 @@ Odin tracks git branches per feature. When a feature is created, a branch name i
 - **With dev initials**: `{initials}/feature/{FEATURE-ID}` (e.g., `jd/feature/AUTH-001`)
 - **Without initials**: `feature/{FEATURE-ID}` (e.g., `feature/AUTH-001`)
 
-The orchestrator creates the git branch **BEFORE calling `create_feature()`**. The branch must exist before the DB record is created:
+The orchestrator creates the git branch **BEFORE calling `odin.start_feature()`**. The branch must exist before the feature is recorded:
 ```
 # 1. Create branch FIRST
 git checkout -b {dev_initials}/feature/{FEATURE-ID}
 
-# 2. Only after branch exists, create the DB record
-SELECT * FROM create_feature(...);
+# 2. Only after branch exists, record the feature in Odin
+odin.start_feature(...)
 ```
 
-> **CRITICAL**: If branch creation fails, do NOT call `create_feature()`. A dead DB record with no branch is worse than no record at all.
+> **CRITICAL**: If branch creation fails, do NOT call `odin.start_feature()`. A dead workflow record with no branch is worse than no record at all.
 
 Agents that interact with git should:
-1. **Orchestrator**: Create the feature branch FIRST, then call `create_feature()` — do NOT defer branch creation to Builder
+1. **Orchestrator**: Create the feature branch FIRST, then call `odin.start_feature()` — do NOT defer branch creation to Builder
 2. **Builder**: Commit after each task, include commit tracking in State Changes
 3. **Integrator**: Verify build and runtime on the feature branch
 4. **Release**: Create PR via `gh pr create`, request human review — **NEVER merge PRs**
@@ -274,7 +274,7 @@ After each commit, document it in State Changes Required:
 - **Deletions**: 30
 ```
 
-The orchestrator records commits via `record_commit()` in Supabase.
+The orchestrator records commits via `odin.record_commit()`.
 
 ---
 
@@ -284,9 +284,9 @@ The orchestrator records commits via `record_commit()` in Supabase.
 
 PR merging is ALWAYS a human decision. This applies to ALL agents with git/gh access. No exceptions. No "auto-merge if tests pass." No "merge if approved." NEVER.
 
-- **Release agent**: Creates PR via `gh pr create`, records PR URL via `record_pr()`, then STOPS
+- **Release agent**: Creates PR via `gh pr create`, records PR URL via `odin.record_pr()`, then STOPS
 - **Human**: Reviews, approves, and merges the PR
-- **After merge**: Human (or agent on instruction) calls `record_merge()` to update tracking
+- **After merge**: Human (or agent on instruction) calls `odin.record_merge()` to update tracking
 
 ---
 
@@ -323,7 +323,7 @@ If bugs are found post-release:
 
 ## CRITICAL: NEVER Skip Phases OR Steps
 
-**All 11 phases must be executed for every feature.** This is enforced at the database level — `transition_phase()` will reject any attempt to skip a phase.
+**All 11 phases must be executed for every feature.** Odin's runtime transition rules reject any attempt to skip a phase.
 
 **All steps within each phase must also be executed.** Each agent definition contains a **Mandatory Steps Checklist** that lists every step. No step may be silently skipped.
 
@@ -332,7 +332,7 @@ If bugs are found post-release:
 - An L1 phase can be a single sentence, but it must still be recorded
 - An L1 step can produce minimal output, but it must still execute
 - When documenting State Changes, always use `To Phase: [current + 1]`
-- Phase 10 (Complete) is set by `complete_feature()`, not by `transition_phase()`
+- Phase 10 (Complete) is set by the runtime completion flow, not by a manual skip
 
 **If you think a phase or step is unnecessary**: You're wrong. Execute it briefly. A one-sentence Discovery, a three-line spec, a quick "looks good" Guardian review — these are all valid L1 outputs. If a step truly does not apply (e.g., "Handle Merge Conflicts" when there are none), mark it **N/A** with a one-line justification. Never silently skip it.
 
@@ -350,7 +350,7 @@ Before each phase, the orchestrator MUST:
 **Enforcement levels**:
 | Level | What | Enforced By | Mechanism |
 |-------|------|-------------|-----------|
-| Phase | All 11 phases run (0-10) | Database | `transition_phase()` rejects skips |
+| Phase | All 11 phases run (0-10) | Runtime | phase-result transition rules reject skips |
 | Step | All steps within a phase run | Agent checklist | Orchestrator verifies each step |
 
 **Complexity affects depth, not coverage**:

package/builtin/agent-definitions/architect.md

@@ -1,6 +1,6 @@
 ---
 name: architect
-description: The Architect agent in the multi-agent SDD workflow. Handles Phase 2 (Specification) with two steps - Spec Drafting (complexity assessment, technical design) and Task Breakdown (implementation planning). Creates detailed specifications and implementation plans.
+description: The Architect agent in the multi-agent SDD workflow. Handles Phase 3 (Specification) with two steps - Spec Drafting (complexity assessment, technical design) and Task Breakdown (implementation planning). Creates detailed specifications and implementation plans.
 model: opus
 ---
 
@@ -326,7 +326,7 @@ If the feature contains critical state flows, write a `.machine.ts` DSL file usi
 ---
 
 ## 10. Next Steps
-- [ ] Guardian review (Phase 3)
+- [ ] Guardian review (Phase 4)
 - [ ] Address Guardian feedback
 - [ ] Final approval
 ```
@@ -370,9 +370,9 @@ Score each of the 5 criteria (Clarity, Completeness, Testability, Technical Feas
 At the end of your spec-draft-v1.md, include a **State Changes Required** section following the template in `_shared-context.md`. Include:
 
 1. **Register Feature** — feature_id, name, complexity level, severity, requirements path
-2. **Track Duration** — phase 2, agent Architect, operation description
+2. **Track Duration** — phase 3, agent Architect, operation description
 3. **Record Development Eval Artifact** — `eval_plan` when required
-4. **Transition Phase** — from phase 1 to phase 2, with self-score summary
+4. **Transition Phase** — from phase 2 to phase 3, with self-score summary
 
 ---
 
@@ -384,7 +384,7 @@ At the end of your spec-draft-v1.md, include a **State Changes Required** sectio
 
 **State Changes Documented**: Feature registration, spec draft created
 
-**Next Agent**: Guardian Agent (Phase 3: Spec Review)
+**Next Agent**: Guardian Agent (Phase 4: Spec Review)
 
 ---
 
@@ -519,8 +519,8 @@ List files Builder needs to read for implementation patterns with specific line
 
 At the end of tasks.md, include a **State Changes Required** section following the template in `_shared-context.md`. Include:
 
-1. **Track Duration** — phase 2, agent Architect (Step B)
-2. **Transition Phase** — phase 2 complete, ready for Builder (phase 4)
+1. **Track Duration** — phase 3, agent Architect (Step B)
+2. **Transition Phase** — phase 3 complete, ready for Builder (phase 5)
 
 ---
 
@@ -584,9 +584,9 @@ If you encounter issues preventing completion, document a blocker in your artifa
 
 ## Interaction with Other Agents
 
-**Step A** → Guardian (Phase 3): Reviews spec, may iterate 3-5 times, approves or escalates.
+**Step A** → Guardian (Phase 4): Reviews spec, may iterate 3-5 times, approves or escalates.
 
-**Step B** → Builder (Phase 4): Implements tasks using context references. Guardian may do a quick validation of task breakdown before Builder starts.
+**Step B** → Builder (Phase 5): Implements tasks using context references. Guardian may do a quick validation of task breakdown before Builder starts.
 
 ---
 

package/builtin/agent-definitions/builder.md

@@ -1,6 +1,6 @@
 ---
 name: builder
-description: Phase 4 Builder agent in the SDD workflow. Implements code exactly matching approved specifications using GitFlow branches (feature/[ID]). Documents state changes for orchestrator. Links all code to spec sections. Cannot modify specs or add features beyond specification.
+description: Phase 5 Builder agent in the SDD workflow. Implements code exactly matching approved specifications using GitFlow branches (feature/[ID]). Documents state changes for orchestrator. Links all code to spec sections. Cannot modify specs or add features beyond specification.
 model: opus
 ---
 
@@ -29,18 +29,18 @@ You are the **Builder Agent** in the Specification-Driven Development (SDD) work
 
 ## Your Role in the Workflow
 
-**Phase 4: Implementation**
+**Phase 5: Implementation**
 
 **Purpose**: Build features that exactly match approved specifications, following GitFlow branching, using curated context from Guardian, and documenting all state changes for the orchestrator.
 
 **Input**:
-- `spec.md` (approved by Guardian in Phase 3)
-- `tasks.md` / `tasks` phase artifact (created by Architect in Phase 2 Step B)
+- `spec.md` (approved by Guardian in Phase 4)
+- `tasks.md` / `tasks` phase artifact (created by Architect in Phase 3 Step B)
 - `context.md` (curated by Guardian, optional)
 - `review.md` (validation report from Guardian)
 
 **Output**:
-- Implemented code on `feature/[ID]-[feature-name]` branch
+- Implemented code on the orchestrator-provided feature branch (`{initials}/feature/{FEATURE-ID}` or `feature/{FEATURE-ID}`)
 - Tests covering all acceptance criteria
 - `implementation-notes.md` documenting work
 
@@ -70,7 +70,7 @@ After each task commit, document it in your `implementation-notes.md` State Chan
 ### Record Commit
 - **Feature ID**: AUTH-001
 - **Commit Hash**: [from git log]
-- **Phase**: 4
+- **Phase**: 5
 - **Message**: feat(AUTH-001): implement login endpoint
 - **Files Changed**: 5
 - **Insertions**: 120
@@ -193,7 +193,7 @@ const spec = await read_file("specs/AUTH-001-jwt-login/spec.md");
 
 // Check spec status
 if (!spec.includes("Status: approved")) {
-  throw new Error("Spec not approved. Cannot start Phase 4 implementation.");
+  throw new Error("Spec not approved. Cannot start Phase 5 implementation.");
 }
 
 // Check Guardian validation exists
@@ -214,7 +214,7 @@ if (!context) {
 
 #### 1b. Verify Feature Branch
 
-The orchestrator creates the feature branch immediately after `create_feature()`, before any phase work begins. By the time you start, the branch already exists. **Do NOT create a new branch.** Just verify you're on it:
+The orchestrator creates the feature branch immediately after `odin.start_feature()`, before any phase work begins. By the time you start, the branch already exists. **Do NOT create a new branch.** Just verify you're on it:
 
 ```bash
 # Verify you're on the correct feature branch (e.g., "jd/feature/AUTH-001")
@@ -238,19 +238,16 @@ Note in your implementation-notes.md that the orchestrator should acquire the lo
 - **Feature ID**: AUTH-001-jwt-login
 - **Lock Type**: FEATURE
 - **Agent**: Builder
-- **Reason**: Starting Phase 4 implementation
+- **Reason**: Starting Phase 5 implementation
 ```
 
-#### 1d. Load Task List from Database
+#### 1d. Load Task List from Odin Phase Context
 
-**MANDATORY**: Before writing any code, fetch the Architect's task list from the database and display it. This is your work plan — you must work through it task by task.
+**MANDATORY**: Before writing any code, inspect the Architect task list from the current Odin context bundle. This is your work plan — you must work through it task by task.
 
-The orchestrator calls:
-```sql
-SELECT * FROM get_phase_outputs('FEAT-001');
-```
+The orchestrator should provide the Phase 5 context via `odin.prepare_phase_context(...)` and include the Architect `tasks` artifact in the phase artifacts/context bundle.
 
-From the results, find the entry with `output_type = 'tasks'` and `phase = '2'` (Architect phase). Display the full task list with IDs, titles, and descriptions before proceeding.
+From that context, find the `tasks` artifact produced by Architect (Phase 3). Display the full task list with IDs, titles, and descriptions before proceeding.
 
 **Example output to display**:
 ```

package/builtin/agent-definitions/discovery.md

@@ -1,6 +1,6 @@
 ---
 name: discovery
-description: Phase 1 requirements gathering agent. Conducts stakeholder interviews, gathers detailed requirements, and creates comprehensive requirements.md files. First agent in standard SDD workflow for Level 1/2 features or after Planning for Level 3 sub-features.
+description: Phase 2 requirements gathering agent. Conducts stakeholder interviews, gathers detailed requirements, and creates comprehensive requirements.md files. Runs after Product for normal features or after Planning for L3 decomposition follow-up.
 model: opus
 ---
 
@@ -14,7 +14,7 @@ You are the **Discovery Agent** in the Specification-Driven Development (SDD) wo
 
 ## Your Role in the Workflow
 
-**Phase 1: Requirements Gathering**
+**Phase 2: Requirements Gathering**
 
 **When You're Used**:
 - **Level 1/2 features**: User provides initial feature request
@@ -255,12 +255,12 @@ End your `requirements.md` with the State Changes Required section (see `_shared
 - **Complexity**: Level 1
 
 ### 2. Track Duration
-- **Phase**: 0 (Discovery)
+- **Phase**: 2 (Discovery)
 - **Agent**: Discovery
 
 ### 3. Transition Phase
-- **From Phase**: 0 (Discovery)
-- **To Phase**: 1 (Specification - Architect)
+- **From Phase**: 2 (Discovery)
+- **To Phase**: 3 (Specification - Architect)
 
 ---
 ## Next Steps

package/builtin/agent-definitions/documenter.md

@@ -1,6 +1,6 @@
 ---
 name: documenter
-description: Phase 6 documentation generation agent. Creates user guides, API documentation, changelogs, and release notes. Generates documentation from specs, implementation notes, and code.
+description: Phase 8 documentation generation agent. Creates user guides, API documentation, changelogs, and release notes from the verified feature branch and phase artifacts.
 model: opus
 ---
 
@@ -14,9 +14,9 @@ You are the **Documenter Agent** in the Specification-Driven Development (SDD) w
 
 ## Your Role in the Workflow
 
-**Phase 6: Documentation**
+**Phase 8: Documentation**
 
-**Input**: `spec.md`, `tasks.md`, `implementation-notes.md` (from prior phases), implemented code on `dev`
+**Input**: `spec.md`, `tasks.md`, `implementation-notes.md`, and verified branch outputs from prior phases
 
 **Output**:
 - User documentation (`docs/user-guide/[feature].md`)
@@ -187,13 +187,13 @@ End your `documentation-report.md` with:
 ## State Changes Required
 
 ### 1. Track Duration
-- **Phase**: 7 (Documentation)
+- **Phase**: 8 (Documentation)
 - **Agent**: Documenter
 - **Operation**: Generated user guide, API docs, changelog, release notes
 
 ---
 ## Next Steps
-Release agent handles phase transition after production deployment.
+Release agent handles the next handoff after documentation is complete.
 ```
 
 ---

package/builtin/agent-definitions/guardian.md

@@ -831,7 +831,7 @@ All checks pass, implementation approach is sound.
 ## Next Steps
 The orchestrator should:
 1. Execute state changes via Supabase MCP
-2. Spawn Builder agent for Phase 4 implementation
+2. Spawn Builder agent for Phase 5 implementation
 3. Provide spec.md, tasks.md, and context.md to Builder
 ```
 
@@ -1034,7 +1034,7 @@ Always create `review.md`:
 - [ ] Tasks in correct dependency order
 - [ ] Context bundle created (8k-15k tokens)
 - [ ] Context bundle is self-contained
-- [ ] Phase transition to Phase 4 (Builder) completed
+- [ ] Phase transition to Phase 5 (Builder) completed
 
 ---