Workflow

Entry point and orchestrator. Routes to appropriate phase, then manages transitions after each approval gate.

Task

$ARGUMENTS

Instructions

Output: ## Workflow

1. Check for Existing State

Read STATE.md if it exists. Parse YAML frontmatter:

---
task: "..."
status: in_progress | blocked | complete | parked
phase: research | plan | implement | debug | idle | quick
path: research,plan,implement  # orchestration path
context_percent: N
last_updated: YYYY-MM-DD
---

If status: idle or status: complete: proceed to assessment

If status: in_progress with path set: offer continuation

## Existing State Found

**Task**: [task]
**Current phase**: [phase]
**Path**: [path]
**Progress**: [which phases complete]

Options:
1. **Continue** — resume at current phase
2. **Park and switch** — set status to parked, begin new task
3. **Discard** — clear state, begin new task

If status: in_progress without path: legacy state, offer resume or restart

If no STATE.md: proceed to assessment

2. Assess Task Type

Quick fix mode: For obvious, low-risk changes (typo fix, add log statement, rename variable), skip research/plan phases entirely. Execute directly, verify, done. No STATE.md needed.

3. Present Recommendation

## Task Assessment

**Task**: [one-line summary]
**Type**: [bug | feature | quick fix | modification]
**Scope**: [small | medium | large]

**Path**: [phase] → [phase] → [phase]

**Rationale**: [Why this path fits]

Proceed?

4. Initialize State

Skip for quick fixes — complete in one turn.

For all other task types, write STATE.md:

---
task: "[one-line summary]"
status: in_progress
phase: [first phase in path]
path: [comma-separated phases]
context_percent: 0
last_updated: [today]
---

## Original Prompt
> [Capture user's request VERBATIM - this survives compaction]

## Scope
**Doing**: [What's included]
**Not doing**: [Explicit exclusions]

## Decisions
[None yet]

## Blockers
[None]

## Key Files
[To be discovered]

## Next Steps
Starting [first phase]

Why capture original prompt: After compaction or session break, the verbatim request ensures intent isn't lost. The one-line task: is a summary; the original prompt is the source of truth.

5. Orchestration Loop

After user approves, execute this loop:

while path has remaining phases:
    1. Pre-flight: check context utilization (automatic)
    2. Invoke current phase skill (using Skill tool)
    3. Phase skill runs, ends with gate question
    4. User approves (or redirects)
    5. AUTO: Run /checkpoint (no user action needed)
    6. Update STATE.md: advance phase, update context_percent
    7. If more phases remain, continue loop
    8. If user redirects, update path and continue

Auto-checkpoint: Checkpoint runs automatically after each gate approval — no user action required. This captures phase-specific learnings before context compaction may be needed.

Invoking phase skills:

• •/research — exploration, returns findings
• •/plan — creates implementation plan
• •/implement — executes plan with checkpoints
• •/debug — diagnoses issue, may lead to implement

After each phase completes:

• •Update phase: to next in path
• •Update ## Next Steps
• •Present transition: "Research complete. Ready to plan?"

On user redirect: Update path: to new direction, continue from there.

6. Completion

When all phases complete:

• •Set status: complete, phase: idle
• •Clear path:
• •Run /checkpoint to save final state

Exit lifecycle — smart defaults based on state:

First, check git state: git status --short

## Task Complete

[Smart suggestion based on above]

**Options:**
1. **Clear** — fresh context for unrelated task (`/clear`)
2. **Compact** — reduce context, preserve learnings (`/compact`)
3. **Continue** — keep context for follow-up questions

Which would you like?

Why smart defaults: Reduces decision fatigue while preserving user control. Uncommitted work should be committed before clearing.

Constraints

• •Don't skip assessment — even obvious tasks benefit from explicit routing
• •Wait for approval at each phase boundary (gates are mandatory)
• •Keep STATE.md as source of truth

Context Hygiene (Mandatory)

Pre-flight check: Before invoking any phase skill, run:

.claude/skills/shared/scripts/read-metrics.sh used_percentage

Context estimation: Before starting a phase, estimate its cost:

./scripts/estimate-context.sh [phase]

If projected utilization exceeds 60%, run recovery protocol BEFORE starting the phase.

Hard gate at 60%: Do not invoke the next phase skill until context is below 60%. This is not a suggestion — degraded context means degraded work quality.

Context Recovery Protocol (at 60%+)

Step 1: Run /checkpoint to save current state

Step 2: Choose recovery action based on STATE.md status:

Step 3: After /compact or /clear, the session-init hook automatically injects STATE.md if the task was incomplete. This ensures immediate recovery.

Why automatic recovery: The hook detects fresh context (<25%) + active STATE.md status and injects the full state. No manual reload needed.

Update STATE.md context_percent: After each phase completion, record current utilization from metrics.

Exit Criteria

Task completed through all phases, or user explicitly exits workflow.