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.
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.
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.
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
For a single reproducible bug, use /stx-fix instead. Full reference → /stx-feature in the catalog.
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.
Compare with the bug-fix flow → §4 Features vs bug fixes.
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.
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
Full reference → /stx-pr-merge in the catalog.
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.
More → §5 Worktree lifecycle.
Implement admin multi-delete
Sarah is asked to add multi-row delete to the admin Dashboard. Three calendar days, two skills, one PR.
/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.
"proceed past dry-run"
- 4 Dev agents spawn — one per tier (db / service / api / ui)
- Run in parallel where their
scope_pathsdon'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
/stx-pr-merge
- commit → push →
gh pr create - Build #1 in feature worktree · pass
gh pr merge --squashon 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.
You're on main and the skills aren't here yet
A bug is open. 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.
The launching pad
Start every fix on main. /stx-fix spawns a worktree from main — it refuses to run inside an existing one. main is where the wave-starter skills live.
git checkout main
If you're in a stale worktree, cd back to main first.
Repro first, then describe it
The skill interviews you for the bug — title, issues (numbered), repro URL/steps, expected behavior. It spawns a worktree at .claude/worktrees/<name>/ and renders a complete prompt from a template.
/stx-fix Timer offset wrong after DST
For a multi-task feature, use /stx-feature instead. Full reference → /stx-fix in the catalog.
The test IS the spec
Read the rendered prompt. It includes title, issues (numbered), repro, expected behavior, scope, out-of-scope. Approve, edit a field, or cancel — this is the only pre-Dev gate.
There's no architecture phase because for a bug, the failing test is the architecture. The Coder makes that test pass.
Failing test first, smallest change to make it pass
QA writes the failing test in the right runner (Playwright for UI bugs, Vitest for logic). Coder reads it and makes the smallest change. QA re-runs independently. Green? done. Red? back to Coder.
Hard cap: 5 iterations. Coder MUST NOT edit the test file — touching it halts the loop and escalates.
One chain, ten steps, no babysitting
Run from inside the worktree once the test is 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
Full reference → /stx-pr-merge in the catalog.
Worktree gone, main updated
The same skill removes the worktree, deletes the local branch, leaves main rebuilt and clean. The fix test rides along in the squash commit — so the bug stays caught if it ever returns.
Change by running /stx-settings. See §7 Settings.
More → §5 Worktree lifecycle.
Fix timer offset after DST
Bob is asked to fix a timer that drifts by an hour after daylight saving switches. Two calendar days, two skills, one PR.
/stx-fix Timer offset wrong after DST
- Worktree spawned at
.claude/worktrees/timer-offset-dst/ - Interview: title, issues, repro, expected
- Rendered prompt previewed
- Acceptance gate ✓ approved as-is
- QA writes 1 failing Playwright spec
- Coder iter 1: tweak offset · QA reruns → red (wrong cause)
- Coder iter 2: real fix in DST helper · QA reruns → green
- Day ends with the test green. No merge yet.
/stx-pr-merge
- commit → push →
gh pr create - Build #1 in feature worktree · pass
gh pr merge --squashon PR #58- Refresh main with
--ff-only - Build #2 in main · pass
- Worktree removed · local branch deleted
- ✓ main has the fix. The regression test rides along in the squash commit.
The mental model
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.
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.
/stx-featureand/stx-fixstart on main because they spawn a worktree./stx-pr-mergeand/stx-worktree-reportrun inside the worktree because that's where the work lives./stx-checkin,/stx-image,/stx-magazine-report,/stx-help,/stx-help-htmlare branch-agnostic — they don't care.- The settings file lives in main's checkout; each new worktree gets a copy at creation.
.claude/ tree — Cursor installs apply transforms at copy time.npx stx-skills → .claude/skills/ + .claude/agents/ (Claude Code, unchanged)npx stx-skills --cursor → .cursor/skills/ + .cursor/agents/ (transformed for Cursor)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 source | Cursor 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 tool | Task tool |
| AskUserQuestion | AskQuestion |
| subagent_type: general-purpose + paste persona | Task with named subagent_type: "stx-analyst" etc. |
| dist/skills/*.js CLI binaries | Copied 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.
.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.
- Analyst → Gate → Architect → Gate → QA → Gate
- Per task: Dev → Reviewer → QA loop
- Up to 3 Dev Tasks in one turn when
scope_pathsdon't overlap - Orchestrator must launch multiple Task calls in the same message
/ 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.
- /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)
- /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
- /stx-pr-mergecommit→PR→build→merge→cleanup
- /stx-worktree-reportHTML report of worktree changes
- /stx-feature --resumeresume halted wave (planned)
Feature wave (/stx-feature) | Bug fix (/stx-fix) | |
|---|---|---|
| Agents | 4 (Analyst, Architect, QA, Dev×N) | 2 (QA, Coder) |
| Pre-Dev gates | 3 (requirement, architecture, qa) | 1 (prompt acceptance) |
| Decomposes into | 1..N Features → 1..N Tasks per Feature | 1..N symptoms, all in one loop |
| Tier specialization | Yes — db / service / api / ui | No |
| Parallelism | Up to N Devs on disjoint scope_paths | Sequential |
| Iteration caps | Soft 3 / hard 5 per task | Hard 5 total |
| Artifacts | wave-state.json + 4 HTML files | handoff.md (only on halt) |
| Use when | Multi-task work spanning tiers | One reproducible bug |
What lives where
| Location | Contents | Survives 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-*.md | Persona contracts for Task tool | No — installer refreshes stx-* only |
| .claude/stx-skill-settings.json | Project-wide settings | Yes — outside installer sweep |
| .claude/worktrees/<name>/ | The feature worktree itself | Yes — outside installer sweep |
| <worktree>/docs/waves/<id>/ | wave-state.json + 4 HTML artifacts | Committed 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/ └── ...
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.
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.
- Feature decomposes into multiple tasks across tiers
- You want failing tests written before any code
- You want a written architecture decision, not freeform
- 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
| File | Owner | Purpose |
|---|---|---|
| wave-state.json | Agents | Canonical state and the only file agents write — features, tasks, suspicious[], escalations[], gates[] |
| codebase-map.md | stx-feature map | Index of components, routes, services, tests and doc headings — built once per wave |
| briefs/*.json | stx-feature brief | Per-role slices of state handed to each agent at spawn |
| requirement-verse.html | Rendered | Gate 1 artifact |
| architecture-verse.html | Rendered | Gate 2 — freezes out-of-scope; §3 Revisions derived from escalations[] |
| qa-verse.html | Rendered | Gate 3 — dry-run boundary |
| result.html | Rendered | End-of-wave summary (gates, reviewer verdicts, suspicious changes) |
| handoff.md | Orchestrator | Only 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 renderproduces every artifact fromwave-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 validaterejects 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.
- 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
- 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
| Field | Type | Default |
|---|---|---|
| title | text | — |
| issues | numbered list | — |
| repro | text | — |
| expected | numbered list | mirrors issues 1:1 |
| test_kind | radio | playwright (UI) / vitest-unit (logic) / none (--no-test) |
| iteration_cap | number | 5 |
| commit_policy | radio | commit-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 everyfix-{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
--autonomousnor--no-testbypasses any halt condition above —--autonomousonly skips the acceptance gate and forces no-commit;--no-testonly 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.
- Quick commit + push with security guards on
- Unsure if there's a secret in the staging area
- Want PR auto-offered on feature branches
- You want the full merge chain →
/stx-pr-merge - Just need
git pushafter 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
| Pattern | Action |
|---|---|
| .env, .env.* | BLOCKED secrets |
| *.pem, *.key, id_rsa | BLOCKED private keys |
| credentials.json, *adminsdk*.json | BLOCKED service creds |
| .DS_Store, *.log, node_modules/ | WARNED can proceed |
| files > 10 MB | FLAGGED 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.
- 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 majorto force)
- 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
| # | Step | Halts if |
|---|---|---|
| 1 | Pre-flight (status, branch, remote) | On main; dirty unrelated; no remote |
| 2 | Stage explicit files | Files don't match described |
| 3 | Commit (Conventional + co-author) | Empty message |
| 3b | Version bump + chore(release): commit | package.json missing version; tag vX.Y.Z exists; npm unavailable |
| 4 | git push -u | Rejected / protected / auth |
| 5 | gh pr create | gh unavailable |
| 6 | Build #1 (feature worktree) | Non-zero exit |
| 7 | gh pr merge --squash | Conflicts / checks |
| 8 | Refresh main --ff-only | Non-fast-forward |
| 8b | Tag vX.Y.Z on main + push tag | Tag exists locally; push fails |
| 9 | Build #2 (main, post-merge) | Non-zero exit |
| 10 | Remove worktree + branch | Cleanup failure |
Version bump policy (default --bump auto)
| Commit subject pattern | Inferred level |
|---|---|
feat: / fix: / perf: | patch |
feat!: / fix!: / BREAKING CHANGE: in body | major |
chore:/docs:/refactor:/style:/test:/ci:/build: | none (silent skip) |
| Anything else | none (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.
- 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
- 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-mergeorgit 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 pattern | Inferred level |
|---|---|
feat: / fix: / perf: | patch |
feat!: / fix!: / BREAKING CHANGE: in body | major |
chore: / docs: / refactor: / style: / test: / ci: / build: | none (skipped) |
| Anything else | none — 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).
/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.
- Worktree finished, want a shareable artifact
- Capture why, not just what
- Preserve audit trail before discarding a halted worktree
- One-line fix —
git logis 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)
- Executive summary (2–4 sentences)
- Stat cards (files, ± lines, deps, test status)
- Status pills (build / lint / tests / commit)
- Approach table with rejected options + reasons
- Key insight callout (optional)
- Two Mermaid diagrams (flowchart + sequence)
- Files table + per-file detail with informative hunks
- Test results (trimmed runner output)
- Deferred caveats
- 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.
- Images bloating context
- Want a defensible report before cleanup
- Want to know which assets are unreferenced
- 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
| Threshold | Default | Why |
|---|---|---|
| File size | 500 KB | Claude Vision resizes large images; bytes beyond this are wasted |
| Longest edge | 1568 px | Matches Claude's internal pre-processing cap |
| Logo/icon target | 512 px | Always rendered small |
| SVG flagged at | 100 KB | Usually 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.
- 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
- 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
| Style | Register | Best for |
|---|---|---|
| #1 Navy Blue | McKinsey-meets-Monocle | GTM plans, board reports, investment memos, audits |
| #2 Veew Teal | Warmer handbook | Playbooks, onboarding, walkthroughs, customer-facing |
| #3 Crimson Magazine | Vogue / Cereal / Kinfolk | Health, wellness, travel, food |
| #4 Surprise me | Claude picks | Anything 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.
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
.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
| Key | Type | Default | Affects |
|---|---|---|---|
| story-style-code | bool | false | When true, Dev prompts include the story-style code block. When false, lives only in ~/.claude/CLAUDE.md. |
| stx-feature.default-soft-cap | int | 3 | Iterations per task before Architect re-engages. |
| stx-feature.default-hard-cap | int | 5 | Absolute ceiling per task; wave halts and writes handoff.md. |
| stx-feature.default-suspicious-ceiling | int | 3 | Suspicious events per task before auto-halt. |
| stx-feature.default-max-parallel-devs | int | 3 | Max concurrent Dev agents. 1 = sequential. |
| stx-feature.default-commit-policy | enum | "commit-after-green" | One of no-commit / commit-after-green / commit-and-pr. |
| stx-fix.default-max-iter | int | 5 | QA → Coder iteration cap. |
| stx-pr-merge.auto-clean | bool | true | When 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.
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.
Per-user settings layer
~/.claude/stx-skill-settings.json overrides project values for the current user. Today everyone shares one file.
Default-branch detection
Today "on main?" assumes main. Real repos use master, develop, configured names. Need exact-match list + ask-on-ambiguous.
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.
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.
Type-aware installer
Installer should refuse to run inside a worktree. Detect via git rev-parse --git-dir ≠ --git-common-dir.
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.
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.
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.
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.