spec-executor

Execution companion for spec-workflow: state navigation, task tracking via tasks.md, incremental delivery, and session recovery. Use after spec-workflow produces the plan.

Execution workflow centered on state navigation and state assurance. At any moment, know where you are, what comes next, and how to recover if interrupted.

---

⚠️ Dependency Notice

This skill CANNOT be used standalone. It depends on spec-workflow to produce the plan and tasks.md tracker before execution begins.

Skill	Phase	Responsibility
spec-workflow	Planning	Requirements → Design → Task breakdown
spec-executor	Execution	State navigation → Task execution → State recovery

Handoff example:

text

spec-workflow output:
  docs/login-feature/tasks.md
  docs/login-feature/requirements.md
  docs/login-feature/design.md

spec-executor input:
  Read docs/login-feature/tasks.md
  Execute tasks in order
  Update tasks.md after each task

Do NOT use this skill for work that has not been planned by spec-workflow.

Validation: Before executing, confirm tasks.md exists and contains valid task entries (Scope + Verification fields). If the file is missing or malformed, stop and ask the user.

---

Quick Start

First time using this skill with a confirmed tasks.md:

text

1. Read tasks.md → find first [ ] task
2. Mark it [~] → execute per Scope description
3. When done: mark [✓], fill Verification, stage changes
4. Show diff → wait for user review and explicit commit approval
5. User says "next" → repeat from step 1

Session compressed? Jump to Session Recovery.

---

State Navigation

Where Am I?

text

Received user instruction
│
├─ Is the scope clear and small? ──→ YES → Execute directly (Simple Task)
│                                    NO
├─ Does it need design/architecture? → YES → Plan first → Write tasks.md → Execute
│                                    NO (unclear)
└─ Investigate → Reclassify

Current State	What To Do Next	Key Output
Just received instruction	Classify task (simple / complex / exploratory)	Decision: plan or execute directly
Planning in progress	Write design doc + tasks.md → wait for user confirmation	Confirmed tasks.md
Ready to implement	Read tasks.md, mark first pending task as [~]	Task in progress
Just finished a task	Update tasks.md to [✓] → verify → commit → next task	Updated tracker
Hit an error	Stop → diagnose → fix → re-verify → resume	Documented fix
Session interrupted	Read tasks.md → verify last done task → resume first pending	Recovered context
User inserts unrelated query	Handle query → return to previous state without losing position	Continuity preserved

State Transition Rules

text

[Classified] --(simple)--> [Executing] --(task done)--> [Update tracker] --(more tasks)--> [Executing]
      │                              │                                    └─(all done)--> [Complete]
      └─(complex)--> [Planning] --(confirmed)--> [Executing]
                             └─(rejected)--> [Revise plan]

[Executing] --(error)--> [Diagnosing] --(fixed)--> [Update tracker] --> [Executing]
                                    └─(stuck)--> [Ask user]

[Any state] --(unrelated user query)--> [Handle query] --> [Return to prior state]

Critical rule: You cannot transition from [Executing] to the next task without updating the tracker. Updating tasks.md is the definition of task completion.

---

Task Classification

Before writing code, classify the task:

Type	Criteria	Planning Required
Complex	New feature, architecture change, multi-file refactor, API design	Yes — use spec-workflow to produce design doc + tasks.md
Simple	Single-file change, config tweak, clear bug fix with known scope	No — brief explanation, then implement
Exploratory	Unclear scope, needs investigation to understand the problem	Investigate first, then reclassify

Boundary rule: If a "simple" task grows to need design decisions, interface changes, or cross-file coordination, stop immediately and upgrade to "complex" with planning.

Task Type Reference

User Intent	Type	Action
New feature, architecture change, large refactor	Complex	Trigger spec-workflow for full planning
Bug fix with ticket/reference, interface alignment	Fix / Complex	Trigger spec-workflow, Phase 1-2 may be simplified
Single-file change, config tweak, clear small fix	Simple	Brief explanation, then implement directly
Explain code, check logs, updatecode, info query	Routine	Execute directly, no Spec

Session split rule: If tasks.md has > 8 pending tasks or estimated work > 2 hours, suggest /clean and continue in a new session.

Must Ask the User

Stop and ask before proceeding when:

Situation	Question to Ask
Unclear requirement background	"What problem should this code solve?"
Design conflict (A vs B)	"Both approaches have tradeoffs — what's your priority?"
Deleting code	"This code appears used in X — are you sure you want to delete it?"
Deleting code — verification	Run grep -r "ClassName" --include="*.java" --include="*.xml" to confirm no downstream references before deleting
Scope expands beyond original	"This seems broader than the original request — should we expand the design?"
Better approach found	"I see a better refactoring path — can you explain the original design intent?"
Uncommitted user changes exist	"I see you have uncommitted changes — should I work from the latest code?"

