Gabriel Radureau
7647a68cdc
Add a root AGENTS.md (ecosystem map of factory/tools/cms + agent operating rules + the persona cohort & workflow) and a new vibe/ knowledge base for LLM agents, modeled on tree-docs conventions and the factory house style. vibe/ folders (each with a README hub + contribution rules): - ADR/ optimized MADR-lite; canonical home going forward (doc/adr stays historical) - PRD/ one subfolder per PRD, mandatory STATUS.md, QA strategy for big ones - investigations/ single INV-NNN-slug.md, or stub + folder w/ notebooks - guidebooks/ tree-docs maps; lab-ecosystem guidebook of factory+tools+cms - runbooks/ [AGENT]/[HUMAN] step procedures (EN; doc/runbooks stays FR) - shareouts/ dated FR handouts (decks/mp4) Seed content (first ADR + PRD): a safe, production-like environment to rehearse risky changes and recovery without touching real prod — local-only sandbox (k3d + arm64 VMs) with a hard prod/sandbox isolation boundary. Includes INV-001 (prod blast-radius couplings), the ecosystem guidebook, and a FR shareout. Conventions enforced: no-tombstone rule, breadcrumb spine, bidirectional cross-links, theme:base mermaid (MCP-validated) + ordered-list-after-diagram. Built with a Workflow + persona cohort; 24 files, zero dead links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.4 KiB
2.4 KiB
vibe > PRD
Product Requirement Documents
Status: 🟢 Active Last Updated: 2026-06-23 Related: vibe/ADR · vibe/Investigations
vibe/PRD/ holds the Product Requirement Documents that drive larger pieces of work in the lab. A PRD captures what we want and why it matters; the matching ADRs capture how we decided to build it, and investigations capture what we learned along the way.
Convention
- One subfolder per PRD, kebab-case (e.g.
safe-prod-like-environment/). - Each subfolder MUST contain:
README.md— the PRD hub: problem, goals/non-goals, requirements, success criteria, and a QA strategy.STATUS.md— the implementation tracker. Update it whenever something ships (a PR merges, a brick lands, a milestone closes). It is the living view of "where are we" against the PRD.
- A big PRD uses tree-docs: the
README.mdstays a hub and detail lives in leaf pages (each with its own breadcrumb and bidirectional cross-links). A tree-sized PRD MUST detail an explicit QA strategy — how the delivered work will be verified, and what "done and safe" means. - PRs cross-link to the PRD, and the PRD's
STATUS.mdcross-links back to the PRs/ADRs/investigations that realised each part. Links are bidirectional. - No-tombstone rule applies: the PRD reads as currently true. Progress lives in
STATUS.md(which is a tracker and may legitimately list shipped items), not as "previously / now" edits scattered through the hub.
Index
| PRD | Hub | Status |
|---|---|---|
| Safe, production-like environment | safe-prod-like-environment/README.md | 🟡 In design |
Rules to contribute
- Create a kebab-case subfolder named for the PRD.
- Add
README.md(the hub) andSTATUS.md(the tracker). Both carry a breadcrumb first line and the leaf header blockquote (Status / Last Updated / Related). - In the hub, state the problem, goals and non-goals, requirements, success criteria, and the QA strategy. If the PRD is large, split detail into leaf pages and keep the README as a navigable hub.
- Keep
STATUS.mdcurrent: every time a piece ships, record it there and link the PR/ADR that delivered it. - Add a row to the Index table above.
- Ensure every PR that implements part of the PRD links to the PRD, and that
STATUS.mdlinks back. Bidirectional links are mandatory.