arcodange-org/factory
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(vibe): bootstrap vibe/ knowledge tree + ecosystem AGENTS.md #10

Merged
arcodange merged 9 commits from arcodange/focused-dirac-151213 into main 2026-06-24 11:01:12 +02:00
Conversation 0 Commits 9 Files Changed 56 +6234 -1
arcodange commented 2026-06-23 11:53:15 +02:00
Owner
Copy Link

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:

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

## 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)
arcodange added 1 commit 2026-06-23 11:53:18 +02:00
docs(vibe): bootstrap vibe/ knowledge tree + ecosystem AGENTS.md 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>
arcodange added 1 commit 2026-06-23 11:53:43 +02:00
docs(vibe): backfill PR #10 crosslink into ADR-0001 + PRD STATUS b886f06824 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
arcodange added 1 commit 2026-06-23 21:11:57 +02:00
docs(vibe): add factory-provisioning guidebook (Ansible + OpenTofu) dbe32161dc 
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 <noreply@anthropic.com>
arcodange added 1 commit 2026-06-23 21:41:21 +02:00
docs(vibe): add tools/ and cms/ guidebooks 548dacfc44 
Two code-grounded tree-docs guidebooks under vibe/guidebooks/, drilling into the
lab-ecosystem 02-tools and 03-cms pages (bidirectional):

- tools/  : hub + components.md (Vault+VSO, Prometheus, Grafana, CrowdSec,
  pgbouncer, Redis/KeyDB, Plausible, ClickHouse; pgcat/tool as Tier-2) +
  secrets-and-vso.md (Vault engines/auth, the app_roles/app_policy modules =
  the <app> join-key machinery, VSO CRDs, secret-paths inventory).
- cms/    : hub + site.md (Nuxt + dual Pages/k3s deploy) + cloudflare.md
  (zone via OVH->CF, Pages, cloudflared tunnel, Turnstile, R2 state) +
  zoho-email.md (OAuth, MX/SPF/DKIM/DMARC/BIMI, the 7 aliases).

Sibling-repo code linked via full gitea URLs; vibe-internal links bidirectional.
Reconciled the cloudflared tunnel token path to kvv2 cms/cloudflared (the chart
VaultStaticSecret is kv-v2; the kvv1 tofu reference is a commented-out stub).
6 mermaid diagrams MCP-validated; zero dead links. Lab Cartographer cohort.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
arcodange added 1 commit 2026-06-23 21:58:40 +02:00
docs(vibe): add applications/ guidebook (webapp + url-shortener) 4823394e0e 
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 <noreply@anthropic.com>
arcodange added 1 commit 2026-06-23 22:12:16 +02:00
docs(vibe): add erp/ guidebook (Dolibarr deployment + backup/recovery + ops) 7bf83e75ed 
Dedicated tree-docs guidebook under vibe/guidebooks/erp/ for the lab's most
data-critical app, cross-linked from the applications hub (bidirectional):

- README.md             : Dolibarr 22.0.4 on Postgres; data-criticality; overview
  diagram; the Vault-unseal-before-scale recovery ordering (CAUTION).
- deployment.md         : upstream image + custom entrypoint (MySQL->psql), the
  50Gi Longhorn RWX documents PVC, Vault CRDs + the shared app_roles iac, init
  scripts (conf.php creds, table-ownership), ingress, CI.
- backup-and-recovery.md: the Ansible CronJob pg_dump (daily 04:00, 15-day
  retention) + restore Job (scale-0 -> restore -> scale-1); the cluster recovery
  ordering (Longhorn -> Vault unseal -> erp scale-up).
- operations.md         : the read-only bin/arcodange CLI, static/company.json,
  Deno+Playwright tests, day-2 ops.

erp code via full gitea URLs; CLUSTER_RECOVERY.md by name; 2 mermaid diagrams
MCP-validated; zero dead links.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
arcodange added 1 commit 2026-06-23 22:22:13 +02:00
docs(vibe): add new-tool and new-app runbooks (grounded in real PRs) 2d76eb45c1 
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 <noreply@anthropic.com>
arcodange added 1 commit 2026-06-23 23:42:32 +02:00
docs(vibe): add maintenance rule to the ansible + opentofu sub-hubs 1824a1885d 
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 <noreply@anthropic.com>
arcodange added 1 commit 2026-06-24 10:55:54 +02:00
chore: gitignore .claude/worktrees 053b04337a 
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 <noreply@anthropic.com>
arcodange merged commit 3b0919b804 into main 2026-06-24 11:01:12 +02:00
arcodange deleted branch arcodange/focused-dirac-151213 2026-06-24 11:01:14 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
arcodange
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: arcodange-org/factory#10
Delete Branch "arcodange/focused-dirac-151213"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?