---

State Assurance

The Tracker (tasks.md)

tasks.md is the primary state reference. If memory, conversation, and tracker disagree, pause and reconcile with the user — never silently override user intent.

Location: docs/{feature-name}/tasks.md (or project-defined location).

Format:

markdown

- [ ] Task name (≤10 words)
  - Scope: files and specific methods/fields changed
  - Affected: files that need sync changes due to this task
  - Verification: how to verify (compile, test, grep, etc.)
  - Commit: the actual commit message used
  - User corrections: 0 | Compression recoveries: 0
  - Notes: dependencies, blockers, scope changes

Critical field — Scope: Must be precise down to method/field level. After session compression, recovery depends entirely on this field to reconstruct what was done and what remains.

Example:

markdown

# Implementation Plan

- [✓] 1. Add user authentication endpoint
  - Scope: `AuthController.java` add `login()` method; `AuthService.java` add `authenticate()`
  - Affected: `UserRepository.java` (add `findByUsername`)
  - Verification: `./gradlew :api:compileJava` passes
  - Commit: `feat(auth): add login endpoint`
  - User corrections: 0 | Compression recoveries: 0
  - Notes: depends on task 0 (DB schema)

- [~] 2. Add JWT token generation
  - Scope: `JwtUtil.java` add `generateToken()`; `AuthService.java` inject JwtUtil
  - Affected: `application.yml` (add jwt.secret)
  - Verification: —
  - Commit: —
  - User corrections: 0 | Compression recoveries: 0
  - Notes: —

- [ ] 3. Add auth middleware
  - Scope: ...

Status values:

• [ ] — Not started
• [~] — In progress (set this before editing code)
• [✓] — Done (set this before committing or starting next task)
• [⏭] — Skipped

Correction tracking:

• User corrections ≥ 2: Escalate — record the pattern in Notes and adjust approach
• Compression recoveries ≥ 6: Suggest user /clean and start fresh

Real-Time Update Discipline

Event	Action	Why
Start a task	Change [ ] → [~]	Prevents duplicate work
Finish a task	Change [~] → [✓], fill Verification + Commit	Defines completion
User changes scope	Add note, increment User corrections	Prevents drift
Session compresses	Mark [~] → [ ] if uncertain	Prevents false progress

This takes precedence over compilation, testing, and starting the next task. A task whose tracker entry is not updated is considered NOT done.

Timeliness Guarantee

tasks.md must be updated in real time — never retroactively:

• After completing a task → update status, verification, and commit message immediately
• After starting a task → change [ ] to [~] before editing code
• After session compression → mark [~] → [ ] if uncertain about state
• After user adds/changes scope → record in Notes immediately
• Never reconstruct progress after compression without re-verifying code state first

Compression Recovery

tasks.md is the operational basis for recovery:

Step	How to use tasks.md
Read and confirm progress	Scan statuses in order; identify boundary between [✓] and [ ]
Verify code state	Only verify the last [✓] row (state boundary). Re-run its verification method. If it fails, state is stale — pause and reconcile
Determine next step	Find first [ ] or [~] row; execute from its Scope description

Session Recovery (After Interruption)

When context is compressed and the session continues:

1. Report count — state "This session has recovered from compression N times"
2. Read tasks.md — scan statuses, identify the boundary between [✓] and [ ]
3. Validate tracker — verify tasks.md structure is intact (expected fields, no corruption). If malformed, ask user before proceeding.
4. Verify boundary — re-run the verification for the last [✓] task. If it fails, the state is stale; pause and reconcile.
5. Resume — mark the first [ ] task as [~] and continue from its Scope description.
6. Count recoveries — increment Compression recoveries. If ≥ 6, stop execution, update tasks.md to [~], and wait for user /clean

Context Switching

Scenario	Rule
User asks unrelated question	Handle it, do NOT modify tracker, return to prior task afterward
User starts a new feature	Pause current task (mark [~]), create new tracker for new work
User changes direction mid-task	Treat as error response: stop, document in Notes, wait for confirmation
User corrects design assumption	Not a context switch — follow Error Response Protocol. Update tasks.md Notes and design.md if assumptions changed

Key principle: One tasks.md per feature. Different features must have different tracker files.

---

Execution Rules

Incremental Delivery

• Implement one small task at a time
• Max ~300 lines changed per task
• Stop for review after each task unless user explicitly authorizes continuous mode
• Update tasks.md status immediately after each task — before committing or starting the next

