Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions skills/bmad-build-auto/step-01-clarify-and-route.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,11 @@ This runs on the output of `tickets.py find` for one ticket. Set `ticket_args` t
1. Load context.
- **A ticket from the tree** — when **Ticket resolution** set `plan_file`: the entry, its epic file and what that file's References name, and the story file when there is one are already the intent. For continuity, read the plans beside `plan_file` whose `ticket` is one of find's `after` ids that is a plain number (an entry of the same epic; a ref such as `1.5` is another epic's). Carry forward each one's **Code Map**, **Design Notes**, **Implementation Notes**, **Plan Change Log**, and **Tasks & Acceptance**, where present, as continuity context for step-02.
- **Anything else:**
- List `{{ config.output_folder }}/{active_initiative}/`, then `{{ config.output_folder }}/`.
{% if initiative_folder == config.output_folder %}
- List `{{ config.output_folder }}/`.
{% else %}
- List `{{ initiative_folder }}/`, then `{{ config.output_folder }}/`.
{% endif %}
- If the invocation prompt points to an unformatted plan or intent file, ingest that file. Do not scan for unrelated intent files.
- Planning documents sit in folders by type, main file named after the folder. Typical ones:
- **PRD** (`prd-*/prd-*.md`) — product requirements and success criteria
Expand All @@ -56,7 +60,7 @@ This runs on the output of `tickets.py find` for one ticket. Set `ticket_args` t
4. Multi-goal warning. If the intent appears to contain multiple independently shippable goals, carry `multiple-goals` forward so step-02 can add it to `{plan_file}` frontmatter `warnings`. Do not split or block.
5. Set the plan file.

Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{ config.output_folder }}/{active_initiative}/plan-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `plan_file` to that path, **EARLY EXIT** → `{{ rendered("step-02-plan.md") }}`); otherwise append `-2`, `-3`, etc. Set `plan_file` = `{{ config.output_folder }}/{active_initiative}/plan-{slug}.md`.
Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{ initiative_folder }}/plan-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `plan_file` to that path, **EARLY EXIT** → `{{ rendered("step-02-plan.md") }}`); otherwise append `-2`, `-3`, etc. Set `plan_file` = `{{ initiative_folder }}/plan-{slug}.md`.

## NEXT

