diff --git a/DOCUMENTATION/GIVE-YOUR-AI-A-BUILD-REGISTRY.md b/DOCUMENTATION/GIVE-YOUR-AI-A-BUILD-REGISTRY.md new file mode 100644 index 0000000..5ce4347 --- /dev/null +++ b/DOCUMENTATION/GIVE-YOUR-AI-A-BUILD-REGISTRY.md @@ -0,0 +1,254 @@ +# Give Your AI a Build Registry — Angus’s “Full System” Reel Through the Organized Codebase Lens + +This guide ingests the August 2026 Angus The Tech Bro Facebook reel about his “full system” and translates it into Organized Codebase terms. + +The short version: + +> **the reel is not really about prompting better. It is about moving work out of ephemeral chat and into a durable, human-supervised operating loop.** + +For Organized Codebase, the useful question is not “should OC become a database product?” + +It is: + +> **where does a persistent registry become the right next layer on top of OC’s existing planning + agents + verification stack?** + +--- + +## Source packet + +### Source +- **Facebook Reel:** +- **Creator:** Angus The Tech Bro +- **Hook / caption:** “Btw if you want my full system that I use just comment the word ‘system’ and I’ll send it to you” + +### Jockey ingest receipts +- **Knowledge store:** `Organized Codebase References` (`ks_01a00589-1fe8-7292-8719-5239c71e9da5`) +- **Asset:** `6a8064a8c8c4dec35fbceac6` +- **Item:** `ksi_01a00589-4c33-7082-aeb7-d2f376ff9159` +- **Response:** `resp_01a0058a-4127-7f23-bd16-c38c2d130db4` +- **Session:** `sess_01a0058a-411e-7113-8929-bd9d38be1f53` + +### Local ingest artifacts +- Manifest: `/Users/claw/.openclaw/workspace/memory/ingests/facebook/1690425296055493_2026-08-15_organized-codebase-references/manifest.json` +- Structured insights: `/Users/claw/.openclaw/workspace/memory/ingests/facebook/1690425296055493_2026-08-15_organized-codebase-references/structured_insights.md` +- Raw Jockey response: `/Users/claw/.openclaw/workspace/memory/ingests/facebook/1690425296055493_2026-08-15_organized-codebase-references/jockey_response.json` + +### Grounding note +This guide is grounded in: +- the reel’s visible labels and spoken claims, +- a recovered progressive MP4 source packet, +- and a structured Jockey extraction saved in the ingest bundle above. + +The reel is architectural and persuasive, not a low-level implementation demo, so backend specifics beyond the visible system shape should be treated as inference rather than fact. + +--- + +## Executive takeaway + +The reel argues for a system with five properties: +1. **durable state** instead of ad hoc prompts, +2. **a registry of work objects** instead of loose files and memory, +3. **specialized agents/skills** instead of one generic agent, +4. **a visible scope → plan → build → test loop**, and +5. **a human bottleneck by design**, especially for taste, strategy, and go-to-market judgment. + +Organized Codebase already does **3, 4, and 5** well. + +It partially does **2** through repo structure and issue/PR workflows. + +It does **not yet present 1 and 2 as a first-class, durable operating pattern** for advanced multi-session builds. + +That is the main gap this reel surfaces. + +--- + +## What the reel actually shows + +The strongest directly visible/spoken elements are: +- “THE LOOP — A system that improves itself.” +- Two inputs: **human input** and **agent input**. +- A database layer that “tracks issues, builds, workflows, skills.” +- A four-stage loop: **scope → plan → build → test**. +- A registry pitch: **“One database for everything you build.”** +- Explicit tables/objects: **tools, workflows, skills, apps, issues**. +- Specialized agent/skill roles: **strategize, build, test, resolve, health check, audit**. +- A counterweight to full autonomy: **“Nothing runs without me: I AM THE LOOP.”** +- A closing claim that the real bottleneck is still humans, especially in creative / go-to-market work. + +That combination matters because it defines a very specific operating model: +- not “better prompts,” +- not “just spawn more agents,” +- not “fully autonomous software factory,” +- but **persistent records + narrow agents + explicit verification + human oversight**. + +--- + +## Where Organized Codebase already matches the reel + +### 1. OC already treats work as a loop, not a one-shot prompt +The reel’s central loop is **scope → plan → build → test**. + +Organized Codebase already encodes that shape in multiple places: +- `README.md` Boris workflow: `/status → Plan Mode → Build → /verify → /commit → /review` +- `.claude/workflows/` via kata modes +- `PLANNING/` as the default planning surface +- verification-oriented commands such as `/verify` and `/review` + +So on loop structure, OC is already aligned. + +### 2. OC already favors specialized roles over one giant agent +The reel surfaces narrow agent/skill roles such as strategize, build, test, resolve, health check, and audit. + +OC already pushes in this direction through: +- `.claude/agents/` +- `.claude/skills/` +- `DOCUMENTATION/GRAPH-ENGINEERING-ORGANIZED-CODEBASE-FIT.md` +- verification-specific agents like `verify-build` and `verify-architecture` + +This is a strong fit: the reel validates OC’s direction toward explicit role separation. + +### 3. OC already keeps the human in the loop +The reel is explicit that humans remain the bottleneck for taste, judgment, and GTM decisions. + +OC already agrees in practice: +- permissions distinguish safe auto-approve from approval-required actions, +- `/review` keeps a deliberate pre-PR judgment layer, +- Boris docs repeatedly frame verification as the control surface, +- the repo positions scaffolding as a way to unlock models safely, not to remove operator judgment. + +That means the reel is **not** asking OC to become “autonomous by default.” +It is reinforcing OC’s human-supervised stance. + +--- + +## Where Organized Codebase is weaker than the reel + +### 1. OC has structure, but not yet a first-class registry story +OC has directories, docs, agents, skills, and PR workflow — but it does **not** yet explain an optional **system-of-record layer** where agents operate on durable work objects such as: +- tools, +- workflows, +- skills, +- apps, +- issues, +- verification results, +- and health/audit findings. + +Today, those concepts mostly live across: +- markdown files, +- git state, +- issue trackers, +- and agent context. + +That works well for many repos, but it is not the same thing as a documented **build registry** pattern. + +### 2. OC does not yet connect health checks and audits back into one common queue +The reel’s loop is important because agent diagnostics feed the same system as human requests. + +OC already has pieces of this idea: +- verification agents, +- review passes, +- graph review concepts, +- maintenance-oriented docs, +- and loop-efficiency notes. + +But those pieces are not yet presented as one durable pattern where: +- diagnostics create or update tracked issues, +- those issues become explicit work items, +- and the next build cycle consumes them. + +### 3. OC lacks a crisp “advanced mode” explanation for persistent state +The reel’s strongest reusable idea is not that every repo needs a database tomorrow. +It is that **some advanced workflows outgrow chat history and filesystem-only coordination**. + +OC would benefit from stating this more plainly: +- default mode: repo structure + plan + verify is enough, +- advanced mode: add a durable registry when the work becomes multi-session, multi-agent, multi-surface, or operator-facing. + +That distinction is currently more implied than taught. + +--- + +## What OC should take from this reel + +### Keep the default simple +Do **not** turn Organized Codebase into “database-first by default.” +For many codebases, OC’s current core is correct: +- repo structure, +- plan mode, +- narrow agents, +- verification, +- PR review. + +### Add a documented advanced pattern +The better move is to teach a new optional layer: + +> **Build Registry Mode** + +Use it when all of these are true: +- the project runs across multiple sessions, +- more than one agent or workflow updates shared state, +- diagnostics need to feed future work automatically, +- operator-facing apps/UIs sit on top of the system, +- or the team wants durable work objects beyond transient chat context. + +### Frame the registry correctly +The registry is not the “agent brain.” +It is the durable substrate for: +- work objects, +- issues, +- verification outcomes, +- health/audit findings, +- and handoffs between humans and agents. + +That framing matters because it keeps OC grounded in operations instead of drifting into vague “memory layer” marketing. + +--- + +## Recommended OC positioning after this comparison + +### Organized Codebase should say +- OC is the **verification-first scaffold** for human-supervised agent work. +- For advanced systems, OC can sit **on top of** a durable registry. +- The registry is where tools/workflows/skills/apps/issues live as persistent objects. +- The human remains the final judge on taste, strategy, and release decisions. + +### Organized Codebase should avoid saying +- that every project needs a database to benefit from OC, +- that more agents automatically means better outcomes, +- or that persistent state removes the need for human review. + +--- + +## What to ship first + +### Ship now +- this source-grounded guidance doc, +- a README link so the idea is discoverable, +- and a clearer sentence in the main workflow docs that OC can grow into a registry-backed advanced mode. + +### Ship later, only if real users need it +- a reusable **build-registry mode** spec/template, +- a minimal schema for `tools / workflows / skills / apps / issues / checks`, +- guidance for feeding health/audit outputs back into tracked work, +- and examples of when a registry materially beats filesystem-only coordination. + +That keeps the repo honest: **docs first, productization second**. + +--- + +## Bottom line + +The reel does not invalidate Organized Codebase’s current design. +It sharpens it. + +OC already has the right instincts around: +- narrow roles, +- explicit loops, +- verification, +- and human oversight. + +The gap is that OC does not yet teach a clean next step for builders whose workflows need **durable shared state**. + +So the right takeaway is: + +> **Organized Codebase should remain verification-first and human-in-the-loop by default, while documenting a registry-backed advanced mode for systems that need persistent work objects and agent-readable state.** diff --git a/README.md b/README.md index e25c742..83ee83d 100644 --- a/README.md +++ b/README.md @@ -171,6 +171,8 @@ Build → One feature at a time The commands enforce the discipline. You can't forget to verify because the workflow includes it. +For larger multi-session systems, treat Organized Codebase as the human-supervised scaffold around the loop. `PLANNING/`, agents, skills, and verification define how work moves; if the project outgrows chat history and loose files, add a durable registry or issue substrate underneath that loop instead of falling back to ad hoc prompting. See [Give Your AI a Build Registry](DOCUMENTATION/GIVE-YOUR-AI-A-BUILD-REGISTRY.md). + ### Permissions The `.claude/settings.json` uses three tiers: @@ -313,6 +315,7 @@ npx create-organized-codebase@latest my-project - **[Delete Your `CLAUDE.md`? — Boris Cherny’s 7 Takeaways for Organized Codebase](DOCUMENTATION/BORIS-DELETE-YOUR-CLAUDE-MD-GUIDE.md)** — July 2026 YC / Hyperautomation Labs synthesis with actionable repo takeaways - **[Boris Context Placement Ladder](DOCUMENTATION/BORIS-CONTEXT-PLACEMENT-LADDER.md)** — Operator rules for prompt vs `CLAUDE.md` vs skill vs MCP, plus routines vs dynamic workflows - **[Graph Engineering in Organized Codebase](DOCUMENTATION/GRAPH-ENGINEERING-ORGANIZED-CODEBASE-FIT.md)** — Practical use cases, anti-use-cases, and a narrow rollout recommendation for OC +- **[Give Your AI a Build Registry](DOCUMENTATION/GIVE-YOUR-AI-A-BUILD-REGISTRY.md)** — Jockey-grounded comparison of Angus’s “full system” reel with OC’s existing loop, verification, and human-in-the-loop model - **[Closed-Loop Evals for Multimodal Agents](DOCUMENTATION/CLOSED-LOOP-EVALS-MULTIMODAL-AGENTS.md)** — TwelveLabs + transcript-grounded takeaways from Uber’s multimodal eval talk, translated into OC operator rules - **[Eval Loop Spec Template](PLANNING/spec-templates/eval-loop.md)** — Reusable scaffold for stage metrics, judges, replay, promotion gates, and rollback - **[Boris Ablation Eval Matrix](DOCUMENTATION/BORIS-ABLATION-EVAL-MATRIX.md)** — How to decide what to prune using tests + evals across models and harnesses