claude-company 0.1.0

package/company/state/RESUME.md

@@ -0,0 +1,28 @@
+# RESUME / HANDOFF - read this first
+
+_The restart point. Sessions die; work must not. The CEO updates this after
+every spawn, merge, CR decision, and agent report. If a session died mid-flight,
+check each worktree's git log before respawning - work may be complete on disk
+without a report._
+
+## 1. Program state at handoff
+(nothing yet)
+
+## 2. Next actions, in order
+1. (nothing queued)
+
+## 3. In flight
+| Agent | Task | Worktree | Last known state |
+|---|---|---|---|
+| - | - | - | - |
+
+## 4. Facts every spawn prompt needs
+_The shared-environment cheat sheet: dev commands, ports, seed/reset behavior,
+auth quirks, hook rules. Fill during /company-init or /onboard._
+
+- Gate suite: `bash company/run-gates.sh`
+- Writing must stay hook-clean: straight quotes, ' - ', three dots.
+- (project facts here)
+
+## 5. Done log (chronological, compressed)
+- (empty)

package/company/state/STATUS.md

@@ -0,0 +1,30 @@
+# STATUS - the current-truth board
+
+_Maintained by the CEO. Updated after every dispatch, merge, and CR decision._
+_Red stays red until proven green. Never average a status._
+
+_Last updated: (never) - session 0._
+
+## Active tasks
+
+| Task | Class | Lead/Agent | State | Gates | Notes |
+|---|---|---|---|---|---|
+| - | - | - | - | - | - |
+
+## Wave position (programs only)
+
+| Wave | Workstreams | State | Exit criteria status |
+|---|---|---|---|
+| - | - | - | - |
+
+## Open CRs
+
+_Next free CR number: CR-1._
+
+| CR | Surface | Status | Disposition |
+|---|---|---|---|
+| - | - | - | - |
+
+## Risks / decisions needed (owner-facing)
+
+1. (none)

package/company/state/WORRIES.md

@@ -0,0 +1,12 @@
+# WORRIES - the ledger of the un-acted-on
+
+_Things observed but not yet run down: integration traps, flake sources, spec
+ambiguities, anything that produced a surprise or a false-green. One row per
+worry, brutally terse. Add a row the moment you notice it. Read this at the
+start of every integration or audit step. A row graduates OUT when it becomes a
+filed CR, a STATUS risk, or a verified fix - delete it then. P0 blocks a
+wave/merge; P3 is polish._
+
+| P | Worry | What (one line) | CEO logic (one line) |
+|---|---|---|---|
+| - | - | - | - |

package/company/state/adherence.log

@@ -0,0 +1 @@
+2026-07-06T15:13:06Z | no_slop | BLOCK | tests/hooks/test_hooks.py | slop tells: 2

package/company/templates/BRIEF-TEMPLATE.md

@@ -0,0 +1,69 @@
+# BRIEF: <task-slug>
+
+_Type: quick | feature | program-workstream. Spec: <link or "none (quick)">.
+Lead: <tech-lead | direct-developer>. Date: YYYY-MM-DD._
+
+> Schema, contracts, kernel, shared UI, and anything in
+> `company/frozen-surfaces.json` are FROZEN - consume them exactly as shipped;
+> any change goes through `company/change-requests/`, never a local edit.
+
+A vague brief is the main cause of a bad agent run. The agent reads this plus
+the project's `CLAUDE.md`, nothing of the CEO's context. Make it sealed and
+self-contained.
+
+## Mission
+One paragraph, in the user's terms, naming the observable outcome that means
+success. Include the one hard constraint that must survive contact with reality.
+
+## Read first (in order)
+1. `CLAUDE.md` (project canon)
+2. `company/METHOD.md` (how the team works)
+3. <the specific module docs / source files to study - exact paths>
+
+## You own
+- `<dir>/` ...
+- `<dir>/` ...
+
+Nothing else. Anything not listed is read-only to you. If the fix you need
+lives outside these paths, report it; do not make it.
+
+## Invariants in play (must not break)
+- <the specific project invariants this task brushes against>
+
+## Frozen surfaces nearby (CR, never edit)
+- <which frozen surfaces this task sits close to, and what to do instead>
+
+## Scope (ordered)
+1. <concrete step, citing FR-XX-NN>
+2. ...
+
+## Integration seams
+- <adjacent module/workstream>: you guarantee <X>; you may assume <Y>.
+- For full-stack work: land the API side first; the UI consumes the merged shape.
+
+## Definition of Done
+Universal DoD (every task) plus this task's specifics:
+- [ ] Every FR in scope implemented, tested, or explicitly deferred with reason
+- [ ] `bash company/run-gates.sh` green - run it yourself before reporting
+- [ ] No edits outside owned directories; zero frozen surfaces patched locally
+- [ ] UI work: screen driven live, four states captured (loaded/empty/error/after-action)
+- [ ] Tests added for new behavior (tests are the oracle - never edited to pass)
+- [ ] Commits follow `company/GIT.md`: conventional, `Task: <slug>` trailer,
+      explicit paths staged
+- [ ] `MODULE.md` created/updated in each owned directory
+- [ ] Report follows `company/templates/REPORT-TEMPLATE.md`
+- [ ] <task-specific DoD lines>
+
+## Fallback assumptions
+For every ambiguity, implement THIS stated assumption and tag the site - do not
+guess, do not ask the user:
+- OQ-XX-01: <question> -> FALLBACK: <decision>. Tag `// OQ-XX-01 assumption`.
+
+## Out of scope
+Explicitly, so nobody "helpfully" expands:
+- <thing> (owned by <other workstream / later phase>)
+
+## Report back
+Your report must contain, as facts: what changed (paths), gate results (paste
+the ladder), FR checklist, ownership diff summary, screenshots (UI), CRs filed,
+deviations from this brief and why, worries for the CEO.

