prizmkit 1.0.122 → 1.0.124

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -31,38 +31,6 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 {{GLOBAL_CONTEXT}}
 
-{{IF_MODE_SELF_EVOLVE}}
-## Framework Self-Development Context
-
-**You are developing the PrizmKit framework itself.** This is NOT a regular project — you are modifying the tool that powers this pipeline. Extra guardrails apply.
-
-### Framework Structure
-
-```
-core/skills/          — Skill definitions (each has _metadata.json)
-core/agents/          — Agent .md definitions (YAML frontmatter required)
-core/team/            — Team config (dev repo only, NOT installed)
-dev-pipeline/         — Pipeline scripts + templates (installed with --pipeline)
-  templates/          — Bootstrap prompt templates (tier1/2/3)
-  scripts/            — Python/bash pipeline scripts
-create-prizmkit/      — npm package / CLI installer
-  bundled/            — Pre-bundled assets (auto-generated, NEVER edit directly)
-tests/                — Validation + unit tests
-```
-
-### 5 Key Invariants (MUST be preserved)
-
-1. **Skill ↔ _metadata.json 1:1 mapping**: Every directory in `core/skills/` MUST have a `_metadata.json`. Every `_metadata.json` must reference an existing skill directory.
-2. **Template variables resolve completely**: All `{{PLACEHOLDER}}` in `dev-pipeline/templates/` must be resolvable by `generate-bootstrap-prompt.py`. No unresolved placeholders in output.
-3. **Agent YAML frontmatter is valid**: Every `.md` in `core/agents/` must have valid YAML frontmatter with required fields (name, description, tools).
-4. **Bundle is generated, never hand-edited**: `create-prizmkit/bundled/` is auto-generated by `scripts/bundle.js`. Manual edits will be overwritten.
-5. **CI must pass**: `npm run ci` (validate-all + bundle + verify-bundle + eslint + vitest) must pass after every change.
-
-### Version Isolation
-
-LLM context is frozen at prompt time. Modifying a skill source file during this session will NOT change the behavior of that skill within this session. The real risk is structural inconsistency.
-{{END_IF_MODE_SELF_EVOLVE}}
-
 ## ⚠️ Context Budget Rules (CRITICAL — read before any phase)
 
 You are running in headless mode with a FINITE context window. Exceeding it will crash the session and lose all work. Follow these rules strictly:
@@ -165,9 +133,9 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 - `context-snapshot.md` exists → use it directly, skip Phase 1
 - Some missing → generate only missing files
 
-Before planning, check whether feature code already exists in the project:
+Before planning, check whether feature code already exists in the project (search in source directories identified from `root.prizm` or the project tree scan):
 ```bash
-grep -r "{{FEATURE_SLUG}}" src/ --include="*.js" --include="*.ts" -l 2>/dev/null | head -20
+grep -r "{{FEATURE_SLUG}}" . --include="*.js" --include="*.ts" --include="*.py" --include="*.go" --include="*.java" --include="*.rb" --include="*.rs" -l --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor --exclude-dir=.prizmkit 2>/dev/null | head -20
 ```
 
 Record result as `EXISTING_CODE` (list of files, or empty).
@@ -177,8 +145,13 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
 1. Read `.prizm-docs/root.prizm` and relevant L1/L2 prizm docs
-2. Scan `src/` for files related to this feature; read each one
-3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
+2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
+   ```bash
+   find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
+   ```
+   Identify the top-level source directories from the results.
+3. Scan the detected source directories for files related to this feature; read each one
+4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
    - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
      ```bash
@@ -189,12 +162,12 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
      ### Files to Modify
      | File | Why Needed | Key Interfaces |
      |------|-----------|----------------|
-     | `src/config.js` | Add runtime config layer | `config` (Zod object), `configSchema` |
+     | `<source-dir>/config.js` | Add runtime config layer | `config` (Zod object), `configSchema` |
 
      ### Files for Reference
      | File | Why Needed | Key Interfaces |
      |------|-----------|----------------|
-     | `src/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
+     | `<source-dir>/security/permission-guard.js` | Permission check integration | `checkCommandPermission(userId, cmd)` |
 
      ### Known TRAPS (from .prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
