claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-planex/SKILL.md

@@ -1,504 +1,130 @@
 ---
 name: team-planex
-description: |
-  Plan-and-execute pipeline with inverted control. Accepts issues.jsonl or roadmap
-  session from roadmap-with-file. Delegates planning to issue-plan-agent (background),
-  executes inline (main flow). Interleaved plan-execute loop.
+description: Unified team skill for plan-and-execute pipeline. Pure router — coordinator always. Beat model is coordinator-only in monitor.md. Triggers on "team planex".
+allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ccw-tools__team_msg(*)
 ---
 
 # Team PlanEx
 
-接收 `issues.jsonl` 或 roadmap session 作为输入，委托规划 + 内联执行。Spawn issue-plan-agent 后台规划下一个 issue，主流程内联执行当前已规划的 issue。交替循环：规划 → 执行 → 规划下一个 → 执行 → 直到所有 issue 完成。
+Unified team skill: plan-and-execute pipeline for issue-based development. Built on **team-worker agent architecture** — coordinator orchestrates, workers are team-worker agents loading role-specific instructions from `roles/<role>/role.md`.
 
 ## Architecture
 
 ```
-┌────────────────────────────────────────────────────┐
-│  SKILL.md (主流程 = 内联执行 + 循环控制)             │
-│                                                     │
-│  Phase 1: 加载 issues.jsonl / roadmap session       │
-│  Phase 2: 规划-执行交替循环                          │
-│    ├── 取下一个未规划 issue → spawn planner (bg)     │
-│    ├── 取下一个已规划 issue → 内联执行               │
-│    │   ├── 内联实现 (Read/Edit/Write/Bash)           │
-│    │   ├── 验证测试 + 自修复 (max 3 retries)         │
-│    │   └── git commit                                │
-│    └── 循环直到所有 issue 规划+执行完毕               │
-│  Phase 3: 汇总报告                                   │
-└────────────────────────────────────────────────────┘
-
-Planner (single reusable agent, background):
-  issue-plan-agent spawn once → send_input per issue → write solution JSON → write .ready marker
-```
-
-## Beat Model (Interleaved Plan-Execute Loop)
-
-```
-Interleaved Loop (Phase 2, single planner reused via send_input):
-═══════════════════════════════════════════════════════════════
-Beat 1              Beat 2              Beat 3
-|                   |                   |
-spawn+plan(A)       send_input(C)       (drain)
-  ↓                   ↓                   ↓
-poll → A.ready      poll → B.ready      poll → C.ready
-  ↓                   ↓                   ↓
-exec(A)             exec(B)             exec(C)
-  ↓                   ↓                   ↓
-send_input(B)       send_input(done)    done
-  (eager delegate)    (all delegated)
-═══════════════════════════════════════════════════════════════
-
-Planner timeline (never idle between issues):
-─────────────────────────────────────────────────────────────
-Planner:  ├─plan(A)─┤├─plan(B)─┤├─plan(C)─┤ done
-Main:     2a(spawn) ├─exec(A)──┤├─exec(B)──┤├─exec(C)──┤
-                    ^2f→send(B) ^2f→send(C)
-─────────────────────────────────────────────────────────────
-
-Single Beat Detail:
-───────────────────────────────────────────────────────────────
-  1. Delegate next    2. Poll ready     3. Execute     4. Verify + commit
-     (2a or 2f eager)    solutions         inline         + eager delegate
-        |                   |                |              |
-  send_input(bg)     Glob(*.ready)    Read/Edit/Write   test → commit
-                          │                              → send_input(next)
-                    wait if none ready
-───────────────────────────────────────────────────────────────
-```
-
----
-
-## Agent Registry
-
-| Agent | Role File | Responsibility | Pattern |
-|-------|-----------|----------------|---------|
-| `issue-plan-agent` | `~/.codex/agents/issue-plan-agent.md` | Explore codebase + generate solutions, single instance reused via send_input | 2.3 Deep Interaction |
-
-> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs and agent instructions are reduced to summaries, **you MUST immediately `Read` the corresponding agent.md to reload before continuing execution**.
-
----
-
-## Subagent API Reference
-
-### spawn_agent
-
-```javascript
-const agentId = spawn_agent({
-  message: `
-## TASK ASSIGNMENT
-
-### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
-
----
-
-${taskContext}
-`
-})
-```
-
-### wait
-
-```javascript
-const result = wait({
-  ids: [agentId],
-  timeout_ms: 600000  // 10 minutes
-})
-```
-
-### send_input
-
-Continue interaction with active agent (reuse for next issue).
-
-```javascript
-send_input({
-  id: agentId,
-  message: `
-## NEXT ISSUE
-
-issue_ids: ["<nextIssueId>"]
-
-## Output Requirements
-1. Generate solution for this issue
-2. Write solution JSON to: <artifactsDir>/<nextIssueId>.json
-3. Write ready marker to: <artifactsDir>/<nextIssueId>.ready
-`
-})
-```
-
-### close_agent
-
-```javascript
-close_agent({ id: agentId })
-```
-
----
-
-## Input
-
-Accepts output from `roadmap-with-file` or direct `issues.jsonl` path.
-
-Supported input forms (parse from `$ARGUMENTS`):
-
-| Form | Detection | Example |
-|------|-----------|---------|
-| Roadmap session | `RMAP-` prefix or `--session` flag | `team-planex --session RMAP-auth-20260301` |
-| Issues JSONL path | `.jsonl` extension | `team-planex .workflow/issues/issues.jsonl` |
-| Issue IDs | `ISS-\d{8}-\d{3,6}` regex | `team-planex ISS-20260301-001 ISS-20260301-002` |
-
-### Input Resolution
-
-| Input Form | Resolution |
-|------------|------------|
-| `--session RMAP-*` | Read `.workflow/.roadmap/<sessionId>/roadmap.md` → extract issue IDs from Roadmap table → load issue data from `.workflow/issues/issues.jsonl` |
-| `.jsonl` path | Read file → parse each line as JSON → collect all issues |
-| Issue IDs | Use directly → fetch details via `ccw issue status <id> --json` |
-
-### Issue Record Fields Used
-
-| Field | Usage |
-|-------|-------|
-| `id` | Issue identifier for planning and execution |
-| `title` | Commit message and reporting |
-| `status` | Skip if already `completed` |
-| `tags` | Wave ordering: `wave-1` before `wave-2` |
-| `extended_context.notes.depends_on_issues` | Execution ordering |
-
-### Wave Ordering
-
-Issues are sorted by wave tag for execution order:
-
-| Priority | Rule |
-|----------|------|
-| 1 | Lower wave number first (`wave-1` before `wave-2`) |
-| 2 | Within same wave: issues without `depends_on_issues` first |
-| 3 | Within same wave + no deps: original order from JSONL |
-
----
-
-## Session Setup
-
-Initialize session directory before processing:
-
-| Item | Value |
-|------|-------|
-| Slug | `toSlug(<first issue title>)` truncated to 20 chars |
-| Date | `YYYYMMDD` format |
-| Session dir | `.workflow/.team/PEX-<slug>-<date>` |
-| Solutions dir | `<sessionDir>/artifacts/solutions` |
-
-Create directories:
-
-```bash
-mkdir -p "<sessionDir>/artifacts/solutions"
-```
-
-Write `<sessionDir>/team-session.json`:
-
-| Field | Value |
-|-------|-------|
-| `session_id` | `PEX-<slug>-<date>` |
-| `input_type` | `roadmap` / `jsonl` / `issue_ids` |
-| `source_session` | Roadmap session ID (if applicable) |
-| `issue_ids` | Array of all issue IDs to process (wave-sorted) |
-| `status` | `"running"` |
-| `started_at` | ISO timestamp |
-
----
-
-## Phase 1: Load Issues + Initialize
-
-1. Parse `$ARGUMENTS` to determine input form
-2. Resolve issues (see Input Resolution table)
-3. Filter out issues with `status: completed`
-4. Sort by wave ordering
-5. Collect into `<issueQueue>` (ordered list of issue IDs to process)
-6. Initialize session directory and `team-session.json`
-7. Set `<plannedSet>` = {} , `<executedSet>` = {} , `<plannerAgent>` = null (single reusable planner)
-
----
-
-## Phase 2: Plan-Execute Loop
-
-Interleaved loop that keeps planner agent busy at all times. Each beat: (1) delegate next issue to planner if idle, (2) poll for ready solutions, (3) execute inline, (4) after execution completes, immediately delegate next issue to planner before polling again.
-
-### Loop Entry
-
-Set `<queueIndex>` = 0 (pointer into `<issueQueue>`).
-
-### 2a. Delegate Next Issue to Planner
-
-Single planner agent is spawned once and reused via `send_input` for subsequent issues.
-
-| Condition | Action |
-|-----------|--------|
-| `<plannerAgent>` is null AND `<queueIndex>` < `<issueQueue>.length` | Spawn planner (first issue), advance `<queueIndex>` |
-| `<plannerAgent>` exists, idle AND `<queueIndex>` < `<issueQueue>.length` | `send_input` next issue, advance `<queueIndex>` |
-| `<plannerAgent>` is busy | Skip (wait for current planning to finish) |
-| `<queueIndex>` >= `<issueQueue>.length` | No more issues to plan |
-
-**First issue — spawn planner**:
-
-```javascript
-const plannerAgent = spawn_agent({
-  message: `
-## TASK ASSIGNMENT
-
-### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ~/.codex/agents/issue-plan-agent.md (MUST read first)
-2. Read: .workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
-
----
-
-issue_ids: ["<issueId>"]
-project_root: "<projectRoot>"
-
-## Output Requirements
-1. Generate solution for this issue
-2. Write solution JSON to: <artifactsDir>/<issueId>.json
-3. Write ready marker to: <artifactsDir>/<issueId>.ready
-   - Marker content: {"issue_id":"<issueId>","task_count":<task_count>,"file_count":<file_count>}
-
-## Multi-Issue Mode
-You will receive additional issues via follow-up messages. After completing each issue,
-output results and wait for next instruction.
-`
-})
-```
-
-**Subsequent issues — send_input**:
-
-```javascript
-send_input({
-  id: plannerAgent,
-  message: `
-## NEXT ISSUE
-
-issue_ids: ["<nextIssueId>"]
-
-## Output Requirements
-1. Generate solution for this issue
-2. Write solution JSON to: <artifactsDir>/<nextIssueId>.json
-3. Write ready marker to: <artifactsDir>/<nextIssueId>.ready
-   - Marker content: {"issue_id":"<nextIssueId>","task_count":<task_count>,"file_count":<file_count>}
-`
+Skill(skill="team-planex", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze -> dispatch -> spawn workers -> STOP
+                                    |
+                    +---------------+---------------+
+                    v                               v
+               [planner]                       [executor]
+         (team-worker agent,            (team-worker agent,
+          loads roles/planner/role.md)   loads roles/executor/role.md)
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | true |
+| executor | [roles/executor/role.md](roles/executor/role.md) | EXEC-* | true |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `PEX`
+- **Session path**: `.workflow/.team/PEX-<slug>-<date>/`
+- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+spawn_agent({
+  agent_type: "team_worker",
+  items: [
+    { type: "text", text: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+requirement: <task-description>
+inner_loop: <true|false>
+execution_method: <codex|gemini>
+
+Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
+
+    { type: "text", text: `## Task Context
+task_id: <task-id>
+title: <task-title>
+description: <task-description>
+pipeline_phase: <pipeline-phase>` },
+
+    { type: "text", text: `## Upstream Context
+<prev_context>` }
+  ]
 })
 ```
 