package/company/templates/CR-TEMPLATE.md

@@ -0,0 +1,28 @@
+# CR-<n>: <slug>
+
+_Requesting agent/task: <who>. Date: YYYY-MM-DD._
+_Status: PROPOSED | APPROVED | REJECTED | APPLIED_
+
+## Frozen surface affected
+<exact path / registry entry>
+
+## Why (cite the requirement)
+<FR-XX-NN / BR-XX-NN / invariant>. A CR without a concrete citation is rejected
+by default.
+
+## Exact proposed change
+The precise diff or addition. No "something like".
+
+## Blast radius
+Every module/workstream that reads or writes this surface; which agents must
+rebase; which gates re-run.
+
+## Owner sign-off needed?
+yes/no - yes when the surface is on the owner-escalation list (money,
+invariants, determinism/versioning, prod schema).
+
+## Workaround if rejected
+How the requesting task proceeds without this change.
+
+---
+_CEO decision and remarks:_

package/company/templates/MODULE-TEMPLATE.md

@@ -0,0 +1,23 @@
+# MODULE: <name>
+
+_One page max. Copy into every directory you own, fill in BEFORE coding, keep
+current. An agent landing here must be one file away from full context._
+
+| What | Where |
+|---|---|
+| Spec | `company/specs/<spec>.md` |
+| Brief | `company/briefs/brief-<slug>.md` |
+| Contracts | <path to the contracts this module consumes/registers> |
+| Owned routes/surfaces | <routes, jobs, exports> |
+| Registrations | <manifest entries, guard keys, widgets this module registers> |
+
+## What lives here
+- <2-5 bullets>
+
+## Seams
+- Upstream: <what this module assumes from others>
+- Downstream: <what others may assume from this module>
+
+## Changelog notes
+- YYYY-MM-DD <one line per out-of-band fix someone else made here, so the
+  owning agent is not surprised next session>

package/company/templates/OPTIONS-TEMPLATE.md

@@ -0,0 +1,42 @@
+# OPTIONS MEMO: <topic>
+
+_Engagement: <slug>. Author: <role(s)>. Date: YYYY-MM-DD._
+_Patterns used: <categories from company/IDEATION.md>._
+
+Client-facing. One screen if possible. The client reads this to see the
+option space and the reasoning - never to do process work.
+
+## The question
+One sentence: what we are deciding.
+
+## Options
+
+| # | Option | Reasoning (why it could win) | Production risks | Trade-offs |
+|---|---|---|---|---|
+| 1 | ... | ... | ... | ... |
+| 2 | ... | ... | ... | ... |
+| 3 | ... | ... | ... | ... |
+
+(Full divergence - the 8-15 raw directions - lives in the appendix or the
+linked working doc, not here. The memo carries the survivors.)
+
+## Scoring
+
+Criteria (weighted where it matters): client value, production risk, cost to
+build, cost to operate, reversibility.
+
+| # | Value | Prod risk | Build cost | Op cost | Reversible | Verdict |
+|---|---|---|---|---|---|---|
+
+## Recommendation
+
+**Option <n>: <name>.** <2-4 sentences: why it wins, what it costs, the one
+risk we will watch.>
+
+**Strongest rejected option:** #<m> - <one sentence on why it lost>. If this
+option keeps winning arguments during the build, we reopen this memo.
+
+**Decisions that are yours:** <owner-escalation items surfaced by the
+divergence, if any - money, business policy. Otherwise "none".>
+
+> Proceeding on Option <n> unless you object. No action needed to approve.

