maestro-flow 0.1.0

package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md

@@ -0,0 +1,725 @@
+# 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": ""
+}
+```