specross 1.0.0

package/template/commands/ba/impact.md

@@ -0,0 +1,42 @@
+> **Agent:** Read `.claude/agents/ba.md` and adopt that persona fully before proceeding.
+
+---
+
+Generate an impact report for story `$ARGUMENTS` when the spec has changed.
+
+The full argument format is: `{story-slug} {old-version} {new-version}`
+Parse $ARGUMENTS to extract:
+- STORY = first word
+- V_OLD = second word
+- V_NEW = third word
+
+Example: if $ARGUMENTS is `user-authentication v1.0.0 v1.1.0` then STORY=user-authentication, V_OLD=v1.0.0, V_NEW=v1.1.0
+
+## Steps
+
+1. Read the current `stories/{STORY}/story.md`.
+
+2. Run: `git diff {V_OLD} {V_NEW} -- stories/{STORY}/story.md`
+   to see what changed between versions. If git is not available, ask the user to paste the diff.
+
+3. Analyse the diff and produce an impact report covering:
+
+### Changes Summary
+What was added, removed, or modified in the story spec.
+
+### Impact on Dev
+- Which parts of the tech-spec (`stories/{STORY}/tech/tech-spec.md`) are affected?
+- Does the scaffold or existing code need to change?
+- Effort estimate for rework: Low / Medium / High
+
+### Impact on QC
+- Which existing test cases (`stories/{STORY}/test/test-cases.md`) are now invalid or need updating?
+- Are new test cases needed for the new/changed ACs?
+- Effort estimate for rework: Low / Medium / High
+
+### Recommended Actions
+Ordered list of actions Dev and QC should take, with the highest-priority items first.
+
+4. Save the report to `stories/{STORY}/docs/impact-{V_OLD}-to-{V_NEW}.md`.
+
+5. Print a summary and remind the team to update their `.spec-lock` files in `stories/{STORY}/tech/` and `stories/{STORY}/test/` once they've applied the changes.

package/template/commands/ba/new-story.md

@@ -0,0 +1,68 @@
+> **Agent:** Read `.claude/agents/ba.md` and adopt that persona fully before proceeding.
+
+---
+
+Create a new story or sub-spec for: $ARGUMENTS
+
+`$ARGUMENTS` supports two formats:
+- `{slug}` — standalone story, e.g. `user-authentication`
+- `{parent}/{slug}` — sub-spec under a parent, e.g. `order-management/create-order`
+
+## Steps
+
+1. Parse $ARGUMENTS:
+   - If it contains `/`: IS_SUB_SPEC = true, PARENT = part before `/`, SLUG = part after `/`
+   - If no `/`: IS_SUB_SPEC = false, SLUG = $ARGUMENTS
+
+2. Determine the display name (title-case the slug, e.g. `create-order` → "Create Order").
+
+3. Create the following folder and files at `ba/$ARGUMENTS/`:
+
+```
+ba/$ARGUMENTS/
+├── story.md        ← populate from _templates/story.md
+├── CHANGELOG.md    ← create with initial entry
+└── docs/           ← empty folder (add a .gitkeep)
+```
+
+4. In `ba/$ARGUMENTS/story.md`, copy the contents of `_templates/story.md` exactly and replace:
+   - `{{STORY_NAME}}` with the display name
+   - `{{STORY_SLUG}}` with `$ARGUMENTS`
+   - `{{DATE}}` with today's date in YYYY-MM-DD format
+
+   **If IS_SUB_SPEC = true**, also add this line to the header table in story.md:
+   ```
+   | **Parent spec** | `ba/{PARENT}/story.md` |
+   ```
+
+   **If IS_SUB_SPEC = false**, replace the Sub-specs section in story.md with:
+   ```markdown
+   ## Sub-specs
+
+   > List child specs here as this feature is broken down.
+
+   | Spec | Status | Notes |
+   |------|--------|-------|
+   | | | |
+   ```
+
+5. In `ba/$ARGUMENTS/CHANGELOG.md`, create:
+
+```markdown
+# Changelog — {display name}
+
+## v0.1.0 — {today}
+- Initial spec created
+```
+
+6. **If IS_SUB_SPEC = true**, check if `ba/{PARENT}/story.md` exists. If it does, append a row to its Sub-specs table:
+   ```
+   | [{display name}]({SLUG}/story.md) | Draft | |
+   ```
+   If the parent story doesn't have a Sub-specs table yet, add the section at the end.
+
+7. Print a summary:
+   - List the files created
+   - If sub-spec: remind BA to fill in AC specific to this flow/area
+   - If parent: remind BA to fill in the overview, then create sub-specs with `/ba:new-story {SLUG}/{sub-slug}`
+   - Suggest next step: "Once story.md is complete, run `/ba:review $ARGUMENTS`"

