Update project structure and configurations
This commit is contained in:
@@ -3,4 +3,109 @@ name: bmad-quick-dev
|
||||
description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
|
||||
---
|
||||
|
||||
Follow the instructions in ./workflow.md.
|
||||
# Quick Dev New Preview Workflow
|
||||
|
||||
**Goal:** Turn user intent into a hardened, reviewable artifact.
|
||||
|
||||
**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
|
||||
|
||||
## READY FOR DEVELOPMENT STANDARD
|
||||
|
||||
A specification is "Ready for Development" when:
|
||||
|
||||
- **Actionable**: Every task has a file path and specific action.
|
||||
- **Logical**: Tasks ordered by dependency.
|
||||
- **Testable**: All ACs use Given/When/Then.
|
||||
- **Complete**: No placeholders or TBDs.
|
||||
|
||||
## SCOPE STANDARD
|
||||
|
||||
A specification should target a **single user-facing goal** within **900–1600 tokens**:
|
||||
|
||||
- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
|
||||
- Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
|
||||
- Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
|
||||
- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
|
||||
- **Neither limit is a gate.** Both are proposals with user override.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root.
|
||||
- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
|
||||
- `{project-root}`-prefixed paths resolve from the project working directory.
|
||||
- `{skill-name}` resolves to the skill directory's basename.
|
||||
|
||||
## On Activation
|
||||
|
||||
### Step 1: Resolve the Workflow Block
|
||||
|
||||
Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
|
||||
|
||||
**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
|
||||
|
||||
1. `{skill-root}/customize.toml` — defaults
|
||||
2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
|
||||
3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
|
||||
|
||||
Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
|
||||
|
||||
### Step 2: Execute Prepend Steps
|
||||
|
||||
Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
|
||||
|
||||
### Step 3: Load Persistent Facts
|
||||
|
||||
Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim.
|
||||
|
||||
### Step 4: Load Config
|
||||
|
||||
Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
|
||||
|
||||
- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
|
||||
- `communication_language`, `document_output_language`, `user_skill_level`
|
||||
- `date` as system-generated current datetime
|
||||
- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
|
||||
- `project_context` = `**/project-context.md` (load if exists)
|
||||
- CLAUDE.md / memory files (load if exist)
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
- Language MUST be tailored to `{user_skill_level}`
|
||||
- Generate all documents in `{document_output_language}`
|
||||
|
||||
### Step 5: Greet the User
|
||||
|
||||
Greet `{user_name}`, speaking in `{communication_language}`.
|
||||
|
||||
### Step 6: Execute Append Steps
|
||||
|
||||
Execute each entry in `{workflow.activation_steps_append}` in order.
|
||||
|
||||
Activation is complete. Begin the workflow below.
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **step-file architecture** for disciplined execution:
|
||||
|
||||
- **Micro-file Design**: Each step is self-contained and followed exactly
|
||||
- **Just-In-Time Loading**: Only load the current step file
|
||||
- **Sequential Enforcement**: Complete steps in order, no skipping
|
||||
- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
|
||||
- **Append-Only Building**: Build artifacts incrementally
|
||||
|
||||
### Step Processing Rules
|
||||
|
||||
1. **READ COMPLETELY**: Read the entire step file before acting
|
||||
2. **FOLLOW SEQUENCE**: Execute sections in order
|
||||
3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
|
||||
4. **LOAD NEXT**: When directed, read fully and follow the next step file
|
||||
|
||||
### Critical Rules (NO EXCEPTIONS)
|
||||
|
||||
- **NEVER** load multiple step files simultaneously
|
||||
- **ALWAYS** read entire step file before execution
|
||||
- **NEVER** skip steps or optimize the sequence
|
||||
- **ALWAYS** follow the exact instructions in the step file
|
||||
- **ALWAYS** halt at checkpoints and wait for human input
|
||||
|
||||
## FIRST STEP
|
||||
|
||||
Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.
|
||||
|
||||
62
.gemini/skills/bmad-quick-dev/compile-epic-context.md
Normal file
62
.gemini/skills/bmad-quick-dev/compile-epic-context.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Compile Epic Context
|
||||
|
||||
**Task**
|
||||
Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic-<N>-context.md`).
|
||||
|
||||
**Steps**
|
||||
|
||||
1. Read the epics file and extract the target epic's title, goal, and list of stories.
|
||||
2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief).
|
||||
3. Pull only the information relevant to this epic.
|
||||
4. Write the compiled context to the exact output path using the format below.
|
||||
|
||||
## Exact Output Format
|
||||
|
||||
Use these headings:
|
||||
|
||||
```markdown
|
||||
# Epic {N} Context: {Epic Title}
|
||||
|
||||
<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
|
||||
|
||||
## Goal
|
||||
|
||||
{One clear paragraph: what this epic achieves and why it matters.}
|
||||
|
||||
## Stories
|
||||
|
||||
- Story X.Y: Brief title only
|
||||
- ...
|
||||
|
||||
## Requirements & Constraints
|
||||
|
||||
{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).}
|
||||
|
||||
## Technical Decisions
|
||||
|
||||
{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.}
|
||||
|
||||
## UX & Interaction Patterns
|
||||
|
||||
{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).}
|
||||
|
||||
## Cross-Story Dependencies
|
||||
|
||||
{Dependencies between stories in this epic or with other epics/systems (omit if none).}
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc.
|
||||
- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't.
|
||||
- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill.
|
||||
- **No story-level details.** The story list is for orientation only. Individual story specs handle the details.
|
||||
- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code.
|
||||
- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material.
|
||||
- **Never hallucinate content.** If source material doesn't say something, don't invent it.
|
||||
- **Omit empty sections entirely**, except Goal and Stories, which are always required.
|
||||
|
||||
## Error handling
|
||||
|
||||
- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file.
|
||||
- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections.
|
||||
41
.gemini/skills/bmad-quick-dev/customize.toml
Normal file
41
.gemini/skills/bmad-quick-dev/customize.toml
Normal file
@@ -0,0 +1,41 @@
|
||||
# DO NOT EDIT -- overwritten on every update.
|
||||
#
|
||||
# Workflow customization surface for bmad-quick-dev. Mirrors the
|
||||
# agent customization shape under the [workflow] namespace.
|
||||
|
||||
[workflow]
|
||||
|
||||
# --- Configurable below. Overrides merge per BMad structural rules: ---
|
||||
# scalars: override wins • arrays (persistent_facts, activation_steps_*): append
|
||||
# arrays-of-tables with `code`/`id`: replace matching items, append new ones.
|
||||
|
||||
# Steps to run before the standard activation (config load, greet).
|
||||
# Overrides append. Use for pre-flight loads, compliance checks, etc.
|
||||
|
||||
activation_steps_prepend = []
|
||||
|
||||
# Steps to run after greet but before the workflow begins.
|
||||
# Overrides append. Use for context-heavy setup that should happen
|
||||
# once the user has been acknowledged.
|
||||
|
||||
activation_steps_append = []
|
||||
|
||||
# Persistent facts the workflow keeps in mind for the whole run
|
||||
# (standards, compliance constraints, stylistic guardrails).
|
||||
# Distinct from the runtime memory sidecar — these are static context
|
||||
# loaded on activation. Overrides append.
|
||||
#
|
||||
# Each entry is either:
|
||||
# - a literal sentence, e.g. "All stories must include testable acceptance criteria."
|
||||
# - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
|
||||
# (glob patterns are supported; the file's contents are loaded and treated as facts).
|
||||
|
||||
persistent_facts = [
|
||||
"file:{project-root}/**/project-context.md",
|
||||
]
|
||||
|
||||
# Scalar: executed when the workflow reaches its final step,
|
||||
# after implementation is complete and explanations are provided. Override wins.
|
||||
# Leave empty for no custom post-completion behavior.
|
||||
|
||||
on_complete = ""
|
||||
@@ -3,7 +3,7 @@ title: '{title}'
|
||||
type: 'feature' # feature | bugfix | refactor | chore
|
||||
created: '{date}'
|
||||
status: 'draft' # draft | ready-for-dev | in-progress | in-review | done
|
||||
context: [] # optional: max 3 project-wide standards/docs. NO source code files.
|
||||
context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body.
|
||||
---
|
||||
|
||||
<!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
wipFile: '{implementation_artifacts}/spec-wip.md'
|
||||
deferred_work_file: '{implementation_artifacts}/deferred-work.md'
|
||||
spec_file: '' # set at runtime for plan-code-review before leaving this step
|
||||
spec_file: '' # set at runtime for both routes before leaving this step
|
||||
story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds
|
||||
---
|
||||
|
||||
# Step 1: Clarify and Route
|
||||
@@ -21,7 +21,7 @@ Before listing artifacts or prompting the user, check whether you already know t
|
||||
|
||||
1. Explicit argument
|
||||
Did the user pass a specific file path, spec name, or clear instruction this message?
|
||||
- If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: ready-for-dev, in-progress, or in-review) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-03 for ready/in-progress, step-04 for review).
|
||||
- If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file`. Before exiting, run **Story-key resolution** (below). Then **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
|
||||
- Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
|
||||
|
||||
2. Recent conversation
|
||||
@@ -29,19 +29,53 @@ Before listing artifacts or prompting the user, check whether you already know t
|
||||
Use the same routing as above.
|
||||
|
||||
3. Otherwise — scan artifacts and ask
|
||||
- `{wipFile}` exists? → Offer resume or archive.
|
||||
- Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
|
||||
- If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
|
||||
- If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
|
||||
- Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
|
||||
- If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
|
||||
- If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-03-implement.md`
|
||||
- If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-04-review.md`
|
||||
- Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
|
||||
|
||||
Never ask extra questions if you already understand what the user intends.
|
||||
|
||||
### Story-key resolution
|
||||
|
||||
This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `{epic_num}` and `{story_num}`. If the spec is not an epic story, skip silently and leave `{story_key}` unset.
|
||||
|
||||
If the spec is an epic story and `{sprint_status}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple).
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
1. Load context.
|
||||
- List files in `{planning_artifacts}` and `{implementation_artifacts}`.
|
||||
- If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
|
||||
- **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
|
||||
|
||||
**A) Epic story path** — if the intent is clearly an epic story:
|
||||
|
||||
1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B.
|
||||
|
||||
2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
|
||||
- **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
|
||||
- **If missing, empty, or invalid:** continue to step 3.
|
||||
|
||||
3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
|
||||
- **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
|
||||
- **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
|
||||
|
||||
4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
|
||||
|
||||
5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
|
||||
|
||||
6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now.
|
||||
|
||||
**B) Freeform path** — if the intent is not an epic story:
|
||||
- Planning artifacts are the output of BMAD phases 1-3. Typical files include:
|
||||
- **PRD** (`*prd*`) — product requirements and success criteria
|
||||
- **Architecture** (`*architecture*`) — technical design decisions and constraints
|
||||
- **UX/Design** (`*ux*`) — user experience and interaction design
|
||||
- **Epics** (`*epic*`) — feature breakdown into implementable stories
|
||||
- **Product Brief** (`*brief*`) — project vision and scope
|
||||
- Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
|
||||
2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
|
||||
3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
|
||||
4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
|
||||
@@ -52,11 +86,13 @@ Never ask extra questions if you already understand what the user intends.
|
||||
- On **K**: Proceed as-is.
|
||||
5. Route — choose exactly one:
|
||||
|
||||
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 `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
|
||||
|
||||
**a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
|
||||
|
||||
**EARLY EXIT** → `./step-oneshot.md`
|
||||
|
||||
**b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
|
||||
1. 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 `{implementation_artifacts}/spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
|
||||
|
||||
|
||||
## NEXT
|
||||
|
||||
@@ -1,5 +1,4 @@
|
||||
---
|
||||
wipFile: '{implementation_artifacts}/spec-wip.md'
|
||||
deferred_work_file: '{implementation_artifacts}/deferred-work.md'
|
||||
---
|
||||
|
||||
@@ -12,11 +11,12 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
|
||||
2. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
|
||||
3. Self-review against READY FOR DEVELOPMENT standard.
|
||||
4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
|
||||
5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
|
||||
1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
|
||||
2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
|
||||
3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`.
|
||||
4. Self-review against READY FOR DEVELOPMENT standard.
|
||||
5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
|
||||
6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
|
||||
- Show user the token count.
|
||||
- HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
|
||||
- On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
|
||||
@@ -24,9 +24,21 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
|
||||
|
||||
### CHECKPOINT 1
|
||||
|
||||
Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit`
|
||||
Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem.
|
||||
|
||||
- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. Display the finalized spec path to the user as a CWD-relative path (no leading `/`) so it is clickable in the terminal. → Step 3.
|
||||
After presenting the summary, display this note:
|
||||
|
||||
---
|
||||
|
||||
Before approving, you can open the spec file in an editor or ask me questions and tell me what to change. You can also use `bmad-advanced-elicitation`, `bmad-party-mode`, or `bmad-code-review` skills, ideally in another session to avoid context bloat.
|
||||
|
||||
---
|
||||
|
||||
HALT and ask human: `[A] Approve` | `[E] Edit`
|
||||
|
||||
- **A**: Re-read `{spec_file}` from disk.
|
||||
- **If the file is missing:** HALT. Tell the user the spec file is gone and STOP — do not write anything to `{spec_file}`, do not set status, do not proceed to Step 3. Nothing below this point runs.
|
||||
- **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
|
||||
- **E**: Apply changes, then return to CHECKPOINT 1.
|
||||
|
||||
|
||||
|
||||
@@ -24,6 +24,10 @@ Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unava
|
||||
|
||||
Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
|
||||
|
||||
Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`.
|
||||
|
||||
If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
|
||||
|
||||
Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.
|
||||
|
||||
**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
|
||||
|
||||
@@ -9,6 +9,7 @@ specLoopIteration: 1
|
||||
|
||||
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
- Review subagents get NO conversation context.
|
||||
- All review subagents must run at the same model capability as the current session.
|
||||
|
||||
## INSTRUCTIONS
|
||||
|
||||
|
||||
@@ -48,16 +48,31 @@ Format each stop as framing first, link on the next indented line:
|
||||
|
||||
When there is only one concern, omit the bold label — just list the stops directly.
|
||||
|
||||
### Commit and Present
|
||||
### Mark Spec Done
|
||||
|
||||
1. Change `{spec_file}` status to `done` in the frontmatter.
|
||||
2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
|
||||
3. Open the spec in the user's editor so they can click through the Suggested Review Order:
|
||||
Change `{spec_file}` status to `done` in the frontmatter.
|
||||
|
||||
Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
|
||||
|
||||
### Commit and Open
|
||||
|
||||
1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
|
||||
2. Open the spec in the user's editor so they can click through the Suggested Review Order:
|
||||
- Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
|
||||
- If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
|
||||
4. Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
|
||||
- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
|
||||
- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
|
||||
- Offer to push and/or create a pull request.
|
||||
|
||||
### Display Summary
|
||||
|
||||
Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
|
||||
|
||||
- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
|
||||
- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
|
||||
- Offer to push and/or create a pull request.
|
||||
|
||||
Workflow complete.
|
||||
|
||||
## On Complete
|
||||
|
||||
Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
|
||||
|
||||
If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.
|
||||
|
||||
@@ -13,11 +13,13 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
|
||||
|
||||
### Implement
|
||||
|
||||
Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`.
|
||||
|
||||
Implement the clarified intent directly.
|
||||
|
||||
### Review
|
||||
|
||||
Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
|
||||
Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
|
||||
|
||||
### Classify
|
||||
|
||||
@@ -29,21 +31,41 @@ Deduplicate all review findings. Three categories only:
|
||||
|
||||
If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
|
||||
|
||||
### Generate Spec Trace
|
||||
|
||||
Set `{title}` = a concise title derived from the clarified intent.
|
||||
|
||||
Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
|
||||
|
||||
1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
|
||||
2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
|
||||
3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
|
||||
|
||||
Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
|
||||
|
||||
### Commit
|
||||
|
||||
If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.
|
||||
|
||||
### Present
|
||||
|
||||
1. Open all changed files in the user's editor so they can review the code directly:
|
||||
- Resolve two sets of absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) each changed file. Run `code -r "{absolute-root}" <absolute-changed-file-paths>` — the root first so VS Code opens in the right context, then each changed file. Always double-quote paths to handle spaces and special characters.
|
||||
- If `code` is not available (command fails), skip gracefully and list the file paths instead.
|
||||
1. Open the spec in the user's editor so they can click through the Suggested Review Order:
|
||||
- Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
|
||||
- If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
|
||||
2. Display a summary in conversation output, including:
|
||||
- The commit hash (if one was created).
|
||||
- List of files changed with one-line descriptions. Use CWD-relative paths with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/`.
|
||||
- List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths.
|
||||
- Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
|
||||
- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
|
||||
- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
|
||||
3. Offer to push and/or create a pull request.
|
||||
|
||||
HALT and wait for human input.
|
||||
|
||||
Workflow complete.
|
||||
|
||||
## On Complete
|
||||
|
||||
Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
|
||||
|
||||
If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.
|
||||
|
||||
19
.gemini/skills/bmad-quick-dev/sync-sprint-status.md
Normal file
19
.gemini/skills/bmad-quick-dev/sync-sprint-status.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Sync Sprint Status
|
||||
|
||||
Shared sub-step for updating `sprint-status.yaml` during quick-dev. Called from any route (plan-code-review, one-shot, future routes) with a `{target_status}` parameter.
|
||||
|
||||
## Preconditions
|
||||
|
||||
Skip this entire file (return to caller) if ANY of:
|
||||
- `{story_key}` is unset
|
||||
- `{sprint_status}` does not exist on disk
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Load the FULL `{sprint_status}` file.
|
||||
2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller.
|
||||
3. **Idempotency check.** If `development_status[{story_key}]` is already at `{target_status}` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status.
|
||||
4. Set `development_status[{story_key}]` to `{target_status}`.
|
||||
5. **Epic lift (only when `{target_status}` = `in-progress`).** Derive the parent epic key as `epic-{N}` from the leading numeric segment of `{story_key}` (e.g., `3-2-digest-delivery` → `epic-3`). If that entry exists and is `backlog`, set it to `in-progress`. Leave it alone otherwise. Skip this sub-step entirely when `{target_status}` is not `in-progress`.
|
||||
6. Refresh `last_updated` to the current date.
|
||||
7. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS and WORKFLOW NOTES.
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
main_config: '{project-root}/_bmad/bmm/config.yaml'
|
||||
---
|
||||
|
||||
# Quick Dev New Preview Workflow
|
||||
|
||||
**Goal:** Turn user intent into a hardened, reviewable artifact.
|
||||
|
||||
**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
|
||||
|
||||
|
||||
## READY FOR DEVELOPMENT STANDARD
|
||||
|
||||
A specification is "Ready for Development" when:
|
||||
|
||||
- **Actionable**: Every task has a file path and specific action.
|
||||
- **Logical**: Tasks ordered by dependency.
|
||||
- **Testable**: All ACs use Given/When/Then.
|
||||
- **Complete**: No placeholders or TBDs.
|
||||
|
||||
|
||||
## SCOPE STANDARD
|
||||
|
||||
A specification should target a **single user-facing goal** within **900–1600 tokens**:
|
||||
|
||||
- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
|
||||
- Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
|
||||
- Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
|
||||
- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
|
||||
- **Neither limit is a gate.** Both are proposals with user override.
|
||||
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **step-file architecture** for disciplined execution:
|
||||
|
||||
- **Micro-file Design**: Each step is self-contained and followed exactly
|
||||
- **Just-In-Time Loading**: Only load the current step file
|
||||
- **Sequential Enforcement**: Complete steps in order, no skipping
|
||||
- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
|
||||
- **Append-Only Building**: Build artifacts incrementally
|
||||
|
||||
### Step Processing Rules
|
||||
|
||||
1. **READ COMPLETELY**: Read the entire step file before acting
|
||||
2. **FOLLOW SEQUENCE**: Execute sections in order
|
||||
3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
|
||||
4. **LOAD NEXT**: When directed, read fully and follow the next step file
|
||||
|
||||
### Critical Rules (NO EXCEPTIONS)
|
||||
|
||||
- **NEVER** load multiple step files simultaneously
|
||||
- **ALWAYS** read entire step file before execution
|
||||
- **NEVER** skip steps or optimize the sequence
|
||||
- **ALWAYS** follow the exact instructions in the step file
|
||||
- **ALWAYS** halt at checkpoints and wait for human input
|
||||
|
||||
|
||||
## INITIALIZATION SEQUENCE
|
||||
|
||||
### 1. Configuration Loading
|
||||
|
||||
Load and read full config from `{main_config}` and resolve:
|
||||
|
||||
- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
|
||||
- `communication_language`, `document_output_language`, `user_skill_level`
|
||||
- `date` as system-generated current datetime
|
||||
- `project_context` = `**/project-context.md` (load if exists)
|
||||
- CLAUDE.md / memory files (load if exist)
|
||||
|
||||
YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
|
||||
|
||||
### 2. Paths
|
||||
|
||||
- `wipFile` = `{implementation_artifacts}/spec-wip.md`
|
||||
|
||||
### 3. First Step Execution
|
||||
|
||||
Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.
|
||||
Reference in New Issue
Block a user