Development Workflow

Language Rules

• Supports Chinese and English queries
• Responses are uniformly in Chinese

Trigger Conditions

• User starts executing a task (e.g., T-01)
• User needs development guidance
• User enters the development phase from devdocs-dev-tasks
• Keywords: "execute task", "start T-XX", "开发任务", "执行任务"

Preconditions

• Task document:

  docs/devdocs/04-dev-tasks.md

• Task is defined and includes: associated requirements, acceptance criteria, testing methods

Workflow

1. Read Task Definition
   ├── Retrieve task details from 04-dev-tasks.md
   ├── Confirm associated F-XXX, AC-XXX
   └── Confirm associated test cases UT/IT/E2E-XXX
           │
           ▼
2. Generate Skeleton Code (Top-Down)
   ├── Interface skeleton + @requirement/@satisfies annotations
   └── Test skeleton + @verifies/@testcase annotations
           │
           ▼
3. Execute Development (Layered TDD)
   ├── Core Logic 🔴: Test-first
   ├── Interface Layer 🟡: Recommended test-first
   ├── UI Layer 🟢: Tests can be added after implementation
   └── Infrastructure ⚪: Verified via integration tests
           │
           ▼
4. Completion Check
   ├── Basic Check (Always Executed)
   │   ├── All acceptance criteria are satisfied
   │   ├── Tests pass
   │   └── Self-check of review points
   │
   └── Adversarial Verification (🔴 Auto-triggered / Manual trigger via --review for other layers)
       ├── 🔍 Code Quality Review (from /code-quality perspective)
       ├── 🧪 Test Completeness Review (from /testing-guide perspective)
       └── 📋 Comprehensive Review Report
           │
           ▼
4.5 Update Self-description (Run /code-self-describe --update)
           │
           ▼
5. Submit Code (Follow /commit-convention)
           │
           ▼
6. Update Traceability (Run /devdocs-sync --trace)

Code Traceability Annotation Specification

Achieve two-way traceability between documents and code; AI automatically adds annotations when generating code.

Annotation Types

@requirement F-XXX

@satisfies AC-XXX

@verifies AC-XXX

@testcase UT/IT/E2E-XXX

Annotation Example

/**
 * Create User
 * @requirement F-001 - User Registration
 * @satisfies AC-001 - Email Format Validation
 * @satisfies AC-002 - Password Strength Validation
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // Implementation code
}

/**
 * @verifies AC-001 - Email Format Validation
 * @testcase UT-001
 */
test('createUser should reject invalid email formats', () => {
  // Test code
});

Annotation Rules

Top-Down Development Mode

Define the skeleton first, then fill in the details. Ensure the traceability chain is established during code generation.

Development Process

Step 1: Generate Interface Skeleton
        ├── Method signature (from 02-system-design.md)
        ├── Add @requirement/@satisfies annotations
        └── Method body: throw new Error('Not implemented')
                │
                ▼
Step 2: Generate Test Skeleton
        ├── Test structure (from 03-test-cases.md)
        ├── Add @verifies/@testcase annotations
        └── Test body: test.skip() or test.todo()
                │
                ▼
Step 3: Implement Interface Details (Follow /code-quality)
                │
                ▼
Step 4: Improve Tests (Follow /testing-guide)
                │
                ▼
Step 5: Run /devdocs-sync --trace to update traceability matrix

Skeleton Generation Constraints

• Interface skeleton must include complete signature (parameters, return value, generics)
• Interface skeleton must add traceability annotations
• Unimplemented methods must throw an Error and indicate the task ID
• Test skeleton must use skip/todo markers
• Test skeleton must add @verifies and @testcase annotations

Layered TDD Mode

TDD Cycle

┌─────┐    ┌─────┐    ┌─────┐
│ Red │ → │ Green│ → │Refactor│ ──┐
│Write Test│    │Write Code│    │Optimize│   │
│(Fails)│    │(Passes)│    │Code │   │
└─────┘    └─────┘    └─────┘   │
    ↑                           │
    └───────────────────────────┘

Skill Collaboration

/code-quality

/testing-guide

/ui-orchestrator

/code-quality

/testing-guide

/code-self-describe

/git-safety

/commit-convention

/devdocs-sync

Constraints

Skeleton Generation Constraints

• Interface skeleton must include complete signature
• Interface skeleton must add traceability annotations
• Unimplemented methods must throw an Error
• Test skeleton must use skip/todo markers
• Test skeleton must add @verifies and @testcase annotations

