diff --git a/docs/plans/agent-surface-and-ops.md b/docs/plans/agent-surface-and-ops.md index f6851ca..d0548d5 100644 --- a/docs/plans/agent-surface-and-ops.md +++ b/docs/plans/agent-surface-and-ops.md @@ -5,14 +5,17 @@ > **Purpose:** Prioritized work queue for agent UX, MCP ergonomics, indexing reliability, and TS/JS graph substrate gaps. Each item has its own plan file; this index links priority tiers and recommended ship order. > > **Roadmap home:** [§ Backlog — Agent & indexing ops](../roadmap.md#agent--indexing-ops) +> +> **PR tracker (pause/resume):** [agent-surface-delivery.md](./agent-surface-delivery.md) --- ## Recommended ship order ``` -P0 (ops polish, ~2 weeks total) - mcp-server-instructions → wsl-watch-policy → git-hook-auto-sync → mcp-tool-allowlist +P0 (ops polish, ~2 weeks total — see delivery tracker for PR bundling) + PR1: mcp-server-instructions + mcp-tool-allowlist + PR2: wsl-watch-policy → git-hook-auto-sync P1 (agent + reliability, parallel tracks) Track A: mcp-trace-explore-tools (+ call-path recipes) diff --git a/docs/plans/agent-surface-delivery.md b/docs/plans/agent-surface-delivery.md new file mode 100644 index 0000000..c237a19 --- /dev/null +++ b/docs/plans/agent-surface-delivery.md @@ -0,0 +1,95 @@ +# Agent surface delivery — PR tracker + +> **Status:** in flight · **Created:** 2026-05-25 +> +> **Purpose:** Map [`agent-surface-and-ops`](./agent-surface-and-ops.md) plans to concrete PRs, parallelization rules, and current status so work can pause/resume outside any single agent session. +> +> **Plan index:** [agent-surface-and-ops.md](./agent-surface-and-ops.md) · **Roadmap:** [§ Agent & indexing ops](../roadmap.md#agent--indexing-ops) + +--- + +## Quick resume + +| Next action | Detail | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Review / merge P0** | PR [#126](https://github.com/stainless-code/codemap/pull/126) (MCP instructions + allowlist), PR [#127](https://github.com/stainless-code/codemap/pull/127) (WSL watch + git hooks) | +| **Start next** | **PR 3** — [`index-lock-and-error-log`](./index-lock-and-error-log.md) on branch from fresh `main` | +| **Do not start yet** | PR 6 (MCP trace tools) until PR 1 + PR 4 land; PR 9 (eval harness) until PR 1 + PR 8 | + +Update the table below when a PR merges or a new branch opens. + +--- + +## Recommended shape: 2 P0 PRs + 5–6 P1 PRs + +Merge each PR to `main` directly. No long-lived integration branch (`feat/agent-ops`). + +### Wave 1 — P0 (~1 week wall clock, 2 PRs) + +| PR | Plans bundled | Status | Branch / link | Notes | +| ----- | ----------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| **1** | [`mcp-server-instructions`](./mcp-server-instructions.md) + [`mcp-tool-allowlist`](./mcp-tool-allowlist.md) | open | [`feat/mcp-instructions-allowlist`](https://github.com/stainless-code/codemap/pull/126) | Same hot files (`mcp-server.ts`, `agent-content`); ~3–4 days | +| **2** | [`wsl-watch-policy`](./wsl-watch-policy.md) → [`git-hook-auto-sync`](./git-hook-auto-sync.md) | open | [`feat/wsl-watch-git-hooks`](https://github.com/stainless-code/codemap/pull/127) | `watch-policy.ts` first; hooks reference it in diagnostics. Lock deferred to PR 3 — note concurrent hook + MCP in PR 2 body | + +### Wave 2 — P1 (~2–3 weeks, parallel tracks) + +Max **3 parallel tracks** at once. + +| PR | Plans | Status | Blocked by | Parallel with | +| ----- | ----------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------- | --------------------------------- | +| **3** | [`index-lock-and-error-log`](./index-lock-and-error-log.md) → [`parse-worker-hardening`](./parse-worker-hardening.md) (stack) | planned | PR 2 merged (doc note on hook+lock) | 4, 5 | +| **4** | Recipe half of [`mcp-trace-explore-tools`](./mcp-trace-explore-tools.md) (`call-path`, `symbol-neighborhood` SQL + tests) | planned | — | 3, 5 | +| **5** | [`affected-tests-recipe`](./affected-tests-recipe.md) | planned | — | 3, 4 | +| **6** | MCP half of trace (`trace` / `explore` / `node` tools) + update instructions | planned | PR 1, PR 4 | — | +| **7** | [`field-qualified-search`](./field-qualified-search.md) | planned | PR 1 | 4, 5 if `mcp-server.ts` untouched | +| **8** | [`agents-init-mcp-wiring`](./agents-init-mcp-wiring.md) | planned | PR 1 | 3–5 | +| **9** | [`agent-eval-harness`](./agent-eval-harness.md) | planned | PR 1, PR 8, allowlist | **last P1** | + +**Parallelization constraints** + +- **Do not parallelize PR 6 + PR 7** — both edit MCP `show` schema; stack or single PR. +- **PR 2 + PR 3** — land lock (PR 3) before documenting hook+lock behavior, or follow up with a doc-only commit. +- **One owner for `agents-init-*`** — git-hooks (P0) and MCP wiring (P1) touch the same files; stack if both active. + +### Wave 3 — P2 (separate epic, trigger-gated) + +Do not rush with P0/P1. **2–4 separate PRs** after P1 completes. + +| Item | Plan | Gate | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | +| Framework routes | [`framework-route-extraction`](./framework-route-extraction.md) | Blocked on [`c9-plugin-layer`](./c9-plugin-layer.md) (XL) | +| Call substrate | [`callback-dispatch-synthesis`](./callback-dispatch-synthesis.md), [`unresolved-calls-staging`](./unresolved-calls-staging.md) | One at a time (schema + parser) | +| FTS default | [`fts-default-on-evaluation`](./fts-default-on-evaluation.md) | Measurement-only; solo PR anytime | +| Cross-project root | [`cross-project-mcp-root`](./cross-project-mcp-root.md) | On demand | + +--- + +## Execution playbook + +1. **Branch from fresh `main` per PR** — rebase often; avoid long-lived feature branches. +2. **Combine same-file P0 items** — e.g. MCP instructions + allowlist = one PR. +3. **Recipe-before-MCP for trace tools** — split `templates/recipes/` from `mcp-server.ts` (PR 4 before PR 6). +4. **One owner for `agents-init-*`** — stack git-hooks and MCP wiring if both in flight. +5. **Land index-lock before parse-worker hardening** — worker timeouts write to `errors.log`. +6. **Agent eval last** — `scripts/agent-eval/` is dev-only and depends on MCP surface + init wiring. +7. **Tracer bullets per PR** — each PR shippable + tested per repo conventions. + +### If you want maximum speed (solo or 2 people) + +| Week | PRs | Outcome | +| ---- | -------------------------------- | ------------------------------ | +| 1 | 1 + 2 | P0 complete | +| 2 | 3 + 4 + 5 (parallel) | Reliability + recipe substrate | +| 3 | 6 + 8 (parallel), then 7, then 9 | MCP tools + init + eval | + +--- + +## Maintaining this doc + +When opening or merging a PR: + +1. Update **Quick resume** and the relevant row **Status** (`planned` → `open` → `merged`). +2. On merge, check off the matching items in [`roadmap.md`](../roadmap.md#agent--indexing-ops). +3. Close individual plan files per [docs-governance](../../.agents/skills/docs-governance/SKILL.md) when the feature ships. + +Status values: `planned` · `open` · `merged` · `cancelled` diff --git a/docs/roadmap.md b/docs/roadmap.md index 3f33156..b1d6031 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -54,7 +54,7 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live ### Agent & indexing ops -Prioritized agent & indexing ops queue (2026-05). Index: [`plans/agent-surface-and-ops.md`](./plans/agent-surface-and-ops.md). +Prioritized agent & indexing ops queue (2026-05). Index: [`plans/agent-surface-and-ops.md`](./plans/agent-surface-and-ops.md). PR tracker: [`plans/agent-surface-delivery.md`](./plans/agent-surface-delivery.md). **P0 — quick wins**