mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
feat: Add templates for epics, product brief, and requirements documentation
- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files. - Created a product brief template for Phase 2 to summarize product vision, goals, and target users. - Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices. feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis - Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt. - Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
This commit is contained in:
catlog22
@@ -0,0 +1,52 @@
|
||||
# Analyze Task
|
||||
|
||||
Parse plan-and-execute input -> detect input type -> determine execution method -> assess scope.
|
||||
|
||||
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
|
||||
|
||||
## Signal Detection
|
||||
|
||||
| Input Pattern | Type | Action |
|
||||
|--------------|------|--------|
|
||||
| `ISS-\d{8}-\d{6}` pattern | Issue IDs | Use directly |
|
||||
| `--text '...'` flag | Text requirement | Create issues via CLI |
|
||||
| `--plan <path>` flag | Plan file | Read file, parse phases |
|
||||
|
||||
## Execution Method Selection
|
||||
|
||||
| Condition | Execution Method |
|
||||
|-----------|-----------------|
|
||||
| `--exec=codex` specified | Codex |
|
||||
| `--exec=gemini` specified | Gemini |
|
||||
| `-y` or `--yes` flag present | Auto (default Gemini) |
|
||||
| No flags (interactive) | AskUserQuestion -> user choice |
|
||||
| Auto + task_count <= 3 | Gemini |
|
||||
| Auto + task_count > 3 | Codex |
|
||||
|
||||
## Scope Assessment
|
||||
|
||||
| Factor | Complexity |
|
||||
|--------|------------|
|
||||
| Issue count 1-3 | Low |
|
||||
| Issue count 4-10 | Medium |
|
||||
| Issue count > 10 | High |
|
||||
| Cross-cutting concern | +1 level |
|
||||
|
||||
## Output
|
||||
|
||||
Write <session>/task-analysis.json:
|
||||
```json
|
||||
{
|
||||
"task_description": "<original>",
|
||||
"input_type": "<issues|text|plan>",
|
||||
"raw_input": "<original input>",
|
||||
"execution_method": "<codex|gemini>",
|
||||
"issue_count_estimate": 0,
|
||||
"complexity": { "score": 0, "level": "Low|Medium|High" },
|
||||
"pipeline_type": "plan-execute",
|
||||
"roles": [
|
||||
{ "name": "planner", "prefix": "PLAN", "inner_loop": true },
|
||||
{ "name": "executor", "prefix": "EXEC", "inner_loop": true }
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -118,14 +118,14 @@ Collect task states from TaskList()
|
||||
| +- EXEC-* -> executor
|
||||
+- Spawn team-worker:
|
||||
Agent({
|
||||
agent_type: "team-worker",
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker for <subject>",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-planex/role-specs/<role>.md
|
||||
role_spec: .claude/skills/team-planex/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: <team-name>
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
# Coordinator Role
|
||||
|
||||
Orchestrate the team-planex pipeline: parse input, create team, dispatch tasks, monitor progress via Spawn-and-Stop beats. Uses **team-worker agent** for all worker spawns.
|
||||
Orchestrate team-planex: analyze -> dispatch -> spawn -> monitor -> report.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
||||
- **Responsibility**: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor callbacks -> Spawn executors -> Report
|
||||
- Name: coordinator | Tag: [coordinator]
|
||||
- Responsibility: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor callbacks -> Spawn executors -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -22,29 +21,22 @@ Orchestrate the team-planex pipeline: parse input, create team, dispatch tasks,
|
||||
- Call implementation CLI tools (code-developer, etc.) directly
|
||||
- Skip dependency validation when creating task chains
|
||||
|
||||
---
|
||||
|
||||
## Command Execution Protocol
|
||||
|
||||
When coordinator needs to execute a command (dispatch, monitor):
|
||||
|
||||
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
|
||||
2. **Follow the workflow** defined in the command file
|
||||
3. **Commands are inline execution guides** - NOT separate agents
|
||||
4. **Execute synchronously** - complete the command workflow before proceeding
|
||||
|
||||
---
|
||||
When coordinator needs to execute a command:
|
||||
1. Read `commands/<command>.md`
|
||||
2. Follow the workflow defined in the command
|
||||
3. Commands are inline execution guides, NOT separate agents
|
||||
4. Execute synchronously, complete before proceeding
|
||||
|
||||
## Entry Router
|
||||
|
||||
When coordinator is invoked, detect invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains `[planner]` or `[executor]` tag | -> handleCallback (monitor.md) |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Add tasks | Arguments contain "add" | -> handleAdd |
|
||||
| Worker callback | Message contains [planner] or [executor] tag | -> handleCallback (monitor.md) |
|
||||
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Add tasks | Args contain "add" | -> handleAdd |
|
||||
| Interrupted session | Active/paused session exists in `.workflow/.team/PEX-*` | -> Phase 0 |
|
||||
| New session | None of above | -> Phase 1 |
|
||||
|
||||
@@ -58,13 +50,11 @@ For callback/check/resume: load `commands/monitor.md` and execute the appropriat
|
||||
4. If planner already sent `all_planned` (check team_msg) -> `SendMessage` to planner to re-enter loop
|
||||
5. STOP
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
1. Scan `.workflow/.team/PEX-*/.msg/meta.json` for sessions with status "active" or "paused"
|
||||
2. No sessions found -> proceed to Phase 1
|
||||
3. Single session found -> resume (Session Reconciliation)
|
||||
2. No sessions -> Phase 1
|
||||
3. Single session -> resume (Session Reconciliation)
|
||||
4. Multiple sessions -> AskUserQuestion for selection
|
||||
|
||||
**Session Reconciliation**:
|
||||
@@ -73,20 +63,18 @@ For callback/check/resume: load `commands/monitor.md` and execute the appropriat
|
||||
3. Rebuild team if needed (TeamCreate + spawn needed workers)
|
||||
4. Kick first executable task -> Phase 4
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Input Parsing + Execution Method
|
||||
|
||||
1. **Parse arguments**: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
|
||||
TEXT-LEVEL ONLY. No source code reading.
|
||||
|
||||
2. **Determine execution method** (see SKILL.md Selection Decision Table):
|
||||
1. Delegate to commands/analyze.md -> produces task-analysis.json
|
||||
2. Parse arguments: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
|
||||
3. Determine execution method (see specs/pipelines.md Selection Decision Table):
|
||||
- Explicit `--exec` flag -> use specified method
|
||||
- `-y` / `--yes` flag -> Auto mode
|
||||
- No flags -> AskUserQuestion for method choice
|
||||
|
||||
3. **Store requirements**: input_type, raw_input, execution_method
|
||||
|
||||
---
|
||||
4. Store requirements: input_type, raw_input, execution_method
|
||||
5. CRITICAL: Always proceed to Phase 2, never skip team workflow
|
||||
|
||||
## Phase 2: Create Team + Initialize Session
|
||||
|
||||
@@ -97,57 +85,46 @@ For callback/check/resume: load `commands/monitor.md` and execute the appropriat
|
||||
5. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
|
||||
6. Initialize meta.json with pipeline metadata:
|
||||
```typescript
|
||||
// Use team_msg to write pipeline metadata to .msg/meta.json
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: "<session-id>",
|
||||
from: "coordinator",
|
||||
type: "state_update",
|
||||
summary: "Session initialized",
|
||||
operation: "log", session_id: "<id>", from: "coordinator",
|
||||
type: "state_update", summary: "Session initialized",
|
||||
data: {
|
||||
pipeline_mode: "plan-execute",
|
||||
pipeline_stages: ["planner", "executor"],
|
||||
roles: ["coordinator", "planner", "executor"],
|
||||
team_name: "planex",
|
||||
input_type: "<issues|text|plan>",
|
||||
execution_method: "<agent|codex|gemini>"
|
||||
execution_method: "<codex|gemini>"
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Create Task Chain
|
||||
|
||||
Delegate to `commands/dispatch.md`:
|
||||
|
||||
1. Read `roles/coordinator/commands/dispatch.md`
|
||||
2. Execute its workflow to create PLAN-001 task
|
||||
3. PLAN-001 contains input info + execution method in description
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Spawn-and-Stop
|
||||
|
||||
1. Load `commands/monitor.md`
|
||||
2. Execute `handleSpawnNext` to find ready tasks and spawn planner worker
|
||||
3. Output status summary
|
||||
4. **STOP** (idle, wait for worker callback)
|
||||
4. STOP (idle, wait for worker callback)
|
||||
|
||||
**ONE_STEP_PER_INVOCATION**: true — coordinator does one operation per wake-up, then STOPS.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Report + Completion Action
|
||||
|
||||
When all tasks are complete (monitor.md detects PIPELINE_COMPLETE):
|
||||
|
||||
1. Load session state -> count completed tasks, duration
|
||||
2. List deliverables with output paths
|
||||
3. Update session status -> "completed"
|
||||
4. Execute Completion Action (see SKILL.md)
|
||||
|
||||
---
|
||||
4. Execute Completion Action per session.completion_action:
|
||||
- interactive -> AskUserQuestion (Archive/Keep/Export)
|
||||
- auto_archive -> Archive & Clean (status=completed, TeamDelete)
|
||||
- auto_keep -> Keep Active (status=paused)
|
||||
- auto_yes -> Archive & Clean without prompting
|
||||
|
||||
## Error Handling
|
||||
|
||||
|
||||
91
.claude/skills/team-planex/roles/executor/role.md
Normal file
91
.claude/skills/team-planex/roles/executor/role.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
role: executor
|
||||
prefix: EXEC
|
||||
inner_loop: true
|
||||
message_types:
|
||||
success: impl_complete
|
||||
error: impl_failed
|
||||
---
|
||||
|
||||
# Executor
|
||||
|
||||
Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Codex/Gemini), verifies with tests, commits, and reports completion.
|
||||
|
||||
## Phase 2: Task & Solution Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Issue ID | Task description `Issue ID:` field | Yes |
|
||||
| Solution file | Task description `Solution file:` field | Yes |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Execution method | Task description `Execution method:` field | Yes |
|
||||
| Wisdom | `<session>/wisdom/` | No |
|
||||
|
||||
1. Extract issue ID, solution file path, session folder, execution method
|
||||
2. Load solution JSON from file (file-first)
|
||||
3. If file not found -> fallback: `ccw issue solution <issueId> --json`
|
||||
4. Load wisdom files for conventions and patterns
|
||||
5. Verify solution has required fields: title, tasks
|
||||
|
||||
## Phase 3: Implementation
|
||||
|
||||
### Backend Selection
|
||||
|
||||
| Method | Backend | CLI Tool |
|
||||
|--------|---------|----------|
|
||||
| `codex` | `ccw cli --tool codex --mode write` | Background CLI |
|
||||
| `gemini` | `ccw cli --tool gemini --mode write` | Background CLI |
|
||||
|
||||
### CLI Backend (Codex/Gemini)
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
|
||||
TASK: <solution.tasks as bullet points>
|
||||
MODE: write
|
||||
CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/
|
||||
EXPECTED: Working implementation with: code changes, test updates, no syntax errors
|
||||
CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
|
||||
Issue: <issueId>
|
||||
Title: <solution.title>
|
||||
Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature
|
||||
```
|
||||
|
||||
Wait for CLI completion before proceeding to verification.
|
||||
|
||||
## Phase 4: Verification + Commit
|
||||
|
||||
### Test Verification
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| Tests | Detect and run project test command | All pass |
|
||||
| Syntax | IDE diagnostics or `tsc --noEmit` | No errors |
|
||||
|
||||
If tests fail: retry implementation once, then report `impl_failed`.
|
||||
|
||||
### Commit
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "feat(<issueId>): <solution.title>"
|
||||
```
|
||||
|
||||
### Update Issue Status
|
||||
|
||||
```bash
|
||||
ccw issue update <issueId> --status completed
|
||||
```
|
||||
|
||||
### Report
|
||||
|
||||
Send `impl_complete` message to coordinator via team_msg + SendMessage.
|
||||
|
||||
## Boundaries
|
||||
|
||||
| Allowed | Prohibited |
|
||||
|---------|-----------|
|
||||
| Load solution from file | Create or modify issues |
|
||||
| Implement via CLI tools (Codex/Gemini) | Modify solution artifacts |
|
||||
| Run tests | Spawn additional agents (use CLI tools instead) |
|
||||
| git commit | Direct user interaction |
|
||||
| Update issue status | Create tasks for other roles |
|
||||
111
.claude/skills/team-planex/roles/planner/role.md
Normal file
111
.claude/skills/team-planex/roles/planner/role.md
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
role: planner
|
||||
prefix: PLAN
|
||||
inner_loop: true
|
||||
message_types:
|
||||
success: issue_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# Planner
|
||||
|
||||
Requirement decomposition -> issue creation -> solution design -> EXEC-* task creation. Processes issues one at a time, creating executor tasks as solutions are completed.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Input type + raw input | Task description | Yes |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Execution method | Task description `Execution method:` field | Yes |
|
||||
| Wisdom | `<session>/wisdom/` | No |
|
||||
|
||||
1. Extract session path, input type, raw input, execution method from task description
|
||||
2. Load wisdom files if available
|
||||
3. Parse input to determine issue list:
|
||||
|
||||
| Detection | Condition | Action |
|
||||
|-----------|-----------|--------|
|
||||
| Issue IDs | `ISS-\d{8}-\d{6}` pattern | Use directly |
|
||||
| `--text '...'` | Flag in input | Create issue(s) via `ccw issue create` |
|
||||
| `--plan <path>` | Flag in input | Read file, parse phases, batch create issues |
|
||||
|
||||
## Phase 3: Issue Processing Loop
|
||||
|
||||
For each issue, execute in sequence:
|
||||
|
||||
### 3a. Generate Solution
|
||||
|
||||
Use CLI tool for issue planning:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Generate implementation solution for issue <issueId>; success = actionable task breakdown with file paths
|
||||
TASK: • Load issue details • Analyze requirements • Design solution approach • Break down into implementation tasks • Identify files to modify/create
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Memory: Session context from <session>/wisdom/
|
||||
EXPECTED: JSON solution with: title, description, tasks array (each with description, files_touched), estimated_complexity
|
||||
CONSTRAINTS: Follow project patterns | Reference existing implementations
|
||||
" --tool gemini --mode analysis --rule planning-breakdown-task-steps
|
||||
```
|
||||
|
||||
Parse CLI output to extract solution JSON. If CLI fails, fallback to `ccw issue solution <issueId> --json`.
|
||||
|
||||
### 3b. Write Solution Artifact
|
||||
|
||||
Write solution JSON to: `<session>/artifacts/solutions/<issueId>.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "<session-id>",
|
||||
"issue_id": "<issueId>",
|
||||
"solution": "<solution-from-agent>",
|
||||
"planned_at": "<ISO timestamp>"
|
||||
}
|
||||
```
|
||||
|
||||
### 3c. Check Conflicts
|
||||
|
||||
Extract `files_touched` from solution. Compare against prior solutions in session.
|
||||
Overlapping files -> log warning to `wisdom/issues.md`, continue.
|
||||
|
||||
### 3d. Create EXEC-* Task
|
||||
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "EXEC-00N: Implement <issue-title>",
|
||||
description: `Implement solution for issue <issueId>.
|
||||
|
||||
Issue ID: <issueId>
|
||||
Solution file: <session>/artifacts/solutions/<issueId>.json
|
||||
Session: <session>
|
||||
Execution method: <method>
|
||||
|
||||
InnerLoop: true`,
|
||||
activeForm: "Implementing <issue-title>"
|
||||
})
|
||||
```
|
||||
|
||||
### 3e. Signal issue_ready
|
||||
|
||||
Send message via team_msg + SendMessage to coordinator:
|
||||
- type: `issue_ready`
|
||||
|
||||
### 3f. Continue Loop
|
||||
|
||||
Process next issue. Do NOT wait for executor.
|
||||
|
||||
## Phase 4: Completion Signal
|
||||
|
||||
After all issues processed:
|
||||
1. Send `all_planned` message to coordinator via team_msg + SendMessage
|
||||
2. Summary: total issues planned, EXEC-* tasks created
|
||||
|
||||
## Boundaries
|
||||
|
||||
| Allowed | Prohibited |
|
||||
|---------|-----------|
|
||||
| Parse input, create issues | Write/modify business code |
|
||||
| Generate solutions (CLI) | Run tests |
|
||||
| Write solution artifacts | git commit |
|
||||
| Create EXEC-* tasks | Call code-developer |
|
||||
| Conflict checking | Direct user interaction |
|
||||
Reference in New Issue
Block a user