Task Size Exemptions

Scenario	Relaxed Limit	Required Condition
User authorizes continuous mode	≤ 500 lines	User explicitly says "continuous implement" or "finish the rest"
Pure deletion	No limit	Only removing code, no new logic, verified no downstream references
Batch rename/migration	≤ 500 lines	Mechanical replacement (e.g., package rename), zero logic change
Config/constant extraction	≤ 400 lines	Extracting scattered magic values to unified constants, no behavior change

If exceeding limit: Must split into smaller tasks or explain split plan to user and get approval.

Continuous Mode Authorization

Only proceed without stopping for review when user explicitly says:

• "You can continuous implement"
• "Finish the rest without asking"
• "Batch execute the remaining tasks"

NOT authorization: "OK", "Continue", "Go ahead", "Sure" — these confirm the current task only. Must ask: "Do you mean I can continuously implement remaining tasks, or just confirming this one?"

When in continuous mode:

• Each task must still be independently verified (compile/type-check)
• Each task must still be independently committed
• tasks.md must be updated before starting the next task
• User can interrupt at any time — stop immediately when they do

Risk Prediction (Before Starting Each Task)

Spend 30 seconds on pre-flight risk analysis:

1. Match task type — What category is this? (API alignment / dependency injection / method refactor / DTO addition / deletion)
2. Extract lessons — What has gone wrong with this type of task before?
3. Pre-verify — Run the recommended verification before writing code:
   • API alignment: Extract signatures with language-specific tools, diff against interface
   • Deletion: grep -r "targetName" to confirm no downstream references
   • Method refactor: grep -r "oldMethodName" to find all call sites
   • Dependency change: Verify all injection points and mock references
   • DTO addition: Check serialization paths and downstream consumers
   • Mock update: Verify test files reference the correct type (interface vs concrete)
   • Package rename: grep -r "old.package.name" to find all imports

Review Rules

Default: Stop and wait for user review after every task.

Review exemptions (no need to stop, but still run quality gates):

Scenario	Condition
User authorized continuous mode	Explicit continuous implement statement
Pure formatting	Only whitespace, line breaks, import sorting — zero logic change
Pure test data adjustment	Only test inputs or expected values — no production code touched
Emergency hotfix	User explicitly says "urgent fix" and change is ≤ 10 lines

Code Quality Gates

Before marking any task [✓]:

• Compiles — no build/type errors. Prefer quiet single-module compilation.
  • Build tool available: run ./gradlew :module:compileJava --quiet or equivalent
  • Build tool unavailable: use javap -public to extract signatures, or grep/diff to verify definitions align
• No dead code — unused imports, helpers, or fields removed
• No magic values — hardcoded literals (appearing 2+ times) extracted to named constants
• Size limits — methods ≤ 30 lines, nesting ≤ 2 levels, files ≤ 500 lines
• Naming — booleans use is/has/should prefixes, names are self-explanatory
• Task status updated — tasks.md reflects current state with verification and commit message

Pre-Commit Checklist

Before every commit:

• Change scope matches the task (or fits within an exemption)
• All quality gates passed
• No secrets or credentials in diff
• Diff reviewed — user has seen the changes and approved
• Commit message provided and follows project convention
• tasks.md updated with status, commit message, and verification
• Self-check: Did I follow the risk prediction? Did I avoid patterns known to fail?

Do not commit if self-check fails.

---

Error Response Protocol

When compilation fails, tests fail, tools error, or user points out a mistake:

1. Stop — no further edits until resolved
2. Locate — identify affected files and methods from error output
3. Verify root cause — use tools (grep, diff, compiler) to confirm. Never rely on reading alone.
4. Fix — apply minimal corrective change
5. Document — distinguish the nature of the fix:
   • Code error: Record cause and fix in tasks.md Notes
   • User corrected design assumption: Update tasks.md Notes and sync changes to design.md
6. Re-verify — run full quality gates and pre-commit checklist
7. Resume — only after explicit user confirmation

Tool Verification Rules

• Agent is for exploration (reading code, gathering context) — never for precision verification
• Bash is for precision (grep, diff, compiler output, line counts) — always cross-check agent conclusions
• Never judge signature alignment, overload resolution, or parameter types by reading alone
• Never trust "looks correct" from an agent without independent verification

---

Core Principles

• State over speed — document progress before moving on
• Verify with tools — grep, diff, compiler; never eyeball
• Stop and ask — when uncertain, pause for clarification
• Tracker is truth — if memory and tracker disagree, the tracker wins
• Agent is not evidence — agent conclusions require Bash cross-check
• Plan before complex work — multi-file or architectural changes need design first