Evidence-driven brownfield discovery for spec-kit.
BrownKit packages the EDCR (Evidence → Discovery → Capabilities → Risk) methodology as a spec-kit extension. It turns an existing codebase into a locked capability model with security and QA risk overlays — ready for modernization planning, AI-assisted refactoring, and per-team handoff.
/init → /scan → /discover → [/report] → /assess → /generate → /finish
| Command | Purpose |
|---|---|
speckit.brownkit.init |
Capture project, security, and QA scope. Create the evidence tree. |
speckit.brownkit.scan |
Extract capability, security, and QA signals from code + external inputs. |
speckit.brownkit.discover |
Verify candidates; lock L1/L2 capabilities; build domain model. |
speckit.brownkit.report |
Emit stakeholder / architect / dev / SDET / (conditional) security reports. |
speckit.brownkit.assess |
STRIDE per capability + QA risk analysis + unified scoring. |
speckit.brownkit.generate |
Capability-scoped AI contexts, security prompts, spec seeds. |
speckit.brownkit.finish |
Validate acceptance criteria and package per-team handoffs. |
Three read-only commands plug into the spec-kit workflow without re-running analysis. They read existing evidence and surface the relevant slice.
| Command | Fires | Purpose |
|---|---|---|
speckit.brownkit.enrich |
before specify / clarify | Surface matching L1/L2 capabilities and spec seeds for the feature in scope. |
speckit.brownkit.gate |
before implement | Check open STRIDE threats and QA risk score; warn or block if risks are unaccepted. |
speckit.brownkit.validate |
after implement | Verify the delivered implementation against spec seed commitments, security constraints, and QA targets. |
All three hooks are optional and prompt before running. Pass --strict to any
of them to treat unresolved findings as a hard stop.
specify extension add brownkit --from https://github.com/MaksimShevtsov/BrownKit/archive/refs/tags/v1.0.0.zipThe specify extension update command does not support external URLs, so updating requires a remove + re-add:
specify extension remove brownkit && specify extension add brownkit --from https://github.com/MaksimShevtsov/BrownKit/archive/refs/tags/v<NEW_VERSION>.zipReplace <NEW_VERSION> with the target version (e.g. v1.1.0). Check CHANGELOG.md for what changed between versions before updating.
Copy config-template.yml to brownkit-config.yml in your project root and
adjust scope. All fields are optional — the pipeline adapts to available
signals and marks absent inputs as not-collected rather than fabricating
defaults.
After a full run:
evidence/
├── context.json, workflow.json
├── discovery/ candidates, l1/l2, domain-model, blueprint, coverage
├── security/ signals, threats/, vulnerabilities/, controls/, risk-scores
├── qa/ test-inventory, coverage-map, testability, environments, qa-context
├── risk/ unified-risk-map
├── reports/ stakeholder, architect, dev, sdet, (security)
└── generate/ capability-contexts/, spec-seeds/, handoff/<team>/
Full write-up in docs/methodology.md. Per-phase
specs live in docs/phases/.
Deterministic accelerators (coverage parsers, git churn, secret scan,
acceptance validator) live under scripts/. Python
core with bash and PowerShell shims. Stdlib only; Python ≥ 3.9.
MIT.