package/template/commands/ba/release.md

@@ -0,0 +1,128 @@
+> **Agent:** Read `.claude/agents/ba.md` and adopt that persona fully before proceeding.
+
+---
+
+Release a story from `ba/` to `stories/`. Format: `{story-slug} {version}`
+
+Parse $ARGUMENTS:
+- STORY = first word (e.g. `user-authentication`)
+- VERSION = second word (e.g. `v1.0.0`). If not provided, default to `v1.0.0` for a new story or bump the patch version of the last release.
+
+## Steps
+
+1. Read `ba/{STORY}/story.md`. If it doesn't exist, stop and say "Story draft not found. Run `/ba:new-story {STORY}` first."
+
+2. Read `ba/{STORY}/CHANGELOG.md` to find the previous version (if any).
+
+3. Determine if this is a new release (first time) or an update:
+   - **New release:** `stories/{STORY}/story.md` does not exist yet
+   - **Update:** `stories/{STORY}/story.md` already exists — diff it against `ba/{STORY}/story.md`
+
+4. **If this is an UPDATE (not the first release):**
+   - Read both `ba/{STORY}/story.md` (new draft) and `stories/{STORY}/story.md` (last released version)
+   - Compare them directly — no git required
+   - Generate a change summary covering:
+     - ACs added / removed / modified
+     - Edge cases added / removed / modified
+     - Out-of-scope or dependency changes
+     - Any section that meaningfully changed
+
+5. Update `ba/{STORY}/CHANGELOG.md` — prepend a new entry:
+
+```markdown
+## {VERSION} — {today}
+
+### Changes
+- [List each meaningful change to the story — ACs added, edge cases updated, scope changes, etc.]
+
+### Impact
+- **Dev:** [Brief note — e.g. "New AC-05 requires token TTL changes" or "No breaking changes"]
+- **QC:** [Brief note — e.g. "2 new test cases needed for AC-05" or "No impact"]
+```
+
+6. **Promote to `stories/`** — copy the full draft into the released stories folder:
+   - Copy `ba/{STORY}/` → `stories/{STORY}/` (overwrite if exists)
+   - This snapshot is the official version Dev and QC will work against
+
+7. Save a release note to `stories/{STORY}/docs/release-{VERSION}.md`:
+
+```markdown
+# Release Note — {STORY} {VERSION}
+
+**Date:** {today}
+**Status:** Ready for Dev and QC
+
+## What's in this release
+[Summary of the story purpose — 2–3 sentences for context]
+
+## What changed (vs previous version)
+[For first release: "Initial story release"]
+[For updates: List each AC / edge case change clearly]
+
+## Action required
+
+### Dev team
+- [ ] Run `/dev:gen-tech-spec {STORY}` (first release)
+- [ ] OR run `/dev:sync {STORY}` (update — see what changed)
+
+### QC team
+- [ ] Run `/qc:gen-test-cases {STORY}` (first release)
+- [ ] OR run `/qc:sync {STORY}` (update — see what changed)
+
+## Story location
+`stories/{STORY}/story.md`
+```
+
+8. **Check for outdated specs** — after promoting to `stories/`, check who is behind:
+
+   - Check `stories/{STORY}/tech/.spec-lock`:
+     - If it exists: read `spec-version` from it
+     - If `spec-version` ≠ `{VERSION}` → Dev's tech spec is outdated (locked at that version)
+   - Check `stories/{STORY}/test/.spec-lock`:
+     - If it exists: read `spec-version` from it
+     - If `spec-version` ≠ `{VERSION}` → QC's test cases are outdated (locked at that version)
+
+9. Create a git tag suggestion. Print:
+
+```
+✅  Story released: {STORY} {VERSION}
+    Draft:    ba/{STORY}/
+    Released: stories/{STORY}/
+
+Run this to tag the version in git:
+  git add ba/{STORY}/ stories/{STORY}/
+  git commit -m "spec({STORY}): release {VERSION}"
+  git tag spec/{STORY}/{VERSION}
+
+Then share the release note with Dev and QC:
+  📄  stories/{STORY}/docs/release-{VERSION}.md
+```
+
+   If any specs are outdated (from step 8), append an alert block:
+
+```
+⚠️  OUTDATED SPECS DETECTED
+──────────────────────────────────────────
+[For each outdated spec, one line:]
+  🔴  Dev tech spec is on {locked-version} — run /dev:sync {STORY}
+  🔴  QC test cases are on {locked-version} — run /qc:sync {STORY}
+──────────────────────────────────────────
+```
+
+   If all specs are up to date (or no specs exist yet), print:
+```
+✅  No outdated specs.
+```
+
+10. If this is an update (not first release), also print the impact summary so the BA can paste it into their team chat:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📢  STORY UPDATE: {STORY} → {VERSION}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[Change summary — bullet points]
+
+Dev: run /dev:sync {STORY}
+QC:  run /qc:sync {STORY}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/template/commands/ba/review.md

