# Team Lifecycle v4 — Agent Instruction

This instruction is loaded by team-worker agents when spawned with roles: `analyst`, `writer`, `planner`, `executor`, `tester`, `reviewer`.

---

## Role-Based Execution

### Analyst Role

**Responsibility**: Research domain, extract structured context, identify constraints.

**Input**:
- `id`: Task ID (e.g., `RESEARCH-001`)
- `title`: Task title
- `description`: Detailed task description with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS
- `role`: `analyst`
- `pipeline_phase`: `research`
- `prev_context`: Previous tasks' findings (empty for wave 1)

**Execution Protocol**:

1. **Read shared discoveries**:
   ```javascript
   const discoveries = Read(`{session}/discoveries.ndjson`)
   ```

2. **Explore domain** (use CLI analysis tools):
   ```bash
   ccw cli -p "PURPOSE: Research domain for {requirement}
   TASK: • Identify problem statement • Define target users • Extract constraints • Map integration points
   CONTEXT: @**/* | Memory: {requirement}
   EXPECTED: Structured research context with problem/users/domain/constraints
   CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis --rule analysis-trace-code-execution
   ```

3. **Extract structured context**:
   - Problem statement: What problem are we solving?
   - Target users: Who will use this?
   - Domain: What domain/industry?
   - Constraints: Technical, business, regulatory constraints
   - Integration points: External systems, APIs, services

4. **Write discovery context**:
   ```javascript
   Write(`{session}/spec/discovery-context.json`, JSON.stringify({
     problem_statement: "Users need OAuth2 authentication with SSO support",
     target_users: ["Enterprise customers", "Internal teams"],
     domain: "Authentication & Authorization",
     constraints: ["Must support SAML", "GDPR compliance", "99.9% uptime"],
     integration_points: ["User service API", "Session store", "Audit log"],
     exploration_dimensions: ["Security", "Scalability", "User experience"]
   }, null, 2))
   ```

5. **Share discoveries**:
   ```bash
   echo '{"ts":"2026-03-08T10:00:00+08:00","worker":"{id}","type":"research","data":{"dimension":"domain","findings":["Auth system needs OAuth2 + RBAC"],"constraints":["Must support SSO"],"integration_points":["User service API"]}}' >> {session}/discoveries.ndjson
   ```

6. **Report result**:
   ```javascript
   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Explored domain: identified OAuth2+RBAC auth pattern, 5 integration points, TypeScript/React stack. Key constraint: must support SSO.",
     quality_score: "",
     supervision_verdict: "",
     error: ""
   })
   ```

**Success Criteria**:
- Discovery context written with all required fields
- Problem statement clear and actionable
- Constraints identified
- Integration points mapped

---

### Writer Role

**Responsibility**: Generate specification documents (product brief, requirements, architecture, epics).

**Input**:
- `id`: Task ID (e.g., `DRAFT-001`)
- `title`: Task title
- `description`: Detailed task description
- `role`: `writer`
- `pipeline_phase`: `product-brief`, `requirements`, `architecture`, or `epics`
- `context_from`: Upstream task IDs
- `prev_context`: Previous tasks' findings
- `inner_loop`: `true` (writer uses inner loop for revision)

**Execution Protocol**:

1. **Read upstream artifacts**:
   ```javascript
   const discoveryContext = JSON.parse(Read(`{session}/spec/discovery-context.json`))
   const productBrief = Read(`{session}/spec/product-brief.md`)  // if exists
   ```

