three-pillars

Structured development framework for Claude Code with design-first pipelines, multi-persona deliberation, and session continuity. Includes a
Open source Repository Open in the app JSON README (API)
About

Structured development framework for Claude Code with design-first pipelines, multi-persona deliberation, and session continuity. Includes a full TDD pipeline (design → detailed design → plan → implement → audit), a spike pipeline for hypothesis-driven experiments, a Council of 18 historical thinker personas for complex decisions, and session management for continuity across conversations. 23 skills, 18 agents.
Details

Kind: Plugins
Topic: No topic detected
Publisher: curtisthe
Origin: marketplace
Category: ferramentas
Stars: 4
Forks: 1
Last push: 2026-07-20T04:55:09Z
Repository state: ativo
Language: Python
License: Apache-2.0
Added: 2026-08-30 01:48:58
Updated: 2026-08-30 01:48:58
Origin id: curtisthe/three-pillars-plugin/three-pillars
README

# three-pillars

Three-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.

The 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.

## Install

**Prerequisites**: [Claude Code](https://claude.ai/code) installed on your machine.

Two commands in your terminal:

```bash
claude plugin marketplace add CurtisThe/three-pillars-plugin
claude plugin install three-pillars@three-pillars
```

Restart Claude Code. That's it — 38 skills and 18 council agents are live.

**Verify** by typing `/tp-guide` in any project. If the skill runs, you're set.

## Update

Releases 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.

```bash
claude plugin update three-pillars@three-pillars
```

Restart 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.).

## Uninstall

```bash
claude plugin uninstall three-pillars@three-pillars
claude plugin marketplace remove CurtisThe/three-pillars-plugin
```

Your project's `three-pillars-docs/tp-designs/` directories are **not** removed — those belong to your project, not the plugin.

### Optional extras

Both extras are **optional**. The plugin's core features (skills, agents, session management) work without them.

**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.

**Status line** — a bash script that shows your context-window usage, active design, and git status in Claude Code's status line.

The plugin's shipped `settings.json` already references `~/.claude/statusline.sh`:
```json
"statusLine": { "type": "command", "command": "~/.claude/statusline.sh", "padding": 1 }
```

To enable it, copy the script into place (one-time, manual):
```bash
cp statusline.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh
```

**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.

**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).

**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.

## Why this exists

AI 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.

## What's in this repo

Three layers, one source of truth:

- **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.
- **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.
- **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.

## Runtime prerequisites

The 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.

A few skills shell out to Python helpers that import the `jsonschema` package:

```bash
pip install jsonschema
```

Claude 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.)

## What's been shipped

As 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.

## How it works

**`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.

**Typical flow for a feature:**
```
/tp-design auth-revamp          # Interactive design conversation → design.md
/tp-design-detail auth-revamp   # Concrete modules, interfaces, test boundaries → detailed-design.md
/tp-design-audit auth-revamp    # Council reviews design against codebase — before any code
/tp-plan auth-revamp            # Sequenced tasks with test criteria → plan.md
/tp-plan-audit auth-revamp      # Verify plan traces fully to design — catch gaps and creep
/tp-phase-implement auth-revamp 1  # Red-green-refactor cycles, parallel agents for independent tasks
/tp-phase-review auth-revamp 1     # Review against design; flag regressions
/tp-implementation-audit auth-revamp  # Final audit: does the code match what was designed?
```

**When you're not sure an approach will work**, spike first:
```
/tp-spike websocket-scaling     # Frame hypothesis and success criteria
/tp-spike-auto websocket-scaling  # Autonomous: plan → audit → implement → results
# Review decisions.md the next morning, then:
/tp-spike-learn websocket-scaling   # Feed learnings back into project docs
```

**Context survives across conversations:**
```
/tp-session-save auth-revamp    # Saves working state to handoff.md (gitignored, local-only)
# Close the conversation, switch machines, come back later:
/tp-session-restore auth-revamp # Full continuity — no re-explaining
```

**Collaboration** — works solo, scales to teams:

- **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.
- **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.
- **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.
- **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`.
- **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.

**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.

Lock-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.

### Commits at every phase

Every 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.

## What's included

**38 skills** organized into pipelines:

| Pipeline | Skills | Purpose |
|---|---|---|
| Getting Started | guide, setup, test-setup, migrate | Vision draw-out, project doc scaffolding, test infrastructure, legacy migration |
| TDD Design | design, design-detail, design-audit | Design documents and review |
| TDD Planning | plan, plan-audit | Task sequencing and verification |
| TDD Implementation | phase-implement, task-cycle, phase-review, implementation-audit | Red-green-refactor execution |
| Autonomous | run-full-design, spike-auto | Unattended end-to-end pipeline execution |
| Spike | spike, spike-plan, spike-implement, spike-results, spike-learn | Hypothesis-driven experiments |
| Design Lifecycle | design-learn, design-release, design-complete | Post-implementation synthesis, handoff, and archival |
| Project Docs | docs-init, docs-update | Living documentation maintenance |
| Session | session-save, session-restore, session-clear | Cross-conversation continuity |
| Collaboration | inflight | In-flight design registry |
| Infrastructure | council | Multi-persona deliberation |