Layered TDD Constraints

• Core logic tasks must be marked 🔴 Mandatory TDD
• Core logic tasks must write tests first, then implementation
• Core logic tasks cannot be submitted before tests pass
• Interface layer tasks are marked 🟡 Recommended TDD
• UI layer tasks are marked 🟢 Optional TDD
• Infrastructure tasks are marked ⚪ Not Applicable TDD
• TDD tasks must include red-green-refactor three steps

Completion Check Constraints

• All acceptance criteria (AC-XXX) are satisfied
• All associated tests pass
• Self-check of review points is completed
• Code traceability annotations are complete
• Code branch coverage analysis is completed (Optional, use /testing-guide branch analysis)

Adversarial Verification (Optional)

Review code from different role perspectives, simulating the multi-person collaboration mode of "Development → Review → Testing". Core logic tasks (🔴) trigger automatically; other layers are triggered manually via

--review

.

Trigger Conditions

Layer Determination: Task layer markers (🔴🟡🟢⚪) come from task definitions in

04-dev-tasks.md

, assigned by

/devdocs-dev-tasks

during task splitting according to task layering rules.

--skip-review

--review

--review

--review

Verification Process

Basic Completion Check (Always Executed)
        │
        ├── All AC satisfied ✅
        ├── All tests pass ✅
        ├── Code annotations complete ✅
        │
        ▼ (When adversarial verification is triggered)
Phase 1: Code Quality Review 🔍
        ├── Switch to /code-quality perspective
        ├── MTE principle check (function length/parameters/nesting/responsibilities)
        ├── Dependency direction check
        ├── Security check
        └── Output: Issue list (Blocker/Suggestion)
        │
        ▼
Phase 2: Test Completeness Review 🧪
        ├── Switch to /testing-guide perspective
        ├── Assertion quality check (forbid weak assertions)
        ├── Coverage check (line/branch ≥80%)
        ├── Requirement traceability check (full AC coverage)
        ├── [Optional] Code branch coverage analysis
        └── Output: Issue list (Blocker/Suggestion)
        │
        ▼
Phase 3: Comprehensive Review Report 📋
        ├── Summarize all issues
        ├── 🚫 Blocker → Must fix before re-verification
        └── 💡 Suggestion → Ask user if they want to fix

Review Result Levels

Adversarial Verification Constraints

• Blocker issues must be fixed before submission
• Each phase must clearly state the current review role
• Review results must be classified (Blocker/Suggestion)
• Core logic tasks (🔴) are triggered by default
• Must re-run verification after fixing Blocker issues

See verification-flow.md for detailed review checklist and report template

Task Completion Process

TDD Tasks (Core Logic 🔴)

1. Confirm test-first approach: Check if tests were written first
2. Confirm red-green cycle: Tests go from failed to passed
3. Check refactoring: Whether code has been optimized
4. Verify acceptance criteria: Check if all AC are satisfied
5. Adversarial Verification (Auto-triggered):
   • Phase 1: Code Quality Review (from /code-quality perspective)
   • Phase 2: Test Completeness Review (from /testing-guide perspective)
   • Phase 3: Comprehensive report, handle Blockers
6. Update self-description: Run /code-self-describe --update
7. Ask for submission: Use AskUserQuestion to ask:
   • "Task T-XX (TDD) is completed, tests passed. Do you want to submit the code?"
   • Options: "Submit" / "Continue modifying" / "Skip"
8. If submit: Execute git add and commit, with task ID included in the message
9. Update status: Mark the task as completed

Non-TDD Tasks (Interface/UI/Infrastructure)

1. Execute tests: Run the testing methods defined in the task
2. Verify acceptance criteria: Check if all acceptance criteria are satisfied
3. Adversarial Verification (If triggered via --review): Same as Phase 1-3 above
4. Self-check review points: Check code review points
5. Ask for submission: Use AskUserQuestion to ask
6. If submit: Execute git add and commit
7. Update status: Mark the task as completed

Commit Message Format

/commit-convention

<type>(T-XX): <Task Name>

- <Completed Item 1>
- <Completed Item 2>

Related: F-XXX, AC-XXX
Tests: UT-XXX, IT-XXX Passed

References

• skeleton-examples.md - Interface/test skeleton examples
• execution-flow.md - Detailed task execution process
• verification-flow.md - Detailed adversarial verification process