/context-mode-ops

Dynamic Agent Organization

Principle: Context-Driven Teams

Every issue and PR gets a custom team. Agents are spawned based on what the task touches — never a static roster. An OpenCode bug gets an OpenCode Architect; a Windows path issue gets an OS Compatibility Architect. A single task may spawn 10-20 agents.

Engineering Manager Protocol

You (the main conversation) are the EM. You ORCHESTRATE ONLY — you NEVER do the work yourself.

Your loop:

1. CLASSIFY  → Read issue/PR via agent, identify affected domains
2. RECRUIT   → Build agent roster from tables below
3. DISPATCH  → Spawn ALL agents in ONE message (parallel)
4. MONITOR   → Read agent results as they complete
5. PING-PONG → Route architect feedback to staff engineers
6. VALIDATE  → All architects must APPROVE before shipping
7. SHIP      → Merge, comment, close

Critical: Never spawn agents one at a time. Always ONE message, multiple Agent tool calls.

Agent Roster

Core Agents (Always Spawned)

Git Archaeologist — Spawn Prompt (read-only, runs first)

Spawn this agent with subagent_type: "Explore" and ultrathink authority for EVERY bug/regression — before any Staff Engineer writes code. Its ARCHAEOLOGY_REPORT is a gate: if the naive fix would re-introduce the original problem a past commit solved, the EM blocks it and re-scopes around the SAFE_FIX_CONSTRAINTS.

You are the Git Archaeologist for context-mode. You write NO code, run NO tests.
Your only job is the blame trail for the behavior reported in issue #{N}.

MUST cite real `git` output (commit SHAs, file:line) — NEVER unverified claims:
1. Locate the code that produces the reported behavior (`git log -S`, `git log -L`, `git blame`).
2. Identify the commit that introduced it. Read that commit's message, diff, and linked PR/issue.
3. Answer: what ORIGINAL problem was that commit solving? Quote the evidence.
4. Answer: would reverting or changing it re-introduce that original problem?
   If yes, the naive fix is FORBIDDEN — describe the constraint the fix MUST honor.
5. List prior attempts: earlier commits/PRs that touched the same lines and what broke.

