Tierward MCP Server

Tierward

Claude generates. Your team decides. An open-source scaffold that brings AI-assisted coding into your team — for the product managers and developers who own the outcome — without giving up control of it. MCP-native — read Tierward governance state from Claude Desktop, ChatGPT, Cursor, VS Code.

Claude Code is fast. The gap it creates is not in the code: it is in the review. When AI writes everything autonomously, you end up approving diffs you don't fully understand, catching regressions two blocks later, and losing the thread of what the system actually does.

Tierward closes that gap. Instead of going all-in overnight, teams adopt it tier by tier — from a light discovery setup to a fully governed pipeline — with enforcement baked in from day one: explicit STOP gates before implementation, audit skills that surface issues before they reach production, and a Stop hook that mechanically prevents Claude from declaring done until your tests pass. Start at Tier 0 with zero process, move up when you need it.

Since v1.17.0, Tierward ships an MCP server alongside the CLI. Any MCP-aware client can read your project's doctor report, team-settings policy, last arch-audit, and skill inventory without running the Tierward CLI. See MCP server.

---

Philosophy

One thing drives Tierward: Claude Code doesn't become harder to work with because it gets less capable. It becomes harder to work with because autonomous decisions accumulate faster than anyone can review them. The pipeline enforces a review contract — requirements before code, hypothesis before fix, tests before done — without slowing down work that doesn't need that structure.

The tier system exists because process has a cost. A solo bugfix should not pay the overhead of a team feature workflow. Two pipelines cover the range: Fast Lane (4 steps, scope-confirm) for quick fixes, Full (14 phases, 4 review gates) for team features. Both enforce the same contract — Claude works phase by phase, your team approves each step. Start at the tier that fits your current risk and add more as the stakes rise.

It is built for the people who carry the result — product managers and developers alike — so the decisions stay with them, not the model.

---

How it works

1. Scaffold once. npx tierward init detects your project type and scaffolds a pipeline, audit skills, security rules, and governance files matched to your stack and team size. The whole setup takes under two minutes.

2. Work inside the pipeline. The pipeline is a rules file Claude reads at session start. For Tier M, that means: dependency scan before implementation, STOP gate after requirements, /simplify after writing code. You get the structure without managing it manually.

3. Run audit skills on demand. Skills like /security-audit, /arch-audit, and /systematic-debugging are multi-step programs that run inside Claude Code. Call them when you need them: before a deploy, when a test fails, after a migration wave. Each produces a structured report.

4. Your team decides. STOP gates pause Claude and present findings. CODEOWNERS guards .claude/. The Stop hook enforces test passage mechanically. No autonomous merges.

---

Quick Start

npx tierward init

The wizard detects your project state and guides you through setup. Three paths available:

After init, open Claude Code and start working. The scaffold is active immediately.

Context Builder (v1.27.0)

Run context before init if you want the scaffold to come out the same way every time, with a written record of what you asked for:

npx tierward context                       # produces CONTEXT.md
npx tierward init                          # reads CONTEXT.md, scaffolds with no further prompts
npx tierward context --all                 # one-shot: context then init
npx tierward context --from-yaml file.md   # bypass interview, validate + copy
npx tierward validate-context              # CI gate: exit 0/1 on schema check

CONTEXT.md is a schema-validated project context file. Greenfield runs a PM-friendly interview. Existing repos go through three-phase inference: algorithmic detection, LLM extraction, hybrid PM review. The first question routes you to a PM or developer flow. The developer flow reuses the technical questions from the legacy init wizards (projectName, stack, commands, scaffold options) and auto-derives tier.rationale from team size + work scope, so devs aren't asked to write PM rationale prose.

As of v1.27.0, the schema covers all four pipeline tiers: tier 0 (Discovery) and tier S (Fast Lane) for solo or bugfix work, tier M (Standard) for feature-block work with feature flags (has_api, has_database, has_frontend, has_design_system, has_prd), and tier L (Full) for complex domain projects.

---

What it does