2. **Generate document based on pipeline_phase**:

   **Product Brief** (DRAFT-001):
   ```markdown
   # Product Brief: OAuth2 Authentication System

   ## Vision
   Enable enterprise customers to authenticate users via OAuth2 with SSO support.

   ## Problem
   Current authentication system lacks OAuth2 support, blocking enterprise adoption.

   ## Target Users
   - Enterprise customers requiring SSO
   - Internal teams needing centralized auth

   ## Success Goals
   - 99.9% uptime
   - <200ms auth latency
   - GDPR compliant
   - Support 10k concurrent users

   ## Key Decisions
   - Use OAuth2 over custom auth
   - Support SAML for SSO
   - Implement RBAC for authorization
   ```

   **Requirements PRD** (DRAFT-002):
   ```markdown
   # Requirements: OAuth2 Authentication

   ## Functional Requirements

   ### FR-001: OAuth2 Authorization Flow
   **Priority**: Must Have
   **Description**: Implement OAuth2 authorization code flow
   **Acceptance Criteria**:
   - User redirected to OAuth provider
   - Authorization code exchanged for access token
   - Token stored securely in session

   ### FR-002: SSO Integration
   **Priority**: Must Have
   **Description**: Support SAML-based SSO
   **Acceptance Criteria**:
   - SAML assertion validated
   - User attributes mapped to internal user model
   - Session created with SSO context

   ## User Stories

   ### US-001: Enterprise User Login
   **As an** enterprise user
   **I want to** log in via my company's SSO
   **So that** I don't need separate credentials

   **Acceptance Criteria**:
   - Given I'm on the login page
   - When I click "Login with SSO"
   - Then I'm redirected to my company's SSO provider
   - And I'm logged in after successful authentication
   ```

   **Architecture Design** (DRAFT-003):
   ```markdown
   # Architecture: OAuth2 Authentication

   ## Component Diagram
   [User] -> [Auth Gateway] -> [OAuth Provider]
                |
                v
           [Session Store]
                |
                v
           [User Service]

   ## Tech Stack
   - **Backend**: Node.js + Express
   - **OAuth Library**: Passport.js
   - **Session Store**: Redis
   - **Database**: PostgreSQL

   ## Architecture Decision Records

   ### ADR-001: Use Passport.js for OAuth
   **Status**: Accepted
   **Context**: Need OAuth2 + SAML support
   **Decision**: Use Passport.js with passport-oauth2 and passport-saml strategies
   **Consequences**: Mature library, good community support, but adds dependency

   ## Data Model
   ```sql
   CREATE TABLE users (
     id UUID PRIMARY KEY,
     email VARCHAR(255) UNIQUE,
     oauth_provider VARCHAR(50),
     oauth_id VARCHAR(255)
   );
   ```

   ## Integration Points
   - User Service API: GET /users/:id, POST /users
   - Session Store: Redis SET/GET with TTL
   - Audit Log: POST /audit/events
   ```

   **Epics and Stories** (DRAFT-004):
   ```markdown
   # Epics: OAuth2 Authentication

   ## Epic 1: OAuth2 Core Flow
   **Priority**: Must Have (MVP)
   **Estimate**: 13 story points

   ### Stories
   1. **STORY-001**: Implement authorization endpoint (3 pts)
   2. **STORY-002**: Implement token exchange (5 pts)
   3. **STORY-003**: Implement token refresh (3 pts)
   4. **STORY-004**: Add session management (2 pts)

   ## Epic 2: SSO Integration
   **Priority**: Must Have (MVP)
   **Estimate**: 8 story points

   ### Stories
   1. **STORY-005**: Integrate SAML provider (5 pts)
   2. **STORY-006**: Map SAML attributes (3 pts)

   ## Epic 3: RBAC Authorization
   **Priority**: Should Have
   **Estimate**: 8 story points

   ### Stories
   1. **STORY-007**: Define role model (2 pts)
   2. **STORY-008**: Implement permission checks (3 pts)
   3. **STORY-009**: Add role assignment UI (3 pts)
   ```

3. **Write document to spec/ directory**:
   ```javascript
   Write(`{session}/spec/{doc-type}.md`, documentContent)
   ```

4. **Share discoveries**:
   ```bash
   echo '{"ts":"2026-03-08T10:15:00+08:00","worker":"{id}","type":"spec_artifact","data":{"doc_type":"product-brief","path":"spec/product-brief.md","sections":["Vision","Problem","Users","Goals"],"key_decisions":["OAuth2 over custom auth"]}}' >> {session}/discoveries.ndjson
   ```

5. **Report result**:
   ```javascript
   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Generated product brief with vision, problem statement, target users, success goals. Key decision: OAuth2 over custom auth.",
     quality_score: "",
     supervision_verdict: "",
     error: ""
   })
   ```

**Success Criteria**:
- Document follows template structure
- All required sections present
- Terminology consistent with upstream docs
- Key decisions documented

---

### Planner Role

**Responsibility**: Break down requirements into implementation tasks.

**Input**:
- `id`: Task ID (e.g., `PLAN-001`)
- `title`: Task title
- `description`: Detailed task description
- `role`: `planner`
- `pipeline_phase`: `planning`
- `context_from`: Upstream task IDs (e.g., `QUALITY-001`)
- `prev_context`: Previous tasks' findings
- `inner_loop`: `true` (planner uses inner loop for refinement)

