How amber-chang/builder-pm works
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: .context Context · agents Agents · CLAUDE.md Constitution · setup.sh Bootstrap
Components 18
Authoring Space
Repo-level source material and bootstrap entrypoint.
- README · Explains the template/governance model and operating intent.
README.md - Design doc · Primary architecture and design source of truth.
docs/design.md - Bootstrap · Copies template content into a target project and initializes it.
setup.sh - Archive docs · Historical audits and inventory material.
docs/archive
Governance Core
Agent contracts, rules, and coordination surface.
- Constitution · Compact top-level ruleset for the generated project.
template/CLAUDE.md - Skill map · Maps roles to reusable skills.
template/SKILLS.md - Agents · Coordinator, Planner, Generator, and Evaluator role definitions.
template/.claude/agents - Commands · AI-assisted command entrypoints for project workflows.
template/.claude/commands - Skills · Reusable workflow techniques such as brainstorming, TDD, and review.
template/.claude/skills
Project Memory
Long-lived context and evolving project knowledge.
- Context · Persistent project vocabulary, conventions, and module context.
template/.context - System state · High-level system memory and current project shape.
template/.context/SYSTEM.md - Glossary · Shared terms and vocabulary for the project.
template/.context/GLOSSARY.md - Conventions · Project-specific conventions and standards.
template/.context/CONVENTIONS.md - Modules · Module-specific knowledge pages under the context boundary.
template/.context/modules
Ops Loops
Self-maintenance checks and stabilizers.
- Loops · Guardrails for anti-bloat, learning capture, and context growth.
template/loops
Verification Gates
Automated drift and fitness checks.
- Drift gate · Checks canonical facts against docs to detect drift.
template/gates/drift-fact-check
Onboarding
Human entry and retrofitting workflow.
- Onboarding · Human guide for starting work in a generated project.
template/ONBOARDING.md - Backfill · Scans existing repos to backfill governance and context.
template/onboarding/backfill
Connections 20
- 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.