diff --git a/.codex/skills/parallel-dev-cycle/SKILL.md b/.codex/skills/parallel-dev-cycle/SKILL.md index c0f427ae..833e6cd2 100644 --- a/.codex/skills/parallel-dev-cycle/SKILL.md +++ b/.codex/skills/parallel-dev-cycle/SKILL.md @@ -59,6 +59,7 @@ Each agent **maintains one main document** (e.g., requirements.md, plan.json, im 5. **Parallel Coordination**: Four agents launched simultaneously; coordination via shared state and orchestrator 6. **File References**: Use short file paths instead of content passing 7. **Self-Enhancement**: RA agent proactively extends requirements based on context +8. **Shared Discovery Board**: All agents share exploration findings via `discoveries.ndjson` — read on start, write as you discover, eliminating redundant codebase exploration ## Arguments @@ -141,11 +142,15 @@ Phase 1: Session Initialization ↓ cycleId, state, progressDir (initialized/resumed) Phase 2: Agent Execution - ↓ agentOutputs {ra, ep, cd, vas} + ├─ All agents read coordination/discoveries.ndjson on start + ├─ Each agent explores → writes new discoveries to board + ├─ Later-finishing agents benefit from earlier agents' findings + ↓ agentOutputs {ra, ep, cd, vas} + shared discoveries.ndjson Phase 3: Result Aggregation ↓ parsedResults, hasIssues, iteration count ↓ [Loop back to Phase 2 if issues and iteration < max] + ↓ (discoveries.ndjson carries over across iterations) Phase 4: Completion & Summary ↓ finalState, summaryReport @@ -179,6 +184,7 @@ Return: cycle_id, iterations, final_state │ ├── changes.log # NDJSON complete history │ └── history/ └── coordination/ + ├── discoveries.ndjson # Shared discovery board (all agents append) ├── timeline.md # Execution timeline └── decisions.log # Decision log ``` @@ -271,7 +277,45 @@ Append: changes.log ← {"timestamp","version":"1.1.0","action":"update","descr **Execution Order**: RA → EP → CD → VAS (dependency chain, all spawned in parallel but block on dependencies) -**Agent → Orchestrator**: Each agent outputs `PHASE_RESULT:` block: +### Shared Discovery Board + +All agents share a real-time discovery board at `coordination/discoveries.ndjson`. Each agent reads it on start and appends findings during work. This eliminates redundant codebase exploration. + +**Lifecycle**: +- Created by the first agent to write a discovery (file may not exist initially) +- Carries over across iterations — never cleared or recreated +- Agents use Bash `echo '...' >> discoveries.ndjson` to append entries + +**Format**: NDJSON, each line is a self-contained JSON with required top-level fields `ts`, `agent`, `type`, `data`: +```jsonl +{"ts":"2026-01-22T10:00:00+08:00","agent":"ra","type":"tech_stack","data":{"language":"TypeScript","framework":"Express","test":"Jest","build":"tsup"}} +``` + +**Discovery Types**: + +| type | Dedup Key | Writers | Readers | Required `data` Fields | +|------|-----------|---------|---------|----------------------| +| `tech_stack` | singleton | RA | EP, CD, VAS | `language`, `framework`, `test`, `build` | +| `project_config` | `data.path` | RA | EP, CD | `path`, `key_deps[]`, `scripts{}` | +| `existing_feature` | `data.name` | RA, EP | CD | `name`, `files[]`, `summary` | +| `architecture` | singleton | EP | CD, VAS | `pattern`, `layers[]`, `entry` | +| `code_pattern` | `data.name` | EP, CD | CD, VAS | `name`, `description`, `example_file` | +| `integration_point` | `data.file` | EP | CD | `file`, `description`, `exports[]` | +| `similar_impl` | `data.feature` | EP | CD | `feature`, `files[]`, `relevance` | +| `code_convention` | singleton | CD | VAS | `naming`, `imports`, `formatting` | +| `utility` | `data.name` | CD | VAS | `name`, `file`, `usage` | +| `test_command` | singleton | CD, VAS | VAS, CD | `unit`, `integration`(opt), `coverage`(opt) | +| `test_baseline` | singleton | VAS | CD | `total`, `passing`, `coverage_pct`, `framework`, `config` | +| `test_pattern` | singleton | VAS | CD | `style`, `naming`, `fixtures` | +| `blocker` | `data.issue` | any | all | `issue`, `severity`, `impact` | + +**Protocol Rules**: +1. Read board before own exploration → skip covered areas (if file doesn't exist, skip) +2. Write discoveries immediately via Bash `echo >>` → don't batch +3. Deduplicate — check existing entries; skip if same `type` + dedup key value already exists +4. Append-only — never modify or delete existing lines + +### Agent → Orchestrator Communication ``` PHASE_RESULT: - phase: ra | ep | cd | vas @@ -281,7 +325,9 @@ PHASE_RESULT: - issues: [] ``` -**Orchestrator → Agent**: Feedback via `send_input` (file refs + issue summary, never full content): +### Orchestrator → Agent Communication + +Feedback via `send_input` (file refs + issue summary, never full content): ``` ## FEEDBACK FROM [Source] [Issue summary with file:line references] diff --git a/.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md b/.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md index 19daa70f..3e0e4e70 100644 --- a/.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md +++ b/.codex/skills/parallel-dev-cycle/phases/02-agent-execution.md @@ -5,11 +5,38 @@ Spawn four specialized agents in parallel and wait for all to complete with time ## Objective - Spawn RA, EP, CD, VAS agents simultaneously using Codex subagent pattern -- Pass cycle context and role references to each agent +- Pass cycle context, role references, and **discovery protocol** to each agent - Wait for all agents with configurable timeout - Handle timeout with convergence request - Output: agentOutputs from all 4 agents +## Shared Discovery Board + +All agents share a discovery board at `{progressDir}/coordination/discoveries.ndjson`. Each agent reads it on start and writes discoveries during execution. This eliminates redundant codebase exploration across agents. + +**Agent reads board → skips covered areas → explores unknowns → writes new findings → other agents benefit** + +### Discovery Protocol Snippet (injected into every agent prompt) + +``` +## SHARED DISCOVERY PROTOCOL + +Board: ${progressDir}/coordination/discoveries.ndjson + +**On Start**: Read board (if exists; if not, skip — you'll be the first writer). + Skip exploration for areas already covered. +**During Work**: Append discoveries as NDJSON entries via Bash `echo '...' >> discoveries.ndjson`. +**Format**: {"ts":"","agent":"","type":"","data":{}} +**Cross-iteration**: Board persists across iterations. Never clear it. + +**You Write** (dedup key in parentheses): +- `` () → required data: , , ... + +**You Read**: + +**Rules**: Read before explore. Write via `echo >>`. Dedup by type+key. Append-only. +``` + ## Agent Role References Each agent reads its detailed role definition at execution time: @@ -64,6 +91,26 @@ Cross-reference the task description against these documents for completeness. --- +## SHARED DISCOVERY PROTOCOL + +Board: ${progressDir}/coordination/discoveries.ndjson + +**On Start**: Read board (if exists; if not, skip — you'll be the first writer). Skip exploration for areas already covered. +**During Work**: Append discoveries as NDJSON entries via Bash \`echo '...' >> discoveries.ndjson\`. +**Format**: {"ts":"","agent":"ra","type":"","data":{}} +**Cross-iteration**: Board persists across iterations. Never clear it. + +**You Write** (dedup key in parentheses): +- \`tech_stack\` (singleton) → required data: language, framework, test, build +- \`project_config\` (data.path) → required data: path, key_deps[], scripts{} +- \`existing_feature\` (data.name) → required data: name, files[], summary + +**You Read**: architecture, similar_impl, test_baseline, blocker + +**Rules**: Read before explore. Write via \`echo >> \`. Dedup by type+key. Append-only. + +--- + ${sourceRefsSection} ## CYCLE CONTEXT @@ -87,6 +134,7 @@ Requirements Analyst - Analyze and refine requirements throughout the cycle. 3. Identify edge cases and implicit requirements 4. Track requirement changes across iterations 5. Maintain requirements.md and changes.log +6. **Share discoveries** to coordination/discoveries.ndjson ${focusDirective} ## DELIVERABLES @@ -126,6 +174,27 @@ function spawnEPAgent(cycleId, state, progressDir) { --- +## SHARED DISCOVERY PROTOCOL + +Board: ${progressDir}/coordination/discoveries.ndjson + +**On Start**: Read board (if exists; if not, skip — you'll be the first writer). Skip exploration for areas already covered. +**During Work**: Append discoveries as NDJSON entries via Bash \`echo '...' >> discoveries.ndjson\`. +**Format**: {"ts":"","agent":"ep","type":"","data":{}} +**Cross-iteration**: Board persists across iterations. Never clear it. + +**You Write** (dedup key in parentheses): +- \`architecture\` (singleton) → required data: pattern, layers[], entry +- \`code_pattern\` (data.name) → required data: name, description, example_file +- \`integration_point\` (data.file) → required data: file, description, exports[] +- \`similar_impl\` (data.feature) → required data: feature, files[], relevance + +**You Read**: tech_stack, project_config, existing_feature, test_command, test_baseline + +**Rules**: Read before explore. Write via \`echo >> \`. Dedup by type+key. Append-only. + +--- + ## CYCLE CONTEXT - **Cycle ID**: ${cycleId} @@ -144,6 +213,7 @@ Exploration & Planning Agent - Explore architecture and generate implementation 3. Design implementation approach 4. Generate plan.json with task breakdown 5. Update or iterate on existing plan +6. **Share discoveries** to coordination/discoveries.ndjson ## DELIVERABLES @@ -182,6 +252,27 @@ function spawnCDAgent(cycleId, state, progressDir) { --- +## SHARED DISCOVERY PROTOCOL + +Board: ${progressDir}/coordination/discoveries.ndjson + +**On Start**: Read board (if exists; if not, skip — you'll be the first writer). Skip exploration for areas already covered. +**During Work**: Append discoveries as NDJSON entries via Bash \`echo '...' >> discoveries.ndjson\`. +**Format**: {"ts":"","agent":"cd","type":"","data":{}} +**Cross-iteration**: Board persists across iterations. Never clear it. + +**You Write** (dedup key in parentheses): +- \`code_convention\` (singleton) → required data: naming, imports, formatting +- \`utility\` (data.name) → required data: name, file, usage +- \`test_command\` (singleton) → required data: unit, integration(opt), coverage(opt) +- \`blocker\` (data.issue) → required data: issue, severity, impact + +**You Read**: tech_stack, architecture, code_pattern, integration_point, similar_impl, test_baseline, test_command + +**Rules**: Read before explore. Write via \`echo >> \`. Dedup by type+key. Append-only. + +--- + ## CYCLE CONTEXT - **Cycle ID**: ${cycleId} @@ -200,6 +291,7 @@ Code Developer - Implement features based on plan and requirements. 3. Handle integration issues 4. Maintain code quality 5. Report implementation progress and issues +6. **Share discoveries** to coordination/discoveries.ndjson ## DELIVERABLES @@ -237,6 +329,27 @@ function spawnVASAgent(cycleId, state, progressDir) { --- +## SHARED DISCOVERY PROTOCOL + +Board: ${progressDir}/coordination/discoveries.ndjson + +**On Start**: Read board (if exists; if not, skip — you'll be the first writer). Skip exploration for areas already covered. +**During Work**: Append discoveries as NDJSON entries via Bash \`echo '...' >> discoveries.ndjson\`. +**Format**: {"ts":"","agent":"vas","type":"","data":{}} +**Cross-iteration**: Board persists across iterations. Never clear it. + +**You Write** (dedup key in parentheses): +- \`test_baseline\` (singleton) → required data: total, passing, coverage_pct, framework, config +- \`test_pattern\` (singleton) → required data: style, naming, fixtures +- \`test_command\` (singleton) → required data: unit, e2e(opt), coverage(opt) +- \`blocker\` (data.issue) → required data: issue, severity, impact + +**You Read**: tech_stack, architecture, code_pattern, code_convention, test_command, utility, integration_point + +**Rules**: Read before explore. Write via \`echo >> \`. Dedup by type+key. Append-only. + +--- + ## CYCLE CONTEXT - **Cycle ID**: ${cycleId} @@ -255,6 +368,7 @@ Validation & Archival Specialist - Validate quality and create documentation. 3. Create archival documentation 4. Summarize cycle results 5. Generate version history +6. **Share discoveries** to coordination/discoveries.ndjson ## DELIVERABLES diff --git a/.codex/skills/parallel-dev-cycle/roles/code-developer.md b/.codex/skills/parallel-dev-cycle/roles/code-developer.md index 99af5f02..dd383b48 100644 --- a/.codex/skills/parallel-dev-cycle/roles/code-developer.md +++ b/.codex/skills/parallel-dev-cycle/roles/code-developer.md @@ -55,6 +55,61 @@ The Code Developer is responsible for implementing features according to the pla - Leave TODO comments without context - Implement features not in the plan +## Shared Discovery Protocol + +CD agent participates in the **Shared Discovery Board** (`coordination/discoveries.ndjson`). This append-only NDJSON file enables all agents to share exploration findings in real-time, eliminating redundant codebase exploration. + +### Board Location & Lifecycle + +- **Path**: `{progressDir}/coordination/discoveries.ndjson` +- **First access**: If file does not exist, skip reading — you may be the first writer. Create it on first write. +- **Cross-iteration**: Board carries over across iterations. Do NOT clear or recreate it. New iterations append to existing entries. + +### Physical Write Method + +Append one NDJSON line using Bash: +```bash +echo '{"ts":"2026-01-22T11:00:00+08:00","agent":"cd","type":"code_convention","data":{"naming":"camelCase functions, PascalCase classes","imports":"absolute paths via @/ alias","formatting":"prettier with default config"}}' >> {progressDir}/coordination/discoveries.ndjson +``` + +### CD Reads (from other agents) + +| type | Dedup Key | Use | +|------|-----------|-----| +| `tech_stack` | (singleton) | Know language/framework without detection — skip project scanning | +| `architecture` | (singleton) | Understand system layout (layers, entry point) before coding | +| `code_pattern` | `data.name` | Follow existing conventions (error handling, validation, etc.) immediately | +| `integration_point` | `data.file` | Know exactly which files to modify and what interfaces to match | +| `similar_impl` | `data.feature` | Read reference implementations for consistency | +| `test_baseline` | (singleton) | Know current test count/coverage before making changes | +| `test_command` | (singleton) | Run tests directly without figuring out commands | + +### CD Writes (for other agents) + +| type | Dedup Key | Required `data` Fields | When | +|------|-----------|----------------------|------| +| `code_convention` | (singleton — only 1 entry) | `naming`, `imports`, `formatting` | After observing naming/import/formatting patterns | +| `utility` | `data.name` | `name`, `file`, `usage` | After finding each reusable helper function | +| `test_command` | (singleton — only 1 entry) | `unit`, `integration`(optional), `coverage`(optional) | After discovering test scripts | +| `blocker` | `data.issue` | `issue`, `severity` (high\|medium\|low), `impact` | When hitting any blocking issue | + +### Discovery Entry Format + +Each line is a self-contained JSON object with exactly these top-level fields: + +```jsonl +{"ts":"","agent":"cd","type":"","data":{}} +``` + +### Protocol Rules + +1. **Read board first** — before own exploration, read `discoveries.ndjson` (if exists) and skip already-covered areas +2. **Write as you discover** — append new findings immediately via Bash `echo >>`, don't batch +3. **Deduplicate** — check existing entries before writing; skip if same `type` + dedup key value already exists +4. **Never modify existing lines** — append-only, no edits, no deletions + +--- + ## Execution Process ### Phase 1: Planning & Setup @@ -64,12 +119,22 @@ The Code Developer is responsible for implementing features according to the pla - Requirements from requirements-analyst.md - Project tech stack and guidelines -2. **Understand Project Structure** +2. **Read Discovery Board** + - Read `{progressDir}/coordination/discoveries.ndjson` (if exists) + - Parse entries by type — note what's already discovered + - If `tech_stack` / `architecture` exist → skip project structure exploration + - If `code_pattern` / `code_convention` exist → adopt conventions directly + - If `integration_point` exist → know target files without searching + - If `similar_impl` exist → read reference files for consistency + - If `test_command` exist → use known commands for testing + +3. **Understand Project Structure** (skip areas covered by board) - Review similar existing implementations - Understand coding conventions - Check for relevant utilities/libraries + - **Write discoveries**: append `code_convention`, `utility` entries for new findings -3. **Prepare Environment** +4. **Prepare Environment** - Create feature branch (if using git) - Set up development environment - Prepare test environment diff --git a/.codex/skills/parallel-dev-cycle/roles/exploration-planner.md b/.codex/skills/parallel-dev-cycle/roles/exploration-planner.md index 0198682d..5d99c882 100644 --- a/.codex/skills/parallel-dev-cycle/roles/exploration-planner.md +++ b/.codex/skills/parallel-dev-cycle/roles/exploration-planner.md @@ -53,6 +53,59 @@ The Exploration & Planning Agent is responsible for understanding the codebase a - Skip dependency analysis - Forget to document risks +## Shared Discovery Protocol + +EP agent participates in the **Shared Discovery Board** (`coordination/discoveries.ndjson`). This append-only NDJSON file enables all agents to share exploration findings in real-time, eliminating redundant codebase exploration. + +### Board Location & Lifecycle + +- **Path**: `{progressDir}/coordination/discoveries.ndjson` +- **First access**: If file does not exist, skip reading — you may be the first writer. Create it on first write. +- **Cross-iteration**: Board carries over across iterations. Do NOT clear or recreate it. New iterations append to existing entries. + +### Physical Write Method + +Append one NDJSON line using Bash: +```bash +echo '{"ts":"2026-01-22T10:30:00+08:00","agent":"ep","type":"architecture","data":{"pattern":"layered","layers":["routes","services","models"],"entry":"src/index.ts"}}' >> {progressDir}/coordination/discoveries.ndjson +``` + +### EP Reads (from other agents) + +| type | Dedup Key | Use | +|------|-----------|-----| +| `tech_stack` | (singleton) | Skip tech stack detection, jump directly to architecture analysis | +| `project_config` | `data.path` | Know dependencies and scripts without re-scanning config files | +| `existing_feature` | `data.name` | Understand existing functionality as exploration starting points | +| `test_command` | (singleton) | Know how to verify architectural assumptions | +| `test_baseline` | (singleton) | Calibrate plan effort estimates based on current test coverage and pass rate | + +### EP Writes (for other agents) + +| type | Dedup Key | Required `data` Fields | When | +|------|-----------|----------------------|------| +| `architecture` | (singleton — only 1 entry) | `pattern`, `layers[]`, `entry` | After mapping overall system structure | +| `code_pattern` | `data.name` | `name`, `description`, `example_file` | After identifying each coding convention | +| `integration_point` | `data.file` | `file`, `description`, `exports[]` | After locating each integration target | +| `similar_impl` | `data.feature` | `feature`, `files[]`, `relevance` (high\|medium\|low) | After finding each reference implementation | + +### Discovery Entry Format + +Each line is a self-contained JSON object with exactly these top-level fields: + +```jsonl +{"ts":"","agent":"ep","type":"","data":{}} +``` + +### Protocol Rules + +1. **Read board first** — before own exploration, read `discoveries.ndjson` (if exists) and skip already-covered areas +2. **Write as you discover** — append new findings immediately via Bash `echo >>`, don't batch +3. **Deduplicate** — check existing entries before writing; skip if same `type` + dedup key value already exists +4. **Never modify existing lines** — append-only, no edits, no deletions + +--- + ## Execution Process ### Phase 1: Codebase Exploration @@ -62,19 +115,28 @@ The Exploration & Planning Agent is responsible for understanding the codebase a - Requirements from RA - Project tech stack and guidelines -2. **Explore Architecture** +2. **Read Discovery Board** + - Read `{progressDir}/coordination/discoveries.ndjson` (if exists) + - Parse entries by type — note what's already discovered + - If `tech_stack` exists → skip tech stack scanning, use shared data + - If `project_config` exists → skip package.json/tsconfig reading + - If `existing_feature` entries exist → use as exploration starting points + +3. **Explore Architecture** (skip areas covered by board) - Identify existing patterns and conventions - Find similar feature implementations - Map module boundaries - Document current architecture + - **Write discoveries**: append `architecture`, `code_pattern`, `integration_point`, `similar_impl` entries to board -3. **Analyze Integration Points** +4. **Analyze Integration Points** - Where will new code integrate? - What interfaces need to match? - What data models exist? - What dependencies exist? + - **Write discoveries**: append `integration_point` entries for each finding -4. **Generate Exploration Report** +5. **Generate Exploration Report** - Write `exploration.md` documenting findings - Include architecture overview - Document identified patterns @@ -82,7 +144,12 @@ The Exploration & Planning Agent is responsible for understanding the codebase a ### Phase 2: Planning -1. **Decompose Requirements** +1. **Re-read Discovery Board** + - Check for newly appeared entries since Phase 1 (other agents may have written) + - If `test_baseline` exists → calibrate effort estimates based on current coverage/pass rate + - If `blocker` entries exist → factor into risk assessment and task dependencies + +2. **Decompose Requirements** - Convert each requirement to one or more tasks - Identify logical grouping - Determine task sequencing diff --git a/.codex/skills/parallel-dev-cycle/roles/requirements-analyst.md b/.codex/skills/parallel-dev-cycle/roles/requirements-analyst.md index ea8a8284..f7cdb098 100644 --- a/.codex/skills/parallel-dev-cycle/roles/requirements-analyst.md +++ b/.codex/skills/parallel-dev-cycle/roles/requirements-analyst.md @@ -50,6 +50,57 @@ The Requirements Analyst maintains **a single file** (`requirements.md`) contain - Forget to increment version number - Skip documenting edge cases +## Shared Discovery Protocol + +RA agent participates in the **Shared Discovery Board** (`coordination/discoveries.ndjson`). This append-only NDJSON file enables all agents to share exploration findings in real-time, eliminating redundant codebase exploration. + +### Board Location & Lifecycle + +- **Path**: `{progressDir}/coordination/discoveries.ndjson` +- **First access**: If file does not exist, skip reading — you are the first writer. Create it on first write. +- **Cross-iteration**: Board carries over across iterations. Do NOT clear or recreate it. New iterations append to existing entries. + +### Physical Write Method + +Append one NDJSON line using Bash: +```bash +echo '{"ts":"2026-01-22T10:00:00+08:00","agent":"ra","type":"tech_stack","data":{"language":"TypeScript","framework":"Express","test":"Jest","build":"tsup"}}' >> {progressDir}/coordination/discoveries.ndjson +``` + +### RA Reads (from other agents) + +| type | Dedup Key | Use | +|------|-----------|-----| +| `architecture` | (singleton) | Understand system structure for requirements scoping | +| `similar_impl` | `data.feature` | Identify existing features to avoid duplicate requirements | +| `test_baseline` | (singleton) | Calibrate NFR targets (coverage, pass rate) based on current state | +| `blocker` | `data.issue` | Incorporate known constraints into requirements | + +### RA Writes (for other agents) + +| type | Dedup Key | Required `data` Fields | When | +|------|-----------|----------------------|------| +| `tech_stack` | (singleton — only 1 entry) | `language`, `framework`, `test`, `build` | After reading package.json / project config | +| `project_config` | `data.path` | `path`, `key_deps[]`, `scripts{}` | After scanning each project config file | +| `existing_feature` | `data.name` | `name`, `files[]`, `summary` | After identifying each existing capability | + +### Discovery Entry Format + +Each line is a self-contained JSON object with exactly these top-level fields: + +```jsonl +{"ts":"","agent":"ra","type":"","data":{}} +``` + +### Protocol Rules + +1. **Read board first** — before own exploration, read `discoveries.ndjson` (if exists) and skip already-covered areas +2. **Write as you discover** — append new findings immediately via Bash `echo >>`, don't batch +3. **Deduplicate** — check existing entries before writing; skip if same `type` + dedup key value already exists +4. **Never modify existing lines** — append-only, no edits, no deletions + +--- + ## Execution Process ### Phase 1: Initial Analysis (v1.0.0) @@ -59,24 +110,36 @@ The Requirements Analyst maintains **a single file** (`requirements.md`) contain - Task description from state - Project tech stack and guidelines -2. **Analyze Explicit Requirements** +2. **Read Discovery Board** + - Read `{progressDir}/coordination/discoveries.ndjson` (if exists) + - Parse entries by type — note what's already discovered + - If `tech_stack` exists → skip tech stack detection + - If `existing_feature` entries exist → incorporate into requirements baseline + +3. **Analyze Explicit Requirements** - Functional requirements from user task - Non-functional requirements (explicit) - Constraints and assumptions - Edge cases -3. **Proactive Enhancement** (NEW - Self-Enhancement Phase) +4. **Write Discoveries** + - Append `tech_stack` entry if not already on board (from package.json, tsconfig, etc.) + - Append `project_config` entry with key deps and scripts + - Append `existing_feature` entries for each existing capability found during analysis + +5. **Proactive Enhancement** (Self-Enhancement Phase) - Execute enhancement strategies based on triggers - Scan codebase for implied requirements + - **Read Discovery Board again** — check for `architecture`, `integration_point`, `blocker` from EP/CD/VAS (may have appeared since step 2) - Analyze peer agent outputs (EP, CD, VAS from previous iteration) - Suggest associated features and NFR scaffolding -4. **Consolidate & Finalize** +6. **Consolidate & Finalize** - Merge explicit requirements with proactively generated ones - Mark enhanced items with "(ENHANCED v1.0.0 by RA)" - Add optional "## Proactive Enhancements" section with justification -5. **Generate Single File** +6. **Generate Single File** - Write `requirements.md` v1.0.0 - Include all sections in one document - Add version header diff --git a/.codex/skills/parallel-dev-cycle/roles/validation-archivist.md b/.codex/skills/parallel-dev-cycle/roles/validation-archivist.md index 53af767a..c2c73b38 100644 --- a/.codex/skills/parallel-dev-cycle/roles/validation-archivist.md +++ b/.codex/skills/parallel-dev-cycle/roles/validation-archivist.md @@ -55,6 +55,61 @@ The Validation & Archival Agent is responsible for verifying implementation qual - Forget to document breaking changes - Skip regression testing +## Shared Discovery Protocol + +VAS agent participates in the **Shared Discovery Board** (`coordination/discoveries.ndjson`). This append-only NDJSON file enables all agents to share exploration findings in real-time, eliminating redundant codebase exploration. + +### Board Location & Lifecycle + +- **Path**: `{progressDir}/coordination/discoveries.ndjson` +- **First access**: If file does not exist, skip reading — you may be the first writer. Create it on first write. +- **Cross-iteration**: Board carries over across iterations. Do NOT clear or recreate it. New iterations append to existing entries. + +### Physical Write Method + +Append one NDJSON line using Bash: +```bash +echo '{"ts":"2026-01-22T12:00:00+08:00","agent":"vas","type":"test_baseline","data":{"total":120,"passing":118,"coverage_pct":82,"framework":"jest","config":"jest.config.ts"}}' >> {progressDir}/coordination/discoveries.ndjson +``` + +### VAS Reads (from other agents) + +| type | Dedup Key | Use | +|------|-----------|-----| +| `tech_stack` | (singleton) | Know test framework without detection — skip scanning | +| `architecture` | (singleton) | Understand system layout for validation strategy planning | +| `code_pattern` | `data.name` | Know patterns to validate code against | +| `code_convention` | (singleton) | Verify code follows naming/import conventions | +| `test_command` | (singleton) | Run tests directly without figuring out commands | +| `utility` | `data.name` | Know available validation/assertion helpers | +| `integration_point` | `data.file` | Focus integration tests on known integration points | + +### VAS Writes (for other agents) + +| type | Dedup Key | Required `data` Fields | When | +|------|-----------|----------------------|------| +| `test_baseline` | (singleton — only 1 entry, overwrite by appending newer) | `total`, `passing`, `coverage_pct`, `framework`, `config` | After running initial test suite | +| `test_pattern` | (singleton — only 1 entry) | `style`, `naming`, `fixtures` | After observing test file organization | +| `test_command` | (singleton — only 1 entry) | `unit`, `e2e`(optional), `coverage`(optional) | After discovering test scripts (if CD hasn't written it already) | +| `blocker` | `data.issue` | `issue`, `severity` (high\|medium\|low), `impact` | When tests reveal blocking issues | + +### Discovery Entry Format + +Each line is a self-contained JSON object with exactly these top-level fields: + +```jsonl +{"ts":"","agent":"vas","type":"","data":{}} +``` + +### Protocol Rules + +1. **Read board first** — before own exploration, read `discoveries.ndjson` (if exists) and skip already-covered areas +2. **Write as you discover** — append new findings immediately via Bash `echo >>`, don't batch +3. **Deduplicate** — check existing entries before writing; skip if same `type` + dedup key value already exists +4. **Never modify existing lines** — append-only, no edits, no deletions + +--- + ## Execution Process ### Phase 1: Test Execution @@ -64,22 +119,33 @@ The Validation & Archival Agent is responsible for verifying implementation qual - Requirements from RA agent - Project tech stack and guidelines -2. **Prepare Test Environment** +2. **Read Discovery Board** + - Read `{progressDir}/coordination/discoveries.ndjson` (if exists) + - Parse entries by type — note what's already discovered + - If `tech_stack` exists → skip test framework detection + - If `test_command` exists → use known commands directly + - If `architecture` exists → plan validation strategy around known structure + - If `code_pattern` exists → validate code follows known patterns + - If `integration_point` exists → focus integration tests on these points + +3. **Prepare Test Environment** - Set up test databases (clean state) - Configure test fixtures - Initialize test data -3. **Run Test Suites** +4. **Run Test Suites** (use `test_command` from board if available) - Execute unit tests - Execute integration tests - Execute end-to-end tests - Run security tests if applicable + - **Write discoveries**: append `test_baseline` with initial results -4. **Collect Results** +5. **Collect Results** - Test pass/fail status - Execution time - Error messages and stack traces - Coverage metrics + - **Write discoveries**: append `test_pattern` if test organization discovered ### Phase 2: Analysis & Validation