**Execution Protocol**:

1. **Read spec artifacts**:
   ```javascript
   const requirements = Read(`{session}/spec/requirements.md`)
   const architecture = Read(`{session}/spec/architecture.md`)
   const epics = Read(`{session}/spec/epics.md`)
   ```

2. **Explore codebase** (use CLI analysis tools):
   ```bash
   ccw cli -p "PURPOSE: Explore codebase for {requirement}
   TASK: • Identify relevant files • Find existing patterns • Locate integration points
   CONTEXT: @**/* | Memory: {requirement}
   EXPECTED: Exploration findings with file paths and patterns
   CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis --rule analysis-trace-code-execution
   ```

3. **Generate implementation plan**:
   ```javascript
   const plan = {
     requirement: "{requirement}",
     complexity: "Medium",  // Low (1-2 modules), Medium (3-4), High (5+)
     approach: "Strategy pattern for OAuth providers",
     tasks: [
       {
         task_id: "TASK-001",
         title: "Create OAuth provider interface",
         description: "Define provider interface with authorize/token/refresh methods",
         files: ["src/auth/providers/oauth-provider.ts"],
         depends_on: [],
         convergence_criteria: [
           "Interface compiles without errors",
           "Type definitions exported"
         ]
       },
       {
         task_id: "TASK-002",
         title: "Implement Google OAuth provider",
         description: "Concrete implementation for Google OAuth2",
         files: ["src/auth/providers/google-oauth.ts"],
         depends_on: ["TASK-001"],
         convergence_criteria: [
           "Tests pass",
           "Handles token refresh",
           "Error handling complete"
         ]
       }
     ],
     exploration_findings: {
       existing_patterns: ["Strategy pattern in payment module"],
       tech_stack: ["TypeScript", "Express", "Passport.js"],
       integration_points: ["User service", "Session store"]
     }
   }
   Write(`{session}/plan/plan.json`, JSON.stringify(plan, null, 2))
   ```

4. **Write per-task files**:
   ```javascript
   for (const task of plan.tasks) {
     Write(`{session}/plan/.task/${task.task_id}.json`, JSON.stringify(task, null, 2))
   }
   ```

5. **Share discoveries**:
   ```bash
   echo '{"ts":"2026-03-08T11:00:00+08:00","worker":"{id}","type":"plan_task","data":{"task_id":"TASK-001","title":"Create OAuth provider interface","files":["src/auth/providers/oauth-provider.ts"],"complexity":"Low","convergence_criteria":["Interface compiles"]}}' >> {session}/discoveries.ndjson
   ```

6. **Report result**:
   ```javascript
   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Generated implementation plan with 2 tasks. Complexity: Medium. Approach: Strategy pattern for OAuth providers. Identified existing strategy pattern in payment module.",
     quality_score: "",
     supervision_verdict: "",
     error: ""
   })
   ```

**Success Criteria**:
- plan.json written with valid structure
- 2-7 tasks defined
- Task dependencies form DAG (no cycles)
- Convergence criteria defined per task
- Complexity assessed

---

### Executor Role

**Responsibility**: Execute implementation plan tasks.

**Input**:
- `id`: Task ID (e.g., `IMPL-001`)
- `title`: Task title
- `description`: Detailed task description
- `role`: `executor`
- `pipeline_phase`: `implementation`
- `context_from`: Upstream task IDs (e.g., `PLAN-001`)
- `prev_context`: Previous tasks' findings
- `inner_loop`: `true` (executor uses inner loop for self-repair)

**Execution Protocol**:

1. **Read implementation plan**:
   ```javascript
   const plan = JSON.parse(Read(`{session}/plan/plan.json`))
   ```

2. **For each task in plan.tasks** (ordered by depends_on):

   a. **Read context files**:
   ```javascript
   for (const file of task.files) {
     if (fileExists(file)) Read(file)
   }
   ```

   b. **Identify patterns**:
   - Note imports, naming conventions, existing structure
   - Follow project patterns from exploration_findings

   c. **Apply changes**:
   - Use Edit for existing files (prefer)
   - Use Write for new files
   - Follow convergence criteria from task

   d. **Build check** (if build command exists):
   ```bash
   npm run build 2>&1 || echo BUILD_FAILED
   ```
   - If build fails: analyze error → fix → rebuild (max 3 retries)

   e. **Verify convergence**:
   - Check each criterion in task.convergence_criteria
   - If not met: self-repair loop (max 3 iterations)

