Getting Started
In one line: Install Superpowers, run setup/bootstrap.sh, read the operating card — then adopt Core gates first, Recommended as value shows, Project-specific only with an ADR.
This section is the entry point for adopting the methodology. The full onboarding is in the setup guide; this is orientation.
Installer: setup/bootstrap.sh <project-root> in the s4u-methodology repository — non-interactive. It upgrades kit-owned files you have not edited, writes <file>.s4u-new beside any you have, and never touches CLAUDE.md or .claude/settings.json. --dry-run prints the plan without writing. (Link omitted from synced docs since the kit lives outside the consuming repo's tree.)
Quick Start (3 Steps):
For developers who want to evaluate the methodology before committing to full setup:
- Install the Superpowers plugin:
claude plugins install superpowers@superpowers-marketplace - Run
setup/bootstrap.sh <your-project-root>from this repo — it installs the corrected hooks (diff-aware Stop verification, lint-on-edit, pre-push gate, memory budget), the reviewer agents, the s4u skills, and the operating card. - Read the operating card (
docs/operating-card.md) — it is the byte-budgeted rule surface (enforced cap in bytes viascripts/context-budgets.tsv, measured bywc -c; roughly 5K tokens); this document is rationale and reference.
Adoption Tiers:
The Core tier is where the §7 gate-admission rule applies to the methodology itself: "a gate that cannot name its mechanism is a wish." Core is therefore split in two, and each item carries the three fields that rule demands — cost, mechanism, retirement condition. Core-mechanized items hold without anyone remembering them. Core-asserted items are equally non-negotiable and equally load-bearing, but nothing detects a violation: the human is the mechanism. Reading them as equivalent is the exact claim-vs-check error the methodology exists to catch, so they are not written in one row. Core-asserted is a debt register, not a comfort: each row's retirement condition names the mechanism that would move it up.
The colour difference is the whole point. Both columns are non-negotiable;
only one of them is protected. Writing them as a single "Core" row would
claim eight enforced rules where four are enforced and four rely on a person
being awake — the claim-vs-check error, committed by the document that names
it. Core-asserted is a debt register with a stated exit, not a comfortable
synonym for "we take this seriously."
Core-mechanized — a named mechanism detects the violation:
| Component | Per-occurrence cost | Enforcement mechanism | Retirement condition |
|---|---|---|---|
Required CI status checks on the default branch: full test suite (never -x first-failure abort), full lint (ruff check + ruff format --check, not rule subsets) | CI minutes per push | templates/workflows/pr-review.yml (the gates job), equalled locally by templates/hooks/pre-push-gate.sh; made blocking by repo-config: branch protection (required status checks) | Never — this is the floor the other gates stand on |
| CODEOWNERS-backed human review on safety paths | One reviewer per safety-path PR | repo-config: CODEOWNERS + repo-config: branch protection (required review) | Never for safety paths; narrow the path set as surfaces are retired |
| Where the product has a user-facing safety surface: a deterministic safety-floor eval subset as a required check | Eval runtime per PR (seconds-minutes) | repo-config: required status check over the project's eval subset (the project supplies the subset; the kit ships no eval harness) | When the safety surface is removed from the product |
| The single-source rule (Section 4.5) | Seconds per CI run | scripts/check-single-source.sh — greps a project's CLAUDE.md/AGENTS.md for verbatim canon rule text and fails on a copy that carries no deviation ADR | When project instruction files are generated from canon rather than authored |
Core-asserted — non-negotiable, but no mechanism detects a violation; enforcement is a human noticing:
| Component | Per-occurrence cost | Enforcement mechanism | Retirement condition |
|---|---|---|---|
| The Brainstorm Gate including the safety-policy trigger (Section 3.1) | 30-60 min per triggered change | none (human-asserted) — a missing Pre-Mortem Block is visible to the human in real time (§3.1), which is a person noticing an absence, not a detector | A hook that fails a branch whose diff fires a trigger and whose design artifact carries no Pre-Mortem Block |
| Silent-failure discipline R1-R3 (defined on the operating card, "Silent-failure discipline (R1–R3)") | Minutes per collection-returning function / silent branch | none (human-asserted) — R2's regression pin is visible in the diff, but nothing asserts it was shipped | A lint rule for R1; a review gate that fails a silent-failure branch landing without a paired test |
| Worktree isolation for agent work | Seconds per task (worktree create/remove) | none (human-asserted) | A pre-commit hook that refuses an agent-authored commit made outside a worktree |
| The testing standard: no-mocking default, migrated-schema oracle, live contract smoke | Testcontainer startup per suite; cents per live smoke | none (human-asserted) — the MOCK APPROVED comment and the reviewer-agent checklists make an unapproved mock visible at review, but no gate greps for create_all, a bare mock, or a missing live smoke | A CI grep for ORM create_all in test setup and for mocks lacking a MOCK APPROVED block |
Recommended and Project-specific:
| Tier | Components | Value Provided |
|---|---|---|
| Recommended (strongly advised) | Reviewer agent definitions, memory discipline (Section 6), the kit hook templates, generated STATE.md, the consolidation census cadence (Section 2.8) | Development velocity and quality — proven valuable but divergence does not break integration |
| Project-specific (adopt with an ADR) | Domain compliance architectures (row-level security, regulatory patterns — see the case studies in docs/showcase.md), a Docusaurus living-doc site, MCP server integrations | Powerful where the domain demands them; cargo-culting them into a project that doesn't is pure process weight |
The split itself is mechanized: scripts/check-tier-mechanisms.sh parses these two tables and fails if a Core-mechanized row names no resolvable mechanism, if a Core-asserted row silently claims one, or if any mechanism path named here does not exist in the repo. That is what stops this table drifting back into a single row of confident prose.
Permission mode is a security control, not a preference. Promptless agent action (dontAsk and equivalents) against anything that can reach production is a team-level decision with a stated default: plan mode or ask-permission for production-touching commands. Treating this as personal preference while treating a compliance architecture as "non-negotiable" inverts the priorities for any safety-critical system.
The tier classification allows incremental adoption: start with Core (the mechanized half is mostly one-time configuration — branch protection, CI flags, CODEOWNERS), add Recommended as value becomes apparent, and adopt Project-specific components only with a deviation ADR explaining why the domain needs them.