Workflow kit
nexus-workflows is the kit of commands, skills and helpers that bwn draws its bundled workflow commands from. It is Markdown and standard-library Python: 48 slash commands, 10 skills, 4 read-only helpers, and hook scripts that guard the shell and file writes. Type /test, /review or /security-review with nothing after it and the command does the rest.
How the commands behave
- They work with no arguments. A bare command finds its scope in the repo: the working diff, then the branch against main, then the last commit, then a failing test. It says which one it picked, in one line.
- They ask only what the repo can't answer. Intent, a trade-off you would care about, or anything irreversible or outward-facing: deleting, pushing, publishing, spending. Never a fact it could read or run. One question at a time, with a recommended answer.
- They carry judgment, not a script. Each command says what an experienced engineer watches for.
/reviewasks whether a test would fail if the change were reverted./debugbisects instead of guessing./security-reviewfollows untrusted input to the places it can do damage. - They end with evidence. Every command closes with a Done when line that names the proof: a command and its quoted output, a file, a screenshot. Saying "done" without it doesn't count.
In bwn
On main, after 0.21.0, bwn bundles /test, /handoff, /changelog, /design-pass and /deslop, plus the distinctive-design and deslop skills. For the rest, run python3 scripts/install_kit.py --layout bwn --dry-run from the kit to see what would be copied into ~/.buildwithnexus/, then run it again without --dry-run. It never deletes, and it skips any file you've edited unless you pass --force. A file of the same name replaces a bundled one. bwn's own /commit, /review, /pr and /debug run before any command file, so the kit's versions of those four run headless only: bwn run '/review'. See Commands.
Commands
Every day
/test bundled in bwn | Add or run one focused test and quote the result. |
/review | Report defects in the local diff by severity. |
/debug | Reproduce a failure and name the cause before editing. |
/commit | Review the diff, skip secrets, run a fast check, and create one commit. |
/pr | Draft a pull request title and body from the branch diff. |
/security-review | Review a change or path for security defects, with evidence. |
/explain | Explain behavior in plain language with a fixed writing shape. |
/handoff bundled in bwn | Write a one-page note for the next session. |
Before you build
/brainstorm | Explore an idea before committing to implementation. |
/grill | Narrow an open decision with rounds of focused questions. |
/discovery | Interview for requirements before design or code. |
/design-brief | One-page brief before design or build. |
/sdd | Start new work spec-first with tests and vertical slices. |
/feature | Break a large ask into shippable work items. |
/user-story | Draft one user story with testable acceptance criteria. |
/bdd | Turn acceptance criteria into Gherkin and step stubs. |
/test-plan | Outline test scope, types, and risks from requirements. |
/questionnaire | Questions for a human who holds facts the repo lacks. |
Decisions on record
/adr | Record one architecture decision in a short ADR file. |
/rfc | Draft a design RFC for a cross-cutting technical choice. |
/migration-plan | Plan a library or runtime migration without editing yet. |
/rebuild | Spec-driven rebuild in vertical slices with old and new paths in parallel. |
Tests and quality
/coverage | Add tests for uncovered lines from a coverage report. |
/testgen | Generate a focused unit test file for one module. |
/playwright | Add a focused end-to-end browser test. |
/journey | Walk a UI flow in a browser and list fixable issues. |
/load-test | Sketch a bounded load test for an endpoint or workflow. |
/entropy | Measure entropy hotspots and apply small verified cleanups. |
/deslop bundled in bwn | Find generated-code leftovers and repair them in focused commits. |
/design-pass bundled in bwn | Lock a non-generic visual concept and verify it on a captured screen. |
/rehearse | Run every command block in a clean matching cell before handing it to the maintainer. |
/lean | State a function's properties as a Lean 4 spec, prove what holds, and turn each into a property-based test. |
Security and supply chain
/secrets-scan | Scan the tree for committed secrets and risky assignments. |
/deps-audit | Run dependency vulnerability audits for this repo's ecosystem. |
/supply-chain | Review dependency provenance, pinning, and SBOM hygiene. |
/sbom | Produce a software bill of materials from manifests. |
/threat-model | List threats and mitigations for a feature or surface. |
/pipeline-review | Review CI/CD definitions for security, reliability, and least privilege. |
/soc2 | Repo readiness table against public SOC 2 Trust Services Criteria (not an audit). |
Docs and operations
/api-docs | Document a public HTTP or library API from the code that defines it. |
/onboard | Orient a reader to how this repository is organized. |
/runbook | Write an operator runbook for running and fixing the service. |
/changelog bundled in bwn | Draft release notes from commits since the last tag. |
/bug | Draft a defect report with repro and expected vs actual. |
/retro | Look back on the session and capture one rule to keep. |
Adding your own
/new-command | Scaffold a slash command markdown file. |
/new-skill | Scaffold a skill folder with frontmatter and when-to-use rules. |
/new-agent | Scaffold a helper agent file with tools and read-only default. |
Skills
A skill is knowledge the agent loads when it needs it. Each one says when to load it and what done looks like.
agent-orchestration | Use when splitting work across helpers: who gets what, what they return, and how to trust it. |
api-design | Use when adding or changing a public interface (HTTP, RPC or library exports): contracts, errors, versioning, limits. |
deslop bundled in bwn | Use after heavy generated edits: find the debris (invisible Unicode, narrating comments, dead code, stock prose), rank it, and clean it up in small commits. |
distinctive-design bundled in bwn | Use when designing or restyling a UI or terminal layout: pick one visual tradition, build it literally, prove contrast and access on a real capture. |
lean | Use when a function's correctness matters more than its example cases: state its properties as a Lean 4 spec, prove what you can, and turn every property into a property-based test in the project's own runner. |
rehearse | Use before handing the maintainer any command block to run on their own machine: run every block in a clean cell that matches theirs first. |
security-review | Use when reviewing code for security: trace untrusted input to dangerous sinks, check authorization, prove each finding. |
testing | Use when writing, generating or judging tests: what a test should pin, what it must never be, and how to prove it tests anything. |
verify-before-done | Use before saying anything is done, fixed or passing: run the narrowest proof and quote it. |
vertical-slicing | Use when planning or building a feature: ship the thinnest path from input to visible result first. |
rehearse is the one to know about if you run commands on your own machine. Before the agent hands you a block, it runs the block in a clean cell that matches your OS, shell and user rights, and checks the output against the block's # expect: line. What it couldn't run is listed as Not rehearsed, with the reason. That's for your information; it is not a task for you.
Helpers
Read-only agents a command can hand a narrow job to. They report; they don't edit. Every helper returns the same shape: a Scope line, a table of severity, path:line, what's wrong and the evidence, and a Not checked line. "Nothing found" is a row, not a blank, and anything unproven is labeled as unproven.
debugger | Read-only reproduction and root-cause analysis. |
pipeline-reviewer | Read-only review of Azure Pipelines and GitHub Actions YAML. |
reviewer | Read-only defect review of the diff or named paths. |
security-check | Read-only pass for injection, secrets, and unsafe defaults. |
Guards and scanners
guard_shell.pyblocks recursive deletes of root or home, force pushes to main,git reset --hard,git clean -fwithout-n, piping a download into a shell, and disk formats. It letsrm -rf build/,grep reboot logsandgit clean -nthrough, and says what to do instead when it blocks.guard_writes.pyblocks writes outside the session's folder and into system directories.screen_prompt.pystops a prompt that looks like it contains a key.strip_invisible.pyremoves invisible Unicode from files the agent writes.scan_slop.py,scan_secrets.py,measure_entropy.pyandlint_blocks.pyreport on a tree. They don't change it.
To turn the guards on in bwn, run python3 scripts/install_kit.py --layout bwn --only scripts --hooks from the kit. It puts each guard in ~/.buildwithnexus/hooks/<Event>/, where bwn runs it with no settings entry; delete a file to turn that guard off. The write guard and the Unicode stripper ignore reads, so running on every tool call is safe. See Permissions & hooks for the events and exit codes.
How the kit checks itself
python3 scripts/check_kit.py fails when a command lacks its no-argument line or its Done when, when a skill lacks Use when or Done when, when a path or command a page mentions doesn't exist, when a shell block in its own docs has no # expect: line, or when the guard tests fail. CI runs it on Linux, macOS and Windows.