bms-speckit-plugin 5.3.0 → 6.0.0

package/blueprints/bms-speckit-pipeline.yaml

@@ -9,14 +9,16 @@
 # to prevent loss and provide traceability per the project constitution.
 
 id: bms_speckit_development_pipeline
-version: 4.3.0
+version: 5.0.0
 name: BMS Speckit Automated Development Pipeline
 description: >
   Full engineering workflow from requirement to verified implementation.
-  Chains brainstorming, constitution, specification, planning, task generation,
-  analysis, implementation (TDD), and final verification.
-  Commits after every important step. Uses knowledge-mcp during brainstorm
-  and specify steps to ground specs in real HOSxP data.
+  Chains brainstorming, external research, constitution, specification,
+  planning, task generation, analysis, implementation (TDD), and final
+  verification. Commits after every important step. Uses knowledge-mcp
+  during brainstorm and specify steps to ground specs in real HOSxP data.
+  Uses WebSearch and context7 during research to survey best practices
+  and current library documentation.
 category: Development
 
 # ─── Chain Sequence ────────────────────────────────────────────────────────────
@@ -51,7 +53,50 @@ chain_sequence:
         system architecture. Also search bms, moph, nhso collections
         if relevant to the feature.
 
-  - step_id: step_2_constitution
+  - step_id: step_2_research
+    skill_id: internal.research
+    action: execute
+    phase: 1
+    description: >
+      Survey external best practices, recommended libraries, compliance
+      standards, and reference architectures via WebSearch and context7.
+      Produces a research brief that enriches the specification step.
+    timeout_seconds: 300
+    input:
+      source: "{{step_1_brainstorm.output}}"
+    output:
+      artifacts: [specs/*/research.md]
+    post_action:
+      commit: true
+      message: "feat(speckit): research — best practices and technology survey"
+      push: true
+    error_handling:
+      on_failure: continue
+      max_retries: 1
+    tools:
+      - WebSearch
+      - mcp__plugin_context7_context7__resolve-library-id
+      - mcp__plugin_context7_context7__query-docs
+    opinionated_prompts:
+      system_context: >
+        Research external best practices, design patterns, and recommended
+        libraries/frameworks relevant to the feature described in step 1.
+
+        1. Identify research topics from the brainstorm output.
+        2. WebSearch for best practices, architecture guidance, and proven
+           patterns for each topic.
+        3. For each technology/library identified: compare alternatives
+           (maintenance, bundle size, license), then use context7
+           resolve-library-id + query-docs to fetch current documentation.
+        4. If the feature involves sensitive data (healthcare, financial, PII),
+           research relevant compliance standards and security guidelines.
+        5. Search for similar implementations or reference architectures.
+
+        Output a research brief containing: best practices summary,
+        recommended libraries with rationale, documentation references,
+        security/compliance notes, and prior art.
+
+  - step_id: step_3_constitution
     skill_id: speckit.constitution
     action: execute
     phase: 1
@@ -84,7 +129,7 @@ chain_sequence:
         TDD is non-negotiable. Constitution must enforce testing at all levels,
         atomic commits, reusable components, and centralized business logic.
 
-  - step_id: step_3_claude_md_sync
+  - step_id: step_4_claude_md_sync
     skill_id: internal.claude_md_verify
     action: execute
     phase: 1
@@ -105,14 +150,15 @@ chain_sequence:
         Read CLAUDE.md and verify it complies with specs/constitution.md.
         Update CLAUDE.md if it conflicts with or is missing constitution rules.
 
-  - step_id: step_4_specify
+  - step_id: step_5_specify
     skill_id: speckit.specify
     action: execute
     phase: 1
-    description: Create feature specification enriched with HOSxP knowledge
+    description: Create feature specification enriched with HOSxP knowledge and research findings
     timeout_seconds: 300
     input:
       requirement: "{{step_1_brainstorm.output}}"
+      research: "{{step_2_research.output}}"
     output:
       artifacts: [specs/*/spec.md]
     post_action:
@@ -126,19 +172,22 @@ chain_sequence:
       system_context: >
         Generate a complete, testable specification. Include acceptance criteria,
         data models, API contracts, and edge cases.
