Epic/Stage Workflow - Orchestrator

This is the orchestrator skill. It contains shared rules that apply to ALL phases. Phase-specific guidance is in separate phase skills.

Model Tiering

• Opus: Complex reasoning (brainstormer, planner, debugger, code-reviewer, doc-writer)
• Sonnet: Medium reasoning (main agent, planner-lite, debugger-lite, doc-writer-lite, test-writer, e2e-tester)
• Haiku: Execution (task-navigator, doc-updater, tester, fixer, scribe, verifier)

CRITICAL: Main Agent Coordination Only

The main agent (Sonnet) is a COORDINATOR, not an executor.

• Main agent DELEGATES all work to subagents
• Main agent NEVER reads, writes, or modifies files directly
• Main agent NEVER runs commands directly (except simple git commands)
• Use the Task tool to spawn subagents for ALL execution work

If you're about to read a file, write code, or run a command → STOP → Delegate to a subagent instead.

When to Use

• After running /next_task to get your task assignment
• During any Design, Build, Refinement, or Finalize phase
• When session protocols apply

When NOT to Use

• Initial project setup (use epic-stage-setup instead)
• Creating new epics or stages
• Tasks outside the epic/stage system

Protocol, Not Advice

This workflow is a protocol (exact adherence required), not guidance (adaptable).

Letter AND Spirit Required:

• Letter: Follow exact steps, use specified agents, invoke specified skills
• Spirit: Understand WHY each step exists, ensure quality

"I understand the spirit" is NOT permission to skip the letter.

Workflow Authority Hierarchy

Level 1: User Authority (Highest for WHAT)

• Defines requirements, priorities, acceptance criteria
• Approves/rejects features
• Requests emergency or abbreviated workflows
• Controls WHAT gets built

Level 2: Workflow Integrity (Non-Negotiable)

These steps CANNOT be skipped by user request:

• code-reviewer invocation (can be abbreviated, not skipped)
• Spec file for non-trivial changes (can be bullet-point, not skipped)
• Formal approval workflow (can be batched, not skipped)
• Exit gates (lessons-learned, journal)

Level 3: Workflow Flexibility (User-Overrideable)

These CAN be adjusted with explicit user consent:

• Abbreviated formats (bullet-point specs, quick reviews)
• Compressed timelines (smoke tests instead of full suite)
• Reduced documentation scope

If user requests skipping Level 2 items:

1. Explain why workflow requires them (prevent regressions, maintain quality)
2. Offer Level 3 alternatives (faster, not absent)
3. If user insists after explanation, document objection in stage file and proceed with Level 3 alternative
4. NEVER skip Level 2 entirely - only abbreviate

User owns the project. Agent has duty of care for quality. Make trade-offs explicit.

Classification Authority

Level 2 is an EXHAUSTIVE list - items are Level 2 if and only if they appear in the list above:

1. code-reviewer invocation
2. Spec file for non-trivial changes
3. Formal approval workflow
4. Exit gates (lessons-learned, journal)

Classification disputes:

If user claims something is Level 3 (not Level 2):

1. Check the list: Is this item explicitly listed above?

- YES → Level 2 applies, follow Level 2 protocol - NO → Level 3, user preference wins

1. Example resolution:

- User: "Skip code-reviewer for this typo" - Agent checks list → "code-reviewer invocation" is listed → Level 2 - Agent: "Code-reviewer is Level 2 (explicit list). I can abbreviate (30-second quick pass) but not skip."

1. If user still insists after explanation:

- Document in stage file: "User overrode Level 2 requirement [item] despite agent objection" - Log as workflow deviation in lessons-learned - Proceed as directed (user has ultimate project authority)

KEY PRINCIPLE: Level 2 classification is OBJECTIVE (explicit list), not subjective (agent judgment). If it's on the list, it's Level 2. Period.

• ❌ "Spirit of exit gate is completeness, I can reorder steps" → Violates letter
• ✅ "Spirit is completeness, I follow steps in order AND explain why each matters" → Follows both

Why exact adherence matters:

• Enables session independence (any agent can resume work)
• Prevents compounding errors (shortcuts cause future mistakes)
• Ensures tracking docs stay synchronized
• Makes workflow auditable and improvable

Phase Routing

After loading this skill, determine the current phase and invoke the appropriate phase skill:

To invoke a phase skill: Use the Skill tool with the skill name (e.g., phase-design).

Each phase skill ends with a mandatory exit gate that invokes lessons-learned and journal skills.

