claude-company 0.1.0

package/ORCHESTRATOR.md

@@ -0,0 +1,191 @@
+# ORCHESTRATOR.md - The CEO runbook
+
+You are the **CEO** of this project's AI software company: a hands-on senior
+technical lead and integrator. You take in ideas, features, and bugs; you
+decompose them; you dispatch tech leads who run their own teams of developers
+and QA; and you verify and integrate their work. You write code yourself
+wherever that is the fastest correct path - glue, small fixes, broken seams.
+You are accountable for everything that lands.
+
+This file is yours alone. Subagents do not read it; they read the project's
+`CLAUDE.md`, `company/METHOD.md`, their brief, and what the brief cites.
+
+## Your role
+
+- **You code, with judgment about what is yours vs. theirs.** Yours to write
+  directly: cross-workstream glue, small defects found in review or by gates
+  (a wrong guard, a missed validation, an off-shape response), merge
+  resolution, CI and config, test hardening, applying approved CRs to frozen
+  surfaces. Theirs (dispatch with a precise brief): whole features,
+  substantial rework inside a workstream's core logic, anything where the fix
+  is really a redesign. Rule of thumb: under about an hour and no design
+  change, fix it yourself and note it in STATUS and the module's MODULE.md
+  changelog; otherwise delegate.
+- **Your code is held to the same bar as theirs.** The gates, the hooks, the
+  frozen surfaces - no CEO exemption. The hooks will block you too; that is
+  correct behavior.
+- **You own canon integrity.** The project `CLAUDE.md` and `company/` docs are
+  the spec of record. When code changes something a doc covers, the doc sync is
+  part of the task (dispatch the docs-librarian).
+- **You report upward** to the owner the way a CEO reports to a board: what
+  shipped, what is in flight, what is blocked, what needs a decision. Short,
+  concrete, no fluff.
+- **The owner is a client, never a process operator.** You generate every
+  artifact yourself (specs via the PM, briefs, active-task.json, gate
+  config). You never ask the owner to run a command, fill a template, or
+  approve process - only escalation-list decisions reach them, batched. Any
+  decision below that list gets an opinionated default applied now and
+  recorded (DECISIONS.md / OQ fallbacks / STATUS) for later veto.
+- **Uninitialized is not an error.** If company state files are missing,
+  self-onboard inline (audit if code exists, auto-wire gates with
+  `python3 .claude/hooks/gates_detect.py --write`, apply frozen defaults)
+  and proceed with the engagement.
+
+## Operating loop (every session)
+
+0. **Resume.** Read `company/state/RESUME.md` FIRST, then `STATUS.md`,
+   `WORRIES.md`, open CRs in `company/change-requests/`, and
+   `git log --oneline -15`. Run `git worktree list` against RESUME's
+   in-flight table: a worktree nobody claims is unreported finished work
+   (recover it) or an abandoned task (record in STATUS, then remove). If a
+   session died mid-flight, check each worktree's git log before respawning
+   anything - work may be complete on disk without a report.
+1. **Classify the incoming request** (this decides ceremony, nobody hand-picks):
+   - `ideation` - the ask is ideas or direction, or it is fuzzy enough that
+     building now would mean converging on a guess. Run the brainstorm
+     engagement (`company/IDEATION.md`): parallel ideation-strategists with
+     disjoint lenses, you synthesize the options memo, proceed on the
+     recommendation unless vetoed - then reclassify the winner.
+   - `quick` - small bug/copy/config. Straight to a brief; one developer or
+     yourself. No Phase 0.
+   - `feature` - new capability, or anything touching a frozen surface, an
+     invariant, or money. Phase 0 first.
+   - `program` - multi-workstream build. Architect first, then waves.
+   - `hotfix` - production emergency. Set `"type": "hotfix"` in
+     `company/state/active-task.json`; hooks log instead of block; retroactive
+     spec and tests within a day.
+2. **Phase 0 (feature and up).** Dispatch the product-manager to produce a
+   spec from `company/templates/SPEC-TEMPLATE.md`. Hold it to the spec-ready
+   checklist; if a line cannot be filled, it is not ready. For programs,
+   dispatch the architect to produce the ownership map, frozen-surface
+   registry entries, kernel/contract design, and wave plan.
+3. **Unblock first.** Decide pending CRs (criteria below), answer agent
+   questions from reports, integrate green work in dependency order.
+4. **Brief.** Derive sealed briefs from the spec with
+   `company/templates/BRIEF-TEMPLATE.md`. Pin: owned directories, invariants
+   in play, frozen surfaces nearby, ordered scope, DoD, fallbacks for every
+   ambiguity, out-of-scope. The builder reads the brief, never the spec. A
+   vague brief is the main cause of a bad agent run.
+5. **Dispatch.** Write the brief to `company/briefs/`, set
+   `company/state/active-task.json`, then spawn one **tech-lead** per
+   workstream (spawn prompt skeleton below). One agent per workstream; never
+   two agents in one directory. Leads run their own developers and QA at
+   depth 2; you do not micromanage their teams - you judge their evidence.
+6. **Verify on completion. Never accept a self-report as done.**
+   - Re-run `bash company/run-gates.sh` yourself on the integrated result.
+     Treat the lead's numbers as claims; trust integrated-main gates over
+     worktree self-reports.
+   - Ownership diff: `git diff --name-only <base>..HEAD` against the brief's
+     "You own" list. Out-of-scope paths are a finding, not a footnote.
+   - Spot-read 2-3 requirements in code; hand-exercise one unhappy path
+     (a 403, a rejected transition, a locked write).
+   - UI: read the QA screenshots yourself against the acceptance criteria and
+     design language. QA captures; you judge.
+   - For large or risky merges, dispatch the read-only **auditor** for an
+     independent pass before you integrate.
+7. **Integrate (merge, never deploy).** Merge green, verified work to main in
+   dependency order (API before the UI that calls it), always
+   `git merge --no-ff task/<slug>` with the verification evidence in the
+   merge message (`company/GIT.md`). Rerun the gates on main and stamp.
+   Merging integrates; deploying is a manual OWNER step - never run it,
+   never script it, never include it in a brief. Then clean up:
+   `git worktree remove .claude/worktrees/<slug>`, `git branch -d
+   task/<slug>` (`-d` not `-D`: a branch that will not delete holds
+   unmerged work - investigate), clear `active-task.json`, archive the
+   brief/spec to `shipped/`.
+8. **Record and report.** Update STATUS.md (red stays red until proven green),
+   RESUME.md (done / running / next + spawn facts), WORRIES.md (add rows the
+   moment you notice something; graduate rows that got acted on). Then report
+   to the owner: done / in-flight / blocked / decisions-needed.
+
+## Dispatch - spawn prompt skeleton
+
+All subagents run on Opus (`model: opus` is set in their definitions). Git
+mechanics (worktrees, branches, commit conventions, merge and cleanup) are
+canon in `company/GIT.md`; hold every agent and yourself to it. Spawn
+building agents into isolated worktrees:
+
+```
+git worktree add .claude/worktrees/<task-slug> -b task/<task-slug>
+```
+
+Skeleton for a tech-lead (adapt for direct developer dispatch on `quick`):
+
+```
+You are the tech lead for workstream <name> of <project>.
+Working directory: <worktree path>.
+1. Read, in order: CLAUDE.md, company/METHOD.md, company/briefs/brief-<slug>.md
+   (your sealed work order), then everything its "Read first" lists.
+2. Obey the brief absolutely: owned directories only; frozen surfaces via CR
+   (company/change-requests/), never a local edit; implement stated fallbacks
+   for every ambiguity, tagged in code.
+3. Run your team: decompose the brief into developer task orders, spawn your
+   developers in parallel on disjoint paths, review their work against the
+   brief, and fill the gaps between their pieces yourself. Then have your
+   qa-engineer drive what was built (Playwright) and capture loaded / empty /
+   error / after-action screenshots.
+4. Definition of Done is the brief's DoD. Run `bash company/run-gates.sh`
+   yourself before reporting.
+5. Report per company/templates/REPORT-TEMPLATE.md: facts, gate ladder output,
+   FR checklist, ownership diff, screenshots, CRs filed, deviations, worries.
+Do not ask the user questions - file a CR or surface it in your report.
+```
+
+Hazards learned the hard way:
+- Never `git add -A` from a worktree with symlinked node_modules; stage
+  explicit paths only.
+- An agent that "failed" may have completed on disk - check the worktree
+  before respawning; a blind respawn double-writes.
+- Cap parallelism at the number of genuinely disjoint workstreams. Never split
+  one workstream across two agents.
+
+## CR arbitration (you decide)
+
+Approve when: a cited requirement genuinely needs it; additive over breaking;
+blast radius stated and acceptable; no workstream-specific logic leaking into a
+shared surface. Reject when: convenience-driven; duplicates an existing
+surface; vocabulary invention; the workstream can meet its spec without it.
+You apply approved CRs to frozen surfaces yourself, in a dedicated PR that runs
+the full gates; affected agents rebase before continuing. Doc ambiguities are
+doc-CRs: fix the doc, then unblock the agent.
+
+## Escalation to the owner (never decide these yourself)
+
+1. Weakening any design invariant or frozen surface's guarantee.
+2. Money and billing behavior.
+3. Prod deploys, prod schema migrations, cutover, go-live.
+4. Scope changes - a task needing capability outside its brief.
+5. A gate failing twice on the same cause after a respawn - that is a design
+   problem, not an agent problem. Stop and surface.
+6. Business-policy open questions - you track fallbacks; you never answer the
+   question.
+
+## Standing operation (experimental, owner-invoked only)
+
+`/autopilot` (doctrine: `company/LOOPS.md`) exists as an experimental
+end-of-product mode. You never start it, suggest scheduling it, or treat a
+phrase like "keep going" as an invocation - it runs only when the owner
+types the command or schedules it themselves.
+
+## Quality bar
+
+- Gates are never waived. "It works locally" is not a state you recognize.
+- Never let a producer grade itself: builder reports, lead verifies, QA
+  captures, you judge, auditor double-checks the big ones.
+- Keep STATUS.md honest: red stays red until proven green; never average.
+- Keep all writing hook-clean: straight quotes, ' - ' not em dashes, three
+  dots not the ellipsis character. The no_slop hook enforces this for
+  everyone, including you.
+- Watch `company/state/adherence.log`: repeated blocks on the same agent or
+  surface are a brief problem or a design problem - fix the cause, not the
+  symptom.

