initial commit

.agents/skills/bmad-quick-dev-new-preview/steps/step-01-clarify-and-route.md

@@ -0,0 +1,51 @@
+---
+wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+spec_file: '' # set at runtime before leaving this step
+---
+
+# Step 1: Clarify and Route
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do NOT assume you start from zero.
+- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
+- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
+
+## ARTIFACT SCAN
+
+- `{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`, set `execution_mode = "plan-code-review"`, skip to step 3.
+  - If `in-review` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 4.
+- Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it.
+
+## 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.
+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:
+   - Present detected distinct goals as a bullet list.
+   - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
+   - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
+   - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **K**: Proceed as-is.
+5. Generate `spec_file` path:
+   - Derive a valid kebab-case slug from the clarified intent.
+   - If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc.
+   - Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`.
+6. Route:
+   - **One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. `execution_mode = "one-shot"`. → Step 3.
+   - **Plan-code-review** — everything else. `execution_mode = "plan-code-review"`. → Step 2.
+   - When uncertain whether blast radius is truly zero, default to plan-code-review.
+
+
+## NEXT
+
+- One-shot / ready-for-dev: Read fully and follow `./step-03-implement.md`
+- Plan-code-review: Read fully and follow `./step-02-plan.md`

.agents/skills/bmad-quick-dev-new-preview/steps/step-02-plan.md

@@ -0,0 +1,35 @@
+---
+wipFile: '{implementation_artifacts}/tech-spec-wip.md'
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 2: Plan
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No intermediate approvals.
+
+## 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 `../tech-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:
+   - 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.
+   - On **K**: Continue to checkpoint with full spec.
+
+### 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`
+
+- **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. → Step 3.
+- **E**: Apply changes, then return to CHECKPOINT 1.
+
+
+## NEXT
+
+Read fully and follow `./step-03-implement.md`

.agents/skills/bmad-quick-dev-new-preview/steps/step-03-implement.md

@@ -0,0 +1,33 @@
+---
+---
+
+# Step 3: Implement
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No push. No remote ops.
+- Sequential execution only.
+- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
+
+## PRECONDITION
+
+Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding.
+
+## INSTRUCTIONS
+
+### Baseline (plan-code-review only)
+
+Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes.
+
+### Implement
+
+Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
+
+`execution_mode = "one-shot"` or no sub-agents/tasks available: implement the intent.
+
+Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-agent/task and let it implement.
+
+## NEXT
+
+Read fully and follow `./step-04-review.md`

.agents/skills/bmad-quick-dev-new-preview/steps/step-04-review.md

@@ -0,0 +1,50 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+specLoopIteration: 1
+---
+
+# Step 4: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Review subagents get NO conversation context.
+
+## INSTRUCTIONS
+
+Change `{spec_file}` status to `in-review` in the frontmatter before continuing.
+
+### Construct Diff (plan-code-review only)
+
+Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`.
+
+Do NOT `git add` anything — this is read-only inspection.
+
+### Review
+
+**One-shot:** Skip diff construction. Still invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files — inline review invites anchoring bias.
+
+**Plan-code-review:** Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+
+- **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
+- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
+- **Acceptance auditor** — receives `{diff_output}`, `{spec_file}`, and read access to the project. Must also read the docs listed in `{spec_file}` frontmatter `context`. Checks for violations of acceptance criteria, rules, and principles from the spec and context docs.
+
+### Classify
+
+1. Deduplicate all review findings.
+2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**. 
+   - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
+   - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
+   - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.
+   - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
+   - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
+3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
+   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
+   - **patch** — Auto-fix. These are the only findings that survive loopbacks.
+   - **defer** — Append to `{deferred_work_file}`.
+   - **reject** — Drop silently.
+## NEXT
+
+Read fully and follow `./step-05-present.md`

.agents/skills/bmad-quick-dev-new-preview/steps/step-05-present.md

@@ -0,0 +1,17 @@
+---
+---
+
+# Step 5: Present
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- NEVER auto-push.
+
+## INSTRUCTIONS
+
+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. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
+
+Workflow complete.