workflow

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.