-Record `<planningIssueId>` = current issue ID.
-
-### 2b. Poll for Ready Solutions
-
-Poll `<artifactsDir>/*.ready` using Glob.
-
-| Condition | Action |
-|-----------|--------|
-| New `.ready` found (not in `<executedSet>`) | Load `<issueId>.json` solution → proceed to 2c |
-| `<plannerAgent>` busy, no `.ready` yet | Check planner: `wait({ ids: [<plannerAgent>], timeout_ms: 30000 })` |
-| Planner finished current issue | Mark planner idle, re-poll |
-| Planner timed out (30s wait) | Re-poll (planner still working) |
-| No `.ready`, planner idle, all issues delegated | Exit loop → Phase 3 |
-| Idle >5 minutes total | Exit loop → Phase 3 |
-
-### 2c. Inline Execution
-
-Main flow implements the solution directly. For each task in `solution.tasks`, ordered by `depends_on` sequence:
-
-| Step | Action | Tool |
-|------|--------|------|
-| 1. Read context | Read all files referenced in current task | Read |
-| 2. Identify patterns | Note imports, naming conventions, existing structure | — (inline reasoning) |
-| 3. Apply changes | Modify existing files or create new files | Edit (prefer) / Write (new files) |
-| 4. Build check | Run project build command if available | Bash |
-
-Build verification:
-
-```bash
-npm run build 2>&1 || echo BUILD_FAILED
-```
-
-| Build Result | Action |
-|--------------|--------|
-| Success | Proceed to 2d |
-| Failure | Analyze error → fix source → rebuild (max 3 retries) |
-| No build command | Skip, proceed to 2d |
-
-### 2d. Verify Tests
-
-Detect test command:
+After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
 
