Project Workflow

Documentation-driven project development workflow, ensuring every development task is traceable and based on documentation.

Important Note: This skill assumes the project has a complete documentation structure (docs/README.md, PRD.md, SAD.md, etc.). For new projects or those lacking documentation, it is strongly recommended to first use the project-docs-setup skill to create complete documentation. If you need to formulate a new development plan, it is recommended to use the project-planning skill.

Workflow Overview

Project Initialization: project-docs-setup (Create documentation)
      ↓
Plan Formulation: project-planning (Requirement clarification + Design + Plan)
      ↓
Development Execution: project-workflow (Execute plan + Update documentation)

Prerequisites

Project Documentation

This skill relies on a complete project documentation system. If the project lacks documentation:

Recommended Approach:

Use the project-docs-setup skill:
  /project-docs-setup
  or tell me: "Create project documentation"

This skill will:
- Understand project requirements through multi-round conversations
- Provide professional product and architecture analysis
- Generate complete documentation such as PRD, SAD, development guides, etc.

Quick Mode: For simple testing only, Phase 0 can create a minimal directory structure, but no documentation content will be included.

Code Review Agent

This skill uses a general-purpose agent for code quality inspection and optimization.

Code Review Features:

Code quality review (code standards, best practices)
Bug and security vulnerability detection
Performance optimization suggestions
Readability and maintainability analysis

Usage Method:

Call using Task tool:
  subagent_type="general-purpose"
  description="Code review for recent changes"
  prompt="Detailed code review prompt..."

Review Process:

Call the general-purpose agent to analyze code changes
The agent generates a detailed review report
Fix issues based on the report
Re-run the review until no major issues exist

Core Process

0. Initialize documentation structure → 1. Read documentation → 2. Determine task type
   ├─ Specified plan → 3. Execute existing plan → Code review → Fix and optimize → 4. Update documentation
   └─ No plan → Prompt to use project-planning to create a plan

Phase 0: Check Documentation Structure

Automatically checked before execution starts.

0.1 Check Required Documentation

Check if the project has a standard documentation structure:

bash

# Check required directories and files
- docs/README.md           # Documentation index (required)
- docs/plans/              # Plan file directory
- docs/specs/              # Specification documents

0.2 Handling Missing Documentation

If incomplete documentation structure is detected:

1. Display detection results:
   "Detected missing project documentation structure"

2. Provide suggestions:
   "It is recommended to use the project-docs-setup skill to create complete project documentation:
   - This skill will understand project requirements through multi-round conversations
   - Automatically generate complete documents such as PRD, SAD, development guides, etc.
   - Provide best practice suggestions and architecture analysis

   Execution methods:
   /project-docs-setup
   or
   Tell me: 'Create project documentation'"

3. Ask for user's choice:
   "How would you like to handle this?
   a) Create complete documentation first (recommended) - I can help you call project-docs-setup
   b) Create minimal structure to continue - Only create empty directories, no documentation content
   c) Skip check and continue execution - Assume documentation is in another location"

4. Based on user's choice:
   - Choose a: Call project-docs-setup skill or prompt user to run it
   - Choose b: Execute 0.3 to create minimal structure
   - Choose c: Skip Phase 0 and enter Phase 1

0.3 Create Minimal Structure (Only when user chooses)

bash

# Only create directory structure, no files will be created
mkdir -p docs/plans
mkdir -p docs/specs
mkdir -p docs/guides
mkdir -p docs/modules
mkdir -p docs/database
mkdir -p docs/api

echo "Basic directory structure created."
echo "Note: Directories are empty, it is recommended to use project-docs-setup to supplement complete documentation later."

0.4 Documentation Exists

If documentation structure is complete, display confirmation information and skip this phase:

✓ Detected complete documentation structure
✓ Directly enter Phase 1

Phase 1: Read Project Documentation

Must be completed before each execution.

1. Read docs/README.md to get documentation index
2. Read task-related documents based on the index:
   - Specification documents (specs/)
   - Module documents (modules/)
   - Development guides (guides/)
3. Read AGENTS.md (if exists) to understand project conventions

Key Document Priority:

Architecture Design (SAD.md) > Requirement Document (PRD.md) > Module Documents > Guides

Phase 2: Determine Task Type

Determine whether to execute an existing plan or create a new plan based on user input.

2.1 Identify Task Type

Signs of executing existing plan:

User clearly specifies plan number: "Execute plan 001", "Continue 001-user-authentication"
User says "Execute plan", "Continue last task" and there is an ongoing plan

Signs of creating new plan:

User describes functional requirements: "Implement user authentication", "Add OCR module"
User says "Start developing XXX feature"

2.2 Routing Logic

if user specified plan number or there is a clear ongoing plan:
    → Phase 3: Execute existing plan
else:
    → Prompt user to use project-planning to create a plan

2.3 Usage Examples

Scenario 1: Execute existing plan

User: "Execute plan 001"
or
User: "Continue development of 001-user-authentication"

→ Route to Phase 3, read and execute the plan

Scenario 2: No plan exists

User: "Implement user authentication feature"
or
User: "Add API rate limiting"

→ Prompt user to use project-planning to create a plan first:
   "Please use the project-planning skill to create an implementation plan first.
    Execution methods: /project-planning
    or tell me: 'Help me plan this feature'"

Phase 3: Execute Existing Plan

When the user specifies a specific plan file, execute the plan directly.

3.1 Read Plan

