claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-planex/instructions/agent-instruction.md

@@ -1,301 +0,0 @@
-# Team PlanEx — Agent Instruction
-
-This instruction is loaded by team-worker agents when spawned with `role: planner` or `role: executor`.
-
----
-
-## Role-Based Execution
-
-### Planner Role
-
-**Responsibility**: Explore codebase, generate implementation solution for issue.
-
-**Input**:
-- `issue_ids`: Array of issue IDs to plan (from spawn message or send_input)
-- `session`: Session directory path
-- `session_id`: Session identifier
-
-**Execution Protocol**:
-
-1. **Read issue details**:
-   ```bash
-   ccw issue status {issue_id} --json
-   ```
-
-2. **Explore codebase** (use CLI analysis tools):
-   ```bash
-   ccw cli -p "PURPOSE: Explore codebase for {issue_title}
-   TASK: • Identify relevant files • Find existing patterns • Locate integration points
-   CONTEXT: @**/* | Memory: Issue {issue_id}
-   EXPECTED: Exploration findings with file paths and patterns
-   CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis --rule analysis-trace-code-execution
-   ```
-
-3. **Generate solution**:
-   - Break down into 2-7 implementation tasks
-   - Define task dependencies (topological order)
-   - Specify files to modify per task
-   - Define convergence criteria per task
-   - Assess complexity: Low (1-2 files), Medium (3-5 files), High (6+ files)
-
-4. **Write solution file**:
-   ```javascript
-   Write(`{session}/artifacts/solutions/{issue_id}.json`, JSON.stringify({
-     issue_id: "{issue_id}",
-     title: "{issue_title}",
-     approach: "Strategy pattern with...",
-     complexity: "Medium",
-     tasks: [
-       {
-         task_id: "EXEC-001",
-         title: "Create interface",
-         description: "Define provider interface...",
-         files: ["src/auth/providers/oauth-provider.ts"],
-         depends_on: [],
-         convergence_criteria: ["Interface compiles", "Types exported"]
-       }
-     ],
-     exploration_findings: {
-       existing_patterns: ["Strategy pattern in payment module"],
-       tech_stack: ["TypeScript", "Express"],
-       integration_points: ["User service"]
-     }
-   }, null, 2))
-   ```
-
-5. **Write ready marker**:
-   ```javascript
-   Write(`{session}/artifacts/solutions/{issue_id}.ready`, JSON.stringify({
-     issue_id: "{issue_id}",
-     task_count: tasks.length,
-     file_count: uniqueFiles.length
-   }))
-   ```
-
-6. **Report to coordinator** (via team_msg):
-   ```javascript
-   mcp__ccw-tools__team_msg({
-     operation: "log",
-     session_id: "{session_id}",
-     from: "planner",
-     to: "coordinator",
-     type: "plan_ready",
-     summary: "Planning complete for {issue_id}",
-     data: {
-       issue_id: "{issue_id}",
-       solution_path: "artifacts/solutions/{issue_id}.json",
-       task_count: tasks.length
-     }
-   })
-   ```
-
-7. **Wait for next issue** (multi-issue mode):
-   - After completing one issue, output results and wait
-   - Coordinator will send next issue via send_input
-   - Repeat steps 1-6 for each issue
-
-**Success Criteria**:
-- Solution file written with valid JSON
-- Ready marker created
-- Message sent to coordinator
-- All tasks have valid dependencies (no cycles)
-
----
-
-### Executor Role
-
-**Responsibility**: Execute implementation tasks from planner solution.
-
-**Input**:
-- `issue_id`: Issue to implement
-- `session`: Session directory path
-- `session_id`: Session identifier
-- `execution_method`: `codex` or `gemini` (from coordinator)
-- `inner_loop`: `true` (executor uses inner loop for self-repair)
-
-**Execution Protocol**:
-
-1. **Read solution file**:
-   ```javascript
-   const solution = JSON.parse(Read(`{session}/artifacts/solutions/{issue_id}.json`))
-   ```
-
-2. **For each task in solution.tasks** (ordered by depends_on):
-
-   a. **Report start**:
-   ```javascript
-   mcp__ccw-tools__team_msg({
-     operation: "log",
-     session_id: "{session_id}",
-     from: "executor",
-     to: "coordinator",
-     type: "impl_start",
-     summary: "Starting {task_id}",
-     data: { task_id: "{task_id}", issue_id: "{issue_id}" }
-   })
-   ```
-
-   b. **Read context files**:
-   ```javascript
-   for (const file of task.files) {
-     Read(file)  // Load existing code
-   }
-   ```
-
-   c. **Identify patterns**:
-   - Note imports, naming conventions, existing structure
-   - Follow project patterns from exploration_findings
-
-   d. **Apply changes**:
-   - Use Edit for existing files (prefer)
-   - Use Write for new files
-   - Follow convergence criteria from task
-
-   e. **Build check** (if build command exists):
-   ```bash
-   npm run build 2>&1 || echo BUILD_FAILED
-   ```
-   - If build fails: analyze error → fix → rebuild (max 3 retries)
-
-   f. **Verify convergence**:
-   - Check each criterion in task.convergence_criteria
-   - If not met: self-repair loop (max 3 iterations)
-
-   g. **Report progress**:
-   ```javascript
-   mcp__ccw-tools__team_msg({
-     operation: "log",
-     session_id: "{session_id}",
-     from: "executor",
-     to: "coordinator",
-     type: "impl_progress",
-     summary: "Completed {task_id}",
-     data: { task_id: "{task_id}", progress_pct: (taskIndex / totalTasks) * 100 }
-   })
-   ```
-
-3. **Run tests** (after all tasks complete):
-   ```bash
-   npm test 2>&1
-   ```
-   - If tests fail: self-repair loop (max 3 retries)
-   - Target: 95% pass rate
-
-4. **Git commit**:
-   ```bash
-   git add -A
-   git commit -m "feat({issue_id}): {solution.title}"
-   ```
-
-5. **Report completion**:
-   ```javascript
-   mcp__ccw-tools__team_msg({
-     operation: "log",
-     session_id: "{session_id}",
-     from: "executor",
-     to: "coordinator",
-     type: "impl_complete",
-     summary: "Completed {issue_id}",
-     data: {
-       task_id: "{task_id}",
-       issue_id: "{issue_id}",
-       files_modified: modifiedFiles,
-       commit_hash: commitHash
-     }
-   })
-   ```
-
-6. **Update issue status**:
-   ```bash
-   ccw issue update {issue_id} --status completed
-   ```
-
-**Success Criteria**:
-- All tasks completed in dependency order
-- Build passes (if build command exists)
-- Tests pass (95% target)
-- Git commit created
-- Issue status updated to completed
-
----
-
-## Inner Loop Protocol
-
-Both roles support inner loop for self-repair:
-
-| Scenario | Max Iterations | Action |
-|----------|---------------|--------|
-| Build failure | 3 | Analyze error → fix source → rebuild |
-| Test failure | 3 | Analyze failure → fix source → re-run tests |
-| Convergence not met | 3 | Check criteria → adjust implementation → re-verify |
-
-After 3 failed iterations: report error to coordinator, mark task as failed.
-
----
-
-## CLI Tool Usage
-
-### Analysis (Planner)
-
-```bash
-ccw cli -p "PURPOSE: {goal}
-TASK: • {step1} • {step2}
-CONTEXT: @**/* | Memory: {context}
-EXPECTED: {deliverable}
-CONSTRAINTS: Read-only" --tool gemini --mode analysis --rule {template}
-```
-
-### Implementation (Executor, optional)
-
-```bash
-ccw cli -p "PURPOSE: {goal}
-TASK: • {step1} • {step2}
-CONTEXT: @{files} | Memory: {context}
-EXPECTED: {deliverable}
-CONSTRAINTS: {constraints}" --tool {execution_method} --mode write --rule development-implement-feature
-```
-
-Use CLI tools when:
-- Planner: Always use for codebase exploration
-- Executor: Use for complex tasks (High complexity), direct implementation for Low/Medium
-
----
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Solution file not found | Report error to coordinator, skip issue |
-| Solution JSON corrupt | Report error, skip issue |
-| Build fails after 3 retries | Mark task failed, report to coordinator |
-| Tests fail after 3 retries | Mark task failed, report to coordinator |
-| Git commit fails | Warn, mark completed anyway |
-| CLI tool timeout | Fallback to direct implementation |
-| Dependency task failed | Skip dependent tasks, report to coordinator |
-
----
-
-## Wisdom Directory
-
-Record learnings in `{session}/wisdom/`:
-
-| File | Content |
-|------|---------|
-| `learnings.md` | Patterns discovered, gotchas, best practices |
-| `decisions.md` | Architecture decisions, trade-offs |
-| `conventions.md` | Code style, naming conventions |
-| `issues.md` | Issue-specific notes, blockers resolved |
-
-Append to these files during execution to share knowledge across issues.
-
----
-
-## Output Format
-
-No structured output required. Workers communicate via:
-- Solution files (planner)
-- Message bus (both roles)
-- Git commits (executor)
-- Wisdom files (both roles)
-
-Coordinator monitors message bus and meta.json for state tracking.