-| Priority | Detection |
-|----------|-----------|
-| 1 | `package.json` → `scripts.test` |
-| 2 | `package.json` → `scripts.test:unit` |
-| 3 | `pytest.ini` / `setup.cfg` (Python) |
-| 4 | `Makefile` test target |
-
-Run tests. If tests fail → self-repair loop:
-
-| Attempt | Action |
-|---------|--------|
-| 1–3 | Analyze test output → diagnose → fix source code → re-run tests |
-| After 3 | Mark issue as failed, log to `<sessionDir>/errors.json`, continue |
-
-### 2e. Git Commit
-
-Stage and commit changes for this issue:
-
-```bash
-git add -A
-git commit -m "feat(<issueId>): <solution-title>"
-```
+## User Commands
 
-| Outcome | Action |
+| Command | Action |
 |---------|--------|
-| Commit succeeds | Record commit hash |
-| Commit fails (nothing to commit) | Warn, continue |
-| Pre-commit hook fails | Attempt fix once, then warn and continue |
-
-### 2f. Update Status + Eagerly Delegate Next
-
-Update issue status:
-
-```bash
-ccw issue update <issueId> --status completed
-```
-
-Add `<issueId>` to `<executedSet>`.
-
-**Eager delegation**: Immediately check planner state and delegate next issue before returning to poll:
-
-| Planner State | Action |
-|---------------|--------|
-| Idle AND more issues in queue | `send_input` next issue → advance `<queueIndex>` |
-| Busy (still planning) | Skip — planner already working |
-| All issues delegated | Skip — nothing to delegate |
-
-This ensures planner is never idle between beats. Return to 2b for next beat.
-
----
-
-## Phase 3: Report
-
-### 3a. Cleanup
-
-Close the planner agent. Ignore cleanup failures.
-
-```javascript
-if (plannerAgent) {
-  try { close_agent({ id: plannerAgent }) } catch {}
-}
-```
-
-### 3b. Generate Report
-
-Update `<sessionDir>/team-session.json`:
-
-| Field | Value |
-|-------|-------|
-| `status` | `"completed"` |
-| `completed_at` | ISO timestamp |
-| `results.total` | Total issues in queue |
-| `results.completed` | Count in `<executedSet>` |
-| `results.failed` | Count of failed issues |
-
-Output summary:
-
-```
-## Pipeline Complete
-
-**Total issues**: <total>
-**Completed**: <completed>
-**Failed**: <failed>
-
-<per-issue status list>
-
-Session: <sessionDir>
-```
-
----
-
-## File-Based Coordination Protocol
-
-| File | Writer | Reader | Purpose |
-|------|--------|--------|---------|
-| `<artifactsDir>/<issueId>.json` | planner | main flow | Solution data |
-| `<artifactsDir>/<issueId>.ready` | planner | main flow | Atomicity signal |
-
-### Ready Marker Format
-
-```json
-{
-  "issue_id": "<issueId>",
-  "task_count": "<task_count>",
-  "file_count": "<file_count>"
-}
-```
-
----
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+| `add <issue-ids or --text '...' or --plan path>` | Append new tasks to planner queue |
 
 ## Session Directory
 
 ```
-.workflow/.team/PEX-<slug>-<date>/
-├── team-session.json
+.workflow/.team/PEX-<slug>-<YYYY-MM-DD>/
+├── .msg/
+│   ├── messages.jsonl          # Message bus log
+│   └── meta.json               # Session state
+├── task-analysis.json          # Coordinator analyze output
 ├── artifacts/
-│   └── solutions/
-│       ├── <issueId>.json
-│       └── <issueId>.ready
-└── errors.json
+│   └── solutions/              # Planner solution output per issue
+│       ├── <issueId-1>.json
+│       └── <issueId-N>.json
+└── wisdom/                     # Cross-task knowledge
+    ├── learnings.md
+    ├── decisions.md
+    ├── conventions.md
+    └── issues.md
 ```
 