MANDATORY Phase Exit Gate

BEFORE proceeding to next phase, you MUST:

1. Invoke the journal skill to record candid feelings about the work
2. If anything noteworthy happened, invoke the lessons-learned skill

Common Rationalizations (REJECT ALL):

Enforcement: Do NOT use any phase transition language ("moving to Build", "starting Refinement", "proceeding to next phase") until journal skill has been invoked for the JUST-COMPLETED phase.

Red Flag - STOP Immediately If:

• You're about to say "moving to [phase]" without having invoked journal
• User requests transition and you haven't completed exit gate
• You think "I already committed" justifies skipping reflection

This is a Level 2 (Non-Negotiable) requirement. No exceptions.

Communication Policy (CRITICAL)

After EVERY subagent call or significant action, explain:

The Three Things to Explain

1. What was found (for exploration) - Key discoveries, patterns identified, relevant files
2. What was done (for implementation) - Files created/modified, specific changes made
3. The outcome - Success/failure, verification results, any issues

Format Requirements

What NOT to Do

NEVER respond with just: "Done", "Task completed", "Fixed", "Updated"

Always provide context even for simple operations.

CRITICAL: Speed pressure does NOT override communication standards

User says "Go fast" or "I'm waiting"? → You still provide full three-part explanations → Transparency and context are non-negotiable → Clear communication prevents misunderstandings that cost more time

CRITICAL: "Success" or "All passed" does NOT mean skip details

When everything works perfectly, agents often think "there's nothing to explain."

This is WRONG. Even for clean successes, explain:

• What was verified
• What passed
• What this means for the next step

After Fixer Returns

Mandatory flow:

1. Report what fixer changed:

- File paths modified - Lines changed - Summary of edits applied

1. Immediately verify the fix:

- Call verifier (for build/type-check/lint) - Call tester (for test failures) - NEVER assume fix worked without verification

1. Handle verification result:

- Success → Continue with next task - Failure → Escalate to debugger (NOT back to fixer)

1. Document the cycle:

- Note: "Fixer applied changes, verifier confirmed fix" - OR: "Fixer applied changes, still failing, escalating to debugger"

Agent Role Boundaries (CRITICAL)

Specialized Agents Are NOT General-Purpose

Each specialized agent does EXACTLY ONE THING:

The Pipeline Model

Errors are resolved through a PIPELINE, not by choosing a single agent:

ERROR → DIAGNOSTIC AGENT → FIXER AGENT → RESOLUTION
        [analyzes]         [implements]
        [produces plan]    [executes plan]

NEVER:

• Skip diagnostic step for medium/high errors
• Tell diagnostic agent to implement
• Expect fixer to diagnose

ALWAYS:

• Route through appropriate diagnostic agent first
• Get diagnostic instructions
• Pass instructions to fixer for implementation

Agent Roster Quick Reference

Fixer Agent Constraints (CRITICAL)

Fixer's ONLY job: Apply explicit line-by-line instructions

What Fixer MUST NOT Do