package/.codex/skills/team-planex/schemas/tasks-schema.md

@@ -1,198 +0,0 @@
-# Team PlanEx — Tasks Schema
-
-## Task Metadata Registry
-
-Team PlanEx uses a **message bus + state file** architecture instead of CSV. Tasks are tracked in `.msg/meta.json` with state updates via `team_msg`.
-
-### Task State Fields
-
-| Field | Type | Description | Example |
-|-------|------|-------------|---------|
-| `task_id` | string | Unique task identifier | `"PLAN-001"` |
-| `issue_id` | string | Source issue identifier | `"ISS-20260308-001"` |
-| `title` | string | Task title from solution | `"Implement OAuth2 provider"` |
-| `role` | enum | Worker role: `planner`, `executor` | `"executor"` |
-| `status` | enum | Task status: `pending`, `in_progress`, `completed`, `failed` | `"completed"` |
-| `assigned_to` | string | Worker agent name | `"executor"` |
-| `depends_on` | array | Dependency task IDs | `["PLAN-001"]` |
-| `files` | array | Files to modify | `["src/auth/oauth.ts"]` |
-| `convergence_criteria` | array | Success criteria | `["Tests pass", "No lint errors"]` |
-| `started_at` | string | ISO timestamp | `"2026-03-08T10:00:00+08:00"` |
-| `completed_at` | string | ISO timestamp | `"2026-03-08T10:15:00+08:00"` |
-| `error` | string | Error message if failed | `""` |
-
----
-
-## Message Bus Schema
-
-### Message Types
-
-| Type | From | To | Data Schema | Description |
-|------|------|----|-----------|----|
-| `plan_ready` | planner | coordinator | `{issue_id, solution_path, task_count}` | Planning complete |
-| `impl_start` | executor | coordinator | `{task_id, issue_id}` | Implementation started |
-| `impl_complete` | executor | coordinator | `{task_id, issue_id, files_modified[], commit_hash}` | Implementation complete |
-| `impl_progress` | executor | coordinator | `{task_id, progress_pct, current_step}` | Progress update |
-| `error` | any | coordinator | `{task_id, error_type, message}` | Error occurred |
-| `state_update` | any | coordinator | `{role, state: {}}` | Role state update (auto-synced to meta.json) |
-
-### Message Format (NDJSON)
-
-```jsonl
-{"id":"MSG-001","ts":"2026-03-08T10:00:00+08:00","from":"planner","to":"coordinator","type":"plan_ready","summary":"Planning complete for ISS-001","data":{"issue_id":"ISS-20260308-001","solution_path":"artifacts/solutions/ISS-20260308-001.json","task_count":3}}
-{"id":"MSG-002","ts":"2026-03-08T10:05:00+08:00","from":"executor","to":"coordinator","type":"impl_start","summary":"Starting EXEC-001","data":{"task_id":"EXEC-001","issue_id":"ISS-20260308-001"}}
-{"id":"MSG-003","ts":"2026-03-08T10:15:00+08:00","from":"executor","to":"coordinator","type":"impl_complete","summary":"Completed EXEC-001","data":{"task_id":"EXEC-001","issue_id":"ISS-20260308-001","files_modified":["src/auth/oauth.ts"],"commit_hash":"abc123"}}
-```
-
----
-
-## State File Schema (meta.json)
-
-### Structure
-
-```json
-{
-  "session_id": "PEX-auth-system-20260308",
-  "pipeline_mode": "plan-execute",
-  "execution_method": "codex",
-  "status": "running",
-  "started_at": "2026-03-08T10:00:00+08:00",
-  "issues": {
-    "ISS-20260308-001": {
-      "status": "completed",
-      "solution_path": "artifacts/solutions/ISS-20260308-001.json",
-      "tasks": ["EXEC-001", "EXEC-002"],
-      "completed_at": "2026-03-08T10:30:00+08:00"
-    }
-  },
-  "tasks": {
-    "EXEC-001": {
-      "task_id": "EXEC-001",
-      "issue_id": "ISS-20260308-001",
-      "title": "Implement OAuth2 provider",
-      "role": "executor",
-      "status": "completed",
-      "assigned_to": "executor",
-      "depends_on": [],
-      "files": ["src/auth/oauth.ts"],
-      "convergence_criteria": ["Tests pass", "No lint errors"],
-      "started_at": "2026-03-08T10:05:00+08:00",
-      "completed_at": "2026-03-08T10:15:00+08:00",
-      "error": ""
-    }
-  },
-  "roles": {
-    "coordinator": {
-      "status": "active",
-      "current_phase": "execution",
-      "last_update": "2026-03-08T10:15:00+08:00"
-    },
-    "planner": {
-      "status": "idle",
-      "issues_planned": 5,
-      "last_update": "2026-03-08T10:10:00+08:00"
-    },
-    "executor": {
-      "status": "active",
-      "current_task": "EXEC-002",
-      "tasks_completed": 1,
-      "last_update": "2026-03-08T10:15:00+08:00"
-    }
-  }
-}
-```
-
----
-
-## Solution File Schema
-
-Planner generates solution files in `artifacts/solutions/<issue-id>.json`:
-
-```json
-{
-  "issue_id": "ISS-20260308-001",
-  "title": "Implement OAuth2 authentication",
-  "approach": "Strategy pattern with provider abstraction",
-  "complexity": "Medium",
-  "tasks": [
-    {
-      "task_id": "EXEC-001",
-      "title": "Create OAuth2 provider interface",
-      "description": "Define provider interface with authorize/token/refresh methods",
-      "files": ["src/auth/providers/oauth-provider.ts"],
-      "depends_on": [],
-      "convergence_criteria": [
-        "Interface compiles without errors",
-        "Type definitions exported"
-      ]
-    },
-    {
-      "task_id": "EXEC-002",
-      "title": "Implement Google OAuth2 provider",
-      "description": "Concrete implementation for Google OAuth2",
-      "files": ["src/auth/providers/google-oauth.ts"],
-      "depends_on": ["EXEC-001"],
-      "convergence_criteria": [
-        "Tests pass",
-        "Handles token refresh",
-        "Error handling complete"
-      ]
-    }
-  ],
-  "exploration_findings": {
-    "existing_patterns": ["Strategy pattern in payment module"],
-    "tech_stack": ["TypeScript", "Express", "Passport.js"],
-    "integration_points": ["User service", "Session store"]
-  }
-}
-```
-
----
-
-## Execution Method Selection
-
-Coordinator selects execution method based on issue complexity:
-
-| Complexity | Method | Criteria |
-|------------|--------|----------|
-| Low | `gemini` | 1-2 files, simple logic, no architecture changes |
-| Medium | `codex` | 3-5 files, moderate complexity, existing patterns |
-| High | `codex` | 6+ files, complex logic, architecture changes |
-
-Stored in `meta.json` → `execution_method` field.
-
----
-
-## Validation Rules
-
-| Rule | Check | Error |
-|------|-------|-------|
-| Unique task IDs | No duplicate `task_id` in meta.json | "Duplicate task ID: {task_id}" |
-| Valid deps | All `depends_on` task IDs exist | "Unknown dependency: {dep_id}" |
-| No self-deps | Task cannot depend on itself | "Self-dependency: {task_id}" |
-| No circular deps | Dependency graph is acyclic | "Circular dependency detected" |
-| Valid status | status ∈ {pending, in_progress, completed, failed} | "Invalid status: {status}" |
-| Valid role | role ∈ {planner, executor} | "Invalid role: {role}" |
-| Issue exists | issue_id exists in issues registry | "Unknown issue: {issue_id}" |
-| Solution file exists | solution_path points to valid file | "Solution file not found: {path}" |
-
----
-
-## Cross-Role Context Flow
-
-| Source | Target | Mechanism |
-|--------|--------|-----------|
-| Planner solution | Executor | Read solution JSON from artifacts/solutions/ |
-| Executor progress | Coordinator | Message bus (impl_progress, impl_complete) |
-| Coordinator state | All workers | Read meta.json state field |
-| Any role state update | meta.json | Auto-sync via team_msg type="state_update" |
-
----
-
-## Discovery Types
-
-Team PlanEx does not use discoveries.ndjson. All context is stored in:
-- Solution files (planner output)
-- Message bus (real-time communication)
-- meta.json (persistent state)
-- wisdom/ directory (cross-task knowledge)