@@ -214,6 +187,13 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/spec.md .prizmkit/specs/{{FEATURE_SLUG}}/pla
 
 > All files go under `.prizmkit/specs/{{FEATURE_SLUG}}/`. Confirm each with `ls` after writing.
 
+**Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
+Before proceeding past CP-1, verify:
+1. Plan.md Data Model section references existing schema/model files (scan for `*.prisma`, `*.sql`, `migrations/`, `models/`, `*.entity.*` files; read them if not already in context-snapshot)
+2. All new tables/fields follow existing naming conventions, ID strategy, timestamp patterns, and constraint style
+3. No `[NEEDS CLARIFICATION]` remains in Data Model section — resolve by reading existing code and making a conservative choice that matches existing patterns. Document the resolution in plan.md.
+4. If a DB design decision genuinely cannot be resolved from existing code alone, document the assumption made and flag it in the Implementation Log for user review.
+
 **CP-1**: Both spec.md and plan.md exist.
 
 ### Phase 3: Analyze — Reviewer Agent
@@ -232,6 +212,54 @@ Wait for Reviewer to return.
 
 **CP-2**: No CRITICAL issues.
 
+{{IF_CRITIC_ENABLED}}
+### Phase 3.5: Plan Challenge — Critic Agent(s)
+
+**Guard**: Verify critic agent file exists before spawning:
+```bash
+ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+```
+If CRITIC:MISSING — skip Phase 3.5 entirely and proceed to Phase 4. Log: "Critic agent not installed — skipping Plan Challenge."
+
+**Choose ONE path based on `{{CRITIC_COUNT}}`:**
+
+**If {{CRITIC_COUNT}} = 1 → Single Critic** (skip to CP-2.5 after this):
+
+Spawn Critic agent (Agent tool, subagent_type="prizm-dev-team-critic", run_in_background=false).
+
+Prompt:
+> "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
+> **MODE: Plan Challenge**
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
+> 2. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
+> 3. Read existing source files in the modules this plan touches.
+> 4. Challenge plan.md against the project's existing architecture, patterns, and style.
+> Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."
+
+**If {{CRITIC_COUNT}} = 3 → Multi-Critic Voting** (skip Single Critic above):
+
+Spawn 3 Critic agents sequentially (each with run_in_background=false), each with a different focus lens:
+
+Critic-A prompt (append to base prompt above):
+> "**Focus Lens: Architecture & Scalability.** Prioritize: architectural pattern fit, scalability implications, over-engineering risks, component boundary design.
+> Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report-A.md`."
+
+Critic-B prompt (append to base prompt above):
+> "**Focus Lens: Data Model & Edge Cases.** Prioritize: data model design fit, entity relationships, edge cases in business logic, missing boundary conditions.
+> Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report-B.md`."
+
+Critic-C prompt (append to base prompt above):
+> "**Focus Lens: Security & Performance.** Prioritize: security attack surface, authentication/authorization gaps, performance bottlenecks, resource leaks.
+> Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report-C.md`."
+
+After all critics return, read all 3 reports:
+- Challenge raised by **2/3 or more** critics → **must respond** (adjust plan or justify why not)
+- Challenge raised by **1/3 only** → logged in context-snapshot but not blocking
+- Max 1 plan revision round.
+
+**CP-2.5**: Plan challenges reviewed and resolved.
+{{END_IF_CRITIC_ENABLED}}
+
 ### Phase 4: Implement — Dev Agent
 
 **Build artifacts rule** (passed to Dev): After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary or build directory is in `.gitignore`. Never commit compiled binaries, build output, or generated artifacts.
@@ -245,17 +273,6 @@ grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || echo
 
 Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false).
 
-{{IF_MODE_SELF_EVOLVE}}
-**Framework Self-Evolve — Dev Extra Instructions**:
-Append the following to the Dev agent prompt:
-> "FRAMEWORK RULES (self-evolve mode):
-> - If you modify any file in `core/skills/`, also update `_metadata.json` in the same skill directory.
-> - If you modify `dev-pipeline/templates/*.md`, verify all `{{PLACEHOLDER}}` markers have matching entries in `generate-bootstrap-prompt.py`.
-> - Before marking implementation complete, run `node tests/validate-all.js` and fix any failures.
-> - NEVER directly modify files in `create-prizmkit/bundled/` — those are auto-generated by `scripts/bundle.js`.
-> - If you modify any file in `dev-pipeline/scripts/` or `dev-pipeline/templates/` or `core/skills/` that this pipeline uses, note this in your Implementation Log for reload_needed tracking."
-{{END_IF_MODE_SELF_EVOLVE}}
-
 Prompt:
 > "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}) using TDD.
 > **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
@@ -294,22 +311,37 @@ Wait for Dev to return. **If Dev times out before all tasks are `[x]`**:
 
 All tasks `[x]`, tests pass.
 
+{{IF_CRITIC_ENABLED}}
+### Phase 4.5: Code Challenge — Critic Agent
+
+**Guard**: Verify critic agent file exists before spawning:
+```bash
+ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+```
+If CRITIC:MISSING — skip Phase 4.5 entirely and proceed to Phase 5. Log: "Critic agent not installed — skipping Code Challenge."
+
+Spawn Critic agent (Agent tool, subagent_type="prizm-dev-team-critic", run_in_background=false).
+
+Prompt:
+> "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
+> **MODE: Code Challenge**
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Implementation Log section shows what Dev changed.
+> 2. Read `.prizm-docs/root.prizm` and relevant module docs for RULES/PATTERNS.
+> 3. Read the actual source files changed (from Implementation Log).
+> 4. Read comparable existing source files in the same module for style comparison.
+> 5. Challenge code integration quality: style fit, robustness, existing code cohesion, hidden impact.
+> Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` (overwrite) with findings (or 'No significant challenges')."
+
+Wait for Critic to return.
+- Read challenge-report.md. For items marked CRITICAL/HIGH: spawn Dev to fix, then proceed to Review.
+
+**CP-3.5**: Code challenges reviewed and resolved.
+{{END_IF_CRITIC_ENABLED}}
+
 ### Phase 5: Review + Test — Reviewer Agent
 
 Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false).
 
-{{IF_MODE_SELF_EVOLVE}}
-**Framework Self-Evolve — Reviewer Extra Instructions**:
-Append the following to the Reviewer agent prompt:
-> "FRAMEWORK REVIEW DIMENSIONS (self-evolve mode):
-> In addition to standard code review, check:
-> 1. **Structural integrity**: Every `core/skills/*/` must have `_metadata.json`. Run `node tests/validate-all.js` to verify.
-> 2. **Template safety**: If any `dev-pipeline/templates/*.md` was modified, check that all `{{PLACEHOLDER}}` markers are properly balanced (open/close) and resolvable.
-> 3. **Agent frontmatter**: If any `core/agents/*.md` was modified, validate YAML frontmatter has required fields (name, description, tools).
-> 4. **CI gate**: Run `npm run ci` and report the result. Any failure is CRITICAL.
-> 5. **Bundle safety**: Verify no files in `create-prizmkit/bundled/` were directly modified (check `git diff --name-only` for bundled/ changes)."
-{{END_IF_MODE_SELF_EVOLVE}}
-
 Prompt:
 > "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 > **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
@@ -346,20 +378,6 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 
 ### Phase 6: Retrospective & Commit (SINGLE COMMIT) — DO NOT SKIP
 
-{{IF_MODE_SELF_EVOLVE}}
-**Framework Validation Gate (self-evolve mode)**:
-
-Before proceeding with commit, run the full framework CI pipeline:
-
-```bash
-bash {{VALIDATOR_SCRIPTS_DIR}}/validate-framework.sh
-```
-
-- If ALL steps pass → proceed with commit below.
-- If any step fails → fix the issue and re-run. Maximum 2 fix-and-retry rounds.
-- After 2 failed rounds → exit and let the pipeline runner handle the failure.
-{{END_IF_MODE_SELF_EVOLVE}}
-
 **For bug fixes**: run `/prizmkit-retrospective` for structural sync only (skip knowledge injection unless a new TRAPS was discovered). Use `fix(<scope>):` commit prefix.
 
 **6a.** Check if feature already committed:
@@ -403,6 +421,9 @@ Working tree MUST be clean after this step. If any feature-related files remain,
 | Team Config | `{{TEAM_CONFIG_PATH}}` |
 | Dev Agent Def | {{DEV_SUBAGENT_PATH}} |
 | Reviewer Agent Def | {{REVIEWER_SUBAGENT_PATH}} |
+{{IF_CRITIC_ENABLED}}
+| Critic Agent Def | {{CRITIC_SUBAGENT_PATH}} |
+{{END_IF_CRITIC_ENABLED}}
 | Project Root | {{PROJECT_ROOT}} |
 | Feature List Path | {{FEATURE_LIST_PATH}} |
 

package/bundled/dev-pipeline/templates/feature-list-schema.json

@@ -100,6 +100,16 @@
           "model": {
             "type": "string",
             "description": "AI model ID for this feature. Overrides $MODEL env var."
+          },
+          "critic": {
+            "type": "boolean",
+            "description": "Enable adversarial critic review for this feature. Default: false.",
+            "default": false
+          },
+          "critic_count": {
+            "type": "integer",
+            "description": "Number of parallel critic agents. 1 = single critic, 3 = multi-critic voting. Default: 1.",
+            "enum": [1, 3]
           }
         }
       }

package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py

@@ -192,16 +192,20 @@ class TestProcessModeBlocks:
         result = process_mode_blocks(tpl, "standard", init_done=False)
         assert "need init" in result
 
-    def test_self_evolve_keeps_self_evolve_and_full(self):
-        tpl = (
-            "{{IF_MODE_SELF_EVOLVE}}se content{{END_IF_MODE_SELF_EVOLVE}}"
-            "{{IF_MODE_FULL}}full content{{END_IF_MODE_FULL}}"
-        )
-        result = process_mode_blocks(tpl, "self-evolve", init_done=True)
-        assert "se content" in result
-        assert "full content" in result
-
-    def test_self_evolve_removes_lite(self):
-        tpl = "{{IF_MODE_LITE}}lite content{{END_IF_MODE_LITE}}"
-        result = process_mode_blocks(tpl, "self-evolve", init_done=True)
-        assert "lite content" not in result
+    def test_critic_enabled_keeps_critic_block(self):
+        tpl = "before\n{{IF_CRITIC_ENABLED}}\ncritic content\n{{END_IF_CRITIC_ENABLED}}\nafter"
+        result = process_mode_blocks(tpl, "standard", init_done=True, critic_enabled=True)
+        assert "critic content" in result
+        assert "IF_CRITIC_ENABLED" not in result
+
+    def test_critic_disabled_removes_critic_block(self):
+        tpl = "before\n{{IF_CRITIC_ENABLED}}\ncritic content\n{{END_IF_CRITIC_ENABLED}}\nafter"
+        result = process_mode_blocks(tpl, "standard", init_done=True, critic_enabled=False)
+        assert "critic content" not in result
+        assert "before" in result
+        assert "after" in result
+
+    def test_critic_default_is_disabled(self):
+        tpl = "{{IF_CRITIC_ENABLED}}critic{{END_IF_CRITIC_ENABLED}}"
+        result = process_mode_blocks(tpl, "standard", init_done=True)
+        assert "critic" not in result

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.122",
+  "version": "1.0.124",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/app-planner/SKILL.md

@@ -137,8 +137,9 @@ Execute the selected scenario workflow in conversation mode with mandatory check
 4. refine descriptions and acceptance criteria
 5. verify DAG/order/priorities
 6. build or append `feature-list.json`
-7. validate and fix until pass
-8. summarize final feature table
+7. ask whether to enable adversarial critic review for high/critical features
+8. validate and fix until pass
+9. summarize final feature table
 
 ### Checkpoints (Mandatory Gates)
 
@@ -150,8 +151,9 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
 | **CP-AP-1** | Vision Summary | Goal/users/differentiators confirmed by user | 1-2 |
 | **CP-AP-2** | Feature Proposals | Feature set with titles+deps identified (pre-validation) | 3-5 |
 | **CP-AP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 6 |
-| **CP-AP-4** | `feature-list.json` Generated | Schema validates, all required keys present | 6 |
-| **CP-AP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 7 |
+| **CP-AP-3.5** | Critic Decision | User decided on critic review for high/critical features | 7 |
+| **CP-AP-4** | `feature-list.json` Generated | Schema validates, all required keys present | 6-7 |
+| **CP-AP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 8 |
 
 **Resume Detection**: See §Resume Support for checkpoint-based resumption.
 
@@ -252,6 +254,8 @@ AI: "Ready to proceed to dev-pipeline."
 - new items default `status: "pending"`
 - English feature titles for stable slug generation
 - `model` field is optional — omitting it means the pipeline uses $MODEL env or CLI default
+- `critic` field is optional (boolean). If user requested adversarial critic review during planning, set `"critic": true` for relevant features. Omitting defaults to `false`.
+- `critic_count` field is optional (integer, 1 or 3). If omitted, defaults to 1 (single critic). Set to 3 for multi-critic voting mode on critical features.
 - **descriptions must be implementation-ready** — minimum 15 words (error), recommended 30/50/80 words for low/medium/high complexity (warning). See `planning-guide.md` §4 for what to include.
 
 ## Next-Step Execution Policy (after planning)

package/bundled/skills/app-planner/assets/evaluation-guide.md

@@ -15,9 +15,9 @@ npm run skill:review -- \
   --workspace /.codebuddy/skill-evals/app-planner-workspace \
   --iteration iteration-N \
   --skill-name app-planner \
-  --skill-path /core/skills/app-planner \
+  --skill-path ${SKILL_DIR} \
   --runs 3 \
-  --grader-cmd "python3 /core/skills/app-planner/scripts/validate-and-generate.py grade --workspace {workspace} --iteration {iteration}"
+  --grader-cmd "python3 ${SKILL_DIR}/scripts/validate-and-generate.py grade --workspace {workspace} --iteration {iteration}"
 ```
 
 Produces:

package/bundled/skills/app-planner/scripts/validate-and-generate.py

@@ -320,6 +320,18 @@ def validate_feature_list(data, planning_mode="new"):
 
         # -- Sub-features --
         subs = feat.get("sub_features")
+
+        # -- Critic fields (optional but validated if present) --
+        critic = feat.get("critic")
+        if critic is not None and not isinstance(critic, bool):
+            errors.append(
+                "{}: 'critic' must be a boolean, got {}".format(label, type(critic).__name__)
+            )
+        critic_count = feat.get("critic_count")
+        if critic_count is not None and critic_count not in (1, 3):
+            errors.append(
+                "{}: 'critic_count' must be 1 or 3, got {}".format(label, critic_count)
+            )
         if isinstance(subs, list):
             for sidx, sub in enumerate(subs):
                 sub_label = "{}->sub_features[{}]".format(label, sidx)

package/bundled/skills/bug-fix-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "bug-fix-workflow"
 tier: companion
-description: "Interactive single-bug fix in current session. Guides through triage → reproduce → fix → review → commit without the background pipeline. Use this skill when the user wants to fix one specific bug right now, interactively. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'let me fix this bug myself', 'fix this bug', 'interactive fix', 'manually fix bug'. (project)"
+description: "Interactive single-bug fix in current session. Guides through deep diagnosis Q&A → triage → reproduce → fix → review → commit without the background pipeline. Use this skill when the user wants to fix one specific bug right now, interactively. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'let me fix this bug myself', 'fix this bug', 'interactive fix', 'manually fix bug'. (project)"
 ---
 
 # Bug Fix Workflow
@@ -79,17 +79,82 @@ For trivial bugs with clear root cause and minimal scope:
 
 ---
 
-### Phase 1: Triage
+### Phase 1: Deep Bug Diagnosis — Interactive Q&A
 
-**Goal**: Understand the bug, locate affected code, classify severity.
+**Goal**: Fully understand the bug before touching any code. Vague bug reports lead to incorrect fixes that mask the real issue or introduce new bugs.
 
-1. **Gather bug info**:
-   - If bug ID given (e.g. B-001): read entry from `bug-fix-list.json`
-   - If raw error: extract error message, stack trace, affected files
-   - If description: ask clarifying questions to narrow down the issue
-2. **Read project context**: `.prizm-docs/root.prizm` → relevant L1/L2 docs for affected modules
-3. **Locate affected code**: read the files mentioned in the error/stack trace
-4. **Check known issues**: search `.prizm-docs/` TRAPS sections for matching patterns
+**CRITICAL RULE**: Ask as many questions as needed until the bug is fully understood. Do NOT rush into code. A misdiagnosed bug leads to a wrong fix, which is worse than no fix.
+
+#### Step 1.1: Initial Bug Information Gathering
+
+- If bug ID given (e.g. B-001): read entry from `bug-fix-list.json` — but DO NOT assume the description is complete
+- If raw error/stack trace: extract error message, affected files, line numbers
+- If natural language description: start the deep-dive Q&A below
+
+#### Step 1.2: Systematic Bug Clarification
+
+Ask questions across these dimensions until every aspect is clear. **Adapt to what the user has already provided** — skip questions that are already answered.
+
+**Reproduction Conditions:**
+- What exact steps trigger the bug? (step-by-step)
+- Which environment/browser/OS/version?
+- Is it reproducible every time, or intermittent?
+- When did it first appear? (after a specific change/deploy?)
+- Does it happen for all users or only specific accounts/roles/data?
+
+**Expected vs Actual Behavior:**
+- What should happen? (the correct behavior)
+- What actually happens? (the buggy behavior)
+- Is there partial functionality (e.g., works for some inputs but not others)?
+
+**Scope and Impact:**
+- Which features/pages/modules are affected?
+- Are there workarounds users are currently using?
+- Is this blocking other work?
+- Are there related symptoms elsewhere?
+
+**Data and State:**
+- What data/state triggers the issue? (specific input values, DB state, user session state)
+- Does the bug involve data corruption or just incorrect display/behavior?
+- If database-related: which tables/records are affected?
+
+**Error Details** (if not already provided):
+- Full error message and stack trace?
+- Browser console errors?
+- Server-side logs?
+- Network request/response details?
+
+#### Step 1.3: Confirmation Before Triage
+
+Summarize the bug understanding:
+
+```
+Bug Summary:
+- Symptom: [what happens]
+- Reproduction: [exact steps]
+- Environment: [where it occurs]
+- Expected: [correct behavior]
+- Impact: [who/what is affected]
+- Data trigger: [what data/state causes it]
+```
+
+Ask the user: "Is this summary accurate? Any details to add?"
+
+**CHECKPOINT CP-BFW-1**: Bug fully understood and confirmed by user.
+
+---
+
+### Phase 2: Triage
+
+**Goal**: Locate affected code, identify root cause, classify severity.
+
+1. **Read project context**: `.prizm-docs/root.prizm` → relevant L1/L2 docs for affected modules
+2. **Locate affected code**: read the files mentioned in the error/stack trace or identified during diagnosis
+3. **Check known issues**: search `.prizm-docs/` TRAPS sections for matching patterns
+4. **If database-related**: read existing schema/model files to understand the data layer
+   ```bash
+   find . -maxdepth 4 -type f \( -name "*.prisma" -o -name "*.sql" -o -path "*/migrations/*" -o -path "*/models/*" -o -name "schema.*" -o -name "*.entity.*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' | head -20
+   ```
 5. **Classify**: root cause (confirmed/suspected), blast radius, fix complexity
 6. **Present diagnosis to user**:
    ```
@@ -100,7 +165,7 @@ For trivial bugs with clear root cause and minimal scope:
    ```
    Ask: "Does this diagnosis look right? Should I proceed with the fix?"
 
-### Phase 2: Reproduce
+### Phase 3: Reproduce
 
 **Goal**: Create a failing test that proves the bug exists.
 
@@ -113,9 +178,9 @@ For trivial bugs with clear root cause and minimal scope:
 If the bug is hard to reproduce automatically (e.g. environment-specific):
 - Ask the user for reproduction steps
 - Write a manual reproduction checklist instead
-- Proceed to Phase 3 with the manual checklist
+- Proceed to Phase 4 with the manual checklist
 
-### Phase 3: Fix
+### Phase 4: Fix
 
 **Goal**: Implement the minimal fix. Red test → green.
 
@@ -123,6 +188,7 @@ If the bug is hard to reproduce automatically (e.g. environment-specific):
    - Change the minimum amount of code to fix the root cause
    - Do NOT refactor or add unrelated improvements — fix the bug only
    - Follow existing code conventions (read from `.prizm-docs/` RULES/PATTERNS)
+   - If the fix involves database changes: read existing schema first, follow existing naming/constraint conventions
 2. **Run the reproduction test** → must **pass** (green)
 3. **Run the full module test suite** → must pass (no regressions)
 4. **Show the fix to user**:
@@ -135,7 +201,7 @@ If the fix causes test regressions:
 - Revise the fix (max 3 attempts)
 - If still failing after 3 attempts, escalate to user with analysis
 
-### Phase 4: Review
+### Phase 5: Review
 
 **Goal**: Verify fix quality before committing.
 
@@ -156,7 +222,7 @@ If the fix causes test regressions:
    Ready to commit.
    ```
 
-### Phase 5: User Verification
+### Phase 6: User Verification
 
 **Goal**: Let the user verify the fix works as expected before committing.
 
@@ -166,15 +232,15 @@ If the fix causes test regressions:
    - **(c) Skip verification** — Proceed directly to commit (automated tests already pass)
 2. **If (a)**: Detect and suggest dev server command (e.g. `npm run dev`, `python manage.py runserver`), start it, wait for user confirmation: "Fix verified? (yes/no)"
 3. **If (b)**: Run the specified command, show results, ask confirmation
-4. **If (c)**: Proceed to Phase 6
+4. **If (c)**: Proceed to Phase 7
 
 If user reports the fix is NOT working:
-- Return to Phase 3 (max 2 more attempts)
+- Return to Phase 4 (max 2 more attempts)
 - If still failing: escalate with analysis
 
 ---
 
-### Phase 6: Commit & Merge
+### Phase 7: Commit & Merge
 
 **Goal**: Commit the fix and offer to merge back to the original branch.
 
@@ -215,11 +281,11 @@ The workflow supports resuming from the last completed phase by detecting existi
 | Artifact Found | Resume From |
 |---------------|------------|
 | (nothing) | Phase 0: Branch Setup |
-| On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Triage |
-| `fix-plan.md` only | Phase 3: Fix |
-| `fix-plan.md` + code changes exist | Phase 4: Review |
-| All docs + review passed | Phase 5: User Verification |
-| All docs + committed | Phase 6: Merge decision |
+| On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Deep Bug Diagnosis |
+| `fix-plan.md` only | Phase 4: Fix |
+| `fix-plan.md` + code changes exist | Phase 5: Review |
+| All docs + review passed | Phase 6: User Verification |
+| All docs + committed | Phase 7: Merge decision |
 
 **Resume**: If `<BUG_ID>` matches an existing `.prizmkit/bugfix/<BUG_ID>/` directory, resume instead of starting fresh.
 
@@ -236,12 +302,13 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 ## Comparison with Pipeline Bug Fix
 
 | Dimension | bug-fix-workflow (this skill) | bugfix-pipeline-launcher |
-|-----------|-------------------------------|--------------------------|
+|-----------|-------------------------------|-----------------------------|
 | Scope | One bug at a time | All bugs in batch |
 | Execution | Interactive, in-session | Foreground or background daemon |
+| Diagnosis | Deep interactive Q&A with user | Automated from bug description |
 | Branch | Creates `fix/<BUG_ID>-*` branch | Pipeline manages branches |
 | Visibility | Full user interaction at each phase | Async, check status periodically |
-| User verification | Yes (Phase 5) | No (automated) |
+| User verification | Yes (Phase 6) | No (automated) |
 | Best for | Complex bugs needing user input | Batch of well-defined bugs |
 | Artifacts | Same (fix-plan.md + fix-report.md) | Same |
 | Commit prefix | `fix(<scope>):` | `fix(<scope>):` |
@@ -251,6 +318,7 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | Scenario | Action |
 |----------|--------|
 | Bug ID not found in bug-fix-list.json | Ask user to provide bug details directly |
+| User's bug description is too vague | Ask systematic clarification questions (Phase 1) |
 | Cannot reproduce the bug | Ask for more context, try alternative reproduction |
 | Fix causes regressions | Revert, analyze, retry (max 3 rounds) |
 | Root cause unclear after investigation | Present findings, ask user for guidance |
@@ -264,7 +332,7 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | `bug-planner` | **this skill** | User picks one bug to fix interactively |
 | `bugfix-pipeline-launcher` | **this skill** | User wants to fix a stuck/complex bug manually |
 | **this skill** | `bugfix-pipeline-launcher` | After fixing, user wants to continue with remaining bugs |
-| **this skill** | `prizmkit-committer` | Built into Phase 6 (pure commit, no doc sync) |
+| **this skill** | `prizmkit-committer` | Built into Phase 7 (pure commit, no doc sync) |
 
 ## Output
 

package/bundled/skills/dev-pipeline-launcher/SKILL.md

@@ -144,28 +144,37 @@ Detect user intent from their message, then follow the corresponding workflow:
    dev-pipeline/run.sh status feature-list.json
    ```
 
-5. **Ask user to confirm**: "Ready to launch the pipeline? It will process N features."
+5. **Ask whether to enable Critic Agent** (adversarial review):
+   Present the choice:
+   - **(a) No — standard pipeline (default)**: No adversarial review. Faster execution, lower token cost.
+   - **(b) Yes — enable Critic review**: Adds adversarial challenge after planning and implementation. Challenges plan fitness and code integration quality. Increases pipeline time by ~5-10 minutes per feature.
 
-6. **Launch** (based on chosen mode from step 4):
-   - Foreground: `dev-pipeline/run.sh run feature-list.json`
-   - Background: `dev-pipeline/launch-daemon.sh start feature-list.json`
+   Default to (a). Only suggest (b) if features have `estimated_complexity: "high"` or above.
+
+   If user chooses (b), add `--critic` flag to the launch command in step 6.
+
+6. **Ask user to confirm**: "Ready to launch the pipeline? It will process N features."
+
+7. **Launch** (based on chosen mode from step 4, with `--critic` if chosen in step 5):
+   - Foreground: `dev-pipeline/run.sh run feature-list.json [--critic]`
+   - Background: `dev-pipeline/launch-daemon.sh start feature-list.json [--critic]`
    - If user specified environment overrides:
      ```bash
      dev-pipeline/launch-daemon.sh start feature-list.json --env "SESSION_TIMEOUT=7200 MAX_RETRIES=5"
      ```
 
-7. **Verify launch**:
+8. **Verify launch**:
    ```bash
    dev-pipeline/launch-daemon.sh status
    ```
 
-8. **Start log monitoring** -- Use the Bash tool with `run_in_background: true`:
+9. **Start log monitoring** -- Use the Bash tool with `run_in_background: true`:
    ```bash
    tail -f dev-pipeline/state/pipeline-daemon.log
    ```
    This runs in background so you can continue interacting with the user.
 
-9. **Report to user**:
+10. **Report to user**:
    - Pipeline PID
    - Log file location
    - "You can ask me 'pipeline status' or 'show logs' at any time"
@@ -250,6 +259,7 @@ When user specifies custom settings, map to environment variables:
 | "max 5 retries" | `MAX_RETRIES=5` |
 | "verbose mode" | `VERBOSE=1` |
 | "heartbeat every 60s" | `HEARTBEAT_INTERVAL=60` |
+| "enable critic review" | `--critic` flag |
 
 Pass via `--env`:
 ```bash