@@ -0,0 +1,44 @@
+> **Agent:** Read `.claude/agents/ba.md` and adopt that persona fully before proceeding.
+
+---
+
+Review the story at `ba/$ARGUMENTS/story.md` for completeness and quality.
+
+## Steps
+
+1. Read `ba/$ARGUMENTS/story.md` fully.
+
+2. Evaluate the story against this checklist:
+
+### Completeness
+- [ ] Story title and slug are filled in
+- [ ] Description clearly explains the "what" and "why" (not just "what")
+- [ ] All actors/users who interact with this feature are identified
+- [ ] Acceptance Criteria (AC) are written in "Given / When / Then" or clear pass/fail format
+- [ ] Each AC is independently testable
+- [ ] Edge cases and error states are documented
+- [ ] Out-of-scope items are explicitly listed
+- [ ] Any dependencies on other stories or systems are noted
+
+### Quality
+- [ ] No ambiguous words like "should", "maybe", "might", "sometimes"
+- [ ] No missing actors (e.g. AC says "the user" but which user role?)
+- [ ] No AC that mixes multiple conditions (each AC = one condition)
+- [ ] No technical implementation details dictated in the AC (BA says WHAT, not HOW)
+
+## Output format
+
+Return a structured review:
+
+**Story:** `$ARGUMENTS`
+**Status:** READY / NEEDS WORK / BLOCKED
+
+**Gaps found:** (list each gap with a specific suggestion to fix it)
+
+**Suggested ACs to add:** (if any are missing)
+
+**Questions for the BA:** (anything that needs clarification before Dev/QC can proceed)
+
+If the story is READY, say so clearly and suggest next steps:
+- Dev: `/dev:gen-tech-spec $ARGUMENTS`
+- QC: `/qc:gen-test-cases $ARGUMENTS`

package/template/commands/dev/gen-scaffold.md

