Skip to content

Commit 4232495

Browse files
hansjm10hansjm10
authored
docs(agent): add canonical agent map (#921)
* docs(agent): add canonical agent map Refs #909 * docs(agent): fix perf report context path Refs #909 * docs(agent): clarify shell mcp launcher prerequisite
1 parent 2e04822 commit 4232495

3 files changed

Lines changed: 331 additions & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Repository Guidelines
22

3+
Use [docs/agent-map.md](docs/agent-map.md) as the canonical task-to-context router for agent work.
4+
35
## Project Structure & Module Organization
46
Modules are declared in `pnpm-workspace.yaml`: `packages/core` contains the deterministic runtime with colocated `*.test.ts`, `packages/content-sample` ships reference data packs, and `packages/config-*` publish shared lint/test presets. Command-line tooling lives in `tools/`. Generated `dist/` outputs are checked in for inspectors but should not be edited by hand.
57

‎docs/agent-map.md‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
title: Agent Map
3+
sidebar_position: 28
4+
---
5+
6+
# Agent Map
7+
8+
This is the canonical task router for agents working in Idle Engine. Start here
9+
after reading `AGENTS.md`, then load only the context packet for the task family
10+
you are handling.
11+
12+
Source initiative: [`docs/agent-first-workflow-design.md`](./agent-first-workflow-design.md).
13+
14+
## How to use this map
15+
16+
1. Identify the task family that matches the issue, PR review, or maintenance
17+
request.
18+
2. Load the listed context packet before editing files.
19+
3. Keep the diff centered in the listed packages or files.
20+
4. Run the focused validation commands first, then broaden validation when the
21+
change crosses package or workflow boundaries.
22+
5. Capture only the artifacts that help reviewers reproduce or inspect the
23+
change.
24+
25+
Escalate instead of guessing when the task crosses public API boundaries,
26+
contradicts a design document, requires a new generated artifact policy, or
27+
needs long-running local processes that are not clearly owned by the command you
28+
are running.
29+
30+
## Runtime
31+
32+
Use this family for deterministic simulation behavior, runtime commands,
33+
events, persistence, scheduling, telemetry, and core package exports.
34+
35+
- **Context packet**:
36+
- `AGENTS.md`
37+
- `docs/idle-engine-design.md`
38+
- `docs/runtime-step-lifecycle.md`
39+
- `docs/runtime-command-queue-design.md`
40+
- `docs/runtime-event-manifest-authoring.md`
41+
- `docs/diagnostic-timeline-design.md`
42+
- `packages/core/README.md`
43+
- **Primary packages and files**:
44+
- `packages/core/src/`
45+
- `packages/core/src/__tests__/`
46+
- `packages/core/benchmarks/`
47+
- `packages/core/package.json`
48+
- **Validation commands**:
49+
- `pnpm --filter @idle-engine/core test`
50+
- `pnpm --filter @idle-engine/core run test:ci`
51+
- `pnpm --filter @idle-engine/core run typecheck`
52+
- `pnpm lint`
53+
- **Artifact expectations**:
54+
- Keep Vitest output machine-readable; do not add console noise before the
55+
final reporter JSON.
56+
- Include benchmark JSON only when runtime performance or payload shape is
57+
part of the change.
58+
- Note changed public exports and migration guidance in the PR body.
59+
- **Escalation triggers**:
60+
- A stable `@idle-engine/core` export needs to be renamed, removed, or moved.
61+
- Deterministic step ordering, hydration semantics, or runtime event frame
62+
shape would change.
63+
- The fix requires shell, renderer, or content packages to depend on
64+
`@idle-engine/core/internals` instead of a public or harness entry point.
65+
66+
## Content Pipeline
67+
68+
Use this family for content schemas, DSL validation, compiler output, sample
69+
packs, generated content modules, and content validation CLIs.
70+
71+
- **Context packet**:
72+
- `AGENTS.md`
73+
- `docs/content-dsl-schema-design.md`
74+
- `docs/content-dsl-usage-guidelines.md`
75+
- `docs/content-schema-reference.md`
76+
- `docs/content-compiler-design.md`
77+
- `docs/content-validation-cli-design.md`
78+
- `packages/content-sample/README.md`
79+
- **Primary packages and files**:
80+
- `packages/content-schema/src/`
81+
- `packages/content-compiler/src/`
82+
- `packages/content-sample/content/`
83+
- `packages/content-sample/dist/`
84+
- `tools/content-schema-cli/src/`
85+
- `docs/examples/`
86+
- **Validation commands**:
87+
- `pnpm generate --check`
88+
- `pnpm --filter @idle-engine/content-schema test`
89+
- `pnpm --filter @idle-engine/content-compiler test`
90+
- `pnpm --filter @idle-engine/content-validation-cli test`
91+
- `pnpm test:ci`
92+
- **Artifact expectations**:
93+
- Commit generated sample or compiled outputs when the source content change
94+
requires them.
95+
- Preserve final JSON payloads emitted by content tooling.
96+
- Include schema compatibility notes when older generated packs may be
97+
affected.
98+
- **Escalation triggers**:
99+
- A schema change is not backward-compatible or needs a migration path.
100+
- Generated output changes without a source content or compiler change.
101+
- Validation failures point to ambiguous DSL behavior rather than a simple
102+
fixture update.
103+
104+
## Renderer
105+
106+
Use this family for renderer contracts, debug renderers, WebGPU rendering,
107+
sprite batching, atlases, render-frame metadata, and action regions.
108+
109+
- **Context packet**:
110+
- `AGENTS.md`
111+
- `docs/controls-contract-design-issue-705.md`
112+
- `docs/desktop-shell-webgpu-renderer-replay-design-issue-778.md`
113+
- `docs/runtime-event-manifest-authoring.md`
114+
- `packages/renderer-webgpu/README.md`
115+
- `packages/shell-desktop/README.md`
116+
- **Primary packages and files**:
117+
- `packages/renderer-contract/src/`
118+
- `packages/renderer-debug/src/`
119+
- `packages/renderer-webgpu/src/`
120+
- `packages/controls/src/`
121+
- `packages/shell-desktop/src/renderer/`
122+
- **Validation commands**:
123+
- `pnpm --filter @idle-engine/renderer-contract test`
124+
- `pnpm --filter @idle-engine/renderer-debug test`
125+
- `pnpm --filter @idle-engine/renderer-webgpu test`
126+
- `pnpm --filter @idle-engine/shell-desktop test`
127+
- `pnpm build`
128+
- **Artifact expectations**:
129+
- Attach or describe screenshots when visual output changes.
130+
- Capture renderer status, WebGPU health, and relevant logs for shell-facing
131+
regressions.
132+
- Include generated renderer bundles or copied assets only when build output
133+
sync requires them.
134+
- **Escalation triggers**:
135+
- Renderer contract types need a breaking change.
136+
- WebGPU fallback behavior or hardware assumptions change.
137+
- A renderer fix depends on runtime state that is not exposed through a stable
138+
contract.
139+
140+
## Shell MCP
141+
142+
Use this family for the Electron shell, headless launchers, MCP server and
143+
gateway tools, shell automation, screenshots, logs, and local diagnostics.
144+
145+
- **Context packet**:
146+
- `AGENTS.md`
147+
- `docs/shell-desktop-mcp.md`
148+
- `docs/agent-first-workflow-design.md`
149+
- `packages/shell-desktop/README.md`
150+
- `tools/scripts/shell-desktop-mcp-smoke.mjs`
151+
- **Primary packages and files**:
152+
- `packages/shell-desktop/src/`
153+
- `packages/shell-desktop/src/mcp/`
154+
- `tools/scripts/start-shell-desktop-headless.sh`
155+
- `tools/scripts/shell-desktop-mcp-smoke.mjs`
156+
- `tools/scripts/*shell-desktop*mcp*`
157+
- **Validation commands**:
158+
- `pnpm --filter @idle-engine/shell-desktop test`
159+
- `pnpm --filter @idle-engine/shell-desktop run test:ci`
160+
- `pnpm shell:desktop:mcp:smoke`
161+
- **MCP launcher prerequisite**:
162+
- On a fresh or headless host, start `pnpm shell:desktop:headless` in a
163+
separate terminal/session before running `pnpm shell:desktop:mcp:smoke`.
164+
The smoke test connects to the running MCP endpoint on loopback and does
165+
not start the shell itself.
166+
- Stop the headless shell with `pnpm shell:desktop:headless:stop` after
167+
collecting validation evidence.
168+
- **Artifact expectations**:
169+
- Store local run artifacts under `artifacts/agent-runs/<run-id>/` when the
170+
task requires screenshots, logs, or health snapshots.
171+
- Include `summary.json`, bounded command logs, renderer status, WebGPU
172+
health, and a screenshot when validating UI or renderer behavior.
173+
- Do not capture secrets, arbitrary environment dumps, or home-directory files.
174+
- **Escalation triggers**:
175+
- The script would need to kill a process it did not start.
176+
- MCP must bind outside loopback or accept non-local clients.
177+
- The smoke loop needs long retries, broad log capture, or manual GUI
178+
interaction to pass.
179+
180+
## Docs
181+
182+
Use this family for Markdown docs, Docusaurus navigation, design documents,
183+
role guidance, contributor instructions, and package README orientation.
184+
185+
- **Context packet**:
186+
- `AGENTS.md`
187+
- `docs/index.md`
188+
- `docs/role-index.md`
189+
- `docs/design-document-template.md`
190+
- `docs/contributor-handbook.md`
191+
- `docs/testing-guidelines.md`
192+
- `packages/docs/sidebars.ts`
193+
- **Primary packages and files**:
194+
- `docs/`
195+
- `packages/docs/`
196+
- `packages/docs/scripts/`
197+
- package-level `README.md` files
198+
- `AGENTS.md`
199+
- **Validation commands**:
200+
- `pnpm --filter @idle-engine/docs test`
201+
- `pnpm --filter @idle-engine/docs lint`
202+
- `pnpm docs:build`
203+
- `pnpm fast:check`
204+
- **Artifact expectations**:
205+
- Reference the source design, issue, or decision record that the doc updates.
206+
- Keep navigation diffs focused in `packages/docs/sidebars.ts`.
207+
- Do not refresh generated coverage or performance pages unless the issue
208+
explicitly targets those pages.
209+
- **Escalation triggers**:
210+
- Two docs disagree about current shipped behavior and no source of truth is
211+
obvious.
212+
- A docs-only issue would require a new CI check, package README policy, or
213+
generated manifest.
214+
- `AGENTS.md` starts growing into a long manual instead of routing to durable
215+
docs.
216+
217+
## Tooling and CI
218+
219+
Use this family for workspace scripts, GitHub Actions, Lefthook hooks, lint
220+
presets, fast checks, repository hygiene, and agent doctor-style commands.
221+
222+
- **Context packet**:
223+
- `AGENTS.md`
224+
- `docs/contributor-handbook.md`
225+
- `docs/agent-first-workflow-design.md`
226+
- `packages/config-eslint/README.md`
227+
- `package.json`
228+
- `lefthook.yml`
229+
- `.github/workflows/ci.yml`
230+
- **Primary packages and files**:
231+
- `tools/scripts/`
232+
- `packages/config-eslint/`
233+
- `packages/config-vitest/`
234+
- `.github/workflows/`
235+
- `lefthook.yml`
236+
- root `package.json`
237+
- **Validation commands**:
238+
- `pnpm lint`
239+
- `pnpm typecheck`
240+
- `pnpm test:ci`
241+
- `pnpm fast:check`
242+
- `pnpm exec lefthook run pre-commit --all-files --force`
243+
- **Artifact expectations**:
244+
- Record before and after command duration when changing CI or hook scope.
245+
- Include actionable failure text for new lint or structural rules.
246+
- Keep local scratch paths ignored rather than committed.
247+
- **Escalation triggers**:
248+
- A guardrail would block existing legitimate package dependencies.
249+
- CI duration changes materially or requires new external services.
250+
- A hook needs to mutate unstaged files or hide validation output from agents.
251+
252+
## Benchmarks and Performance
253+
254+
Use this family for benchmark harnesses, performance reports, generated
255+
performance docs, runtime overhead checks, and threshold changes.
256+
257+
- **Context packet**:
258+
- `AGENTS.md`
259+
- `docs/benchmark-output-schema.md`
260+
- `docs/validation-performance-benchmarks-caching-design.md`
261+
- `docs/content-validation-performance.md`
262+
- `docs/agent-first-workflow-design.md`
263+
- `package.json`
264+
- `tools/perf-report/index.ts`
265+
- **Primary packages and files**:
266+
- `packages/core/benchmarks/`
267+
- `packages/content-schema/benchmarks/`
268+
- `tools/perf-report/`
269+
- `docs/performance/index.md`
270+
- benchmark fixtures and baselines near the package under test
271+
- **Validation commands**:
272+
- `pnpm benchmark`
273+
- `pnpm perf:run`
274+
- `pnpm perf:md`
275+
- `pnpm --filter @idle-engine/content-schema run bench:check`
276+
- `pnpm --filter @idle-engine/core run benchmark`
277+
- **Artifact expectations**:
278+
- Preserve machine-readable benchmark output shape.
279+
- Commit `docs/performance/index.md` only when explicitly refreshing the
280+
generated performance page.
281+
- Include baseline update rationale and the compared commit or run ID.
282+
- **Escalation triggers**:
283+
- A threshold change weakens a regression gate.
284+
- Benchmark noise makes pass or fail status ambiguous.
285+
- Performance output schema changes would break report generation.
286+
287+
## Release and Generated Artifacts
288+
289+
Use this family for checked-in `dist/` outputs, generated runtime version files,
290+
coverage reports, content outputs, package publishing readiness, and release
291+
validation.
292+
293+
- **Context packet**:
294+
- `AGENTS.md`
295+
- `docs/contributor-handbook.md`
296+
- `docs/coverage-report-automation-design.md`
297+
- `docs/benchmark-output-schema.md`
298+
- `docs/agent-first-workflow-design.md`
299+
- package README for every package whose generated output changes
300+
- **Primary packages and files**:
301+
- `packages/*/dist/`
302+
- `packages/content-sample/dist/`
303+
- `docs/coverage/index.md`
304+
- `docs/performance/index.md`
305+
- `tools/scripts/generate-version.mjs`
306+
- `tools/scripts/verify-dist-sync.mjs`
307+
- **Validation commands**:
308+
- `pnpm build`
309+
- `pnpm generate --check`
310+
- `pnpm coverage:md`
311+
- `pnpm perf:md`
312+
- `pnpm test:ci`
313+
- **Artifact expectations**:
314+
- Do not edit generated files by hand.
315+
- Commit refreshed generated files only when the issue explicitly calls for
316+
the refresh or the source change requires the output to stay in sync.
317+
- Prefer the manual Coverage Report workflow for coverage page refreshes, then
318+
commit the generated `docs/coverage/index.md` artifact when applying it.
319+
- **Escalation triggers**:
320+
- A generated diff appears without a reproducible command.
321+
- Coverage or performance pages change during an unrelated fix.
322+
- Release validation requires secrets, publishing credentials, or production
323+
package registry access.

‎packages/docs/sidebars.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,12 @@ const sidebars: SidebarsConfig = {
5858
{
5959
type: 'category',
6060
label: 'Operations & Process',
61-
items: ['implementation-plan', 'project-board-workflow', 'agent-first-workflow-design'],
61+
items: [
62+
'agent-map',
63+
'implementation-plan',
64+
'project-board-workflow',
65+
'agent-first-workflow-design',
66+
],
6267
},
6368
],
6469
};

0 commit comments

Comments
 (0)