claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-lifecycle/agents/writer.md

@@ -1,502 +0,0 @@
-# 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**: `~/~  or <project>/.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: ~/~  or <project>/.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**: `~/~  or <project>/.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 |