3. **Share discoveries**:
   ```bash
   echo '{"ts":"2026-03-08T11:00:00+08:00","worker":"{id}","type":"implementation","data":{"task_id":"IMPL-001","files_modified":["src/auth/oauth.ts","src/auth/rbac.ts"],"approach":"Strategy pattern for auth providers","changes_summary":"Created OAuth2 provider, RBAC middleware, session management"}}' >> {session}/discoveries.ndjson
   ```

4. **Report result**:
   ```javascript
   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Implemented 2 tasks: OAuth provider interface + Google OAuth implementation. Modified 2 files. All convergence criteria met.",
     quality_score: "",
     supervision_verdict: "",
     error: ""
   })
   ```

**Success Criteria**:
- All tasks completed in dependency order
- Build passes (if build command exists)
- All convergence criteria met
- Code follows project patterns

---

### Tester Role

**Responsibility**: Run tests, fix failures, achieve 95% pass rate.

**Input**:
- `id`: Task ID (e.g., `TEST-001`)
- `title`: Task title
- `description`: Detailed task description
- `role`: `tester`
- `pipeline_phase`: `validation`
- `context_from`: Upstream task IDs (e.g., `IMPL-001`)
- `prev_context`: Previous tasks' findings

**Execution Protocol**:

1. **Detect test framework**:
   ```javascript
   const packageJson = JSON.parse(Read('package.json'))
   const testCommand = packageJson.scripts?.test || packageJson.scripts?.['test:unit']
   ```

2. **Run affected tests first** (if possible):
   ```bash
   npm test -- --changed
   ```

3. **Run full test suite**:
   ```bash
   npm test 2>&1
   ```

4. **Parse test results**:
   - Total tests
   - Passed tests
   - Failed tests
   - Pass rate = passed / total

5. **Self-repair loop** (if pass rate < 95%):
   - Analyze test output
   - Diagnose failure cause
   - Fix source code
   - Re-run tests
   - Max 10 iterations

6. **Share discoveries**:
   ```bash
   echo '{"ts":"2026-03-08T11:30:00+08:00","worker":"{id}","type":"test_result","data":{"framework":"vitest","pass_rate":98,"failures":["timeout in SSO integration test"],"fix_iterations":2}}' >> {session}/discoveries.ndjson
   ```

7. **Report result**:
   ```javascript
   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Ran 50 tests. Pass rate: 98% (49/50). Fixed 2 failures in 2 iterations. Remaining failure: timeout in SSO integration test (non-blocking).",
     quality_score: "",
     supervision_verdict: "",
     error: ""
   })
   ```

**Success Criteria**:
- Test suite executed
- Pass rate >= 95%
- Failures fixed (max 10 iterations)
- Test results documented

---

### Reviewer Role

**Responsibility**: Multi-dimensional code review or quality gate scoring.

**Input**:
- `id`: Task ID (e.g., `REVIEW-001` or `QUALITY-001`)
- `title`: Task title
- `description`: Detailed task description
- `role`: `reviewer`
- `pipeline_phase`: `review` or `readiness`
- `context_from`: Upstream task IDs
- `prev_context`: Previous tasks' findings

**Execution Protocol**:

**For Code Review** (REVIEW-*):

1. **Read implementation files**:
   ```javascript
   const plan = JSON.parse(Read(`{session}/plan/plan.json`))
   const modifiedFiles = plan.tasks.flatMap(t => t.files)
   ```

2. **Multi-dimensional review**:
   - **Quality**: Code style, naming, structure
   - **Security**: Input validation, auth checks, SQL injection
   - **Architecture**: Follows design, proper abstractions
   - **Requirements**: Covers all FRs, acceptance criteria met

3. **Determine verdict**:
   - `BLOCK`: Critical issues, cannot merge
   - `CONDITIONAL`: Minor issues, can merge with fixes
   - `APPROVE`: No issues, ready to merge

4. **Write review report**:
   ```markdown
   # Code Review: {id}

   ## Verdict: APPROVE

   ## Quality (8/10)
   - Code style consistent
   - Naming clear and semantic
   - Minor: some functions could be extracted

   ## Security (9/10)
   - Input validation present
   - Auth checks correct
   - SQL injection prevented

   ## Architecture (8/10)
   - Follows strategy pattern
   - Proper abstractions
   - Minor: could use dependency injection

   ## Requirements Coverage (10/10)
   - All FRs implemented
   - Acceptance criteria met
   - Edge cases handled

   ## Issues
   (none)

   ## Recommendations
   1. Extract validation logic to separate module
   2. Add dependency injection for testability
   ```

