Files

francy51 97a9f611bb docs(orchestrator): document that agents cannot complete cards

Add an "Implementation Board" section to the root AGENTS.md (auto-loaded as
context by every pi run) stating the hard rule: an agent may never mark a kanban
card done — only a human can. Agents leave finished work in-progress with a
summary comment for review. The code-level enforcement lives in the API.

2026-06-16 15:44:37 -04:00

2.8 KiB

Raw Permalink Blame History

VOID::NAV — Monorepo Root

Single-player narrative-driven space exploration saga. Windward meets Stellaris with AI-generated storytelling in the style of The Templin Institute.

Directory Map

Path	Purpose
`apps/docs`	Living design docs, interactive demos, and vertical-slice prototype (Vite + React)
`apps/game`	Playable game client — Rust + Bevy (independent of the JS/TS workspace)
`apps/site`	Public landing page (Vite + React)
`packages/ui`	Shared UI primitives and design tokens for the TS apps
`scripts/`	Dev tooling (dev.sh startup script)
`archive/`	Legacy pre-monorepo files kept for reference

Key Files

package.json — pnpm workspace scripts (dev, build, check)
pnpm-workspace.yaml — workspace glob patterns (covers TS apps only)
tsconfig.base.json — Shared TypeScript config (ES2020, React JSX) — does not apply to apps/game
apps/game/Cargo.toml — Rust manifest for the game binary

Commands

JS/TS workspace (docs, site, packages/ui)

pnpm dev                # Docs + site servers
pnpm dev:docs           # Docs only (port 5173)
pnpm dev:site           # Site only (port 5174)
pnpm build              # Build all TS packages
pnpm check              # Typecheck all TS packages

Rust game (`apps/game`)

cd apps/game
cargo run               # Build + run the game binary
cargo check             # Fast typecheck
cargo build             # Build without running
cargo clippy            # Lint

Architecture Notes

Two independent toolchains coexist: the pnpm/TS workspace (docs, site, UI lib) and the Cargo/Rust game client. They share no code.
V1 is single-player with local persistence. Future multiplayer servers will be added as an optional enhancement.
Naming follows RFC 344: see apps/game/AGENTS.md for Rust/Bevy conventions.

Implementation Board (Agent Orchestrator)

The docs site's Implementation Board (apps/api + the KanbanBoardPage) can launch autonomous pi agent runs against individual cards from isolated git worktrees, streaming progress back to the UI.

Hard rule: an agent may NEVER mark a kanban card done (completed) — only a human can. When an agent finishes its work it leaves the card in in-progress and posts a summary comment (plus links to any docs it updated); the operator reviews the diff and moves the card to done. Agents may move cards freely between backlog, todo, and in-progress. This is enforced in code: the agent-facing card-move endpoint (PATCH /api/internal/cards/:id) rejects done with 403.

Conventions (TS apps)

TS apps use Tailwind CSS v4 with custom design tokens from packages/ui
3D rendering in apps/docs uses React Three Fiber + Drei + Three.js

2.8 KiB Raw Permalink Blame History