spec-stateflow

Structured software engineering workflow with state-driven execution: requirement analysis → technical design → task planning → execution with state navigation and session recovery. Triggers: new feature, complex architecture, multi-module integration, database/UI design, or any task requiring structured planning and execution. Trigger words: new feature, architecture design, requirement implementation, spec workflow, state recovery, task tracking, 新功能, 复杂架构, 多模块, 需求实现, spec工作流, 状态恢复, 任务追踪

Important: You must follow these rules. Each phase must be confirmed by the user before proceeding to the next phase.

When to Use This Skill

Use this skill for structured development workflow when you need to:

• Develop new features from scratch
• Design complex architecture
• Integrate multiple modules
• Ensure high-quality requirement analysis and acceptance criteria

Do NOT use for:

• Simple requirements
• Simple bug fixes (single file / single method / obvious root cause)
• Documentation updates
• Configuration changes

Fix vs Simple bug fix boundary: A "Fix" task (use Spec) involves cross-module impact, systematic tech debt, or requires design before coding. A "Simple bug fix" (no Spec) is a localized, obvious fix in ≤1 file with no architectural implications.

How to Use This Skill

1. Follow the four phases in order — each phase requires user confirmation before proceeding:
   • Phase 1: Write requirements using EARS syntax → requirements.md
   • Phase 2: Design technical solution (architecture, API, DB, etc.) → design.md
   • Phase 3: Break down tasks with field-level specifics → tasks.md
   • Phase 4: Execute tasks with state tracking, compression recovery, and context switching
2. [HIGHEST PRIORITY]Real-time tasks.md updates — After completing each small task, you MUST immediately update {SPEC_PATH}/tasks.md, before compilation, testing, or starting the next task. Not updated = not done. See Phase 4 State Assurance for details

Testing: This skill includes test-prompts.json with 10 test scenarios covering all phases and edge cases. Use them to validate skill behavior.

Path Convention

All Spec files use the following placeholders. Actual paths are defined in the user's project configuration:

Placeholder	Meaning
{SPEC_DIR}	Spec file root directory
{SPEC_NAME}	Current spec name
{SPEC_PATH}	Full path = {SPEC_DIR}/{SPEC_NAME}

Spec file list:

File	Description
{SPEC_PATH}/requirements.md	Requirements document (Phase 1 output)
{SPEC_PATH}/design.md	Technical design document (Phase 2 output)
{SPEC_PATH}/tasks.md	Task breakdown & progress tracker (Phase 3 output, single source of truth)

Entry Points

Your situation	Start here
New feature / complex task	Phase 1 (full workflow: Phase 1 → 2 → 3 → 4)
Ready to execute (user confirmed plan)	Phase 4 → Quick Start
User authorized continuous batch / driver-monitor automation	Phase 4 → Continuous Operation Mode
Session compressed / interrupted	Phase 4 → Compression Recovery
User says "updatecode" / "continue" / "resume"	Phase 4 → Quick Start (read tasks.md → locate breakpoint → continue)

For all runtime states (error, context switch, task completion, etc.), see Phase 4 → State Navigation.

Workflow Rules

1. When you determine that the user's input implies a new requirement (not explicitly stated), you may work independently following standard software engineering practices. Confirm with the user when necessary.

2. When the user explicitly states a new requirement, you must follow the full workflow: understand the problem and requirements clearly, and confirm with the user before proceeding to the next phase.

---

Phase 1: Requirements Document and Acceptance Criteria Design

First complete the requirements design using EARS (Easy Approach to Requirements Syntax) method. You must confirm requirement details with the user. After final confirmation, the requirements are finalized, then proceed to the next phase.

Save to {SPEC_PATH}/requirements.md. After confirming with the user, proceed to the next phase.

If user rejects or requests changes: Update requirements.md and re-confirm. Do NOT proceed to Phase 2 until user explicitly approves.

Reference format:

markdown

# Requirements Document

## Introduction

Requirement description

## Requirements

### Requirement 1 - Requirement Name

**User Story:** User story content

#### Acceptance Criteria

1. Use EARS syntax: While <optional precondition>, when <optional trigger>, the <system name> shall <system response>. For example: When "Mute" is selected, the laptop shall suppress all audio output.
2. ...
...

---

Phase 2: Technical Solution Design

After completing the requirements design, based on the current technical architecture and the confirmed requirements above, design the technical solution. It should be concise but accurately describe the technical architecture (e.g., architecture, tech stack, technology selection, database/interface design, test strategy, security). Use mermaid diagrams when necessary.

Must include chapters: Background, Design Goals, Business Model, System Design (precise to package path, class name, method signature), Refactoring Design (if applicable), Deployment Plan (for large tasks), Risk Assessment (for large tasks).