**For Quality Gate** (QUALITY-*):

1. **Read all spec artifacts**:
   ```javascript
   const productBrief = Read(`{session}/spec/product-brief.md`)
   const requirements = Read(`{session}/spec/requirements.md`)
   const architecture = Read(`{session}/spec/architecture.md`)
   const epics = Read(`{session}/spec/epics.md`)
   ```

2. **Score 4 dimensions** (25% each):
   - **Completeness**: All sections present, no gaps
   - **Consistency**: Terminology aligned, decisions traced
   - **Traceability**: Vision → requirements → architecture → epics
   - **Depth**: Sufficient detail for implementation

3. **Calculate overall score**:
   ```javascript
   const score = (completeness + consistency + traceability + depth) / 4
   ```

4. **Determine gate verdict**:
   - `>= 80%`: PASS (proceed to implementation)
   - `60-79%`: REVIEW (revisions recommended)
   - `< 60%`: FAIL (return to writer for rework)

5. **Write quality report**:
   ```markdown
   # Quality Gate: {id}

   ## Overall Score: 82%

   ## Dimension Scores
   - Completeness: 90% (23/25)
   - Consistency: 85% (21/25)
   - Traceability: 80% (20/25)
   - Depth: 75% (19/25)

   ## Verdict: PASS

   ## Findings
   - All spec documents present and complete
   - Terminology consistent across docs
   - Clear trace from vision to epics
   - Sufficient detail for implementation
   - Minor: architecture could include more error handling details
   ```

6. **Share discoveries**:
   ```bash
   echo '{"ts":"2026-03-08T12:00:00+08:00","worker":"{id}","type":"quality_gate","data":{"gate_id":"QUALITY-001","score":82,"dimensions":{"completeness":90,"consistency":85,"traceability":80,"depth":75},"verdict":"pass"}}' >> {session}/discoveries.ndjson
   ```

7. **Report result**:
   ```javascript
   report_agent_job_result({
     id: "{id}",
     status: "completed",
     findings: "Quality gate: Completeness 90%, Consistency 85%, Traceability 80%, Depth 75%. Overall: 82.5% PASS.",
     quality_score: "82",
     supervision_verdict: "",
     error: ""
   })
   ```

**Success Criteria**:
- All dimensions scored
- Report written with findings
- Verdict determined
- Score >= 80% for quality gate pass

---

## Inner Loop Protocol

Roles with `inner_loop: true` support self-repair:

| Scenario | Max Iterations | Action |
|----------|---------------|--------|
| Build failure | 3 | Analyze error → fix source → rebuild |
| Test failure | 10 | Analyze failure → fix source → re-run tests |
| Convergence not met | 3 | Check criteria → adjust implementation → re-verify |
| Document incomplete | 2 | Review template → add missing sections → re-validate |

After max iterations: report error, mark task as failed.

---

## Shared Discovery Board

All roles read/write `{session}/discoveries.ndjson`:

**Discovery Types**:
- `research`: Research findings
- `spec_artifact`: Specification document
- `exploration`: Codebase exploration
- `plan_task`: Implementation task definition
- `implementation`: Implementation result
- `test_result`: Test execution result
- `review_finding`: Code review finding
- `checkpoint`: Supervisor checkpoint result
- `quality_gate`: Quality gate assessment

**Protocol**:
1. Read discoveries at start
2. Append discoveries during execution (never modify existing)
3. Deduplicate by type + dedup key

---

## Error Handling

| Error | Resolution |
|-------|------------|
| Upstream artifact not found | Report error, mark failed |
| Spec document invalid format | Report error, mark failed |
| Plan JSON corrupt | Report error, mark failed |
| Build fails after 3 retries | Mark task failed, report error |
| Tests fail after 10 retries | Mark task failed, report error |
| CLI tool timeout | Fallback to direct implementation |
| Dependency task failed | Skip dependent tasks, report error |

---

## Output Format

All roles use `report_agent_job_result` with this schema:

```json
{
  "id": "{id}",
  "status": "completed" | "failed",
  "findings": "Key discoveries (max 500 chars)",
  "quality_score": "0-100 (reviewer only)",
  "supervision_verdict": "pass|warn|block (supervisor only)",
  "error": ""
}
```