# amber-chang/builder-pm architecture

> Architecture diagram of the GitHub repository amber-chang/builder-pm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amber-chang/builder-pm
- Repository: https://github.com/amber-chang/builder-pm

## Overview

1. **What this repo is**
   - This is not an application runtime; it is a **template + governance package** for initializing other projects.
   - The architectural boundary is: **root repo = authoring/specification space**, while **`template/` = the installable payload** that gets copied into a new project.

2. **Primary source of truth**
   - `docs/design.md` is the canonical architecture/design document.
   - `README.md` frames the product intent and the “one-page core + minimal skeleton + optional modules” model.
   - `docs/archive/` contains prior audits/inventory material; these are support artifacts, not core runtime components.

3. **Installer / bootstrap path**
   - `setup.sh` is the only obvious executable entrypoint at the repo level.
   - Its job is to copy `template/` into a target project, fill placeholders, initialize git, and optionally enable extra modules.
   - This creates the key flow: **template repository → generated project scaffold**.

4. **The installable payload**
   - Everything under `template/` is meant to land in the downstream project.
   - That payload is organized around governance, agent contracts, knowledge files, control loops, and onboarding material rather than product features.

5. **Governance core**
   - `template/CLAUDE.md` is the “one-page constitution”: the compact ruleset the README calls the 10 principles / 4 phase buckets.
   - `template/SKILLS.md` acts as the single mapping from roles to skills.
   - `template/.claude/agents/` defines the four role contracts: **Coordinator, Planner, Generator, Evaluator**.
   - This is the main delivery pipeline: **human ↔ Coordinator → Planner → Generator → Evaluator**.

6. **Operational skills layer**
   - `template/.claude/skills/` contains reusable behavior packs such as brainstorming, TDD, and code review.
   - These are not app features; they are workflow behaviors attached to the agent roles.
   - The architecture separates **role orchestration** from **task technique**.

7. **Project knowledge layer**
   - `template/.context/` is the evolving project memory: `SYSTEM.md`, `GLOSSARY.md`, `CONVENTIONS.md`, and `modules/`.
   - This is the main long-lived knowledge boundary for the generated project.
   - The idea is that the project’s vocabulary, conventions, and module-specific context accumulate here over time.

8. **Self-maintenance loops**
   - `template/loops/` contains three stabilization mechanisms:
     - **anti-bloat**: checks rule fitness and prevents the system from accumulating dead weight
     - **learning-capture**: captures lessons from work sessions
     - **context-growth**: ensures the context set grows in a controlled way
   - These are guardrail subsystems, not user-facing features.

9. **Hard gate / verification layer**
   - `template/gates/drift-fact-check/` is the main automated gate described in the README.
   - It compares canonical facts against docs to detect drift, using a small Node/CommonJS testable checker (`check-drift-fact.cjs` plus fixtures/tests).
   - This is one of the “two hard gates” the README emphasizes: a **truth-consistency check** for governance docs.

10. **Onboarding and project backfill**
   - `template/ONBOARDING.md` is the human entry guide for starting work in a generated project.
   - `template/onboarding/backfill/` contains a separate evidence-scanning/backfill workflow, with fixtures for empty, no-git, and sample projects.
   - This subsystem appears aimed at retrofitting governance/context into existing repositories rather than only greenfield installs.

11. **Command and hook surface**
   - `template/.claude/commands/` and `template/.claude/skills/` show the repo is designed for an AI-assisted command workflow.
   - `template/loops/learning-capture/capture-nudge.hook.cjs` suggests hook-driven capture at session boundaries.
   - So the operational model is **document + agent contract + hook/checker**, not a standalone daemon or service.

12. **External/runtime characteristics**
   - The checkers and hooks are implemented as **Node/CommonJS scripts**, with adjacent test files and fixtures.
   - There is no evidence of a traditional backend, frontend, database, or network service; the architecture is primarily **filesystem-driven governance automation**.
   - The important runtime boundary is between **static template content** and **small validation scripts** that enforce consistency.

