· Walkthrough & Reference
Documentation

Multi-agent feature waves, without the surprise.

Install one package. Get slash-commands that drive waves, bug fixes, commits, and PR merges — all built around the worktree model.

2Primary skills
2Worktree skills
6Helper skills
v1.11.3Current release
Relevance · As of Fable 5.1

Still relevant under Fable 5.1 — the loop became canon

We re-tested /stx-feature & /stx-fix against the current Claude Code harness and the 2026 agentic-dev field. Verdict: both approaches remain valid — one of them is now first-party doctrine.

  • /stx-fix is first-party canon. Anthropic's best-practices doc now prescribes the same QA → Coder loop: failing test first, Coder locked out of test files, tampering is a hard stop.
  • Its paranoia is measured, not hypothetical. The halt taxonomy (test edited, assertion weakened, SUT mocked) maps 1:1 onto documented reward-hacking, seen at 5–14% on hack-prone coding tasks even in aligned models.
  • /stx-feature's spine is the 2026 mainstream. Spec → gates → verification is what Spec Kit, Kiro, and BMAD all converged on; QA-owned failing-test-first and the read-only fresh-context Reviewer are ahead of the field.
  • Scorecard: 7 of 10 industry norms fully met, 2 partial, 1 gap. The gap is that guardrails live in prose, not hooks.
  • What aged is choreography, not philosophy. Per-task role handoffs, fresh spawns per iteration, and per-iteration full review are the procedural scaffolding the field is deleting; six proposals sit in the drawer, none applied yet.
Read the full study →
01 Walkthrough
Features become Waves of tasks — specialist agents solve them in parallel, behind three approval gates.
Step 1 · Install

You're on main and the skills aren't here yet

A big change is inbound. If this harmless skill set isn't installed in your project, run one line. The installer writes to .claude/skills/ (Claude Code) — or pass --cursor / --both for Cursor. Nothing else in your project moves.

npx github:socitix/stx-skills
# Cursor IDE:
npx github:socitix/stx-skills --cursor
# Both IDEs:
npx github:socitix/stx-skills --both

Re-running is the supported way to pick up updates. Your settings file (.claude/stx-skill-settings.json) is left alone on re-install. See §2 Cursor IDE for transforms and multi-agent behavior.

Step 2 · On main

The launching pad

Start every wave on main. Skills that spawn a worktree refuse to run inside one — main is the launching pad because it's where the wave-starter skills live.

git checkout main

If you're in a stale worktree, cd back to main first. The skill halts with a clear message if you forget.

Step 3 · /stx-feature

One sentence is enough to seed the wave

Type the slash command, describe the feature in plain words. The skill spawns a worktree at .claude/worktrees/<name>/ and runs the Analyst. No production code is touched — just a conversation about what you're building.

/stx-feature Implement multi-delete feature for Admins on Dashboard
Step 4 · Approve

Three cheap moments to redirect

Analyst writes requirement-verse.html, you approve. Architect writes architecture-verse.html, you approve — scope freezes. QA writes failing tests in qa-verse.html, you approve — dry-run boundary reached.

Each gate is your chance to redirect before the expensive Dev wave starts. Catching a misread requirement at Gate 1 costs minutes; catching it after the Dev wave costs hours.

Step 5 · Dev wave

One agent per tier, in parallel

db / service / api / ui — each tier has a specialized Dev agent prompt. Multiple Dev agents run in parallel where their scope_paths don't overlap. QA re-runs every test after each Dev cycle — a Dev calling "green" doesn't end the loop until QA confirms independently.

Iteration caps. Soft 3 per task → Architect re-engages. Hard 5 → wave halts with a handoff doc.

Step 6 · /stx-pr-merge

One chain, ten steps, no babysitting

Run from inside the worktree when all tests are green. It commits, pushes, opens the PR, builds twice (once in the worktree, once after merge), squash-merges, refreshes main. One approval sentence covers the whole chain.

/stx-pr-merge
Step 7 · Cleanup

Worktree gone, main updated

The same skill removes the worktree, deletes the local branch, leaves main rebuilt and clean. The wave artifacts (requirement-verse, architecture-verse, qa-verse, result.html) ride along in the squash commit — so they're preserved in main's history.

Change by running /stx-settings. See §7 Settings.

If a wave halted instead of finishing, run /stx-worktree-report first to write a single HTML report into main's docs/ — that survives worktree removal.

Implement admin multi-delete

Sarah is asked to add multi-row delete to the admin Dashboard. Three calendar days, two skills, one PR.