One contract across four tiers — from a solo bugfix to a fully governed team pipeline. Claude proposes, your team approves, at every tier.

Tiered pipelines matched to risk

Start at Tier 0. Move up when you need more structure: npx tierward upgrade --tier=m

26 audit skills

Executable multi-step programs that run inside Claude Code. Not prompt instructions. Structured audit workflows with model routing (haiku for mechanical checks, sonnet for analysis).

Skills are conditionally installed based on your project: hasApi, hasDatabase, hasFrontend, hasDesignSystem.

11 tech stacks auto-detected

Node.js/TS, Node.js/JS, Python, Go, Swift, Kotlin, Rust, .NET, Ruby, Java - plus generic fallback. Security rules, permissions, and CLAUDE.md fields adapt automatically.

MCP server (v1.17.0+)

The tierward package ships an MCP server (tierward-mcp binary) alongside the CLI, version-locked, single npm install -g. Any MCP-aware client (Claude Desktop, ChatGPT desktop, Cursor, VS Code, Copilot Studio) can query Tierward governance state without the Tierward CLI running. Six read-only tools cover doctor report, team-settings, last arch-audit, skill inventory, package metadata, and /pr-review comments. Full reference in the MCP server section below.

Tierward is also available as a Claude Code plugin in the Claude Code marketplace (v1.32.0+). Install from the marketplace to get the Tierward MCP server wired up automatically alongside your Claude Code installation.

Incremental adoption

Install individual components without a full scaffold:

npx tierward add skill security-audit   # install one skill
npx tierward add rule git                # install one rule
npx tierward add rule security --stack swift  # stack-specific variant

Custom skills (custom-* prefix) are preserved across upgrades. See Custom Skills Guide.

---

Architecture

your-project/
├── CLAUDE.md                    # Project context (<200 lines)
├── .claude/
│   ├── settings.json            # Permissions + Stop hook (mechanical enforcement)
│   ├── team-settings.json       # Team policy: minTier / allowed / blocked / required (v1.16+)
│   ├── rules/
│   │   ├── pipeline.md          # Development workflow (tier-appropriate)
│   │   ├── security.md          # Stack-aware: web / apple / android / systems
│   │   ├── git.md               # Commit format, branch rules
│   │   └── output-style.md      # Communication rules
│   ├── skills/                  # Audit skills (conditional per project)
│   ├── session/                 # Session recovery (gitignored)
│   └── .mcp.json                # Wire tierward-mcp into MCP-aware clients (v1.17+)
├── docs/                        # Requirements, specs, backlog (M/L)
├── .github/                     # PR template, CODEOWNERS
└── .pre-commit-config.yaml      # Secret scanning

The Stop hook in settings.json is the core enforcement mechanism. It blocks Claude from completing any task until tests pass. Present in every tier, including Discovery.

---

CLI Commands

npx tierward init                    # scaffold wizard
npx tierward init --dry-run          # preview without writing
npx tierward init --answers file.json  # skip prompts (CI/automation)
npx tierward doctor                  # validate setup (29 checks)
npx tierward doctor --report         # JSON output for CI
npx tierward doctor --ci             # silent, exit 1 on failure
npx tierward upgrade                 # update template files
npx tierward upgrade --tier=m        # promote to higher tier
npx tierward upgrade --anthropic     # show diff for Anthropic-influenced files (dry-run)
npx tierward upgrade --anthropic --apply  # write the diff (with .bak backup)
npx tierward add skill <name>        # install one skill
npx tierward add rule <name>         # install one rule
npx tierward new skill               # create a custom skill (wizard)
tierward-mcp                            # MCP server (stdio); wire from .mcp.json

MCP server

tierward-mcp is a Model Context Protocol server that makes Tierward governance state readable by any MCP-aware client (Claude Desktop, ChatGPT desktop, Cursor, VS Code, Copilot Studio). The CLI and MCP server ship in the same npm package, version-locked.

Wire it up by adding to .mcp.json (project-scoped) or ~/.claude/.mcp.json (user-scoped):

