Skip to content

docs(plans): agent-surface delivery PR tracker #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SutuSebastian merged 1 commit into from
May 25, 2026
+101 −3
Merged

docs(plans): agent-surface delivery PR tracker #128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/plans/agent-surface-and-ops.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
95 changes: 95 additions & 0 deletions docs/plans/agent-surface-delivery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
2 changes: 1 addition & 1 deletion docs/roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down
Loading