Spec Workflow

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
• Documentation updates
• Configuration changes

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 5 test scenarios covering all phases. 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:

Spec file list:

Entry Points

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:

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

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

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

# 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
  - User corrections: 0 | Compression recoveries: 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: — | Compression recoveries: —
  - 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 and contains valid task entries (Scope + Specifics + Verification fields). If the file is missing or malformed, stop and ask the user.

Quick Start

First time with a confirmed tasks.md:

1. Read {SPEC_PATH}/tasks.md → find first [ ] task
2. Mark it [~] → execute per Specifics description
3. When done: mark [✓], fill Verification + Commit, stage changes
4. Show diff → wait for user review and explicit commit approval
5. If user approves: commit → next task. If user rejects: revert status to [~], address feedback, repeat from step 3
6. User says "next" → repeat from step 1

Session compressed? Jump to Compression Recovery.

State Navigation

Where Am I?

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

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
   • Compression recoveries 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.

[Classified] --(simple/routine)--> [Executing] --(task done)--> [Update tracker] --(more tasks)--> [Executing]
      │                              │                                    └─(all done)--> [Complete]
      └─(complex/fix)--> [Planning] --(confirmed)--> [Executing]
                             └─(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]

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

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)
• Compression recoveries: +1 after each compression recovery

Timeliness Guarantee

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

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.

Step 1 (check recovery count) must be performed first before any other step.

Full Compression Recovery Flow (7 Steps)

Step 1: Check recovery count, decide whether to continue

• Count the real compression recovery count since last session reset using the method below, then write the result into the current task's Compression recoveries field in {SPEC_PATH}/tasks.md
• Report count: Tell user "This task has been compression-recovered X times"
• Decision branch:
  • If < 6: Continue to Step 2
  • If ≥ 6: Stop execution immediately, then:
    1. Update {SPEC_PATH}/tasks.md: mark current task as [~], update compression recovery count
    2. Tell user: "Current task has been compression-recovered X times (≥6). Accumulated context errors may make state reconstruction unreliable. Please reset session — I will continue from Spec files in a new session."
    3. Do not execute any code modifications — wait for user to reset session
  • 6 is a hard threshold, do not override

Compression Recovery Count Method (for Step 1):

Count real context compaction events, never estimate manually.

Steps:

1. Identify the agent's session storage directory (e.g., for Claude Code: ~/.claude/projects/{project-hash}/sessions/)
2. Find session files that contain the current requirement ID
3. Count compression markers within those files (e.g., for Claude Code: count occurrences of <compacted> or similar context-compaction tags)
4. Sum all matching compression events = true compression recovery count for this requirement
5. Write the result into the current task's Compression recoveries field in {SPEC_PATH}/tasks.md

If the agent platform's session storage structure is unknown, fall back to reading the Compression recoveries field values from all tasks in tasks.md and use the maximum value + 1 as the current count. Report to user that this is an estimate.

Step 2: 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 3

Step 3: 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 Step 3 and Step 4 → go to Step 5
• 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 4: 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 5: 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 6: 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 7: 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

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