Day 1 · Monday
$ pwd: /repo · on main
/stx-feature Implement multi-delete feature for Admins on Dashboard
  • Worktree spawned at .claude/worktrees/admin-multi-delete/
  • Analyst → 1 Feature, acceptance criteria
  • Gate 1 ✓ requirement-verse.html
  • Architect → 4 Tasks: db migration · service · API route · UI button
  • Gate 2 ✓ architecture-verse.html · scope frozen
  • QA → 4 failing Playwright tests, one per Task
  • Gate 3 ✓ qa-verse.html · dry-run boundary
  • Sarah stops here. Worktree persists overnight.
Day 2 · Tuesday
$ pwd: /repo/.claude/worktrees/admin-multi-delete
"proceed past dry-run"
  • 4 Dev agents spawn — one per tier (db / service / api / ui)
  • Run in parallel where their scope_paths don't overlap
  • QA re-runs each test after every Dev cycle
  • Two tasks pass on first iteration, one on second, one on third
  • All 4 tests green by end of day
Day 3 · Wednesday
$ pwd: /repo/.claude/worktrees/admin-multi-delete
/stx-pr-merge
  • commit → push → gh pr create
  • Build #1 in feature worktree · pass
  • gh pr merge --squash on PR #42
  • Refresh main with --ff-only
  • Build #2 in main · pass
  • Worktree removed · local branch deleted
  • ✓ main has the feature. Wave artifacts ride along in the squash commit.

The mental model

01

main never holds half-done code

Every in-flight change lives in a worktree under .claude/worktrees/<name>/. main only sees commits that have been merged. Discard a worktree and you lose that work — main is unaffected.

02

Skills know where they belong

Every skill is main-bound, worktree-bound, or any-bound. Run from the wrong checkout, the skill halts. No nested worktrees, no targeting the wrong tree.

Everything else follows:
  • /stx-feature and /stx-fix start on main because they spawn a worktree.
  • /stx-pr-merge and /stx-worktree-report run inside the worktree because that's where the work lives.
  • /stx-checkin, /stx-image, /stx-magazine-report, /stx-help, /stx-help-html are branch-agnostic — they don't care.
  • The settings file lives in main's checkout; each new worktree gets a copy at creation.
02 Cursor IDE
Same skills, two install targets. Source of truth stays Claude-native under the package's .claude/ tree — Cursor installs apply transforms at copy time.
default
npx stx-skills → .claude/skills/ + .claude/agents/ (Claude Code, unchanged)
--cursor
npx stx-skills --cursor → .cursor/skills/ + .cursor/agents/ (transformed for Cursor)
--both
npx stx-skills --both → both trees in one pass (teams using Claude Code and Cursor on the same repo)

Install examples

# From GitHub — Cursor only
cd ~/projects/my-app
npx github:socitix/stx-skills --cursor

# Sibling clone — both IDEs
npx ../stx-skills --both

# Explicit target + one skill
npx ../stx-skills --cursor --skill stx-feature ~/projects/my-app

# Refresh after pulling stx-skills updates
npx ../stx-skills --both

What the installer transforms (--cursor)

