buildwithnexusv0.21.0
Menu

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

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 bwnAdd or run one focused test and quote the result.
/reviewReport defects in the local diff by severity.
/debugReproduce a failure and name the cause before editing.
/commitReview the diff, skip secrets, run a fast check, and create one commit.
/prDraft a pull request title and body from the branch diff.
/security-reviewReview a change or path for security defects, with evidence.
/explainExplain behavior in plain language with a fixed writing shape.
/handoff bundled in bwnWrite a one-page note for the next session.

Before you build

/brainstormExplore an idea before committing to implementation.
/grillNarrow an open decision with rounds of focused questions.
/discoveryInterview for requirements before design or code.
/design-briefOne-page brief before design or build.
/sddStart new work spec-first with tests and vertical slices.
/featureBreak a large ask into shippable work items.
/user-storyDraft one user story with testable acceptance criteria.
/bddTurn acceptance criteria into Gherkin and step stubs.
/test-planOutline test scope, types, and risks from requirements.
/questionnaireQuestions for a human who holds facts the repo lacks.

Decisions on record

/adrRecord one architecture decision in a short ADR file.
/rfcDraft a design RFC for a cross-cutting technical choice.
/migration-planPlan a library or runtime migration without editing yet.
/rebuildSpec-driven rebuild in vertical slices with old and new paths in parallel.

Tests and quality

/coverageAdd tests for uncovered lines from a coverage report.
/testgenGenerate a focused unit test file for one module.
/playwrightAdd a focused end-to-end browser test.
/journeyWalk a UI flow in a browser and list fixable issues.
/load-testSketch a bounded load test for an endpoint or workflow.
/entropyMeasure entropy hotspots and apply small verified cleanups.
/deslop bundled in bwnFind generated-code leftovers and repair them in focused commits.
/design-pass bundled in bwnLock a non-generic visual concept and verify it on a captured screen.
/rehearseRun every command block in a clean matching cell before handing it to the maintainer.
/leanState 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-scanScan the tree for committed secrets and risky assignments.
/deps-auditRun dependency vulnerability audits for this repo's ecosystem.
/supply-chainReview dependency provenance, pinning, and SBOM hygiene.
/sbomProduce a software bill of materials from manifests.
/threat-modelList threats and mitigations for a feature or surface.
/pipeline-reviewReview CI/CD definitions for security, reliability, and least privilege.
/soc2Repo readiness table against public SOC 2 Trust Services Criteria (not an audit).

Docs and operations

/api-docsDocument a public HTTP or library API from the code that defines it.
/onboardOrient a reader to how this repository is organized.
/runbookWrite an operator runbook for running and fixing the service.
/changelog bundled in bwnDraft release notes from commits since the last tag.
/bugDraft a defect report with repro and expected vs actual.
/retroLook back on the session and capture one rule to keep.

Adding your own

/new-commandScaffold a slash command markdown file.
/new-skillScaffold a skill folder with frontmatter and when-to-use rules.
/new-agentScaffold 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-orchestrationUse when splitting work across helpers: who gets what, what they return, and how to trust it.
api-designUse when adding or changing a public interface (HTTP, RPC or library exports): contracts, errors, versioning, limits.
deslop bundled in bwnUse 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 bwnUse when designing or restyling a UI or terminal layout: pick one visual tradition, build it literally, prove contrast and access on a real capture.
leanUse 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.
rehearseUse 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-reviewUse when reviewing code for security: trace untrusted input to dangerous sinks, check authorization, prove each finding.
testingUse 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-doneUse before saying anything is done, fixed or passing: run the narrowest proof and quote it.
vertical-slicingUse 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.

debuggerRead-only reproduction and root-cause analysis.
pipeline-reviewerRead-only review of Azure Pipelines and GitHub Actions YAML.
reviewerRead-only defect review of the diff or named paths.
security-checkRead-only pass for injection, secrets, and unsafe defaults.

Guards and scanners

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.