+        Incorporate research findings from step 2 — recommended libraries,
+        best practices, and compliance requirements should be referenced
+        in the specification.
         Use mcp__bms-knowledge-mcp__search_knowledge to search the hosxp
         collection for exact table names, field names, data types, and
         relationships needed by this feature. Reference actual HOSxP
         data structures in the spec, not assumed ones.
 
-  - step_id: step_5_plan
+  - step_id: step_6_plan
     skill_id: speckit.plan
     action: execute
     phase: 1
     description: Generate implementation plan from specification
     timeout_seconds: 300
     input:
-      source: "{{step_4_specify.artifacts}}"
+      source: "{{step_5_specify.artifacts}}"
     output:
       artifacts: [specs/*/plan.md]
     post_action:
@@ -153,14 +202,14 @@ chain_sequence:
         Plan in ordered steps. Include file paths, component boundaries,
         test strategy, and rollback considerations.
 
-  - step_id: step_6_tasks
+  - step_id: step_7_tasks
     skill_id: speckit.tasks
     action: execute
     phase: 1
     description: Generate dependency-ordered task list
     timeout_seconds: 300
     input:
-      source: "{{step_5_plan.artifacts}}"
+      source: "{{step_6_plan.artifacts}}"
     output:
       artifacts: [specs/*/tasks.md]
     post_action:
@@ -175,14 +224,14 @@ chain_sequence:
         Tasks must be atomic, dependency-ordered, and each independently testable.
         Include clear acceptance criteria per task.
 
-  - step_id: step_7_analyze
+  - step_id: step_8_analyze
     skill_id: speckit.analyze
     action: execute
     phase: 1
     description: Cross-artifact consistency and quality check
     timeout_seconds: 300
     input:
-      source: "{{step_6_tasks.artifacts}}"
+      source: "{{step_7_tasks.artifacts}}"
     output:
       artifacts: [analysis_report]
     post_action:
@@ -194,12 +243,14 @@ chain_sequence:
       max_retries: 1
     opinionated_prompts:
       system_context: >
-        Check spec ↔ plan ↔ tasks consistency. Flag gaps, contradictions,
-        and missing test coverage. Non-destructive — report only.
+        Check spec ↔ plan ↔ tasks ↔ research consistency. Flag gaps,
+        contradictions, and missing test coverage. Verify that research
+        recommendations are reflected in the spec and plan.
+        Non-destructive — report only.
 
   # ── Phase 2: Implementation (main context) ────────────────────────────────
 
-  - step_id: step_8_compact
+  - step_id: step_9_compact
     skill_id: internal.compact
     action: execute
     phase: 2
@@ -209,7 +260,7 @@ chain_sequence:
       on_failure: continue
       max_retries: 0
 
-  - step_id: step_9_implement_with_rolling_qc
+  - step_id: step_10_implement_with_rolling_qc
     skill_id: speckit.implement
     action: execute_loop
     phase: 2
@@ -219,7 +270,7 @@ chain_sequence:
       next task. Catches bugs at the source, not at the end.
     timeout_seconds: 3600
     input:
-      tasks_path: "{{step_6_tasks.artifacts}}"
+      tasks_path: "{{step_7_tasks.artifacts}}"
       loop_engine: ralph-loop
       completion_promise: "FINISHED"
       max_iterations: 10
@@ -256,19 +307,19 @@ chain_sequence:
         validation pass. Apply improvements, re-run all tests, confirm zero
         regression. Only output FINISHED after everything is validated.
 
-  - step_id: step_10_final_quality_gate
+  - step_id: step_11_final_quality_gate
     agent_id: bms-speckit:quality-control
     action: dispatch_agent
     phase: 2
     description: >
       Final comprehensive QC sweep by the quality-control agent. Since inline
       QC already caught per-task issues, this focuses on cross-cutting concerns:
-      dependency health, deep security audit, overall UX consistency, and
-      accessibility compliance.
+      dependency health, deep security audit, overall UX consistency,
+      accessibility compliance, and deployment artifact validation.
     timeout_seconds: 900
     post_action:
       commit: true
-      message: "fix(speckit): final QC — security, deps, UX consistency, accessibility"
+      message: "fix(speckit): final QC — security, deps, UX consistency, accessibility, deployment"
       push: true
     error_handling:
       on_failure: stop
