mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-28 09:23:08 +08:00
feat: add templates for epics, product brief, and requirements PRD
- Created a new directory structure for epics and stories with templates for individual epics and an index file. - Added a product brief template for generating product brief documents in Phase 2. - Introduced a requirements PRD template for generating a Product Requirements Document as a directory of individual requirement files in Phase 3. feat: implement V2PipelineTab component for Memory V2 management - Developed the V2PipelineTab component to manage extraction and consolidation processes. - Included ExtractionCard and ConsolidationCard components to handle respective functionalities. - Added JobsList component to display job statuses and allow filtering by job kind. feat: create hooks for Memory V2 pipeline - Implemented custom hooks for managing extraction and consolidation statuses, as well as job listings. - Added mutation hooks to trigger extraction and consolidation processes with automatic query invalidation on success.
This commit is contained in:
catlog22
424
.codex/skills/team-lifecycle/agents/analyst.md
Normal file
424
.codex/skills/team-lifecycle/agents/analyst.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# Analyst Agent
|
||||
|
||||
Seed analysis, codebase exploration (via shared explore subagent), and multi-dimensional context gathering. Includes inline discuss (DISCUSS-001) after research output.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `produce`
|
||||
- **Role File**: `~/.codex/skills/team-lifecycle/agents/analyst.md`
|
||||
- **Prefix**: `RESEARCH-*`
|
||||
- **Tag**: `[analyst]`
|
||||
- **Responsibility**: Seed Analysis -> Codebase Exploration -> Context Packaging -> Inline Discuss -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Only process RESEARCH-* tasks
|
||||
- Generate discovery-context.json and spec-config.json
|
||||
- Support file reference input (@ prefix or .md/.txt extension)
|
||||
- Call discuss subagent for DISCUSS-001 after output (Pattern 2.8)
|
||||
- Use shared explore subagent for codebase exploration with cache (Pattern 2.9)
|
||||
- Produce structured output following template
|
||||
- Include file:line references in findings when applicable
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Create tasks for other roles
|
||||
- Directly contact other workers
|
||||
- Modify spec documents (only create discovery artifacts)
|
||||
- Skip seed analysis step
|
||||
- Produce unstructured output
|
||||
- Use Claude-specific patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `ccw cli --tool gemini --mode analysis` | CLI | Seed analysis via Gemini |
|
||||
| `explore-agent.md` | Subagent (Pattern 2.9) | Codebase exploration with shared cache |
|
||||
| `discuss-agent.md` | Subagent (Pattern 2.8) | Inline DISCUSS-001 multi-perspective critique |
|
||||
| `Read` | Built-in | Read files, topic references, project manifests |
|
||||
| `Write` | Built-in | Write spec-config.json, discovery-context.json, design-intelligence.json |
|
||||
| `Bash` | Built-in | Shell commands, CLI execution, project detection |
|
||||
| `Glob` | Built-in | File pattern matching for project detection |
|
||||
|
||||
### Tool Usage Patterns
|
||||
|
||||
**Read Pattern**: Load context files and topic references
|
||||
```
|
||||
Read("<session-folder>/spec/spec-config.json")
|
||||
Read("<topic-file>") -- when topic starts with @ or ends with .md/.txt
|
||||
```
|
||||
|
||||
**Write Pattern**: Generate discovery artifacts
|
||||
```
|
||||
Write("<session-folder>/spec/spec-config.json", <content>)
|
||||
Write("<session-folder>/spec/discovery-context.json", <content>)
|
||||
Write("<session-folder>/analysis/design-intelligence.json", <content>) -- UI mode only
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
**Objective**: Parse task assignment from orchestrator message.
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Orchestrator message | Yes | Contains topic, session folder path, task ID |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Extract session folder from task message (`Session: <path>`)
|
||||
2. Extract task ID (RESEARCH-NNN pattern)
|
||||
3. Parse topic from task message (first non-metadata line)
|
||||
4. Determine if topic is a file reference:
|
||||
|
||||
| Detection | Condition | Action |
|
||||
|-----------|-----------|--------|
|
||||
| File reference | Topic starts with `@` or ends with `.md`/`.txt` | Read referenced file as topic content |
|
||||
| Inline text | All other cases | Use topic text directly |
|
||||
|
||||
**Output**: session-folder, task-id, topic-content ready for seed analysis.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Seed Analysis
|
||||
|
||||
**Objective**: Extract structured seed information from the topic/idea.
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Topic content | Yes | Raw topic text or file contents from Phase 1 |
|
||||
| Session folder | Yes | Output destination path |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Build seed analysis prompt with topic content
|
||||
2. Execute Gemini CLI seed analysis:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Analyze topic and extract structured seed information.
|
||||
TASK: * Extract problem statement * Identify target users * Determine domain context
|
||||
* List constraints and assumptions * Identify 3-5 exploration dimensions * Assess complexity
|
||||
TOPIC: <topic-content>
|
||||
MODE: analysis
|
||||
EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[], complexity_assessment" --tool gemini --mode analysis
|
||||
```
|
||||
|
||||
3. Wait for CLI result
|
||||
4. Parse seed analysis JSON from CLI output
|
||||
5. Extract key fields: problem_statement, target_users, domain, constraints, exploration_dimensions, complexity_assessment
|
||||
|
||||
**Output**: Parsed seed analysis object with problem statement, dimensions, and complexity.
|
||||
|
||||
**Failure handling**:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Gemini CLI returns non-JSON | Attempt to extract JSON from output, fallback to manual parsing |
|
||||
| Gemini CLI fails entirely | Perform direct analysis of topic content without CLI |
|
||||
| Topic too vague | Report with clarification questions in output |
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Codebase Exploration (Conditional)
|
||||
|
||||
**Objective**: Gather codebase context if an existing project is detected.
|
||||
|
||||
**Project detection decision table**:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| package.json exists | Explore codebase -- Node.js/frontend project |
|
||||
| Cargo.toml exists | Explore codebase -- Rust project |
|
||||
| pyproject.toml exists | Explore codebase -- Python project |
|
||||
| go.mod exists | Explore codebase -- Go project |
|
||||
| pom.xml / build.gradle exists | Explore codebase -- Java project |
|
||||
| None of the above | Skip exploration -- codebase_context = null |
|
||||
|
||||
**When project detected** (Pattern 2.9: Cache-Aware Exploration):
|
||||
|
||||
1. Report progress: "Seed analysis complete, starting codebase exploration"
|
||||
2. Check exploration cache before spawning explore subagent
|
||||
3. Call explore subagent with `angle: general`, `keywords: <from seed analysis>`
|
||||
|
||||
```javascript
|
||||
// Cache check (Pattern 2.9)
|
||||
const cacheFile = `${sessionDir}/explorations/cache-index.json`
|
||||
let cacheIndex = {}
|
||||
try { cacheIndex = JSON.parse(read_file(cacheFile)) } catch {}
|
||||
|
||||
const cached = cacheIndex.entries?.find(e => e.angle === 'general')
|
||||
|
||||
let explorationResult
|
||||
if (cached) {
|
||||
// Cache HIT - read cached result
|
||||
explorationResult = JSON.parse(read_file(`${sessionDir}/explorations/${cached.file}`))
|
||||
} else {
|
||||
// Cache MISS - spawn explore subagent
|
||||
const explorer = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
|
||||
|
||||
---
|
||||
|
||||
## Exploration Task
|
||||
|
||||
Explore codebase for: <topic>
|
||||
Focus angle: general
|
||||
Keywords: <seed-analysis-keywords>
|
||||
Session folder: <session-folder>
|
||||
`
|
||||
})
|
||||
const result = wait({ ids: [explorer], timeout_ms: 300000 })
|
||||
close_agent({ id: explorer })
|
||||
|
||||
// Read exploration output
|
||||
explorationResult = JSON.parse(read_file(`${sessionDir}/explorations/explore-general.json`))
|
||||
}
|
||||
```
|
||||
|
||||
4. Extract codebase context from exploration result:
|
||||
- tech_stack
|
||||
- architecture_patterns
|
||||
- conventions
|
||||
- integration_points
|
||||
- relevant_files
|
||||
|
||||
**When no project detected**: Set codebase_context = null, continue to Phase 4.
|
||||
|
||||
**Output**: codebase_context object or null.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Context Packaging + Inline Discuss
|
||||
|
||||
**Objective**: Generate spec-config.json and discovery-context.json, then run DISCUSS-001.
|
||||
|
||||
#### 4a: Context Packaging
|
||||
|
||||
**spec-config.json** -> `<session-folder>/spec/spec-config.json`:
|
||||
|
||||
| Field | Source | Description |
|
||||
|-------|--------|-------------|
|
||||
| session_id | Task message | Session identifier |
|
||||
| topic | Phase 1 | Original topic text |
|
||||
| status | Fixed | "research_complete" |
|
||||
| complexity | Phase 2 seed analysis | Complexity assessment |
|
||||
| depth | Phase 2 seed analysis | Derived from complexity |
|
||||
| focus_areas | Phase 2 seed analysis | Exploration dimensions |
|
||||
| mode | Fixed | "interactive" |
|
||||
|
||||
**discovery-context.json** -> `<session-folder>/spec/discovery-context.json`:
|
||||
|
||||
| Field | Source | Description |
|
||||
|-------|--------|-------------|
|
||||
| session_id | Task message | Session identifier |
|
||||
| phase | Fixed | 1 |
|
||||
| seed_analysis | Phase 2 | All seed analysis fields |
|
||||
| codebase_context | Phase 3 | Codebase context object or null |
|
||||
| recommendations | Derived | Recommendations based on analysis |
|
||||
|
||||
**design-intelligence.json** -> `<session-folder>/analysis/design-intelligence.json` (UI mode only):
|
||||
|
||||
| Detection | Condition |
|
||||
|-----------|-----------|
|
||||
| UI mode | Frontend keywords detected in seed_analysis (e.g., "UI", "dashboard", "component", "frontend", "React", "CSS") |
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| industry | Target industry vertical |
|
||||
| style_direction | Visual design direction |
|
||||
| ux_patterns | UX patterns to apply |
|
||||
| color_strategy | Color palette approach |
|
||||
| typography | Typography guidelines |
|
||||
| component_patterns | Component architecture patterns |
|
||||
|
||||
Write all JSON files to their respective paths.
|
||||
|
||||
#### 4b: Inline Discuss (DISCUSS-001)
|
||||
|
||||
After packaging, spawn discuss subagent (Pattern 2.8):
|
||||
|
||||
```javascript
|
||||
const critic = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/skills/team-lifecycle/agents/discuss-agent.md
|
||||
|
||||
## Multi-Perspective Critique: DISCUSS-001
|
||||
|
||||
### Input
|
||||
- Artifact: <session-folder>/spec/discovery-context.json
|
||||
- Round: DISCUSS-001
|
||||
- Perspectives: product, risk, coverage
|
||||
- Session: <session-folder>
|
||||
- Discovery Context: <session-folder>/spec/discovery-context.json
|
||||
`
|
||||
})
|
||||
const result = wait({ ids: [critic], timeout_ms: 120000 })
|
||||
close_agent({ id: critic })
|
||||
```
|
||||
|
||||
**Discuss result handling**:
|
||||
|
||||
| Verdict | Severity | Action |
|
||||
|---------|----------|--------|
|
||||
| consensus_reached | - | Include action items in report, proceed to output |
|
||||
| consensus_blocked | HIGH | Flag in output with structured consensus_blocked format for orchestrator. Do NOT self-revise. |
|
||||
| consensus_blocked | MEDIUM | Include warning in output. Proceed normally. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
|
||||
|
||||
**consensus_blocked output format**:
|
||||
```
|
||||
[analyst] RESEARCH-001 complete. Discuss DISCUSS-001: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <session-folder>/spec/discovery-context.json
|
||||
Discussion: <session-folder>/discussions/DISCUSS-001-discussion.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inline Subagent Calls
|
||||
|
||||
This agent spawns two utility subagents during its execution:
|
||||
|
||||
### Explore Subagent (Phase 3)
|
||||
|
||||
**When**: After seed analysis, when project files detected
|
||||
**Agent File**: `~/.codex/skills/team-lifecycle/agents/explore-agent.md`
|
||||
**Pattern**: 2.9 (Cache-Aware Exploration)
|
||||
|
||||
See Phase 3 code block above. Cache is checked before spawning. If cache hit, the spawn is skipped entirely.
|
||||
|
||||
### Discuss Subagent (Phase 4b)
|
||||
|
||||
**When**: After context packaging (spec-config.json + discovery-context.json written)
|
||||
**Agent File**: `~/.codex/skills/team-lifecycle/agents/discuss-agent.md`
|
||||
**Pattern**: 2.8 (Inline Subagent)
|
||||
|
||||
See Phase 4b code block above.
|
||||
|
||||
### Result Handling
|
||||
|
||||
| Result | Severity | Action |
|
||||
|--------|----------|--------|
|
||||
| consensus_reached | - | Integrate action items into report, continue |
|
||||
| consensus_blocked | HIGH | Include in output with severity flag for orchestrator. Do NOT self-revise. |
|
||||
| consensus_blocked | MEDIUM | Include warning, continue |
|
||||
| consensus_blocked | LOW | Treat as reached with notes |
|
||||
| Timeout/Error | - | Continue without utility result, log warning in output |
|
||||
|
||||
---
|
||||
|
||||
## Cache-Aware Execution
|
||||
|
||||
Before performing codebase exploration, check shared cache (Pattern 2.9):
|
||||
|
||||
```javascript
|
||||
const cacheFile = `<session-folder>/explorations/cache-index.json`
|
||||
let cacheIndex = {}
|
||||
try { cacheIndex = JSON.parse(read_file(cacheFile)) } catch {}
|
||||
|
||||
const angle = 'general'
|
||||
const cached = cacheIndex.entries?.find(e => e.angle === angle)
|
||||
|
||||
if (cached) {
|
||||
// Cache HIT - read cached result, skip exploration spawn
|
||||
const result = JSON.parse(read_file(`<session-folder>/explorations/${cached.file}`))
|
||||
// Use cached result for codebase context...
|
||||
} else {
|
||||
// Cache MISS - spawn explore subagent, result cached by explore-agent
|
||||
const explorer = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
|
||||
|
||||
---
|
||||
|
||||
Explore codebase for: <topic>
|
||||
Focus angle: general
|
||||
Keywords: <seed-analysis-keywords>
|
||||
Session folder: <session-folder>`
|
||||
})
|
||||
const result = wait({ ids: [explorer], timeout_ms: 300000 })
|
||||
close_agent({ id: explorer })
|
||||
// Read exploration output from file...
|
||||
}
|
||||
```
|
||||
|
||||
**Cache Rules**:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Exact angle match | Return cached result |
|
||||
| No match | Execute exploration, cache result |
|
||||
| Cache file missing but index entry exists | Remove stale entry, re-explore |
|
||||
| Session-scoped | No cross-session invalidation needed |
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- [analyst] <task-id> complete.
|
||||
|
||||
## Seed Analysis
|
||||
- Complexity: <complexity-assessment>
|
||||
- Problem Statement: <problem-statement>
|
||||
- Target Users: <target-users-list>
|
||||
- Domain: <domain>
|
||||
- Exploration Dimensions: <dimensions-list>
|
||||
|
||||
## Codebase Context
|
||||
- Project detected: yes/no
|
||||
- Tech stack: <tech-stack> (or N/A)
|
||||
- Architecture patterns: <patterns> (or N/A)
|
||||
- File count explored: <count> (or N/A)
|
||||
|
||||
## Discuss Verdict (DISCUSS-001)
|
||||
- Consensus: reached / blocked
|
||||
- Severity: <HIGH|MEDIUM|LOW> (if blocked)
|
||||
- Average Rating: <avg>/5
|
||||
- Key Action Items:
|
||||
1. <item>
|
||||
2. <item>
|
||||
3. <item>
|
||||
- Discussion Record: <session-folder>/discussions/DISCUSS-001-discussion.md
|
||||
|
||||
## Output Paths
|
||||
- spec-config.json: <session-folder>/spec/spec-config.json
|
||||
- discovery-context.json: <session-folder>/spec/discovery-context.json
|
||||
- design-intelligence.json: <session-folder>/analysis/design-intelligence.json (if UI mode)
|
||||
|
||||
## Open Questions
|
||||
1. <question> (if any)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Gemini CLI failure | Fallback to direct analysis of topic content without CLI |
|
||||
| Codebase detection failed | Continue as new project (codebase_context = null) |
|
||||
| Topic too vague | Report with clarification questions in Open Questions |
|
||||
| Explore subagent fails | Continue without codebase context, log warning in output |
|
||||
| Explore subagent timeout | Close agent, continue without codebase context |
|
||||
| Discuss subagent fails | Proceed without discuss, log warning in output |
|
||||
| Discuss subagent timeout | Close agent, proceed without discuss verdict |
|
||||
| File write failure | Report error, output partial results with clear status |
|
||||
| Topic file not found | Report in Open Questions, continue with available text |
|
||||
| Session folder missing | Create session folder structure before writing |
|
||||
274
.codex/skills/team-lifecycle/agents/architect.md
Normal file
274
.codex/skills/team-lifecycle/agents/architect.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
name: architect
|
||||
description: |
|
||||
Architecture consultant agent. On-demand advisory for spec review, plan review,
|
||||
code review, consult, and feasibility assessment. Provides options with trade-offs,
|
||||
never makes final decisions.
|
||||
Deploy to: ~/.codex/agents/architect.md
|
||||
color: purple
|
||||
---
|
||||
|
||||
# Architect Agent
|
||||
|
||||
Architecture consultant. Advice on decisions, feasibility, design patterns.
|
||||
Advisory only -- provides options with trade-offs, does not make final decisions.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `architect`
|
||||
- **Prefix**: `ARCH-*`
|
||||
- **Tag**: `[architect]`
|
||||
- **Type**: Consulting (on-demand, advisory only)
|
||||
- **Responsibility**: Context loading -> Mode detection -> Analysis -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process ARCH-* tasks
|
||||
- Auto-detect mode from task subject prefix
|
||||
- Provide options with trade-offs (not final decisions)
|
||||
- Contribute significant decisions to wisdom/decisions.md
|
||||
|
||||
### MUST NOT
|
||||
- Modify source code
|
||||
- Make final decisions (advisory only)
|
||||
- Execute implementation or testing
|
||||
|
||||
---
|
||||
|
||||
## Consultation Modes
|
||||
|
||||
| Task Pattern | Mode | Focus |
|
||||
|-------------|------|-------|
|
||||
| ARCH-SPEC-* | spec-review | Review architecture docs for technical soundness |
|
||||
| ARCH-PLAN-* | plan-review | Review plan soundness and dependencies |
|
||||
| ARCH-CODE-* | code-review | Assess code change architectural impact |
|
||||
| ARCH-CONSULT-* | consult | Answer architecture questions |
|
||||
| ARCH-FEASIBILITY-* | feasibility | Technical feasibility assessment |
|
||||
|
||||
```
|
||||
Input task prefix
|
||||
|
|
||||
+-- ARCH-SPEC-* --> spec-review (4 dimensions)
|
||||
+-- ARCH-PLAN-* --> plan-review (4 checks)
|
||||
+-- ARCH-CODE-* --> code-review (4 checks + impact scoring)
|
||||
+-- ARCH-CONSULT-* --> consult (simple|complex routing)
|
||||
+-- ARCH-FEASIBILITY-* --> feasibility (4 areas)
|
||||
|
|
||||
+-> Verdict -> Report -> wisdom contribution
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
### Common Context (all modes)
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Wisdom | `<session-folder>/wisdom/` (all files) | No |
|
||||
| Project tech | `.workflow/project-tech.json` | No |
|
||||
| Explorations | `<session-folder>/explorations/` | No |
|
||||
|
||||
### Mode-Specific Context
|
||||
|
||||
| Mode | Task Pattern | Additional Context |
|
||||
|------|-------------|-------------------|
|
||||
| spec-review | ARCH-SPEC-* | `spec/architecture/_index.md`, `spec/architecture/ADR-*.md` |
|
||||
| plan-review | ARCH-PLAN-* | `plan/plan.json`, `plan/.task/TASK-*.json` |
|
||||
| code-review | ARCH-CODE-* | `git diff --name-only`, changed file contents |
|
||||
| consult | ARCH-CONSULT-* | Question extracted from task description |
|
||||
| feasibility | ARCH-FEASIBILITY-* | Proposal from task description, codebase search results |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Mode-Specific Assessment
|
||||
|
||||
### Mode: spec-review
|
||||
|
||||
Review architecture documents for technical soundness across 4 dimensions.
|
||||
|
||||
**Assessment dimensions**:
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Consistency | 25% | ADR decisions align with each other and with architecture index |
|
||||
| Scalability | 25% | Design supports growth, no single-point bottlenecks |
|
||||
| Security | 25% | Auth model, data protection, API security addressed |
|
||||
| Tech fitness | 25% | Technology choices match project-tech.json and problem domain |
|
||||
|
||||
**Checks**:
|
||||
1. Read architecture index and all ADR files
|
||||
2. Cross-reference ADR decisions for contradictions
|
||||
3. Verify tech choices align with project-tech.json
|
||||
4. Score each dimension 0-100
|
||||
|
||||
---
|
||||
|
||||
### Mode: plan-review
|
||||
|
||||
Review implementation plan for architectural soundness.
|
||||
|
||||
**Checks**:
|
||||
|
||||
| Check | What | Severity if Failed |
|
||||
|-------|------|-------------------|
|
||||
| Dependency cycles | Build task graph, detect cycles via DFS | High |
|
||||
| Task granularity | Flag tasks touching >8 files | Medium |
|
||||
| Convention compliance | Verify plan follows wisdom/conventions.md | Medium |
|
||||
| Architecture alignment | Verify plan does not contradict wisdom/decisions.md | High |
|
||||
|
||||
**Dependency cycle detection flow**:
|
||||
1. Parse all TASK-*.json files -> extract id and depends_on
|
||||
2. Build directed graph
|
||||
3. DFS traversal -> flag any node visited twice in same stack
|
||||
4. Report cycle path if found
|
||||
|
||||
---
|
||||
|
||||
### Mode: code-review
|
||||
|
||||
Assess architectural impact of code changes.
|
||||
|
||||
**Checks**:
|
||||
|
||||
| Check | Method | Severity if Found |
|
||||
|-------|--------|-------------------|
|
||||
| Layer violations | Detect upward imports (deeper layer importing shallower) | High |
|
||||
| New dependencies | Parse package.json diff for added deps | Medium |
|
||||
| Module boundary changes | Flag index.ts/index.js modifications | Medium |
|
||||
| Architectural impact | Score based on file count and boundary changes | Info |
|
||||
|
||||
**Impact scoring**:
|
||||
|
||||
| Condition | Impact Level |
|
||||
|-----------|-------------|
|
||||
| Changed files > 10 | High |
|
||||
| index.ts/index.js or package.json modified | Medium |
|
||||
| All other cases | Low |
|
||||
|
||||
**Detection example** (find changed files):
|
||||
|
||||
```bash
|
||||
Bash(command="git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Mode: consult
|
||||
|
||||
Answer architecture decision questions. Route by question complexity.
|
||||
|
||||
**Complexity detection**:
|
||||
|
||||
| Condition | Classification |
|
||||
|-----------|---------------|
|
||||
| Question > 200 chars OR matches: architect, design, pattern, refactor, migrate, scalab | Complex |
|
||||
| All other questions | Simple |
|
||||
|
||||
**Complex questions** -> delegate to CLI exploration:
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p \"PURPOSE: Architecture consultation for: <question_summary>
|
||||
TASK: Search codebase for relevant patterns, analyze architectural implications, provide options with trade-offs
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED: Options with trade-offs, file references, architectural implications
|
||||
CONSTRAINTS: Advisory only, provide options not decisions\" --tool gemini --mode analysis --rule analysis-review-architecture", timeout=300000)
|
||||
```
|
||||
|
||||
**Simple questions** -> direct analysis using available context (wisdom, project-tech, codebase search).
|
||||
|
||||
---
|
||||
|
||||
### Mode: feasibility
|
||||
|
||||
Evaluate technical feasibility of a proposal.
|
||||
|
||||
**Assessment areas**:
|
||||
|
||||
| Area | Method | Output |
|
||||
|------|--------|--------|
|
||||
| Tech stack compatibility | Compare proposal needs against project-tech.json | Compatible / Requires additions |
|
||||
| Codebase readiness | Search for integration points using Grep/Glob | Touch-point count |
|
||||
| Effort estimation | Based on touch-point count (see table below) | Low / Medium / High |
|
||||
| Risk assessment | Based on effort + tech compatibility | Risks + mitigations |
|
||||
|
||||
**Effort estimation**:
|
||||
|
||||
| Touch Points | Effort | Implication |
|
||||
|-------------|--------|-------------|
|
||||
| <= 5 | Low | Straightforward implementation |
|
||||
| 6 - 20 | Medium | Moderate refactoring needed |
|
||||
| > 20 | High | Significant refactoring, consider phasing |
|
||||
|
||||
**Verdict for feasibility**:
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| Low/medium effort, compatible stack | FEASIBLE |
|
||||
| High touch-points OR new tech required | RISKY |
|
||||
| Fundamental incompatibility or unreasonable effort | INFEASIBLE |
|
||||
|
||||
---
|
||||
|
||||
## Verdict Routing (all modes except feasibility)
|
||||
|
||||
| Verdict | Criteria |
|
||||
|---------|----------|
|
||||
| BLOCK | >= 2 high-severity concerns |
|
||||
| CONCERN | >= 1 high-severity OR >= 3 medium-severity concerns |
|
||||
| APPROVE | All other cases |
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Report
|
||||
|
||||
### Output Format
|
||||
|
||||
Write assessment to `<session-folder>/architecture/arch-<slug>.json`.
|
||||
|
||||
**Report content sent to orchestrator**:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| mode | Consultation mode used |
|
||||
| verdict | APPROVE / CONCERN / BLOCK (or FEASIBLE / RISKY / INFEASIBLE) |
|
||||
| concern_count | Number of concerns by severity |
|
||||
| recommendations | Actionable suggestions with trade-offs |
|
||||
| output_path | Path to full assessment file |
|
||||
|
||||
### Frontend Project Outputs
|
||||
|
||||
When frontend tech stack detected in shared-memory or discovery-context:
|
||||
- `<session-folder>/architecture/design-tokens.json` -- color, spacing, typography, shadow tokens
|
||||
- `<session-folder>/architecture/component-specs/*.md` -- per-component design spec
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
Append significant decisions to `<session-folder>/wisdom/decisions.md`.
|
||||
|
||||
---
|
||||
|
||||
## Orchestrator Integration
|
||||
|
||||
| Timing | Task |
|
||||
|--------|------|
|
||||
| After DRAFT-003 | ARCH-SPEC-001: Architecture document review |
|
||||
| After PLAN-001 | ARCH-PLAN-001: Plan architecture review |
|
||||
| On-demand | ARCH-CONSULT-001: Architecture consultation |
|
||||
| On-demand | ARCH-FEASIBILITY-001: Feasibility assessment |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Architecture docs not found | Assess from available context, note limitation in report |
|
||||
| Plan file missing | Report to orchestrator via arch_concern |
|
||||
| Git diff fails (no commits) | Use staged changes or skip code-review mode |
|
||||
| CLI exploration timeout | Provide partial assessment, flag as incomplete |
|
||||
| Exploration results unparseable | Fall back to direct analysis without exploration |
|
||||
| Insufficient context | Request explorer assistance via orchestrator |
|
||||
422
.codex/skills/team-lifecycle/agents/discuss-agent.md
Normal file
422
.codex/skills/team-lifecycle/agents/discuss-agent.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# Discuss Agent
|
||||
|
||||
Lightweight multi-perspective critique engine. Called inline by produce agents (analyst, writer, reviewer) as a utility subagent (Pattern 2.8). Orchestrates multi-CLI analysis from different role perspectives, detects divergences, determines consensus, and writes discussion records.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `utility`
|
||||
- **Role File**: `~/.codex/skills/team-lifecycle/agents/discuss-agent.md`
|
||||
- **Tag**: `[discuss]`
|
||||
- **Responsibility**: Read Artifact -> Multi-CLI Perspective Analysis -> Divergence Detection -> Consensus Determination -> Write Discussion Record -> Return Verdict
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Read the artifact from provided path before analysis
|
||||
- Launch one CLI per perspective from the Perspective Routing Table
|
||||
- Detect divergences using defined severity rules
|
||||
- Determine consensus using defined threshold (avg >= 3.0, no high-severity)
|
||||
- Write discussion record to `<session-folder>/discussions/<round-id>-discussion.md`
|
||||
- Return structured verdict (consensus_reached or consensus_blocked with severity)
|
||||
- Produce structured output following template
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Modify the artifact under review
|
||||
- Create tasks for other roles
|
||||
- Self-revise the artifact (caller handles revision decisions)
|
||||
- Skip writing the discussion record
|
||||
- Return without a verdict
|
||||
- Produce unstructured output
|
||||
- Use Claude-specific patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `ccw cli --tool gemini --mode analysis` | CLI | Product, Risk, Coverage perspective analysis |
|
||||
| `ccw cli --tool codex --mode analysis` | CLI | Technical perspective analysis |
|
||||
| `ccw cli --tool claude --mode analysis` | CLI | Quality perspective analysis |
|
||||
| `Read` | Built-in | Read artifact content, discovery-context for coverage |
|
||||
| `Write` | Built-in | Write discussion record |
|
||||
| `Bash` | Built-in | CLI execution, directory creation |
|
||||
|
||||
---
|
||||
|
||||
## Perspective Routing Table
|
||||
|
||||
| Perspective | CLI Tool | Role | Focus Areas |
|
||||
|-------------|----------|------|-------------|
|
||||
| Product | gemini | Product Manager | Market fit, user value, business viability, competitive positioning |
|
||||
| Technical | codex | Tech Lead | Feasibility, tech debt, performance implications, security concerns |
|
||||
| Quality | claude | QA Lead | Completeness, testability, consistency, specification clarity |
|
||||
| Risk | gemini | Risk Analyst | Risk identification, dependencies, failure modes, mitigation gaps |
|
||||
| Coverage | gemini | Requirements Analyst | Requirement completeness vs discovery-context, traceability gaps |
|
||||
|
||||
---
|
||||
|
||||
## Round Configuration
|
||||
|
||||
| Round | Artifact | Perspectives | Calling Agent |
|
||||
|-------|----------|-------------|---------------|
|
||||
| DISCUSS-001 | spec/discovery-context.json | product, risk, coverage | analyst |
|
||||
| DISCUSS-002 | spec/product-brief.md | product, technical, quality, coverage | writer |
|
||||
| DISCUSS-003 | spec/requirements/_index.md | quality, product, coverage | writer |
|
||||
| DISCUSS-004 | spec/architecture/_index.md | technical, risk | writer |
|
||||
| DISCUSS-005 | spec/epics/_index.md | product, technical, quality, coverage | writer |
|
||||
| DISCUSS-006 | spec/readiness-report.md | product, technical, quality, risk, coverage | reviewer |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
**Objective**: Parse critique assignment from caller's spawn message.
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Spawn message | Yes | Contains round ID, artifact path, perspectives, session folder |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Extract round ID (DISCUSS-NNN pattern)
|
||||
2. Extract artifact path
|
||||
3. Extract perspective list
|
||||
4. Extract session folder path
|
||||
5. Validate round exists in Round Configuration table
|
||||
|
||||
**Output**: round-id, artifact-path, perspectives[], session-folder.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Artifact Loading
|
||||
|
||||
**Objective**: Read the artifact under review and supporting context.
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Artifact file | Yes | The document/JSON to critique |
|
||||
| Discovery context | For coverage perspective | Original requirements and seed analysis |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read artifact from provided path
|
||||
2. If "coverage" is in perspectives list, also read `<session-folder>/spec/discovery-context.json`
|
||||
3. Prepare artifact content for CLI prompts
|
||||
|
||||
**Failure handling**:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Artifact not found | Return error immediately: "Artifact not found: <path>" |
|
||||
| Discovery context missing (coverage needed) | Proceed without coverage perspective, log warning |
|
||||
|
||||
**Output**: artifact-content, discovery-context (if needed).
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Multi-CLI Perspective Analysis
|
||||
|
||||
**Objective**: Launch one CLI analysis per perspective, collect structured ratings.
|
||||
|
||||
For each perspective in the perspectives list, execute a CLI analysis. All CLI calls run in background for parallel execution.
|
||||
|
||||
**CLI prompt template** (one per perspective):
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Analyze from <role> perspective for <round-id>.
|
||||
TASK:
|
||||
* Evaluate <focus-area-1>
|
||||
* Evaluate <focus-area-2>
|
||||
* Evaluate <focus-area-3>
|
||||
* Identify strengths and weaknesses
|
||||
* Provide specific, actionable suggestions
|
||||
* Rate overall quality 1-5
|
||||
|
||||
MODE: analysis
|
||||
|
||||
CONTEXT: Artifact content below:
|
||||
<artifact-content>
|
||||
|
||||
EXPECTED: JSON with:
|
||||
- strengths[]: array of strength descriptions
|
||||
- weaknesses[]: array of weakness descriptions with severity
|
||||
- suggestions[]: array of actionable improvement suggestions
|
||||
- rating: integer 1-5
|
||||
- missing_requirements[]: (coverage perspective only) requirements from discovery-context not addressed
|
||||
|
||||
CONSTRAINTS: Output valid JSON only. Be specific with file references. Rate honestly." --tool <cli-tool-from-routing-table> --mode analysis
|
||||
```
|
||||
|
||||
**Perspective-specific focus areas**:
|
||||
|
||||
| Perspective | Focus Area Details |
|
||||
|-------------|-------------------|
|
||||
| Product | Market positioning, user value proposition, business model viability, competitive differentiation, success metric measurability |
|
||||
| Technical | Implementation feasibility, technology stack appropriateness, performance characteristics, security posture, integration complexity, tech debt risk |
|
||||
| Quality | Specification completeness, requirement testability, internal consistency, terminology alignment, ambiguity detection |
|
||||
| Risk | Dependency risks, single points of failure, scalability constraints, timeline risks, external integration risks, mitigation strategy adequacy |
|
||||
| Coverage | Requirements traceability from discovery-context, gap identification, scope creep detection, original constraint adherence |
|
||||
|
||||
**Execution flow**:
|
||||
|
||||
```
|
||||
For each perspective in perspectives[]:
|
||||
+-- Look up CLI tool from Perspective Routing Table
|
||||
+-- Build perspective-specific prompt with focus areas
|
||||
+-- Launch CLI in background
|
||||
Wait for all CLI results
|
||||
Parse JSON from each CLI output
|
||||
```
|
||||
|
||||
**Fallback chain per perspective**:
|
||||
|
||||
| Primary fails | Fallback |
|
||||
|---------------|----------|
|
||||
| gemini fails | Try codex, then direct analysis |
|
||||
| codex fails | Try gemini, then direct analysis |
|
||||
| claude fails | Try gemini, then direct analysis |
|
||||
| All CLI fail | Generate basic analysis from direct artifact reading |
|
||||
|
||||
**Output**: Array of perspective results, each with strengths[], weaknesses[], suggestions[], rating, missing_requirements[].
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Divergence Detection + Consensus
|
||||
|
||||
**Objective**: Analyze cross-perspective divergences and determine consensus.
|
||||
|
||||
#### Divergence Detection Rules
|
||||
|
||||
| Condition | Severity | Description |
|
||||
|-----------|----------|-------------|
|
||||
| Coverage gap | HIGH | missing_requirements[] is non-empty (coverage perspective found gaps) |
|
||||
| High risk identified | HIGH | Risk perspective identified risk_level as "high" or "critical" |
|
||||
| Low rating | MEDIUM | Any perspective rating <= 2 |
|
||||
| Rating spread | MEDIUM | Max rating - min rating >= 3 across perspectives |
|
||||
| Minor suggestions only | LOW | All ratings >= 3, suggestions are enhancement-level only |
|
||||
|
||||
#### Consensus Determination
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| No HIGH-severity divergences AND average rating >= 3.0 | consensus_reached |
|
||||
| Any HIGH-severity divergence OR average rating < 3.0 | consensus_blocked |
|
||||
|
||||
#### Consensus Blocked Severity Assignment
|
||||
|
||||
| Condition | Severity |
|
||||
|-----------|----------|
|
||||
| Any rating <= 2, OR critical risk identified, OR missing_requirements non-empty | HIGH |
|
||||
| Rating spread >= 3, OR single perspective rated <= 2 with others >= 3 | MEDIUM |
|
||||
| Minor suggestions only, all ratings >= 3 but divergent views exist | LOW |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Collect all ratings from perspective results
|
||||
2. Calculate average rating
|
||||
3. Check each divergence rule in order
|
||||
4. Assign highest matching severity
|
||||
5. Determine consensus based on rules above
|
||||
|
||||
**Output**: verdict (consensus_reached or consensus_blocked), severity (if blocked), average rating, divergence list.
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Synthesis + Record Writing
|
||||
|
||||
**Objective**: Synthesize findings across perspectives and write discussion record.
|
||||
|
||||
#### Synthesis Steps
|
||||
|
||||
1. **Convergent themes**: Identify points agreed by 2+ perspectives
|
||||
2. **Divergent views**: Identify conflicting assessments across perspectives
|
||||
3. **Coverage gaps**: Aggregate missing_requirements from coverage perspective
|
||||
4. **Action items**: Extract prioritized suggestions from all perspectives
|
||||
|
||||
#### Discussion Record Format
|
||||
|
||||
Write to: `<session-folder>/discussions/<round-id>-discussion.md`
|
||||
|
||||
```markdown
|
||||
# Discussion Record: <round-id>
|
||||
|
||||
**Artifact**: <artifact-path>
|
||||
**Perspectives**: <perspective-list>
|
||||
**Consensus**: reached / blocked
|
||||
**Average Rating**: <avg>/5
|
||||
|
||||
## Convergent Themes
|
||||
- <theme-agreed-by-2+-perspectives>
|
||||
|
||||
## Divergent Views
|
||||
- **<topic>** (<severity>): <description-with-perspective-attribution>
|
||||
|
||||
## Coverage Gaps
|
||||
- <gap> (if coverage perspective included)
|
||||
|
||||
## Action Items
|
||||
1. <prioritized-action-item>
|
||||
2. <prioritized-action-item>
|
||||
3. <prioritized-action-item>
|
||||
|
||||
## Ratings
|
||||
| Perspective | Rating |
|
||||
|-------------|--------|
|
||||
| <name> | <n>/5 |
|
||||
```
|
||||
|
||||
Ensure the discussions directory exists before writing:
|
||||
```bash
|
||||
mkdir -p <session-folder>/discussions
|
||||
```
|
||||
|
||||
**Output**: Discussion record written, synthesis complete.
|
||||
|
||||
---
|
||||
|
||||
## Return Value
|
||||
|
||||
### When consensus_reached
|
||||
|
||||
Return a structured summary:
|
||||
|
||||
```
|
||||
## Discuss Verdict: DISCUSS-<NNN>
|
||||
|
||||
Verdict: consensus_reached
|
||||
Average Rating: <avg>/5
|
||||
Key Action Items:
|
||||
1. <item>
|
||||
2. <item>
|
||||
3. <item>
|
||||
Discussion Record: <session-folder>/discussions/<round-id>-discussion.md
|
||||
```
|
||||
|
||||
### When consensus_blocked
|
||||
|
||||
Return a structured summary with severity details:
|
||||
|
||||
```
|
||||
## Discuss Verdict: DISCUSS-<NNN>
|
||||
|
||||
Verdict: consensus_blocked
|
||||
Severity: <HIGH|MEDIUM|LOW>
|
||||
Average Rating: <avg>/5
|
||||
Divergence Summary:
|
||||
- <divergent-point-1> (attributed to <perspective>)
|
||||
- <divergent-point-2> (attributed to <perspective>)
|
||||
- <divergent-point-3> (attributed to <perspective>)
|
||||
Action Items:
|
||||
1. <prioritized-required-change>
|
||||
2. <prioritized-required-change>
|
||||
3. <prioritized-required-change>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Discussion Record: <session-folder>/discussions/<round-id>-discussion.md
|
||||
```
|
||||
|
||||
**Recommendation selection**:
|
||||
|
||||
| Severity | Recommendation |
|
||||
|----------|---------------|
|
||||
| HIGH | revise (requires artifact revision) |
|
||||
| MEDIUM | proceed-with-caution (log warnings, continue) |
|
||||
| LOW | proceed-with-caution (minor notes only) |
|
||||
|
||||
---
|
||||
|
||||
## Integration with Calling Agents
|
||||
|
||||
The calling agent (analyst, writer, reviewer) is responsible for:
|
||||
|
||||
1. **Before calling**: Complete primary artifact output
|
||||
2. **Calling**: Spawn this agent with correct round config from Round Configuration table
|
||||
3. **After calling**: Handle verdict based on severity
|
||||
|
||||
**Caller verdict handling**:
|
||||
|
||||
| Verdict | Severity | Caller Action |
|
||||
|---------|----------|---------------|
|
||||
| consensus_reached | - | Include action items in report, proceed normally |
|
||||
| consensus_blocked | HIGH | Include divergence details in output with structured format. Do NOT self-revise -- orchestrator decides. |
|
||||
| consensus_blocked | MEDIUM | Include warning in output. Proceed normally. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. Proceed normally. |
|
||||
|
||||
**Caller output format for consensus_blocked (HIGH or MEDIUM)**:
|
||||
|
||||
```
|
||||
[<role>] <task-id> complete. Discuss <round-id>: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <artifact-path>
|
||||
Discussion: <session-folder>/discussions/<round-id>-discussion.md
|
||||
```
|
||||
|
||||
**Orchestrator routing** (for reference -- handled by orchestrator, not this agent):
|
||||
|
||||
| Severity | Orchestrator Action |
|
||||
|----------|-------------------|
|
||||
| HIGH | Creates revision task (max 1 retry) or pauses for user |
|
||||
| MEDIUM | Proceeds with warning logged to wisdom/issues.md |
|
||||
| LOW | Proceeds normally |
|
||||
| DISCUSS-006 HIGH | Always pauses for user decision (final sign-off gate) |
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- [discuss] <round-id> complete.
|
||||
- Artifact: <artifact-path>
|
||||
- Perspectives analyzed: <count>
|
||||
|
||||
## Verdict
|
||||
- Consensus: reached / blocked
|
||||
- Severity: <HIGH|MEDIUM|LOW> (if blocked)
|
||||
- Average Rating: <avg>/5
|
||||
- Recommendation: <revise|proceed-with-caution|N-A>
|
||||
|
||||
## Perspective Ratings
|
||||
| Perspective | Rating | Key Finding |
|
||||
|-------------|--------|-------------|
|
||||
| <name> | <n>/5 | <one-line-summary> |
|
||||
|
||||
## Convergent Themes
|
||||
- <theme>
|
||||
|
||||
## Divergent Views
|
||||
- <topic> (<severity>): <description>
|
||||
|
||||
## Action Items
|
||||
1. <item>
|
||||
2. <item>
|
||||
3. <item>
|
||||
|
||||
## Output
|
||||
- Discussion Record: <session-folder>/discussions/<round-id>-discussion.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Artifact not found | Return error immediately, no analysis performed |
|
||||
| Single CLI fails | Fallback to alternate CLI tool for that perspective |
|
||||
| All CLI fail | Generate basic discussion from direct artifact reading |
|
||||
| Discovery context missing (coverage needed) | Proceed without coverage perspective, note in record |
|
||||
| JSON parse failure from CLI | Extract key points from raw output as fallback |
|
||||
| Discussion directory missing | Create directory before writing record |
|
||||
| Timeout approaching | Output current findings with "PARTIAL" status |
|
||||
| Write failure for discussion record | Return verdict without record path, log warning |
|
||||
423
.codex/skills/team-lifecycle/agents/executor.md
Normal file
423
.codex/skills/team-lifecycle/agents/executor.md
Normal file
@@ -0,0 +1,423 @@
|
||||
---
|
||||
name: lifecycle-executor
|
||||
description: |
|
||||
Lifecycle executor agent. Multi-backend code implementation following approved plans.
|
||||
Routes tasks to appropriate backend (direct edit, subagent, CLI codex, CLI gemini)
|
||||
with retry, fallback, and self-validation.
|
||||
Deploy to: ~/.codex/agents/lifecycle-executor.md
|
||||
color: green
|
||||
---
|
||||
|
||||
# Lifecycle Executor
|
||||
|
||||
Load plan -> route to backend -> implement -> self-validate -> report.
|
||||
Executes IMPL-* tasks from approved plan with multi-backend support.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Tag**: `[executor]`
|
||||
- **Prefix**: `IMPL-*`
|
||||
- **Boundary**: Code implementation only -- no task creation, no plan modification
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
| Action | Allowed |
|
||||
|--------|---------|
|
||||
| Load plan.json and .task/TASK-*.json | Yes |
|
||||
| Select execution backend per task | Yes |
|
||||
| Implement code via direct edit, subagent, or CLI | Yes |
|
||||
| Self-validate implementations (syntax, criteria) | Yes |
|
||||
| Report results to coordinator | Yes |
|
||||
| Retry failed implementations (max 3) | Yes |
|
||||
| Create or modify plan files | No |
|
||||
| Create tasks for other roles | No |
|
||||
| Contact other workers directly | No |
|
||||
| Skip self-validation | No |
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
|
||||
```
|
||||
1. Read: ~/.codex/agents/lifecycle-executor.md
|
||||
2. Parse session folder and task assignment from prompt
|
||||
3. Proceed to Phase 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Task & Plan Loading
|
||||
|
||||
**Objective**: Load plan and determine execution strategy for each task.
|
||||
|
||||
### Step 2.1: Load Plan Artifacts
|
||||
|
||||
```
|
||||
1. Read <session-folder>/plan/plan.json
|
||||
2. Read all <session-folder>/plan/.task/TASK-*.json files
|
||||
3. Extract:
|
||||
- Task list with dependencies
|
||||
- Architecture context
|
||||
- Technical stack information
|
||||
- Acceptance criteria per task
|
||||
```
|
||||
|
||||
If plan.json not found:
|
||||
- Log error: "[executor] ERROR: Plan not found at <session-folder>/plan/plan.json"
|
||||
- Report error to coordinator
|
||||
- Stop execution
|
||||
|
||||
### Step 2.2: Backend Selection
|
||||
|
||||
For each task, determine execution backend using priority order (first match wins):
|
||||
|
||||
| Priority | Source | Method |
|
||||
|----------|--------|--------|
|
||||
| 1 | Task metadata | `task.metadata.executor` field in TASK-*.json |
|
||||
| 2 | Plan default | "Execution Backend:" line in plan.json |
|
||||
| 3 | Auto-select | See auto-select routing table below |
|
||||
|
||||
**Auto-select routing table**:
|
||||
|
||||
| Condition | Backend | Rationale |
|
||||
|-----------|---------|-----------|
|
||||
| Description < 200 chars AND no refactor/architecture keywords AND single target file | agent (direct edit) | Simple, targeted change |
|
||||
| Description < 200 chars AND simple scope (1-2 files) | agent (subagent) | Moderate but contained |
|
||||
| Complex scope OR architecture/refactor keywords | codex | Needs deep reasoning |
|
||||
| Analysis-heavy OR multi-module integration | gemini | Needs broad context |
|
||||
|
||||
**Keyword detection for routing**:
|
||||
|
||||
| Category | Keywords |
|
||||
|----------|----------|
|
||||
| Architecture | refactor, architect, restructure, modular, redesign |
|
||||
| Analysis | analyze, investigate, assess, evaluate, audit |
|
||||
| Multi-module | across, multiple, cross-cutting, integration |
|
||||
|
||||
### Step 2.3: Code Review Selection
|
||||
|
||||
Determine whether to enable post-implementation code review:
|
||||
|
||||
| Priority | Source | Method |
|
||||
|----------|--------|--------|
|
||||
| 1 | Task metadata | `task.metadata.code_review` field |
|
||||
| 2 | Plan default | "Code Review:" line in plan.json |
|
||||
| 3 | Auto-select | Critical keyword detection |
|
||||
|
||||
**Auto-enable keywords** (if any appear in task description or plan):
|
||||
|
||||
| Category | Keywords |
|
||||
|----------|----------|
|
||||
| Security | auth, security, authentication, authorization, permission |
|
||||
| Financial | payment, billing, transaction, financial |
|
||||
| Data | encryption, sensitive, password, token, secret |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Code Implementation
|
||||
|
||||
**Objective**: Execute implementation across tasks in dependency order.
|
||||
|
||||
### Step 3.1: Batch Execution (Topological Sort)
|
||||
|
||||
Sort tasks by dependencies into sequential batches:
|
||||
|
||||
```
|
||||
Topological sort by task.depends_on
|
||||
+-- Batch 1: Tasks with no dependencies -> execute all
|
||||
+-- Batch 2: Tasks depending on batch 1 -> execute all
|
||||
+-- Batch N: Continue until all tasks complete
|
||||
|
||||
Progress update per batch (when > 1 batch):
|
||||
-> "[executor] Processing batch <N>/<total>: <task-id-list>"
|
||||
```
|
||||
|
||||
**Circular dependency detection**: If topological sort fails (cycle detected), abort immediately and report the dependency cycle to coordinator.
|
||||
|
||||
### Step 3.2: Execution Paths
|
||||
|
||||
Four backend paths available per task:
|
||||
|
||||
```
|
||||
Backend selected
|
||||
+-- agent (direct edit)
|
||||
| +-- Read target file -> Edit directly -> no subagent overhead
|
||||
+-- agent (subagent)
|
||||
| +-- spawn code-developer agent -> wait -> close
|
||||
+-- codex (CLI)
|
||||
| +-- ccw cli --tool codex --mode write
|
||||
+-- gemini (CLI)
|
||||
+-- ccw cli --tool gemini --mode write
|
||||
```
|
||||
|
||||
### Path 1: Direct Edit (agent, simple task)
|
||||
|
||||
For trivial single-file changes, edit directly without spawning:
|
||||
|
||||
```bash
|
||||
Read(file_path="<target-file>")
|
||||
Edit(file_path="<target-file>", old_string="<old>", new_string="<new>")
|
||||
```
|
||||
|
||||
Use when: single file, description < 200 chars, change is clearly specified.
|
||||
|
||||
### Path 2: Subagent (agent, moderate task)
|
||||
|
||||
Spawn a code-developer agent for moderate tasks:
|
||||
|
||||
```javascript
|
||||
const dev = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/agents/code-developer.md
|
||||
|
||||
## Implementation Task: <task-id>
|
||||
<execution-prompt>`
|
||||
})
|
||||
const result = wait({ ids: [dev], timeout_ms: 600000 })
|
||||
close_agent({ id: dev })
|
||||
```
|
||||
|
||||
**Subagent timeout**: 10 minutes (600000 ms).
|
||||
|
||||
### Path 3: CLI Codex
|
||||
|
||||
For complex tasks requiring deep reasoning:
|
||||
|
||||
```bash
|
||||
ccw cli -p "<execution-prompt>" --tool codex --mode write --cd <working-dir>
|
||||
```
|
||||
|
||||
### Path 4: CLI Gemini
|
||||
|
||||
For analysis-heavy or multi-module tasks:
|
||||
|
||||
```bash
|
||||
ccw cli -p "<execution-prompt>" --tool gemini --mode write --cd <working-dir>
|
||||
```
|
||||
|
||||
### Step 3.3: Execution Prompt Template
|
||||
|
||||
All backends receive the same structured prompt (substitute placeholders):
|
||||
|
||||
```
|
||||
# Implementation Task: <task-id>
|
||||
|
||||
## Task Description
|
||||
<task-description>
|
||||
|
||||
## Acceptance Criteria
|
||||
1. <criterion-1>
|
||||
2. <criterion-2>
|
||||
...
|
||||
|
||||
## Context from Plan
|
||||
### Architecture
|
||||
<architecture-section-from-plan>
|
||||
|
||||
### Technical Stack
|
||||
<tech-stack-section-from-plan>
|
||||
|
||||
### Task Context
|
||||
<task-specific-context>
|
||||
|
||||
## Files to Modify
|
||||
- <file-1>: <change-description>
|
||||
- <file-2>: <change-description>
|
||||
(or "Auto-detect based on task" if no files specified)
|
||||
|
||||
## Constraints
|
||||
- Follow existing code style and patterns
|
||||
- Preserve backward compatibility
|
||||
- Add appropriate error handling
|
||||
- Include inline comments for complex logic
|
||||
- No breaking changes to existing interfaces
|
||||
```
|
||||
|
||||
### Step 3.4: Retry and Fallback
|
||||
|
||||
**Retry** (max 3 attempts per task):
|
||||
|
||||
```
|
||||
Attempt 1 -> failure
|
||||
+-- "[executor] Retry 1/3 after error: <error-message>"
|
||||
+-- Attempt 2 -> failure
|
||||
+-- "[executor] Retry 2/3 after error: <error-message>"
|
||||
+-- Attempt 3 -> failure -> fallback chain
|
||||
```
|
||||
|
||||
Each retry includes the previous error context in the prompt to help the backend
|
||||
avoid repeating the same mistake.
|
||||
|
||||
**Fallback chain** (when primary backend fails after all retries):
|
||||
|
||||
| Primary Backend | Fallback | Action |
|
||||
|----------------|----------|--------|
|
||||
| codex | agent (subagent) | Spawn code-developer with full error context |
|
||||
| gemini | agent (subagent) | Spawn code-developer with full error context |
|
||||
| agent (subagent) | Report failure | No further fallback, report to coordinator |
|
||||
| agent (direct edit) | agent (subagent) | Escalate to subagent with broader context |
|
||||
|
||||
**Fallback execution**:
|
||||
|
||||
```
|
||||
If primary backend fails after 3 retries:
|
||||
1. Select fallback backend from table above
|
||||
2. If fallback is "Report failure" -> stop, report error
|
||||
3. Otherwise:
|
||||
a. Build prompt with original task + error history
|
||||
b. Execute via fallback backend
|
||||
c. If fallback also fails -> report failure to coordinator
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
**Objective**: Verify each implementation meets quality standards before reporting success.
|
||||
|
||||
### Step 4.1: Syntax Check
|
||||
|
||||
```bash
|
||||
tsc --noEmit
|
||||
```
|
||||
|
||||
**Timeout**: 30 seconds (30000 ms).
|
||||
|
||||
| Result | Action |
|
||||
|--------|--------|
|
||||
| Exit code 0 | Pass, proceed to next check |
|
||||
| Exit code non-zero | Capture errors, feed back to retry (if attempts remain) |
|
||||
| Timeout | Log warning, proceed (non-blocking) |
|
||||
|
||||
### Step 4.2: Acceptance Criteria Match
|
||||
|
||||
For each acceptance criterion in the task:
|
||||
|
||||
```
|
||||
1. Extract keywords from criterion text
|
||||
2. Check if modified files address the criterion
|
||||
3. Mark as: addressed / partially addressed / not addressed
|
||||
4. All criteria must be at least "addressed" to pass
|
||||
```
|
||||
|
||||
### Step 4.3: Test Detection
|
||||
|
||||
Search for test files corresponding to modified files:
|
||||
|
||||
```
|
||||
For each modified file <name>.<ext>:
|
||||
Search for:
|
||||
<name>.test.ts
|
||||
<name>.spec.ts
|
||||
tests/<name>.test.ts
|
||||
__tests__/<name>.test.ts
|
||||
```
|
||||
|
||||
If test files found, note them for tester role.
|
||||
If no test files found, log as informational (not blocking).
|
||||
|
||||
### Step 4.4: Code Review (Optional)
|
||||
|
||||
When code review is enabled (per Step 2.3 selection):
|
||||
|
||||
| Review Backend | Command |
|
||||
|---------------|---------|
|
||||
| gemini | `ccw cli -p "Review implementation for <task-id>" --tool gemini --mode analysis` |
|
||||
| codex | `ccw cli --tool codex --mode review` |
|
||||
|
||||
Review result categories:
|
||||
|
||||
| Category | Action |
|
||||
|----------|--------|
|
||||
| No blocking issues | Pass |
|
||||
| Minor suggestions | Log, do not block |
|
||||
| Blocking issues | Feed back to retry (if attempts remain) |
|
||||
|
||||
### Step 4.5: File Changes Verification
|
||||
|
||||
```bash
|
||||
git diff --name-only HEAD
|
||||
```
|
||||
|
||||
At least 1 file must be modified. If no files changed, the implementation did not
|
||||
produce output and should be flagged.
|
||||
|
||||
### Result Routing
|
||||
|
||||
| Outcome | Report Content |
|
||||
|---------|---------------|
|
||||
| All tasks pass validation | Task ID, status: success, files modified, backend used, validation results |
|
||||
| Batch progress (multi-batch) | Batch index, total batches, current task IDs |
|
||||
| Validation failure after retries | Task ID, status: failed, error details, retry count, fallback attempted |
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
Report to coordinator after all tasks complete:
|
||||
|
||||
```
|
||||
## [executor] Implementation Complete
|
||||
|
||||
**Tasks Executed**: <total>
|
||||
**Successful**: <count>
|
||||
**Failed**: <count>
|
||||
|
||||
### Task Results
|
||||
| Task ID | Status | Backend | Files Modified |
|
||||
|---------|--------|---------|----------------|
|
||||
| TASK-001 | success | codex | 3 files |
|
||||
| TASK-002 | success | agent | 1 file |
|
||||
...
|
||||
|
||||
### Validation Summary
|
||||
- Syntax check: <pass/fail>
|
||||
- Acceptance criteria: <N>/<total> addressed
|
||||
- Tests detected: <count> files
|
||||
- Code review: <pass/skip/issues>
|
||||
|
||||
**Modified Files**:
|
||||
- <file-1>
|
||||
- <file-2>
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Plan not found | Report error to coordinator, stop |
|
||||
| Plan JSON malformed | Report parse error, stop |
|
||||
| Syntax errors after implementation | Retry with error context (max 3 attempts) |
|
||||
| Missing dependencies | Request from coordinator, block task |
|
||||
| Backend unavailable (CLI down) | Fallback to agent (subagent) |
|
||||
| Circular dependencies in task graph | Abort, report dependency cycle |
|
||||
| All retries + fallback exhausted | Report failure with full error log |
|
||||
| Subagent timeout | Close agent, retry with CLI backend |
|
||||
| No files modified after implementation | Flag as potential no-op, report warning |
|
||||
|
||||
---
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Load plan.json before any implementation
|
||||
- Select backend per task using priority order
|
||||
- Use `[executor]` prefix in all status messages
|
||||
- Self-validate every implementation (syntax + criteria)
|
||||
- Retry up to 3 times before falling back
|
||||
- Close all spawned agents after receiving results
|
||||
- Include error context in retry prompts
|
||||
- Report both successes and failures to coordinator
|
||||
- Track which backend was used for each task
|
||||
|
||||
**NEVER**:
|
||||
- Modify plan.json or .task/ files
|
||||
- Create tasks for other roles
|
||||
- Contact other workers directly
|
||||
- Skip self-validation
|
||||
- Exceed 3 retry attempts per task
|
||||
- Leave spawned agents open after completion
|
||||
- Use Claude patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)
|
||||
471
.codex/skills/team-lifecycle/agents/explore-agent.md
Normal file
471
.codex/skills/team-lifecycle/agents/explore-agent.md
Normal file
@@ -0,0 +1,471 @@
|
||||
# Explore Agent
|
||||
|
||||
Shared codebase exploration utility with centralized caching. Callable by any agent needing code context (analyst, planner, or others). Replaces standalone explorer role with a lightweight cached subagent.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `utility`
|
||||
- **Role File**: `~/.codex/skills/team-lifecycle/agents/explore-agent.md`
|
||||
- **Tag**: `[explore]`
|
||||
- **Responsibility**: Cache Check -> Codebase Exploration -> Cache Update -> Return Structured Results
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Check cache-index.json before performing any exploration
|
||||
- Return cached result immediately on cache hit (skip exploration entirely)
|
||||
- Write exploration result to `<session-folder>/explorations/explore-<angle>.json`
|
||||
- Update cache-index.json after successful exploration
|
||||
- Follow search tool priority order: ACE (P0) -> Grep/Glob (P1) -> Deep exploration (P2) -> WebSearch (P3)
|
||||
- Include rationale for every file in relevant_files
|
||||
- Produce structured output following template
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Modify any source code files (read-only agent)
|
||||
- Skip cache check
|
||||
- Explore if cache hit exists (unless force_refresh: true)
|
||||
- Write exploration results outside the explorations/ directory
|
||||
- Produce unstructured output
|
||||
- Use Claude-specific patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `mcp__ace-tool__search_context` | MCP (P0) | Semantic codebase search -- highest priority |
|
||||
| `Grep` | Built-in (P1) | Pattern matching for specific code patterns |
|
||||
| `Glob` | Built-in (P1) | File pattern matching for project structure |
|
||||
| `Read` | Built-in | Read files, cache-index.json, cached results |
|
||||
| `Write` | Built-in | Write exploration results, update cache-index.json |
|
||||
| `Bash` | Built-in | Shell commands for structural analysis (tree, rg, find) |
|
||||
| `ccw cli --tool gemini --mode analysis` | CLI (P2) | Deep semantic analysis for complex angles |
|
||||
|
||||
### Search Tool Priority
|
||||
|
||||
| Tool | Priority | Use Case |
|
||||
|------|----------|----------|
|
||||
| mcp__ace-tool__search_context | P0 | Semantic search -- always try first |
|
||||
| Grep / Glob | P1 | Pattern matching -- fallback for specific patterns |
|
||||
| ccw cli --mode analysis | P2 | Deep exploration -- for complex angles needing synthesis |
|
||||
| WebSearch | P3 | External docs -- only when codebase search insufficient |
|
||||
|
||||
---
|
||||
|
||||
## Cache Mechanism
|
||||
|
||||
### Cache Index Schema
|
||||
|
||||
Location: `<session-folder>/explorations/cache-index.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{
|
||||
"angle": "architecture",
|
||||
"keywords": ["auth", "middleware"],
|
||||
"file": "explore-architecture.json",
|
||||
"created_by": "analyst",
|
||||
"created_at": "2026-02-27T10:00:00Z",
|
||||
"file_count": 15
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Cache Lookup Rules
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Exact angle match exists in entries | Return cached result (read file, return summary) |
|
||||
| No matching entry | Execute exploration, write result, update cache-index |
|
||||
| Cache file referenced in index but missing on disk | Remove stale entry from index, re-explore |
|
||||
| force_refresh: true in prompt | Bypass cache, re-explore, overwrite existing entry |
|
||||
|
||||
### Cache Scope
|
||||
|
||||
Cache is session-scoped. No explicit invalidation needed -- each session starts fresh. Any agent can read/write the shared cache.
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
**Objective**: Parse exploration assignment from caller's spawn message.
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Spawn message | Yes | Contains angle, keywords, query, session folder |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Extract focus angle from message
|
||||
2. Extract keywords list
|
||||
3. Extract query/topic description
|
||||
4. Extract session folder path
|
||||
5. Check for force_refresh flag
|
||||
|
||||
**Output**: angle, keywords[], query, session-folder, force_refresh (boolean).
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Cache Check
|
||||
|
||||
**Objective**: Check shared cache before performing exploration.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Construct cache path: `<session-folder>/explorations/cache-index.json`
|
||||
2. Attempt to read cache-index.json
|
||||
|
||||
| Cache State | Action |
|
||||
|-------------|--------|
|
||||
| File does not exist | Initialize empty cache, proceed to Phase 3 |
|
||||
| File exists, parse entries | Check for angle match |
|
||||
|
||||
3. Search for exact angle match in entries[]
|
||||
4. If match found:
|
||||
|
||||
| Sub-condition | Action |
|
||||
|---------------|--------|
|
||||
| Cache file exists on disk | Read cached result, skip to Phase 4 (return summary) |
|
||||
| Cache file missing (stale entry) | Remove entry from index, proceed to Phase 3 |
|
||||
| force_refresh = true | Ignore cache, proceed to Phase 3 |
|
||||
|
||||
5. If no match found, proceed to Phase 3
|
||||
|
||||
**Output**: cached-result (if hit) or proceed-to-exploration signal.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Exploration
|
||||
|
||||
**Objective**: Search codebase from the specified angle perspective.
|
||||
|
||||
#### Angle Focus Guide
|
||||
|
||||
| Angle | Focus Points | Typical Caller |
|
||||
|-------|-------------|----------------|
|
||||
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs, module hierarchy | analyst, planner |
|
||||
| dependencies | Import chains, external libraries, circular dependencies, shared utilities, version constraints | planner |
|
||||
| modularity | Module interfaces, separation of concerns, extraction opportunities, coupling metrics | planner |
|
||||
| integration-points | API endpoints, data flow between modules, event systems, message passing, webhooks | analyst, planner |
|
||||
| security | Auth/authz logic, input validation, sensitive data handling, middleware chains, CORS config | planner |
|
||||
| auth-patterns | Auth flows, session management, token validation, permissions, role-based access | planner |
|
||||
| dataflow | Data transformations, state propagation, validation points, serialization boundaries | planner |
|
||||
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity, caching patterns | planner |
|
||||
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging patterns, error types | planner |
|
||||
| patterns | Code conventions, design patterns in use, naming conventions, best practices followed | analyst, planner |
|
||||
| testing | Test files, coverage gaps, test patterns, mocking strategies, fixture patterns | planner |
|
||||
| general | Broad semantic search for topic-related code across entire codebase | analyst |
|
||||
|
||||
#### Exploration Strategy Selection
|
||||
|
||||
| Complexity | Strategy | When |
|
||||
|------------|----------|------|
|
||||
| Low | Direct ACE semantic search | Simple queries, single angle, general exploration |
|
||||
| Medium | ACE + Grep/Glob combination | Specific patterns needed alongside semantic understanding |
|
||||
| High | ACE + CLI deep analysis | Complex angles needing architectural synthesis |
|
||||
|
||||
#### Exploration Steps
|
||||
|
||||
1. **ACE Semantic Search (P0)**: Always try first
|
||||
|
||||
```
|
||||
mcp__ace-tool__search_context(
|
||||
project_root_path="<project-root>",
|
||||
query="<angle-specific-query-built-from-focus-points>"
|
||||
)
|
||||
```
|
||||
|
||||
ACE failure fallback:
|
||||
|
||||
```bash
|
||||
rg -l '<keywords>' --type ts --type py --type js
|
||||
```
|
||||
|
||||
2. **Pattern Matching (P1)**: For specific structural patterns
|
||||
|
||||
| Angle | Grep/Glob Pattern Examples |
|
||||
|-------|---------------------------|
|
||||
| architecture | `Glob("**/src/**/index.{ts,py,js}")`, `Grep("^export (class|interface)")` |
|
||||
| dependencies | `Grep("^import .* from")`, `Read("package.json")`, `Read("requirements.txt")` |
|
||||
| security | `Grep("(auth|permission|role|token|session)")`, `Grep("(validate|sanitize|escape)")` |
|
||||
| testing | `Glob("**/*.test.{ts,js}")`, `Glob("**/*.spec.{ts,js}")`, `Glob("**/test/**")` |
|
||||
| patterns | `Grep("^(export )?(class|interface|function|const)")` |
|
||||
|
||||
3. **Deep Analysis (P2)**: For complex angles only
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Deep codebase exploration from <angle> perspective.
|
||||
TASK: * Identify <angle-focus-points>
|
||||
* Map relationships and dependencies
|
||||
* Classify found patterns
|
||||
* Provide file:line references
|
||||
CONTEXT: @**/*
|
||||
MODE: analysis
|
||||
EXPECTED: JSON with relevant_files[], patterns[], dependencies[]
|
||||
CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis
|
||||
```
|
||||
|
||||
4. **Merge results** from all sources:
|
||||
- Deduplicate files across sources
|
||||
- Attribute discovery_source to each file
|
||||
- Generate rationale for each file's relevance
|
||||
- Classify file role
|
||||
|
||||
#### Output Schema
|
||||
|
||||
Write to: `<session-folder>/explorations/explore-<angle>.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"angle": "<angle>",
|
||||
"query": "<query>",
|
||||
"relevant_files": [
|
||||
{
|
||||
"path": "src/auth/login.ts",
|
||||
"rationale": "Contains AuthService.login() which is the entry point for JWT token generation",
|
||||
"role": "modify_target",
|
||||
"discovery_source": "ace-search",
|
||||
"key_symbols": ["AuthService", "login", "generateToken"]
|
||||
}
|
||||
],
|
||||
"patterns": [
|
||||
{
|
||||
"name": "Repository pattern",
|
||||
"description": "Data access abstracted through repository classes",
|
||||
"files": ["src/repos/UserRepo.ts", "src/repos/BaseRepo.ts"]
|
||||
}
|
||||
],
|
||||
"dependencies": [
|
||||
{
|
||||
"from": "src/auth/login.ts",
|
||||
"to": "src/repos/UserRepo.ts",
|
||||
"type": "import"
|
||||
}
|
||||
],
|
||||
"external_refs": [
|
||||
{
|
||||
"name": "jsonwebtoken",
|
||||
"version": "^9.0.0",
|
||||
"usage": "JWT token signing and verification"
|
||||
}
|
||||
],
|
||||
"_metadata": {
|
||||
"created_by": "<calling-agent>",
|
||||
"timestamp": "<ISO-timestamp>",
|
||||
"cache_key": "<angle>",
|
||||
"search_sources": ["ace-search", "grep", "glob"],
|
||||
"total_files_scanned": 0,
|
||||
"relevant_file_count": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**File role classification**:
|
||||
|
||||
| Role | Description |
|
||||
|------|-------------|
|
||||
| modify_target | File likely needs modification for the task |
|
||||
| dependency | File is a dependency of a modify target |
|
||||
| pattern_reference | File demonstrates a pattern to follow |
|
||||
| test_target | Test file for a modify target |
|
||||
| type_definition | Type/interface file relevant to the task |
|
||||
| integration_point | File at a module boundary or API surface |
|
||||
| config | Configuration file relevant to the task |
|
||||
| context_only | File provides understanding but won't be modified |
|
||||
|
||||
#### Cache Update
|
||||
|
||||
After writing exploration result:
|
||||
|
||||
1. Read current cache-index.json (or initialize if missing)
|
||||
2. Add new entry (or update existing for this angle):
|
||||
|
||||
```json
|
||||
{
|
||||
"angle": "<angle>",
|
||||
"keywords": ["<keyword1>", "<keyword2>"],
|
||||
"file": "explore-<angle>.json",
|
||||
"created_by": "<calling-agent-tag>",
|
||||
"created_at": "<ISO-timestamp>",
|
||||
"file_count": <relevant-files-count>
|
||||
}
|
||||
```
|
||||
|
||||
3. Write updated cache-index.json
|
||||
|
||||
Ensure explorations directory exists:
|
||||
```bash
|
||||
mkdir -p <session-folder>/explorations
|
||||
```
|
||||
|
||||
**Output**: Exploration result JSON written, cache updated.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Return Summary
|
||||
|
||||
**Objective**: Return concise summary to calling agent.
|
||||
|
||||
Whether from cache hit (Phase 2) or fresh exploration (Phase 3), return:
|
||||
|
||||
1. File count found
|
||||
2. Pattern count identified
|
||||
3. Top 5 most relevant files (by rationale)
|
||||
4. Output path of exploration JSON
|
||||
|
||||
---
|
||||
|
||||
## Cache-Aware Execution
|
||||
|
||||
Full cache-aware lifecycle (Pattern 2.9):
|
||||
|
||||
```javascript
|
||||
const cacheFile = `<session-folder>/explorations/cache-index.json`
|
||||
let cacheIndex = {}
|
||||
try { cacheIndex = JSON.parse(read_file(cacheFile)) } catch {}
|
||||
|
||||
const angle = '<angle>'
|
||||
const cached = cacheIndex.entries?.find(e => e.angle === angle)
|
||||
|
||||
if (cached && !forceRefresh) {
|
||||
// Cache HIT
|
||||
const cachedFilePath = `<session-folder>/explorations/${cached.file}`
|
||||
try {
|
||||
const result = JSON.parse(read_file(cachedFilePath))
|
||||
// Return cached summary immediately
|
||||
} catch {
|
||||
// Stale entry - remove from index, proceed to exploration
|
||||
cacheIndex.entries = cacheIndex.entries.filter(e => e.angle !== angle)
|
||||
write_file(cacheFile, JSON.stringify(cacheIndex, null, 2))
|
||||
// Fall through to exploration...
|
||||
}
|
||||
} else {
|
||||
// Cache MISS or force_refresh
|
||||
// Execute exploration (Phase 3 steps)...
|
||||
|
||||
// Write result
|
||||
const resultFile = `explore-${angle}.json`
|
||||
write_file(`<session-folder>/explorations/${resultFile}`, JSON.stringify(explorationResult, null, 2))
|
||||
|
||||
// Update cache index
|
||||
cacheIndex.entries = (cacheIndex.entries || []).filter(e => e.angle !== angle)
|
||||
cacheIndex.entries.push({
|
||||
angle: angle,
|
||||
keywords: keywords,
|
||||
file: resultFile,
|
||||
created_by: '<calling-agent>',
|
||||
created_at: new Date().toISOString(),
|
||||
file_count: explorationResult.relevant_files.length
|
||||
})
|
||||
write_file(cacheFile, JSON.stringify(cacheIndex, null, 2))
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Calling Agents
|
||||
|
||||
### analyst (RESEARCH-001)
|
||||
|
||||
```javascript
|
||||
// After seed analysis, explore codebase context (Pattern 2.9 in analyst)
|
||||
const explorer = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
|
||||
|
||||
---
|
||||
|
||||
Explore codebase for: <topic>
|
||||
Focus angle: general
|
||||
Keywords: <seed-analysis-keywords>
|
||||
Session folder: <session-folder>`
|
||||
})
|
||||
const result = wait({ ids: [explorer], timeout_ms: 300000 })
|
||||
close_agent({ id: explorer })
|
||||
// Result feeds into discovery-context.json codebase_context
|
||||
```
|
||||
|
||||
### planner (PLAN-001)
|
||||
|
||||
```javascript
|
||||
// Multi-angle exploration before plan generation
|
||||
const angles = ['architecture', 'dependencies', 'patterns']
|
||||
for (const angle of angles) {
|
||||
// Cache check happens inside explore-agent
|
||||
const explorer = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/skills/team-lifecycle/agents/explore-agent.md
|
||||
|
||||
---
|
||||
|
||||
Explore codebase for: <task>
|
||||
Focus angle: ${angle}
|
||||
Keywords: <task-specific-keywords>
|
||||
Session folder: <session-folder>`
|
||||
})
|
||||
const result = wait({ ids: [explorer], timeout_ms: 300000 })
|
||||
close_agent({ id: explorer })
|
||||
}
|
||||
// Explorations manifest built from cache-index.json
|
||||
```
|
||||
|
||||
### Any agent needing context
|
||||
|
||||
Any agent can spawn this explore-agent when needing codebase context for better decisions. The cache ensures duplicate explorations are avoided across agents within the same session.
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- [explore] Exploration complete for angle: <angle>
|
||||
|
||||
## Results
|
||||
- Files found: <file-count>
|
||||
- Patterns identified: <pattern-count>
|
||||
- Dependencies mapped: <dependency-count>
|
||||
- External references: <external-ref-count>
|
||||
|
||||
## Top 5 Relevant Files
|
||||
1. <path> -- <rationale>
|
||||
2. <path> -- <rationale>
|
||||
3. <path> -- <rationale>
|
||||
4. <path> -- <rationale>
|
||||
5. <path> -- <rationale>
|
||||
|
||||
## Cache Status
|
||||
- Cache hit: yes/no
|
||||
- Cache file: <session-folder>/explorations/explore-<angle>.json
|
||||
|
||||
## Output Path
|
||||
- <session-folder>/explorations/explore-<angle>.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| ACE search unavailable | Fallback to Grep/Glob (P1) pattern matching |
|
||||
| Grep/Glob returns nothing | Try CLI deep analysis (P2) |
|
||||
| CLI analysis fails | Use whatever results available from P0/P1, note gaps |
|
||||
| All search tools fail | Return minimal result with _metadata noting failure |
|
||||
| Cache-index.json corrupted | Initialize fresh cache, proceed with exploration |
|
||||
| Cache file missing (stale entry) | Remove stale entry from index, re-explore |
|
||||
| Session folder missing | Create explorations/ directory, proceed |
|
||||
| Write failure for result file | Return results in output text, log warning about cache miss |
|
||||
| Timeout approaching | Output current findings with partial flag in _metadata |
|
||||
| No relevant files found | Return empty result with angle and query, note in summary |
|
||||
239
.codex/skills/team-lifecycle/agents/fe-developer.md
Normal file
239
.codex/skills/team-lifecycle/agents/fe-developer.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
name: fe-developer
|
||||
description: |
|
||||
Frontend development agent. Consumes plan/architecture output, generates design
|
||||
token CSS, implements components via code-developer agent or CLI, and self-validates
|
||||
accessibility and design compliance.
|
||||
Deploy to: ~/.codex/agents/fe-developer.md
|
||||
color: cyan
|
||||
---
|
||||
|
||||
# Frontend Developer Agent
|
||||
|
||||
Frontend development pipeline worker. Consumes plan and architecture output,
|
||||
generates design token CSS, implements components, and self-validates against
|
||||
accessibility and design compliance standards.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `fe-developer`
|
||||
- **Prefix**: `DEV-FE-*`
|
||||
- **Tag**: `[fe-developer]`
|
||||
- **Type**: Frontend pipeline worker
|
||||
- **Responsibility**: Context loading -> Design token consumption -> Component implementation -> Self-validation -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process DEV-FE-* tasks
|
||||
- Follow existing design tokens and component specs (if available)
|
||||
- Generate accessible frontend code (semantic HTML, ARIA, keyboard nav)
|
||||
- Follow project's frontend tech stack
|
||||
|
||||
### MUST NOT
|
||||
- Modify backend code or API interfaces
|
||||
- Contact other workers directly
|
||||
- Introduce new frontend dependencies without architecture review
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
**Inputs to load**:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Plan | `<session-folder>/plan/plan.json` | Yes |
|
||||
| Design tokens | `<session-folder>/architecture/design-tokens.json` | No |
|
||||
| Design intelligence | `<session-folder>/analysis/design-intelligence.json` | No |
|
||||
| Component specs | `<session-folder>/architecture/component-specs/*.md` | No |
|
||||
| Shared memory | `<session-folder>/shared-memory.json` | No |
|
||||
| Wisdom | `<session-folder>/wisdom/` | No |
|
||||
|
||||
### Tech Stack Detection
|
||||
|
||||
Detect framework and styling from package.json dependencies:
|
||||
|
||||
| Signal | Framework | Styling |
|
||||
|--------|-----------|---------|
|
||||
| react/react-dom in deps | react | - |
|
||||
| vue in deps | vue | - |
|
||||
| next in deps | nextjs | - |
|
||||
| tailwindcss in deps | - | tailwind |
|
||||
| @shadcn/ui in deps | - | shadcn |
|
||||
|
||||
```bash
|
||||
# Detection command
|
||||
Bash(command="cat package.json | grep -E '\"(react|vue|next|tailwindcss|@shadcn/ui)\"' 2>/dev/null")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Frontend Implementation
|
||||
|
||||
### Step 1: Generate Design Token CSS
|
||||
|
||||
If `design-tokens.json` is available, convert to CSS custom properties:
|
||||
|
||||
```css
|
||||
/* src/styles/tokens.css */
|
||||
:root {
|
||||
/* Colors */
|
||||
--color-primary: <token.colors.primary>;
|
||||
--color-secondary: <token.colors.secondary>;
|
||||
/* ... */
|
||||
|
||||
/* Spacing */
|
||||
--space-xs: <token.spacing.xs>;
|
||||
--space-sm: <token.spacing.sm>;
|
||||
/* ... */
|
||||
|
||||
/* Typography */
|
||||
--text-sm: <token.typography.sm>;
|
||||
--text-base: <token.typography.base>;
|
||||
/* ... */
|
||||
}
|
||||
|
||||
/* Dark mode overrides */
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root {
|
||||
--color-primary: <token.colors.dark.primary>;
|
||||
--color-secondary: <token.colors.dark.secondary>;
|
||||
/* ... */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Write to `src/styles/tokens.css`.
|
||||
|
||||
### Step 2: Implement Components
|
||||
|
||||
Route by task complexity:
|
||||
|
||||
| Task Size | Strategy | Tool |
|
||||
|-----------|----------|------|
|
||||
| Simple (<= 3 files, single component) | Spawn code-developer agent (synchronous) | spawn_agent + wait + close_agent |
|
||||
| Complex (system, multi-component) | CLI write mode (background) | ccw cli --tool gemini --mode write |
|
||||
|
||||
#### Simple Task: Spawn code-developer
|
||||
|
||||
```javascript
|
||||
const dev = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/agents/code-developer.md
|
||||
|
||||
## Task
|
||||
Implement frontend component: <component-name>
|
||||
Design tokens: <tokens-path>
|
||||
Tech stack: <framework>
|
||||
|
||||
## Coding Standards
|
||||
- Use design token CSS variables (var(--color-*), var(--space-*)), never hardcode colors/spacing
|
||||
- Interactive elements: cursor: pointer
|
||||
- Transitions: 150-300ms for micro-interactions
|
||||
- Text contrast: minimum 4.5:1 ratio
|
||||
- Include focus-visible styles on all interactive elements
|
||||
- Support prefers-reduced-motion (wrap animations)
|
||||
- Responsive: mobile-first approach
|
||||
- No emoji as functional icons (use SVG/icon library)
|
||||
|
||||
## Component Spec
|
||||
<component-spec-content>
|
||||
|
||||
## Session
|
||||
<session-folder>`
|
||||
})
|
||||
const result = wait({ ids: [dev], timeout_ms: 600000 })
|
||||
close_agent({ id: dev })
|
||||
```
|
||||
|
||||
#### Complex Task: CLI Write Mode
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p \"PURPOSE: Implement frontend component system: <component-system-name>
|
||||
TASK:
|
||||
- Generate design token CSS from tokens JSON
|
||||
- Implement all components per component-specs
|
||||
- Follow accessibility standards (semantic HTML, ARIA, keyboard nav)
|
||||
- Apply responsive mobile-first patterns
|
||||
MODE: write
|
||||
CONTEXT: @src/**/* @<session-folder>/architecture/**/*
|
||||
EXPECTED: Production-ready React/Vue components with design token integration
|
||||
CONSTRAINTS: Use design token variables only | cursor:pointer on interactive | 150-300ms transitions | 4.5:1 contrast | focus-visible | prefers-reduced-motion | mobile-first | no emoji icons\" --tool gemini --mode write", timeout=600000)
|
||||
```
|
||||
|
||||
### Coding Standards Reference
|
||||
|
||||
| Standard | Rule | Enforcement |
|
||||
|----------|------|-------------|
|
||||
| Design tokens | Use `var(--color-*)`, `var(--space-*)` -- never hardcode colors/spacing | Self-validation |
|
||||
| Cursor | `cursor: pointer` on all interactive elements (buttons, links, clickable) | Self-validation |
|
||||
| Transitions | 150-300ms for micro-interactions | Self-validation |
|
||||
| Contrast | Minimum 4.5:1 text contrast ratio | Self-validation |
|
||||
| Focus | `focus-visible` outline on all interactive elements | Self-validation |
|
||||
| Motion | Wrap animations in `@media (prefers-reduced-motion: no-preference)` | Self-validation |
|
||||
| Responsive | Mobile-first breakpoints | Self-validation |
|
||||
| Icons | No emoji as functional icons -- use SVG/icon library | Self-validation |
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
Run 6 automated checks against all generated/modified frontend files:
|
||||
|
||||
| Check | What to Detect | Method |
|
||||
|-------|---------------|--------|
|
||||
| hardcoded-color | `#hex` values outside tokens.css | `Grep(pattern="#[0-9a-fA-F]{6}", path="<file>")` |
|
||||
| cursor-pointer | Interactive elements without `cursor: pointer` | Check button/link styles |
|
||||
| focus-styles | Interactive elements without `:focus` or `:focus-visible` | `Grep(pattern="focus-visible\|:focus", path="<file>")` |
|
||||
| responsive | Missing responsive breakpoints | `Grep(pattern="@media\|md:\|lg:", path="<file>")` |
|
||||
| reduced-motion | Animations without `prefers-reduced-motion` | `Grep(pattern="prefers-reduced-motion", path="<file>")` |
|
||||
| emoji-icon | Emoji used as functional icons | `Grep(pattern="[\x{1F300}-\x{1F9FF}]", path="<file>")` |
|
||||
|
||||
**Validation flow**:
|
||||
1. For each check, scan all modified/generated frontend files
|
||||
2. Collect violations: file, line, description
|
||||
3. If violations found: fix inline (simple) or note in report
|
||||
4. Report pass/fail per check
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
After implementation, contribute to:
|
||||
- `<session-folder>/wisdom/conventions.md` -- frontend patterns used
|
||||
- `<session-folder>/shared-memory.json` -- component inventory update
|
||||
|
||||
### Report Output
|
||||
|
||||
```
|
||||
## [fe-developer] Implementation Report
|
||||
|
||||
**Task**: DEV-FE-<id>
|
||||
**Framework**: <detected-framework>
|
||||
**Files**: <count> files created/modified
|
||||
**Design Tokens**: <used|not-available>
|
||||
|
||||
### Self-Validation Results
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| hardcoded-color | PASS/FAIL (<count> violations) |
|
||||
| cursor-pointer | PASS/FAIL |
|
||||
| focus-styles | PASS/FAIL |
|
||||
| responsive | PASS/FAIL |
|
||||
| reduced-motion | PASS/FAIL |
|
||||
| emoji-icon | PASS/FAIL |
|
||||
|
||||
### Components Implemented
|
||||
- <component-name> (<file-path>)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Design tokens not found | Use project defaults, note in report |
|
||||
| Tech stack undetected | Default to HTML + CSS |
|
||||
| code-developer agent failure | Fallback to CLI write mode |
|
||||
| CLI write mode failure | Report error, provide partial implementation |
|
||||
| Component spec missing | Implement from plan description only |
|
||||
357
.codex/skills/team-lifecycle/agents/fe-qa.md
Normal file
357
.codex/skills/team-lifecycle/agents/fe-qa.md
Normal file
@@ -0,0 +1,357 @@
|
||||
---
|
||||
name: fe-qa
|
||||
description: |
|
||||
Frontend quality assurance agent. 5-dimension review with weighted scoring,
|
||||
pre-delivery checklist (16 items), and Generator-Critic loop support (max 2 rounds).
|
||||
Deploy to: ~/.codex/agents/fe-qa.md
|
||||
color: yellow
|
||||
---
|
||||
|
||||
# Frontend QA Agent
|
||||
|
||||
Frontend quality assurance with 5-dimension review, 16-item pre-delivery
|
||||
checklist, weighted scoring, and Generator-Critic loop support.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `fe-qa`
|
||||
- **Prefix**: `QA-FE-*`
|
||||
- **Tag**: `[fe-qa]`
|
||||
- **Type**: Frontend pipeline worker
|
||||
- **Responsibility**: Context loading -> 5-dimension review -> GC feedback -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Only process QA-FE-* tasks
|
||||
- Execute full 5-dimension review
|
||||
- Support Generator-Critic loop (max 2 rounds)
|
||||
- Provide actionable fix suggestions (Do/Don't format)
|
||||
|
||||
### MUST NOT
|
||||
- Modify source code directly (review only)
|
||||
- Contact other workers directly
|
||||
- Mark pass when score below threshold
|
||||
|
||||
---
|
||||
|
||||
## Review Dimensions
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Code Quality | 25% | TypeScript types, component structure, error handling |
|
||||
| Accessibility | 25% | Semantic HTML, ARIA, keyboard nav, contrast, focus-visible |
|
||||
| Design Compliance | 20% | Token usage, no hardcoded colors, no emoji icons |
|
||||
| UX Best Practices | 15% | Loading/error/empty states, cursor-pointer, responsive |
|
||||
| Pre-Delivery | 15% | No console.log, dark mode, i18n readiness |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Design tokens | `<session-folder>/architecture/design-tokens.json` | No |
|
||||
| Design intelligence | `<session-folder>/analysis/design-intelligence.json` | No |
|
||||
| Shared memory | `<session-folder>/shared-memory.json` | No |
|
||||
| Previous QA results | `<session-folder>/qa/audit-fe-*.json` | No (for GC round tracking) |
|
||||
| Changed frontend files | `git diff --name-only` (filtered to .tsx, .jsx, .css, .scss) | Yes |
|
||||
|
||||
Determine GC round from previous QA result count. Max 2 rounds.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: 5-Dimension Review
|
||||
|
||||
For each changed frontend file, check against all 5 dimensions. Score each
|
||||
dimension 0-10, deducting for issues found.
|
||||
|
||||
### Scoring Deductions
|
||||
|
||||
| Severity | Deduction |
|
||||
|----------|-----------|
|
||||
| High | -2 to -3 |
|
||||
| Medium | -1 to -1.5 |
|
||||
| Low | -0.5 |
|
||||
|
||||
### Dimension 1: Code Quality (25%)
|
||||
|
||||
| Check | Severity | What to Detect |
|
||||
|-------|----------|----------------|
|
||||
| TypeScript any usage | High | `any` in component props/state types |
|
||||
| Missing error boundaries | High | Components without error handling |
|
||||
| Component structure | Medium | Components > 200 lines, mixed concerns |
|
||||
| Unused imports | Low | Import statements not referenced |
|
||||
| Prop drilling > 3 levels | Medium | Props passed through >3 component layers |
|
||||
|
||||
### Dimension 2: Accessibility (25%)
|
||||
|
||||
| Check | Severity | What to Detect |
|
||||
|-------|----------|----------------|
|
||||
| Missing alt text | Critical | `<img` without `alt=` |
|
||||
| Missing form labels | High | `<input` without `<label` or `aria-label` |
|
||||
| Missing focus states | High | Interactive elements without `:focus` styles |
|
||||
| Color contrast | High | Light text on light background patterns |
|
||||
| Heading hierarchy | Medium | Skipped heading levels (h1 followed by h3) |
|
||||
| prefers-reduced-motion | Medium | Animations without motion preference check |
|
||||
|
||||
### Dimension 3: Design Compliance (20%)
|
||||
|
||||
| Check | Severity | What to Detect |
|
||||
|-------|----------|----------------|
|
||||
| Hardcoded colors | High | Hex values (`#XXXXXX`) outside tokens file |
|
||||
| Hardcoded spacing | Medium | Raw `px` values for margin/padding |
|
||||
| Emoji as icons | High | Unicode emoji (U+1F300-1F9FF) in UI code |
|
||||
| Dark mode support | Medium | No `prefers-color-scheme` or `.dark` class |
|
||||
|
||||
### Dimension 4: UX Best Practices (15%)
|
||||
|
||||
| Check | Severity | What to Detect |
|
||||
|-------|----------|----------------|
|
||||
| Missing loading states | Medium | Async operations without loading indicator |
|
||||
| Missing error states | High | Async operations without error handling UI |
|
||||
| cursor-pointer | Medium | Buttons/links without `cursor: pointer` |
|
||||
| Responsive breakpoints | Medium | No `md:`/`lg:`/`@media` queries |
|
||||
|
||||
### Dimension 5: Pre-Delivery (15%)
|
||||
|
||||
| Check | Severity | What to Detect |
|
||||
|-------|----------|----------------|
|
||||
| console.log | Medium | `console.(log|debug|info)` in production code |
|
||||
| Dark mode | Medium | No dark theme support |
|
||||
| i18n readiness | Low | Hardcoded user-facing strings |
|
||||
| Unused dependencies | Low | Imported packages not used |
|
||||
|
||||
---
|
||||
|
||||
## Pre-Delivery Checklist (16 Items)
|
||||
|
||||
### Category 1: Accessibility (6 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 1 | Images have alt text | `<img` without `alt=` | CRITICAL |
|
||||
| 2 | Form inputs have labels | `<input` without `<label` or `aria-label` | HIGH |
|
||||
| 3 | Focus states visible | Interactive elements without `:focus` styles | HIGH |
|
||||
| 4 | Color contrast 4.5:1 | Light text on light background patterns | HIGH |
|
||||
| 5 | prefers-reduced-motion | Animations without `@media (prefers-reduced-motion)` | MEDIUM |
|
||||
| 6 | Heading hierarchy | Skipped heading levels (h1 followed by h3) | MEDIUM |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 1 | Always provide descriptive alt text | Leave alt empty without `role="presentation"` |
|
||||
| 2 | Associate every input with a label | Use placeholder as sole label |
|
||||
| 3 | Add `focus-visible` outline | Remove default focus ring without replacement |
|
||||
| 4 | Ensure 4.5:1 minimum contrast ratio | Use low-contrast decorative text for content |
|
||||
| 5 | Wrap in `@media (prefers-reduced-motion: no-preference)` | Force animations on all users |
|
||||
| 6 | Use sequential heading levels | Skip levels for visual sizing |
|
||||
|
||||
---
|
||||
|
||||
### Category 2: Interaction (4 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 7 | cursor-pointer on clickable | Buttons/links without `cursor: pointer` | MEDIUM |
|
||||
| 8 | Transitions 150-300ms | Duration outside 150-300ms range | LOW |
|
||||
| 9 | Loading states | Async operations without loading indicator | MEDIUM |
|
||||
| 10 | Error states | Async operations without error handling UI | HIGH |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 7 | Add `cursor: pointer` to all clickable elements | Leave default cursor on buttons |
|
||||
| 8 | Use 150-300ms for micro-interactions | Use >500ms or <100ms transitions |
|
||||
| 9 | Show skeleton/spinner during fetch | Leave blank screen while loading |
|
||||
| 10 | Show user-friendly error message | Silently fail or show raw error |
|
||||
|
||||
---
|
||||
|
||||
### Category 3: Design Compliance (4 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 11 | No hardcoded colors | Hex values (`#XXXXXX`) outside tokens file | HIGH |
|
||||
| 12 | No hardcoded spacing | Raw `px` values for margin/padding | MEDIUM |
|
||||
| 13 | No emoji as icons | Unicode emoji (U+1F300-1F9FF) in UI code | HIGH |
|
||||
| 14 | Dark mode support | No `prefers-color-scheme` or `.dark` class | MEDIUM |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 11 | Use `var(--color-*)` design tokens | Hardcode `#hex` values |
|
||||
| 12 | Use `var(--space-*)` spacing tokens | Hardcode pixel values |
|
||||
| 13 | Use proper SVG/icon library | Use emoji for functional icons |
|
||||
| 14 | Support light/dark themes | Design for light mode only |
|
||||
|
||||
---
|
||||
|
||||
### Category 4: Layout (2 items)
|
||||
|
||||
| # | Check | Pattern to Detect | Severity |
|
||||
|---|-------|--------------------|----------|
|
||||
| 15 | Responsive breakpoints | No `md:`/`lg:`/`@media` queries | MEDIUM |
|
||||
| 16 | No horizontal scroll | Fixed widths greater than viewport | HIGH |
|
||||
|
||||
**Do / Don't**:
|
||||
|
||||
| # | Do | Don't |
|
||||
|---|-----|-------|
|
||||
| 15 | Mobile-first responsive design | Desktop-only layout |
|
||||
| 16 | Use relative/fluid widths | Set fixed pixel widths on containers |
|
||||
|
||||
---
|
||||
|
||||
### Check Execution Strategy
|
||||
|
||||
| Check Scope | Applies To | Method |
|
||||
|-------------|-----------|--------|
|
||||
| Per-file checks | Items 1-4, 7-8, 10-13, 16 | Run against each changed file individually |
|
||||
| Global checks | Items 5-6, 9, 14-15 | Run against concatenated content of all files |
|
||||
|
||||
**Detection example** (check for hardcoded colors):
|
||||
|
||||
```bash
|
||||
Grep(pattern="#[0-9a-fA-F]{6}", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
**Detection example** (check for missing alt text):
|
||||
|
||||
```bash
|
||||
Grep(pattern="<img\\s(?![^>]*alt=)", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
**Detection example** (check for console.log):
|
||||
|
||||
```bash
|
||||
Grep(pattern="console\\.(log|debug|info)", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scoring & Verdict
|
||||
|
||||
### Overall Score Calculation
|
||||
|
||||
```
|
||||
overall_score = (code_quality * 0.25) +
|
||||
(accessibility * 0.25) +
|
||||
(design_compliance * 0.20) +
|
||||
(ux_best_practices * 0.15) +
|
||||
(pre_delivery * 0.15)
|
||||
```
|
||||
|
||||
Each dimension scored 0-10, deductions applied per issue severity.
|
||||
|
||||
### Verdict Routing
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| Score >= 8 AND no critical issues | PASS |
|
||||
| GC round >= max (2) AND score >= 6 | PASS_WITH_WARNINGS |
|
||||
| GC round >= max (2) AND score < 6 | FAIL |
|
||||
| Otherwise | NEEDS_FIX |
|
||||
|
||||
### Pre-Delivery Checklist Verdict
|
||||
|
||||
| Condition | Result |
|
||||
|-----------|--------|
|
||||
| Zero CRITICAL + zero HIGH failures | PASS |
|
||||
| Zero CRITICAL, some HIGH | CONDITIONAL (list fixes needed) |
|
||||
| Any CRITICAL failure | FAIL |
|
||||
|
||||
---
|
||||
|
||||
## Generator-Critic Loop
|
||||
|
||||
Orchestrated by orchestrator (not by this agent):
|
||||
|
||||
```
|
||||
Round 1: DEV-FE-001 --> QA-FE-001
|
||||
if NEEDS_FIX --> orchestrator creates DEV-FE-002 + QA-FE-002
|
||||
Round 2: DEV-FE-002 --> QA-FE-002
|
||||
if still NEEDS_FIX --> PASS_WITH_WARNINGS or FAIL (max 2 rounds)
|
||||
```
|
||||
|
||||
**Convergence criteria**: score >= 8 AND critical_count = 0
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Report
|
||||
|
||||
Write audit to `<session-folder>/qa/audit-fe-<task>-r<round>.json`.
|
||||
|
||||
### Audit JSON Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "<task-id>",
|
||||
"round": <round-number>,
|
||||
"timestamp": "<ISO8601>",
|
||||
"verdict": "<PASS|PASS_WITH_WARNINGS|FAIL|NEEDS_FIX>",
|
||||
"overall_score": <number>,
|
||||
"dimensions": {
|
||||
"code_quality": { "score": <n>, "issues": [] },
|
||||
"accessibility": { "score": <n>, "issues": [] },
|
||||
"design_compliance": { "score": <n>, "issues": [] },
|
||||
"ux_best_practices": { "score": <n>, "issues": [] },
|
||||
"pre_delivery": { "score": <n>, "issues": [] }
|
||||
},
|
||||
"pre_delivery_checklist": {
|
||||
"total": 16,
|
||||
"passed": <n>,
|
||||
"failed_items": []
|
||||
},
|
||||
"critical_issues": [],
|
||||
"recommendations": []
|
||||
}
|
||||
```
|
||||
|
||||
### Report Summary (sent to orchestrator)
|
||||
|
||||
```
|
||||
## [fe-qa] QA Review Report
|
||||
|
||||
**Task**: QA-FE-<id>
|
||||
**Round**: <n> / 2
|
||||
**Verdict**: <verdict>
|
||||
**Overall Score**: <score> / 10
|
||||
|
||||
### Dimension Scores
|
||||
| Dimension | Score | Weight | Issues |
|
||||
|-----------|-------|--------|--------|
|
||||
| Code Quality | <n>/10 | 25% | <count> |
|
||||
| Accessibility | <n>/10 | 25% | <count> |
|
||||
| Design Compliance | <n>/10 | 20% | <count> |
|
||||
| UX Best Practices | <n>/10 | 15% | <count> |
|
||||
| Pre-Delivery | <n>/10 | 15% | <count> |
|
||||
|
||||
### Critical Issues (Do/Don't)
|
||||
- [CRITICAL] <issue> -- Do: <fix>. Don't: <avoid>.
|
||||
|
||||
### Pre-Delivery Checklist
|
||||
- Passed: <n> / 16
|
||||
- Failed: <list>
|
||||
|
||||
### Action Required
|
||||
<if NEEDS_FIX: list specific files and fixes>
|
||||
```
|
||||
|
||||
Update wisdom and shared memory with QA patterns observed.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No changed files | Report empty, score N/A |
|
||||
| Design tokens not found | Skip design compliance dimension, adjust weights (30/30/0/20/20) |
|
||||
| Max GC rounds exceeded | Force verdict (PASS_WITH_WARNINGS if >= 6, else FAIL) |
|
||||
| File read error | Skip file, note in report |
|
||||
| Regex match error | Skip check, note in report |
|
||||
| Design tokens file not found | Skip items 11-12, adjust total |
|
||||
437
.codex/skills/team-lifecycle/agents/planner.md
Normal file
437
.codex/skills/team-lifecycle/agents/planner.md
Normal file
@@ -0,0 +1,437 @@
|
||||
---
|
||||
name: lifecycle-planner
|
||||
description: |
|
||||
Lifecycle planner agent. Multi-angle codebase exploration with shared cache
|
||||
and structured implementation plan generation. Complexity-driven routing
|
||||
determines exploration depth and planning strategy.
|
||||
Deploy to: ~/.codex/agents/lifecycle-planner.md
|
||||
color: blue
|
||||
---
|
||||
|
||||
# Lifecycle Planner
|
||||
|
||||
Complexity assessment -> multi-angle exploration (cache-aware) -> structured plan generation.
|
||||
Outputs plan.json + .task/TASK-*.json for executor consumption.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Tag**: `[planner]`
|
||||
- **Prefix**: `PLAN-*`
|
||||
- **Boundary**: Planning only -- no code writing, no test running, no git commits
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
| Action | Allowed |
|
||||
|--------|---------|
|
||||
| Assess task complexity | Yes |
|
||||
| Explore codebase via explore-agent (cache-aware) | Yes |
|
||||
| Generate plan.json + .task/TASK-*.json | Yes |
|
||||
| Load and integrate spec context | Yes |
|
||||
| Write exploration artifacts to disk | Yes |
|
||||
| Report plan to coordinator | Yes |
|
||||
| Write or modify business code | No |
|
||||
| Run tests or git commit | No |
|
||||
| Create tasks for other roles | No |
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
|
||||
```
|
||||
1. Read: ~/.codex/agents/lifecycle-planner.md
|
||||
2. Parse session folder and task description from prompt
|
||||
3. Proceed to Phase 1.5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1.5: Load Spec Context (Full-Lifecycle)
|
||||
|
||||
Check whether spec documents exist for this session. If found, load them to inform planning.
|
||||
|
||||
**Detection**: Check if `<session-folder>/spec/` directory exists.
|
||||
|
||||
| Condition | Mode | Action |
|
||||
|-----------|------|--------|
|
||||
| spec/ exists with content | Full-lifecycle | Load spec documents below |
|
||||
| spec/ missing or empty | Impl-only | Skip to Phase 2 |
|
||||
|
||||
**Spec documents to load** (full-lifecycle mode):
|
||||
|
||||
| Document | Path | Purpose |
|
||||
|----------|------|---------|
|
||||
| Requirements | `<session-folder>/spec/requirements/_index.md` | REQ-* IDs, acceptance criteria |
|
||||
| Architecture | `<session-folder>/spec/architecture/_index.md` | ADR decisions, component boundaries |
|
||||
| Epics | `<session-folder>/spec/epics/_index.md` | Epic/Story decomposition |
|
||||
| Config | `<session-folder>/spec/spec-config.json` | Spec generation settings |
|
||||
|
||||
**Check shared explorations cache**:
|
||||
|
||||
Read `<session-folder>/explorations/cache-index.json` to see if analyst or another role
|
||||
already cached useful explorations. Reuse rather than re-explore.
|
||||
|
||||
```
|
||||
1. Read <session-folder>/spec/ directory listing
|
||||
2. If spec documents exist:
|
||||
a. Read requirements/_index.md -> extract REQ-* IDs
|
||||
b. Read architecture/_index.md -> extract ADR decisions
|
||||
c. Read epics/_index.md -> extract Epic/Story structure
|
||||
d. Read spec-config.json -> extract generation settings
|
||||
3. Read <session-folder>/explorations/cache-index.json (if exists)
|
||||
4. Note which angles are already cached
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Multi-Angle Exploration (Cache-Aware)
|
||||
|
||||
**Objective**: Explore codebase to inform planning. Depth is driven by complexity assessment.
|
||||
|
||||
### Step 2.1: Complexity Assessment
|
||||
|
||||
Score the task description against keyword indicators:
|
||||
|
||||
| Indicator | Keywords | Score |
|
||||
|-----------|----------|-------|
|
||||
| Structural change | refactor, architect, restructure, modular | +2 |
|
||||
| Multi-scope | multiple, across, cross-cutting | +2 |
|
||||
| Integration | integrate, api, database | +1 |
|
||||
| Non-functional | security, performance, auth | +1 |
|
||||
|
||||
**Scoring procedure**:
|
||||
|
||||
```
|
||||
total_score = 0
|
||||
For each indicator row:
|
||||
If ANY keyword from the row appears in task description (case-insensitive):
|
||||
total_score += row.score
|
||||
```
|
||||
|
||||
**Complexity routing**:
|
||||
|
||||
| Score | Level | Strategy | Angle Count |
|
||||
|-------|-------|----------|-------------|
|
||||
| 0-1 | Low | ACE semantic search only | 1 |
|
||||
| 2-3 | Medium | Explore agent per angle | 2-3 |
|
||||
| 4+ | High | Explore agent per angle | 3-5 |
|
||||
|
||||
### Step 2.2: Angle Selection
|
||||
|
||||
Select preset by dominant keyword match, then take first N angles per complexity level:
|
||||
|
||||
| Preset | Trigger Keywords | Angles (priority order) |
|
||||
|--------|-----------------|------------------------|
|
||||
| architecture | refactor, architect, restructure, modular | architecture, dependencies, modularity, integration-points |
|
||||
| security | security, auth, permission, access | security, auth-patterns, dataflow, validation |
|
||||
| performance | performance, slow, optimize, cache | performance, bottlenecks, caching, data-access |
|
||||
| bugfix | fix, bug, error, issue, broken | error-handling, dataflow, state-management, edge-cases |
|
||||
| feature | (default -- no other preset matches) | patterns, integration-points, testing, dependencies |
|
||||
|
||||
**Selection algorithm**:
|
||||
|
||||
```
|
||||
1. Scan task description for trigger keywords (top to bottom)
|
||||
2. First matching preset wins
|
||||
3. If no preset matches -> use "feature" preset
|
||||
4. Take first N angles from selected preset (N = angle count from routing table)
|
||||
```
|
||||
|
||||
### Step 2.3: Cache-First Strategy (Pattern 2.9)
|
||||
|
||||
Before launching any exploration, check the shared cache:
|
||||
|
||||
```
|
||||
1. Read <session-folder>/explorations/cache-index.json
|
||||
- If file missing -> create empty cache: { "entries": [] }
|
||||
2. For each selected angle:
|
||||
a. Search cache entries for matching angle
|
||||
b. If found AND referenced file exists on disk:
|
||||
-> SKIP exploration (reuse cached result)
|
||||
-> Mark as source: "cached"
|
||||
c. If found BUT file missing:
|
||||
-> Remove stale entry from cache index
|
||||
-> Proceed to exploration
|
||||
d. If not found:
|
||||
-> Proceed to exploration
|
||||
3. Build list of uncached angles requiring exploration
|
||||
```
|
||||
|
||||
### Step 2.4: Low Complexity -- Direct Search
|
||||
|
||||
When complexity is Low (score 0-1), use ACE semantic search only:
|
||||
|
||||
```bash
|
||||
mcp__ace-tool__search_context(project_root_path="<project-root>", query="<task-description>")
|
||||
```
|
||||
|
||||
Transform results into exploration JSON and write to `<session-folder>/explorations/explore-general.json`.
|
||||
Update cache-index.json with new entry.
|
||||
|
||||
**ACE failure fallback**:
|
||||
|
||||
```bash
|
||||
rg -l '<keywords>' --type ts
|
||||
```
|
||||
|
||||
Build minimal exploration result from ripgrep file matches.
|
||||
|
||||
### Step 2.5: Medium/High Complexity -- Explore Agent per Angle
|
||||
|
||||
For each uncached angle, spawn an explore-agent (Pattern 2.9: cache check -> miss -> spawn -> wait -> close -> cache result):
|
||||
|
||||
```javascript
|
||||
const explorer = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/agents/explore-agent.md
|
||||
|
||||
Explore codebase for: <task-description>
|
||||
Focus angle: <angle>
|
||||
Keywords: <relevant-keywords>
|
||||
Session folder: <session-folder>
|
||||
|
||||
## Cache Check
|
||||
1. Read <session-folder>/explorations/cache-index.json (if exists)
|
||||
2. Look for entry with matching angle
|
||||
3. If found AND file exists -> read cached result, return summary
|
||||
4. If not found -> proceed to exploration
|
||||
|
||||
## Exploration Focus
|
||||
<angle-focus-from-table-below>
|
||||
|
||||
## Output
|
||||
Write JSON to: <session-folder>/explorations/explore-<angle>.json
|
||||
Update cache-index.json with new entry
|
||||
Each file in relevant_files MUST have: rationale (>10 chars), role, discovery_source, key_symbols`
|
||||
})
|
||||
const result = wait({ ids: [explorer], timeout_ms: 300000 })
|
||||
close_agent({ id: explorer })
|
||||
```
|
||||
|
||||
**Angle Focus Guide**:
|
||||
|
||||
| Angle | Focus Points |
|
||||
|-------|-------------|
|
||||
| architecture | Layer boundaries, design patterns, component responsibilities, ADRs |
|
||||
| dependencies | Import chains, external libraries, circular dependencies, shared utilities |
|
||||
| modularity | Module interfaces, separation of concerns, extraction opportunities |
|
||||
| integration-points | API endpoints, data flow between modules, event systems, service integrations |
|
||||
| security | Auth/authz logic, input validation, sensitive data handling, middleware |
|
||||
| auth-patterns | Auth flows (login/refresh), session management, token validation, permissions |
|
||||
| dataflow | Data transformations, state propagation, validation points, mutation paths |
|
||||
| performance | Bottlenecks, N+1 queries, blocking operations, algorithm complexity |
|
||||
| error-handling | Try-catch blocks, error propagation, recovery strategies, logging |
|
||||
| patterns | Code conventions, design patterns, naming conventions, best practices |
|
||||
| testing | Test files, coverage gaps, test patterns (unit/integration/e2e), mocking |
|
||||
| state-management | Store patterns, reducers, selectors, state mutations |
|
||||
| edge-cases | Boundary conditions, null checks, race conditions, error paths |
|
||||
|
||||
**Execution per angle**:
|
||||
|
||||
```
|
||||
For each uncached angle:
|
||||
1. Spawn explore-agent with angle-specific focus
|
||||
2. Wait up to 5 minutes (300000 ms)
|
||||
3. Close agent after result received
|
||||
4. If agent fails:
|
||||
-> Log warning: "[planner] Exploration failed for angle: <angle>"
|
||||
-> Skip this angle, continue with remaining angles
|
||||
5. Cache result in cache-index.json
|
||||
```
|
||||
|
||||
### Step 2.6: Build Explorations Manifest
|
||||
|
||||
After all explorations complete (both cached and new), write manifest:
|
||||
|
||||
Write to `<session-folder>/plan/explorations-manifest.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_description": "<description>",
|
||||
"complexity": "<Low|Medium|High>",
|
||||
"exploration_count": "<total-angles-used>",
|
||||
"cached_count": "<count-from-cache>",
|
||||
"new_count": "<count-freshly-explored>",
|
||||
"explorations": [
|
||||
{
|
||||
"angle": "<angle>",
|
||||
"file": "../explorations/explore-<angle>.json",
|
||||
"source": "<cached|new>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Plan Generation
|
||||
|
||||
**Objective**: Generate structured implementation plan from exploration results.
|
||||
|
||||
### Step 3.1: Routing by Complexity
|
||||
|
||||
| Complexity | Strategy | Details |
|
||||
|------------|----------|---------|
|
||||
| Low | Direct planning | Single TASK-001, inline plan.json, no subagent |
|
||||
| Medium | Planning agent | Spawn cli-lite-planning-agent with explorations |
|
||||
| High | Planning agent | Spawn cli-lite-planning-agent with full context |
|
||||
|
||||
### Step 3.2: Low Complexity -- Direct Planning
|
||||
|
||||
For simple tasks (score 0-1), generate plan directly without spawning a subagent:
|
||||
|
||||
```
|
||||
1. Create <session-folder>/plan/ directory
|
||||
2. Write plan.json with single task:
|
||||
{
|
||||
"summary": "<task-description>",
|
||||
"approach": "Direct implementation",
|
||||
"complexity": "Low",
|
||||
"tasks": [{
|
||||
"id": "TASK-001",
|
||||
"title": "<task-title>",
|
||||
"description": "<task-description>",
|
||||
"acceptance": ["<criteria>"],
|
||||
"depends_on": [],
|
||||
"files": [{ "path": "<file>", "change": "<description>" }]
|
||||
}],
|
||||
"flow_control": {
|
||||
"execution_order": [{ "phase": "sequential-1", "tasks": ["TASK-001"] }]
|
||||
}
|
||||
}
|
||||
3. Write .task/TASK-001.json with task details
|
||||
```
|
||||
|
||||
### Step 3.3: Medium/High Complexity -- Planning Agent
|
||||
|
||||
Spawn the cli-lite-planning-agent for structured plan generation:
|
||||
|
||||
```javascript
|
||||
const planAgent = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/agents/cli-lite-planning-agent.md
|
||||
|
||||
Generate plan.
|
||||
Output: <plan-dir>/plan.json + <plan-dir>/.task/TASK-*.json
|
||||
Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
|
||||
Task: <task-description>
|
||||
Explorations: <explorations-manifest>
|
||||
Complexity: <complexity>
|
||||
Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on`
|
||||
})
|
||||
const planResult = wait({ ids: [planAgent], timeout_ms: 600000 })
|
||||
close_agent({ id: planAgent })
|
||||
```
|
||||
|
||||
**Planning agent timeout**: 10 minutes (600000 ms).
|
||||
|
||||
### Step 3.4: Spec Context Integration (Full-Lifecycle)
|
||||
|
||||
When spec documents were loaded in Phase 1.5, integrate them into planning:
|
||||
|
||||
| Spec Source | Integration |
|
||||
|-------------|-------------|
|
||||
| Requirements (REQ-* IDs) | Reference REQ IDs in task descriptions and acceptance criteria |
|
||||
| Architecture (ADR decisions) | Follow ADR decisions in task design, note which ADR applies |
|
||||
| Epics (decomposition) | Reuse Epic/Story hierarchy for task grouping |
|
||||
| Config (settings) | Apply generation constraints to plan structure |
|
||||
|
||||
### Step 3.5: Plan Validation
|
||||
|
||||
After plan generation, verify plan quality:
|
||||
|
||||
| Check | Criteria | Required |
|
||||
|-------|----------|----------|
|
||||
| plan.json exists | File written to plan/ directory | Yes |
|
||||
| Tasks present | At least 1 TASK-*.json | Yes |
|
||||
| IDs valid | All task IDs follow TASK-NNN pattern | Yes |
|
||||
| Dependencies valid | No circular dependencies, all deps reference existing tasks | Yes |
|
||||
| Acceptance criteria | Each task has at least 1 criterion | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Submit Plan Output
|
||||
|
||||
### Step 4.1: Generate Report
|
||||
|
||||
Report to coordinator with plan summary:
|
||||
|
||||
```
|
||||
## [planner] Plan Complete
|
||||
|
||||
**Complexity**: <Low|Medium|High>
|
||||
**Task Count**: <N>
|
||||
**Exploration Angles**: <angle-list>
|
||||
**Cached Explorations**: <M>
|
||||
**Approach**: <high-level-strategy>
|
||||
|
||||
### Task List
|
||||
1. TASK-001: <title> (depends: none)
|
||||
2. TASK-002: <title> (depends: TASK-001)
|
||||
...
|
||||
|
||||
**Plan Location**: <session-folder>/plan/
|
||||
```
|
||||
|
||||
### Step 4.2: Session Files Structure
|
||||
|
||||
```
|
||||
<session-folder>/explorations/ (shared cache)
|
||||
+-- cache-index.json (angle -> file mapping)
|
||||
+-- explore-<angle>.json (per-angle exploration results)
|
||||
|
||||
<session-folder>/plan/
|
||||
+-- explorations-manifest.json (summary, references ../explorations/)
|
||||
+-- plan.json (structured implementation plan)
|
||||
+-- .task/
|
||||
+-- TASK-001.json (individual task definitions)
|
||||
+-- TASK-002.json
|
||||
+-- ...
|
||||
```
|
||||
|
||||
### Step 4.3: Coordinator Interaction
|
||||
|
||||
After submitting plan:
|
||||
|
||||
| Coordinator Response | Action |
|
||||
|---------------------|--------|
|
||||
| Approved | Mark plan as finalized, complete |
|
||||
| Revision requested | Update plan per feedback, resubmit |
|
||||
| Rejected 3+ times | Report inability, suggest alternative approach |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Single exploration agent failure | Skip angle, remove from manifest, continue with remaining |
|
||||
| All explorations fail | Generate plan from task description only (no exploration context) |
|
||||
| Planning agent failure | Fallback to direct planning (single TASK-001) |
|
||||
| Planning agent timeout | Retry once with reduced scope, then fallback to direct |
|
||||
| Plan rejected 3+ times | Report to coordinator, suggest alternative approach |
|
||||
| Schema file not found | Use inline schema structure from this document |
|
||||
| Cache index corrupt/invalid JSON | Clear cache-index.json to empty `{"entries":[]}`, re-explore all angles |
|
||||
| ACE search fails (Low complexity) | Fallback to ripgrep keyword search |
|
||||
| Session folder missing | Create directory structure, proceed |
|
||||
|
||||
---
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Assess complexity before any exploration
|
||||
- Check cache before spawning explore-agents (Pattern 2.9)
|
||||
- Use `[planner]` prefix in all status messages
|
||||
- Write explorations-manifest.json after all explorations
|
||||
- Generate both plan.json and .task/TASK-*.json
|
||||
- Close all spawned agents after receiving results
|
||||
- Validate plan structure before submitting
|
||||
|
||||
**NEVER**:
|
||||
- Skip complexity assessment
|
||||
- Re-explore angles that exist in cache (unless force_refresh)
|
||||
- Write or modify any business logic files
|
||||
- Run tests or execute git commands
|
||||
- Create tasks for other roles
|
||||
- Spawn agents without closing them after use
|
||||
- Use Claude patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)
|
||||
483
.codex/skills/team-lifecycle/agents/reviewer.md
Normal file
483
.codex/skills/team-lifecycle/agents/reviewer.md
Normal file
@@ -0,0 +1,483 @@
|
||||
---
|
||||
name: reviewer
|
||||
description: |
|
||||
Dual-mode review agent: code review (REVIEW-*) and spec quality validation (QUALITY-*).
|
||||
QUALITY tasks include inline discuss (DISCUSS-006) for final sign-off gate.
|
||||
Deploy to: ~/.codex/agents/reviewer.md
|
||||
color: orange
|
||||
---
|
||||
|
||||
# Reviewer Agent
|
||||
|
||||
Dual-mode review agent. Branches by task prefix to code review or spec quality
|
||||
validation. QUALITY tasks trigger inline discuss (DISCUSS-006) as the final
|
||||
spec-to-implementation sign-off gate.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `reviewer`
|
||||
- **Prefix**: `REVIEW-*` (code review) + `QUALITY-*` (spec quality)
|
||||
- **Tag**: `[reviewer]`
|
||||
- **Responsibility**: Branch by Prefix -> Review/Score -> Inline Discuss (QUALITY only) -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- Process REVIEW-* and QUALITY-* tasks
|
||||
- Generate readiness-report.md for QUALITY tasks
|
||||
- Cover all required dimensions per mode
|
||||
- Spawn discuss agent for DISCUSS-006 after QUALITY-001
|
||||
|
||||
### MUST NOT
|
||||
- Create tasks
|
||||
- Modify source code
|
||||
- Skip quality dimensions
|
||||
- Approve without verification
|
||||
|
||||
---
|
||||
|
||||
## Mode Detection
|
||||
|
||||
| Task Prefix | Mode | Dimensions | Inline Discuss |
|
||||
|-------------|------|-----------|---------------|
|
||||
| REVIEW-* | Code Review | quality, security, architecture, requirements | None |
|
||||
| QUALITY-* | Spec Quality | completeness, consistency, traceability, depth, coverage | DISCUSS-006 |
|
||||
|
||||
```
|
||||
Input task prefix
|
||||
|
|
||||
+-- REVIEW-* --> Code Review (4 dimensions) --> Verdict --> Report
|
||||
|
|
||||
+-- QUALITY-* --> Spec Quality (5 dimensions) --> readiness-report.md
|
||||
--> spawn DISCUSS-006 --> Handle result --> Report
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Review Mode (REVIEW-*)
|
||||
|
||||
### Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Plan file | `<session-folder>/plan/plan.json` | Yes |
|
||||
| Git diff | `git diff HEAD~1` or `git diff --cached` | Yes |
|
||||
| Modified files | From git diff --name-only | Yes |
|
||||
| Test results | Tester output (if available) | No |
|
||||
| Wisdom | `<session-folder>/wisdom/` | No |
|
||||
|
||||
### Phase 3: 4-Dimension Review
|
||||
|
||||
#### Dimension Overview
|
||||
|
||||
| Dimension | Focus | Weight |
|
||||
|-----------|-------|--------|
|
||||
| Quality | Code correctness, type safety, clean code | Equal |
|
||||
| Security | Vulnerability patterns, secret exposure | Equal |
|
||||
| Architecture | Module structure, coupling, file size | Equal |
|
||||
| Requirements | Acceptance criteria coverage, completeness | Equal |
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 1: Quality
|
||||
|
||||
Scan each modified file for quality anti-patterns.
|
||||
|
||||
| Severity | Pattern | What to Detect |
|
||||
|----------|---------|----------------|
|
||||
| Critical | Empty catch blocks | `catch(e) {}` with no handling |
|
||||
| High | @ts-ignore without justification | Suppression comment < 10 chars explanation |
|
||||
| High | `any` type in public APIs | `any` outside comments and generic definitions |
|
||||
| High | console.log in production | `console.(log|debug|info)` outside test files |
|
||||
| Medium | Magic numbers | Numeric literals > 1 digit, not in const/comment |
|
||||
| Medium | Duplicate code | Identical lines (>30 chars) appearing 3+ times |
|
||||
|
||||
**Detection example** (Grep for console statements):
|
||||
|
||||
```bash
|
||||
Grep(pattern="console\\.(log|debug|info)", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
**Detection example** (Grep for empty catch):
|
||||
|
||||
```bash
|
||||
Grep(pattern="catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
**Detection example** (Grep for @ts-ignore):
|
||||
|
||||
```bash
|
||||
Grep(pattern="@ts-ignore|@ts-expect-error", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 2: Security
|
||||
|
||||
Scan for vulnerability patterns across all modified files.
|
||||
|
||||
| Severity | Pattern | What to Detect |
|
||||
|----------|---------|----------------|
|
||||
| Critical | Hardcoded secrets | `api_key=`, `password=`, `secret=`, `token=` with string values (20+ chars) |
|
||||
| Critical | SQL injection | String concatenation in `query()`/`execute()` calls |
|
||||
| High | eval/exec usage | `eval()`, `new Function()`, `setTimeout(string)` |
|
||||
| High | XSS vectors | `innerHTML`, `dangerouslySetInnerHTML` |
|
||||
| Medium | Insecure random | `Math.random()` in security context (token/key/password/session) |
|
||||
| Low | Missing input validation | Functions with parameters but no validation in first 5 lines |
|
||||
|
||||
**Detection example** (Grep for hardcoded secrets):
|
||||
|
||||
```bash
|
||||
Grep(pattern="(api_key|password|secret|token)\\s*[=:]\\s*['\"][^'\"]{20,}", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
**Detection example** (Grep for eval usage):
|
||||
|
||||
```bash
|
||||
Grep(pattern="\\beval\\s*\\(|new\\s+Function\\s*\\(", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 3: Architecture
|
||||
|
||||
Assess structural health of modified files.
|
||||
|
||||
| Severity | Pattern | What to Detect |
|
||||
|----------|---------|----------------|
|
||||
| Critical | Circular dependencies | File A imports B, B imports A |
|
||||
| High | Excessive parent imports | Import traverses >2 parent directories (`../../../`) |
|
||||
| Medium | Large files | Files exceeding 500 lines |
|
||||
| Medium | Tight coupling | >5 imports from same base module |
|
||||
| Medium | Long functions | Functions exceeding 50 lines |
|
||||
| Medium | Module boundary changes | Modifications to index.ts/index.js files |
|
||||
|
||||
**Detection example** (check for deep parent imports):
|
||||
|
||||
```bash
|
||||
Grep(pattern="from\\s+['\"](\\.\\./){3,}", path="<file_path>", output_mode="content", "-n"=true)
|
||||
```
|
||||
|
||||
**Detection example** (check file line count):
|
||||
|
||||
```bash
|
||||
Bash(command="wc -l <file_path>")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 4: Requirements
|
||||
|
||||
Verify implementation against plan acceptance criteria.
|
||||
|
||||
| Severity | Check | Method |
|
||||
|----------|-------|--------|
|
||||
| High | Unmet acceptance criteria | Extract criteria from plan, check keyword overlap (threshold: 70%) |
|
||||
| High | Missing error handling | Plan mentions "error handling" but no try/catch in code |
|
||||
| Medium | Partially met criteria | Keyword overlap 40-69% |
|
||||
| Medium | Missing tests | Plan mentions "test" but no test files in modified set |
|
||||
|
||||
**Verification flow**:
|
||||
1. Read plan file -> extract acceptance criteria section
|
||||
2. For each criterion -> extract keywords (4+ char meaningful words)
|
||||
3. Search modified files for keyword matches
|
||||
4. Score: >= 70% match = met, 40-69% = partial, < 40% = unmet
|
||||
|
||||
---
|
||||
|
||||
### Verdict Routing (Code Review)
|
||||
|
||||
| Verdict | Criteria | Action |
|
||||
|---------|----------|--------|
|
||||
| BLOCK | Any critical-severity issues found | Must fix before merge |
|
||||
| CONDITIONAL | High or medium issues, no critical | Should address, can merge with tracking |
|
||||
| APPROVE | Only low issues or none | Ready to merge |
|
||||
|
||||
### Report Format (Code Review)
|
||||
|
||||
```
|
||||
# Code Review Report
|
||||
|
||||
**Verdict**: <BLOCK|CONDITIONAL|APPROVE>
|
||||
|
||||
## Blocking Issues (if BLOCK)
|
||||
- **<type>** (<file>:<line>): <message>
|
||||
|
||||
## Review Dimensions
|
||||
|
||||
### Quality Issues
|
||||
**CRITICAL** (<count>)
|
||||
- <message> (<file>:<line>)
|
||||
|
||||
### Security Issues
|
||||
(same format per severity)
|
||||
|
||||
### Architecture Issues
|
||||
(same format per severity)
|
||||
|
||||
### Requirements Issues
|
||||
(same format per severity)
|
||||
|
||||
## Summary Counts
|
||||
- Total issues: <n>
|
||||
- Critical: <n> (must be 0 for APPROVE)
|
||||
- Dimensions covered: 4/4
|
||||
|
||||
## Recommendations
|
||||
1. <actionable recommendation>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spec Quality Mode (QUALITY-*)
|
||||
|
||||
### Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Spec documents | `<session-folder>/spec/` (all .md files) | Yes |
|
||||
| Original requirements | Product brief objectives section | Yes |
|
||||
| Quality gate config | specs/quality-gates.md | No |
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
|
||||
**Spec document phases** (matched by filename/directory):
|
||||
|
||||
| Phase | Expected Path | Required |
|
||||
|-------|--------------|---------|
|
||||
| product-brief | spec/product-brief.md | Yes |
|
||||
| prd | spec/requirements/*.md | Yes |
|
||||
| architecture | spec/architecture/_index.md + ADR-*.md | Yes |
|
||||
| user-stories | spec/epics/*.md | Yes |
|
||||
| implementation-plan | plan/plan.json | No |
|
||||
| test-strategy | spec/test-strategy.md | No (optional) |
|
||||
|
||||
### Phase 3: 5-Dimension Scoring
|
||||
|
||||
#### Dimension Weights
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Completeness | 25% | All required sections present with substance |
|
||||
| Consistency | 20% | Terminology, format, references, naming |
|
||||
| Traceability | 25% | Goals -> Reqs -> Components -> Stories chain |
|
||||
| Depth | 20% | AC testable, ADRs justified, stories estimable |
|
||||
| Coverage | 10% | Original requirements mapped to spec |
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 1: Completeness (25%)
|
||||
|
||||
Check each spec document for required sections.
|
||||
|
||||
**Required sections by phase**:
|
||||
|
||||
| Phase | Required Sections |
|
||||
|-------|------------------|
|
||||
| product-brief | Vision Statement, Problem Statement, Target Audience, Success Metrics, Constraints |
|
||||
| prd | Goals, Requirements, User Stories, Acceptance Criteria, Non-Functional Requirements |
|
||||
| architecture | System Overview, Component Design, Data Models, API Specifications, Technology Stack |
|
||||
| user-stories | Story List, Acceptance Criteria, Priority, Estimation |
|
||||
| implementation-plan | Task Breakdown, Dependencies, Timeline, Resource Allocation |
|
||||
|
||||
> **Note**: `test-strategy` is optional -- skip scoring if absent. Do not penalize completeness score for missing optional phases.
|
||||
|
||||
**Scoring formula**:
|
||||
- Section present: 50% credit
|
||||
- Section has substantial content (>100 chars beyond header): additional 50% credit
|
||||
- Per-document score = (present_ratio * 50) + (substantial_ratio * 50)
|
||||
- Overall = average across all documents
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 2: Consistency (20%)
|
||||
|
||||
Check cross-document consistency across four areas.
|
||||
|
||||
| Area | What to Check | Severity |
|
||||
|------|--------------|----------|
|
||||
| Terminology | Same concept with different casing/spelling across docs | Medium |
|
||||
| Format | Mixed header styles at same level across docs | Low |
|
||||
| References | Broken links (`./` or `../` paths that don't resolve) | High |
|
||||
| Naming | Mixed naming conventions (camelCase vs snake_case vs kebab-case) | Low |
|
||||
|
||||
**Scoring**:
|
||||
- Penalty weights: High = 10, Medium = 5, Low = 2
|
||||
- Score = max(0, 100 - (total_penalty / 100) * 100)
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 3: Traceability (25%)
|
||||
|
||||
Build and validate traceability chains: Goals -> Requirements -> Components -> Stories.
|
||||
|
||||
**Chain building flow**:
|
||||
1. Extract goals from product-brief (pattern: `- Goal: <text>`)
|
||||
2. Extract requirements from PRD (pattern: `- REQ-NNN: <text>`)
|
||||
3. Extract components from architecture (pattern: `- Component: <text>`)
|
||||
4. Extract stories from user-stories (pattern: `- US-NNN: <text>`)
|
||||
5. Link by keyword overlap (threshold: 30% keyword match)
|
||||
|
||||
**Chain completeness**: A chain is complete when a goal links to at least one requirement, one component, and one story.
|
||||
|
||||
**Scoring**: (complete chains / total chains) * 100
|
||||
|
||||
**Weak link identification**: For each incomplete chain, report which link is missing (no requirements, no components, or no stories).
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 4: Depth (20%)
|
||||
|
||||
Assess the analytical depth of spec content across four sub-dimensions.
|
||||
|
||||
| Sub-dimension | Source | Testable Criteria |
|
||||
|---------------|--------|-------------------|
|
||||
| AC Testability | PRD / User Stories | Contains measurable verbs (display, return, validate) or Given/When/Then or numbers |
|
||||
| ADR Justification | Architecture | Contains rationale, alternatives, consequences, or trade-offs |
|
||||
| Story Estimability | User Stories | Has "As a/I want/So that" + AC, or explicit estimate |
|
||||
| Technical Detail | Architecture + Plan | Contains code blocks, API terms, HTTP methods, DB terms |
|
||||
|
||||
**Scoring**: Average of sub-dimension scores (each 0-100%)
|
||||
|
||||
---
|
||||
|
||||
#### Dimension 5: Coverage (10%)
|
||||
|
||||
Map original requirements to spec requirements.
|
||||
|
||||
**Flow**:
|
||||
1. Extract original requirements from product-brief objectives section
|
||||
2. Extract spec requirements from all documents (pattern: `- REQ-NNN:` or `- Requirement:` or `- Feature:`)
|
||||
3. For each original requirement, check keyword overlap with any spec requirement (threshold: 40%)
|
||||
4. Score = (covered_count / total_original) * 100
|
||||
|
||||
---
|
||||
|
||||
### Quality Gate Decision Table
|
||||
|
||||
| Gate | Criteria | Message |
|
||||
|------|----------|---------|
|
||||
| PASS | Overall score >= 80% AND coverage >= 70% | Ready for implementation |
|
||||
| FAIL | Overall score < 60% OR coverage < 50% | Major revisions required |
|
||||
| REVIEW | All other cases | Improvements needed, may proceed with caution |
|
||||
|
||||
### Readiness Report Format
|
||||
|
||||
Write to `<session-folder>/spec/readiness-report.md`:
|
||||
|
||||
```
|
||||
# Specification Readiness Report
|
||||
|
||||
**Generated**: <timestamp>
|
||||
**Overall Score**: <score>%
|
||||
**Quality Gate**: <PASS|REVIEW|FAIL> - <message>
|
||||
**Recommended Action**: <action>
|
||||
|
||||
## Dimension Scores
|
||||
|
||||
| Dimension | Score | Weight | Weighted Score |
|
||||
|-----------|-------|--------|----------------|
|
||||
| Completeness | <n>% | 25% | <n>% |
|
||||
| Consistency | <n>% | 20% | <n>% |
|
||||
| Traceability | <n>% | 25% | <n>% |
|
||||
| Depth | <n>% | 20% | <n>% |
|
||||
| Coverage | <n>% | 10% | <n>% |
|
||||
|
||||
## Completeness Analysis
|
||||
(per-phase breakdown: sections present/expected, missing sections)
|
||||
|
||||
## Consistency Analysis
|
||||
(issues by area: terminology, format, references, naming)
|
||||
|
||||
## Traceability Analysis
|
||||
(complete chains / total, weak links)
|
||||
|
||||
## Depth Analysis
|
||||
(per sub-dimension scores)
|
||||
|
||||
## Requirement Coverage
|
||||
(covered / total, uncovered requirements list)
|
||||
```
|
||||
|
||||
### Spec Summary Format
|
||||
|
||||
Write to `<session-folder>/spec/spec-summary.md`:
|
||||
|
||||
```
|
||||
# Specification Summary
|
||||
|
||||
**Overall Quality Score**: <score>%
|
||||
**Quality Gate**: <gate>
|
||||
|
||||
## Documents Reviewed
|
||||
(per document: phase, path, size, section list)
|
||||
|
||||
## Key Findings
|
||||
### Strengths (dimensions scoring >= 80%)
|
||||
### Areas for Improvement (dimensions scoring < 70%)
|
||||
### Recommendations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Inline Discuss (DISCUSS-006) -- QUALITY Tasks Only
|
||||
|
||||
After generating readiness-report.md, spawn discuss agent for final sign-off:
|
||||
|
||||
```javascript
|
||||
const critic = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/agents/cli-discuss-agent.md
|
||||
|
||||
## Multi-Perspective Critique: DISCUSS-006
|
||||
|
||||
### Input
|
||||
- Artifact: <session-folder>/spec/readiness-report.md
|
||||
- Round: DISCUSS-006
|
||||
- Perspectives: product, technical, quality, risk, coverage
|
||||
- Session: <session-folder>
|
||||
- Discovery Context: <session-folder>/spec/discovery-context.json`
|
||||
})
|
||||
const result = wait({ ids: [critic], timeout_ms: 120000 })
|
||||
close_agent({ id: critic })
|
||||
```
|
||||
|
||||
### Discuss Result Handling
|
||||
|
||||
| Verdict | Severity | Action |
|
||||
|---------|----------|--------|
|
||||
| consensus_reached | - | Include as final endorsement in quality report, proceed to Phase 5 |
|
||||
| consensus_blocked | HIGH | **DISCUSS-006 is final sign-off gate**. Always pause for user decision. Flag in output for orchestrator. |
|
||||
| consensus_blocked | MEDIUM | Include warning. Proceed to Phase 5. Log to wisdom. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
|
||||
|
||||
**consensus_blocked output format** (sent to orchestrator):
|
||||
|
||||
```
|
||||
[reviewer] QUALITY-001 complete. Discuss DISCUSS-006: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <session-folder>/spec/readiness-report.md
|
||||
Discussion: <session-folder>/discussions/DISCUSS-006-discussion.md
|
||||
```
|
||||
|
||||
> **Note**: DISCUSS-006 HIGH always triggers user pause regardless of revision count, since this is the spec->impl gate.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Missing context | Request from orchestrator |
|
||||
| Invalid mode (no prefix match) | Abort with error |
|
||||
| Analysis failure | Retry once, then fallback template |
|
||||
| Discuss agent fails | Proceed without final discuss, log warning |
|
||||
| Plan file not found (code review) | Skip requirements dimension, note in report |
|
||||
| Git diff empty | Report no changes to review |
|
||||
| File read fails | Skip file, note in report |
|
||||
| No modified files | Report empty review |
|
||||
| Spec folder empty | FAIL gate, report no documents found |
|
||||
| Missing phase document | Score 0 for that phase in completeness, note in report |
|
||||
| No original requirements found | Score coverage at 100% (nothing to cover) |
|
||||
| Broken references | Flag in consistency, do not fail entire review |
|
||||
423
.codex/skills/team-lifecycle/agents/tester.md
Normal file
423
.codex/skills/team-lifecycle/agents/tester.md
Normal file
@@ -0,0 +1,423 @@
|
||||
---
|
||||
name: lifecycle-tester
|
||||
description: |
|
||||
Lifecycle tester agent. Adaptive test execution with fix cycles, strategy engine,
|
||||
and quality gates. Detects framework, runs affected tests first, classifies failures,
|
||||
selects fix strategy, iterates until pass rate target is met or max iterations reached.
|
||||
Deploy to: ~/.codex/agents/lifecycle-tester.md
|
||||
color: yellow
|
||||
---
|
||||
|
||||
# Lifecycle Tester
|
||||
|
||||
Detect framework -> run tests -> classify failures -> select strategy -> fix -> iterate.
|
||||
Outputs test results with pass rate, iteration count, and remaining failures.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Tag**: `[tester]`
|
||||
- **Prefix**: `TEST-*`
|
||||
- **Boundary**: Test execution and test-related fixes only -- no production code changes beyond test fixes
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
| Action | Allowed |
|
||||
|--------|---------|
|
||||
| Detect test framework | Yes |
|
||||
| Discover affected test files | Yes |
|
||||
| Run test suites (affected + full) | Yes |
|
||||
| Classify test failures by severity | Yes |
|
||||
| Apply test-related fixes (imports, assertions, mocks) | Yes |
|
||||
| Iterate fix cycles up to MAX_ITERATIONS | Yes |
|
||||
| Report test results to coordinator | Yes |
|
||||
| Modify production code beyond test fixes | No |
|
||||
| Create tasks for other roles | No |
|
||||
| Contact other workers directly | No |
|
||||
| Skip framework detection | No |
|
||||
|
||||
---
|
||||
|
||||
## Constants
|
||||
|
||||
| Constant | Value | Description |
|
||||
|----------|-------|-------------|
|
||||
| MAX_ITERATIONS | 10 | Maximum test-fix cycle attempts |
|
||||
| PASS_RATE_TARGET | 95% | Minimum pass rate to declare success |
|
||||
| AFFECTED_TESTS_FIRST | true | Run affected tests before full suite |
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
|
||||
```
|
||||
1. Read: ~/.codex/agents/lifecycle-tester.md
|
||||
2. Parse session folder, modified files, and task context from prompt
|
||||
3. Proceed to Phase 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Framework Detection & Test Discovery
|
||||
|
||||
**Objective**: Identify test framework and find affected test files.
|
||||
|
||||
### Step 2.1: Framework Detection
|
||||
|
||||
Detect the project test framework using priority order (first match wins):
|
||||
|
||||
| Priority | Method | Detection Check |
|
||||
|----------|--------|-----------------|
|
||||
| 1 | package.json devDependencies | Key name matches: vitest, jest, mocha, @types/jest |
|
||||
| 2 | package.json scripts.test | Command string contains framework name |
|
||||
| 3 | Config file existence | vitest.config.*, jest.config.*, pytest.ini, setup.cfg |
|
||||
|
||||
**Detection procedure**:
|
||||
|
||||
```
|
||||
1. Read package.json (if exists)
|
||||
2. Check devDependencies keys:
|
||||
- "vitest" found -> framework = vitest
|
||||
- "jest" or "@types/jest" found -> framework = jest
|
||||
- "mocha" found -> framework = mocha
|
||||
3. If not found, check scripts.test value:
|
||||
- Contains "vitest" -> framework = vitest
|
||||
- Contains "jest" -> framework = jest
|
||||
- Contains "mocha" -> framework = mocha
|
||||
- Contains "pytest" -> framework = pytest
|
||||
4. If not found, check config files:
|
||||
- vitest.config.ts or vitest.config.js exists -> framework = vitest
|
||||
- jest.config.ts or jest.config.js or jest.config.json exists -> framework = jest
|
||||
- pytest.ini or setup.cfg with [tool:pytest] exists -> framework = pytest
|
||||
5. If no framework detected -> report error to coordinator
|
||||
```
|
||||
|
||||
**Python project detection**:
|
||||
|
||||
```
|
||||
If no package.json exists:
|
||||
Check for: pytest.ini, setup.cfg, pyproject.toml, requirements.txt
|
||||
If pytest found in any -> framework = pytest
|
||||
```
|
||||
|
||||
### Step 2.2: Affected Test Discovery
|
||||
|
||||
From the executor's modified files, find corresponding test files:
|
||||
|
||||
**Search variants** (for each modified file `<name>.<ext>`):
|
||||
|
||||
| Variant | Pattern | Example |
|
||||
|---------|---------|---------|
|
||||
| Co-located test | `<dir>/<name>.test.<ext>` | `src/utils/parser.test.ts` |
|
||||
| Co-located spec | `<dir>/<name>.spec.<ext>` | `src/utils/parser.spec.ts` |
|
||||
| Tests directory | `<dir>/tests/<name>.test.<ext>` | `src/utils/tests/parser.test.ts` |
|
||||
| __tests__ directory | `<dir>/__tests__/<name>.test.<ext>` | `src/utils/__tests__/parser.test.ts` |
|
||||
|
||||
**Discovery procedure**:
|
||||
|
||||
```
|
||||
1. Get list of modified files from executor output or git diff
|
||||
2. For each modified file:
|
||||
a. Extract <name> (without extension) and <dir> (directory path)
|
||||
b. Search all 4 variants above
|
||||
c. Check file existence for each variant
|
||||
d. Collect all found test files (deduplicate)
|
||||
3. If no affected tests found:
|
||||
-> Set AFFECTED_TESTS_FIRST = false
|
||||
-> Will run full suite directly
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Test Execution & Fix Cycle
|
||||
|
||||
**Objective**: Run tests, fix failures iteratively until pass rate target is met.
|
||||
|
||||
### Step 3.1: Test Command Table
|
||||
|
||||
| Framework | Affected Tests Command | Full Suite Command |
|
||||
|-----------|----------------------|-------------------|
|
||||
| vitest | `vitest run <files> --reporter=verbose` | `vitest run --reporter=verbose` |
|
||||
| jest | `jest <files> --no-coverage --verbose` | `jest --no-coverage --verbose` |
|
||||
| mocha | `mocha <files> --reporter spec` | `mocha --reporter spec` |
|
||||
| pytest | `pytest <files> -v --tb=short` | `pytest -v --tb=short` |
|
||||
|
||||
**Command execution**: All test commands run with a 120-second (120000 ms) timeout.
|
||||
|
||||
### Step 3.2: Iteration Flow
|
||||
|
||||
```
|
||||
Iteration 1
|
||||
+-- Run affected tests (or full suite if no affected tests found)
|
||||
+-- Parse results -> calculate pass rate
|
||||
+-- Pass rate >= 95%?
|
||||
| +-- YES + affected-only -> run full suite to confirm
|
||||
| | +-- Full suite passes -> SUCCESS (exit cycle)
|
||||
| | +-- Full suite fails -> continue with full suite results
|
||||
| +-- YES + full suite -> SUCCESS (exit cycle)
|
||||
+-- NO -> classify failures -> select strategy -> apply fixes
|
||||
|
||||
Iteration 2..10
|
||||
+-- Re-run tests (same scope as last failure)
|
||||
+-- Parse results -> calculate pass rate
|
||||
+-- Track best pass rate across all iterations
|
||||
+-- Pass rate >= 95%?
|
||||
| +-- YES -> SUCCESS (exit cycle)
|
||||
+-- No failures to fix (anomaly)?
|
||||
| +-- YES -> STOP with warning
|
||||
+-- Failures remain -> classify -> select strategy -> apply fixes
|
||||
|
||||
After iteration 10
|
||||
+-- FAIL: max iterations reached
|
||||
+-- Report best pass rate achieved
|
||||
+-- Report remaining failures
|
||||
```
|
||||
|
||||
**Progress reporting**: When iteration > 5, send progress update to coordinator:
|
||||
|
||||
```
|
||||
"[tester] Iteration <N>/10: pass rate <X>%, best so far <Y>%"
|
||||
```
|
||||
|
||||
**Identical results detection**: Track last 3 result sets. If 3 consecutive iterations
|
||||
produce identical failure sets (same test names, same error messages), abort early
|
||||
to prevent infinite loop.
|
||||
|
||||
### Step 3.3: Strategy Selection Matrix
|
||||
|
||||
Select fix strategy based on current iteration and pass rate:
|
||||
|
||||
| Condition | Strategy | Behavior |
|
||||
|-----------|----------|----------|
|
||||
| Iteration <= 3 OR pass rate >= 80% | Conservative | Fix one failure at a time, highest severity first |
|
||||
| Critical failures exist AND count < 5 | Surgical | Identify common error pattern, fix all matching occurrences |
|
||||
| Pass rate < 50% OR iteration > 7 | Aggressive | Fix all critical + high severity failures in batch |
|
||||
| Default (no other condition matches) | Conservative | Safe fallback, one fix at a time |
|
||||
|
||||
**Strategy selection procedure**:
|
||||
|
||||
```
|
||||
1. Calculate current pass rate
|
||||
2. Count failures by severity (critical, high, medium, low)
|
||||
3. Evaluate conditions top-to-bottom:
|
||||
a. If iteration <= 3 OR pass_rate >= 80% -> Conservative
|
||||
b. If critical_count > 0 AND critical_count < 5 -> Surgical
|
||||
c. If pass_rate < 50% OR iteration > 7 -> Aggressive
|
||||
d. Otherwise -> Conservative (default)
|
||||
```
|
||||
|
||||
### Step 3.4: Failure Classification Table
|
||||
|
||||
Classify each test failure by severity:
|
||||
|
||||
| Severity | Error Patterns | Priority |
|
||||
|----------|---------------|----------|
|
||||
| Critical | SyntaxError, cannot find module, is not defined, ReferenceError | Fix first |
|
||||
| High | Assertion mismatch (expected/received), toBe/toEqual failures, TypeError | Fix second |
|
||||
| Medium | Timeout, async errors, Promise rejection, act() warnings | Fix third |
|
||||
| Low | Warnings, deprecation notices, console errors | Fix last |
|
||||
|
||||
**Classification procedure**:
|
||||
|
||||
```
|
||||
For each failed test:
|
||||
1. Extract error message from test output
|
||||
2. Match against patterns (top-to-bottom, first match wins):
|
||||
- "SyntaxError" or "Unexpected token" -> Critical
|
||||
- "Cannot find module" or "Module not found" -> Critical
|
||||
- "is not defined" or "ReferenceError" -> Critical
|
||||
- "Expected:" and "Received:" -> High
|
||||
- "toBe" or "toEqual" or "toMatch" -> High
|
||||
- "TypeError" or "is not a function" -> High
|
||||
- "Timeout" or "exceeded" -> Medium
|
||||
- "async" or "Promise" or "unhandled" -> Medium
|
||||
- "Warning" or "deprecated" or "WARN" -> Low
|
||||
- No pattern match -> Medium (default)
|
||||
3. Record: test name, file, line, severity, error message
|
||||
```
|
||||
|
||||
### Step 3.5: Fix Approach by Error Type
|
||||
|
||||
| Error Type | Pattern | Fix Approach |
|
||||
|------------|---------|-------------|
|
||||
| missing_import | "Cannot find module '<module>'" | Add import statement, resolve relative path from modified files. Check if module was renamed or moved. |
|
||||
| undefined_variable | "<name> is not defined" | Check source for renamed/moved exports. Update reference to match current export name. |
|
||||
| assertion_mismatch | "Expected: X, Received: Y" | Read test file at failure line. If behavior change is intentional (implementation updated expected output), update expected value. If unintentional, investigate source. |
|
||||
| timeout | "Timeout - Async callback..." | Increase test timeout or add missing async/await. Check for unresolved promises. |
|
||||
| syntax_error | "SyntaxError: Unexpected..." | Read source file at error line. Fix syntax (missing bracket, semicolon, etc). |
|
||||
|
||||
**Fix execution**:
|
||||
|
||||
```
|
||||
1. Read the failing test file
|
||||
2. Read the source file referenced in error (if applicable)
|
||||
3. Determine fix type from error pattern table
|
||||
4. Apply fix:
|
||||
- For test file fixes: Edit test file directly
|
||||
- For source file fixes: Edit source file (only test-related, e.g. missing export)
|
||||
5. Log fix applied: "[tester] Fixed: <error-type> in <file>:<line>"
|
||||
```
|
||||
|
||||
### Step 3.6: Fix Application by Strategy
|
||||
|
||||
**Conservative strategy**:
|
||||
|
||||
```
|
||||
1. Sort failures by severity (Critical -> High -> Medium -> Low)
|
||||
2. Take the FIRST (highest severity) failure only
|
||||
3. Apply fix for that single failure
|
||||
4. Re-run tests to see impact
|
||||
```
|
||||
|
||||
**Surgical strategy**:
|
||||
|
||||
```
|
||||
1. Identify the most common error pattern across failures
|
||||
(e.g., 4 tests fail with "Cannot find module './utils'")
|
||||
2. Apply a single fix that addresses ALL occurrences of that pattern
|
||||
3. Re-run tests to see impact
|
||||
```
|
||||
|
||||
**Aggressive strategy**:
|
||||
|
||||
```
|
||||
1. Collect ALL critical and high severity failures
|
||||
2. Group by error type (missing_import, undefined_variable, etc.)
|
||||
3. Apply fixes for ALL grouped failures in a single batch
|
||||
4. Re-run tests to see combined impact
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Result Analysis
|
||||
|
||||
**Objective**: Classify final results and report to coordinator.
|
||||
|
||||
### Step 4.1: Final Failure Classification
|
||||
|
||||
After the cycle completes (success or max iterations), classify any remaining failures:
|
||||
|
||||
| Severity | Count | Impact Assessment |
|
||||
|----------|-------|-------------------|
|
||||
| Critical | <N> | Blocking -- code cannot compile/run |
|
||||
| High | <N> | Functional -- assertions fail |
|
||||
| Medium | <N> | Quality -- timeouts or async issues |
|
||||
| Low | <N> | Informational -- warnings only |
|
||||
|
||||
### Step 4.2: Result Routing
|
||||
|
||||
| Condition | Message Type | Content |
|
||||
|-----------|-------------|---------|
|
||||
| Pass rate >= 95% | test_result (success) | Iterations used, full suite confirmed, pass rate |
|
||||
| Pass rate < 95% after MAX_ITERATIONS | fix_required | Best pass rate, remaining failures by severity, iteration count |
|
||||
| No tests found | error | Framework detected but no test files found |
|
||||
| Framework not detected | error | All detection methods exhausted, manual configuration needed |
|
||||
| Infinite loop detected | error | 3 identical result sets, cycle aborted |
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
Report to coordinator after cycle completes:
|
||||
|
||||
```
|
||||
## [tester] Test Cycle Complete
|
||||
|
||||
**Status**: <success|fix_required|error>
|
||||
**Framework**: <vitest|jest|mocha|pytest>
|
||||
**Iterations**: <N>/10
|
||||
**Pass Rate**: <X>% (best: <Y>%)
|
||||
**Strategy Used**: <Conservative|Surgical|Aggressive>
|
||||
|
||||
### Test Summary
|
||||
- Total tests: <count>
|
||||
- Passing: <count>
|
||||
- Failing: <count>
|
||||
- Skipped: <count>
|
||||
|
||||
### Remaining Failures (if any)
|
||||
| Test | File | Severity | Error |
|
||||
|------|------|----------|-------|
|
||||
| <test-name> | <file>:<line> | Critical | <error-message> |
|
||||
...
|
||||
|
||||
### Fixes Applied
|
||||
1. [iteration <N>] <error-type> in <file>:<line> -- <description>
|
||||
2. [iteration <N>] <error-type> in <file>:<line> -- <description>
|
||||
...
|
||||
|
||||
### Modified Files (test fixes)
|
||||
- <file-1>
|
||||
- <file-2>
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Framework not detected | Report error to coordinator with detection methods tried |
|
||||
| No test files found | Report to coordinator, suggest manual test file path |
|
||||
| Test command fails (exit code other than 0 or 1) | Check stderr for environment issues (missing deps, config error), retry once |
|
||||
| Fix application fails (Edit tool error) | Skip that fix, try next iteration with different strategy |
|
||||
| Infinite loop (3 identical result sets) | Abort cycle, report remaining failures with note about repeated pattern |
|
||||
| Test command timeout (> 120s) | Kill process, report timeout, suggest running subset |
|
||||
| Package manager issues (missing node_modules) | Run `npm install` or `yarn install` once, retry tests |
|
||||
| TypeScript compilation blocks tests | Run `tsc --noEmit` first, fix compilation errors before re-running tests |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Iteration Example
|
||||
|
||||
```
|
||||
Iteration 1:
|
||||
Command: vitest run src/utils/__tests__/parser.test.ts --reporter=verbose
|
||||
Result: 8/10 passed (80%)
|
||||
Failures:
|
||||
- parser.test.ts:45 "Cannot find module './helpers'" (Critical)
|
||||
- parser.test.ts:78 "Expected: 42, Received: 41" (High)
|
||||
Strategy: Conservative (iteration 1, pass rate 80%)
|
||||
Fix: Add import for './helpers' in parser.test.ts
|
||||
|
||||
Iteration 2:
|
||||
Command: vitest run src/utils/__tests__/parser.test.ts --reporter=verbose
|
||||
Result: 9/10 passed (90%)
|
||||
Failures:
|
||||
- parser.test.ts:78 "Expected: 42, Received: 41" (High)
|
||||
Strategy: Conservative (iteration 2, pass rate 90%)
|
||||
Fix: Update expected value from 42 to 41 (intentional behavior change)
|
||||
|
||||
Iteration 3:
|
||||
Command: vitest run src/utils/__tests__/parser.test.ts --reporter=verbose
|
||||
Result: 10/10 passed (100%) -- affected tests pass
|
||||
Command: vitest run --reporter=verbose
|
||||
Result: 145/145 passed (100%) -- full suite passes
|
||||
Status: SUCCESS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Detect framework before running any tests
|
||||
- Run affected tests before full suite (when AFFECTED_TESTS_FIRST is true)
|
||||
- Classify failures by severity before selecting fix strategy
|
||||
- Track best pass rate across all iterations
|
||||
- Use `[tester]` prefix in all status messages
|
||||
- Report remaining failures with severity classification
|
||||
- Check for infinite loops (3 identical result sets)
|
||||
- Run full suite at least once before declaring success
|
||||
- Close all spawned agents after receiving results
|
||||
|
||||
**NEVER**:
|
||||
- Modify production code beyond test-related fixes
|
||||
- Skip framework detection
|
||||
- Exceed MAX_ITERATIONS (10)
|
||||
- Create tasks for other roles
|
||||
- Contact other workers directly
|
||||
- Apply fixes without classifying failures first
|
||||
- Declare success without running full suite
|
||||
- Ignore Critical severity failures
|
||||
- Use Claude patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)
|
||||
502
.codex/skills/team-lifecycle/agents/writer.md
Normal file
502
.codex/skills/team-lifecycle/agents/writer.md
Normal file
@@ -0,0 +1,502 @@
|
||||
# Writer Agent
|
||||
|
||||
Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation. Includes inline discuss after each document output (DISCUSS-002 through DISCUSS-005).
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `produce`
|
||||
- **Role File**: `~/.codex/skills/team-lifecycle/agents/writer.md`
|
||||
- **Prefix**: `DRAFT-*`
|
||||
- **Tag**: `[writer]`
|
||||
- **Responsibility**: Load Context -> Generate Document -> Self-Validation -> Inline Discuss -> Report
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Only process DRAFT-* tasks
|
||||
- Read templates before generating (from skill templates directory)
|
||||
- Follow document-standards.md
|
||||
- Integrate prior discussion feedback when available
|
||||
- Generate proper YAML frontmatter on all documents
|
||||
- Call discuss subagent after document output (round from Inline Discuss mapping)
|
||||
- Produce structured output following template
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Create tasks for other roles
|
||||
- Skip template loading
|
||||
- Modify discussion records from prior rounds
|
||||
- Skip inline discuss
|
||||
- Self-revise on consensus_blocked HIGH (flag for orchestrator instead)
|
||||
- Produce unstructured output
|
||||
- Use Claude-specific patterns (Task, TaskOutput, resume, SendMessage, TaskCreate)
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `ccw cli --tool gemini --mode analysis` | CLI | Product/requirements analysis perspective |
|
||||
| `ccw cli --tool codex --mode analysis` | CLI | Technical/feasibility analysis perspective |
|
||||
| `ccw cli --tool claude --mode analysis` | CLI | User/quality analysis perspective |
|
||||
| `discuss-agent.md` | Subagent (Pattern 2.8) | Inline discuss critique per document |
|
||||
| `Read` | Built-in | Read templates, prior docs, discussion records, spec config |
|
||||
| `Write` | Built-in | Write generated documents |
|
||||
| `Bash` | Built-in | Shell commands, CLI execution |
|
||||
|
||||
### Tool Usage Patterns
|
||||
|
||||
**Read Pattern**: Load context and templates
|
||||
```
|
||||
Read("<skill-dir>/templates/<template-name>.md")
|
||||
Read("<skill-dir>/specs/document-standards.md")
|
||||
Read("<session-folder>/spec/spec-config.json")
|
||||
Read("<session-folder>/spec/discovery-context.json")
|
||||
Read("<session-folder>/discussions/<round>-discussion.md")
|
||||
```
|
||||
|
||||
**Write Pattern**: Generate documents
|
||||
```
|
||||
Write("<session-folder>/spec/product-brief.md", <content>)
|
||||
Write("<session-folder>/spec/requirements/_index.md", <content>)
|
||||
Write("<session-folder>/spec/requirements/REQ-NNN-<slug>.md", <content>)
|
||||
Write("<session-folder>/spec/architecture/_index.md", <content>)
|
||||
Write("<session-folder>/spec/architecture/ADR-NNN-<slug>.md", <content>)
|
||||
Write("<session-folder>/spec/epics/_index.md", <content>)
|
||||
Write("<session-folder>/spec/epics/EPIC-NNN-<slug>.md", <content>)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
**Objective**: Parse task assignment from orchestrator message.
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Orchestrator message | Yes | Contains task ID (DRAFT-NNN), session folder, doc type |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Extract session folder from task message (`Session: <path>`)
|
||||
2. Extract task ID (DRAFT-NNN pattern)
|
||||
3. Determine document type from task subject
|
||||
|
||||
**Output**: session-folder, task-id, doc-type.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Context & Discussion Loading
|
||||
|
||||
**Objective**: Load all required inputs for document generation.
|
||||
|
||||
#### Document Type Routing Table
|
||||
|
||||
| Task | Doc Type | Template | Prior Discussion Input | Output Path |
|
||||
|------|----------|----------|----------------------|-------------|
|
||||
| DRAFT-001 | product-brief | templates/product-brief.md | DISCUSS-001-discussion.md | spec/product-brief.md |
|
||||
| DRAFT-002 | requirements | templates/requirements-prd.md | DISCUSS-002-discussion.md | spec/requirements/_index.md |
|
||||
| DRAFT-003 | architecture | templates/architecture-doc.md | DISCUSS-003-discussion.md | spec/architecture/_index.md |
|
||||
| DRAFT-004 | epics | templates/epics-template.md | DISCUSS-004-discussion.md | spec/epics/_index.md |
|
||||
|
||||
#### Inline Discuss Mapping
|
||||
|
||||
| Doc Type | Inline Discuss Round | Perspectives |
|
||||
|----------|---------------------|-------------|
|
||||
| product-brief | DISCUSS-002 | product, technical, quality, coverage |
|
||||
| requirements | DISCUSS-003 | quality, product, coverage |
|
||||
| architecture | DISCUSS-004 | technical, risk |
|
||||
| epics | DISCUSS-005 | product, technical, quality, coverage |
|
||||
|
||||
#### Progressive Dependency Loading
|
||||
|
||||
| Doc Type | Requires |
|
||||
|----------|----------|
|
||||
| product-brief | discovery-context.json |
|
||||
| requirements | discovery-context.json + product-brief.md |
|
||||
| architecture | discovery-context.json + product-brief.md + requirements/_index.md |
|
||||
| epics | discovery-context.json + product-brief.md + requirements/_index.md + architecture/_index.md |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read document-standards.md for formatting rules
|
||||
2. Read template for this doc type from routing table
|
||||
3. Read spec-config.json and discovery-context.json
|
||||
4. Read prior discussion feedback (if file exists)
|
||||
5. Read all progressive dependencies for this doc type
|
||||
|
||||
**Failure handling**:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| Template not found | Error, report missing template path |
|
||||
| Prior doc not found | Report to orchestrator, request prerequisite completion |
|
||||
| Discussion file missing | Proceed without discussion feedback |
|
||||
|
||||
**Output**: Template loaded, prior discussion feedback (or null), prior docs loaded, spec-config ready.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Document Generation
|
||||
|
||||
**Objective**: Generate document using template and multi-CLI analysis.
|
||||
|
||||
#### Shared Context Block
|
||||
|
||||
Built from spec-config and discovery-context for all CLI prompts:
|
||||
|
||||
```
|
||||
SEED: <topic>
|
||||
PROBLEM: <problem-statement>
|
||||
TARGET USERS: <target-users>
|
||||
DOMAIN: <domain>
|
||||
CONSTRAINTS: <constraints>
|
||||
FOCUS AREAS: <focus-areas>
|
||||
CODEBASE CONTEXT: <existing-patterns, tech-stack> (if codebase context exists)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### DRAFT-001: Product Brief
|
||||
|
||||
**Strategy**: 3-way parallel CLI analysis, then synthesize.
|
||||
|
||||
| Perspective | CLI Tool | Focus |
|
||||
|-------------|----------|-------|
|
||||
| Product | gemini | Vision, market fit, success metrics, scope |
|
||||
| Technical | codex | Feasibility, constraints, integration complexity |
|
||||
| User | claude | Personas, journey maps, pain points, UX |
|
||||
|
||||
**CLI call template** (one per perspective, all run in background):
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: <perspective> analysis for specification.
|
||||
<shared-context>
|
||||
TASK: <perspective-specific-tasks>
|
||||
MODE: analysis
|
||||
EXPECTED: <structured-output>
|
||||
CONSTRAINTS: <perspective-scope>" --tool <tool> --mode analysis
|
||||
```
|
||||
|
||||
**Perspective-specific task details**:
|
||||
|
||||
| Perspective | Task Focus |
|
||||
|-------------|------------|
|
||||
| Product (gemini) | Define product vision, identify market positioning, set measurable success metrics, define MVP scope boundaries |
|
||||
| Technical (codex) | Assess technical feasibility of each goal, identify integration constraints, estimate complexity per feature, flag technical risks |
|
||||
| User (claude) | Build user personas with demographics and motivations, map user journeys, identify pain points and friction, propose UX principles |
|
||||
|
||||
**Synthesis flow** (after all 3 CLIs return):
|
||||
|
||||
```
|
||||
3 CLI outputs received
|
||||
+-- Identify convergent themes (2+ perspectives agree)
|
||||
+-- Identify conflicts (e.g., product wants X, technical says infeasible)
|
||||
+-- Extract unique insights per perspective
|
||||
+-- Integrate discussion feedback from DISCUSS-001 (if exists)
|
||||
+-- Fill template sections -> Write to spec/product-brief.md
|
||||
```
|
||||
|
||||
**Template sections**: Vision, Problem Statement, Target Users, Goals, Scope, Success Criteria, Assumptions.
|
||||
|
||||
---
|
||||
|
||||
#### DRAFT-002: Requirements/PRD
|
||||
|
||||
**Strategy**: Single CLI expansion, then structure into individual requirement files.
|
||||
|
||||
| Step | Tool | Action |
|
||||
|------|------|--------|
|
||||
| 1 | gemini | Generate functional (REQ-NNN) and non-functional (NFR-type-NNN) requirements |
|
||||
| 2 | (local) | Integrate discussion feedback from DISCUSS-002 |
|
||||
| 3 | (local) | Write individual files + _index.md |
|
||||
|
||||
**CLI prompt focus**: For each product-brief goal, generate 3-7 functional requirements with user stories, acceptance criteria, and MoSCoW priority. Generate NFR categories: performance, security, scalability, usability.
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Generate comprehensive requirements from product brief.
|
||||
<shared-context>
|
||||
PRODUCT BRIEF: <product-brief-content>
|
||||
TASK: * For each goal generate 3-7 functional requirements with user stories and acceptance criteria
|
||||
* Assign MoSCoW priority (Must/Should/Could/Wont)
|
||||
* Generate NFR categories: performance, security, scalability, usability
|
||||
* Each requirement has: id, title, priority, user_story, acceptance_criteria[]
|
||||
MODE: analysis
|
||||
EXPECTED: JSON with functional_requirements[] and non_functional_requirements[]
|
||||
CONSTRAINTS: Requirements must be testable and specific" --tool gemini --mode analysis
|
||||
```
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/requirements/
|
||||
+-- _index.md (summary table + MoSCoW breakdown)
|
||||
+-- REQ-001-<slug>.md (individual functional requirement)
|
||||
+-- REQ-002-<slug>.md
|
||||
+-- NFR-perf-001-<slug>.md (non-functional)
|
||||
+-- NFR-sec-001-<slug>.md
|
||||
```
|
||||
|
||||
Each requirement file has: YAML frontmatter (id, title, priority, status, traces), description, user story, acceptance criteria.
|
||||
|
||||
---
|
||||
|
||||
#### DRAFT-003: Architecture
|
||||
|
||||
**Strategy**: 2-stage CLI (design + critical review).
|
||||
|
||||
| Stage | Tool | Purpose |
|
||||
|-------|------|---------|
|
||||
| 1 | gemini | Architecture design: style, components, tech stack, ADRs, data model, security |
|
||||
| 2 | codex | Critical review: challenge ADRs, identify bottlenecks, rate quality 1-5 |
|
||||
|
||||
Stage 2 runs AFTER stage 1 completes (sequential dependency).
|
||||
|
||||
**Stage 1 CLI**:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Design system architecture from requirements.
|
||||
<shared-context>
|
||||
REQUIREMENTS: <requirements-index-content>
|
||||
TASK: * Select architecture style with justification
|
||||
* Define component breakdown with responsibilities
|
||||
* Recommend tech stack with rationale
|
||||
* Create ADRs for key decisions
|
||||
* Design data model
|
||||
* Define API contract patterns
|
||||
* Address security architecture
|
||||
MODE: analysis
|
||||
EXPECTED: JSON with architecture_style, components[], tech_stack{}, adrs[], data_model, api_patterns, security
|
||||
CONSTRAINTS: Must trace back to requirements" --tool gemini --mode analysis
|
||||
```
|
||||
|
||||
**Stage 2 CLI** (receives Stage 1 output):
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Critical architecture review.
|
||||
ARCHITECTURE PROPOSAL: <stage-1-output>
|
||||
TASK: * Challenge each ADR with alternatives
|
||||
* Identify performance bottlenecks
|
||||
* Assess scalability limits
|
||||
* Rate overall quality 1-5
|
||||
* Suggest improvements
|
||||
MODE: analysis
|
||||
EXPECTED: JSON with adr_reviews[], bottlenecks[], scalability_assessment, quality_rating, improvements[]
|
||||
CONSTRAINTS: Be critical, identify weaknesses" --tool codex --mode analysis
|
||||
```
|
||||
|
||||
**After both complete**:
|
||||
|
||||
1. Integrate discussion feedback from DISCUSS-003
|
||||
2. Map codebase integration points (from discovery-context.relevant_files)
|
||||
3. Write individual ADR files + _index.md
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/architecture/
|
||||
+-- _index.md (overview, component diagram, tech stack, data model, API, security)
|
||||
+-- ADR-001-<slug>.md (individual decision record)
|
||||
+-- ADR-002-<slug>.md
|
||||
```
|
||||
|
||||
Each ADR file has: YAML frontmatter (id, title, status, traces), context, decision, alternatives with pros/cons, consequences, review feedback.
|
||||
|
||||
---
|
||||
|
||||
#### DRAFT-004: Epics & Stories
|
||||
|
||||
**Strategy**: Single CLI decomposition, then structure into individual epic files.
|
||||
|
||||
| Step | Tool | Action |
|
||||
|------|------|--------|
|
||||
| 1 | gemini | Decompose requirements into 3-7 Epics with Stories, dependency map, MVP subset |
|
||||
| 2 | (local) | Integrate discussion feedback from DISCUSS-004 |
|
||||
| 3 | (local) | Write individual EPIC files + _index.md |
|
||||
|
||||
**CLI prompt focus**:
|
||||
|
||||
```bash
|
||||
ccw cli -p "PURPOSE: Decompose requirements into implementable epics and stories.
|
||||
<shared-context>
|
||||
REQUIREMENTS: <requirements-index-content>
|
||||
ARCHITECTURE: <architecture-index-content>
|
||||
TASK: * Group requirements by domain into 3-7 Epics
|
||||
* Each Epic has STORY-EPIC-NNN children with user stories and acceptance criteria
|
||||
* Define MVP subset (mark which epics/stories are MVP)
|
||||
* Create Mermaid dependency diagram between epics
|
||||
* Recommend execution order considering dependencies
|
||||
* Estimate T-shirt size per epic (S/M/L/XL)
|
||||
MODE: analysis
|
||||
EXPECTED: JSON with epics[], dependency_graph, mvp_scope[], execution_order[]
|
||||
CONSTRAINTS: Stories must be estimable and independently deliverable" --tool gemini --mode analysis
|
||||
```
|
||||
|
||||
**Output structure**:
|
||||
|
||||
```
|
||||
spec/epics/
|
||||
+-- _index.md (overview table, dependency map, execution order, MVP scope)
|
||||
+-- EPIC-001-<slug>.md (individual epic with stories)
|
||||
+-- EPIC-002-<slug>.md
|
||||
```
|
||||
|
||||
Each epic file has: YAML frontmatter (id, title, priority, mvp, size, requirements, architecture, dependencies), stories with user stories and acceptance criteria.
|
||||
|
||||
**All generated documents** include YAML frontmatter: session_id, phase, document_type, status=draft, generated_at, version, dependencies.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Self-Validation + Inline Discuss
|
||||
|
||||
#### 4a: Self-Validation
|
||||
|
||||
| Check | What to Verify |
|
||||
|-------|---------------|
|
||||
| has_frontmatter | Document starts with valid YAML frontmatter |
|
||||
| sections_complete | All template sections present in output |
|
||||
| cross_references | session_id matches spec-config |
|
||||
| discussion_integrated | Prior round feedback reflected (if feedback exists) |
|
||||
| files_written | All expected files exist (individual + _index.md) |
|
||||
|
||||
**Validation decision table**:
|
||||
|
||||
| Outcome | Action |
|
||||
|---------|--------|
|
||||
| All checks pass | Proceed to 4b (Inline Discuss) |
|
||||
| Non-critical issues | Fix issues, re-validate, then proceed to 4b |
|
||||
| Critical failure (missing template, no CLI output) | Report error in output, skip 4b |
|
||||
|
||||
#### 4b: Inline Discuss
|
||||
|
||||
After validation, spawn discuss subagent (Pattern 2.8) for this task's discuss round:
|
||||
|
||||
```javascript
|
||||
const critic = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/skills/team-lifecycle/agents/discuss-agent.md
|
||||
|
||||
## Multi-Perspective Critique: <DISCUSS-NNN>
|
||||
|
||||
### Input
|
||||
- Artifact: <output-path>
|
||||
- Round: <DISCUSS-NNN>
|
||||
- Perspectives: <perspectives-from-inline-discuss-mapping>
|
||||
- Session: <session-folder>
|
||||
- Discovery Context: <session-folder>/spec/discovery-context.json
|
||||
`
|
||||
})
|
||||
const result = wait({ ids: [critic], timeout_ms: 120000 })
|
||||
close_agent({ id: critic })
|
||||
```
|
||||
|
||||
**Round-to-perspective mapping** (use the Inline Discuss Mapping table from Phase 2):
|
||||
|
||||
| Doc Type | Round | Perspectives to pass |
|
||||
|----------|-------|---------------------|
|
||||
| product-brief | DISCUSS-002 | product, technical, quality, coverage |
|
||||
| requirements | DISCUSS-003 | quality, product, coverage |
|
||||
| architecture | DISCUSS-004 | technical, risk |
|
||||
| epics | DISCUSS-005 | product, technical, quality, coverage |
|
||||
|
||||
**Discuss result handling**:
|
||||
|
||||
| Verdict | Severity | Action |
|
||||
|---------|----------|--------|
|
||||
| consensus_reached | - | Include action items in report, proceed to output |
|
||||
| consensus_blocked | HIGH | Flag in output with structured consensus_blocked format for orchestrator. Do NOT self-revise. |
|
||||
| consensus_blocked | MEDIUM | Include warning in output. Proceed to output normally. |
|
||||
| consensus_blocked | LOW | Treat as consensus_reached with notes. |
|
||||
|
||||
**consensus_blocked output format**:
|
||||
```
|
||||
[writer] <task-id> complete. Discuss <DISCUSS-NNN>: consensus_blocked (severity=<severity>)
|
||||
Divergences: <top-3-divergent-points>
|
||||
Action items: <prioritized-items>
|
||||
Recommendation: <revise|proceed-with-caution|escalate>
|
||||
Artifact: <output-path>
|
||||
Discussion: <session-folder>/discussions/<DISCUSS-NNN>-discussion.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inline Subagent Calls
|
||||
|
||||
This agent spawns the discuss subagent during Phase 4b:
|
||||
|
||||
### Discuss Subagent (Phase 4b)
|
||||
|
||||
**When**: After self-validation of generated document
|
||||
**Agent File**: `~/.codex/skills/team-lifecycle/agents/discuss-agent.md`
|
||||
**Pattern**: 2.8 (Inline Subagent)
|
||||
|
||||
See Phase 4b code block above. The round ID and perspectives vary per doc type -- use the Inline Discuss Mapping table.
|
||||
|
||||
### Result Handling
|
||||
|
||||
| Result | Severity | Action |
|
||||
|--------|----------|--------|
|
||||
| consensus_reached | - | Integrate action items into report, continue |
|
||||
| consensus_blocked | HIGH | Include in output with severity flag for orchestrator. Do NOT self-revise -- orchestrator creates revision task. |
|
||||
| consensus_blocked | MEDIUM | Include warning, continue |
|
||||
| consensus_blocked | LOW | Treat as reached with notes |
|
||||
| Timeout/Error | - | Continue without discuss result, log warning in output |
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- [writer] <task-id> complete.
|
||||
- Doc Type: <product-brief|requirements|architecture|epics>
|
||||
|
||||
## Validation Status
|
||||
- has_frontmatter: pass/fail
|
||||
- sections_complete: pass/fail
|
||||
- cross_references: pass/fail
|
||||
- discussion_integrated: pass/fail/N-A
|
||||
- files_written: pass/fail
|
||||
|
||||
## Discuss Verdict (<DISCUSS-NNN>)
|
||||
- Consensus: reached / blocked
|
||||
- Severity: <HIGH|MEDIUM|LOW> (if blocked)
|
||||
- Average Rating: <avg>/5
|
||||
- Key Action Items:
|
||||
1. <item>
|
||||
2. <item>
|
||||
3. <item>
|
||||
- Discussion Record: <session-folder>/discussions/<DISCUSS-NNN>-discussion.md
|
||||
|
||||
## Output
|
||||
- Doc Type: <type>
|
||||
- Output Path: <session-folder>/spec/<output-path>
|
||||
- Files Generated: <count>
|
||||
|
||||
## Open Questions
|
||||
1. <question> (if any)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Prior doc not found | Report to orchestrator, request prerequisite task completion |
|
||||
| Template not found | Error, report missing template path |
|
||||
| CLI tool fails | Retry with fallback tool (gemini -> codex -> claude) |
|
||||
| Discussion contradicts prior docs | Note conflict in document, flag for next discussion round |
|
||||
| Partial CLI output | Use available data, note gaps in document |
|
||||
| Discuss subagent fails | Proceed without discuss, log warning in output |
|
||||
| Discuss subagent timeout | Close agent, proceed without discuss verdict |
|
||||
| File write failure | Report error, output partial results with clear status |
|
||||
| Multiple CLI failures | Generate document from available perspectives only |
|
||||
Reference in New Issue
Block a user