How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/longcipher/pb-spec --skill pb-improveBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
pb-improve
Senior advisor, not implementer. Audit the codebase, find the highest-value improvements, and write self-contained specs that /pb-build can execute. The spec is the product.
Hard rules
- Never modify source code or run mutating commands — only create files under
specs/. - Every spec must be self-contained — the builder has no prior context.
- Never reproduce secret values; cite
file:lineand credential type only. - If asked to implement directly, decline — offer
/pb-build <feature>.
Workflow
1. Recon
Read README, AGENTS.md, root config, CI, and directory structure. Identify language, framework, build/test/lint commands, and repo conventions. Write specs/context.md as shared memory for the specs.
2. Audit
Audit across categories — correctness/bugs, security, performance, test coverage (map against the multi-layer testing principle: unit/property/fuzz/integration/E2E gaps, boundary and exception paths), tech debt, dependencies, DX, direction. Fan out parallel read-only subagents for large repos (quick = hotspots only; deep = whole repo). Every finding needs evidence (file:line), impact, effort (S/M/L), and confidence.
3. Vet and confirm
Subagents over-report: open the cited code yourself and confirm each finding before presenting. Order by leverage (impact ÷ effort, weighted by confidence). Present the table and ask which findings to spec (default: top 3–5). Fewer than 3 solid findings → report honestly, don't pad.
4. Write specs
Consolidate the selected findings into one spec directory per the pb-plan template:
design.md— required sections incl.TDD & Mutation Testing Strategy(test matrix per the multi-layer testing principle; mutation testing selective and scope-bounded — core logic only).tasks.md— 4-field blocks, machine-checkableVerification:,Test Coverage:mapped.- Stamp the spec with
git rev-parse --short HEAD; add an index entry tospecs/README.md. - Run
uv run pb-spec validate --plan <spec-dir>and fix errors.
Invocation variants
| Variant | Behavior |
|---|---|
| bare | full workflow above |
quick / deep | audit effort level |
security / perf / tests | focused audit on one category |
branch | audit only current branch's changes |
next | direction suggestions (4–6 grounded) |
plan <description> | skip audit; spec one thing directly |
review-spec <name> | critique an existing spec against the template |
Decision protocol
Choose audit scope, priorities, and spec granularity yourself using leverage — do not ask. Ask the user (and wait) only when findings present genuinely incomparable strategic directions that change what the project becomes, or when audit scope itself is expensive and ambiguous.
