{
  "markdown": "# three-pillars\n\nThree-pillars is the published canon for design-first AI-assisted development. **One repo, three purposes**: methodology writing (the canon), a [Claude Code](https://claude.ai/code) reference implementation (`skills/` + `agents/`, installable today), and the source for the auto-generated Hermes distribution at `CurtisThe/three-pillars-hermes` (build pipeline planned, see [CHANGELOG.md](CHANGELOG.md)). The methodology is durable; the implementations propagate from it.\n\nThe discipline: design before plan before code, with council-based deliberation and audit gates at every phase. The bet: AI lets you ship code fast — three-pillars makes sure you're shipping the *right* code.\n\n## Install\n\n**Prerequisites**: [Claude Code](https://claude.ai/code) installed on your machine.\n\nTwo commands in your terminal:\n\n```bash\nclaude plugin marketplace add CurtisThe/three-pillars-plugin\nclaude plugin install three-pillars@three-pillars\n```\n\nRestart Claude Code. That's it — 38 skills and 18 council agents are live.\n\n**Verify** by typing `/tp-guide` in any project. If the skill runs, you're set.\n\n## Update\n\nReleases ship new skills, bug fixes, and refinements. Check the [releases page](https://github.com/CurtisThe/three-pillars-plugin/releases) or the top of the commit log to see what's new.\n\n```bash\nclaude plugin update three-pillars@three-pillars\n```\n\nRestart Claude Code after updating so the new skills are loaded. Your existing designs, plans, and session state are untouched — updates only replace the plugin's own files (`skills/`, `agents/`, `CLAUDE.md`, etc.).\n\n## Uninstall\n\n```bash\nclaude plugin uninstall three-pillars@three-pillars\nclaude plugin marketplace remove CurtisThe/three-pillars-plugin\n```\n\nYour project's `three-pillars-docs/tp-designs/` directories are **not** removed — those belong to your project, not the plugin.\n\n### Optional extras\n\nBoth extras are **optional**. The plugin's core features (skills, agents, session management) work without them.\n\n**Framework instructions** — copy `CLAUDE.md` to `~/.claude/CLAUDE.md` for the TDD pipeline methodology guide. Skills work without it, but CLAUDE.md gives Claude persistent context about the framework across all conversations.\n\n**Status line** — a bash script that shows your context-window usage, active design, and git status in Claude Code's status line.\n\nThe plugin's shipped `settings.json` already references `~/.claude/statusline.sh`:\n```json\n\"statusLine\": { \"type\": \"command\", \"command\": \"~/.claude/statusline.sh\", \"padding\": 1 }\n```\n\nTo enable it, copy the script into place (one-time, manual):\n```bash\ncp statusline.sh ~/.claude/statusline.sh\nchmod +x ~/.claude/statusline.sh\n```\n\n**If you skip this step:** nothing breaks. Claude Code will try to run the command, silently fail (file not found), and render an empty status line. No functionality is lost.\n\n**Why `~/.claude/` and not inside the project?** The status line is a user-global Claude Code feature, not per-project. It lives next to your user-wide `settings.json` and applies to every Claude Code session. The `statusline.sh` script itself is read-only: it reads git status, file-existence checks for `.claude/last-design` and `three-pillars-docs/tp-designs/`, and formats the output for your terminal. No network requests. No writes. See `statusline.sh` for the source (it's ~200 lines of bash).\n\n**Reviewer note:** if you're auditing this plugin, the `~/.claude/statusline.sh` path in `settings.json` is a user-scoped external dependency with graceful failure, not a silent install hook. It requires explicit user action to enable.\n\n## Why this exists\n\nAI coding assistants are fast. The bottleneck is no longer writing code — it's writing the *right* code. Three-pillars adds the missing layers: a design-first pipeline that forces clarity before implementation, council-based deliberation that stress-tests decisions from multiple angles, and session continuity that preserves context across conversations and machines.\n\n## What's in this repo\n\nThree layers, one source of truth:\n\n- **The canon (methodology writing)** — this `README.md`, [`CONTRIBUTING.md`](CONTRIBUTING.md), the `CLAUDE.md` framework guide, and the monthly cadence: `METHODOLOGY.md` (planned v1.6.0+), `adoption/` guides, `examples/` worked examples. Vendor-agnostic and host-agnostic — engage the methodology without installing anything.\n- **The Claude Code reference implementation** — `skills/` (37 `tp-*` skills + `/council`, including the autonomous PR-iteration loop `/tp-pr-iterate`/`/tp-pr-fix`) and `agents/` (18 council personas), installable via `claude plugin install`. The patterns the canon describes, made operational for Claude Code adopters.\n- **The Hermes-distribution source** — `scripts/build-hermes-distribution.py` (planned) + a GitHub Action will transform `skills/` into a Hermes-installable skill package at every release tag, force-pushed to `CurtisThe/three-pillars-hermes`. No drift by construction — humans never edit the downstream repo. See [CHANGELOG.md](CHANGELOG.md) for status.\n\n## Runtime prerequisites\n\nThe plugin's core features (skills, agents, session management) work with **Claude Code**, **git**, and **GitHub CLI (`gh`)** on any POSIX shell with **Python 3** available. No extra installs for core skills.\n\nA few skills shell out to Python helpers that import the `jsonschema` package:\n\n```bash\npip install jsonschema\n```\n\nClaude Code plugins don't install Python dependencies, so this is not declared in any manifest — install it so those skills are self-contained. (The `jsonschema` package is used by the tier-return validator and the classifier judge.)\n\n## What's been shipped\n\nAs of v2.2.0, substantive additions include the autonomous PR-iteration loop (`/tp-pr-iterate`, `/tp-pr-fix`) that polls review comments, classifies them, and dispatches one structural-fix commit per round until the review settles. See [CHANGELOG.md](CHANGELOG.md) for the running record.\n\n## How it works\n\n**`three-pillars-docs/vision.md` is the \"why\", design documents are the source of truth, tests are the proof, and audits are the gates.** Nothing ships without being traced back to a design that serves the vision and validated against the codebase. Every skill reads vision first and uses it as the tie-breaker when technical options are equivalent.\n\n**Typical flow for a feature:**\n```\n/tp-design auth-revamp          # Interactive design conversation → design.md\n/tp-design-detail auth-revamp   # Concrete modules, interfaces, test boundaries → detailed-design.md\n/tp-design-audit auth-revamp    # Council reviews design against codebase — before any code\n/tp-plan auth-revamp            # Sequenced tasks with test criteria → plan.md\n/tp-plan-audit auth-revamp      # Verify plan traces fully to design — catch gaps and creep\n/tp-phase-implement auth-revamp 1  # Red-green-refactor cycles, parallel agents for independent tasks\n/tp-phase-review auth-revamp 1     # Review against design; flag regressions\n/tp-implementation-audit auth-revamp  # Final audit: does the code match what was designed?\n```\n\n**When you're not sure an approach will work**, spike first:\n```\n/tp-spike websocket-scaling     # Frame hypothesis and success criteria\n/tp-spike-auto websocket-scaling  # Autonomous: plan → audit → implement → results\n# Review decisions.md the next morning, then:\n/tp-spike-learn websocket-scaling   # Feed learnings back into project docs\n```\n\n**Context survives across conversations:**\n```\n/tp-session-save auth-revamp    # Saves working state to handoff.md (gitignored, local-only)\n# Close the conversation, switch machines, come back later:\n/tp-session-restore auth-revamp # Full continuity — no re-explaining\n```\n\n**Collaboration** — works solo, scales to teams:\n\n- **Branch-per-design**: each design or spike lives on its own branch, `tp/{design-name}`. Skills prompt to create the branch if you start on `main`, and push it to `origin` immediately on creation so teammates see in-flight work without waiting for the first commit.\n- **Advisory lock**: `three-pillars-docs/tp-designs/{name}/lock.json` records who holds the design and on which branch. Committed to git — parallel work produces a merge conflict at PR time, which forces a conversation instead of silently merging divergent implementations.\n- **Takeover**: if the holder abandons the design, the next developer passes `--force-takeover` to claim it; the prior holder is preserved in `previous_owners[]` for history.\n- **Graceful handoff**: the holder can run `/tp-design-release {name}` to step away cleanly — `owner` goes to `null`, and the next person claims the design without needing `--force-takeover`.\n- **Remote-aware**: lock-enforcing skills `git fetch` at the start of each preflight, so they catch teammates' claims that were pushed but not yet pulled locally. Offline-tolerant — the check fails open.\n\n**What the framework handles vs. what you still need**: this framework enforces **ownership** — who currently holds a claimed design and whether a parallel claim is allowed. It does not handle **assignment** — who should be working on what in the first place. That lives in your existing planning tool (Jira, Asana, Linear, GitHub Projects, a whiteboard, Slack). As long as your team coordinates assignments there, the lock here catches accidental overlap and abandoned work without trying to replace the planning system. Aspirational future: hooks or MCP servers could sync lock state with those external tools — out of scope today, but a direction the framework can grow into.\n\nLock-enforcing skills (design, spike, detail, plan, audits, implement, review) refuse to proceed if another developer holds the lock. Read-only skills (`/tp-session-restore`, learn/guide) inspect the lock and warn but never block. See `skills/_shared/collaboration.md` for the full protocol.\n\n### Commits at every phase\n\nEvery skill that produces substantial work commits before returning — design.md, plan.md, per-task code, review.md, audit results, learn updates. One commit per task during `/tp-phase-implement`. Commits are scoped (never `git add -A`), conventionally named (`Design: {name} high-level`, `Plan: {name}`, `Implement: {name} 1.2 — title`, `Learn: {name} design`, etc.), and never include Co-Authored-By trailers. The working tree stays clean between phases. Each commit is pushed to `origin` fail-open — a failed push is logged and never blocks the commit — while opening a PR is still reserved for `/tp-design-complete`. See `skills/_shared/commit-after-work.md` for the full protocol.\n\n## What's included\n\n**38 skills** organized into pipelines:\n\n| Pipeline | Skills | Purpose |\n|---|---|---|\n| Getting Started | guide, setup, test-setup, migrate | Vision draw-out, project doc scaffolding, test infrastructure, legacy migration |\n| TDD Design | design, design-detail, design-audit | Design documents and review |\n| TDD Planning | plan, plan-audit | Task sequencing and verification |\n| TDD Implementation | phase-implement, task-cycle, phase-review, implementation-audit | Red-green-refactor execution |\n| Autonomous | run-full-design, spike-auto | Unattended end-to-end pipeline execution |\n| Spike | spike, spike-plan, spike-implement, spike-results, spike-learn | Hypothesis-driven experiments |\n| Design Lifecycle | design-learn, design-release, design-complete | Post-implementation synthesis, handoff, and archival |\n| Project Docs | docs-init, docs-update | Living documentation maintenance |\n| Session | session-save, session-restore, session-clear | Cross-conversation continuity |\n| Collaboration | inflight | In-flight design registry |\n| Infrastructure | council | Multi-persona deliberation |\n\n**18 council agents** — Aristotle, Feynman, Torvalds, Taleb, Kahneman, Meadows, and others. Used by `/council` for standalone deliberation and automatically by audit skills.\n\n## Skills reference\n\nMost skills take a `{design-name}` as their first argument, corresponding to a directory under `three-pillars-docs/tp-designs/`.\n\n### Getting started\n\nFresh-project setup follows a deliberate order — **why** before **how**, **how** before **tests**:\n\n| Command | What it does |\n|---|---|\n| `/tp-setup` | Conversational draw-out of the project's \"why\" into `three-pillars-docs/vision.md`. Vision only — no test-runner decisions. Run this first on any new project. |\n| `/tp-docs-init` | Scaffold `architecture.md`, `product_roadmap.md`, `known_issues.md` from codebase analysis, using the vision as context. |\n| `/tp-test-setup` | Configure test infrastructure (runner, layout, permissions, starter test) informed by `architecture.md`. Runs *after* docs-init so the test choices are grounded in the documented system structure. |\n| `/tp-guide [intent]` | Read project docs (vision first) and recommend the highest-impact next step. Weighs recommendations against the stated vision. |\n| `/tp-migrate` | Migrates an existing project from the legacy `docs/` + `tdd-*` layout to the current `three-pillars-docs/` + `tp-*` layout. Run once on repos that predate the rename. |\n\n### Design phase\n\n| Command | What it does |\n|---|---|\n| `/tp-design {name}` | Interactive conversation that produces `design.md` |\n| `/tp-design-detail {name}` | Translates `design.md` into `detailed-design.md` — modules, interfaces, test boundaries |\n| `/tp-design-audit {name}` | Multi-angle review of the detailed design against the codebase |\n\n### Planning phase\n\n| Command | What it does |\n|---|---|\n| `/tp-plan {name}` | Generates `plan.md` — sequenced tasks with test criteria, grouped by phase |\n| `/tp-plan-audit {name}` | Verifies plan traces fully to both design documents |\n\n### Implementation phase\n\n| Command | What it does |\n|---|---|\n| `/tp-phase-implement {name} [phase]` | Executes a phase via red-green-refactor cycles |\n| `/tp-task-cycle {name} <phase.task>` | Single red-green-refactor cycle for one task |\n| `/tp-phase-review {name} [phase]` | Reviews completed phase against design and plan |\n| `/tp-implementation-audit {name}` | Final audit — does the code match what was designed? |\n\n### Autonomous orchestration\n\n| Command | What it does |\n|---|---|\n| `/tp-run-full-design {name}` | Drives the full TDD pipeline unattended — design → detail → plan → implement → audits → PR — logging every decision to `decisions.md` for morning review |\n| `/tp-spike-auto {name}` | Interactive spike design, then autonomous spike-plan → audit → implement → results chain |\n\n### Spike pipeline\n\n| Command | What it does |\n|---|---|\n| `/tp-spike {name}` | Frame a hypothesis and success criteria |\n| `/tp-spike-plan {name}` | Lightweight experiment plan from the spike design |\n| `/tp-spike-implement {name}` | Execute experiments with human review gates |\n| `/tp-spike-results {name}` | Capture findings and verdict |\n| `/tp-spike-learn {name}` | Synthesize learnings into project docs |\n\n### Design lifecycle\n\n| Command | What it does |\n|---|---|\n| `/tp-design-learn {name}` | Synthesize a design's impact into project docs |\n| `/tp-design-release {name}` | Release your lock without completing — graceful handoff to a teammate |\n| `/tp-design-complete {name}` | Archive to `three-pillars-docs/completed-tp-designs/`, commit, and offer a PR back to the base branch |\n\n### Project docs\n\n| Command | What it does |\n|---|---|\n| `/tp-docs-init` | Scaffold `architecture.md`, `product_roadmap.md`, `known_issues.md` (assumes `three-pillars-docs/vision.md` already exists via `/tp-setup`) |\n| `/tp-docs-update [vision\\|architecture\\|roadmap\\|known-issues]` | Targeted updates after a milestone. Vision updates follow a sticky-vision protocol — do not drift the vision to match implementation. |\n\n### Session management\n\n| Command | What it does |\n|---|---|\n| `/tp-session-save {name}` | Save context to `handoff.md` for cross-conversation continuity |\n| `/tp-session-restore [name]` | Restore context at start of a new conversation |\n| `/tp-session-clear {name}` | Clear stale context when switching tasks |\n\n### Collaboration\n\n| Command | What it does |\n|---|---|\n| `/tp-inflight [--json]` | Show every in-flight `tp/*` design branch across the team — owner, phase, branch age, staleness flag. Read-only, fail-open. |\n\n### Council of High Intelligence\n\n`/council` convenes multi-persona deliberation for complex decisions. 18 reasoning personas analyze problems from independent angles, cross-examine each other, and produce synthesized recommendations.\n\nModes: full (18 members, 3 rounds), quick (fast 2-round), duo (2-member dialectic), or auto-triad (system picks the best 3).\n\n## Status\n\n**Actively maintained.** New patterns land monthly per the cadence above; smaller fixes (typos, broken links, refinements) land between releases. Cadence is monthly because methodology content isn't best produced weekly and quarterly looks abandoned. See [CHANGELOG.md](CHANGELOG.md) for the running record.\n\nThe Claude Code reference implementation (`skills/` + `agents/`) is in production use — install it, run `/tp-guide`, ship designs. The Hermes-distribution build pipeline ships in a near-term release; until then, Hermes adopters can hand-port the methodology from this canon.\n\n## Who maintains this\n\nCurtis ([@CurtisThe](https://github.com/CurtisThe)) — practitioner working on AI agent discipline in production engineering contexts. Contributions welcome per [CONTRIBUTING.md](CONTRIBUTING.md); for substantive proposals, open an issue first so we can align on `three-pillars-docs/vision.md`.\n\n## License\n\n[Apache License 2.0](LICENSE). See [NOTICE](NOTICE) for attribution.\n\n| Component | License | Source |\n|---|---|---|\n| Council of High Intelligence | MIT | [0xNyk/council-of-high-intelligence](https://github.com/0xNyk/council-of-high-intelligence) |\n",
  "bytes": 17701,
  "sha": "1c5e437d79a0ae46b06d4e5ea84cf7d823b2c7898ecf9dca8040af1c678337f9",
  "repo_slug": "curtisthe/three-pillars-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_curtisthe_three_pillars_plugin_three_pil_20294315/readme"
}