# Tierward

A governed, phased process for building with Claude Code: tiered pipelines, STOP gates you approve, audit skills, and a human-approval commit gate. Built on Claude Code primitives.

> **Claude Code-only.** Tierward's enforcement layer (STOP gates, the human-approval commit gate, and audit skills) is built on Claude Code primitives and does not support other AI coding tools. See [why](https://marcoguillermaz.github.io/Tierward/guide/quick-start) in the docs.

```bash
npx tierward init
```

---

## What it does

Claude Code is fast. The gap it creates is not in the code; it is in the review. When an AI agent writes autonomously, decisions accumulate faster than anyone can verify them. Tierward closes that gap by enforcing a review contract directly in the development session, not as a prompt Claude may or may not follow, but as a process it cannot bypass.

You stay the decision-maker. STOP gates stop Claude before implementation: it presents its plan and waits for your explicit approval before writing code. A commit gate then blocks `git commit` until that approval is on record, and, on GitHub plans that support code owners, CODEOWNERS sends every change to `.claude/` to a human reviewer, which blocks the merge when branch protection requires code owner review.

Verification is built in at the same level. The Stop hook is a shell command in `.claude/settings.json`: when Claude tries to declare a task done, it runs your test suite, and if tests fail Claude is sent back to fix them.

## Quick start

```bash
# Add Tierward to an existing project
npx tierward init

# Validate the scaffold
npx tierward doctor

# Check for Anthropic spec drift
npx tierward upgrade --anthropic --dry-run
```

The wizard detects your tech stack and scaffolds the right configuration. Runs in about two minutes.

## Four tiers

Start at the lowest tier that covers your risk. Move up when you need more structure.

| Tier | Pipeline | Best for |
| --- | --- | --- |
| **0 — Discovery** | Stop hook only | First exploration, zero process |
| **S — Fast Lane** | 4 steps, scope-confirm | Solo dev, low-risk fixes |
| **M — Standard** | 13 phases, 3 STOP gates | Feature blocks, 1–2 collaborators |
| **L — Full** | 14 phases, 4 STOP gates | Team projects, complex domain work |

The wizard also asks how changes reach `main`: through a `staging` branch, by a local merge, or by a pull request with no staging branch and no push to `main`.

## What gets scaffolded

- **`CLAUDE.md`** — project context Claude reads at session start (stack, commands, conventions)
- **`.claude/settings.json`** — Stop hook, governance and audit log hooks, a deny list (nothing pre-approved; an existing file keeps your permissions and only gains the hooks)
- **`.claude/rules/pipeline.md`** — the development pipeline Claude follows, phase by phase
- **`.claude/rules/security.md`** — stack-aware security rules (11 stacks supported)
- **`.claude/skills/`** — audit slash-commands: `/arch-audit`, `/security-audit`, `/systematic-debugging`, and more
- **`.github/CODEOWNERS`** — requests human review of `.claude/` changes in public repos, or in private repos on paid GitHub plans; the review is mandatory only with branch protection that requires code owner review
- **`team-settings.json`** (opt-in) — enforce `minTier`, `allowedSkills`, `blockedSkills` across every team clone

## Audit skills

27 executable multi-step programs that run inside Claude Code. Not one-shot prompts: structured workflows with STOP gates, model routing (haiku for mechanical checks, sonnet for analysis), and structured output.

`/security-audit` `/arch-audit` `/doc-audit` `/test-audit` `/accessibility-audit` `/compliance-audit` `/api-contract-audit` `/infra-audit` `/dependency-audit` `/perf-audit` `/visual-audit` `/responsive-audit` `/ux-audit` `/migration-audit` `/pr-review` `/systematic-debugging` `/simplify` and more.

## MCP server

```bash
npx -y --package=tierward tierward-mcp
```

Or install from the MCP registry: `io.github.marcoguillermaz/tierward`

Six read-only tools expose governance state to any MCP-aware client (doctor report, team settings, arch-audit status, skill inventory, package metadata) without the CLI running.

## Supported stacks

Node.js/TypeScript, Node.js/JavaScript, Python, Go, Swift/macOS/iOS, Kotlin/Android, Rust, .NET/C#, Ruby, Java, and a generic fallback.

Stack detection is automatic at init. Security rules, permissions, audit skill configuration, and Stop hook defaults adapt to your stack.

## VS Code extension

Install **Tierward** from the VS Code Marketplace. It adds a Governance view that lists your project's skills and rules, puts doctor health in the status bar, shows doctor findings in the Problems panel, and opens a skill in Claude Code with its slash command already filled in. Everything it shows comes from the `tierward` CLI, which must be on your `PATH`. It doesn't set up the MCP server or the Claude Code plugin.

## Requirements

- Node.js >= 22
- Claude Code CLI

## Documentation

**[marcoguillermaz.github.io/Tierward](https://marcoguillermaz.github.io/Tierward/)** — quick start, tiers, skill reference, configuration.

Source and full changelog: [github.com/marcoguillermaz/Tierward](https://github.com/marcoguillermaz/Tierward)

## License

MIT