@@ -0,0 +1,40 @@
+> **Agent:** Read `.claude/agents/dev.md` and adopt that persona fully before proceeding.
+
+---
+
+Generate a code scaffold for story: $ARGUMENTS
+
+## Steps
+
+1. Read `stories/$ARGUMENTS/tech/tech-spec.md`. If it doesn't exist, stop and say: "Tech spec not found. Run `/dev:gen-tech-spec $ARGUMENTS` first."
+
+2. Read `stories/$ARGUMENTS/story.md` for business context.
+
+3. Read `CLAUDE.md` for the project's tech stack, folder conventions, coding standards, and naming rules.
+
+4. Analyse the tech spec and identify all files that need to be created or modified:
+   - New files (controllers, services, models, components, tests, etc.)
+   - Existing files that need changes (router registration, DI container, etc.)
+
+5. For each file, generate the scaffold:
+   - **Include:** function/method signatures, class/interface definitions, inline TODO comments for business logic
+   - **Do not include:** full implementations — leave logic as `// TODO: implement` or `pass`
+   - **Do include:** imports, type hints/interfaces, error handling stubs, and docstrings/JSDoc
+
+6. Write files to the appropriate locations under `src/` (or the project's source folder as defined in CLAUDE.md).
+
+7. Also create stub test files under `tests/` that match the scaffold — one test file per implementation file, with `describe` / `it` blocks pre-filled from the AC mapping in the tech spec but left as pending (`it.todo()` or `xit()`).
+
+8. After generating all files, print:
+
+**Scaffold summary for `$ARGUMENTS`:**
+
+| File | Type | Action |
+|------|------|--------|
+| src/... | Controller | Created |
+| src/... | Service | Created |
+| tests/... | Unit test | Created |
+
+**Next steps:**
+1. Fill in the `// TODO` sections in each file
+2. Run `/dev:review $ARGUMENTS` once implementation is done to verify all ACs are covered

package/template/commands/dev/gen-tech-spec.md

@@ -0,0 +1,39 @@
+> **Agent:** Read `.claude/agents/dev.md` and adopt that persona fully before proceeding.
+
+---
+
+Generate a technical specification for story: $ARGUMENTS
+
+## Steps
+
+1. Read `stories/$ARGUMENTS/story.md` fully. If it doesn't exist, stop and say:
+   "Story not found. Run `/ba:new-story $ARGUMENTS` first."
+
+2. Check that the story has complete Acceptance Criteria. If incomplete, warn the user and suggest `/ba:review $ARGUMENTS` before proceeding.
+
+3. Read `CLAUDE.md` to understand the project's tech stack, conventions, and architecture patterns.
+
+4. Read `_templates/tech-spec.md` — this is the **exact output format** to follow.
+   - Every section in the template must appear in the output
+   - Replace placeholder text with real content derived from the story
+   - Do not add or remove sections unless the template instructs it
+
+5. Check if `stories/$ARGUMENTS/tech/tech-spec.md` already exists. If it does, warn the user and ask to confirm before overwriting.
+
+6. Generate the tech spec following `_templates/tech-spec.md` exactly, and write it to `stories/$ARGUMENTS/tech/tech-spec.md`.
+   - Fill `{{STORY_NAME}}` with the title-cased story name
+   - Fill `{{STORY_SLUG}}` with `$ARGUMENTS`
+   - Fill `{{DATE}}` with today's date
+   - Map every AC from story.md into the AC Mapping table — no AC left blank
+
+7. Read `stories/$ARGUMENTS/CHANGELOG.md` to find the current story version (the latest `## vX.Y.Z` entry at the top). Create `.spec-lock` at `stories/$ARGUMENTS/tech/.spec-lock`:
+   ```
+   story: $ARGUMENTS
+   spec-version: {current-story-version}
+   generated: {today}
+   ```
+
+8. Print next steps:
+   - "Tech spec created: `stories/$ARGUMENTS/tech/tech-spec.md`"
+   - "Review it before running `/dev:gen-scaffold $ARGUMENTS`"
+   - "To customize the output format, edit `_templates/tech-spec.md`"

package/template/commands/dev/review.md

@@ -0,0 +1,52 @@
+> **Agent:** Read `.claude/agents/dev.md` and adopt that persona fully before proceeding.
+
+---
+
+Review implementation against the story and tech spec for: $ARGUMENTS
+
+## Steps
+
+1. Read `stories/$ARGUMENTS/story.md` — this is the source of truth for requirements.
+2. Read `stories/$ARGUMENTS/tech/tech-spec.md` — this is the agreed technical approach.
+3. Read `stories/$ARGUMENTS/tech/.spec-lock` to check which spec version this work is based on.
+4. Read all relevant implementation files in `src/` related to this story.
+
+## Review Checklist
+
+### Requirements Coverage
+For each Acceptance Criterion in story.md, check:
+- [ ] Is it implemented?
+- [ ] Is it implemented correctly (matches the AC, not just roughly)?
+- [ ] Is the edge case handling from the story covered?
+
+### Tech Spec Compliance
+- [ ] Does the implementation match the data model in the tech spec?
+- [ ] Are the API contracts (endpoints, shapes, auth) as specced?
+- [ ] Were the architecture decisions from the spec followed? If not, is there a good reason?
+
+### Code Quality
+- [ ] No obvious bugs or unhandled error paths
+- [ ] No hardcoded values where config/constants should be used
+- [ ] No TODO comments left behind that should be implemented
+- [ ] Tests exist for the main paths and edge cases
+
+## Output Format
+
+**Story:** `$ARGUMENTS`
+**Review result:** APPROVED / CHANGES REQUESTED / BLOCKED
+
+### ACs Status
+| AC | Status | Notes |
+|----|--------|-------|
+| AC-01 | ✅ Covered | |
+| AC-02 | ⚠️ Partial | Missing error state for X |
+| AC-03 | ❌ Not found | |
+
+### Issues Found
+(Numbered list — specific file and line where possible)
+
+### Questions / Decisions Needed
+(Anything that requires BA or team input)
+
+### Verdict
+Clear recommendation: ready to merge, needs fixes, or needs a BA conversation first.

package/template/commands/dev/status.md

@@ -0,0 +1,51 @@
+> **Agent:** Read `.claude/agents/dev.md` and adopt that persona fully before proceeding.
+
+---
+
+Scan all released stories and show which ones need a tech spec sync.
+
+## Steps
+
+1. List all subdirectories under `stories/`. Each subdirectory is a story slug.
+   If `stories/` is empty or doesn't exist, print "No stories released yet." and stop.
+
+2. For each story folder, collect its sync status:
+
+   a. Read `stories/{story}/CHANGELOG.md` — extract the latest version (the first `## vX.Y.Z` entry at the top). If CHANGELOG doesn't exist, mark as `unknown`.
+
+   b. Check `stories/{story}/tech/.spec-lock`:
+      - If it **doesn't exist** → status: `⚪ No tech spec`
+      - If it exists → read `spec-version`
+        - If `spec-version` == latest version → status: `✅ Up to date`
+        - If `spec-version` != latest version → status: `🔴 Outdated  (locked: {spec-version} → latest: {latest})`
+
+3. Print the status table:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋  DEV STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[one line per story, sorted: outdated first, then up-to-date, then no spec]
+
+  🔴  user-authentication   v1.0.0 → v1.3.0   /dev:sync user-authentication
+  🔴  create-order          v1.1.0 → v1.2.0   /dev:sync create-order
+  ✅  payment-flow          v2.0.0
+  ⚪  export-report                            /dev:gen-tech-spec export-report
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{N} stories need sync   {M} up to date   {K} no tech spec yet
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+4. If there are outdated stories, print a shortcut block:
+
+```
+Run these to sync:
+[one line per outdated story]
+  /dev:sync {story}
+```
+
+If everything is up to date, print:
+```
+✅  All tech specs are up to date.
+```

package/template/commands/dev/sync.md

@@ -0,0 +1,62 @@
+> **Agent:** Read `.claude/agents/dev.md` and adopt that persona fully before proceeding.
+
+---
+
+Check if the story spec has changed since the tech spec was generated, and show what needs to be updated.
+
+Story: $ARGUMENTS
+
+## Steps
+
+1. Read `stories/$ARGUMENTS/tech/.spec-lock`. If it doesn't exist, say:
+   "No spec-lock found. Run `/dev:gen-tech-spec $ARGUMENTS` to generate the tech spec first."
+
+   The `.spec-lock` contains the story version this tech spec was based on (e.g. `v1.0.0`).
+
+2. Read `stories/$ARGUMENTS/CHANGELOG.md` to find the latest released version.
+
+3. Compare the locked version vs the latest version:
+   - If they match → print "✅ Your tech spec is up to date. No action needed." and stop.
+   - If they differ → continue.
+
+4. Read the latest release note at `stories/$ARGUMENTS/docs/release-{latest-version}.md` to understand what changed.
+
+5. Read the current `stories/$ARGUMENTS/story.md` fully.
+
+6. Read the current `stories/$ARGUMENTS/tech/tech-spec.md` fully.
+
+7. Produce a sync report:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔄  DEV SYNC — $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Your tech spec: v{locked}
+Latest story:   v{latest}
+
+CHANGES SINCE YOUR LAST SYNC:
+[List each changed AC or edge case, with a clear description of what changed]
+
+WHAT YOU NEED TO UPDATE IN YOUR TECH SPEC:
+[For each change, specific guidance on which section of tech-spec.md to update]
+
+WHAT YOU NEED TO UPDATE IN YOUR CODE:
+[For each change, brief note on likely code impact — file/function level if possible]
+
+EFFORT ESTIMATE: Low / Medium / High
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+8. After the report, ask: "Would you like me to update the tech spec now with these changes?"
+   - If yes: update `stories/$ARGUMENTS/tech/tech-spec.md` with the new/changed sections
+   - If no: leave it as-is
+
+9. Once the tech spec is updated (either now or by the dev manually), remind them to update `.spec-lock`:
+
+```
+When you've finished updating your tech spec and code, update your spec-lock:
+
+stories/$ARGUMENTS/tech/.spec-lock
+  → change spec-version to: {latest}
+  → change synced: to today's date
+```

package/template/commands/help.md

@@ -0,0 +1,77 @@
+Print the Specross command reference. No arguments needed.
+
+---
+
+Print the following help text exactly:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚡  SPECROSS — Command Reference
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+BUSINESS ANALYST  ──────────────────────────────────────────
+
+  /ba:new-story {story}
+    Create a new story draft under ba/{story}/story.md
+    Uses the story template — fill in AC, edge cases, scope.
+
+  /ba:review {story}
+    Review a draft story for gaps before releasing.
+    Checks: missing AC, vague criteria, undefined edge cases.
+
+  /ba:release {story} {version}
+    Promote a draft to stories/ as the official released version.
+    Diffs vs previous, writes CHANGELOG, alerts outdated Dev/QC specs.
+
+  /ba:impact {story}
+    Show downstream impact of a story change before releasing.
+    Lists which Dev and QC artifacts will be affected.
+
+DEVELOPER  ─────────────────────────────────────────────────
+
+  /dev:status
+    Scan all stories — show which tech specs are outdated or missing.
+    Run this first thing to see what needs attention.
+
+  /dev:gen-tech-spec {story}
+    Generate a tech spec from the released story.
+    Maps every AC to a technical approach. Locks spec version.
+
+  /dev:gen-scaffold {story}
+    Generate skeleton code and stub tests from the tech spec.
+    Creates files in src/ and tests/ with TODOs to implement.
+
+  /dev:review {story}
+    Review your implementation against the story's AC.
+    Flags gaps between code and acceptance criteria.
+
+  /dev:sync {story}
+    Show what changed in the story since your last tech spec.
+    Tells you exactly which sections and code to update.
+
+QC / TESTING  ──────────────────────────────────────────────
+
+  /qc:status
+    Scan all stories — show which test cases are outdated or missing.
+    Run this first thing to see what needs attention.
+
+  /qc:gen-test-cases {story}
+    Generate test cases from the released story.
+    Happy path + edge case + negative TCs for every AC. Locks spec version.
+
+  /qc:gen-scripts {story}
+    Generate automation scripts from the test cases.
+    Uses the framework defined in CLAUDE.md (Playwright, Cypress, pytest…).
+
+  /qc:sync {story}
+    Show what changed in the story since your last test cases.
+    Lists invalid TCs, TCs needing updates, and new TCs to add.
+
+  /qc:bug-report {story}
+    Generate a structured bug report tied to a story's AC.
+    Includes repro steps, expected vs actual, AC reference.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Tip: Start with /ba:new-story → /ba:release → /dev:status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/template/commands/qc/bug-report.md

@@ -0,0 +1,33 @@
+> **Agent:** Read `.claude/agents/qc.md` and adopt that persona fully before proceeding.
+
+---
+
+Generate a structured bug report for story: $ARGUMENTS
+
+Parse $ARGUMENTS: `{story-slug} {TC-ID}`
+- STORY = first word (e.g. `user-authentication`)
+- TC_ID = second word (e.g. `TC-003`)
+
+## Steps
+
+1. Read `stories/{STORY}/test/test-cases.md` and find the test case matching {TC_ID}.
+   If not found, stop and say clearly which TC-IDs are available.
+
+2. Read `stories/{STORY}/story.md` to understand the related AC.
+
+3. Read `_templates/bug-report.md` — this is the **exact output format** to follow.
+
+4. Ask the user to provide:
+   - What actually happened (actual result)
+   - Steps to reproduce (if different from TC steps)
+   - Environment (browser, OS, app version, test/staging/prod)
+   - Screenshots, logs, or error messages (paste or describe)
+
+5. Generate the bug report following `_templates/bug-report.md` exactly.
+   Save to `stories/{STORY}/test/bugs/bug-{TC_ID}-{slug}.md`
+   where `{slug}` is a short hyphenated description (e.g. `login-fails-empty-password`).
+
+6. After saving, print:
+   - "Bug report saved: `stories/{STORY}/test/bugs/bug-{TC_ID}-{slug}.md`"
+   - "Share with the Dev team and link in your issue tracker."
+   - "To customize the bug report format, edit `_templates/bug-report.md`"