• Read files to "understand context" (debugger provides context)
• Search for patterns using Grep/Glob (that's exploration)
• Re-read files after editing to "verify" (trust Edit tool worked)
• Run type-check, test, or build commands (verifier/tester's job)
• Make multiple fix attempts (return after first attempt)
• Diagnose why something failed (debugger's job)
• Make design decisions about HOW to fix (coordinator's job)
• Iterate based on verification results (coordinator escalates)

What Fixer MUST Do

• Read ONLY files being edited (for Edit tool preparation)
• Apply EXACTLY the changes specified
• Return immediately after applying changes
• Report what was changed (files, line numbers)

Retry Policy

Fixer gets ONE attempt per instruction set

Error occurs → debugger diagnoses → fixer applies fix → return
                                                          │
                                                          ▼
                                              verifier checks result
                                                          │
                                    ┌─────────────────────┼─────────────────────┐
                                    │                                           │
                              Fixed                                    Still failing
                                    │                                           │
                                    ▼                                           ▼
                              Continue                        Escalate back to debugger
                                                              (DO NOT call fixer again)

Instructions Must Be Explicit

Pattern: Edit <file>: Line <N>: Change from <old> to <new>

Include:

1. File path: Full path from project root
2. Line number: Exact line to edit
3. Old text: What's currently there (for Edit tool matching)
4. New text: What it should become

Red Flags - STOP Before Calling Fixer:

• Instructions use words like "fix", "resolve", "handle" → Too vague
• No specific line numbers provided → Too vague
• No old text → new text provided → Too vague
• Instructions mention "investigate", "check", or "verify" → Wrong role

Error Handling Flow

Error Severity Routing

CRITICAL:

• Medium/High errors ALWAYS involve TWO agents in sequence
• First agent provides instructions
• Second agent implements instructions
• NEVER tell first agent to implement
• NEVER expect second agent to diagnose

Calling Debugger Agents

CORRECT: "Diagnose the root cause of [error]. Provide specific fix instructions that fixer agent can implement."

INCORRECT: "Diagnose and fix [error]" "Fix this error"

Parallel Execution Rules

ALWAYS run independent operations in parallel:

• verifier + tester (during Build verification)
• Multiple file reads/explorations
• Independent subagent tasks

NEVER run as background tasks - await all parallel calls before proceeding.

How to parallelize: Send multiple Task tool calls in a single message.

The git add -A Problem (CRITICAL)

Never use git add -A, git add ., or git commit -a

When doc-updater updates tracking files, it does NOT commit them. If tracking files remain uncommitted and a later stage uses git add -A, it picks up:

• Changelog entries from previous stages
• Stage files from previous stages
• Epic files that should have been committed earlier

ALWAYS use specific file paths:

# CORRECT - Tracking files
git add epics/EPIC-XXX/STAGE-XXX-YYY.md epics/EPIC-XXX/EPIC-XXX.md

# CORRECT - Changelog
git add changelog/2026-01-13.changelog.md

# WRONG - Picks up everything
git add -A
git add .

Epic File Updates Are MANDATORY

The epic file's stage table MUST be updated when a stage changes status. This is NOT optional.

Exit Gate Error Handling

If an exit gate step fails (e.g., journal skill fails due to disk error):

1. Report the failure to the user with specific error details
2. Ask user: Retry? Skip? Wait?
3. If skipping, document in stage file: "Journal skipped due to [error]"
4. Only proceed to next phase with user consent

Required steps (blocking): Update stage file, Update epic file Always-attempt steps (skip only on system error with user consent): lessons-learned, journal

If lessons-learned or journal fails due to system error (not by choice):

1. Report error to user with specific details
2. Ask: Retry? Skip? Wait for resolution?
3. If skipping, document in stage file: "[Skill] skipped due to [error] on [date]"

Journal and lessons-learned are NEVER skipped by choice - only on system failure.

Required Step Failures

If stage file or epic file update fails:

1. Report failure with full error details (disk space, permissions, file locks)
2. Retry ONCE (transient errors may resolve)
3. If retry fails, present options:

- Wait: User resolves issue (free disk space, fix permissions), then retry - Manual update: User edits file manually, confirms when done - Abort: Document incomplete exit, roll back phase state

1. NEVER proceed without required steps complete

Why: Stage/epic files are source of truth. Skipping breaks session independence and /next_task navigation.

Partial Exit Gate Completion

If stage file updates but epic file update fails:

1. Retry epic file update (most likely to succeed after stage file worked)
2. If retry fails: User manually edits epic file stage table
3. Rollback option: Revert stage file to previous phase status, re-run exit gate

Prevention: doc-updater should update stage + epic in sequence (stage first, then epic). This makes forward recovery (retry epic) easier than rollback.

Concurrent Session Detection

Before completing ANY phase exit gate:

1. Check git status for unexpected changes:

``bash git status epics/EPIC-XXX/STAGE-XXX-YYY.md epics/EPIC-XXX/EPIC-XXX.md ``

1. If files show "modified" but you haven't updated them yet:

- Another session may have completed the phase - Run: git diff epics/EPIC-XXX/STAGE-XXX-YYY.md - Check if phase is already marked complete

1. Resolution:

- Phase already complete: Inform user, do NOT duplicate work, exit gracefully - Different phase complete: Pull changes, proceed with current phase - Conflict detected: User must resolve manually

Prevention: Sessions should coordinate via user. Tracking files should be committed immediately after phase completion.

Session Protocols

Starting a Session

1. Run /next_task to get assignment
2. This skill loads automatically
3. Invoke the appropriate phase skill based on current phase
4. Begin phase-specific workflow

Refinement Phase State Interpretation

• "Refinement: In Progress" → Invoke phase-refinement (REQUIRED even when resuming from previous session)
• "Refinement: Complete (awaiting feedback)" → Wait for user feedback in main conversation, don't invoke any phase skill yet
• "Refinement: Complete" (no note) + user approved → Invoke phase-finalize

CRITICAL: Always invoke the phase skill when resuming a session. Do NOT rely on "memory" from previous session context. Phase skills may have been updated, and session independence requires fresh skill invocation every time.

Handling State Conflicts

If task-navigator returns a different phase than stage file shows:

1. Report the conflict: "Task-navigator says [X], but stage file shows [Y]"
2. Stage file is authoritative - it contains the detailed phase completion status
3. Ask user: "Which should I follow? (A) Stage file state, (B) Investigate discrepancy"
4. If stage file is corrupted: Report specific inconsistency, ask user to manually fix

Corrupted or Malformed Stage Files

If stage file has conflicting or invalid state:

1. Report specific inconsistency:

- "Header says Status: Build but Build section shows [x] Complete" - "Refinement shows Desktop: Approved but no approval note found"

1. Do NOT proceed with ambiguous state

1. Ask user for resolution:

- "Please check the stage file and confirm the correct current phase" - "Once fixed, I'll re-read and continue"

Ending a Session

1. Complete current phase's exit gate (includes lessons-learned and journal)
2. State progress: "Completed [X], next session will [Y]"
3. Note any blockers or decisions needed

Code Review Policy

ALL code review suggestions must be implemented, regardless of severity:

• Critical, Important, Minor - all mandatory
• "Nice to have" = "Must have"
• Only skip if implementation would break functionality (document why)

User as Technical Reviewer

User's technical expertise does NOT exempt stages from code-reviewer agent:

• User reviewing code = additional quality layer (good)
• Skipping code-reviewer because user reviewed = workflow violation (bad)
• BOTH reviews happen: user's judgment + agent's automated checks
• Findings may overlap (confirms quality)
• Findings may differ (catches different issues)

User authority controls WHAT to build, not WHETHER to run quality gates.

Emergency Situations Do NOT Bypass Workflow

"Production is down" / "Critical hotfix" / "User has a deadline":

• Time pressure does NOT skip code-reviewer, verifier, or tester
• Emergency is NOT an exception - it's a reason to be MORE careful
• Fast is achieved through efficient subagent coordination, not skipping steps

If genuinely time-critical:

1. Run abbreviated workflow (code-reviewer can be quick for small changes)
2. Document in stage file: "Emergency workflow - abbreviated review due to [reason]"
3. Schedule follow-up full review if abbreviated
4. User must explicitly consent to abbreviated workflow (consent does NOT allow skipping workflow entirely - only abbreviating)

Abbreviated Workflow Minimums (NEVER skip these - PER STAGE):

• code-reviewer subagent MUST run per stage (even if 30-second quick pass)
• verifier MUST confirm build/type-check passes per stage
• For logic changes: At least smoke test per stage (full suite can be deferred)
• Zero review per stage is NEVER okay, regardless of fix size

Batched reviews across stages are NOT permitted:

• ❌ "One review for 5 hotfixes" → Each stage needs its own review
• ❌ "Review them all together" → Each stage reviewed independently
• ✅ "Run 5 abbreviated reviews in parallel" → Each stage gets its own fast review

Why per-stage matters: Each stage may introduce different issues. Batching hides which stage caused which problem and makes rollback harder.

Time-critical with multiple stages?

• Run abbreviated code-reviewer per stage (30 seconds each)
• Run reviews in parallel to save time
• Total: 5 stages × 30s = 2.5 minutes (parallel) vs 2.5 minutes (sequential but batched-unsafe)

"Abbreviated" means faster execution, not fewer steps:

• Spec: Bullet points acceptable (still required unless truly trivial per L5)
• code-reviewer: Focus on critical issues only (still invoked)
• Testing: Smoke tests instead of comprehensive (still run something)

Explicit Consent Requirements:

Before requesting emergency consent, agent MUST explain:

"Abbreviated workflow means: quick code-reviewer pass, verifier only, smoke tests. Full workflow is safer. Use abbreviated workflow for this fix?"

Vague statements do NOT count as consent:

• ❌ "Do what you need to do"
• ❌ "Just fix it ASAP"
• ❌ "I trust you"
• ✅ "Yes, use abbreviated workflow for this hotfix"

Rationalizations that don't work:

• "Production is broken" → Broken prod + buggy fix = worse
• "User needs it in 5 minutes" → Skipped review takes longer to fix later
• "Code-reviewer will take too long" → Code-reviewer is usually 2-3 minutes
• "This is different, it's urgent" → Urgency increases error likelihood
• "User said 'do whatever'" → Vague consent ≠ explicit consent

Common Rationalizations (Don't Fall For These)

Discovering New Work Mid-Phase (Sequential Dependency Ordering)

During any phase, you may discover that new stages or epics are needed. When this happens, apply the Sequential Dependency Ordering rule:

Core Rule: Dependencies flow upward numerically. If work X depends on work Y, then Y must have a lower number than X.

Decision Flow for New Work Discovery

digraph new_work {
    "Discover new work needed" [shape=box];
    "Is it a DEPENDENCY or DEPENDENT?" [shape=diamond];
    "DEPENDENCY: Current stage NEEDS this work" [shape=box];
    "DEPENDENT: This work NEEDS current stage" [shape=box];
    "Create with LOWER number or earlier epic" [shape=box, style=filled, fillcolor=lightgreen];
    "Create with HIGHER number or later epic" [shape=box, style=filled, fillcolor=lightgreen];
    "Consider deferring current stage" [shape=box, style=filled, fillcolor=lightyellow];

    "Discover new work needed" -> "Is it a DEPENDENCY or DEPENDENT?";
    "Is it a DEPENDENCY or DEPENDENT?" -> "DEPENDENCY: Current stage NEEDS this work" [label="dependency"];
    "Is it a DEPENDENCY or DEPENDENT?" -> "DEPENDENT: This work NEEDS current stage" [label="dependent"];
    "DEPENDENCY: Current stage NEEDS this work" -> "Create with LOWER number or earlier epic";
    "Create with LOWER number or earlier epic" -> "Consider deferring current stage";
    "DEPENDENT: This work NEEDS current stage" -> "Create with HIGHER number or later epic";
}

Mid-Phase Discovery Rules

1. If the new work is a DEPENDENCY (current stage needs it to function):

- Create it with a LOWER stage number in the same epic, OR - Assign it to an EARLIER epic if it's cross-cutting - Consider deferring the current stage until the dependency is complete - Never create a dependency with a higher number than current work

1. If the new work is a DEPENDENT (it needs current stage to exist):

- Create it with a HIGHER stage number in the same epic, OR - Assign it to a LATER epic - Continue with current stage - no blocking issue

1. Cross-epic discoveries:

- If current epic needs work from a LATER epic: STOP - this violates sequential ordering - Move the dependent work to that later epic, OR move the dependency to the current/earlier epic - Never create a stage that blocks the current epic's sequential flow

Red Flags - STOP Immediately If:

• You're about to create a stage that depends on later-numbered work
• You're inserting STAGE-XXX-XXXA that requires work from a later epic
• User pressure to "keep features together" would create forward dependencies
• You discover the current stage can't complete without future work

What To Do When Blocked

If the current stage cannot proceed without dependency work:

1. Document the dependency in the stage file under Session Notes
2. Create the dependency stage with appropriate (lower) numbering
3. Update epic table to show the new stage
4. Recommend deferral to user: "STAGE-005-003 requires STAGE-005-002A. Recommend completing 002A first."
5. User decides: Continue (with incomplete work) or switch to dependency

Never silently proceed when a dependency blocks current work.

When User Insists on Violating Dependency Order

If user requests continuing despite forward dependency:

1. Explain the consequence: "If we proceed, STAGE-XXX will be incomplete/broken until [dependency] is done"
2. Document override: Add to stage file: "User requested proceeding despite dependency on [future work] - documented [date]"
3. Proceed as directed (user has project authority)
4. Log in lessons-learned: "Sequential dependency violation - user override"

This is NOT permission to skip the explanation. Always explain first, then document, then proceed.

Critical Red Flags

Signs you're skipping the workflow:

• Creating files before /next_task
• Skipping brainstormer because "it's obvious" (when it's not)
• Building without user selecting approach
• Using Opus agents when Haiku would suffice
• Running operations sequentially that could be parallel
• Skipping code review suggestions
• Editing files directly instead of delegating to scribe/fixer/doc-updater
• Reading code files directly instead of using Explore or having subagent read
• Running build/test commands directly instead of delegating to verifier/tester
• Updating stage docs yourself instead of using doc-updater subagent
• Using git add -A or git add . instead of specific file paths
• Forgetting to update epic file when stage completes
• Not invoking phase skill after loading this orchestrator
• Skipping exit gate (lessons-learned and journal) at phase end