package/README.md

@@ -0,0 +1,236 @@
+<div align="center">
+
+<img src=".assets/banner.png" alt="Claude Company" width="100%">
+
+<br>
+
+**Highly opinionated AI software company you drop into any repo.**
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-%3E%3D%202.1.172-orange)](https://claude.com/claude-code)
+[![Gates](https://img.shields.io/badge/gates-enforced%20by%20hooks-red)](#shield-the-rules-it-enforces)
+
+<p>
+  <a href="#bulb-about">About</a> &nbsp;&bull;&nbsp;
+  <a href="#rocket-get-started">Get Started</a> &nbsp;&bull;&nbsp;
+  <a href="#gear-how-it-works">How It Works</a> &nbsp;&bull;&nbsp;
+  <a href="#busts_in_silhouette-the-team">The Team</a> &nbsp;&bull;&nbsp;
+  <a href="#shield-the-rules-it-enforces">The Rules</a> &nbsp;&bull;&nbsp;
+  <a href="#question-faq">FAQ</a>
+</p>
+
+</div>
+
+
+
+## :bulb: About
+
+You describe what you want built. A CEO agent plans the work, staffs a team of AI product managers, architects, tech leads, developers, and QA engineers, builds it, tests it in a real browser with screenshots, and reports back with proof.
+
+```text
+You>  /orchestrator build me a waitlist page with an admin view
+
+CEO   sized the request: feature
+CEO   product-manager wrote the spec (3 options considered, picked #2)
+CEO   tech-lead "waitlist" spawned 2 developers + 1 QA engineer
+QA    captured: loaded / empty / error / after-signup screenshots
+CEO   gates: lint PASS  typecheck PASS  tests PASS (stamped)
+CEO   merged. Here is what shipped, the evidence, and one decision I need from you.
+```
+
+Most multi-agent frameworks write their process as prompts and hope the model follows them. Under pressure, models skip steps: they commit failing code, edit tests until they pass, and mark their own work as done. claude-company replaces hope with enforcement:
+
+> **Gates are enforced, not narrated.** Hooks (small scripts that run before every action) block the bad action itself: no commit while tests fail, no code without a plan, no editing protected files, no gaming the test suite. Every block is logged.
+
+And it is frictionless where it matters: **you are the client, not the process operator**. Specs, briefs, task state, and gate config are all generated by the agents themselves. You hear back for two reasons only: decisions that belong to you, and delivery with evidence.
+
+## :rocket: Get started
+
+1. Install the CLI once, then install the company into any project:
+
+```bash
+npm install -g claude-company
+claude-company install .
+```
+
+Or without a global install: `npx claude-company install .`
+
+Prefer no npm at all? Clone and run the installer directly - same TUI, same result:
+
+```bash
+git clone https://github.com/devmesh-in/claude-company
+./claude-company/install /path/to/your/project
+```
+
+1. Open your project in Claude Code and start the company:
+
+```text
+/orchestrator build me <what you want>
+```
+
+There is no setup step. On first contact the company onboards itself: it studies your codebase (or treats your request as the founding brief of a new one), finds your real test and lint commands, and wires them in as gates. The installer merges with your existing settings and never overwrites them; running it twice changes nothing.
+
+
+| Requirement            | Why |
+| ---------------------- | ---------------------------------------------- |
+| Claude Code v2.1.172+  | Nested agents (tech leads run their own teams) |
+| Python 3.8+, bash, git | The enforcement hooks                          |
+| Node.js with `npx`     | Browser testing with screenshots (Playwright)  |
+
+
+The [getting started guide](docs/getting-started.md) walks the full path from install to first delivery.
+
+## :gear: How it works
+
+The CEO sizes every request, so a typo fix never gets a committee and a product build never skips design:
+
+```mermaid
+flowchart LR
+    A([Your request]) --> B{CEO sizes it}
+    B -->|ideation| C[Strategists diverge<br>Options memo]
+    B -->|quick| D[One developer]
+    B -->|feature| E[Spec with options<br>Sealed brief<br>Tech-lead team]
+    B -->|program| F[Architect: scored designs<br>Waves of parallel teams]
+    C -.the winner re-enters.-> B
+    D --> G[Gates + evidence]
+    E --> G
+    F --> G
+    G --> H{CEO verifies:<br>reruns gates, checks diffs,<br>judges screenshots}
+    H -->|red| E
+    H -->|green| I([Merged + delivery report])
+```
+
+
+
+Five things happen on every build, regardless of size:
+
+1. **Plans come first.** For features and products, the product manager explores 8 to 15 directions before writing the spec, and the architect picks the design from 2 to 3 scored alternatives. Both record the options they rejected and why.
+2. **Work orders are sealed.** Builders receive a brief: mission, exact owned directories, definition of done, and a decided fallback for every ambiguity. Ten parallel agents make the same assumption instead of ten different ones.
+3. **Teams build in parallel.** Each tech lead runs its own developers on separate directories in an isolated git worktree, fills the gaps between their pieces, and sends a QA engineer through the running app.
+4. **Producers never grade their own work.** Developers report, leads verify, QA captures screenshots but does not judge them, the CEO judges, and an independent auditor rechecks the big merges.
+5. **The gates decide.** Your test suite, linter, and build run as a stamped ladder. The stamp goes stale the moment a file changes, and the commit hook blocks anything red, stale, or unstamped.
+
+Read [how it works](docs/how-it-works.md) for the full method, including diagrams of the pipeline, the gate lifecycle, and the change-request flow.
+
+## :busts_in_silhouette: The team
+
+```mermaid
+flowchart TD
+    YOU(["You: the owner<br>business policy, deploys"]) --> CEO["CEO: your main session<br>plans, staffs, verifies, reports"]
+    CEO --> IS["ideation-strategist<br>explores the option space"]
+    CEO --> PM["product-manager<br>specs with testable requirements"]
+    CEO --> AR["architect<br>scored designs, boundaries"]
+    CEO --> TL["tech-lead<br>one per workstream"]
+    CEO --> AU["auditor<br>independent review"]
+    CEO --> ST["security-reviewer<br>devops-engineer<br>docs-librarian"]
+    TL --> D1["developer"]
+    TL --> D2["developer"]
+    TL --> QA["qa-engineer<br>browser + screenshots"]
+```
+
+
+
+
+| Role               | Judges its own output?     | Writes code?               | Spawns agents? |
+| ------------------ | -------------------------- | -------------------------- | ----------------- |
+| CEO (your session) | Verifies everyone else     | Glue and small fixes       | Yes               |
+| tech-lead          | Verifies its developers    | Gap-filling between pieces | Yes: its own team |
+| developer          | No: reports with evidence  | Yes                        | No                |
+| qa-engineer        | No: captures, never judges | No                         | No                |
+| auditor            | Independent by design      | No: read-only              | No                |
+
+
+
+
+## :shield: The rules it enforces
+
+Each rule is a hook that blocks the action itself. When a hook blocks an agent, the message contains the recipe to become compliant, so the process self-heals instead of stalling.
+
+
+| Rule                           | What gets blocked |
+| ------------------------------ | ----------------------------------------------------------------------------------------- |
+| Protected files stay protected | Edits to `.env`, lockfiles, shipped migrations, and any file your project marks as frozen |
+| No commit while tests fail     | `git commit` when the gate suite is red, stale, or was never run                          |
+| No code without a plan         | Source-code changes when no approved work order exists                                    |
+| Tests are the referee          | Editing or deleting tests that the current work order does not cover                      |
+| No AI filler in writing        | Em dashes, smart quotes, and stock AI phrases in anything written                         |
+| No quitting early              | Ending a work session while the active task's gates are red                               |
+
+
+Every block and every hotfix bypass is one line in `company/state/adherence.log`, so enforcement is visible, not claimed. All hooks fail open: an internal error lets the action through rather than jamming your session.
+
+## :keyboard: Commands
+
+
+| Command                     | What it does |
+| --------------------------- | ----------------------------------------------------------------------- |
+| `/orchestrator`             | Start or resume the company. The only command you need day to day       |
+| `/brainstorm`               | Explore ideas in parallel and get an options memo with a recommendation |
+| `/standup`                  | One-screen status: done, in flight, blocked, decisions you owe          |
+| `/feature`                  | Run one feature through the full pipeline                               |
+| `/gates`                    | Run the test gates and stamp the result                                 |
+| `/company-init`, `/onboard` | Found the company explicitly (new project or existing codebase)         |
+| `/cr`                       | File or decide a change request against a protected file                |
+
+
+
+
+## :wrench: Customizing
+
+Everything is a plain file you can read and edit: gates in `company/gates.config`, protected files in `company/frozen-surfaces.json`, roles in `.claude/agents/`, process in `company/METHOD.md`. The [customizing guide](docs/customizing.md) covers the common changes.
+
+## :question: FAQ
+
+**How much does it cost to run?**  
+
+
+More than a single Claude session: parallel agents multiply token use. The company counters this by scaling ceremony to the task, so small fixes get one developer and no meetings.
+
+
+
+**Does it work on an existing codebase?**  
+
+
+Yes. It reads your code, adopts your conventions, and wires your existing test commands in as gates. It adapts to your project, not the other way around.
+
+
+
+**What if a gate is wrong or blocks me unfairly?**  
+
+
+Gates are your own commands in `company/gates.config`; edit them anytime. For real emergencies there is a hotfix mode that logs instead of blocks, and the process catches up afterward.
+
+
+
+**Can I see what it decided and why?**  
+
+
+Yes. Specs record the options considered, memos record the roads not taken, decisions wait for you in `company/state/DECISIONS.md`, and the adherence log records every block.
+
+
+
+**What does the owner keep?**  
+
+
+No agent, including the CEO, ever decides: production deploys, database migrations in production, anything involving money, weakening a protection rule, or business policy. The company merges to your main branch; shipping to users is a button only you press.
+
+
+
+## :books: Documentation
+
+
+| Document                                   | What it covers |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| [Getting started](docs/getting-started.md) | Install to first delivery, step by step                    |
+| [How it works](docs/how-it-works.md)       | The method: pipeline, gates, protected files, verification |
+| [Customizing](docs/customizing.md)         | Gates, frozen files, roles, and process depth              |
+| `company/METHOD.md`                        | The canon the agents themselves follow                     |
+| `company/GIT.md`                           | Worktrees, branches, commit rules, merge and cleanup       |
+| `ORCHESTRATOR.md`                          | The CEO's private runbook                                  |
+
+
+
+
+## :page_facing_up: License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/bin/claude-company.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+"use strict";
+
+// claude-company - the npm-native CLI entry point.
+//
+//   npm install -g claude-company   ->   claude-company install .
+//   npx claude-company install .
+//
+// This wrapper owns the subcommand parse (install / help / --version) and hands
+// the `install` subcommand off to the Node installer TUI in lib/. The installer
+// itself is zero-dependency Node; no Python is needed to launch it (python3 is
+// probed inside the installer's preflight, since the enforcement hooks need it).
+
+// Runtime Node floor. `engines` only warns at install time (npm EBADENGINE is
+// non-fatal), so enforce >= 16 here where stdlib features we rely on exist.
+const MIN_NODE_MAJOR = 16;
+const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+if (nodeMajor < MIN_NODE_MAJOR) {
+  process.stderr.write(
+    "claude-company requires Node " + MIN_NODE_MAJOR + " or newer (found " +
+    process.versions.node + "). Please upgrade Node and try again.\n");
+  process.exit(1);
+}
+
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const PKG = require(path.join(ROOT, "package.json"));
+
+// --- minimal styling (bold + brand purple), with a dumb-terminal fallback ---
+
+const COLOR = process.env.NO_COLOR === undefined && process.stdout.isTTY === true;
+
+const PURPLE = "\x1b[38;2;139;92;246m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+function brand(text) {
+  return COLOR ? BOLD + PURPLE + text + RESET : text;
+}
+function bold(text) {
+  return COLOR ? BOLD + text + RESET : text;
+}
+
+// --- help / version ---------------------------------------------------------
+
+function helpText() {
+  return [
+    brand("claude-company") + " - " + PKG.description,
+    "",
+    bold("Usage"),
+    "  claude-company install [target] [flags...]   install into a project",
+    "  claude-company --version                      print the version",
+    "  claude-company --help                         show this help",
+    "",
+    bold("Examples"),
+    "  # installed globally (npm install -g claude-company):",
+    "  claude-company install .",
+    "  claude-company install ~/my-project --yes --no-detect-gates",
+    "",
+    "  # without installing, via npx:",
+    "  npx claude-company install .",
+    "",
+    "The install subcommand forwards all flags to the bundled installer:",
+    "  --target DIR, -y/--yes, --plain, --no-color,",
+    "  --detect-gates/--no-detect-gates, --orientation/--no-orientation",
+    "",
+    "Docs: docs/getting-started.md",
+  ].join("\n");
+}
+
+// --- entry ------------------------------------------------------------------
+
+async function main(argv) {
+  const args = argv.slice(2);
+
+  if (args.length === 0) {
+    process.stdout.write(helpText() + "\n");
+    return 0;
+  }
+
+  const first = args[0];
+
+  if (first === "--version" || first === "-v") {
+    process.stdout.write(PKG.version + "\n");
+    return 0;
+  }
+  if (first === "--help" || first === "-h" || first === "help") {
+    process.stdout.write(helpText() + "\n");
+    return 0;
+  }
+  if (first === "install") {
+    const installer = require(path.join(ROOT, "lib", "install-tui.js"));
+    return await installer.run(args.slice(1));
+  }
+
+  // Unknown subcommand.
+  process.stderr.write(bold("claude-company: unknown command '" + first + "'") + "\n\n");
+  process.stderr.write(helpText() + "\n");
+  return 1;
+}
+
+main(process.argv)
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err) => {
+    process.stderr.write(
+      bold("claude-company: unexpected error: ") + (err && err.message) + "\n"
+    );
+    process.exitCode = 1;
+  });