package/company/templates/REPORT-TEMPLATE.md

@@ -0,0 +1,35 @@
+# REPORT: <task-slug>
+
+_Agent: <role>. Brief: `company/briefs/brief-<slug>.md`. Date: YYYY-MM-DD._
+
+Reports contain facts, not adjectives. "Robust" and "comprehensive" are not
+facts. Never describe unverified work as working.
+
+## What changed
+- <path>: <one line>
+
+## Gate results (paste the ladder, do not summarize)
+```
+<output of bash company/run-gates.sh>
+```
+
+## FR checklist
+- FR-XX-01: implemented + tested (<test path>) | deferred because <reason>
+
+## Ownership
+`git diff --stat <base>..HEAD` summary. Confirm: no paths outside the brief's
+"You own" list. If any, say so plainly.
+
+## Evidence (UI tasks)
+Screenshots: loaded / empty / error / after-action. Paths or embeds. You
+capture; the lead and CEO judge.
+
+## CRs filed
+- CR-<n>: <slug> - status
+
+## Deviations from the brief
+What and why. An empty section means "none", written explicitly.
+
+## Worries for the CEO
+Suspicions, near-misses, false-green risks - anything that belongs in
+`company/state/WORRIES.md`.

package/company/templates/SPEC-TEMPLATE.md

@@ -0,0 +1,69 @@
+# SPEC: <feature name>
+
+_Type: feature | program-module. Author: product-manager. Date: YYYY-MM-DD._
+_Status: DRAFT | SPEC-READY | SHIPPED (move to company/specs/shipped/ when shipped)._
+
+The spec is rich and human-facing; it can be long. The builder agent NEVER
+reads it - it reads the brief derived from it. Reference, do not embed.
+
+## Part 1 - Product requirements
+
+### Problem
+What hurts, for whom, and what it costs today. No solutions here.
+
+### Goal and success metrics
+The observable outcome that means this worked. Binary where possible.
+
+### Users and personas
+Who touches this, with their permissions posture.
+
+### User stories and acceptance criteria
+US-XX-1: As a <persona>, I can <action>, so that <value>.
+  - AC: given/when/then, concrete enough to test.
+
+### Functional requirements
+Stable IDs. Every FR is later implemented, tested, or explicitly deferred - the
+traceability gate checks these IDs against the PR.
+
+- FR-XX-01: ...
+- FR-XX-02: ...
+
+### Business rules and validations
+- BR-XX-01: ... (server-side; client mirrors are UX only)
+
+### Scope
+**In:** ...
+**Out:** ... (be explicit - out-of-scope lines prevent helpful expansion)
+
+### UX notes
+Flows, states (loading/empty/error/ready), microcopy intent.
+
+## Part 2 - Build readiness (the bridge from PRD to buildable)
+
+If a line below cannot be filled, the spec is not ready. That is the point of
+Phase 0: caught before any build tokens are spent.
+
+- **Owned directories:** which dirs the build will create/modify, per workstream.
+- **Invariants in play:** which project invariants this touches.
+- **Frozen surfaces touched:** which, and the CR(s) needed before build.
+- **Data model impact:** tables/columns/migrations, forward-only.
+- **Contracts impact:** new enums/DTOs/transitions (additive? breaking?).
+- **Open questions and chosen fallbacks:**
+  - OQ-XX-01: <question>. FALLBACK: <the single decided default every agent
+    implements, tagged `// OQ-XX-01 assumption` in code>. Owner answers later.
+- **Verification plan:** how each FR will be proven (test, e2e slice, screenshot).
+
+## Spec-ready checklist (the Phase 0 gate)
+
+- [ ] Every FR has a stable ID and at least one acceptance criterion
+- [ ] Out-of-scope is explicit
+- [ ] Every open question has a single decided fallback
+- [ ] Owned directories are named and disjoint from other in-flight work
+- [ ] Frozen-surface needs are identified and CRs filed
+- [ ] Data/contract impact stated (or "none")
+- [ ] Verification plan covers every FR
+
+## Part 3 - Brief handoff
+
+Derive the brief(s) with `company/templates/BRIEF-TEMPLATE.md`. The brief links
+this spec; it does not embed it.

