Magnus HedemarkandGitHub
e10508b034
* feat(bmad): add BMad control-plane protocol skill New standalone methodology skill that lets any agent run the BMad method (Breakthrough Method of Agile AI-Driven Development) as a harness-agnostic control-plane protocol: five-field intent contracts, direct/bounded/initiative classification, review-as-triage, failure routing by layer, and autonomy gating with machine-readable spec status. - SKILL.md protocol core with progressive disclosure + When not to use - README.md human-facing install guide - 9 references: protocol, classification, spec, lifecycle, project-context, review-and-failure-routing, autonomy, party-mode, adoption - 4 templates: SPEC, INTENT, STORY, REVIEW - scripts/check-spec.py + 16 tests (stdlib, deterministic spec validation) - evals/evals.json: 9 output-quality cases - Routing seams from bmad to adjacent skills and back from spec-driven-development, product-shaping, implementation-planning, neckbeard - Catalog updates: root README, skill-triggers, marketplace/plugin/llms.txt Closes #399 * fix(bmad): address droid-review findings - check-spec.py: skip headings inside fenced/indented code blocks so a spec cannot PASS on section text that only appears in a code sample - check-spec.py: catch UnicodeDecodeError on non-UTF-8 files and report FAIL instead of crashing - STORY.md template: add created key for resumability/traceability parity - SPEC.md template: split in-progress and in-review status bullets - add 2 regression tests (heading-in-fence, non-UTF-8) * fix(bmad): address droid-review round 2 - check-spec.py: read specs with utf-8-sig so a UTF-8 BOM cannot silently disable the frontmatter status check - check-spec.py: handle standard YAML inline comments after status values (status: draft # pending review) without a false FAIL - references/protocol.md: make lifecycle phrasing consistent with lifecycle.md — four phases plus a learning closeout - add 2 regression tests (BOM, inline comment) * fix(bmad): tolerate trailing whitespace on frontmatter delimiters A spec whose --- delimiter lines carry trailing spaces or tabs would silently disable the status check and let an invalid status PASS. Relax the delimiter pattern and add a regression test. * fix(bmad): ignore inline comments in quoted status values * fix(bmad): tolerate leading blank lines before frontmatter * fix(bmad): fail closed on unparseable frontmatter, matching fence markers Address droid-review round 5 and 6 findings as a single closed class: - Fail closed when a file opens with a --- delimiter that cannot be parsed, so no whitespace/frontmatter permutation can silently disable the status check (previously: unparseable frontmatter was treated as 'no status' warning, letting an invalid status PASS). - Track fence opener markers in collect_headings so a mismatched fence no longer closes a code block early (false-PASS on missing sections) and an unclosed fence no longer swallows real headings. - Accept empty well-formed frontmatter (---\n---) and closing delimiters without a trailing newline. - STORY.md template: parent-spec points at the sibling SPEC.md. - README: status vocabulary is not a strict linear chain; blocked is a resumable routing signal. Whitespace/frontmatter mutation sweep: 9 formatting variants x valid/invalid status all verdict correctly; malformed delimiters fail closed. 29 tests.
neckbeard
An evidence-driven operating model for software delivery — not a "10x developer" persona, but a disciplined workflow that helps an AI agent choose the smallest safe intervention, prove it worked at the real delivery boundary, and leave an audit trail a human can inspect.
Why Install This Skill
Most "senior developer" prompts fail the same way: they make an agent emit short, confident code and call it effectiveness. Scott Logic's critique of the Ponytail benchmark showed that a static behavioral prompt plus a narrow, gameable metric (lines of code) cannot substantiate any real claim about software engineering. Swapping the persona for the three words "Follow YAGNI principles" nearly matched its score.
neckbeard is the answer to that failure mode. Instead of performing a character, it gives an agent a bounded, stage-aware spine: frame the change, discover the real system before designing, pick the smallest intervention that is still safe, execute by SDLC stage, record evidence, and stop or escalate when the evidence runs out. Minimalism is treated as a consequence of understanding, not a reflex — so the bundle does not win by reflexively deleting or compressing.
Install it when you want delivery discipline that is inspectable. Every non-trivial run produces an evidence ledger: intent, inspected artifacts, assumptions, rejected alternatives, files changed, checks run, observed outputs, and the boundaries that were not verified. "Done" is prohibited unless the declared verification target was actually exercised. For a test-only regression guard around already-correct production behavior, the bundle uses a bounded lightweight path with clean-baseline and targeted-mutant evidence rather than ordinary bug-fix reproduction requirements.
What You Get
| Path | What it provides |
|---|---|
SKILL.md |
Thin umbrella that routes a request through the delivery spine and composes specialist catalog skills |
references/stages.md |
Entry conditions, required evidence, exit conditions, and escalation rules for each SDLC stage |
references/lightweight-test-hardening.md |
Bounded path for test-only regression guards: baseline-pass / mutant-fail evidence, hermeticity, finality-before-push, and review pacing |
references/evidence-ledger.md |
The ledger schema and the rules for distinguishing a component check from a delivery-boundary check |
references/risk-authority-gates.md |
Stop and escalation rules; the gate before any mutation, deploy, merge, or destructive act |
references/routing-table.md |
"Use existing skill instead" table so the bundle composes the catalog rather than swallowing it |
references/journey.md |
Canonical 9-phase change-request journey — intake, discovery, design, spec, test plan, implementation, review, readiness, authorized release — with four delivery paths |
references/lifecycle.md |
Platform mechanics for GitHub (reference mode) and enterprise contexts — intake snapshots, CI/review monitoring, terminal states, and post-merge release authority |
references/delivery-packet.md |
Durable cross-phase handoff: provenance, resumability, gate verdicts, exact-head binding, lifecycle states, and an artifact ownership map |
references/position-assessment.md |
Entry mode for picking up delivery work that started elsewhere: artifact inventory, phase exit-condition scoring, a position report, and packet bootstrap |
references/tracker-discovery.md |
Intake sub-step that detects which tracking system holds the work item and routes tracker operations to the matching tooling skill (linear, jira-cli, notion) |
references/evaluation.md |
Evaluation methodology: fixtures, baselines, rubrics, multi-run reporting, claims policy |
templates/ |
Change contract, decision record, evidence ledger, verification plan, evaluation report |
templates/delivery-packet.md |
Fillable delivery packet template mirroring the nine field groups defined in the reference |
evals/evals.json |
Schema-v1 output-quality evaluation cases covering routing, gates, skip reasons, exact-head binding, terminal states, and lightweight test-hardening semantics |
eval/ |
Versioned evaluation harness: task schema, scoring rubric, baseline protocol, fixtures, and a runner |
Quick Start
Load the umbrella when a non-trivial change lands — read SKILL.md and follow
its core loop. For a bug, the agent frames a change contract, loads
systematic-debugging for root cause, makes the smallest safe fix, verifies at
the real boundary, and writes an evidence ledger. For a feature, it routes
discovery to product-discovery, shaping of the bounded idea to product-shaping,
and specification to spec-driven-development before writing code.
To run the evaluation suite against your harness:
python3 eval/run_eval.py --suite eval/fixtures --report out/report.md
Triggers
- Asked to fix, build, refactor, review, verify, or release software where the work is non-trivial.
- A change needs a defensible "done" backed by evidence, not a claim.
- You want an inspectable record of what was inspected, assumed, changed, and left unverified.
- You need to evaluate whether a delivery skill actually improves outcomes.
- You are delivering a change request — an issue, ticket, or tracked request — from intake through planning, gates, implementation, and review to a verified PR (or equivalent reviewable deliverable).
- You need to carry work from an issue to a PR to an authorized post-merge release with resumable, exact-head-bound state across phases.
- You are asked to continue work someone else started — a half-implemented branch or adopted spec with no delivery packet — and need an evidence-based answer to "what step are we on and what remains?"
- Your product tracks work in Linear, Jira, or Notion, and the lifecycle should operate that system through its own tooling skill instead of assuming GitHub.
Do not trigger for single factual questions, fully-specified one-line edits, or tasks already owned end-to-end by a more specific skill. The change-request journey is not loaded for a plain fix, refactor, or review that has no issue/ticket trajectory.
Requirements
- An agent harness with file read/write, terminal access, and skill loading.
- No network or runtime dependency in the bundle itself.
- The evaluation runner needs Python 3.9+ (standard library only).
- Recommended companion catalog skills (loaded on demand, not required):
product-discovery,spec-driven-development,software-architecture-analysis,systematic-debugging,technical-documentation,verification-methodology.