Save to {SPEC_PATH}/design.md. You must confirm with the user clearly, then proceed to the next phase.

If user rejects or requests changes: Update design.md and re-confirm. Do NOT proceed to Phase 3 until user explicitly approves.

Reference format:

markdown

# Technical Solution Design

## Background
Why this design is needed — business context and problem statement

## Design Goals
- Goal 1: ...
- Goal 2: ...

## Business Model
Core domain models, entity relationships, key data flows

## System Design
### Architecture Overview
(mermaid diagram or component description)

### Module: {module-name}
- **Package:** `com.example.module`
- **New classes:**
  - `ClassName` — responsibility description
  - `InterfaceName` — method signatures: `ReturnType methodName(ParamType param)`
- **Modified classes:**
  - `ExistingClass` — add method `newMethod()`, change field `field` scope

### API Design
| Endpoint | Method | Request | Response |
|----------|--------|---------|----------|
| `/api/xxx` | POST | `{field: type}` | `{field: type}` |

### Database Design
Table name, columns, indexes, migration steps

### Test Strategy
Unit test scope, integration test plan, verification methods

## Refactoring Design (if applicable)
What to refactor, why, and how to do it incrementally

## Deployment Plan (for large tasks)
Environments, rollout steps, rollback plan

## Risk Assessment (for large tasks)
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| ... | High/Med/Low | High/Med/Low | ... |

---

Phase 3: Task Breakdown

After completing the technical solution design, based on the requirements document and technical solution, break down specific tasks. You must confirm with the user clearly, then save to {SPEC_PATH}/tasks.md. After confirming with the user, proceed to the next phase.

If user rejects or requests changes: Adjust task breakdown and re-confirm. Do NOT proceed to Phase 4 until user explicitly approves.

Task Field Specification

Every task in {SPEC_PATH}/tasks.md must contain the following fields:

Field	Specification	Example
Task name	Verb-object structure, ≤10 words	Remove unused methods from IMultiAppInfo
Scope	Files directly modified by this task	IMultiAppInfoProxyInterface.java, MultiAppInfoProxy.java
Affected	Files that need sync changes due to this task (imports, calls, etc.)	NoticeService.java, BpmService.java
Specifics	Most critical field. Precise down to method/field level	Interface remove methodA(), methodB(); add methodC(String)
Status	[✓] Done / [ ] Not started / [~] In progress or paused / [⏭] Skipped (user decision only; dependencies not auto-blocked, flag in final summary)	[✓]
Verification	How to verify (compile, test, grep, etc.)	grep signatures + compile verification
Commit	Backfill after git commit: actual commit message + short hash	feat(proxy): remove unused methods (a1b2c3d)
User corrections	Count of user corrections; ≥2 triggers escalation	0
Notes	Dependencies, blockers, scope changes	Depends on task 1

Critical field — Specifics: 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.

Status values:

• [ ] — Not started
• [~] — In progress
• [✓] — Done
• [⏭] — Skipped (only when user explicitly decides to skip; agent cannot self-skip; skipped tasks are excluded from execution — dependencies are not auto-blocked, but flag them in the final task summary)

Task Format Reference

markdown

# Implementation Plan

- [✓] 1. Remove unused methods from IMultiAppInfo
  - Scope: `IMultiAppInfoProxyInterface.java`, `MultiAppInfoProxy.java`
  - Affected: `NoticeService.java`
  - Specifics: Interface remove getCachedV2AppInfo(), listV1OfflineApps(); impl class sync
  - Verification: grep signatures + compile verification
  - Commit: feat(proxy): remove unused methods (a1b2c3d)
  - User corrections: 0
  - Notes: User requested keeping getV1AppInfo 3-param overload
  - _Requirement: R1

- [ ] 2. Add getAppName method
  - Scope: `IMultiAppInfoProxyInterface.java`, `MultiAppInfoProxy.java`
  - Affected: —
  - Specifics: Interface add getAppName(String); impl class add getAppName(String)
  - Verification: —
  - Commit: —
  - User corrections: —
  - Notes: Depends on task 1 completion
  - _Requirement: R2

---

Phase 4: Task Execution

Execute tasks in order from {SPEC_PATH}/tasks.md. This phase covers execution mechanics, state navigation, and session recovery.

Validation: Before executing, confirm {SPEC_PATH}/tasks.md exists, contains valid task entries (Scope + Specifics + Verification fields), and all tasks have valid status markers ([ ] / [~] / [✓] / [⏭]). If the file is missing, malformed, or has tasks with missing/invalid status markers, stop and fix the format before proceeding.

