mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-12 12:06:29 +03:00
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.
2.6 KiB
2.6 KiB
Project Context: Conservative Repository Rules
Project context is the mechanism by which BMad records rules that code alone cannot express. The design principle: persist expensive-to-rediscover truth, not every fact about the repository. If an agent can cheaply inspect something from the code, duplicating it in permanent context creates stale noise.
What belongs in project context (e.g. AGENTS.md)
- Organization policies that affect how work is done.
- Frozen paths or generated files that must not be edited by hand.
- Branch and security rules.
- Commands with non-obvious prerequisites.
- Conventions that differ from ecosystem defaults.
- Observed pitfalls (things agents get wrong here specifically).
- Cross-component rules and required versions.
What does not belong
- A stale copy of the repository's directory tree or technology list.
- Anything an agent can reliably discover by reading the code.
- Transient state that will be wrong next week.
- Rules that apply to every repository anywhere (those belong in the harness, not the project).
The workflow intents
| Intent | Purpose |
|---|---|
| Setup | Establish the initial project-context block for a repository |
| Adopt | Bring an existing repository under project-context discipline without rewriting its history |
| Refresh | Update rules when the repository or policy changes |
| Record | Add a specific observed pitfall or non-obvious command |
| Audit | Review the existing block for staleness, drift, or over-duplication |
Operating rules
- Preserve human-authored content outside the owned markers; never rewrite the whole file.
- Keep the human in the loop for writes. A rule you are about to persist should be verifiable against the repository — if you cannot demonstrate it, do not record it.
- Verify commands before recording them as prerequisites. A command with an undocumented prerequisite recorded from memory is a liability.
- When a contested design decision surfaces during project-context work, route it back to architecture (an ADR or the architecture spine), not into local instructions.
- Mark the block so an audit can tell which lines are project-context-owned and which are human-authored.
Adoption path for an existing repository
- Inspect what already exists (AGENTS.md, CONTRIBUTING.md, CI, docs).
- Extract only rules that are expensive to rediscover and not already enforced by CI.
- Draft the block; show the human; get approval before writing.
- Record the first observed pitfall when one actually occurs — do not invent pitfalls.
- Re-audit on a schedule or when the repository changes materially.