mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 11:53:52 +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
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