Skip to content

Commit 8807614

Browse files
SutuSebastianSutuSebastian
authored
docs(plans): add agent-surface delivery PR tracker (#128)
Capture wave/PR map, parallelization rules, and live status so agent-surface work can pause and resume outside a single session.
1 parent 04c4aa7 commit 8807614

3 files changed

Lines changed: 101 additions & 3 deletions

File tree

‎docs/plans/agent-surface-and-ops.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,17 @@
55
> **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.
66
>
77
> **Roadmap home:** [§ Backlog — Agent & indexing ops](../roadmap.md#agent--indexing-ops)
8+
>
9+
> **PR tracker (pause/resume):** [agent-surface-delivery.md](./agent-surface-delivery.md)
810
911
---
1012

1113
## Recommended ship order
1214

1315
```
14-
P0 (ops polish, ~2 weeks total)
15-
mcp-server-instructions → wsl-watch-policy → git-hook-auto-sync → mcp-tool-allowlist
16+
P0 (ops polish, ~2 weeks total — see delivery tracker for PR bundling)
17+
PR1: mcp-server-instructions + mcp-tool-allowlist
18+
PR2: wsl-watch-policy → git-hook-auto-sync
1619
1720
P1 (agent + reliability, parallel tracks)
1821
Track A: mcp-trace-explore-tools (+ call-path recipes)

‎docs/plans/agent-surface-delivery.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Agent surface delivery — PR tracker
2+
3+
> **Status:** in flight · **Created:** 2026-05-25
4+
>
5+
> **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.
6+
>
7+
> **Plan index:** [agent-surface-and-ops.md](./agent-surface-and-ops.md) · **Roadmap:** [§ Agent & indexing ops](../roadmap.md#agent--indexing-ops)
8+
9+
---
10+
11+
## Quick resume
12+
13+
| Next action | Detail |
14+
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15+
| **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) |
16+
| **Start next** | **PR 3** — [`index-lock-and-error-log`](./index-lock-and-error-log.md) on branch from fresh `main` |
17+
| **Do not start yet** | PR 6 (MCP trace tools) until PR 1 + PR 4 land; PR 9 (eval harness) until PR 1 + PR 8 |
18+
19+
Update the table below when a PR merges or a new branch opens.
20+
21+
---
22+
23+
## Recommended shape: 2 P0 PRs + 5–6 P1 PRs
24+
25+
Merge each PR to `main` directly. No long-lived integration branch (`feat/agent-ops`).
26+
27+
### Wave 1 — P0 (~1 week wall clock, 2 PRs)
28+
29+
| PR | Plans bundled | Status | Branch / link | Notes |
30+
| ----- | ----------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
31+
| **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 |
32+
| **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 |
33+
34+
### Wave 2 — P1 (~2–3 weeks, parallel tracks)
35+
36+
Max **3 parallel tracks** at once.
37+
38+
| PR | Plans | Status | Blocked by | Parallel with |
39+
| ----- | ----------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------- | --------------------------------- |
40+
| **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 |
41+
| **4** | Recipe half of [`mcp-trace-explore-tools`](./mcp-trace-explore-tools.md) (`call-path`, `symbol-neighborhood` SQL + tests) | planned | — | 3, 5 |
42+
| **5** | [`affected-tests-recipe`](./affected-tests-recipe.md) | planned | — | 3, 4 |
43+
| **6** | MCP half of trace (`trace` / `explore` / `node` tools) + update instructions | planned | PR 1, PR 4 | — |
44+
| **7** | [`field-qualified-search`](./field-qualified-search.md) | planned | PR 1 | 4, 5 if `mcp-server.ts` untouched |
45+
| **8** | [`agents-init-mcp-wiring`](./agents-init-mcp-wiring.md) | planned | PR 1 | 3–5 |
46+
| **9** | [`agent-eval-harness`](./agent-eval-harness.md) | planned | PR 1, PR 8, allowlist | **last P1** |
47+
48+
**Parallelization constraints**
49+
50+
- **Do not parallelize PR 6 + PR 7** — both edit MCP `show` schema; stack or single PR.
51+
- **PR 2 + PR 3** — land lock (PR 3) before documenting hook+lock behavior, or follow up with a doc-only commit.
52+
- **One owner for `agents-init-*`** — git-hooks (P0) and MCP wiring (P1) touch the same files; stack if both active.
53+
54+
### Wave 3 — P2 (separate epic, trigger-gated)
55+
56+
Do not rush with P0/P1. **2–4 separate PRs** after P1 completes.
57+
58+
| Item | Plan | Gate |
59+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
60+
| Framework routes | [`framework-route-extraction`](./framework-route-extraction.md) | Blocked on [`c9-plugin-layer`](./c9-plugin-layer.md) (XL) |
61+
| Call substrate | [`callback-dispatch-synthesis`](./callback-dispatch-synthesis.md), [`unresolved-calls-staging`](./unresolved-calls-staging.md) | One at a time (schema + parser) |
62+
| FTS default | [`fts-default-on-evaluation`](./fts-default-on-evaluation.md) | Measurement-only; solo PR anytime |
63+
| Cross-project root | [`cross-project-mcp-root`](./cross-project-mcp-root.md) | On demand |
64+
65+
---
66+
67+
## Execution playbook
68+
69+
1. **Branch from fresh `main` per PR** — rebase often; avoid long-lived feature branches.
70+
2. **Combine same-file P0 items** — e.g. MCP instructions + allowlist = one PR.
71+
3. **Recipe-before-MCP for trace tools** — split `templates/recipes/` from `mcp-server.ts` (PR 4 before PR 6).
72+
4. **One owner for `agents-init-*`** — stack git-hooks and MCP wiring if both in flight.
73+
5. **Land index-lock before parse-worker hardening** — worker timeouts write to `errors.log`.
74+
6. **Agent eval last** — `scripts/agent-eval/` is dev-only and depends on MCP surface + init wiring.
75+
7. **Tracer bullets per PR** — each PR shippable + tested per repo conventions.
76+
77+
### If you want maximum speed (solo or 2 people)
78+
79+
| Week | PRs | Outcome |
80+
| ---- | -------------------------------- | ------------------------------ |
81+
| 1 | 1 + 2 | P0 complete |
82+
| 2 | 3 + 4 + 5 (parallel) | Reliability + recipe substrate |
83+
| 3 | 6 + 8 (parallel), then 7, then 9 | MCP tools + init + eval |
84+
85+
---
86+
87+
## Maintaining this doc
88+
89+
When opening or merging a PR:
90+
91+
1. Update **Quick resume** and the relevant row **Status** (`planned` → `open` → `merged`).
92+
2. On merge, check off the matching items in [`roadmap.md`](../roadmap.md#agent--indexing-ops).
93+
3. Close individual plan files per [docs-governance](../../.agents/skills/docs-governance/SKILL.md) when the feature ships.
94+
95+
Status values: `planned` · `open` · `merged` · `cancelled`

‎docs/roadmap.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Soft constraints — describe shipped reality. Decided-but-unshipped flips live
5454

5555
### Agent & indexing ops
5656

57-
Prioritized agent & indexing ops queue (2026-05). Index: [`plans/agent-surface-and-ops.md`](./plans/agent-surface-and-ops.md).
57+
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).
5858

5959
**P0 — quick wins**
6060

0 commit comments

Comments
 (0)