docs(idef0): shape Pillar C — ADR-010 (Agent SDK packaging) + RFC-034 (daemon bridge) - #168
Closed
explosivebit wants to merge 1 commit into
Closed
explosivebit wants to merge 1 commit into
explosivebit wants to merge 1 commit into
Conversation
… (daemon) SHAPE only (design; build is later) for PRD-038 Pillar C, the live local onboarding agent. - ADR-010 resolves Q1 (Agent SDK vs ADR-003 bin/ allow-list): ship the SDK + daemon as a SEPARATE optional npm package (@forgeplan/web-agent), launched by a spawn-only bin/ onboard-agent subcommand — bin/ only child_process.spawns it, never imports it, so ADR-003's node:+citty allow-list and the npx-fast guarantee are untouched. Rejected: dist-agent/ image (bloats every install) and extending the bin allow-list (reintroduces npx-time SDK resolution). - RFC-034 architects the daemon-bridge: a localhost (127.0.0.1) WebSocket, a persistent Agent SDK session in a read-only profile (Read/Glob/Grep + read-only forgeplan MCP; Write/Edit/Bash denied), one relayed SDK tool show_on_map that drives the EXISTING RFC-033 tour camera via a new camera-bus seam, and a two-tier chat (Tier 0 client-grounded from map.json, model-free, offline; Tier 1 live agent via probe). Rule 22 (no /api/* in the live path), rule 23 (bin spawn-only), rule 24 all preserved. validate: RFC-034 0 errors/0 warnings. Both draft — activation gated on the build's EvidencePack (rule 11). Wires to the just-merged tour camera (PR #167) and depends on marketplace CM-02 (stable node ids) for precise show_on_map(node) targeting. Refs: PRD-038, ADR-010, RFC-034
Contributor
Author
|
Superseded by the consolidated Pillar C PR (feat/idef0-onboard-agent-phase1), which carries the shape (RFC-034 + ADR-010, now active) plus the build + live-proof evidence (EVID-096). Closing to avoid a duplicate RFC-034/ADR-010 merge. |
explosivebit
added a commit
that referenced
this pull request
Jul 8, 2026
…amera chat) (#169) ## Summary **The live onboarding agent (PRD-038 Pillar C).** Talk to your project in the web chat and a **real local Claude Code session** answers — grounded in the actual repo — while the **map moves as it explains**. Two-tier + graceful: Tier 0 answers offline from `map.json`; Tier 1 upgrades to the live agent when the daemon is running. This PR consolidates the Pillar C **shape + build + evidence** (supersedes the shape-only #168). ## Proven end-to-end (EVID-096) Spawned the daemon, connected a WS client, asked *"what is this project and what is it for?"* — the local CC answered verbatim: *"@forgeplan/web is a tiny zero-install npm CLI that scaffolds a pre-built SvelteKit app into `.forgeplan-web/`, serves a read-only force-directed map of Forgeplan artifacts… `npx @forgeplan/web start`…"* — then **called `show_on_map` → `{zone: z.surfaces}`** and narrated the zone flow. Real model turn, grounded, camera-driven. ## What's in it - **RFC-034 + ADR-010** (active) — the daemon/protocol/camera/chat architecture + the packaging decision (separate optional package + spawn-only subcommand). - **Phase 1** — `camera-bus` seam (the one primitive a chat uses to move the RFC-033 tour camera) + Tier-0 chat (`map-chat`: client-grounded, model-free, offline). - **`agent/`** — NEW separate package `@forgeplan/web-agent` (ADR-010: own deps `@anthropic-ai/claude-agent-sdk` + `ws` + `zod`, never in core): a 127.0.0.1 WebSocket daemon booting a persistent Agent SDK `query()` session in a **read-only** profile (Read/Glob/Grep + `show_on_map`; deny Write/Edit/Bash), with an in-process `createSdkMcpServer` `show_on_map` tool that relays camera frames. - **`bin/commands/onboard-agent.mjs`** — spawn-only subcommand (rule 23: `spawn`s the package, never imports it). - **Tier-1 web wiring** — `agent-client.ts` (read-only WS client) + `chat-store` Tier-1 (stream → assistant bubble; `show_on_map` → camera-bus; degrades to Tier 0 when the daemon is down). ## Invariants - **Rule 22**: the live path is browser↔daemon over `ws://127.0.0.1`; `/api/*` is never involved. - **Rule 23 / ADR-010**: core `bin/` stays `node:*`+citty+siblings (spawn-only); the SDK lives only in the `agent/` package; root `package.json` untouched. - **Read-only**: the agent cannot mutate the workspace. ## Test plan - `npx vitest run src/widgets/map-chat src/widgets/composed-map` → **153/153**. - `npx svelte-check` → **0 errors**. - `node agent/scripts/smoke.mjs` → exit 0 (protocol + read-only profile + bind + `/health` + `{ready}`). - Rule-23 allow-list grep over `bin/` → OK. - **Live end-to-end turn** (above) — daemon + local CC + `show_on_map` (EVID-096, CL3). ## To try it `npx @forgeplan/web onboard-agent` in your project → the web chat detects it (`● live`) → ask away. Refs: PRD-038, RFC-034, ADR-010, EVID-096, RFC-033 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SHAPE only (design artifacts; build is a later step) for PRD-038 Pillar C — the live local onboarding agent.
bin/allow-list): ship the SDK + daemon as a separate optional npm package (@forgeplan/web-agent), launched by a spawn-onlybin/ onboard-agentsubcommand.bin/onlychild_process.spawns it, never imports it → ADR-003'snode:+cittyallow-list + thenpx-fast guarantee stay intact. Rejected:dist-agent/image (bloats every install with the SDK) and extending the allow-list (reintroducesnpx-time SDK resolution).show_on_mapdriving the existing RFC-033 tour camera via a newcamera-busseam, and a two-tier chat (Tier 0 client-grounded frommap.json, model-free/offline; Tier 1 live agent via probe). Rules 22/23/24 all preserved.validate: RFC-034 0 errors / 0 warnings.Why
Pillar C adds the voice to the map: ask a question, get a grounded answer that also moves the camera — using the user's own local Claude Code (no API key in the web). This PR is the design; the build follows (camera-bus + Tier 0 chat first, then the agent package).
Test plan
Design-only PR (no code).
forgeplan validate RFC-034→ 0 errors/0 warnings;forgeplan validate ADR-010→ 0 MUST errors. Both draft; activation gated on the build's EvidencePack (rule 11).Refs: PRD-038, ADR-010, RFC-034
🤖 Generated with Claude Code