13. **How the pieces fit together**
   - Build-time: the repo authors maintain `docs/`, gate logic, and template content.
   - Install-time: `setup.sh` materializes `template/` into a new project.
   - Run-time in the generated project: agents use `CLAUDE.md`, `SKILLS.md`, and `.context/` to coordinate work.
   - Maintenance-time: loops and gates scan for rule bloat, learning opportunities, and factual drift.

14. **Diagramming takeaway**
   - The clearest architecture diagram would center on a **governance stack**:
     - top: human workflow and onboarding
     - middle: coordinator/planner/generator/evaluator agent pipeline
     - supporting layers: skills, context, gates, loops
     - bottom: `setup.sh` bootstrap and the `template/` payload
   - This repo is best understood as a **meta-system for producing disciplined AI-assisted projects**, not as a product application itself.

Main entry points: [`template/.context`](https://github.com/amber-chang/builder-pm/blob/main/template/.context) (Context), [`template/.claude/agents`](https://github.com/amber-chang/builder-pm/blob/main/template/.claude/agents) (Agents), [`template/CLAUDE.md`](https://github.com/amber-chang/builder-pm/blob/main/template/CLAUDE.md) (Constitution), [`setup.sh`](https://github.com/amber-chang/builder-pm/blob/main/setup.sh) (Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_root["Authoring Space"]
  node_n_readme["README<br/>product framing<br/>[README.md]"]
  node_n_design["Design doc<br/>canonical design<br/>[design.md]"]
  node_n_setup["Bootstrap<br/>installer script<br/>[setup.sh]"]
  node_n_archive["Archive docs<br/>supporting docs"]
end

subgraph group_g_template["Template Payload"]
end

subgraph group_g_governance["Governance Core"]
  node_n_claude_md["Constitution<br/>governance rules<br/>[CLAUDE.md]"]
  node_n_skills_md["Skill map<br/>[SKILLS.md]"]
  node_n_agents["Agents<br/>role contracts<br/>[agents]"]
  node_n_commands["Commands<br/>command surface<br/>[commands]"]
  node_n_skills["Skills<br/>behavior packs<br/>[skills]"]
end

subgraph group_g_knowledge["Project Memory"]
  node_n_context["Context<br/>project memory<br/>[.context]"]
  node_n_system["System state<br/>context core<br/>[SYSTEM.md]"]
  node_n_glossary["Glossary<br/>context lexicon<br/>[GLOSSARY.md]"]
  node_n_conventions["Conventions<br/>context rules<br/>[CONVENTIONS.md]"]
  node_n_modules["Modules<br/>module context<br/>[modules]"]
end

subgraph group_g_ops["Ops Loops"]
  node_n_loops["Loops<br/>stabilization suite"]
end

subgraph group_g_gates["Verification Gates"]
  node_n_drift_gate["Drift gate<br/>fact checker"]
end

subgraph group_g_onboard["Onboarding"]
  node_n_onboarding["Onboarding<br/>entry guide<br/>[ONBOARDING.md]"]
  node_n_backfill["Backfill<br/>retrofit workflow"]
end

node_n_readme -->|"frames"| node_n_design
node_n_setup -->|"materializes"| node_n_claude_md
node_n_setup -->|"installs"| node_n_context
node_n_setup -->|"delivers"| node_n_onboarding
node_n_claude_md -->|"defines"| node_n_agents
node_n_skills_md -->|"maps"| node_n_skills
node_n_agents -->|"invokes"| node_n_commands
node_n_agents -->|"uses"| node_n_skills
node_n_agents -->|"reads"| node_n_context
node_n_context -->|"contains"| node_n_system
node_n_context -->|"contains"| node_n_glossary
node_n_context -->|"contains"| node_n_conventions
node_n_context -->|"extends"| node_n_modules
node_n_loops -->|"controls"| node_n_context
node_n_loops -->|"checks"| node_n_claude_md
node_n_drift_gate -->|"validates"| node_n_design
node_n_drift_gate -->|"validates"| node_n_claude_md
node_n_onboarding -->|"routes to"| node_n_backfill
node_n_backfill -->|"populates"| node_n_context
node_n_archive -.->|"supports"| node_n_design

click node_n_readme "https://github.com/amber-chang/builder-pm/blob/main/README.md"
click node_n_design "https://github.com/amber-chang/builder-pm/blob/main/docs/design.md"
click node_n_setup "https://github.com/amber-chang/builder-pm/blob/main/setup.sh"
click node_n_archive "https://github.com/amber-chang/builder-pm/tree/main/docs/archive"
click node_n_claude_md "https://github.com/amber-chang/builder-pm/blob/main/template/CLAUDE.md"
click node_n_skills_md "https://github.com/amber-chang/builder-pm/blob/main/template/SKILLS.md"
click node_n_agents "https://github.com/amber-chang/builder-pm/blob/main/template/.claude/agents"
click node_n_commands "https://github.com/amber-chang/builder-pm/blob/main/template/.claude/commands"
click node_n_skills "https://github.com/amber-chang/builder-pm/blob/main/template/.claude/skills"
click node_n_context "https://github.com/amber-chang/builder-pm/blob/main/template/.context"
click node_n_system "https://github.com/amber-chang/builder-pm/blob/main/template/.context/SYSTEM.md"
click node_n_glossary "https://github.com/amber-chang/builder-pm/blob/main/template/.context/GLOSSARY.md"
click node_n_conventions "https://github.com/amber-chang/builder-pm/blob/main/template/.context/CONVENTIONS.md"
click node_n_modules "https://github.com/amber-chang/builder-pm/blob/main/template/.context/modules"
click node_n_loops "https://github.com/amber-chang/builder-pm/tree/main/template/loops"
click node_n_drift_gate "https://github.com/amber-chang/builder-pm/tree/main/template/gates/drift-fact-check"
click node_n_onboarding "https://github.com/amber-chang/builder-pm/blob/main/template/ONBOARDING.md"
click node_n_backfill "https://github.com/amber-chang/builder-pm/tree/main/template/onboarding/backfill"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_readme,node_n_design,node_n_setup,node_n_archive,node_n_onboarding,node_n_backfill toneBlue
class node_n_claude_md,node_n_skills_md,node_n_agents,node_n_commands,node_n_skills toneMint
class node_n_context,node_n_system,node_n_glossary,node_n_conventions,node_n_modules toneRose
class node_n_loops toneIndigo
class node_n_drift_gate toneTeal
```

## Components

### Authoring Space

Repo-level source material and bootstrap entrypoint.

- [README](https://github.com/amber-chang/builder-pm/blob/main/README.md): product framing · Explains the template/governance model and operating intent. · `README.md`
- [Design doc](https://github.com/amber-chang/builder-pm/blob/main/docs/design.md): canonical design · Primary architecture and design source of truth. · `docs/design.md`
- [Bootstrap](https://github.com/amber-chang/builder-pm/blob/main/setup.sh): installer script · Copies template content into a target project and initializes it. · `setup.sh`
- [Archive docs](https://github.com/amber-chang/builder-pm/tree/main/docs/archive): supporting docs · Historical audits and inventory material. · `docs/archive`

### Governance Core

Agent contracts, rules, and coordination surface.

- [Constitution](https://github.com/amber-chang/builder-pm/blob/main/template/CLAUDE.md): governance rules · Compact top-level ruleset for the generated project. · `template/CLAUDE.md`
- [Skill map](https://github.com/amber-chang/builder-pm/blob/main/template/SKILLS.md): role-skill map · Maps roles to reusable skills. · `template/SKILLS.md`
- [Agents](https://github.com/amber-chang/builder-pm/blob/main/template/.claude/agents): role contracts · Coordinator, Planner, Generator, and Evaluator role definitions. · `template/.claude/agents`
- [Commands](https://github.com/amber-chang/builder-pm/blob/main/template/.claude/commands): command surface · AI-assisted command entrypoints for project workflows. · `template/.claude/commands`
- [Skills](https://github.com/amber-chang/builder-pm/blob/main/template/.claude/skills): behavior packs · Reusable workflow techniques such as brainstorming, TDD, and review. · `template/.claude/skills`

### Project Memory

Long-lived context and evolving project knowledge.

- [Context](https://github.com/amber-chang/builder-pm/blob/main/template/.context): project memory · Persistent project vocabulary, conventions, and module context. · `template/.context`
- [System state](https://github.com/amber-chang/builder-pm/blob/main/template/.context/SYSTEM.md): context core · High-level system memory and current project shape. · `template/.context/SYSTEM.md`
- [Glossary](https://github.com/amber-chang/builder-pm/blob/main/template/.context/GLOSSARY.md): context lexicon · Shared terms and vocabulary for the project. · `template/.context/GLOSSARY.md`
- [Conventions](https://github.com/amber-chang/builder-pm/blob/main/template/.context/CONVENTIONS.md): context rules · Project-specific conventions and standards. · `template/.context/CONVENTIONS.md`
- [Modules](https://github.com/amber-chang/builder-pm/blob/main/template/.context/modules): module context · Module-specific knowledge pages under the context boundary. · `template/.context/modules`

### Ops Loops

Self-maintenance checks and stabilizers.

- [Loops](https://github.com/amber-chang/builder-pm/tree/main/template/loops): stabilization suite · Guardrails for anti-bloat, learning capture, and context growth. · `template/loops`

### Verification Gates

Automated drift and fitness checks.

- [Drift gate](https://github.com/amber-chang/builder-pm/tree/main/template/gates/drift-fact-check): fact checker · Checks canonical facts against docs to detect drift. · `template/gates/drift-fact-check`

### Onboarding

Human entry and retrofitting workflow.

- [Onboarding](https://github.com/amber-chang/builder-pm/blob/main/template/ONBOARDING.md): entry guide · Human guide for starting work in a generated project. · `template/ONBOARDING.md`
- [Backfill](https://github.com/amber-chang/builder-pm/tree/main/template/onboarding/backfill): retrofit workflow · Scans existing repos to backfill governance and context. · `template/onboarding/backfill`

## Connections

- README → Design doc: frames · README points to the canonical design intent.
- Bootstrap → Constitution: materializes · Bootstrap copies the template payload into a new project.
- Bootstrap → Context: installs · Bootstrap also seeds the project memory boundary.
- Bootstrap → Onboarding: delivers · Generated projects start with onboarding guidance.
- Constitution → Agents: defines · The constitution sets the role contract surface.
- Skill map → Skills: maps · Skill map connects roles to technique packs.
- Agents → Commands: invokes · Roles are exposed through command-driven workflows.
- Agents → Skills: uses · Agents pull in reusable behavior packs.
- Agents → Context: reads · Agents rely on project memory while working.
- Context → System state: contains · System state is the top-level context document.
- Context → Glossary: contains · Context includes project vocabulary.
- Context → Conventions: contains · Context includes conventions and standards.
- Context → Modules: extends · Module memory grows under the context boundary.
- Loops → Context: controls · Loops regulate how context accumulates and stays useful.
- Loops → Constitution: checks · Anti-bloat guards the rule set from unnecessary growth.
- Drift gate → Design doc: validates · The drift gate compares facts against canonical docs.
- Drift gate → Constitution: validates · It also checks governance text for factual consistency.
- Onboarding → Backfill: routes to · Onboarding points to retrofitting existing repositories.
- Backfill → Context: populates · Backfill reconstructs project memory from repository evidence.
- Archive docs → Design doc: supports · Archive material informs the design and governance history.