Expand Down
3 changes: 1 addition & 2 deletions skills/bmad-build-auto/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ To HALT with a final status and optional blocking condition. The halts `blocked
1. **A ticket from the tree** (`{ticket_args}` is set) with final status `blocked`: run `uv run {project-root}/_bmad/method/scripts/tickets.py --project-root {project-root} mark {ticket_args} blocked --blocked <blocking condition>`, with each argument quoted for the shell, which writes `status`, `blocked_at`, and `blocked_reason` to `{plan_file}` and creates it when there is none. Then append missing result details under `## Auto Run Result` in `{plan_file}`. If `mark` fails, follow 2 instead.
2. **Otherwise:**
- If `{plan_file}` is known and exists, update `status` in frontmatter and append missing result details under `## Auto Run Result`.
- If `{plan_file}` is unknown or missing, create `{{ config.output_folder }}/{active_initiative}/bmad-build-auto-result-<slug-or-timestamp>.md` with:
- If `{plan_file}` is unknown or missing, create `{{ initiative_folder }}/bmad-build-auto-result-<slug-or-timestamp>.md` with:
```markdown
---
status: <final status>
Expand Down Expand Up @@ -56,7 +56,6 @@ A full plan is "Ready for Development" when:

- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory.
- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents.
- `{active_initiative}` is the value printed by `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.active_initiative`, read once before step 1. When it is unset, drop `/{active_initiative}` from every path.
- Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim.

## On Activation
Expand Down
16 changes: 10 additions & 6 deletions skills/bmad-build/step-01-clarify-and-route.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,12 @@ Before listing artifacts, resolve existing workflow state in this order. Skip th
3. The ticket tree
With no argument and no intent from the conversation, run `uv run {project-root}/_bmad/method/scripts/tickets.py --project-root {project-root} next`.
- Non-zero exit (no active initiative, a store refusal, a malformed tree) → say in one line that the ticket tree is unavailable and why, then go to 4.
- A row in any group whose `status` is `draft`, `ready-for-dev`, `in-progress`, or `in-review` has a started plan when the file at `find <ref>`'s `plan` exists. When any row has one, or `{{ config.output_folder }}/{active_initiative}/` holds a `plan-*.md` with one of those statuses, go to 4.
- A row in any group whose `status` is `draft`, `ready-for-dev`, `in-progress`, or `in-review` has a started plan when the file at `find <ref>`'s `plan` exists. When any row has one, or `{{ initiative_folder }}/` holds a `plan-*.md` with one of those statuses, go to 4.
- No `ready_to_start` row → say in one line that nothing in the tree is ready, naming what is ready to refine, in progress, or blocked, then go to 4.
- Otherwise run `find <ref>` with the first `ready_to_start` row's `ref`, tell the user in one line which entry you are building, and follow **Ticket resolution**.

4. Otherwise — scan artifacts and ask
- Active plans (`draft`, `ready-for-dev`, `in-progress`, `in-review`) among `{{ config.output_folder }}/{active_initiative}/plan-*.md`, or started plans in the tree from branch 3? → List them all and HALT. Give the user a choice:
- Active plans (`draft`, `ready-for-dev`, `in-progress`, `in-review`) among `{{ initiative_folder }}/plan-*.md`, or started plans in the tree from branch 3? → List them all and HALT. Give the user a choice:
- Resume one of the listed plans
- **Next entry** — when branch 3 found a `ready_to_start` row with no `status`, the first one: run `find <ref>` with its `ref` and follow **Ticket resolution**
- **New** — start new work
Expand All @@ -56,8 +56,12 @@ This runs on the output of `tickets.py find` for one ticket. Find's `description
1. Load context.
- **A ticket from the tree** — when **Ticket resolution** set `plan_file`: the entry, its epic file and what that file's References name, and the story file when there is one are already the intent. For continuity, read the plans beside `plan_file` whose `ticket` is one of find's `after` ids that is a plain number (an entry of the same epic; a ref such as `1.5` is another epic's). Extract each one's **Code Map**, **Design Notes**, **Plan Change Log**, and task list as continuity context for step-02 planning.
- **Anything else:**
- No `{active_initiative}`: unless the user already said in this session, ask once whether this work belongs to an initiative (hand off to the `bmad` skill to set one, then read `{active_initiative}` again) or is loose.
- List `{{ config.output_folder }}/{active_initiative}/`, then `{{ config.output_folder }}/`.
{% if initiative_folder == config.output_folder %}
- No initiative is active: unless the user already said in this session, ask once whether this work belongs to an initiative (hand off to the `bmad` skill to set one, then run this skill again) or is loose.
- List `{{ config.output_folder }}/`.
{% else %}
- List `{{ initiative_folder }}/`, then `{{ config.output_folder }}/`.
{% endif %}
- If you find an unformatted plan or intent file, ingest its contents to form your understanding of the intent.
- Planning documents sit in folders by type, main file named after the folder. Typical ones:
- **PRD** (`prd-*/prd-*.md`) — product requirements and success criteria
Expand All @@ -74,7 +78,7 @@ This runs on the output of `tickets.py find` for one ticket. Find's `description
- HALT and give the user a choice:
- **Split** — pick first goal, defer the rest.
- **Keep all goals** — accept the risks.
- If the user chooses **Split**: For each deferred goal, append one new entry to `{{ config.output_folder }}/{active_initiative}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
- If the user chooses **Split**: For each deferred goal, append one new entry to `{{ initiative_folder }}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
```markdown
- source_plan: none
summary: <one sentence naming the deferred goal>
Expand All @@ -83,7 +87,7 @@ This runs on the output of `tickets.py find` for one ticket. Find's `description
- If the user chooses **Keep all goals**: Proceed as-is.
5. Set the plan file.

Derive a valid kebab-case slug from the current intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{ config.output_folder }}/{active_initiative}/plan-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `plan_file` to that path, **EARLY EXIT** → `{{ rendered("step-02-plan.md") }}`); otherwise append `-2`, `-3`, etc. Set `plan_file` = `{{ config.output_folder }}/{active_initiative}/plan-{slug}.md`.
Derive a valid kebab-case slug from the current intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{ initiative_folder }}/plan-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `plan_file` to that path, **EARLY EXIT** → `{{ rendered("step-02-plan.md") }}`); otherwise append `-2`, `-3`, etc. Set `plan_file` = `{{ initiative_folder }}/plan-{slug}.md`.

