---

name: workflow version: 1.0.0 changelog: Initial structured workflow with gates and state management description: Entry point for task execution. Routes to research, plan, implement, or debug based on task type and existing state. Orchestrates phase transitions after approval. disable-model-invocation: true allowed-tools: Read, Write, Glob, Skill, AskUserQuestion

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

| Signals | Task Type | Path | Gates | |---------|-----------|------|-------| | "not working", "error", "bug", "broken" | Bug | debug (then implement if needed) | Normal | | "add", "implement", "create", "build" + unclear scope | Feature | research,plan,implement | Normal | | Clear, small, single-file change | Quick fix | (none - direct implementation) | Minimal | | "refactor", "change", "update" + multi-file | Modification | research,plan,implement | Normal |

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

| Condition | Default | Prompt | |-----------|---------|--------| | Uncommitted changes | Suggest commit | "Uncommitted changes detected. Commit first?" | | Clean git + high context (>50%) | Suggest clear | "Task complete. /clear recommended for fresh start." | | Clean git + low context (<50%) | Suggest continue | "Task complete. Context is light — continue or /clear?" |

## 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

| Utilization | Action | |-------------|--------| | < 50% | Proceed normally | | 50-60% | Warn user, proceed with caution | | 60%+ | GATE: Run context recovery protocol |

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

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

| Phase | Typical Cost | |-------|--------------| | research | +15% | | plan | +10% | | implement | +20% | | debug | +15% |

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:

| STATE.md status | Action | Rationale | |-----------------|--------|-----------| | in_progress or blocked | /compact | Preserve learnings, continue task | | complete or idle | /clear | Fresh start, no continuity needed | | No STATE.md | /clear | Nothing to preserve |

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.