Quick Start

First time with a confirmed tasks.md:

text

0. Validate tasks.md format — ensure every task has a valid status marker [ ]/[~]/[✓]/[⏭]. Fix any missing/invalid markers before proceeding.
1. Read {SPEC_PATH}/tasks.md → if any [~] task exists, continue it; otherwise find first [ ] task
2. Mark it [~] → execute per Specifics description
3. When done: mark [✓], fill Verification, stage changes
4. Show diff → wait for user review and explicit commit approval (**skipped in [Continuous Operation Mode](#continuous-operation-mode)**)
5. If user approves: commit → backfill Commit field with actual message + short hash → next task. If user rejects: revert status to [~], address feedback, repeat from step 2
6. User says "next" → repeat from step 1

Session compressed? Jump to Compression Recovery. Continuous batch authorized by the user (e.g. "you may continue implementing" / "complete the rest without asking"), or running under driver/monitor automation? Jump to Continuous Operation Mode.

State Navigation

Where Am I?

text

Received user instruction
│
├─ Is the scope clear and small? ──→ YES → Do NOT use this skill, execute directly
│                                    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 / fix / routine) → see Entry Points for entry decisions	Decision: plan or execute directly
Planning in progress (Phase 1-3)	Continue current phase → wait for user confirmation before next phase	Confirmed spec doc
Ready to implement	Read {SPEC_PATH}/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 → wait for user confirmation → judge next step based on user's direction	Documented fix
Session interrupted / compressed	Jump to Compression Recovery	Recovered context
User asks unrelated question	Handle query → return to previous state, do NOT modify tracker	Continuity preserved
User starts a new feature mid-task	Pause current (mark [~]) → create new tracker → see Context Switching	New {SPEC_PATH}
User changes direction mid-task	Stop → document in Notes → wait for confirmation	Updated tracker
User corrects design assumption	Update tasks.md Notes and design.md → wait for confirmation	Synced docs
All tasks done	Generate final summary → wait for user confirmation → complete	See Task Completion

Task Completion

When all tasks in tasks.md are [✓] or [⏭]:

1. Generate final summary including:
   • Total tasks: done / skipped
   • Skipped tasks list (if any) — flag each with its original scope and reason for skip
   • User corrections total across all tasks
2. Present summary to user and wait for confirmation
3. After user confirms: the spec workflow is complete. Spec files (requirements.md, design.md, tasks.md) are retained as project documentation

State Transition Rules

The State Navigation table is the primary reference. The flow diagram below illustrates the core state machine; all scenarios in the table are authoritative.

text

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

[Executing] --(error)--> [Diagnosing] --(fixed)--> [Update tracker] --> [Executing]
                                    └─(stuck)--> [Ask user] --(user responds)--> [Judge next step based on user's direction]

[Complete] --(user confirms)--> [Done]

[Any state] --(unrelated user query)--> [Handle query] --> [Return to prior state]
[Any state] --(user changes direction)--> [Stop + document] --> [Wait for confirmation]
[Any state] --(user corrects design assumption)--> [Update tasks.md + design.md] --> [Wait for confirmation]
[Any state] --(session compressed/interrupted)--> [Recovery] --(tracker reconciled)--> [Resume prior state]

Scope note: The diagram above covers only tasks that enter the Spec workflow (Complex / Fix). Simple and Routine tasks are executed directly without entering this state machine.

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

Continuous Operation Mode

Skips per-task show diff → wait approval. Auto-advances to next [ ] task. All other tracker disciplines remain mandatory.

Activation

• User explicitly authorizes continuous batch (e.g. you may continue implementing / complete the rest without asking)
• Invoked by driver/monitor automation

Ambiguous confirmations (OK / continue / okay) do NOT activate. Authorization does not survive session compression.

Behavior Diff

Discipline	Status
Mark [~] / [✓], fill Verification + Commit	✅ Kept
Run verification (compile / test / grep)	✅ Kept
Per-task independent commit	✅ Kept
Increment User corrections on rejection	✅ Kept
Show diff → wait approval	❌ Skipped
Wait for next between tasks	❌ Auto-advance

Auto-Pause Triggers

Reverts to Default Mode immediately on:

Trigger	Action
Compilation / verification fails	Rollback to [~], record in Notes
User corrections ≥ 2	Escalate per project config
Scope expansion	Record drift, wait for confirmation
Risky ops (force push, reset --hard, schema migration, etc.)	Stop and ask
User interrupts	Stop after current task's commit
All tasks complete	Switch to Task Completion
Session compression recovery	Revert to Default, re-confirm

State Assurance

The Tracker (tasks.md)

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

Key reminders for execution:

• Specifics is the most critical field — must be precise down to method/field level; after session compression, recovery depends entirely on this field
• Status values: [ ] Not started / [~] In progress (set before editing code) / [✓] Done (set before committing) / [⏭] Skipped (user decision only)
• User corrections: ≥2 triggers escalation (user's project configuration defines the escalation behavior)

Timeliness Guarantee

{SPEC_PATH}/tasks.md must be updated in real time — never retroactively:

Event	Action	Why
Start a task	[ ] → [~] before editing code	Prevents duplicate work
Finish a task (before commit)	[~] → [✓], fill Verification immediately	Defines completion
Finish a task (after commit)	Backfill Commit field with actual message + short hash	Traceability
User changes scope	Record in Notes immediately, increment User corrections	Prevents drift
Session compresses	[~] → [ ] if uncertain about state	Prevents false progress

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

Prohibited:

• Never reconstruct progress after compression without re-verifying code state first
• Never write progress retroactively after compression — progress not written before compression is unreliable

Compression Recovery

{SPEC_PATH}/tasks.md is the operational basis for recovery.

Trigger: System message "This session is being continued from a previous conversation" or when memory is fuzzy.

Quick Step	Full Step Mapping
Read and confirm progress	Step 1
Verify code state	Step 2-3
Determine next step	Step 4-6

Full Compression Recovery Flow (6 Steps)

Step 1: Read Spec files, confirm {SPEC_PATH}/tasks.md progress

• Read {SPEC_PATH}/requirements.md, {SPEC_PATH}/design.md, {SPEC_PATH}/tasks.md
• tasks.md is the only trustworthy state source — summary progress descriptions are NOT reliable
• Special cases:
  • If Spec files don't exist:
    • If context indicates a Simple task (no requirement ID, no Spec): run git status and git diff, determine progress from working tree state, continue directly
    • Otherwise (Complex/Fix): Spec planning hasn't started. Re-run "Where Am I?" classification
  • If files exist but tasks.md is missing: Rebuild tasks.md from design.md, note in remarks "table rebuilt after compression recovery"
  • If all files exist: Proceed to Step 2

Step 2: Verify actual code state

• Run git status and git diff to confirm working tree state
• If no [✓] rows in tasks.md (no tasks completed yet): first [ ] or [~] row is the next task, skip the rest of this step and all of Step 3 → go to Step 4
• If [✓] rows exist: Only verify the last [✓] row (state boundary), re-execute verification per "Scope + Specifics + Verification" fields
• If verification passes → trust all prior [✓]; if fails → change that task status to [ ], consider backtracking
• If tasks.md doesn't match actual state, fix tasks.md first, then continue

Step 3: Do not trust summary "completed" conclusions

• Summary claims of "completed", "aligned", "fixed" — only verify the last completed task
• Especially for precision-critical conclusions (interface/impl alignment, method signature matching, compile status)
• If verification fails, revert that task to [ ], consider backtracking

Step 4: Re-confirm next task

• Explicitly state the next task name and scope
• Do not continue based on vague summary descriptions (e.g., "continue fixing remaining interfaces")

Step 5: Use programmatic verification, not manual reading

• For "does it exist", "is it aligned", "does it match" — prefer Bash tools (grep, javap, diff) for programmatic verification
• Never judge interface/impl alignment, method existence, or parameter matching by reading alone

Step 6: Update tasks.md before executing

• Before making any code changes, update {SPEC_PATH}/tasks.md first
• Ensure tasks.md is consistent with actual state

Context Switching

Scenario	Rule
User starts a new feature	Pause current task (mark [~]), create new tracker for new work
User raises multiple parallel requests	Confirm priority and order with user; create separate Spec directories (different {SPEC_NAME}) for each; execute sequentially, never mix tasks.md

Key principle: One tasks.md per requirement. Different requirements must have different {SPEC_PATH}.

Do not abandon unfinished tasks. Unless user explicitly says "cancel" or "skip", mark unfinished tasks as [~] and record progress.

When returning to a previous task, re-verify state. Verify the last [✓] row per Step 2 of Compression Recovery.

---

Key Principles

1. [HIGHEST PRIORITY]Real-Time Task Tracking — Updating {SPEC_PATH}/tasks.md is the definition of task completion; it takes precedence over all other operations
2. User Confirmation Required — Each phase must be confirmed by the user before proceeding to the next
3. Tracker is truth — When memory conflicts with tracker, trust the tracker; pause and reconcile with the user on conflicts
4. Verify with tools — Prefer programmatic verification (grep, diff, compiler); never rely on reading or memory for precision questions
5. Cross-check conclusions — Any conclusion from indirect observation must be independently verified