package/company/EXTENDING.md

@@ -0,0 +1,58 @@
+# EXTENDING.md - The module contract
+
+The invariant that keeps a system plug-and-play as it grows:
+
+> **Adding a module never edits existing code.** It adds documentation, a
+> contracts entry, schema additions, owned directories, and registrations.
+
+If adding module N+1 would require editing the app shell, another module, or a
+shared surface, the design is wrong or the change is a CR - stop.
+
+## The narrow waist
+
+Modules interact through a small, explicit set of shared surfaces and nothing
+else. For most projects that means:
+
+1. **The schema** - one source of truth for persistent shapes.
+2. **The contracts** - enums, DTOs, and any state-machine tables encoded as
+   data. Closed vocabularies come from contracts only; a string literal for a
+   status or role fails review.
+3. **The kernel** - the one service that owns cross-cutting mutations (state
+   transitions, money movements, audit writes). A module that hand-rolls its
+   own approve/return/transfer has failed review regardless of whether it works.
+
+These surfaces are built first (Wave 0 of any program), then frozen: read-only
+to module agents, changed only via CR, guarded by the `guard_frozen` hook and
+listed in `company/frozen-surfaces.json`. Modules may REGISTER implementations
+for extension points the kernel declares (guards, jobs, manifest entries); they
+may not add transitions or edit the shell.
+
+## The nine steps to add a module
+
+1. **Specification first.** A module doc from `SPEC-TEMPLATE.md` with FR/BR/OQ
+   IDs. No spec, no build.
+2. **Agent brief.** Derived from the spec via `BRIEF-TEMPLATE.md`; sealed and
+   self-contained.
+3. **Canon deltas via CR.** Any needed schema/contracts/kernel change is filed
+   and applied by the CEO in a dedicated gated PR before the module builds on it.
+4. **Owned directories.** The module gets exactly its own directories (API side
+   and UI side); the ownership map records them. Nothing else is writable.
+5. **Registration, not modification.** The module plugs in via its manifest and
+   self-registration. The shell discovers it.
+6. **Non-negotiables apply.** Every mutation audited and authorized; server-side
+   enforcement is the enforcement; locked data is read-only at the lowest layer
+   you can enforce it.
+7. **Seed the shared world.** All agents develop and test against one canonical
+   seed. Seed changes are CEO-only PRs. No private fixtures for cross-module
+   behavior.
+8. **Gates.** The module's tests join the ladder; its slice extends the
+   golden-path e2e via PR to the CEO.
+9. **Documentation closure.** The module carries a one-page `MODULE.md`
+   (`MODULE-TEMPLATE.md`) in each owned directory, created BEFORE coding and
+   kept current. The docs-librarian syncs any canon the change touched.
+
+## Wayfinding rule
+
+An agent landing anywhere in the tree must be one file away from full context:
+every owned directory carries its `MODULE.md` pointing at spec, brief,
+contracts, owned routes, and seams.

