Spec Recorder (Orchestrator)
Thin orchestrator. It verifies preconditions and delegates the merge work to the recorder-agent sub-agent.
Required Skills (for the orchestrator)
Invoke before starting:
/speq-cli— Spec validation
The recorder-agent sub-agent invokes its own required skills.
Workflow
Phase 0: Load Project Hook (orchestrator)
Check for .speq/record-hook.md in the repo root.
- Present: read it. Announce "Loaded project hook: .speq/record-hook.md". Its content is authoritative: it can add to, change, or override any part of this workflow. If the hook conflicts with this workflow, the hook wins.
- Absent: continue normally, no mention.
Note it (not its full content) as a Project Hook: line in the recorder-agent brief below.
Phase 1: Resolve Plan Name (orchestrator)
Get the plan name from the user prompt. If none is given, ask the user to choose from the plans under specs/_plans/.
Phase 2: Verify Preconditions (orchestrator)
Check: specs/_plans/<plan-name>/verification-report.md exists? ├─ Yes → Proceed └─ No → STOP: "Run /speq-implement <plan-name> first."
Phase 3: Delegate to recorder-agent
Spawn the recorder sub-agent with the plan name:
Delegate to recorder-agent — Record <plan-name> into permanent specs ## Plan Name <plan-name> ## Context - Verification report confirmed at: specs/_plans/<plan-name>/verification-report.md - Plan file: specs/_plans/<plan-name>/plan.md - Delta specs: specs/_plans/<plan-name>/**/spec.md - Architecture delta (optional): specs/_plans/<plan-name>/architecture.md ## Your Task Merge all delta specs, and the architecture delta if present, into permanent specs per the `recorder-agent` workflow. Validate between merges. Archive the plan on success. If any library threshold is exceeded (scenarios > 10, domain features > 8), STOP before archiving and return a question for the user. Project Hook: <if active, ".speq/record-hook.md — read it and apply it"; otherwise omit this line> Return a summary of merged features and the archive path.
Phase 4: Handle Threshold Escalations (orchestrator)
If the sub-agent returns threshold signals:
- Ask the user for their organizational decision
- Respawn
recorder-agentwith the decision, OR apply a trivial edit (for example, a file rename) directly - Archive only after all decisions are resolved
If the sub-agent returns Recording failed: architecture delta: ..., do not respawn it and do not fix the delta yourself. The plan stays unarchived. Report the message to the user and stop. The fix is a plan change: correct architecture.md in the plan, or refresh its BASE after a stale-base error.
Phase 5: Confirm Completion (orchestrator)
Report to user:
✓ Verification report confirmed ✓ All deltas merged ✓ Spec library validated ✓ Plan archived: specs/_recorded/NNN-<plan-name> ✓ Architecture merged: <sections> (omit when no delta) ✓ ADRs accepted: N — <slugs> (omit when none)
Work Split (reference)
| Step | Performed by | Why |
|---|---|---|
| Precondition checks, user questions | This skill (pins Sonnet) | Lightweight orchestration |
| Delta merge, validation, archive | recorder-agent sub-agent | Fixed steps: apply markers, validate, archive |
The split preserves rotation discipline: the orchestrator can respawn the sub-agent with a fresh context and keep its own state.
Anti-Patterns
| Pattern | Why Wrong |
|---|---|
| Record without verification report | Implementation not proven |
| Archive after an architecture delta failure | The delta was not merged, so the plan must stay open |