@@ -284,10 +335,14 @@ chain_sequence:
            all features, empty states, responsive design
         D. Accessibility — alt text, form labels, keyboard nav, heading hierarchy
         E. Integration check — verify all components work together end-to-end
+        F. Deployment artifacts — Dockerfile lint, base image CVE check via
+           WebSearch, docker-compose validation, .dockerignore, CI/CD configs
+           (skipped if no deployment files exist)
         Fix everything possible. Flag major dependency updates for user review.
-        Only proceed to merge when all checks pass.
+        Proceed to merge unless unfixed build errors, test failures, or
+        critical security vulnerabilities remain.
 
-  - step_id: step_11_merge
+  - step_id: step_12_merge
     skill_id: internal.git_merge_to_main
     action: execute
     phase: 2
@@ -308,22 +363,26 @@ chain_sequence:
 metadata:
   author: manoirx
   created_at: "2026-03-29"
-  tags: [speckit, tdd, workflow, development, chain, engineering, hosxp, knowledge]
-  estimated_duration_seconds: 6000
+  updated_at: "2026-04-02"
+  tags: [speckit, tdd, workflow, development, chain, engineering, hosxp, knowledge, research]
+  estimated_duration_seconds: 6300
   commit_strategy: per_step
   knowledge_collections:
     hosxp: "Data dictionaries, ER diagrams, table schemas, module architecture"
     bms: "BMS tools, organization, API info"
     moph: "Ministry of Public Health regulations"
     nhso: "NHSO reimbursement rules and announcements"
+  external_research:
+    websearch: "Best practices, library comparisons, compliance standards, reference architectures"
+    context7: "Current library documentation and API references"
   phases:
     phase_1:
       name: Specification & Planning
-      steps: [step_1 through step_7]
+      steps: [step_1 through step_8]
       execution: subagent
       reason: Preserve main context window for implementation
     phase_2:
       name: Implementation & Verification & Merge
-      steps: [step_8 through step_11]
+      steps: [step_9 through step_12]
       execution: main_context
       reason: Implementation needs full tool access and ralph-loop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bms-speckit-plugin",