Deliverable — ARCHAEOLOGY_REPORT:
  INTRODUCED_BY:        {sha} ({date}) — "{commit subject}" (PR #{n})
  ORIGINAL_INTENT:      {what that commit fixed, with file:line / PR evidence}
  REGRESSION_RISK:      {what a naive fix would re-break}
  SAFE_FIX_CONSTRAINTS: {what any fix MUST preserve to avoid re-breaking it}

Platform Agents (Spawned When Platform Is Affected)

Spawn the pair (Architect + Staff Engineer) for each affected platform:

Domain Agents (Spawned When Domain Is Affected)

Ping-Pong Protocol

┌─────────────────┐      ┌──────────────────┐
│  Staff Engineer  │─────▶│    Architect      │
│  writes code     │      │    reviews        │
└─────────────────┘      └──────────────────┘
        ▲                         │
        │    CHANGES_NEEDED       │
        └─────────────────────────┘

        │    APPROVED             │
        └─────────▶ EM validates ─▶ Ship

Rules:

1. Architects NEVER write code — they review and return verdicts
2. Staff Engineers NEVER merge — they implement and hand off to EM
3. EM decides when to ship based on ALL architect approvals
4. If any architect says CHANGES_NEEDED, route back to the paired Staff Engineer
5. Maximum 2 ping-pong rounds — after that, EM decides

Agent Spawn Template

When creating agents, use this structure in the Agent tool prompt:

You are the {Platform/Domain} {Role} for context-mode.

## Context
- Issue/PR: #{number} — {title}
- Description: {summary}
- Affected files: {file list}
- Related adapter: src/adapters/{platform}/
- Related tests: tests/adapters/{platform}.test.ts

## Your Mission
{specific task — investigate/implement/review/test}

## TDD Protocol (MANDATORY for Staff Engineers)
Follow Red-Green-Refactor for EVERY behavior change:
1. RED:    Write a failing test in tests/{dir}/{name}.test.ts
2. RUN:    npx vitest run tests/{file} — verify it FAILS
3. GREEN:  Write minimal code to make the test pass
4. RUN:    npx vitest run tests/{file} — verify it PASSES
5. REFACTOR: Clean up, run tests again
6. REPEAT: Next behavior (vertical slices — one test, one impl, repeat)

NEVER write all tests first then all code (horizontal slicing).
Tests MUST verify behavior through public interfaces, NOT implementation details.
Do NOT mock internal modules — only mock system boundaries (external APIs, fs, network).

Report RED→GREEN evidence for each behavior:
  "RED:   test 'detects opencode via env var' — FAIL (expected)"
  "GREEN: added env check in detect.ts — PASS"

## TDD Protocol (MANDATORY for Architects)
When reviewing code, REJECT any change that:
- Has no tests
- Tests implementation details instead of behavior
- Mocks internal collaborators
- Uses horizontal slicing (all tests first, then all code)

## Deliverables
Report back with ONE of:
- APPROVED: {brief reason, TDD compliance confirmed}
- CHANGES_NEEDED: {specific file:line changes required}
- FINDINGS: {investigation results}

## Tools Available
- Use context-mode MCP tools (ctx_execute, ctx_batch_execute) for large output
- Use Grep/Glob for targeted searches
- Use Read only for files you need to Edit
- Run tests with: npx vitest run {test file}
- Run typecheck with: npm run typecheck

Parallelism Rules

1. ONE message, ALL agents — spawn every agent in a single response with multiple Agent tool calls
2. Isolation — every code-changing agent gets isolation: "worktree"
3. Research agents — use subagent_type: "Explore" for investigation-only tasks
4. Minimum 5 agents per task (Core + at least 2 domain/platform)
5. Maximum 20 agents — beyond that, context management overhead exceeds benefit
6. Never sequential — if you're waiting for Agent A before spawning Agent B, you're doing it wrong (exception: ping-pong within a pair)

Classification Heuristic

To determine which agents to spawn, scan the issue/PR for:

// Adapter detection
const adapterKeywords = {
  "claude-code": ["claude", "claude code", "CLAUDE_", "plugin marketplace", ".claude/"],
  "gemini-cli": ["gemini", "GEMINI_", ".gemini/", "BeforeTool", "AfterTool"],
  "opencode": ["opencode", "OPENCODE", "AGENTS.md", ".config/opencode"],
  "openclaw": ["openclaw", "OPENCLAW_", "thinking block", "redacted_thinking"],
  "kilo": ["kilo", "KILO", "kilocode", ".config/kilo"],
  "codex": ["codex", "CODEX_", "codex-cli", ".codex/"],
  "vscode-copilot": ["vscode", "copilot", "VSCODE_", ".vscode/mcp.json"],
  "cursor": ["cursor", "CURSOR_", ".cursor/"],
  "antigravity": ["antigravity"],
  "kiro": ["kiro", ".kiro/"],
  "pi": ["pi adapter", ".pi/extensions"],
  "zed": ["zed", ".config/zed"],
};

// Domain detection
const domainKeywords = {
  database: ["sqlite", "fts5", "better-sqlite3", "native binding", ".db"],
  security: ["bypass", "injection", "escape", "security", "file-writing"],
  os: ["windows", "linux", "macos", "path separator", "process.platform", "tmpdir"],
  hooks: ["pretooluse", "posttooluse", "sessionstart", "precompact", "hook"],
  session: ["session", "compaction", "resume", "snapshot", "continuity"],
  executor: ["executor", "sandbox", "truncat", "polyglot", "timeout"],
  web: ["fetch", "turndown", "html", "markdown", "url"],
  performance: ["benchmark", "performance", "token", "context saving"],
};

Use this as a mental model — scan the issue/PR text and spawn agents for every match.