## NEXT

Expand Down
2 changes: 1 addition & 1 deletion skills/bmad-build/step-02-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
5. Self-review against READY FOR DEVELOPMENT standard. For anything important that's missing: if the repository can tell you, go look and fix the plan; if a human has to decide, add an `## Open Questions` entry. Do not invent the answer.
6. Resolve the gates before the checkpoint. Two things must be settled, in whatever order the conversation makes natural; combine them in one message when both apply.
- **Token count** (see SCOPE STANDARD). If the plan exceeds 1600 tokens, show the count and give the user a choice:
- **Split** — carve off secondary goals. Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{ config.output_folder }}/{active_initiative}/deferred-work.md` using the format below. Do not modify existing entries or look for duplicates. Rewrite the current plan to cover only the main goal — do not surgically carve sections out; regenerate the plan for the narrowed scope.
- **Split** — carve off secondary goals. Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{ initiative_folder }}/deferred-work.md` using the format below. Do not modify existing entries or look for duplicates. Rewrite the current plan to cover only the main goal — do not surgically carve sections out; regenerate the plan for the narrowed scope.
- **Keep full plan** — accept the risks.
```markdown
- source_plan: `{plan_file}`
Expand Down
2 changes: 1 addition & 1 deletion skills/bmad-build/step-04-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ Write `lenses_ran` — the ids launched, in launch order — to `{plan_file}` fr
```

If it cannot be continued, apply the patches yourself. Then re-run the checks in `{plan_file}`'s `## Verification` section, if present — the patches changed code after the implementer's verification; if verification fails and the failure cannot be fixed, HALT and escalate to the human. Rewrite `{diff_file}` so it reflects the patched tree.
- **defer** — Append one new entry to `{{ config.output_folder }}/{active_initiative}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
- **defer** — Append one new entry to `{{ initiative_folder }}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
```markdown
- source_plan: `{plan_file}`
summary: <one sentence>
Expand Down
2 changes: 1 addition & 1 deletion skills/bmad-build/step-oneshot.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ For each group:

- **patch** — This change caused or exposed the problem. The smallest fix is simple, adds no new public API, and does not guard code paths you did not show are reachable. Fix it now.
- **HALT** — Same as patch, but the smallest fix is not that simple. Stop and ask the user before continuing.
- **defer** — Everything else: old bugs not caused by this change, ideas for later, groups where every member is `maybe-false` and would be `medium` or `high` if true (record that severity marked unverified, and what would prove it; if it would only be `low`, reject it), or fixes that would edit CLAUDE.md, AGENTS.md, rules, or specs. Add one entry to `{{ config.output_folder }}/{active_initiative}/deferred-work.md`:
- **defer** — Everything else: old bugs not caused by this change, ideas for later, groups where every member is `maybe-false` and would be `medium` or `high` if true (record that severity marked unverified, and what would prove it; if it would only be `low`, reject it), or fixes that would edit CLAUDE.md, AGENTS.md, rules, or specs. Add one entry to `{{ initiative_folder }}/deferred-work.md`:

```markdown
- source_plan: `{plan_file}`
Expand Down
1 change: 0 additions & 1 deletion skills/bmad-build/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ A plan should target a **single user-facing goal** within **900–1600 tokens**:

- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory.
- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents.
- `{active_initiative}` is the value printed by `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.active_initiative`, read once before step 1. When it is unset, drop `/{active_initiative}` from every path.
- Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim.

## On Activation
Expand Down
2 changes: 1 addition & 1 deletion skills/bmad-code-review/step-02-review.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ failed_layers: '' # set at runtime: comma-separated list of lenses that failed o
{{ workflow.thorough_lenses }}
{% endif %}

