francy51
97a9f611bb
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.
69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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`)
|
|
|
|
```bash
|
|
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
|