@cluesmith/codev 3.0.0-rc.11 → 3.0.0-rc.13

package/dist/lib/team-github.js

@@ -67,7 +67,19 @@ export function buildTeamGraphQLQuery(members, owner, name) {
       nodes { ... on Issue { number title url } }
     }
     ${alias}_prs: search(query: "repo:${repo} author:${m.github} is:pr is:open", type: ISSUE, first: 20) {
-      nodes { ... on PullRequest { number title url } }
+      nodes {
+        ... on PullRequest {
+          number
+          title
+          url
+          isDraft
+          createdAt
+          reviewDecision
+          reviewRequests(first: 20) {
+            nodes { requestedReviewer { ... on User { login } } }
+          }
+        }
+      }
     }
     ${alias}_merged: search(query: "repo:${repo} author:${m.github} is:pr is:merged merged:>=${since}", type: ISSUE, first: 20) {
       nodes { ... on PullRequest { number title url mergedAt } }
@@ -81,11 +93,99 @@ export function buildTeamGraphQLQuery(members, owner, name) {
   ${fragments}
 }`;
 }
+/**
+ * Derive review-blocking relationships from every team member's authored PRs.
+ *
+ * Two-pass algorithm:
+ *   1. Collect (author, reviewer, pr) tuples by iterating each author's PRs
+ *      and cross-referencing requested reviewers against the team roster.
+ *   2. Distribute each tuple into the author's `reviewBlocking` array (as
+ *      `direction: 'authored'`) and the reviewer's (as `direction: 'reviewing'`).
+ *
+ * Rules are documented in spec 694:
+ *   - Open, not draft.
+ *   - reviewDecision !== 'APPROVED'.
+ *   - Requested reviewer must resolve to a User (not Team) and match the team roster.
+ *   - Author is guaranteed to be a team member by construction (query scope).
+ */
+export function deriveReviewBlocking(prsByAuthor, members) {
+    // Case-insensitive lookup: lower-case github handle → TeamMember.
+    const roster = new Map();
+    for (const m of members) {
+        if (!isValidGitHubHandle(m.github))
+            continue;
+        roster.set(m.github.toLowerCase(), m);
+    }
+    const displayName = (m) => m.name || m.github;
+    const perMember = new Map();
+    const entriesFor = (handle) => {
+        const existing = perMember.get(handle);
+        if (existing)
+            return existing;
+        const fresh = [];
+        perMember.set(handle, fresh);
+        return fresh;
+    };
+    for (const [authorHandle, prs] of prsByAuthor) {
+        const author = roster.get(authorHandle.toLowerCase());
+        if (!author)
+            continue;
+        for (const pr of prs) {
+            if (pr.isDraft)
+                continue;
+            if (pr.reviewDecision === 'APPROVED')
+                continue;
+            const requestedNodes = pr.reviewRequests?.nodes ?? [];
+            for (const node of requestedNodes) {
+                const login = node?.requestedReviewer?.login;
+                if (!login)
+                    continue; // Team-based requests resolve to undefined login.
+                const reviewer = roster.get(login.toLowerCase());
+                if (!reviewer)
+                    continue; // External reviewer.
+                if (reviewer.github.toLowerCase() === author.github.toLowerCase())
+                    continue; // Self-review edge.
+                const prMeta = {
+                    number: pr.number,
+                    title: pr.title,
+                    url: pr.url,
+                    createdAt: pr.createdAt ?? '',
+                };
+                entriesFor(author.github).push({
+                    direction: 'authored',
+                    otherName: displayName(reviewer),
+                    otherGithub: reviewer.github,
+                    pr: prMeta,
+                });
+                entriesFor(reviewer.github).push({
+                    direction: 'reviewing',
+                    otherName: displayName(author),
+                    otherGithub: author.github,
+                    pr: prMeta,
+                });
+            }
+        }
+    }
+    // Sort each member's entries oldest-first (stable, with PR number as tiebreaker).
+    for (const list of perMember.values()) {
+        list.sort((a, b) => {
+            const byDate = (a.pr.createdAt ?? '').localeCompare(b.pr.createdAt ?? '');
+            if (byDate !== 0)
+                return byDate;
+            return a.pr.number - b.pr.number;
+        });
+    }
+    return perMember;
+}
+// =============================================================================
+// Response Parser
+// =============================================================================
 /**
  * Parse the GraphQL response into a map of github handle → TeamMemberGitHubData.
  */
 export function parseTeamGraphQLResponse(data, members) {
     const result = new Map();
+    const prsByAuthor = new Map();
     for (const member of members) {
         if (!isValidGitHubHandle(member.github))
             continue;
@@ -94,15 +194,24 @@ export function parseTeamGraphQLResponse(data, members) {
         const prs = data[`${alias}_prs`];
         const merged = data[`${alias}_merged`];
         const closed = data[`${alias}_closed`];
+        const openPrNodes = prs?.nodes ?? [];
+        prsByAuthor.set(member.github, openPrNodes);
         result.set(member.github, {
             assignedIssues: (assigned?.nodes ?? []).map(n => ({ number: n.number, title: n.title, url: n.url })),
-            openPRs: (prs?.nodes ?? []).map(n => ({ number: n.number, title: n.title, url: n.url })),
+            openPRs: openPrNodes.map(n => ({ number: n.number, title: n.title, url: n.url })),
             recentActivity: {
                 mergedPRs: (merged?.nodes ?? []).map(n => ({ number: n.number, title: n.title, url: n.url, mergedAt: n.mergedAt })),
                 closedIssues: (closed?.nodes ?? []).map(n => ({ number: n.number, title: n.title, url: n.url, closedAt: n.closedAt })),
             },
+            reviewBlocking: [],
         });
     }
+    const perMemberBlocking = deriveReviewBlocking(prsByAuthor, members);
+    for (const [handle, entries] of perMemberBlocking) {
+        const bucket = result.get(handle);
+        if (bucket)
+            bucket.reviewBlocking = entries;
+    }
     return result;
 }
 // =============================================================================

package/dist/lib/team-github.js.map

@@ -1 +1 @@
-{"version":3,"file":"team-github.js","sourceRoot":"","sources":["../../src/lib/team-github.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"team-github.js","sourceRoot":"","sources":["../../src/lib/team-github.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cluesmith/codev",
-  "version": "3.0.0-rc.11",
+  "version": "3.0.0-rc.13",
   "description": "Codev CLI - AI-assisted software development framework",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "skeleton",
     "templates",
     "dashboard-dist",
-    "scripts/forge"
+    "scripts/forge",
+    "scripts/postinstall.mjs"
   ],
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.41",
@@ -48,8 +49,8 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.0.15",
-    "@cluesmith/codev-dashboard": "0.0.0",
-    "@cluesmith/codev-types": "0.0.1"
+    "@cluesmith/codev-types": "0.0.1",
+    "@cluesmith/codev-dashboard": "0.0.0"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -72,7 +73,7 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "pnpm clean && tsc && pnpm build:dashboard && pnpm copy-skeleton",
-    "build:dashboard": "cd ../dashboard && pnpm build && cp -r dist ../../packages/codev/dashboard-dist",
+    "build:dashboard": "cd ../dashboard && pnpm build && rm -rf ../../packages/codev/dashboard-dist && cp -r dist ../../packages/codev/dashboard-dist",
     "dev:dashboard": "cd ../dashboard && pnpm dev",
     "copy-skeleton": "rm -rf skeleton && cp -r ../../codev-skeleton skeleton",
     "dev": "tsx src/cli.ts",
@@ -82,6 +83,6 @@
     "test:e2e:watch": "vitest --config vitest.e2e.config.ts",
     "test:e2e:playwright": "pnpm exec playwright test",
     "test:e2e:cli": "pnpm build && vitest run --config vitest.cli.config.ts",
-    "postinstall": "node -e \"try{require('fs').chmodSync(require('path').join(require.resolve('node-pty'),'..','..','prebuilds',process.platform+'-'+process.arch,'spawn-helper'),0o755)}catch{}\""
+    "postinstall": "node ./scripts/postinstall.mjs"
   }
 }

package/scripts/forge/github/issue-list.sh

@@ -1,4 +1,4 @@
 #!/bin/sh
 # Forge concept: issue-list (GitHub via gh CLI)
-# Output: JSON [{number, title, url, labels, createdAt, author}]
-exec gh issue list --limit 200 --json number,title,url,labels,createdAt,author
+# Output: JSON [{number, title, url, labels, createdAt, author, assignees}]
+exec gh issue list --limit 200 --json number,title,url,labels,createdAt,author,assignees

package/scripts/postinstall.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+// Restores executable bits that pnpm pack/publish strips from files outside
+// the `bin` field. See issue #693 — without this, `afx spawn` fails with
+// Permission denied when invoking forge concept scripts.
+
+import { chmodSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const forgeRoot = join(here, 'forge');
+
+function chmodForgeScripts(root) {
+  let providers;
+  try {
+    providers = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const provider of providers) {
+    if (!provider.isDirectory()) continue;
+    const providerDir = join(root, provider.name);
+    for (const entry of readdirSync(providerDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.sh')) continue;
+      chmodSync(join(providerDir, entry.name), 0o755);
+    }
+  }
+}
+
+function chmodNodePtySpawnHelper() {
+  try {
+    const require = createRequire(import.meta.url);
+    const ptyEntry = require.resolve('node-pty');
+    const helper = join(
+      ptyEntry,
+      '..',
+      '..',
+      'prebuilds',
+      `${process.platform}-${process.arch}`,
+      'spawn-helper'
+    );
+    chmodSync(helper, 0o755);
+  } catch {
+    // node-pty may not ship a prebuild for this platform; harmless.
+  }
+}
+
+chmodForgeScripts(forgeRoot);
+chmodNodePtySpawnHelper();

package/skeleton/protocols/research/builder-prompt.md

@@ -0,0 +1,85 @@
+# {{protocol_name}} Builder ({{mode}} mode)
+
+You are conducting multi-agent research.
+
+{{#if mode_soft}}
+## Mode: SOFT
+You are running in SOFT mode. This means:
+- You follow the RESEARCH protocol yourself (no porch orchestration)
+- The architect monitors your work and verifies you're adhering to the protocol
+- Use `consult` for the 3-way investigation and critique phases
+{{/if}}
+
+{{#if mode_strict}}
+## Mode: STRICT
+You are running in STRICT mode. This means:
+- Porch orchestrates your work
+- Run: `porch next` to get your next tasks
+- Follow porch signals and gate approvals
+
+### ABSOLUTE RESTRICTIONS (STRICT MODE)
+- **NEVER edit `status.yaml` directly** — only porch commands may modify project state
+- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to
+- **NEVER skip the 3-way consultation** — always follow porch next → porch done cycle
+{{/if}}
+
+## Protocol
+Follow the RESEARCH protocol: `codev/protocols/research/protocol.md`
+
+## RESEARCH Overview
+
+The RESEARCH protocol produces a high-confidence research report through triangulation:
+
+1. **Scope** — Define the precise question, scope, and acceptance criteria. Write a research brief. Gate: architect approval before proceeding.
+2. **Investigate** — Dispatch the brief to 3 models (Gemini, Codex, Claude) in parallel. Each investigates independently. No anchoring — they don't see each other's work.
+3. **Synthesize** — Read all 3 reports. Identify consensus, disagreements, and unique contributions. Write a single synthesis report organized by topic (not by model).
+4. **Critique** — Send the synthesis back to all 3 models for critique. Incorporate valid feedback. Document rejected critique. Finalize the report.
+
+## Output Location
+
+All artifacts go to `codev/research/`:
+- `<topic>-brief.md` — the scoped question (Phase 1)
+- `<topic>-gemini.md`, `<topic>-codex.md`, `<topic>-claude.md` — individual investigations (Phase 2)
+- `<topic>.md` — the final synthesis report (Phase 3+4, this is the deliverable)
+- `<topic>-critique-rebuttals.md` — critique responses (Phase 4)
+
+{{#if task}}
+## Research Topic
+{{task_text}}
+{{/if}}
+
+## Key Principles
+
+- **Triangulate**: consensus across 3 models > any single model's claim
+- **Cite sources**: tell investigators to provide sources where possible
+- **Be candid about uncertainty**: "I don't know" > confabulation
+- **Organize by topic, not by model**: the synthesis is a standalone document
+- **Note surprises**: the most valuable findings are often unexpected
+- **Keep it concise**: the synthesis should be shorter than the sum of the investigations
+
+## Using consult for 3-way Investigation
+
+For the investigate phase, use the `consult` CLI to dispatch to each model:
+
+```bash
+# Phase 2: parallel investigation
+consult -m gemini --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-gemini.md &
+consult -m codex --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-codex.md &
+consult -m claude --prompt-file codev/research/<topic>-brief.md --output codev/research/<topic>-claude.md &
+wait
+```
+
+For the critique phase:
+```bash
+# Phase 4: parallel critique
+consult -m gemini --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-gemini.md &
+consult -m codex --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-codex.md &
+consult -m claude --prompt "Critique this research synthesis for gaps, errors, and bias:" --prompt-file codev/research/<topic>.md --output codev/research/<topic>-critique-claude.md &
+wait
+```
+
+## Getting Started
+1. Read the RESEARCH protocol document
+2. Understand the research question from the architect
+3. Write the research brief (Phase 1)
+4. Wait for scope-approval before proceeding to investigation

package/skeleton/protocols/research/protocol.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "../../protocol-schema.json",
+  "name": "research",
+  "version": "1.0.0",
+  "description": "Multi-agent research with 3-way investigation, synthesis, and critique",
+  "input": {
+    "type": "none",
+    "required": false,
+    "default_for": []
+  },
+  "hooks": {
+    "pre-spawn": {}
+  },
+  "phases": [
+    {
+      "id": "scope",
+      "name": "Scope",
+      "description": "Define the research question, scope, and acceptance criteria",
+      "type": "once",
+      "steps": [
+        "clarify_question",
+        "define_scope",
+        "define_acceptance_criteria",
+        "create_research_brief"
+      ],
+      "gate": {
+        "name": "scope-approval",
+        "description": "Architect confirms the research question is correctly scoped",
+        "requires": ["research_brief_exists"],
+        "next": "investigate"
+      }
+    },
+    {
+      "id": "investigate",
+      "name": "Investigate",
+      "description": "3-way parallel investigation — each model researches independently",
+      "type": "once",
+      "steps": [
+        "dispatch_gemini_investigation",
+        "dispatch_codex_investigation",
+        "dispatch_claude_investigation",
+        "collect_all_reports"
+      ],
+      "consultation": {
+        "enabled": true,
+        "models": ["codex"],
+        "parallel": true,
+        "type": "investigation"
+      },
+      "transition": {
+        "on_complete": "synthesize"
+      }
+    },
+    {
+      "id": "synthesize",
+      "name": "Synthesize",
+      "description": "Merge the 3 investigation reports into a single coherent research document",
+      "type": "once",
+      "steps": [
+        "read_all_investigation_reports",
+        "identify_consensus_and_disagreements",
+        "resolve_conflicts",
+        "write_synthesis_report"
+      ],
+      "transition": {
+        "on_complete": "critique"
+      }
+    },
+    {
+      "id": "critique",
+      "name": "Critique",
+      "description": "3-way review of the synthesis — each model critiques for gaps, errors, and bias",
+      "type": "once",
+      "steps": [
+        "dispatch_gemini_critique",
+        "dispatch_codex_critique",
+        "dispatch_claude_critique",
+        "incorporate_feedback",
+        "finalize_report"
+      ],
+      "consultation": {
+        "enabled": true,
+        "models": ["codex"],
+        "parallel": true,
+        "type": "critique"
+      },
+      "gate": {
+        "name": "research-complete",
+        "description": "Research report finalized",
+        "requires": ["report_finalized"],
+        "next": null
+      }
+    }
+  ],
+  "signals": {
+    "PHASE_COMPLETE": {
+      "description": "Signal current phase is complete",
+      "transitions_to": "next_phase"
+    },
+    "BLOCKED": {
+      "description": "Signal research is blocked",
+      "requires": "reason"
+    },
+    "SCOPE_REJECTED": {
+      "description": "Architect rejects the scope — rework needed",
+      "transitions_to": "scope"
+    }
+  },
+  "defaults": {
+    "mode": "strict",
+    "consultation": {
+      "enabled": true,
+      "models": ["codex"],
+      "parallel": true
+    },
+    "checks": {}
+  }
+}

package/skeleton/protocols/research/protocol.md

@@ -0,0 +1,169 @@
+# RESEARCH Protocol
+
+## Overview
+
+Multi-agent research with 3-way investigation, synthesis, and critique. Three AI models independently investigate a question, their findings are synthesized into a single report, and then all three models critique the synthesis for gaps, errors, and bias.
+
+**Core Principle**: Triangulate. No single model's knowledge is authoritative. Consensus across models is more reliable than any individual output.
+
+## When to Use
+
+**Use for**: Competitive analysis, technology evaluation, market research, architectural decision support, "what's the state of X?" questions, exploring unfamiliar domains.
+
+**Skip for**: Implementation work (use SPIR/ASPIR), quick questions (just ask), experiments (use EXPERIMENT), known-answer lookups (just search).
+
+## Output
+
+All research artifacts go to `codev/research/`. The final deliverable is a single synthesis report at `codev/research/<topic>.md`.
+
+## Phases
+
+### Phase 1: Scope
+
+**Purpose**: Make sure we're asking the right question before spending 3 models' worth of compute on answering it.
+
+The builder:
+1. Reads the architect's research request
+2. Clarifies the question — what specifically are we trying to learn?
+3. Defines the scope — what's in, what's out, what depth is needed
+4. Defines acceptance criteria — what does a good answer look like?
+5. Writes a **research brief** (`codev/research/<topic>-brief.md`) with:
+   - The precise question(s)
+   - Scope boundaries
+   - **Required targets** (when applicable — not all research questions have them). When the user names specific projects, products, or systems, those are exemplars of a CLASS, not an exhaustive list. The brief should:
+     - List the named targets as required coverage (each gets a dedicated section)
+     - Identify the CLASS they represent (e.g., "open-source always-on agent frameworks")
+     - Instruct investigators to find OTHER members of that class the user didn't name — discovering what the user SHOULD be thinking about is often the most valuable part of the research
+     - If an investigator cannot find information about a required target, they must say so explicitly — not silently skip it
+   - **Optional context** — additional sources that may be useful but are not required
+   - What a useful answer looks like
+   - Suggested sources or angles for the investigators
+6. Sends the brief to the architect for approval
+
+**Gate**: `scope-approval` — the architect confirms the question is correctly scoped before the 3-way investigation begins. This prevents wasting compute on a badly-framed question.
+
+### Phase 2: Investigate (3-way parallel)
+
+**Purpose**: Get three independent perspectives on the question.
+
+The builder dispatches the research brief to three models (Gemini, Codex, Claude) via `consult`. Each model:
+1. Receives the scoped research brief
+2. Independently investigates using web search, its training knowledge, and reasoning
+3. Produces a standalone investigation report with:
+   - **A dedicated section for each required target** from the brief. Every required target gets its own heading with specific findings — not mentioned in passing, not substituted with an easier target. If a required target yields no findings, the section must say "No information found" rather than being omitted.
+   - Findings (with sources where possible)
+   - Confidence levels on key claims
+   - Gaps it couldn't fill
+   - Surprises or things that contradicted expectations
+
+The investigations run in **parallel** — each model works independently without seeing the others' output. This prevents anchoring bias.
+
+Investigation reports are saved to:
+- `codev/research/<topic>-gemini.md`
+- `codev/research/<topic>-codex.md`
+- `codev/research/<topic>-claude.md`
+
+### Phase 3: Synthesize
+
+**Purpose**: Merge three independent reports into one coherent document.
+
+The builder:
+1. Reads all three investigation reports
+2. Identifies **consensus** — what all three agree on (highest confidence)
+3. Identifies **disagreements** — where models contradict each other
+4. Resolves conflicts — picks the best-supported position, notes the disagreement
+5. Identifies **unique contributions** — things only one model found that the others missed
+6. Writes the **synthesis report** (`codev/research/<topic>.md`) with:
+   - **Scope summary** — a short section (before the executive summary) restating the research question, required targets, and scope boundaries from the brief. A reader should understand what was asked without needing to read the brief separately.
+   - Executive summary
+   - Findings (organized by topic, not by model)
+   - Confidence annotations (consensus vs. single-source)
+   - Gaps and limitations
+   - Recommendations (if the research brief asked for them)
+
+The synthesis is written as a **standalone document** — a reader should never need to reference the individual investigation reports. Those are kept as appendices for traceability.
+
+### Phase 4: Critique (3-way review)
+
+**Purpose**: Pressure-test the synthesis for gaps, errors, and bias.
+
+The builder dispatches the synthesis report back to all three models for critique. Each model:
+1. Reads the synthesis
+2. **Checks coverage against the brief** — does every required target from the research brief have dedicated coverage in the synthesis? Lists any required targets that were named in the brief but have zero or minimal coverage. This is the #1 critique check.
+3. Checks for factual errors or unsupported claims
+4. Identifies gaps — important aspects the synthesis missed
+5. Flags potential bias — did the synthesis over-weight one model's perspective?
+6. Suggests specific improvements
+
+The builder then:
+1. Incorporates valid critique
+2. Documents rejected critique with rationale
+3. Finalizes the report
+4. Commits to `codev/research/<topic>.md`
+
+## File Structure
+
+Only the brief and final report are checked in. Individual investigation reports and full critique outputs are working artifacts — useful during the process but not committed to the repo.
+
+```
+codev/research/
+├── <topic>-brief.md              # Phase 1: scoped research question (checked in)
+└── <topic>.md                    # Phase 3+4: final synthesis (the deliverable, checked in)
+```
+
+The final report includes:
+- A **"Disagreements and resolution"** section documenting where the three investigators disagreed and how the synthesis resolved each disagreement
+- A **"Changes from critique"** section summarizing what the critique phase changed (not the full critique — just what was added, removed, or corrected and why)
+
+Individual investigation reports (`<topic>-gemini.md`, `<topic>-codex.md`, `<topic>-claude.md`) and raw critique outputs are kept locally during the research process but NOT committed. The final report is the deliverable; the process artifacts are disposable.
+
+## Best Practices
+
+### Scoping
+- A good research question is specific enough to answer in 1500-3000 words per model
+- "What's the state of X?" is too broad — "What are the top 5 players in X, their strengths/weaknesses, and the structural gaps?" is better
+- Include the "so what" — why are we researching this? What decision does it inform?
+
+### Investigation
+- Tell each model to cite sources where possible
+- Tell each model to be candid about uncertainty — "I don't know" is better than confabulation
+- Tell each model to note surprises — the most valuable findings are often the unexpected ones
+
+### Synthesis
+- Organize by topic, not by model ("here's what we found about X" not "here's what Gemini said")
+- Weight consensus over single-model claims
+- Don't smooth over disagreements — note them explicitly
+- Keep the synthesis shorter than the sum of the investigations
+
+### Critique
+- Critiquers should focus on gaps and errors, not style
+- A critique that says "add more about X" is useful; "rewrite the intro" is not
+- The builder should reject critique that's outside the original scope
+
+## Integration with Other Protocols
+
+### Research → SPIR
+When research informs a feature decision:
+1. Reference the research report in the spec
+2. Link specific findings as evidence for design choices
+
+### Research → EXPERIMENT
+When research identifies something worth testing:
+1. Create an experiment to validate the research finding
+2. Reference the research report as motivation
+
+## Git Workflow
+
+### Commits
+```
+[Research: topic] Scoped research brief
+[Research: topic] 3-way investigation complete
+[Research: topic] Synthesis report
+[Research: topic] Final report (post-critique)
+```
+
+### What to Commit
+- All investigation reports (for traceability)
+- The final synthesis (the deliverable)
+- The critique rebuttals (for process transparency)
+- Do NOT commit raw web search results or intermediate notes

package/skeleton/templates/AGENTS.md

@@ -14,6 +14,7 @@ This project uses **Codev** for AI-assisted development.
 - **BUGFIX**: Bug fixes from GitHub issues (`codev/protocols/bugfix/protocol.md`)
 - **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
 - **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
+- **RESEARCH**: Multi-agent research with 3-way investigation, synthesis, and critique (`codev/protocols/research/protocol.md`)
 
 ## Key Locations