# Workflow kit

[nexus-workflows](https://github.com/Garretts-Apps/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. `/review` asks whether a test would fail if the change were reverted. `/debug` bisects instead of guessing. `/security-review` follows 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](https://buildwithnexus.dev/docs/commands#workflow-kit).

## 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.py` blocks recursive deletes of root or home, force pushes to main, `git reset --hard`, `git clean -f` without `-n`, piping a download into a shell, and disk formats. It lets `rm -rf build/`, `grep reboot logs` and `git clean -n` through, and says what to do instead when it blocks.
- `guard_writes.py` blocks writes outside the session's folder and into system directories.
- `screen_prompt.py` stops a prompt that looks like it contains a key. `strip_invisible.py` removes invisible Unicode from files the agent writes.
- `scan_slop.py`, `scan_secrets.py`, `measure_entropy.py` and `lint_blocks.py` report 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](https://buildwithnexus.dev/docs/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.

MIT licensed · Made by [Garrett Eaglin](https://garretteaglin.com/)