**18 council agents** — Aristotle, Feynman, Torvalds, Taleb, Kahneman, Meadows, and others. Used by `/council` for standalone deliberation and automatically by audit skills.

## Skills reference

Most skills take a `{design-name}` as their first argument, corresponding to a directory under `three-pillars-docs/tp-designs/`.

### Getting started

Fresh-project setup follows a deliberate order — **why** before **how**, **how** before **tests**:

| Command | What it does |
|---|---|
| `/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. |
| `/tp-docs-init` | Scaffold `architecture.md`, `product_roadmap.md`, `known_issues.md` from codebase analysis, using the vision as context. |
| `/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. |
| `/tp-guide [intent]` | Read project docs (vision first) and recommend the highest-impact next step. Weighs recommendations against the stated vision. |
| `/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. |

### Design phase

| Command | What it does |
|---|---|
| `/tp-design {name}` | Interactive conversation that produces `design.md` |
| `/tp-design-detail {name}` | Translates `design.md` into `detailed-design.md` — modules, interfaces, test boundaries |
| `/tp-design-audit {name}` | Multi-angle review of the detailed design against the codebase |

### Planning phase

| Command | What it does |
|---|---|
| `/tp-plan {name}` | Generates `plan.md` — sequenced tasks with test criteria, grouped by phase |
| `/tp-plan-audit {name}` | Verifies plan traces fully to both design documents |

### Implementation phase

| Command | What it does |
|---|---|
| `/tp-phase-implement {name} [phase]` | Executes a phase via red-green-refactor cycles |
| `/tp-task-cycle {name} <phase.task>` | Single red-green-refactor cycle for one task |
| `/tp-phase-review {name} [phase]` | Reviews completed phase against design and plan |
| `/tp-implementation-audit {name}` | Final audit — does the code match what was designed? |

### Autonomous orchestration

| Command | What it does |
|---|---|
| `/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 |
| `/tp-spike-auto {name}` | Interactive spike design, then autonomous spike-plan → audit → implement → results chain |

### Spike pipeline

| Command | What it does |
|---|---|
| `/tp-spike {name}` | Frame a hypothesis and success criteria |
| `/tp-spike-plan {name}` | Lightweight experiment plan from the spike design |
| `/tp-spike-implement {name}` | Execute experiments with human review gates |
| `/tp-spike-results {name}` | Capture findings and verdict |
| `/tp-spike-learn {name}` | Synthesize learnings into project docs |

### Design lifecycle

| Command | What it does |
|---|---|
| `/tp-design-learn {name}` | Synthesize a design's impact into project docs |
| `/tp-design-release {name}` | Release your lock without completing — graceful handoff to a teammate |
| `/tp-design-complete {name}` | Archive to `three-pillars-docs/completed-tp-designs/`, commit, and offer a PR back to the base branch |

### Project docs

| Command | What it does |
|---|---|
| `/tp-docs-init` | Scaffold `architecture.md`, `product_roadmap.md`, `known_issues.md` (assumes `three-pillars-docs/vision.md` already exists via `/tp-setup`) |
| `/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. |

### Session management

| Command | What it does |
|---|---|
| `/tp-session-save {name}` | Save context to `handoff.md` for cross-conversation continuity |
| `/tp-session-restore [name]` | Restore context at start of a new conversation |
| `/tp-session-clear {name}` | Clear stale context when switching tasks |

### Collaboration

| Command | What it does |
|---|---|
| `/tp-inflight [--json]` | Show every in-flight `tp/*` design branch across the team — owner, phase, branch age, staleness flag. Read-only, fail-open. |

### Council of High Intelligence

`/council` convenes multi-persona deliberation for complex decisions. 18 reasoning personas analyze problems from independent angles, cross-examine each other, and produce synthesized recommendations.

Modes: full (18 members, 3 rounds), quick (fast 2-round), duo (2-member dialectic), or auto-triad (system picks the best 3).

## Status

**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.

The 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.

## Who maintains this

Curtis ([@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`.

## License

[Apache License 2.0](LICENSE). See [NOTICE](NOTICE) for attribution.

| Component | License | Source |
|---|---|---|
| Council of High Intelligence | MIT | [0xNyk/council-of-high-intelligence](https://github.com/0xNyk/council-of-high-intelligence) |
three-pillars

About

Details

README

More