-  "version": "5.3.0",
+  "version": "6.0.0",
   "description": "Chain-orchestrated development pipeline: /bms-speckit takes requirements and runs brainstorm → constitution → specify → plan → tasks → analyze → implement → verify with per-step error handling",
   "files": [
     ".claude-plugin/",

package/skills/bms-speckit-auto/SKILL.md

@@ -14,7 +14,7 @@ Chain blueprint: `blueprints/bms-speckit-pipeline.yaml`
 3. On step failure, check the **error policy** before proceeding:
    - `on_failure: stop` → halt the chain and report which step failed
    - `on_failure: continue` → log the failure and proceed to next step
-4. Pass `$ARGUMENTS` (the user's requirement) to step 1 (brainstorm). Step 4 (specify) receives the **output from step 1**
+4. Pass `$ARGUMENTS` (the user's requirement) to step 1 (brainstorm). Step 5 (specify) receives the **output from step 1 enriched by step 2 research**
 5. **Commit and push after every important step** — each artifact-producing step must commit its output before proceeding to the next step
 6. **Report progress** to the user at every step transition
 7. Do NOT ask for confirmation between steps
@@ -27,16 +27,17 @@ Before dispatching the Phase 1 subagent, create a progress tracker so the user c
 
 ```
 TaskCreate: "Step 1: Brainstorm — explore requirements"
-TaskCreate: "Step 2: Constitution — engineering principles"
-TaskCreate: "Step 3: CLAUDE.md sync"
-TaskCreate: "Step 4: Specify — feature specification"
-TaskCreate: "Step 5: Plan — implementation plan"
-TaskCreate: "Step 6: Tasks — task list"
-TaskCreate: "Step 7: Analyze — consistency check"
-TaskCreate: "Step 8: Compact context"
-TaskCreate: "Step 9: Implement with rolling QC"
-TaskCreate: "Step 10: Final quality gate"
-TaskCreate: "Step 11: Merge to main"
+TaskCreate: "Step 2: Research — best practices & technology survey"
+TaskCreate: "Step 3: Constitution — engineering principles"
+TaskCreate: "Step 4: CLAUDE.md sync"
+TaskCreate: "Step 5: Specify — feature specification"
+TaskCreate: "Step 6: Plan — implementation plan"
+TaskCreate: "Step 7: Tasks — task list"
+TaskCreate: "Step 8: Analyze — consistency check"
+TaskCreate: "Step 9: Compact context"
+TaskCreate: "Step 10: Implement with rolling QC"
+TaskCreate: "Step 11: Final quality gate"
+TaskCreate: "Step 12: Merge to main"
 ```
 
 Then output a message to the user:
@@ -57,14 +58,14 @@ You are running the BMS Speckit specification and planning chain. Execute each s
 
 **IMPORTANT — Progress reporting:** Before starting each step, output a progress message to the user in this format:
 
-`[Step N/11] step_name — description...`
+`[Step N/12] step_name — description...`
 
 After completing each step, output:
 
-`[Step N/11] DONE — brief result summary`
+`[Step N/12] DONE — brief result summary`
 
 ### Step 1 — Brainstorm `[on_failure: STOP]`
-- **Progress:** Output `[Step 1/11] Brainstorm — exploring requirements and design...`
+- **Progress:** Output `[Step 1/12] Brainstorm — exploring requirements and design...`
 - **Skill:** `superpowers.brainstorm`
 - **Input:** "$ARGUMENTS"
 - **Purpose:** Explore intent, requirements, design alternatives, and edge cases
@@ -72,66 +73,88 @@ After completing each step, output:
 - **Output:** Detailed specification document
 - **Timeout:** 300s
 - **Post-action:** Commit all files and push. Message: `feat(speckit): brainstorm — explore requirements and design`
-- **Done:** Output `[Step 1/11] DONE — brainstorm complete`
+- **Done:** Output `[Step 1/12] DONE — brainstorm complete`
 
-### Step 2 — Constitution `[on_failure: STOP]`
-- **Progress:** Output `[Step 2/11] Constitution — establishing engineering principles...`
+### Step 2 — Research `[on_failure: CONTINUE]`
+- **Progress:** Output `[Step 2/12] Research — surveying best practices and technologies...`
+- **Purpose:** Research external best practices, proven patterns, recommended libraries/frameworks, and informative reference material relevant to the user's requirement. This grounds the pipeline in current industry knowledge before specification begins.
+- **Tools:** Use `WebSearch` and `mcp__plugin_context7_context7__resolve-library-id` + `mcp__plugin_context7_context7__query-docs` for library documentation
+- **Timeout:** 300s
+- **Process:**
+  1. **Identify research topics** from Step 1 output — extract key technologies, patterns, and domains that need external validation
+  2. **Best practices search** — WebSearch for best practices, design patterns, and architecture guidance relevant to the feature (e.g., "real-time dashboard best practices", "patient data security standards", "React table performance optimization")
+  3. **Library/framework survey** — For each technology identified in brainstorm:
+     - WebSearch for current recommended libraries, compare alternatives (stars, maintenance, bundle size, license)
+     - Use context7 `resolve-library-id` then `query-docs` to fetch current documentation for top candidates
+  4. **Security & compliance research** — If the feature involves sensitive data (healthcare, financial, PII), search for relevant compliance standards and security guidelines
+  5. **Prior art** — Search for similar implementations, open-source examples, or reference architectures that inform the design
+- **Output:** A research brief saved as `specs/*/research.md` containing:
+  - **Best practices summary** — key patterns and principles to follow
+  - **Recommended libraries** — with rationale (why this over alternatives)
+  - **Documentation references** — links and key API details from context7
+  - **Security/compliance notes** — standards to adhere to (if applicable)
+  - **Prior art** — reference implementations or architectures found
+- **Post-action:** Commit all files and push. Message: `feat(speckit): research — best practices and technology survey`
+- **Done:** Output `[Step 2/12] DONE — research brief created (N topics researched)`
+
+### Step 3 — Constitution `[on_failure: STOP]`
+- **Progress:** Output `[Step 3/12] Constitution — establishing engineering principles...`
 - **Skill:** `speckit.constitution`
 - **Input:** "Establish and enforce a comprehensive set of engineering principles that prioritize high code quality, strict adherence to Test-Driven Development (TDD) practices, and well-defined testing standards across unit, component, integration, and API levels to ensure system reliability and maintainability, maintain a consistent, user-friendly, and professional user interface aligned with strong user experience (UX) guidelines, optimize application performance through efficient architecture and resource management; enforce disciplined version control practices with frequent, atomic commits to minimize risk and improve traceability, promote the development and reuse of modular components and functions while centralizing business logic to avoid duplication and ensure consistency, provide clear, informative user feedback and progress reporting throughout system interactions, and leverage all available tools, frameworks, and domain-specific expertise to support developers in delivering robust, scalable, and high-quality applications."
 - **Output:** `specs/constitution.md`
 - **Timeout:** 300s
-- **Done:** Output `[Step 2/11] DONE — constitution created`
+- **Done:** Output `[Step 3/12] DONE — constitution created`
 
-### Step 3 — CLAUDE.md Sync `[on_failure: CONTINUE]`
-- **Progress:** Output `[Step 3/11] CLAUDE.md Sync — verifying compliance...`
+### Step 4 — CLAUDE.md Sync `[on_failure: CONTINUE]`
+- **Progress:** Output `[Step 4/12] CLAUDE.md Sync — verifying compliance...`
 - **Action:** Read CLAUDE.md and verify it complies with the constitution in `specs/constitution.md`. Update CLAUDE.md if it conflicts with or is missing constitution rules.
 - **Timeout:** 120s
 - **Post-action:** Commit all files and push. Message: `feat(speckit): add constitution and sync CLAUDE.md`
-- **Done:** Output `[Step 3/11] DONE — CLAUDE.md synced`
+- **Done:** Output `[Step 4/12] DONE — CLAUDE.md synced`
 
-### Step 4 — Specify `[on_failure: STOP]`
-- **Progress:** Output `[Step 4/11] Specify — creating feature specification...`
+### Step 5 — Specify `[on_failure: STOP]`
+- **Progress:** Output `[Step 5/12] Specify — creating feature specification...`
 - **Skill:** `speckit.specify`
-- **Input:** Use the detailed specification output from Step 1 (brainstorm) as the argument
+- **Input:** Use the detailed specification output from Step 1 (brainstorm) **enriched with the research findings from Step 2**. Include recommended libraries, best practices, and compliance requirements from the research brief in the specification input.
 - **Knowledge lookup:** Use `mcp__bms-knowledge-mcp__search_knowledge` to search the `hosxp` collection for exact table names, field names, data types, and relationships needed by this feature. Reference actual HOSxP data structures in the spec.
 - **Output:** `specs/*/spec.md`
 - **Timeout:** 300s
 - **Retry:** up to 2 attempts
 - **Post-action:** Commit all files and push. Message: `feat(speckit): add feature specification`
-- **Done:** Output `[Step 4/11] DONE — specification created`
+- **Done:** Output `[Step 5/12] DONE — specification created`
 
-### Step 5 — Plan `[on_failure: STOP]`
-- **Progress:** Output `[Step 5/11] Plan — generating implementation plan...`
+### Step 6 — Plan `[on_failure: STOP]`
+- **Progress:** Output `[Step 6/12] Plan — generating implementation plan...`
 - **Skill:** `speckit.plan`
-- **Input:** reads from step 4 artifacts
+- **Input:** reads from step 5 artifacts
 - **Output:** `specs/*/plan.md`
 - **Timeout:** 300s
 - **Retry:** up to 2 attempts
 - **Post-action:** Commit all files and push. Message: `feat(speckit): add implementation plan`
-- **Done:** Output `[Step 5/11] DONE — plan created`
+- **Done:** Output `[Step 6/12] DONE — plan created`
 
-### Step 6 — Tasks `[on_failure: STOP]`
-- **Progress:** Output `[Step 6/11] Tasks — generating task list...`
+### Step 7 — Tasks `[on_failure: STOP]`
+- **Progress:** Output `[Step 7/12] Tasks — generating task list...`
 - **Skill:** `speckit.tasks`
-- **Input:** reads from step 5 artifacts
+- **Input:** reads from step 6 artifacts
 - **Output:** `specs/*/tasks.md`
 - **Timeout:** 300s
 - **Retry:** up to 2 attempts
 - **Post-action:** Commit all files and push. Message: `feat(speckit): add task list`
-- **Done:** Output `[Step 6/11] DONE — N tasks created`
+- **Done:** Output `[Step 7/12] DONE — N tasks created`
 
-### Step 7 — Analyze `[on_failure: CONTINUE]`
-- **Progress:** Output `[Step 7/11] Analyze — cross-artifact consistency check...`
+### Step 8 — Analyze `[on_failure: CONTINUE]`
+- **Progress:** Output `[Step 8/12] Analyze — cross-artifact consistency check...`
 - **Skill:** `speckit.analyze`
-- **Purpose:** Cross-artifact consistency check (spec ↔ plan ↔ tasks). Non-destructive — report only.
+- **Purpose:** Cross-artifact consistency check (spec ↔ plan ↔ tasks ↔ research). Non-destructive — report only.
 - **Timeout:** 300s
 - **Post-action:** Commit all files and push. Message: `feat(speckit): add cross-artifact analysis report`
-- **Done:** Output `[Step 7/11] DONE — analysis complete`
+- **Done:** Output `[Step 8/12] DONE — analysis complete`
 
 After all steps complete, return: the feature name, number of tasks created, and the path to tasks.md.
 """
 
-After the subagent completes, update tasks 1-7 as completed using TaskUpdate, then output:
+After the subagent completes, update tasks 1-8 as completed using TaskUpdate, then output:
 
 > Phase 1 complete. N tasks created at specs/feature-name/tasks.md
 > Starting Phase 2 (implementation)...
@@ -142,13 +165,13 @@ After the subagent completes, update tasks 1-7 as completed using TaskUpdate, th
 
 > **Execution context:** Runs in main context after subagent completes.
 
-### Step 8 — Compact `[on_failure: CONTINUE]`
-- **Progress:** Output `[Step 8/11] Compact — freeing context window...`
+### Step 9 — Compact `[on_failure: CONTINUE]`
+- **Progress:** Output `[Step 9/12] Compact — freeing context window...`
 - **Action:** Run `/compact` to free context window before implementation.
-- **Done:** Update task 8 as completed.
+- **Done:** Update task 9 as completed.
 
-### Step 9 — Implement with Rolling QC `[on_failure: CONTINUE | max_retries: 3]`
-- **Progress:** Output `[Step 9/11] Implement — starting rolling QC loop (N tasks)...`
+### Step 10 — Implement with Rolling QC `[on_failure: CONTINUE | max_retries: 3]`
+- **Progress:** Output `[Step 10/12] Implement — starting rolling QC loop (N tasks)...`
 - **Engine:** ralph-loop
 - **Input:** Use the **tasks.md path returned by the Phase 1 subagent** (e.g. `specs/my-feature/tasks.md`). Replace `{TASKS_PATH}` below with the actual path.
 - **Completion promise:** `FINISHED`
@@ -164,10 +187,10 @@ After the subagent completes, update tasks 1-7 as completed using TaskUpdate, th
 
 `/ralph-loop:ralph-loop "systematically execute speckit.implement via the Skill tool to complete every task defined in {TASKS_PATH} with strict adherence to specification requirements. IMPORTANT: apply rolling QC after EACH task — after implementing a task run build and fix build errors, run linter and fix lint errors, run ALL tests (not just new ones) and fix failures, check for hardcoded secrets and injection vulnerabilities in code you just wrote, verify UI code has actionable error messages and loading states — only commit when build plus lint plus tests all pass with zero errors then proceed to next task. Report progress to the user after each task: output [Task N/total] DONE — task_name. Do NOT batch QC at the end. Maintain atomic commits after each successful task with clear traceability, avoid requesting confirmation and proceed autonomously, once all tasks are implemented invoke speckit.analyze via the Skill tool to perform a full validation pass, automatically apply all recommended improvements or corrections, re-run all tests to confirm stability and zero regression, and only output <promise>FINISHED</promise> after every task is fully completed, validated, and aligned with production-grade quality standards" --completion-promise "FINISHED" --max-iterations 10`
 
-- **Done:** Update task 9 as completed. Output `[Step 9/11] DONE — all tasks implemented and verified`
+- **Done:** Update task 10 as completed. Output `[Step 10/12] DONE — all tasks implemented and verified`
 
-### Step 10 — Final Quality Gate `[on_failure: STOP | max_retries: 3]`
-- **Progress:** Output `[Step 10/11] Final QC — running comprehensive quality audit...`
+### Step 11 — Final Quality Gate `[on_failure: STOP | max_retries: 3]`
+- **Progress:** Output `[Step 11/12] Final QC — running comprehensive quality audit...`
 - **Agent:** Dispatch `bms-speckit:quality-control` agent
 - **Purpose:** Final comprehensive sweep. Since inline QC already caught per-task issues, this focuses on **cross-cutting concerns** that can only be detected across the full codebase.
 - **Timeout:** 900s
@@ -179,15 +202,15 @@ After the subagent completes, update tasks 1-7 as completed using TaskUpdate, th
   - **E. Integration check** — verify all components work together end-to-end
   - **F. Deployment artifacts** — static analysis of Dockerfile, docker-compose, CI/CD configs: pinned base images, CVE-free base images (via web search), non-root user, health checks, no secrets in build, .dockerignore coverage (skipped if no deployment files exist)
 - The agent fixes everything it can. Major dependency updates are flagged for user review.
-- **Completion rule:** When the QC agent returns its report, proceed to Step 11 **unless** the report contains unfixed build errors, unfixed test failures, or unfixed critical security vulnerabilities. Informational findings, flagged-for-review items, and already-fixed issues do NOT block progression. If uncertain, proceed — the QC agent already fixed what it could.
+- **Completion rule:** When the QC agent returns its report, proceed to Step 12 **unless** the report contains unfixed build errors, unfixed test failures, or unfixed critical security vulnerabilities. Informational findings, flagged-for-review items, and already-fixed issues do NOT block progression. If uncertain, proceed — the QC agent already fixed what it could.
 - **Post-action:** Commit all fixes and push. Message: `fix(speckit): final QC — security, deps, UX consistency, accessibility`
-- **Done:** Update task 10 as completed. Output `[Step 10/11] DONE — quality gate passed`
+- **Done:** Update task 11 as completed. Output `[Step 11/12] DONE — quality gate passed`
 
-### Step 11 — Merge to Main `[on_failure: STOP]`
-- **Progress:** Output `[Step 11/11] Merge — merging to main branch...`
+### Step 12 — Merge to Main `[on_failure: STOP]`
+- **Progress:** Output `[Step 12/12] Merge — merging to main branch...`
 - **Action:** Switch to main branch, merge the feature branch (fast-forward if possible), push main to remote, then clean up the feature branch.
 - **Timeout:** 120s
-- **Done:** Update task 11 as completed. Output:
+- **Done:** Update task 12 as completed. Output:
 
 > Pipeline complete! Feature merged to main.
 
@@ -198,13 +221,15 @@ After the subagent completes, update tasks 1-7 as completed using TaskUpdate, th
 ```
 Phase 1 (subagent)                          Phase 2 (main context)
 ──────────────────────────────              ──────────────────────────────
-Step 1: brainstorm ──STOP── commit          Step 8:  compact
-        + knowledge search (hosxp)          Step 9:  implement + rolling QC
-Step 2: constitution ─STOP─┐                         ┌─ implement task ─┐
-Step 3: CLAUDE.md sync ───┘ commit                   │  inline QC       │
-Step 4: specify ──────STOP── commit                  │  fix → commit    │
-        + knowledge search (hosxp)                   └─ next task ──────┘
-Step 5: plan ─────────STOP── commit         Step 10: final QC agent ── commit
-Step 6: tasks ────────STOP── commit                  (security/deps/UX/a11y)
-Step 7: analyze ──────────── commit         Step 11: merge to main + push
+Step 1: brainstorm ──STOP── commit          Step 9:  compact
+        + knowledge search (hosxp)          Step 10: implement + rolling QC
+Step 2: research ────────── commit                   ┌─ implement task ─┐
+        + WebSearch + context7                       │  inline QC       │
+Step 3: constitution ─STOP─┐                         │  fix → commit    │
+Step 4: CLAUDE.md sync ───┘ commit                   └─ next task ──────┘
+Step 5: specify ──────STOP── commit         Step 11: final QC agent ── commit
+        + knowledge search (hosxp)                   (security/deps/UX/a11y/deploy)
+Step 6: plan ─────────STOP── commit         Step 12: merge to main + push
+Step 7: tasks ────────STOP── commit
+Step 8: analyze ──────────── commit
 ```