Claude sourceCursor installed
.claude/skills/.cursor/skills/ (+ disable-model-invocation: true on slash skills)
.claude/agents/stx-*.md.cursor/agents/stx-*.md (only stx-* personas managed; other agents preserved)
Agent toolTask tool
AskUserQuestionAskQuestion
subagent_type: general-purpose + paste personaTask with named subagent_type: "stx-analyst" etc.
dist/skills/*.js CLI binariesCopied unchanged into skill dirs

Running multi-agent waves in Cursor

/stx-feature and /stx-fix are orchestrator skills — the main Cursor agent reads them and delegates via the Task tool. There is no separate runtime; continuity lives in wave-state.json on disk.

Worktrees: STX vs Cursor native. STX skills create .claude/worktrees/<name>/ and mandate Step 0.5 (cd + branch verify) before any edit — the skill drives behavior, not which IDE folder is open. Cursor's separate /worktree command and Agents Window worktree toggle use Cursor's own checkout manager and .cursor/worktrees.json; they do not integrate with STX today. Do not assume invoking /stx-feature switches the Cursor workspace — the orchestrator must cd and pass absolute paths to subagents.
Sequential (by design)
  • Analyst → Gate → Architect → Gate → QA → Gate
  • Per task: Dev → Reviewer → QA loop
Parallel (when eligible)
  • Up to 3 Dev Tasks in one turn when scope_paths don't overlap
  • Orchestrator must launch multiple Task calls in the same message
Invoke skills in Cursor. Use the / menu or @-mention the skill name (e.g. /stx-feature). Persona contracts live in .cursor/agents/ — the orchestrator spawns them by name, not by pasting inline prompts.

Directory shape (Cursor)

<project>/
├── .cursor/
│   ├── skills/
│   │   ├── stx-feature/
│   │   ├── stx-fix/
│   │   └── ...
│   └── agents/
│       ├── stx-analyst.md
│       ├── stx-architect.md
│       └── ... (10 stx personas)
├── .claude/          ← still used for worktrees + settings
│   ├── worktrees/
│   └── stx-skill-settings.json
└── ...

--link (dev symlink mode) applies to Claude skills only. Cursor installs always copy + transform because paths and APIs differ.

03 Three types of commands
Where you run a skill tells you what it does.
main-bound
You're on main and want to start something. The skill spawns a worktree.
worktree-bound
You're in a worktree doing feature work. The skill operates on it (commit, merge, report, clean).
any-bound
Runs anywhere. Utilities: commit, image audit, docs. Branch-agnostic.
main-bound main
  • /stx-featureinitiate a multi-task wave for big features
  • /stx-fixsingle-bug QA→Coder loop
  • npx stx-skillsinstall / refresh → .claude/
  • npx stx-skills --cursorinstall / refresh → .cursor/
  • npx stx-skills --bothinstall both IDE trees
  • /stx-skill-settingsview/edit settings (planned)
any-bound any
  • /stx-checkincommit + push with security scan
  • /stx-imageaudit / resize project images
  • /stx-magazine-reportmagazine-style HTML report from any source
  • /stx-helpterse text help
  • /stx-help-htmlthis walkthrough
worktree-bound worktree
  • /stx-pr-mergecommit→PR→build→merge→cleanup
  • /stx-worktree-reportHTML report of worktree changes
  • /stx-feature --resumeresume halted wave (planned)
Why types matter. A wave-starter run inside a worktree would nest worktrees inside worktrees. A cleanup skill run from main would target the wrong tree. The type tells the skill where it's allowed to run.
04 Features vs bug fixes
Two flows, two skills. Pick the one that matches the work.
FEATURE WAVE /stx-feature BUG FIX /stx-fix Analyst features & acceptance criteria ▶ Gate 1 Architect tier-tagged tasks · scope_paths ▶ Gate 2 QA failing tests, one per task ▶ Gate 3 Dev wave db / service / api / ui agents done all tasks green 4 agents · 3 gates · N tasks across tiers QA writes failing test repro encoded in code ▶ Approve Coder fixes smallest change to pass QA re-runs test green? done. red? loop. loop ≤ 5× done test green, cap not hit 2 agents · 1 cap · 1 bug (or small cluster)
Left: a feature decomposes into multiple tasks across tiers. Right: a bug stays a single loop with a hard iteration cap.
Feature wave (/stx-feature)Bug fix (/stx-fix)
Agents4 (Analyst, Architect, QA, Dev×N)2 (QA, Coder)
Pre-Dev gates3 (requirement, architecture, qa)1 (prompt acceptance)
Decomposes into1..N Features → 1..N Tasks per Feature1..N symptoms, all in one loop
Tier specializationYes — db / service / api / uiNo
ParallelismUp to N Devs on disjoint scope_pathsSequential
Iteration capsSoft 3 / hard 5 per taskHard 5 total
Artifactswave-state.json + 4 HTML fileshandoff.md (only on halt)
Use whenMulti-task work spanning tiersOne reproducible bug
05 Worktree lifecycle
Create · work · report · discard.
MAIN on main main updated WORKTREE git worktree add squash-merge · refresh Wave work — see §4 for the agent flow Wave work Analyst → Architect → QA → Dev → Report · 3 user gates inside · see §4 for detail stx-skill-settings.json copied from main at creation or discard if halted
A worktree is born on main, lives through four agent phases, then either merges back (success) or is discarded — /stx-worktree-report writes its artifact to main first.

What lives where

LocationContentsSurvives reinstall?
.claude/skills/<name>/Skill source + CLI binary (Claude Code)No — installer wipes & replaces stx-*
.cursor/skills/<name>/Skill source + CLI binary (Cursor, transformed)No — installer wipes & replaces stx-*
.cursor/agents/stx-*.mdPersona contracts for Task toolNo — installer refreshes stx-* only
.claude/stx-skill-settings.jsonProject-wide settingsYes — outside installer sweep
.claude/worktrees/<name>/The feature worktree itselfYes — outside installer sweep
<worktree>/docs/waves/<id>/wave-state.json + 4 HTML artifactsCommitted to feature branch

Directory shape

# After a couple of waves:
<project>/
├── .claude/
│   ├── skills/                   ← Claude Code (default install)
│   ├── stx-skill-settings.json   ← persistent, checked in
│   └── worktrees/
│       ├── wave-admin-multi-delete/
│       └── bugfix-timer-offset/
├── .cursor/                      ← Cursor (--cursor / --both)
│   ├── skills/
│   └── agents/
└── ...
Discarding without losing work. Before git worktree remove on a halted wave, run /stx-worktree-report from inside the worktree — it writes an HTML report to main's docs/ dir, outside the worktree being torn down.
06 Skill catalog
Click any row to expand.
New in v1.10: Help docs are now generated from per-skill catalog.json files via npm run build. Editing card content directly here is overwritten on the next build — change .claude/skills/<name>/catalog.json instead.

v1.9 (previous): The stx-reviewer persona joins the wave loop between Dev hand-back and QA rerun. Reads the Dev's diff, emits a structured verdict (approved, concerns[], or one of three instant-halt verdicts for test-file edits, weakened assertions, or SUT mocking), and writes to wave-state.json.reviewer_verdicts[]. Ten personas across two skills — see AGENTS.md for the full inventory.
F /stx-featureMulti-agent feature wave. Analyst → Architect → QA → Dev with Reviewer gate between Dev and QA. Three approval gates, orchestrator-run interviews (subagents can't reach the user), tier-specialized Devs, suspicious-change tracking, reviewer_verdicts[] trail. Agents write only wave-state.json; every HTML artifact is rendered from it deterministically, so the two can't drift. --autonomous mode auto-approves all gates for unattended runs (never commits). Personas live in .claude/agents/. main-bound v1.11

Drives a multi-agent feature wave. Spawns a worktree, builds a codebase-map.md index once so no agent has to re-walk the repo, interviews the user up front (orchestrator-run — agents that hit a blocking ambiguity hand back an open_questions[] block instead of asking directly), then runs Analyst → Architect → QA in sequence (each behind a user gate unless --autonomous), then dispatches tier-specialized Dev agents under QA control until all tests are green. Each agent gets a brief — the slice of state its role needs — rather than the previous agent's rendered HTML.

Use when
  • Feature decomposes into multiple tasks across tiers
  • You want failing tests written before any code
  • You want a written architecture decision, not freeform
Don't use when
  • It's a single bug → /stx-fix
  • Refactor with no behavior change (no failing test)
  • You're already inside a worktree (main-bound)

Invocations

# Fully interactive
/stx-feature

# Seed initial_request, then interactive
/stx-feature Implement multi-delete feature for Admins on Dashboard

# Autonomous — auto-approve all 3 gates; never commits
/stx-feature --autonomous Implement multi-delete feature for Admins on Dashboard

# Resume a halted wave (planned)
/stx-feature --resume wave-admin-multi-delete-7f3a

Artifacts produced

FileOwnerPurpose
wave-state.jsonAgentsCanonical state and the only file agents write — features, tasks, suspicious[], escalations[], gates[]
codebase-map.mdstx-feature mapIndex of components, routes, services, tests and doc headings — built once per wave
briefs/*.jsonstx-feature briefPer-role slices of state handed to each agent at spawn
requirement-verse.htmlRenderedGate 1 artifact
architecture-verse.htmlRenderedGate 2 — freezes out-of-scope; §3 Revisions derived from escalations[]
qa-verse.htmlRenderedGate 3 — dry-run boundary
result.htmlRenderedEnd-of-wave summary (gates, reviewer verdicts, suspicious changes)
handoff.mdOrchestratorOnly on halt

Iteration caps

  • Soft cap 3 / task — Architect re-engages, may append Revision N to architecture-verse.
  • Hard cap 5 / task — wave halts, handoff.md written.
  • Suspicious-changes 3 / task — auto-halt task (scope-drift, test-file touch, mock-of-SUT, build-break).
  • Autonomous never bypasses reviewer halt verdicts, iteration caps, destructive ops, or commit/PR steps.

Deterministic artifacts

  • Agents write JSON, never HTML. The bundled stx-feature render produces every artifact from wave-state.json, so the HTML cannot say something the state does not.
  • Derived, not stored: Architect Revisions come from escalations[]; reviewer-rejection counts, iteration totals and agent tallies are computed at render time.
  • Validation is a halt condition. stx-feature validate rejects malformed state by field path and the renderer writes nothing.
  • Never hand-edit a rendered artifact — change the state and re-render. Rendering is idempotent.
B /stx-fixTwo-agent QA → Coder loop for a known bug. Failing test first, smallest change to make it pass. Writes a per-fix folder under docs/waves/fix-{slug}/. Personas live in .claude/agents/. main-bound v1.11

QA → Coder loop against one reproducible bug. Interview → render prompt → user acceptance → loop. The Coder cannot edit test files; touching them halts the loop. On close-out, writes a per-fix folder under docs/waves/fix-{slug}/ containing fix-report.html (human-readable summary) and fix-state.json (machine-readable record), plus refreshes the cross-fix index at docs/waves/fix-wiki.html. --no-test runs quick-fix mode: no QA agent, no test authored, no Playwright — the Coder's change is verified by npm run lint + npm run build + the repro, and the report records that the fix ships with no regression test.

Use when
  • Reproducible bug with concrete URL/state/steps
  • You want failing test first, then minimal fix
  • Fix fits one worktree
  • Small obvious fix where a test costs more than the bug → --no-test
Don't use when
  • Multiple acceptance criteria → /stx-feature
  • Spans multiple tiers → /stx-feature
  • You don't have a repro yet

Invocations

# Interactive
/stx-fix

# Pre-supply title
/stx-fix Timer offset wrong after DST

# Autonomous — skip acceptance gate; forces no-commit
/stx-fix --autonomous --from bug.yaml

# Quick fix — no test, no Playwright; lint + build + repro
/stx-fix --no-test Timer offset wrong after DST

# Both — no interview, no acceptance gate, no test
/stx-fix --autonomous --no-test --from bug.yaml

Required interview fields

FieldTypeDefault
titletext—
issuesnumbered list—
reprotext—
expectednumbered listmirrors issues 1:1
test_kindradioplaywright (UI) / vitest-unit (logic) / none (--no-test)
iteration_capnumber5
commit_policyradiocommit-after-green

Artifacts produced (v1.3+)

  • docs/waves/fix-{slug}/fix-report.html — per-fix human-readable report (one folder per fix, slug derived from the bug title)
  • docs/waves/fix-{slug}/fix-state.json — per-fix machine-readable state record (iteration count, halt reason, files touched, test outcomes)
  • docs/waves/fix-wiki.html — cross-fix index page linking every fix-{slug}/ folder, regenerated on each close-out

Halt conditions

  • Coder edits a test file
  • Coder edits an existing test file under --no-test — disabling a test is not a fix
  • Coder weakens or skips an assertion
  • Iteration cap trips (default 5)
  • Lint/build fails for an unrelated reason
  • Neither --autonomous nor --no-test bypasses any halt condition above — --autonomous only skips the acceptance gate and forces no-commit; --no-test only skips test authoring.
C /stx-checkinCommit + push with security scan. Blocks secrets, warns on noise, offers PR on feature branches. any-bound v1.11

A guarded git commit workflow. Scans for secrets, warns on noise, stages, commits with Claude co-authorship, pushes, optionally opens a PR.

Use when
  • Quick commit + push with security guards on
  • Unsure if there's a secret in the staging area
  • Want PR auto-offered on feature branches
Don't use when
  • You want the full merge chain → /stx-pr-merge
  • Just need git push after a manual commit

Invocations

# Interactive
/stx-checkin

# With message
/stx-checkin -m "feat: add login"

# Preview
/stx-checkin --dry-run

# Commit only
/stx-checkin --skip-push

Security scan

PatternAction
.env, .env.*BLOCKED secrets
*.pem, *.key, id_rsaBLOCKED private keys
credentials.json, *adminsdk*.jsonBLOCKED service creds
.DS_Store, *.log, node_modules/WARNED can proceed
files > 10 MBFLAGGED suggest Git LFS
M /stx-pr-mergeFull chain: commit → version bump → push → PR → build → squash-merge → refresh main → tag & push → build → cleanup. Halts on any failure. worktree-bound v1.11

The complete close-out for a feature worktree. Two build gates around the merge. A conservative auto version bump (separate chore(release): commit) rides along between commit and push; the matching vX.Y.Z tag is pushed from main after the squash, so the tag always points at a real shipped commit. Designed to be approved as one chain rather than step-by-step.

Use when
  • Feature branch finished, want one chain to merge & clean up
  • You want hard build-validation around the merge
  • You want the version bumped automatically (conservative patch by default; --bump minor/--bump major to force)
Don't use when
  • Only commit + push needed → /stx-checkin
  • You only need the version bump (no merge) → /stx-version-bump
  • You're on main (skill is worktree-bound)

The chain

#StepHalts if
1Pre-flight (status, branch, remote)On main; dirty unrelated; no remote
2Stage explicit filesFiles don't match described
3Commit (Conventional + co-author)Empty message
3bVersion bump + chore(release): commitpackage.json missing version; tag vX.Y.Z exists; npm unavailable
4git push -uRejected / protected / auth
5gh pr creategh unavailable
6Build #1 (feature worktree)Non-zero exit
7gh pr merge --squashConflicts / checks
8Refresh main --ff-onlyNon-fast-forward
8bTag vX.Y.Z on main + push tagTag exists locally; push fails
9Build #2 (main, post-merge)Non-zero exit
10Remove worktree + branchCleanup failure

Version bump policy (default --bump auto)

Commit subject patternInferred level
feat: / fix: / perf:patch
feat!: / fix!: / BREAKING CHANGE: in bodymajor
chore:/docs:/refactor:/style:/test:/ci:/build:none (silent skip)
Anything elsenone (pass --bump to force)

minor / major are explicit-only

The auto-policy never picks minor or major on its own — pass --bump minor or --bump major when this PR warrants more than a patch. The one exception is the ! / BREAKING CHANGE: marker, which signals major deliberately.

Single chained approval

One sentence covers every named step: "Commit these, bump version, push, open a PR, squash-merge, refresh main, tag and push, clean up the worktree." Failures still halt; unexpected files still need a fresh approval. Pass --no-bump to suppress both the bump and the tag, or --no-tag to keep the bump but defer the tag push.

V /stx-version-bumpStandalone SemVer bump: reads package.json, infers a conservative level from the commit subject, writes a separate chore(release) commit, tags locally. No push. any-bound v1.11

The standalone counterpart to /stx-pr-merge's built-in bump step. Use when you forgot to bump in the last shipped PR, want to override the auto-inference, or are aggregating several feature PRs into a single release commit. Strictly local — push is intentionally left to /stx-pr-merge or a hand-run git push --follow-tags.

Use when
  • Last PR shipped without a bump — make a release commit now
  • Auto picked patch for a feat:, want to bump minor instead
  • Release-PR style: aggregate several merged PRs into one chore(release)
  • Using /stx-checkin (no /stx-pr-merge) and want the bump artifact locally
Don't use when
  • You're running /stx-pr-merge — its STEP 1b already does this
  • Working tree is dirty — release commit must be bump-only
  • You want to push the tag — use /stx-pr-merge or git push --follow-tags

Invocations

# auto-infer level from HEAD commit subject
/stx-version-bump

# explicit level (positional or via flag)
/stx-version-bump minor
/stx-version-bump --bump major

# infer from a non-HEAD commit (e.g. release-PR aggregation)
/stx-version-bump --from-commit HEAD~3

# bump but defer tagging
/stx-version-bump patch --no-tag

# non-Node repo using a plain VERSION file
/stx-version-bump --version-file VERSION

# preview only
/stx-version-bump --dry-run

Auto-inference policy (conservative)

Commit subject patternInferred level
feat: / fix: / perf:patch
feat!: / fix!: / BREAKING CHANGE: in bodymajor
chore: / docs: / refactor: / style: / test: / ci: / build:none (skipped)
Anything elsenone — pass --bump to force

minor / major are explicit-only

The auto-policy never infers minor or major on its own — those require an explicit positional minor/major or --bump minor/--bump major. !/BREAKING CHANGE: markers are the one exception (they signal major deliberately).

Tag is created locally only. Push when you ship — /stx-pr-merge does this automatically at STEP 5b, or run git push origin vX.Y.Z by hand.

Repos that mirror the version

This skill touches only the version source (package.json or --version-file). In a repo that stamps that version into other files — stx-skills mirrors it into every shipped SKILL.md + catalog.json, every persona, and README.md via npm run build — run that build after the bump and amend the stamped files into the release commit, or the docs check fails on the drift. Never hand-edit a version: field.

R /stx-worktree-reportSingle-file HTML report of worktree changes. Exec summary, approach table, Mermaid diagrams, per-file diffs, test results. worktree-bound v1.11

Self-contained *.html under docs/ documenting a worktree's changes. Same shape every time: stats, status pills, approach trade-off table, two Mermaid diagrams, per-file diffs, test output, deferred caveats.

Use when
  • Worktree finished, want a shareable artifact
  • Capture why, not just what
  • Preserve audit trail before discarding a halted worktree
Don't use when
  • One-line fix — git log is enough
  • Diff incomplete (re-run when done)

Invocations

# Infer from cwd
/stx-worktree-report

# Explicit worktree
/stx-worktree-report --worktree .claude/worktrees/wave-admin-multi-delete

# Override defaults
/stx-worktree-report --base develop --title "Replacing the PNG download"

Sections (always the same shape)

  1. Executive summary (2–4 sentences)
  2. Stat cards (files, ± lines, deps, test status)
  3. Status pills (build / lint / tests / commit)
  4. Approach table with rejected options + reasons
  5. Key insight callout (optional)
  6. Two Mermaid diagrams (flowchart + sequence)
  7. Files table + per-file detail with informative hunks
  8. Test results (trimmed runner output)
  9. Deferred caveats
  10. Out of scope
I /stx-imageAudit project images for AI-context-safe sizing. Reports unused & oversized; optional resize via macOS sips. any-bound v1.11

Scans for images, reports which are unreferenced and which exceed Claude Vision's 1568 px / 500 KB thresholds. Default mode makes no changes.

Use when
  • Images bloating context
  • Want a defensible report before cleanup
  • Want to know which assets are unreferenced
Don't use when
  • Not on macOS and don't need analysis (raster dims need sips)
  • Images loaded by constructed strings (false positives in "unused")

Invocations

# Analyze only
/stx-image

# Subfolder
/stx-image --folder public

# Apply (in place via sips)
/stx-image --folder public --apply

# Also delete unused
/stx-image --apply --delete-unused

Thresholds

ThresholdDefaultWhy
File size500 KBClaude Vision resizes large images; bytes beyond this are wasted
Longest edge1568 pxMatches Claude's internal pre-processing cap
Logo/icon target512 pxAlways rendered small
SVG flagged at100 KBUsually embedded rasters — recommend SVGO
M /stx-magazine-reportMagazine-style single-file HTML deliverable from any analytical source. Cover, chapters, severity meters, click-to-expand detail library, four editorial palettes. any-bound v1.11

Content-agnostic generator. Turn any analytical brief — a blood panel, a GTM deck, a 10-K, an interview corpus, a renovation plan — into a printed-magazine-quality HTML file. Cover, TL;DR scorecard, finding cards with severity meters, targets table, action cards with pill badges, click-to-expand detail library, donut/bar charts, and a closing prediction band. Print-friendly, mobile responsive, self-contained.

Use when
  • Deliverable needs editorial polish, not a bulleted summary
  • Non-specialist reader must understand a domain deeply
  • You want a shareable, printable, point-in-time artifact
Don't use when
  • Short answers, code review notes, or one-page summaries (markdown is enough)
  • Operational dashboards that update daily
  • You want a worktree change-log artifact → /stx-worktree-report

Invocations

# Fully interactive — assistant runs the interview
/stx-magazine-report

# Pre-supply the style and locale
/stx-magazine-report --style 2 --locale "Kolkata, India"

# Explicit source + output
/stx-magazine-report --source ./inputs/q3-portfolio.pdf --output ./reports/q3-portfolio.html

Four palettes

StyleRegisterBest for
#1 Navy BlueMcKinsey-meets-MonocleGTM plans, board reports, investment memos, audits
#2 Veew TealWarmer handbookPlaybooks, onboarding, walkthroughs, customer-facing
#3 Crimson MagazineVogue / Cereal / KinfolkHealth, wellness, travel, food
#4 Surprise meClaude picksAnything that doesn't fit the others

Output

Writes a self-contained .html file under the working folder (or topic-named subfolder). Returns the path + a 3-line summary in chat. Never commits.

H /stx-helpTerse text-mode help. Lists every skill grouped by type with one-liners. Ends with a pointer to /stx-help-html. any-bound v1.11

Quick reference, in-terminal. Prints every skill name with a one-liner, grouped by type. Use this when you don't want to leave the terminal.

Invocations

/stx-help

Note

No options. Output ends with a one-line pointer to /stx-help-html for the visual walkthrough.

D /stx-help-htmlOpen this walkthrough doc in your default browser. Visual: diagrams, expandable catalog, examples. any-bound v1.11

Thin shell-out. Runs open .claude/skills/stx-help-html/help.html (or the Cursor copy at .cursor/skills/stx-help-html/help.html when installed with --cursor). The HTML you're reading right now is that file — shipped with the skill, refreshed on every installer run.

Invocations

/stx-help-html

Location

<project>/.claude/skills/stx-help-html/help.html · Cursor: .cursor/skills/stx-help-html/help.html

S /stx-skill-settingsView / edit project skill settings. Real CLI binary that bypasses the LLM. planned —

Project-local CLI plus a thin slash-command wrapper. Reads and writes .claude/stx-skill-settings.json. Bypasses the LLM by shipping as a real Node.js binary.

Status: planned (PR-B). The settings file is read by skills already; the CLI to manage it is the next piece of work.

Invocations (planned)

# Bypass LLM entirely
! .claude/skills/stx-skill-settings/stx-skill-settings.js
! .claude/skills/stx-skill-settings/stx-skill-settings.js --edit
! .claude/skills/stx-skill-settings/stx-skill-settings.js --set story-style-code=true
! .claude/skills/stx-skill-settings/stx-skill-settings.js --reset

# Slash form (LLM in the loop, but trivially)
/stx-skill-settings
07 Settings
One file, checked in by default.
Settings is checked in by default. Lives at .claude/stx-skill-settings.json. Installer does not gitignore it. Project-bound, team-shared if committed — NOT personalized per-user yet (see pending #1).

Shape

{
  "story-style-code": false,
  "stx-feature.default-soft-cap": 3,
  "stx-feature.default-hard-cap": 5,
  "stx-feature.default-suspicious-ceiling": 3,
  "stx-feature.default-max-parallel-devs": 3,
  "stx-feature.default-commit-policy": "commit-after-green",
  "stx-fix.default-max-iter": 5,
  "stx-pr-merge.auto-clean": true
}

Keys

KeyTypeDefaultAffects
story-style-codeboolfalseWhen true, Dev prompts include the story-style code block. When false, lives only in ~/.claude/CLAUDE.md.
stx-feature.default-soft-capint3Iterations per task before Architect re-engages.
stx-feature.default-hard-capint5Absolute ceiling per task; wave halts and writes handoff.md.
stx-feature.default-suspicious-ceilingint3Suspicious events per task before auto-halt.
stx-feature.default-max-parallel-devsint3Max concurrent Dev agents. 1 = sequential.
stx-feature.default-commit-policyenum"commit-after-green"One of no-commit / commit-after-green / commit-and-pr.
stx-fix.default-max-iterint5QA → Coder iteration cap.
stx-pr-merge.auto-cleanbooltrueWhen true, /stx-pr-merge removes the worktree and deletes the local branch after a successful merge. Set false to keep the worktree around for post-merge inspection.

Setting spotlight · auto-clean

stx-pr-merge.auto-clean — default true. Change in .claude/stx-skill-settings.json to keep the worktree around after merge.

Settings pre-fill, they don't bypass. Skills still run their interview — settings change the default answer, not whether the question fires.

Worktrees see a snapshot

The settings file is copied into the worktree at creation (not symlinked). Edits to main's file don't propagate to a worktree already in flight — intentional, the wave runs with the settings it was started with.

08 Pending features
Designed during scenario walkthroughs, not yet shipped.
1

Per-user settings layer

~/.claude/stx-skill-settings.json overrides project values for the current user. Today everyone shares one file.

planned
2

Default-branch detection

Today "on main?" assumes main. Real repos use master, develop, configured names. Need exact-match list + ask-on-ambiguous.

research
3

Stale-CLI version detection

CLI binaries ship with skills. Worktrees branched before a CLI update keep the old version. Ship random version-id; warn on mismatch.

research
4

Halt-path auto-commits artifacts before discard

When a wave halts and the worktree is later removed, artifacts are lost unless committed. Auto-commit at halt time so the branch preserves them.

planned
5

Type-aware installer

Installer should refuse to run inside a worktree. Detect via git rev-parse --git-dir ≠ --git-common-dir.

planned
6

type: frontmatter enforcement

Every SKILL.md gains a type: main | worktree | any field, checked at invocation. --allow-anywhere override flag for the rare deliberate case.

planned
7

Resume for /stx-feature

/stx-feature --resume <wave-id> reads wave-state.json and picks up from saved status. Halts cleanly if the worktree's gone.

planned
8

Settings CLI (/stx-skill-settings)

Real CLI that bypasses the LLM. View / edit / set / reset against the project settings file. Header reminder that settings are checked in.

planned
9

Worktree session switch (Step 0.5)

Shipped in v1.2.1 (/stx-feature) and v1.1.1 (/stx-fix): mandatory cd into .claude/worktrees/<name> after create, branch verify, worktree_path in wave-state.json, Worktree preamble on every subagent. See docs/temp/REQ-worktree-enforcement-and-cursor-integration.md.

shipped