----
-
-## Lifecycle Management
-
-### Timeout Protocol
-
-| Phase | Default Timeout | On Timeout |
-|-------|-----------------|------------|
-| Phase 1 (Load) | 60s | Report error, stop |
-| Phase 2 (Planner wait) | 600s per issue | Skip issue, write `.error` marker |
-| Phase 2 (Execution) | No timeout | Self-repair up to 3 retries |
-| Phase 2 (Loop idle) | 5 min total idle | Break loop → Phase 3 |
-
-### Cleanup Protocol
-
-At workflow end, close the planner agent:
-
-```javascript
-if (plannerAgent) {
-  try { close_agent({ id: plannerAgent }) } catch { /* already closed */ }
-}
-```
+## Specs Reference
 
----
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions, task metadata registry, execution method selection
 
 ## Error Handling
 
-| Phase | Scenario | Resolution |
-|-------|----------|------------|
-| 1 | Invalid input (no issues, bad JSONL) | Report error, stop |
-| 1 | Roadmap session not found | Report error, stop |
-| 1 | Issue fetch fails | Retry once, then skip issue |
-| 2 | Planner spawn fails | Retry once, then skip issue |
-| 2 | issue-plan-agent timeout (>10 min) | Skip issue, write `.error` marker, continue |
-| 2 | Solution file corrupt / unreadable | Skip, log to `errors.json`, continue |
-| 2 | Implementation error | Self-repair up to 3 retries per task |
-| 2 | Tests failing after 3 retries | Mark issue failed, log, continue |
-| 2 | Git commit fails | Warn, mark completed anyway |
-| 2 | Polling idle >5 minutes | Break loop → Phase 3 |
-| 3 | Agent cleanup fails | Ignore |
-
----
-
-## User Commands
-
-| Command | Action |
-|---------|--------|
-| `check` / `status` | Show progress: planned / executing / completed / failed counts |
-| `resume` / `continue` | Re-enter loop from Phase 2 |
-
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Role spec file not found | Error with expected path (roles/<name>/role.md) |
+| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
+| Planner issue planning failure | Retry once, then skip to next issue |
+| Executor impl failure | Report to coordinator, continue with next EXEC-* task |
+| Pipeline stall | Coordinator monitors, escalate to user |
+| Worker no response | Report waiting task, suggest user `resume` |

package/.codex/skills/team-planex/roles/coordinator/commands/analyze.md

@@ -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) | request_user_input -> 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 }
+  ]
+}
+```