Introduces a root AGENTS.md (ecosystem map of factory / tools / cms + agent operating rules + a reusable persona cohort & workflow) and a new vibe/ knowledge base for LLM agents — built with the tree-docs conventions and the factory house style.
24 files, zero dead links, every Mermaid diagram MCP-validated.
The vibe/ tree
Each folder has a README hub + "rules to contribute":
A safe, production-like environment to rehearse risky changes and recovery without touching real prod:
ADR-0001 — decision: local-only sandbox (k3d fast mode + 3 arm64 VMs on the Mac) with a hard prod↔sandbox isolation boundary; physical/cloud tiers explicitly out of scope.
## What
Introduces a root **`AGENTS.md`** (ecosystem map of `factory` / `tools` / `cms` + agent operating rules + a reusable persona cohort & workflow) and a new **`vibe/`** knowledge base for LLM agents — built with the `tree-docs` conventions and the factory house style.
24 files, **zero dead links**, every Mermaid diagram MCP-validated.
## The `vibe/` tree
Each folder has a README hub + "rules to contribute":
| Folder | Purpose |
|---|---|
| `vibe/ADR/` | Optimized MADR-lite ADRs — **canonical home going forward** (`doc/adr/` stays historical, cross-linked) |
| `vibe/PRD/` | One subfolder per PRD, **mandatory `STATUS.md`**, QA strategy for big ones (tree-docs) |
| `vibe/investigations/` | Single `INV-NNN-slug.md`, or stub + same-named folder with notebooks |
| `vibe/guidebooks/` | Tree-docs maps; the **lab-ecosystem** guidebook of factory+tools+cms |
| `vibe/runbooks/` | `[AGENT]`/`[HUMAN]` step procedures (EN; `doc/runbooks/` stays FR) |
| `vibe/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:
- **[ADR-0001](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/arcodange/focused-dirac-151213/vibe/ADR/0001-safe-prod-like-environment.md)** — decision: local-only sandbox (k3d fast mode + 3 arm64 VMs on the Mac) with a hard prod↔sandbox **isolation boundary**; physical/cloud tiers explicitly out of scope.
- **[PRD · Safe prod-like environment](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/arcodange/focused-dirac-151213/vibe/PRD/safe-prod-like-environment/README.md)** + **[STATUS.md](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/arcodange/focused-dirac-151213/vibe/PRD/safe-prod-like-environment/STATUS.md)** (phased tracker, all ⬜).
- **[INV-001 · Prod blast-radius couplings](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/arcodange/focused-dirac-151213/vibe/investigations/INV-001-prod-blast-radius-couplings.md)** — the couplings the sandbox must isolate.
- **[Lab ecosystem guidebook](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/arcodange/focused-dirac-151213/vibe/guidebooks/lab-ecosystem/README.md)** — end-to-end map of factory+tools+cms.
## Conventions enforced
No-tombstone rule (foremost) · breadcrumb spine · bidirectional cross-links · `theme:base` Mermaid + ordered-list-after-diagram · English in `vibe/`, French in `shareouts/`.
Built with a Workflow + persona cohort (Lab Cartographer, ADR Scribe, PRD Architect, Investigator, Diagram Smith, Continuity Warden).
> STATUS.md and ADR-0001 references backfill this PR number after open.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
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 <[email protected]>
Deep, code-grounded tree-docs guidebook under vibe/guidebooks/factory-provisioning/,
explored from the actual playbooks/roles and tofu code:
- Hub: the two provisioning engines (operator-run Ansible vs CI-applied OpenTofu),
a green-field bring-up flow, master index, maintenance rule.
- ansible/ sub-tree: ordered pages 01-system .. 06-recover, an inventory & variables
concept page, and a Tier-1/Tier-2 roles reference (hashicorp_vault, step_ca,
crowdsec, pihole, deploy_docker_compose + the gitea_* family and helpers).
- opentofu/ sub-tree: factory-iac (Cloudflare/OVH/GCP/Gitea/Vault edge +
cloudflare_token module), postgres-iac (per-app DB/role/pgbouncer lookup),
ci-apply-flow (Gitea OIDC-JWT -> Vault -> auto-approve apply).
Cross-linked bidirectionally with the lab-ecosystem guidebook and the safe-env
ADR/PRD (the sandbox rehearses exactly these engines). 14 mermaid diagrams
MCP-validated; zero dead links. Authored by the Lab Cartographer cohort.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Tree-docs guidebook under vibe/guidebooks/applications/ documenting the common
app pattern and two contrasting archetypes, drilling into lab-ecosystem/01-factory
(bidirectional):
- README.md : the shared app pattern (repo = Dockerfile + chart + optional iac +
CI; ArgoCD app-of-apps; the <app> join key; .fr vs .lab ingress conventions) +
a two-archetype comparison.
- webapp.md : canonical Go + Postgres exemplar (chart, VaultAuth/Static/Dynamic
CRDs, inline iac vs the shared app_roles module, CI); notes the current nuance
that the live pod still uses the static pgbouncer_auth DATABASE_URL.
- url-shortener.md : Rust + SQLite-on-Longhorn-RWO counterpart (single replica,
no iac/no Vault, CI mirrors the upstream image); the power-cut recovery story.
erp is referenced in prose only (its own guidebook lands next). Sibling-repo code
via full gitea URLs; 2 mermaid diagrams MCP-validated; zero dead links.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Two agent-oriented runbooks under vibe/runbooks/ with [AGENT]/[HUMAN] step
markers, grounded in real diffs:
- new-tool.md : add a platform component to the tools repo so ArgoCD deploys it
into the tools namespace (wrapper Chart.yaml + the tool library + a row in
chart/values.yaml; optional iac/ for secrets). Mirrors the prometheus/crowdsec
additions.
- new-app.md : stand up a brand-new application across THREE repos (app +
factory + tools) with the strict ordering dependency and the TERRAFORM_SSH_KEY
pitfall. Phase-by-phase mapped to the dance-lessons-coach onboarding PRs
(#89/#97/#98/#99/#100), factory #1/#2, tools #1; the FR doc/runbooks/new-web-app
is linked as the detailed companion.
2 mermaid diagrams MCP-validated; zero dead links across the vibe tree.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
The two factory-provisioning sub-hubs were the only guidebook index pages without
the "alter a documented component -> update its page in the same PR" reminder that
every sibling hub carries. Add a scoped maintenance rule to each, pointing back to
the factory-provisioning maintenance rule and the guidebooks' Rules to contribute,
so no folder hub silently drifts.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Per-session Claude Code checkouts live under .claude/worktrees/<slug>/
on the trunk; keep them out of git so the main checkout stays clean.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
What
Introduces a root
AGENTS.md(ecosystem map offactory/tools/cms+ agent operating rules + a reusable persona cohort & workflow) and a newvibe/knowledge base for LLM agents — built with thetree-docsconventions and the factory house style.24 files, zero dead links, every Mermaid diagram MCP-validated.
The
vibe/treeEach folder has a README hub + "rules to contribute":
vibe/ADR/doc/adr/stays historical, cross-linked)vibe/PRD/STATUS.md, QA strategy for big ones (tree-docs)vibe/investigations/INV-NNN-slug.md, or stub + same-named folder with notebooksvibe/guidebooks/vibe/runbooks/[AGENT]/[HUMAN]step procedures (EN;doc/runbooks/stays FR)vibe/shareouts/Seed content — first ADR + PRD
A safe, production-like environment to rehearse risky changes and recovery without touching real prod:
Conventions enforced
No-tombstone rule (foremost) · breadcrumb spine · bidirectional cross-links ·
theme:baseMermaid + ordered-list-after-diagram · English invibe/, French inshareouts/.Built with a Workflow + persona cohort (Lab Cartographer, ADR Scribe, PRD Architect, Investigator, Diagram Smith, Continuity Warden).
🤖 Generated with Claude Code