Claude-Code-Workflow/.codex/skills/team-issue/instructions/agent-instruction.md

Agent Instruction -- Team Issue Resolution

CSV agent instruction template for spawn_agents_on_csv. Each agent receives this template with its row's column values substituted via {column_name} placeholders.

---

TASK ASSIGNMENT

MANDATORY FIRST STEPS

1. Read shared discoveries: .workflow/.csv-wave/{session_id}/discoveries.ndjson (if exists, skip if not)
2. Read project context: .workflow/project-tech.json (if exists)
3. Read wisdom files: .workflow/.csv-wave/{session_id}/wisdom/ (conventions, learnings)

---

Your Task

Task ID: {id} Title: {title} Description: {description} Role: {role} Issue IDs: {issue_ids} Execution Method: {execution_method}

Previous Tasks' Findings (Context)

{prev_context}

---

Execution Protocol

Role Router

Determine your execution steps based on {role}:

Role	Execution Steps
explorer	Step A: Codebase Exploration
planner	Step B: Solution Design
integrator	Step C: Queue Formation
implementer	Step D: Implementation

---

Step A: Codebase Exploration (explorer role)

1. Extract issue ID from {issue_ids} (pattern: GH-\d+ or ISS-\d{8}-\d{6})
2. Load issue details: Bash("ccw issue status <issueId> --json")
3. Assess complexity from issue keywords:

Signal	Weight
Structural change (refactor, architect)	+2
Cross-cutting (multiple, across)	+2
Integration (api, database)	+1
High priority (>= 4)	+1

4. Explore codebase:

   • Use mcp__ace-tool__search_context for semantic search based on issue keywords
   • Read relevant files to understand context
   • Map dependencies and integration points
   • Check git log for related changes

5. Write context report:

   # Write to session explorations folder
   Write("<session>/explorations/context-<issueId>.json", JSON.stringify({
     issue_id: "<issueId>",
     issue: { id, title, priority, status, labels, feedback },
     relevant_files: [{ path, relevance }],
     dependencies: [],
     impact_scope: "low|medium|high",
     existing_patterns: [],
     related_changes: [],
     key_findings: [],
     complexity_assessment: "Low|Medium|High"
   }))
   

6. Share discoveries to board

---

Step B: Solution Design (planner role)

1. Extract issue ID from {issue_ids}
2. Load explorer context (if available): Read upstream artifact from prev_context
3. Check if this is a revision task (SOLVE-fix-*): If yes, read audit report for rejection feedback
4. Generate solution via CLI:

   ccw cli -p "PURPOSE: Design solution for issue <issueId> and decompose into implementation tasks; success = solution with task breakdown
   TASK: * Load issue details * Analyze explorer context * Design solution approach * Break into tasks * Generate solution JSON
   MODE: analysis
   CONTEXT: @**/* | Memory: Issue <issueId>, Explorer findings from prev_context
   EXPECTED: Solution JSON with: issue_id, solution_id, approach, tasks[], estimated_files, dependencies
   CONSTRAINTS: Follow existing patterns | Minimal changes
   " --tool gemini --mode analysis --rule planning-breakdown-task-steps
   

5. Write solution artifact:

   Write("<session>/solutions/solution-<issueId>.json", solutionJson)
   

6. Bind solution to issue: Bash("ccw issue bind <issueId> <solutionId>")

---

Step C: Queue Formation (integrator role)

1. Extract issue IDs from {issue_ids}
2. Verify all issues have bound solutions: Bash("ccw issue solutions <issueId> --json")
3. Analyze file conflicts between solutions
4. Build dependency graph for execution ordering
5. Determine parallel execution groups
6. Write execution queue:

   Write("<session>/queue/execution-queue.json", JSON.stringify({
     queue: [{ issue_id, solution_id, order, depends_on: [], estimated_files: [] }],
     conflicts: [{ issues: [], files: [], resolution: "" }],
     parallel_groups: [{ group: 0, issues: [] }]
   }))
   

---

Step D: Implementation (implementer role)

1. Extract issue ID from {issue_ids}
2. Load bound solution: Bash("ccw issue solutions <issueId> --json")
3. Load explorer context (from prev_context or file)
4. Determine execution backend from {execution_method}:

Method	CLI Command
codex	ccw cli --tool codex --mode write --id issue-<issueId>
gemini	ccw cli --tool gemini --mode write --id issue-<issueId>
qwen	ccw cli --tool qwen --mode write --id issue-<issueId>

5. Execute implementation:

   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: Solution plan, explorer context
   EXPECTED: Working implementation with code changes, test updates
   CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
   " --tool <execution_method> --mode write --rule development-implement-feature
   

6. Verify: Run tests, check for errors

7. Update issue status: Bash("ccw issue update <issueId> --status resolved")

---

Share Discoveries (ALL ROLES)

After completing your work, append findings to the shared discovery board:

echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> <session>/discoveries.ndjson

Discovery Types to Share:

Type	Data Schema	When to Use
file_found	{path, relevance, purpose}	Explorer: relevant file discovered
pattern_found	{pattern, location, description}	Explorer: code pattern identified
dependency_found	{from, to, type}	Explorer: module dependency found
solution_approach	{issue_id, approach, estimated_files}	Planner: solution strategy
conflict_found	{issues, files, resolution}	Integrator: file conflict
impl_result	{issue_id, files_changed, tests_pass}	Implementer: build outcome

---

Output (report_agent_job_result)

Return JSON:

{
  "id": "{id}",
  "status": "completed | failed",
  "findings": "Key discoveries and implementation notes (max 500 chars)",
  "artifact_path": "relative path to main artifact file (e.g., explorations/context-ISS-xxx.json)",
  "error": ""
}

---

Quality Checklist

Before reporting complete:

• Mandatory first steps completed (discoveries, project context, wisdom)
• Role-specific execution steps followed
• At least 1 discovery shared to board
• Artifact file written to session folder
• Findings include file:line references where applicable
• prev_context findings were incorporated