package/docs/customizing.md

@@ -0,0 +1,88 @@
+# Customizing
+
+Everything the company runs on is a plain file in your repo. This guide covers the changes people make most: gates, protected files, process depth, and the team itself. Edit, commit, done; no rebuild step exists.
+
+| I want to... | Edit | Section |
+|---|---|---|
+| Add or change a test gate | `company/gates.config` | [Gates](#add-or-change-gates) |
+| Protect a file from agent edits | `company/frozen-surfaces.json` | [Protect a file](#protect-freeze-a-file) |
+| Give a request more or less process | say it, or `company/METHOD.md` | [Tune process](#tune-how-much-process-a-request-gets) |
+| Change a role's instructions or model | `.claude/agents/<role>.md` | [Change the team](#change-the-team) |
+| Undo a founding default | `company/frozen-surfaces.json`, `CLAUDE.md` | [Founding defaults](#adjust-the-founding-defaults) |
+| Change the enforcement itself | `.claude/hooks/` | [Enforcement](#change-the-enforcement-itself) |
+
+## Add or change gates
+
+Gates live in `company/gates.config`:
+
+```json
+{
+  "gates": [
+    { "name": "lint", "command": "npm run lint", "blocking": true },
+    { "name": "tests", "command": "npm test", "blocking": true }
+  ]
+}
+```
+
+Rules that keep the ladder useful:
+
+- Order cheap to expensive (lint before tests before build) so failures surface fast
+- Every command must exit non-zero on failure, or the gate cannot block anything
+- Add gates you intend to keep. There is no non-blocking mode, because a warnable gate becomes a skippable gate
+
+To rebuild the config from your project automatically, run:
+
+```bash
+python3 .claude/hooks/gates_detect.py --write
+```
+
+It detects package scripts, pytest, Go, Cargo, and Makefiles, and only replaces placeholder entries; gates you wrote by hand are kept.
+
+## Protect (freeze) a file
+
+Add an entry to `company/frozen-surfaces.json`:
+
+```json
+{
+  "surfaces": [
+    { "pattern": "src/db/schema.*", "why": "single source of truth for data shapes", "change_via": "CR" }
+  ]
+}
+```
+
+Patterns match against the file path and its basename. From then on, every agent edit to a matching file is blocked, and the block message points the agent to the change-request process. Good candidates: schemas, shipped migrations, payment code, generated files, and anything with exactly one legitimate writer.
+
+`.env` files, lockfiles, and the gate stamp are protected out of the box.
+
+## Tune how much process a request gets
+
+The CEO sizes each request automatically: `ideation`, `quick`, `feature`, `program`, or `hotfix`. The sizing rules live in `company/METHOD.md` under "Ceremony scales with the task". Two useful overrides:
+
+- Say the class in your request ("treat this as a quick fix") and the CEO will honor it
+- For a production fire, say hotfix. Hooks log instead of block, and the process catches up afterward
+
+If features in your project keep getting more ceremony than they deserve, edit the class table in `METHOD.md`; it is canon, and the agents follow it.
+
+## Change the team
+
+Each role is one markdown file in `.claude/agents/`. The file's frontmatter sets the model and tool access; the body is the role's standing instructions.
+
+- **Adjust a role**: edit its file. Keep instructions short and explain why a rule exists; agents follow reasons better than bare orders.
+- **Add a role**: copy the closest existing file, rename it, and describe when it should be used in the `description` field. The CEO dispatches based on that description.
+- **Change models**: every agent ships with `model: opus`. Your main session (the CEO) uses whatever model you run Claude Code with.
+
+Two roles are load-bearing; change them carefully. `tech-lead` is the only agent allowed to spawn other agents, and `developer` carries the working rules every builder inherits.
+
+## Adjust the founding defaults
+
+During self-onboarding the company freezes migration and schema files, wires detected gates, and records its choices for your veto. If it froze something you need fluid, remove the entry from `frozen-surfaces.json`. If it missed a convention your team cares about, add it to your project's `CLAUDE.md`; every agent reads that file first.
+
+## Change the enforcement itself
+
+The hooks are readable Python in `.claude/hooks/`, wired in `.claude/settings.json`, with tests in `tests/hooks/`. If you change a hook, run the suite:
+
+```bash
+bash tests/hooks/run_tests.sh
+```
+
+One caution: the hooks are the part of the system that keeps the rest honest. Weakening them quietly turns every other promise in this repo back into hope.

package/docs/getting-started.md

@@ -0,0 +1,99 @@
+# Getting started
+
+This guide takes you from install to your first delivered feature. It works for a brand-new project or a codebase you already have. Allow ten minutes, most of it watching the company work.
+
+## Before you start
+
+| You need | Used for |
+|---|---|
+| Claude Code v2.1.172+ | Nested agents (tech leads run their own teams) |
+| Python 3.8+ and git | The enforcement hooks |
+| Node.js with `npx` | Browser testing with screenshots (optional but recommended) |
+
+## Step 1: install
+
+Install the CLI once, then install the company into your project:
+
+```bash
+npm install -g claude-company
+claude-company install /path/to/your/project
+```
+
+`npx claude-company install .` does the same without a global install. If you prefer no npm at all, clone the repo and run `./claude-company/install /path/to/your/project` directly - same installer either way. Add `--yes` for a non-interactive run (CI, scripts).
+
+The installer copies the team, the rules, and the process files into your project. It merges with what you already have: your existing Claude settings, MCP servers, and `CLAUDE.md` are extended, never replaced. Run it again after an update and it refreshes claude-company's own files while leaving your state alone.
+
+After it finishes, your project has three new things:
+
+| Path | What it is |
+|---|---|
+| `.claude/` | The agent team, the commands, and the enforcement hooks |
+| `company/` | The process documents, templates, and state files |
+| `ORCHESTRATOR.md` | The CEO's private runbook |
+
+## Step 2: start the company
+
+Open your project in Claude Code and give the orchestrator your first request:
+
+```text
+/orchestrator build me a REST API for tracking workouts, with user accounts
+```
+
+You do not need to initialize anything first. The company notices it is new here and onboards itself:
+
+```mermaid
+flowchart LR
+    A([first /orchestrator run]) --> B{company files<br>present?}
+    B -->|yes| E[resume from state files]
+    B -->|no| C[study the codebase<br>or found a new one<br>from your request]
+    C --> D[auto-detect test and lint<br>commands as gates<br>+ protect key files]
+    D --> E
+    E --> F([run your request])
+```
+
+You can watch this happen; it reports what it found and what it wired.
+
+## Step 3: watch the pipeline
+
+For a feature-sized request, expect this sequence:
+
+1. The CEO sizes the request and dispatches the product manager.
+2. The product manager explores 8 to 15 directions, then writes a spec with numbered, testable requirements. The spec records which options it considered and why the winner won.
+3. The CEO turns the spec into sealed work orders and spawns a tech lead.
+4. The tech lead runs its own team: developers building in parallel, then a QA engineer that clicks through the running app and captures screenshots of the loaded, empty, error, and after-action states.
+5. The CEO reruns the gates itself, checks the diffs stayed inside their assignments, reads the screenshots, merges, and reports to you.
+
+Small requests skip most of this. A typo fix gets one developer and the gates, nothing more.
+
+## Step 4: read the delivery report
+
+The company interrupts you for two things only:
+
+| Interruption | What you get |
+|---|---|
+| Delivery | What shipped, the evidence (green gates, screenshots), what is next |
+| Your decisions | Anything involving money, deploys, or business policy, batched in `company/state/DECISIONS.md` |
+
+To check on things at any time:
+
+```text
+/standup
+```
+
+You get one screen: done, in flight, blocked, decisions you owe, and current gate status.
+
+## When something gets blocked
+
+Sooner or later you will see a message like this:
+
+```text
+BLOCKED: git commit requires green, fresh gates.
+Fix: run `bash company/run-gates.sh` and repair any failure.
+```
+
+This is the system working. The block message contains the fix, agents get the same messages, and most blocks resolve without you. For a production emergency, tell the orchestrator it is a hotfix: hooks then log instead of block, and the process catches up afterward.
+
+## Where to go next
+
+- [How it works](how-it-works.md) explains the method: why briefs are sealed, why producers never grade their own work, and what the gates actually check
+- [Customizing](customizing.md) covers adding gates, protecting files, and tuning process depth