troupe 0.1.0__tar.gz

troupe-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "troupe",
+  "description": "A persistent, governed AI team for Claude Code - named cast, enforced governance hooks, shared decision log, and an autonomous issue watch (Reeve).",
+  "version": "0.1.0",
+  "author": {
+    "name": "Kevin"
+  },
+  "homepage": "https://github.com/KevinIssaDev/troupe",
+  "repository": "https://github.com/KevinIssaDev/troupe",
+  "license": "MIT"
+}

troupe-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.gif binary

troupe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest
+
+  build:
+    name: build & package data
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify wheel contains package data
+        run: uv run --no-project python scripts/check_wheel.py dist

troupe-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Quality gate
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pyright
+          uv run pytest
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Verify wheel contains package data
+        run: uv run python scripts/check_wheel.py dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI Trusted Publishing — no API tokens
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

troupe-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

troupe-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0 (2026-07-06)
+
+Initial release. Reeve's execute path was rehearsed live against a sandbox
+repo before this release: one governed cycle fixed a README typo and
+commented its outcome on the issue for $0.55 of a $2.00 budget.
+
+- `troupe init` — casts a persistent, named AI team (craft-surname pool with
+  role affinities) into `.troupe/` + `.claude/`; idempotent, never overwrites
+  team state
+- Compiled agent definitions in `.claude/agents/` work both as Agent Teams
+  teammate types and as plain subagents (no experimental flag required)
+- Six enforced governance hooks, emitted as self-contained stdlib-only
+  scripts: file-write guard, PII scrub (redact-in-place), decision logger,
+  opt-in human review gate, bounded idle nudge, session context injection
+- `troupe doctor` — setup diagnosis; `troupe upgrade` — refreshes
+  troupe-owned files without touching team state
+- Reeve (`troupe watch`) — autonomous GitHub issue watch: triage-only by
+  default, `--execute` opt-in, turn/budget/wall-clock ceilings per run,
+  per-cycle and per-day cost caps, per-issue failure backoff with human
+  escalation, `reeve-stop` sentinel
+- Claude Code plugin manifest + skill wrapping the CLI
+- CI across Ubuntu/macOS/Windows; PyPI publishing via Trusted Publishing

troupe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