{
  "mcpServers": {
    "tierward": { "command": "tierward-mcp" }
  }
}

Read-only tools exposed:

Note: The legacy cdk_* tool names remain available as deprecated aliases for backwards compatibility.

The server resolves the project root from $TIERWARD_PROJECT_ROOT (or the legacy $CDK_PROJECT_ROOT) if set, otherwise from process.cwd(). v1.17.0 launched read-only by design; that posture is unchanged through v1.33.0.

---

Process controls

Stop hook (every tier) - Claude cannot declare done until tests pass:

"Stop": [{ "hooks": [{ "type": "command",
  "command": "npm test || echo '{\"decision\": \"block\", \"reason\": \"Tests must pass.\"}'"
}] }]

STOP gates (Tier M/L) - Requirements reviewed before implementation. Spec-first or scope-confirm mode auto-selected per block.

Audit logging - Every tool use appended to ~/.claude/audit/project.jsonl.

AI attribution - Every Claude-assisted commit tagged with Co-authored-by.

Weekly arch-audit - SessionStart hook checks if /arch-audit ran in the last 7 days.

CODEOWNERS - Changes to .claude/ require tech lead review.

---

Testing

node packages/cli/test/integration/run.js    # 1170 integration checks
node --test 'packages/cli/test/unit/**/*.test.js'   # 585 unit tests

Covers: file structure per tier, Stop hook presence, pipeline gate counts, placeholder resolution, skill pruning, security variant selection, native stack adaptation, rubric scoring, cross-stack content invariants (10 stacks — the named stacks excluding the other fallback), golden-file assertions (Swift, Node-TS, Python), full CLI execution via --answers fixtures.

A separate template-coverage layer (under packages/cli/test/template-coverage/) hard-fails on cross-tier semantic drift, missing gate clauses, and undocumented placeholders in the shipped templates. The three scripts (cross-tier-lint.mjs, gate-enum.mjs, placeholder-check.mjs) run standalone for local work and automatically inside run.js. Strategy and concept registry: docs/architecture/test-coverage-strategy.md.

---

Requirements

• Node.js >= 22
• Claude Code CLI
• Git

---

Documentation

---

Roadmap

See GitHub Milestones for the 12-month plan.

Current: v1.33.1 adds an output-style language rule (code identifiers, paths, and commands stay verbatim across response languages) and extends doctor validation to tier 0. v1.33.0 adds /systematic-debugging (tier S+): root-cause enforcement with a STOP gate between hypothesis and fix, Red Flags anti-rationalization tables, and pipeline hooks in tier M/L. v1.32.0 ships the Tierward plugin for the Claude Code marketplace and a bootstrap soft hook for plugin-installed projects. v1.31.0 ships the VS Code extension (P1–P3): governance tree view with skill and rule browsing, live health status bar with arch-audit staleness, and Tierward doctor findings surfaced as Problems panel diagnostics. Also adds /skill-security (SkillSpector integration, tier S+), a 64-pattern vulnerability scanner for Claude Code skill files.

Next: /arch-audit MCP-aware once the upstream Anthropic spec MCP server lands. /privacy-audit re-eval (Issue #97 sub-track 3) when AST tracing matures or demand signal materializes. Q2 #3 VitePress docs site (ICE 432) stays on hold.

---

Support

Tierward is open-source, MIT-licensed, and built in the open. If it's useful to your team, here's how to support it:

• ❤️ Sponsor on GitHub — fund ongoing development, recurring or one-time
• ☕ Buy Me a Coffee — one-off support, no account needed
• ⭐ Star the repo — it helps other product and engineering teams discover the project
• 🐛 Open an issue or start a discussion
• 🔧 Send a pull request — see Contributing below

---

Contributing

See CONTRIBUTING.md for development setup, project structure, and PR guidelines.

To report a security issue, see SECURITY.md.

License

MIT

---

Built and maintained by Marco Guillermaz. Distributed on npm as tierward. Discussions and questions: GitHub Discussions.