3. If a lens's instruction requires subagents and none are available, for each such lens write that lens's child prompt beside `{plan_file}`, named after it with the lens id appended (in `{{ config.output_folder }}/{active_initiative}/` when there is no plan), with every file it points to — the diff, the claims, the reviewer instruction file — replaced inline by that file's contents, and every other line left exactly as written. That session shares no filesystem with this one, so its prompt has to stand alone; this is the only place you read a reviewer instruction file yourself. Then HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, treat them as those lenses' findings and resume from this point.
3. If a lens's instruction requires subagents and none are available, for each such lens write that lens's child prompt beside `{plan_file}`, named after it with the lens id appended (in `{{ initiative_folder }}/` when there is no plan), with every file it points to — the diff, the claims, the reviewer instruction file — replaced inline by that file's contents, and every other line left exactly as written. That session shares no filesystem with this one, so its prompt has to stand alone; this is the only place you read a reviewer instruction file yourself. Then HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, treat them as those lenses' findings and resume from this point.

4. **Lens failure handling**: If any lens fails, times out, or returns empty results, append the lens's `name` to `failed_layers` (comma-separated) and proceed with findings from the remaining lenses.

Expand Down
2 changes: 1 addition & 1 deletion skills/bmad-code-review/step-04-present.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
deferred_work_file: '{{ config.output_folder }}/{active_initiative}/deferred-work.md'
deferred_work_file: '{{ initiative_folder }}/deferred-work.md'
---

# Step 4: Present and Act
Expand Down
1 change: 0 additions & 1 deletion skills/bmad-code-review/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ If you need an explicit user instruction to run them, ask once now for the whole
- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory.
- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents.
- `{date}` is the current system datetime.
- `{active_initiative}` is the value printed by `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core.active_initiative`, read once before step 1. When it is unset, drop `/{active_initiative}` from every path.

## On Activation

Expand Down
2 changes: 1 addition & 1 deletion skills/bmad-toolsmith/shapes/rendered-skill/shape.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,6 @@ A skill whose Markdown is rendered once per run from `customize.toml` and the te
## Rules

- `SKILL.md` does one thing: runs `uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}"`, maps the words of the invocation to `--set workflow.<key>=<value>`, follows the printed `workflow.md`, and halts on any failure. No Jinja in it; the renderer excludes it.
- Jinja (`{{ workflow.key }}`, `{% if %}`, `rendered("step-02-<name>.md")`) lives only in `workflow.md` and the steps. An agent-facing `{{placeholder}}` sits inside `{% raw %}...{% endraw %}`; a single-brace `{placeholder}` passes through untouched. A customization value the templates cannot act on, such as a misspelled selector, is rejected at the top of `workflow.md` with `{{ halt("...") }}`, one guard per selector.
- Jinja (`{{ workflow.key }}`, `{% if %}`, `rendered("step-02-<name>.md")`) lives only in `workflow.md` and the steps. An agent-facing `{{placeholder}}` sits inside `{% raw %}...{% endraw %}`; a single-brace `{placeholder}` passes through untouched. The skill's documents go under `{{ initiative_folder }}`, the output folder extended by the active initiative when one is set. A customization value the templates cannot act on, such as a misspelled selector, is rejected at the top of `workflow.md` with `{{ halt("...") }}`, one guard per selector.
- `customize.toml` holds `[workflow]` with `activation_steps_prepend`, `activation_steps_append` and `persistent_facts`. A selector is a scalar with its allowed values in the comment above it; an instruction a team may replace whole is a `"""` block scalar. Teams override in `{project-root}/_bmad/custom/<name>.toml` or `<name>.user.toml`; a single run overrides with `--set`.
- Each step is loaded when reached, says at the top what it produces, and ends by naming the next step as `{{ rendered("step-NN-<name>.md") }}` or by saying the workflow is complete. A step that shows a menu halts and waits for the user. No file whose name contains `template` carries `{{ config.* }}` or `{{ workflow.* }}`.
2 changes: 1 addition & 1 deletion skills/bmad-walkthrough/step-02-narrative.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Write the review narrative and the review log in a new folder
`walkthrough-<slug>/` under
`{{ config.output_folder }}/{active_initiative}/`: the narrative as
`{{ initiative_folder }}/`: the narrative as
`walkthrough-<slug>.md`, the log as `walkthrough-<slug>-log.md`.
`<slug>` is a short review slug; check that the folder name is
unused before creating it.
Expand Down
Loading
Loading