Issue 14 | Workflow Automation: Workflow Definition and Skill Pipeline

14.1 Workflow Definition

Workflows are defined in the .agents/workflows/ directory and are the concrete step descriptions of a Skill pipeline. Each workflow file is a Markdown document, listing the sequence of operations an agent should follow, organized by stage.

14.1.1 Workflow Directory Structure

.agents/workflows/
├── feature-development.md   # New Feature Development (8 stages, 27 steps)
├── bug-fix.md               # Bug Fix (4 stages, 13 steps)
├── plan-and-research.md     # Planning and Research (4 stages, 13 steps)
└── session-archive.md       # Session Archive (3 stages, 10 steps)

14.1.2 Workflow Loading Mechanism

Agent executes a Skill (e.g., /planning-with-files)
  → Skill reads the corresponding workflow file under .agents/workflows/
  → Injects workflow steps into the agent's context
  → Agent executes step-by-step

Workflow files are not automatically loaded—they are used indirectly through the Skill call chain. An Agent needs to call the corresponding Skill to read the workflow content.

14.1.3 Feature Development Workflow (feature-development.md)

This is the most complete workflow, covering the entire process from planning to archiving:

flowchart TD
    S1["Stage 1: Planning
planning-with-files"] --> S2["Stage 2: Design
brainstorming → writing-plans"]
    S2 --> S3["Stage 3: Prepare for Execution
plan written to task_plan.md"]
    S3 --> S4["Stage 4: TDD Execution
test-driven-development"]
    S4 --> S5{"Tests Pass?"}
    S5 -->|No| S6["Stage 5: Debugging
systematic-debugging"]
    S6 --> S4
    S5 -->|Yes| S7["Stage 6: Verification
verification-before-completion"]
    S7 --> S8["Stage 7: Review
requesting-code-review"]
    S8 --> S9["Stage 8: Archiving
Update all plan files"]

    style S4 fill:#c8e6c9
    style S6 fill:#ffcdd2
    style S7 fill:#bbdefb

27 Steps in Detail:

14.1.4 Bug Fix Workflow (bug-fix.md)

# Bug Fix Workflow

## Stage 1: Diagnosis
1. Use planning-with-files
2. Restore task_plan.md, findings.md, progress.md, bugs.md
3. Use systematic-debugging
4. Record symptoms, potential root causes, and reproduction path in bugs.md

## Stage 2: Reproduction and Fix
5. Use test-driven-development
6. First create or run a failing reproduction check
7. Implement minimal fix

## Stage 3: Regression Verification
8. Rerun target checks
9. Run relevant regression checks
10. Use verification-before-completion

## Stage 4: Archiving
11. Update fix and timestamp in bugs.md
12. Update fix summary in progress.md
13. Update relevant task status in task_plan.md

14.1.5 Planning and Research Workflow (plan-and-research.md)

# Planning and Research Workflow

## Stage 1: Plan Files
1. Use planning-with-files
2. Restore or create root directory plan files
3. Record current problem definition in task_plan.md

## Stage 2: Discovery
4. Read requirement.md
5. Explore local files, reference materials, and current constraints
6. Record findings, risks, and open questions in findings.md

## Stage 3: Design
7. Use brainstorming
8. Clarify scope, tradeoffs, success criteria, and interface boundaries
9. Produce design spec

## Stage 4: Implementation Plan
10. Use writing-plans
11. Convert spec into a phased implementation plan
12. Use planning-with-files to write to task_plan.md
13. Record next steps in progress.md

14.1.6 Session Archive Workflow (session-archive.md)

# Session Archive Workflow

## Stage 1: Document Archiving
1. Check task_plan.md: Completed [x], In Progress [/], Blocked [!]
2. Update progress.md: Append session summary
3. Update findings.md if new discoveries
4. Update bugs.md if new failures

## Stage 2: Verification
5. Confirm latest verification evidence is written to progress.md
6. Confirm next active stage is visible in task_plan.md
7. Confirm unresolved risks are visible for the next session

## Stage 3: Handoff
8. Summarize what was completed this round
9. Summarize what remains
10. For final integration, follow Git rules in CLAUDE.md

14.1.7 How to Create Custom Workflows

# 1. Create directory
mkdir -p .agents/workflows

# 2. Create workflow file
cat > .agents/workflows/feature-development.md << 'EOF'
# Feature Development Workflow

## Stage 1: Planning
1. Use planning-with-files
2. Restore or create plan files
...

## Stage 2: Design
...
EOF

# 3. Reference in CLAUDE.md
echo "## Skill Usage Rules" >> CLAUDE.md
echo "Feature development uses the feature-development workflow" >> CLAUDE.md

Workflow Design Principles:

1. One clear action per step — "Use X skill" or "Update Y file"
2. Clear output — Verifiable output at the end of each stage
3. Step numbering — Facilitates agent progress tracking
4. Reference Skill names — Agent knows when to call which Skill
5. Reference file names — Clearly indicates which file to write to

14.2 Skill Pipeline

Skills are reusable instruction templates for Claude Code. Each Skill defines a specific working method (e.g., TDD, debugging, planning), invoked via /skill-name.

14.2.1 Overview of Skills Used in This Project

flowchart LR
    subgraph "Planning Stage"
        PWF[planning-with-files]
        BS[brainstorming]
        WP[writing-plans]
    end
    
    subgraph "Execution Stage"
        TDD[test-driven-development]
        SD[systematic-debugging]
    end
    
    subgraph "Delivery Stage"
        VBC[verification-before-completion]
        RCR[requesting-code-review]
        FDB[finishing-a-development-branch]
    end
    
    subgraph "Parallel/Delegation"
        DPA[dispatching-parallel-agents]
        SDD[subagent-driven-development]
        EP[executing-plans]
    end
    
    subgraph "Plugin Skill"
        MS[mem-search]
        KA[knowledge-agent]
        SE[smart-explore]
        CV[caveman]
    end
    
    PWF --> BS --> WP --> TDD --> SD --> VBC --> RCR --> FDB
    
    style PWF fill:#e1f5fe
    style TDD fill:#c8e6c9
    style VBC fill:#fff9c4
    style MS fill:#f3e5f5

14.2.2 Core Skill Details

14.2.3 Skill Sources

Skill Sources:
├── User Skills (~/.claude/skills/)
│   ├── planning-with-files
│   ├── brainstorming
│   ├── writing-plans
│   ├── test-driven-development
│   ├── systematic-debugging
│   ├── verification-before-completion
│   ├── requesting-code-review
│   ├── dispatching-parallel-agents
│   ├── subagent-driven-development
│   ├── executing-plans
│   └── finishing-a-development-branch
│
└── Plugin Skills
    ├── caveman (caveman plugin)
    │   ├── /caveman
    │   ├── /caveman-commit
    │   └── /caveman-review
    └── claude-mem (claude-mem plugin)
        ├── /mem-search
        ├── /knowledge-agent
        └── /smart-explore

14.2.4 Skill Limitations in Teams Mode

flowchart TD
    TL["team-lead session"] -->|"✅ Can call all Skills"| SK["Skill Execution"]
    AG["Sub-Agent
(ui-dev / logic-dev / qa)"] -->|"❌ Not recommended to call"| X["Permission popup → Agent stops"]
    
    TL -->|"Alternative Solution"| P["Inline Skill rules
in the prompt"]
    P --> AG2["Agent works directly by rules
without calling Skill tools"]
    
    style X fill:#ffcdd2
    style P fill:#c8e6c9
    style AG2 fill:#c8e6c9

Why Sub-Agents Should Not Call Skills:

1. Skills are tool calls — Require being in the settings.json allow list
2. Skills have nested operations — bypassPermissions does not cover nested layers
3. Skill execution consumes context — A sub-agent's 200k token window can be filled by Skill output
4. Unnecessary — Planning is completed by the team-lead; sub-agents only need to execute

Alternative: Inline Skill Rules into Agent Prompt

Agent({
  name: "logic-dev",
  prompt: `你是 logic-dev。

// Directly write TDD rules in the prompt, replacing the /test-driven-development Skill
// Replacing the /systematic-debugging Skill
Working Rules:
1. Write failing tests first (RED)
2. Implement minimal passing code (GREEN)
3. Refactor (REFACTOR)
4. When tests fail: diagnose → fix → rerun, do not retry blindly
5. Maximum 5 self-repair attempts, stop after exceeding

...`
})

14.2.5 Relationship Between Skills and Workflows

Skill (Tool)    →    Workflow (Step-by-step Guide)    →    Files (State Persistence)

/brainstorming         feature-development.md       findings.md
/planning-with-files   steps 6-8 of                  task_plan.md
                                                  progress.md

• Skills are callable tools (/skill-name), defining what to do
• Workflows are step-by-step guides (.agents/workflows/*.md), defining in what order to do it
• CLAUDE.md is the project constitution, defining rules and boundaries
• Plan files (task_plan.md, etc.) are for persistent state

14.2.6 Referencing Skills and Workflows in CLAUDE.md

The Skill Usage Rules section in CLAUDE.md tells the agent:

1. Which Skills must be used (planning-with-files to start complex tasks)
2. In what order to use them (pipeline: brainstorming → writing-plans → TDD → verification)
3. Which steps cannot be skipped (design does not skip brainstorming, completion does not skip verification)
4. What to use when failing (use systematic-debugging for test failures, do not retry arbitrarily)

This set of rules ensures that every agent follows a unified working methodology, even in Teams parallel development.