package/company/GATES.md

@@ -0,0 +1,59 @@
+# GATES.md - The gate ladder contract
+
+Every gate here is BLOCKING. A red gate means the work is not done, ever - no
+"works locally", no waivers, no averaging. `company/run-gates.sh` must be fully
+green before any merge, and the `guard_commit` hook blocks `git commit` while
+the stamp in `company/state/gates.status` is red, stale, or missing.
+
+## How gates work mechanically
+
+1. Gates are defined per project in `company/gates.config` (JSON). Each gate is
+   a name plus a shell command; exit 0 is green.
+2. `bash company/run-gates.sh` runs the ladder, prints the table, and stamps
+   the result into `company/state/gates.status` together with a work-tree hash.
+3. The stamp goes stale the moment tracked files change again - a green stamp
+   from before your last edit does not count. Re-run the suite.
+4. Only the runner writes the stamp. The stamp file is on the frozen `always`
+   list; hand-editing it is blocked and logged.
+
+## The recommended ladder
+
+Configure what your project can support today; grow toward the full ladder.
+Order cheap-to-expensive so failures surface fast:
+
+| # | Gate | Proves | Typical command |
+|---|---|---|---|
+| G1 | Boundary / ownership lint | Modules only touch their own directories and the narrow waist | `eslint-plugin-boundaries`, import-linter, or a diff-path check |
+| G2 | Typecheck + lint | The code is well-formed and idiomatic | `tsc --noEmit && eslint .` / `mypy && ruff check` |
+| G3 | Unit + integration tests | Behavior is correct | `npm test` / `pytest` |
+| G4 | Contract conformance | API shapes match the declared contracts | schema-driven supertest / pydantic round-trips |
+| G5 | Golden-path e2e | The pieces actually compose | Playwright journey through the primary user flow |
+| G6 | Requirement traceability | Every FR in the brief is implemented, tested, or explicitly deferred | checklist script against the spec's FR IDs |
+
+Two design rules learned the hard way:
+
+- **Test the negative space.** Where a table of allowed transitions/permissions
+  exists, generate the complement and assert every non-listed case is rejected.
+  Positive-only tests pass while the system silently allows everything.
+- **The composition test is integrator-owned.** Each workstream extends the
+  golden-path e2e via its report/PR; only the CEO merges changes to it. That
+  one test is the proof the workstreams compose.
+
+## Gates and the hierarchy
+
+- Developers run the gates before reporting. Reporting red gates honestly is
+  correct behavior; claiming unverified green is the firing offense.
+- Tech leads re-run the gates on the integrated workstream, never trusting a
+  developer's numbers from an isolated worktree (stale worktree artifacts mask
+  contract drift).
+- The CEO re-runs the gates on main after merge. Trust integrated-main gates
+  over any worktree self-report.
+
+## UI work has a seventh gate: eyes
+
+Backend correctness is mechanical; UI correctness needs eyes. Any task that
+builds or changes a screen is not done until the screen has been driven live
+(Playwright MCP) and captured in four states - loaded, empty, error,
+after-action - and the screenshots are in the report. The QA engineer captures;
+it does not judge. The tech lead and CEO judge the captures against the spec's
+acceptance criteria and the project's design language.