troupe-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: troupe
+Version: 0.1.0
+Summary: A persistent, governed AI team for Claude Code — a named cast of specialists, enforced governance hooks, a shared decision log, and an autonomous issue-triage loop.
+Project-URL: Homepage, https://github.com/KevinIssaDev/troupe
+Project-URL: Repository, https://github.com/KevinIssaDev/troupe
+Project-URL: Changelog, https://github.com/KevinIssaDev/troupe/blob/main/CHANGELOG.md
+Author: Kevin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-teams,ai-agents,claude-code,cli,governance
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# Troupe
+
+**A persistent, governed AI team for Claude Code.**
+
+Troupe gives your repository a named cast of AI specialists — a lead, a backend dev, a frontend dev, a tester — that **live in your repo as files**. They keep their names, charters, and accumulated knowledge across sessions, share an append-only architectural decision log, work under governance rules enforced by real Claude Code hooks (not polite prompt suggestions), and can optionally triage your GitHub issues overnight.
+
+> ⚠️ **Alpha software.** Interfaces may change between releases. Reeve (the autonomous watch) spends real money when you pass `--execute` — read [its safety model](#reeve--the-autonomous-issue-watch) first.
+
+```
+$ uvx troupe init
+
+Cast:
+  Wright     Lead
+  Mason      Backend
+  Webster    Frontend
+  Sawyer     Tester
+Created 24 file(s), left 0 untouched.
+```
+
+## Why Troupe when Agent Teams exists
+
+Claude Code's experimental [Agent Teams](https://code.claude.com/docs/en/agent-teams) already does orchestration well: a team lead, parallel teammates with their own context windows, a shared task list, inter-agent messaging. **Troupe builds none of that.** It fills the gaps that are file-shaped — the things that vanish when the session ends:
+
+| | Agent Teams (native) | Troupe adds |
+|---|---|---|
+| **Team identity** | Session-scoped; teams are named `session-…` and dissolve on exit | A persistent cast with names, charters, and per-member history, committed to the repo |
+| **Rules & memory** | Task list persists per session, holds ephemeral work items | `decisions.md` (append-only decision log) + `directives.md` (standing rules), injected into every session |
+| **Governance** | Permission modes and hook *capability* | Enforced policy content: file-write guard, PII scrub, reviewer lockout, bounded idle nudge — emitted as working hooks |
+| **Unattended work** | — | Reeve: a schedulable issue watch with hard cost/turn/time ceilings |
+
+Compared to its prior art, [Squad](https://github.com/bradygaster/squad) (which pioneered this model for GitHub Copilot CLI): Troupe is Python-native, targets Claude Code, and leans on Agent Teams for all orchestration instead of shipping its own coordinator. Compared to orchestrators like Gas Town or Multiclaude, Troupe doesn't compete on spawn mechanics at all — it's the persistence and governance layer underneath whatever does the orchestrating.
+
+Works with the Agent Teams flag on (cast members become teammate types); degrades gracefully to plain subagents when it's off. Both paths use the same `.claude/agents/` definitions.
+
+## Quick start
+
+Requirements: Python 3.11+, [uv](https://docs.astral.sh/uv/) (or pip), Claude Code. `gh` CLI only if you use Reeve.
+
+```bash
+cd your-project
+uvx troupe init                       # default cast: lead, backend, frontend, tester
+uvx troupe init --roles lead,backend,frontend,tester,security,devops,docs
+git add .troupe .claude && git commit -m "cast the troupe"
+```
+
+Then open Claude Code in the project. The `SessionStart` hook injects the roster, standing rules, and recent decisions into every session automatically. Spawn cast members as subagents (or, with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, as teammates) by their agent type:
+
+```
+Spawn a teammate using the mason agent type to build the API endpoints,
+and sawyer to write tests for them.
+```
+
+Check or repair a setup any time:
+
+```bash
+uvx troupe doctor      # diagnoses scaffold, hooks, wiring, environment
+uvx troupe upgrade     # refreshes troupe-owned files; never touches team state
+```
+
+## What gets created
+
+```
+.troupe/
+├── team.md              # roster
+├── decisions.md         # append-only decision log (auto-fed by hook)
+├── directives.md        # standing rules, edit in place
+├── policy.json          # governance policy: protected paths, PII, gates
+├── config.json · casting-state.json
+└── agents/{name}/
+    ├── charter.md       # role definition — yours to edit
+    └── history.md       # accumulated knowledge — the agent appends
+.claude/
+├── settings.json        # hook wiring (merged non-destructively)
+├── hooks/               # six self-contained governance scripts (stdlib-only)
+└── agents/{name}.md     # compiled definitions: teammate types AND subagents
+```
+
+Commit `.troupe/` and `.claude/`. Anyone who clones gets the team — same names, same knowledge, same rules.
+
+### The cast
+
+Names come from English occupational surnames, chosen so the etymology quietly maps to the role: **Wright** (master builder) leads, **Mason** (foundations) takes backend, **Webster** (weaver — of webs) takes frontend, **Sawyer** (cuts things open) tests, **Ward** (watchman) does security, **Piper** (keeps pipes flowing) does DevOps, **Page** does docs. A 24-name pool with role affinities backs larger casts; names are never reused within a project, even after a member retires.
+
+## Governance — enforced, not suggested
+
+`troupe init` emits six hook scripts into `.claude/hooks/` — self-contained, stdlib-only Python, so they run on any machine with no troupe install on the per-tool-call hot path:
+
+| Hook | Event | What it enforces |
+|---|---|---|
+| File guard | `PreToolUse` | Blocks agent writes to protected paths (casting state, charters, policy itself, hooks, `.env*`, keys) per `policy.json` |
+| PII scrub | `PreToolUse` | Redacts email addresses *in place* before content is written; allowlist for intentional ones |
+| Decision log | `TaskCompleted` | Appends a structured entry to `decisions.md` for every completed task |
+| Review gate | `TaskCompleted` | Opt-in: blocks completion until a human drops a marker in `.troupe/approvals/` — which is itself write-protected, so agents can't self-approve |
+| Idle nudge | `TeammateIdle` | Sends idling teammates back for a final sweep — strictly bounded (2 nudges/agent/session), so no infinite keep-alive |
+| Session context | `SessionStart` | Injects roster + directives + recent decisions into every session |
+
+Policy lives in `.troupe/policy.json` — patterns, allowlists, and toggles are yours to edit; the file guard protects the file itself from agents.
+
+## Reeve — the autonomous issue watch
+
+A *reeve* was the manorial overseer: the one who made sure the estate's work actually got done. Reeve polls GitHub issues labeled `troupe` and, only when explicitly told, dispatches headless Claude Code sessions to work them.
+
+```bash
+uvx troupe watch --once               # one read-only triage cycle (cron-friendly)
+uvx troupe watch                      # poll every 10 min, still read-only
+uvx troupe watch --execute            # actually work issues (costs money)
+```
+
+**Safety model, in order of the walls you'd hit:**
+
+- **Triage-only by default.** No `--execute` → no writes, no agent runs, no cost. Ever.
+- **Reeve itself never writes to GitHub.** Comments happen inside the governed Claude session, under its permission rules (`acceptEdits` + a narrow `gh`/`git`-read allowlist). `--skip-permissions` exists but is refused without `--execute`.
+- **Governance stays on during unattended work.** Runs are non-bare and pass `--settings` explicitly, so the file guard and PII scrub fire exactly when nobody's watching.
+- **Three independent ceilings per run**: `--max-turns` (30), `--max-budget-usd` (native cost cap), and `--timeout-minutes` (30, hard wall-clock kill for hangs).
+- **Two accumulating ceilings**: `--max-cost-per-cycle` ($2) and `--max-cost-per-day` ($10), tracked from the JSON output's `total_cost_usd`.
+- **Per-issue backoff**: a failing issue cools down 2 cycles per failure and escalates to humans after 3 failures (`--reset-backoff` clears the ledger).
+- **Clean shutdown**: `touch .troupe/reeve-stop` — Reeve finishes the cycle and exits. The sentinel is write-protected from agents; only you can stop the overseer.
+
+Run it from cron, a systemd timer, or Task Scheduler with `--once`. **Point it at a throwaway repo first.**
+
+## Upgrading
+
+```bash
+uv tool upgrade troupe   # or: pip install -U troupe
+uvx troupe upgrade       # refresh hook scripts, agent definitions, policy sections
+```
+
+`troupe upgrade` never touches team state (charters, histories, decisions, directives, casting) and never modifies policy keys you've edited — it only adds missing sections.
+
+## Development
+
+```bash
+git clone https://github.com/KevinIssaDev/troupe && cd troupe
+uv sync --dev
+uv run pytest            # 86 tests; gh and claude are stubbed throughout
+uv run ruff check . && uv run pyright
+```
+
+CI runs the suite on Ubuntu, macOS, and Windows (cross-platform is a first-class concern — paths via `pathlib`, subprocess in list form, no shell strings). Releases publish to PyPI via Trusted Publishing on version tags.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Squad (MIT, by [@bradygaster](https://github.com/bradygaster)) is gratefully acknowledged as prior art for the architecture and conventions; Troupe shares no code, name, or cast with it.

troupe-0.1.0/PROJECT-BRIEF.md

@@ -0,0 +1,172 @@
+# Cadre — a persistent, governed AI team for Claude Code
+
+**Status:** pre-implementation planning document
+**Working name:** Cadre (placeholder — rename freely; avoid "Squad"/"Team" for trademark/collision reasons)
+**Author:** Kevin, with Claude (Anthropic) assisting on design
+**Reference implementation (prior art, MIT licensed, Node/TypeScript):** local clone at `E:\squad` — https://github.com/bradygaster/squad
+
+---
+
+## 1. What this is
+
+Cadre gives a Claude Code user a **persistent, named AI team that lives in their repo as files** — a roster of specialists (lead, frontend, backend, tester, etc.) with real names, individual charters, a shared architectural decision log, enforced governance rules, and (optionally) an autonomous loop that triages GitHub issues overnight.
+
+It is a Python-native, PyPI-packaged CLI + hook set for **Claude Code**, directly analogous to what `squad` (bradygaster/squad) built for **GitHub Copilot CLI**.
+
+## 2. What this explicitly is NOT
+
+Do not rebuild multi-agent orchestration. Claude Code already ships this natively as **Agent Teams** (experimental, flag `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`): a team lead, independent teammates each with their own context window, a shared task list, and direct mailbox messaging between agents. There are also at least two existing third-party orchestrators built on top of it (Gas Town, Multiclaude) plus a large cross-harness plugin marketplace (wshobson/agents).
+
+**Non-goals:**
+- Do not write a custom task-list/mailbox/parallel-spawn engine. Use Agent Teams for that.
+- Do not try to out-feature Gas Town/Multiclaude on raw orchestration mechanics.
+- Do not port Squad's Node code line-for-line. Squad is prior art for *architecture and conventions*, not a codebase to translate.
+
+**The actual gap Cadre fills** (confirmed not covered by Agent Teams or the other orchestrators as of this writing):
+1. A **persistent named roster** that survives across sessions *and* across projects (a thematic casting/naming system), rather than anonymous "teammate-1"-style instances.
+2. A **governance layer with real enforcement** — file-write guards, PII scrubbing, reviewer lockout — implemented as actual Claude Code hooks, not just instructions in a prompt.
+3. A **shared decisions/directives log** (`decisions.md`, `directives.md`) that persists architectural choices and permanent team rules across sessions, distinct from the ephemeral task list Agent Teams already provides.
+4. **Ralph** — an autonomous, schedulable loop that polls GitHub issues, builds context, invokes Claude Code headlessly, and applies tiered escalation/backoff — for unattended overnight work.
+
+If, during planning, you find Agent Teams already covers #3 adequately (e.g. its task list already persists per-team at `~/.claude/tasks/{team-name}/` in a way that's good enough), say so and shrink scope rather than building redundant machinery.
+
+## 3. Reference material to study first
+
+Before writing any code, read through `E:\squad` (already added as a working directory) for:
+- `README.md` (root and `dev` branch) — full command surface, `.squad/` directory layout, `squad.config.ts` SDK-first mode
+- `packages/squad-cli` — CLI structure, `init`/`watch`/`doctor`/`upgrade` command implementations
+- `packages/squad-sdk` — hook pipeline design (file-write guards, PII scrubbing, reviewer lockout, event-driven monitoring)
+- `.github/agents/squad.agent.md` (generated by `squad init` if you run it in a scratch dir) — the coordinator persona/governance prompt
+- Docs site content (`bradygaster.github.io/squad` if mirrored, or `docs/` in the repo) — casting system, ceremonies, skills packaging, Ralph's escalation tiers and state backends (`git-notes`, `orphan-branch`)
+
+Treat this as **architectural reference only**. Squad is MIT-licensed so borrowing concepts and even file-naming conventions is fine; do not copy verbatim text/code, and do not reuse Squad's name, mascots, or branding.
+
+Also read current Anthropic documentation before implementing anything hook- or Agent-Teams-related, since this is a fast-moving experimental feature:
+- `https://code.claude.com/docs/en/agent-teams` — Agent Teams architecture, hook events (`TeammateIdle`, `TaskCreated`, `TaskCompleted`), limitations
+- `https://docs.claude.com` and `https://support.claude.com` — hooks reference, skills/plugins packaging, MCP configuration (`.mcp.json`)
+
+Do not assume specifics (minimum model version, exact flag behavior, session-resume support) from memory or from third-party blog posts — verify against the official docs above, since this feature has changed multiple times in recent months.
+
+## 4. Target platform assumptions
+
+- Claude Code, with **Agent Teams** enabled (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`) as the orchestration substrate.
+- Claude Code **hooks** (`.claude/settings.json`) as the enforcement substrate — `PreToolUse`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` at minimum.
+- Claude Code **skills** (`~/.claude/skills/` or project-local) for reusable team knowledge, mirroring Squad's `.copilot/skills/`.
+- Optional: project-scoped MCP config (`.mcp.json`) if a task genuinely needs a stateful tool server rather than a file + hook. Default to files + hooks first; only reach for an MCP server if file-based state proves insufficient during implementation.
+- This is an experimental Claude Code feature. Build with a fallback path in mind: if Agent Teams is unavailable/disabled, Cadre should degrade gracefully to plain Claude Code **subagents** (Task tool) for parallel work, even without teammate-to-teammate messaging.
+
+## 5. Tech stack
+
+- **Language:** Python 3.11+
+- **CLI framework:** Typer (preferred) or Click
+- **Packaging:** `pyproject.toml`, PEP 621 metadata, `hatchling` build backend
+- **Dev workflow / zero-install run:** `uv` — `uvx cadre init` should work with no pre-install, same ergonomics as `npx @bradygaster/squad-cli init`
+- **Templates:** shipped as package data, extracted via `importlib.resources`
+- **GitHub integration (for Ralph):** `PyGithub`, or shelling out to the `gh` CLI — decide during implementation based on which gives cleaner auth handling
+- **Testing:** `pytest`, plus an end-to-end test that runs `cadre init` into a temp dir and asserts the resulting file tree (mirrors Squad's own `doctor` self-check)
+- **Lint/type-check:** `ruff`, `pyright` (or `mypy`)
+- **CI/CD:** GitHub Actions — lint + type-check + test matrix across ubuntu/macos/windows (Squad's own changelog has multiple Windows-escaping bugs — treat cross-platform as a first-class concern, not an afterthought; always use `pathlib` and list-form `subprocess` args, never `shell=True` string concatenation)
+- **Release:** PyPI via **Trusted Publishers** (GitHub Actions OIDC — no long-lived API tokens)
+- **Discoverability inside Claude Code:** a `plugin.json`/manifest at repo root so Cadre is installable through Claude Code's own plugin mechanism, thinly wrapping the same `cadre` CLI commands
+
+## 6. Proposed repo layout (the tool's own source)
+
+```
+cadre/
+├── pyproject.toml
+├── README.md
+├── LICENSE (MIT, matching Squad's license choice)
+├── src/cadre/
+│   ├── cli.py                 # Typer app, subcommand registration
+│   ├── commands/
+│   │   ├── init.py            # scaffolds .cadre/ in target repo
+│   │   ├── watch.py           # Ralph: the polling/triage loop
+│   │   ├── doctor.py          # health check, mirrors `squad doctor`
+│   │   └── upgrade.py         # refreshes templates without touching state
+│   ├── casting/
+│   │   ├── registry.py        # persistent name-pool logic
+│   │   └── names.json         # thematic name pool (own theme, not Squad's)
+│   ├── governance/
+│   │   ├── file_guard.py      # PreToolUse hook: blocked paths/patterns
+│   │   ├── pii_scrub.py       # scans content before write
+│   │   └── reviewer_lockout.py # enforces human-approval gates
+│   ├── decisions/
+│   │   └── log.py             # append/rotate decisions.md, directives.md
+│   ├── ralph/
+│   │   ├── poller.py          # GitHub issue polling
+│   │   ├── context.py         # builds the work-context prompt scaffold
+│   │   ├── runner.py          # headless `claude -p` invocation
+│   │   └── state_backend.py   # in-memory / git-notes / orphan-branch
+│   └── templates/             # package data: charter.md, team.md, etc.
+├── tests/
+└── .github/workflows/ci.yml, release.yml
+```
+
+## 7. Proposed scaffolded output (what `cadre init` creates in a user's project)
+
+```
+.cadre/
+├── team.md            # roster: names, roles
+├── decisions.md        # append-only architectural decision log
+├── directives.md       # permanent team rules
+├── casting-state.json  # this project's assigned names/theme
+├── config.json
+├── agents/
+│   └── <name>/
+│       ├── charter.md  # role definition, expertise, tools
+│       └── history.md  # accumulated knowledge
+└── skills/              # optional reusable knowledge files
+.claude/
+├── settings.json        # wires up hooks (file guard, PII scrub, decision logging)
+└── agents/              # optional subagent fallback definitions
+```
+
+## 8. Governance hooks — mapped to real Claude Code hook events
+
+| Cadre concern | Claude Code hook | Behavior |
+|---|---|---|
+| File-write guard | `PreToolUse` on write-capable tools | Exit non-zero / code 2 to block writes to protected paths |
+| PII scrubbing | `PreToolUse` | Scan content about to be written; block or redact |
+| Reviewer lockout | `TaskCompleted` | Exit code 2 to prevent completion until a human-approval marker is present |
+| Decision logging | `TaskCompleted` | Append a structured entry to `.cadre/decisions.md` |
+| Idle nudge / anti-stall | `TeammateIdle` | Exit code 2 with feedback to keep a teammate working, mirroring Squad's "escalation" ethos |
+
+Verify exact hook payload shapes and exit-code semantics against current docs before implementing — these have changed across Claude Code versions.
+
+## 9. Ralph (autonomous watch loop) — design sketch
+
+- Polls GitHub issues on an interval (configurable), similar to `squad watch --execute --interval N`
+- Builds a "work context" prompt: prioritized issue list + relevant decision-log excerpts, mirroring Squad's context scaffold
+- Invokes Claude Code **headlessly** (`claude -p "<prompt>" --output-format json`) rather than reimplementing an agent loop
+- Tiered escalation/backoff on repeated failures (avoid infinite retry storms against the same issue)
+- Pluggable state backend: start with a simple local state file/SQLite; consider `git-notes` or an orphan branch later if cross-machine durability matters
+- A stop sentinel file (e.g. `.cadre/ralph-stop`) for clean shutdown, mirroring Squad's pattern
+- Should be runnable standalone as a scheduled task/cron/systemd timer/GitHub Action — do not assume the user is watching a terminal
+
+## 10. Suggested build order
+
+1. **M0** — repo scaffolding, `pyproject.toml`, CI skeleton, license, empty `cadre --version`
+2. **M1** — `cadre init`: `.cadre/` + `.claude/` directory generation, charter templates, casting/naming
+3. **M2** — governance hooks: file guard + decision logging (the two with clearest, testable behavior)
+4. **M3** — remaining hooks: PII scrub, reviewer lockout, idle nudge
+5. **M4** — `cadre doctor` health check
+6. **M5** — Ralph: polling loop, headless invocation, one state backend, stop sentinel
+7. **M6** — packaging polish: `uvx` zero-install path, Claude Code plugin manifest, PyPI trusted-publisher release workflow
+8. **M7** — docs (README, quickstart, comparison table vs. Agent Teams/Gas Town/Multiclaude), initial public release
+
+## 11. Open decisions (flag these back to the human, don't guess silently)
+
+- Final project name (avoid collision with Squad, Gas Town, Multiclaude)
+- License (MIT recommended, matching the ecosystem norm and the reference project)
+- Whether Ralph auth uses a GitHub App or a personal access token by default
+- Whether to require Agent Teams' experimental flag as a hard dependency, or ship a subagent-only fallback mode from day one
+- Naming theme for the casting/name pool (pick something distinct from Squad's)
+
+## 12. Definition of done for v1
+
+- `uvx cadre init` scaffolds a working `.cadre/` + `.claude/settings.json` in under 10 seconds
+- At least one governance hook (file guard) demonstrably blocks a disallowed write in a test
+- `decisions.md` accumulates entries automatically after a completed task, without manual prompting
+- Ralph can run one full poll → context-build → headless-invoke → comment-back cycle against a real test repo
+- CI green on ubuntu/macos/windows
+- Published on PyPI, installable and documented for a stranger with no prior context