1. Locate the plan file based on the user-specified number (e.g., docs/plans/001-user-authentication.md)
2. Read the complete content of the plan file
3. Check plan status (pending/in progress/completed)

3.2 Create Task List

1. Convert tasks in the plan to todos using TodoWrite
2. Update plan status to "in progress"

3.3 Execute Step by Step

For each task:
  1. Mark todo as in_progress
  2. Execute task with reference to relevant documents
  3. Run tests/verification
  4. Mark todo as completed
  5. Update task status in the plan file [x]
  6. Add record to the execution record table

Execution Principles:

Follow CONVENTIONS and ANTI-PATTERNS in the project's AGENTS.md
Follow TDD: Write tests first, then implement
Update the plan file immediately after completing each task

3.4 Completion Verification

1. Confirm all tasks are completed
2. Run complete test suite
3. Execute code review
4. Fix and optimize loop
5. Update plan status to "completed"
6. Enter Phase 4 to update documentation

3.5 Code Review and Fix Loop

Use general-purpose agent for code quality inspection:

Loop until no major issues exist:
  1. Call general-purpose agent
     Using Task tool:
       subagent_type="general-purpose"
       description="Code review for recent changes"
       prompt="
         Please review the code changes for this feature/task.

         Focus on the following aspects:
         1. Code quality and best practices
            - Code style and consistency
            - Follow project conventions (check AGENTS.md if exists)
            - SOLID principles and design patterns

         2. Bugs and security
            - Potential bugs or edge cases
            - Security vulnerabilities (SQL injection, XSS, etc.)
            - Completeness of error handling

         3. Performance
            - Performance bottlenecks
            - Inefficient algorithms or queries
            - Memory leaks or resource management issues

         4. Maintainability
            - Code readability and clarity
            - Documentation and comments (when necessary)
            - Test coverage

         Please classify issues by severity:
         - Blocking: Critical issues that must be fixed (security, severe bugs)
         - Important: Important issues that should be fixed (performance, code quality)
         - Minor: Improvement suggestions (readability, small optimizations)

         Please provide specific file paths and line numbers for each issue.
       "

  2. Analyze review report
     - Code standard issues
     - Potential bugs and security vulnerabilities
     - Performance optimization suggestions
     - Maintainability issues

  3. Classify by severity
     - Blocking issues (must fix): Security vulnerabilities, severe bugs
     - Important issues (should fix): Performance issues, code standards
     - Suggested optimizations (optional): Readability improvements, small optimizations

  4. Fix blocking and important issues
     - Modify code
     - Run tests to ensure fixes are effective
     - Update relevant documentation

  5. Re-run code review
     - Verify issues are resolved
     - Check for new issues introduced

  6. Confirm completion
     - No blocking issues
     - Important issues are fixed or have a plan for handling
     - User confirms to continue

Code Review Principles:

Blocking issues must be resolved in this phase
Important issues should be resolved as much as possible
Suggested optimizations can be recorded as technical debt and handled later
Re-run code review after each fix
Maximum 3-5 iterations to avoid over-optimization

Phase 4: Update Documentation

After task completion, update affected documentation.

Documents that must be checked and updated:

Change Type	Documents to Update
New module added	docs/modules/{module}.md, docs/specs/SAD.md
API changes	docs/api/*.md
Database changes	docs/database/SCHEMA.md
New feature added	docs/specs/PRD.md
Architecture adjustment	docs/specs/SAD.md, AGENTS.md

Update AGENTS.md:

If there are new conventions or anti-patterns, add to corresponding sections
Update CHANGELOG to record changes

Exception Handling

Scenario	Handling Method
No docs/ directory	Automatically create documentation structure (Phase 0)
No docs/plans/ directory	Automatically create docs/plans/ directory
No plan file	Prompt user to use project-planning to create a plan
Code review agent execution failed	Check error message, try re-execution or skip code review
Blocking issues found in code review	Must fix before continuing, record in execution record
Code review iterations exceed 5 rounds	Discuss with user, decide whether to continue optimization or accept current status
Plan execution interrupted	Read plan file when resuming, continue from uncompleted tasks
Task execution failed	Record failure reason in execution record, ask user for handling method
Requirement change	Update plan file, mark original task status, add new tasks

Appendix

Plan File Naming Convention

docs/plans/
├── 001-user-authentication.md
├── 002-llm-service-integration.md
├── 003-ocr-module.md
└── ...

Naming Rules:

Format:
```
001-feature-name.md
```
(3-digit number + feature name)
Numbering starts from 001 and increments
Feature name uses lowercase letters and hyphens, concise and clear

Use project-planning to Formulate Plans

When no plan file exists, use the project-planning skill to create a plan:

Call project-planning:

Call using Skill tool: skill="project-planning"
or tell user: "/project-planning" or "Help me plan this feature"

project-planning will automatically:

Determine requirement clarity
Select appropriate mode (Brainstorming or Writing Plans)
Produce plan documentation (includes design and implementation, detail level depends on complexity)
Save to
```
docs/plans/001-feature-name.md
```

After completion:

Plan file will be saved to
```
docs/plans/001-feature-name.md
```
(using 3-digit numbering)
Return to project-workflow, execute the plan using Phase 3

Detailed Information:

Refer to project-planning skill documentation
Supports requirement clarification, design discussion, detailed plan writing

project-workflow

NPX Install

Tags

SKILL.md Content (Chinese)