prizmkit 1.0.153 → 1.1.0

package/bundled/skills/refactor-workflow/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: "refactor-workflow"
 tier: 1
-description: "End-to-end refactor workflow: deep requirement Q&A → analyze → plan → implement → review → commit. 7-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
+description: "End-to-end refactor workflow: structured scoping → parallel code & doc analysis → collaborative planning → implement → review → commit. 6-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
 ---
 
 # PrizmKit Refactor Workflow
 
-End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 7-phase behavior-preserving pipeline with mandatory test gates after each task.
+End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 6-phase behavior-preserving pipeline with mandatory test gates after each task.
 
 ### When to Use
 - User says "refactor", "clean up code", "restructure", "extract module", "code refactoring", "optimize code structure"
@@ -23,13 +23,12 @@ End-to-end orchestration skill for code refactoring and optimization. Chains exi
 
 ```
 refactor-workflow
-  → Phase 0: Branch    → refactor/<slug> branch
-  → Phase 1: Understand → deep interactive Q&A with user
-  → Phase 2: Analyze   → refactor-analysis.md
-  → Phase 3: Plan      → plan.md (including Tasks section)
-  → Phase 4: Implement → (code)
-  → Phase 5: Review    → (review report)
-  → Phase 6: Verify & Commit → git commit + merge decision
+  → Phase 0: Branch              → refactor/<slug> branch
+  → Phase 1: Understand & Analyze → structured scoping + parallel Agent reading + collaborative planning
+  → Phase 2: Plan                → plan.md (including Tasks section)
+  → Phase 3: Implement           → (code)
+  → Phase 4: Review              → (review report)
+  → Phase 5: Verify & Commit     → git commit + merge decision
 ```
 
 ### Pipeline Phases
@@ -37,27 +36,28 @@ refactor-workflow
 | Phase | Name | Skill Used | Artifact |
 |-------|------|-----------|----------|
 | 0 | Branch Setup | git | → `refactor/<slug>` branch |
-| 1 | Understand (Deep Q&A) | Interactive clarification | → Refactoring requirements confirmed |
-| 2 | Analyze (Code Analysis) | Built-in code analysis + code reading | → `refactor-analysis.md` |
-| 3 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
-| 4 | Implement | `/prizmkit-implement` | (code changes) |
-| 5 | Code Review | `/prizmkit-code-review` | (review report) |
-| 6 | Verify & Commit | `/prizmkit-committer` | git commit + merge |
+| 1 | Understand & Analyze | Interactive scoping + parallel Agent reading + code analysis | → Refactoring scope confirmed + `refactor-analysis.md` |
+| 2 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
+| 3 | Implement | `/prizmkit-implement` | (code changes) |
+| 4 | Code Review | `/prizmkit-code-review` | (review report) |
+| 5 | Verify & Commit | `/prizmkit-committer` | git commit + merge |
 
 ### Key Principles
 
 | Principle | Description |
 |-----------|-------------|
-| **Deep understanding first** | Before analyzing code, fully understand the user's motivation, goals, and constraints. Refactoring without clear goals leads to churn. |
-| **Behavior preservation** | Refactoring changes structure, not behavior. If tests pass before and after, behavior is preserved. Acceptance criteria = "behavior unchanged + structure improved". |
-| **Test gates** | Full test suite runs after every task — not just at checkpoints. A refactoring that breaks tests mid-way is much harder to debug than catching it immediately. |
-| **Structural sync only** | Refactoring triggers `/prizmkit-retrospective` Job 1 (structural sync) — update `.prizm-docs/` to reflect file/interface changes. Skip knowledge injection unless a genuinely new pitfall was discovered during refactoring. |
-| **Incremental safety** | Each task preserves all tests (green → green). If tests fail → stop and revert, because later tasks build on the assumption that previous ones are clean. |
+| **Structured scoping first** | Use structured choices (not open-ended Q&A) to quickly establish refactoring type, scope, and reference materials. |
+| **Parallel understanding** | Dispatch multiple Agents concurrently to read code, docs, and knowledge files — don't read sequentially. |
+| **Show findings, then collaborate** | Present what the Agents discovered, then work with the user to shape the refactoring plan — don't just ask questions without context. |
+| **Behavior preservation** | Refactoring changes structure, not behavior. If tests pass before and after, behavior is preserved. |
+| **Test gates** | Full test suite runs after every task — not just at checkpoints. |
+| **Structural sync only** | Refactoring triggers `/prizmkit-retrospective` Job 1 (structural sync) — update `.prizm-docs/` to reflect file/interface changes. Skip knowledge injection unless a genuinely new pitfall was discovered. |
+| **Incremental safety** | Each task preserves all tests (green → green). If tests fail → stop and revert. |
 
 ### Artifacts
 Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
-- **`refactor-analysis.md`** — Code analysis (Phase 2)
-- **`plan.md`** — Refactoring plan with Tasks section (Phase 3)
+- **`refactor-analysis.md`** — Scoping + code analysis (Phase 1)
+- **`plan.md`** — Refactoring plan with Tasks section (Phase 2)
 
 **PRECONDITION:**
 
@@ -94,94 +94,110 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 1: Understand — Deep Refactoring Q&A
+## Phase 1: Understand & Analyze
 
-**Goal**: Fully understand the user's refactoring motivation, goals, constraints, and expectations before analyzing code. Refactoring without clear goals leads to aimless restructuring.
+**Goal**: Through structured choices, parallel Agent reading, and collaborative discussion, fully understand the refactoring scope and produce a code analysis — all in one integrated phase.
 
-**CRITICAL RULE**: Ask as many questions as needed until the refactoring scope and goals are crystal clear. Do NOT jump into code analysis. A misunderstood refactoring goal leads to wasted effort or, worse, breaking the architecture in an unintended direction.
+**CRITICAL RULE**: This phase has 5 steps executed in order. Do NOT skip to planning without completing all steps, especially the parallel reading and collaborative discussion.
 
-### Step 1.1: Motivation and Goals
+### Step 1.1: Refactoring Type Selection
 
-Ask the user to explain why they want to refactor:
+Present the user with a structured choice to establish the refactoring approach:
 
-- **What's the pain point?** What specific problem does the current code cause? (Hard to add features? Hard to test? Confusing to read? Performance issues?)
-- **What's the desired outcome?** What should the code look like after refactoring? (Better separation of concerns? Reduced coupling? Clearer interfaces?)
-- **What triggered this?** Did a recent feature attempt expose the debt? Is it proactive cleanup?
+Ask the user to choose:
+- **(a) Incremental refactoring** — Gradual, low-risk improvements. Refactor piece by piece, each step independently deployable.
+- **(b) Full refactoring** — Comprehensive restructuring of the entire target area. Higher risk, bigger payoff.
+- **(c) Targeted refactoring** — Focus on a specific part or concern (e.g., extract one module, decouple one dependency, simplify one flow).
 
-### Step 1.2: Scope and Boundaries
+Follow up based on choice:
+- If **(a)**: Ask which area to start with, and what the incremental milestones should be
+- If **(b)**: Confirm the full scope boundary — what's included and what's explicitly excluded
+- If **(c)**: Confirm the specific target and the expected outcome
 
-Establish clear boundaries for what will and won't change:
+### Step 1.2: Reference Materials Collection
 
-- **Which modules/files are in scope?** (specific paths, or "everything under src/auth/")
-- **What is explicitly OUT of scope?** (e.g., "don't touch the API layer", "leave the database schema as-is")
-- **Are there any behavior changes allowed?** (Usually no for refactoring, but sometimes the user wants to combine refactoring with a minor behavior change — clarify this upfront)
-- **Should the public API/interface stay the same?** (Or is renaming/restructuring the API acceptable?)
+Ask the user if they have supplementary materials that can inform the refactoring:
 
-### Step 1.3: Constraints and Risks
+Present as a multi-select checklist:
+- **Code paths** — Specific files or directories to focus on (e.g., `src/auth/`, `lib/payment.js`)
+- **Refactoring-related documents** — Design docs, RFCs, architecture proposals, migration guides
+- **Existing knowledge docs** — `.prizm-docs/`, ADRs, inline documentation, wiki pages, or team notes about the target area
+- **None** — No additional materials, rely on code reading
 
-Understand what the user is concerned about:
+For each item the user provides, record the path or description for the next step.
 
-- **Which behaviors absolutely must NOT change?** (critical paths, user-facing behavior, external integrations)
-- **Are there performance requirements?** (e.g., "the refactored code must not be slower")
-- **Are there any code areas that are particularly fragile?** (known tricky sections, undocumented behavior)
-- **Is there a deadline or time constraint?** (affects how aggressive the refactoring can be)
-- **If database/schema changes are involved**: read existing schema files first and confirm scope with user
-  ```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
-  ```
+### Step 1.3: Parallel Agent Reading
 
-### Step 1.4: Confirmation
+Based on the user's selections in Steps 1.1 and 1.2, dispatch **multiple Agents in parallel** to read and analyze:
 
-Summarize the refactoring scope:
+**Agent allocation strategy:**
+- **Agent A (Code Structure)**: Read the target code files — understand architecture, dependencies (incoming/outgoing), module boundaries, public API surface
+- **Agent B (Documentation)**: Read any user-provided docs + relevant `.prizm-docs/` (TRAPS, PATTERNS, RULES) + TODO/FIXME/HACK comments in target code
+- **Agent C (Test Baseline)**: Locate and run test suites for the target area — record pass/fail counts, identify pre-existing failures, assess coverage
+
+If the user provided no docs (chose "None" in Step 1.2), Agent B focuses entirely on `.prizm-docs/` and inline code comments.
+
+**Each Agent produces a structured summary:**
+- Agent A: file inventory, dependency graph, complexity hotspots, code smells
+- Agent B: known traps, architectural decisions, existing knowledge about the target
+- Agent C: test suite status (total/passing/failing), coverage estimate, behavior contracts
+
+### Step 1.4: Present Findings & Collaborative Planning
+
+After all Agents complete, **present a consolidated findings report** to the user:
 
 ```
-Refactoring Scope:
-- Target: [modules/files in scope]
-- Goal: [desired structural improvement]
-- Out of scope: [what won't change]
-- Behavior contract: [what must remain unchanged]
-- Constraints: [performance, API stability, etc.]
+## Refactoring Findings
+
+### Code Structure (Agent A)
+- [file inventory, dependency graph, complexity metrics]
+- [identified code smells: long functions, deep nesting, duplication, coupling]
+
+### Existing Knowledge (Agent B)
+- [known traps and risks from docs]
+- [relevant architectural decisions]
+- [user-provided doc insights]
+
+### Test Baseline (Agent C)
+- [test suite status: X total, Y passing, Z failing]
+- [coverage estimate]
+- [behavior contracts to preserve]
+
+### Recommended Refactoring Approach
+- [based on findings, propose concrete refactoring strategy]
+- [identify highest-impact opportunities]
+- [flag risks and cross-module impacts]
 ```
 
-Ask the user: "Is this scope accurate? Anything to adjust?"
+Then engage the user in **collaborative discussion**:
+- "Based on these findings, here's what I recommend for the refactoring approach. What do you think?"
+- Discuss priorities: which improvements matter most?
+- Discuss constraints: any areas that are off-limits?
+- Discuss risks: how to handle fragile or undocumented areas?
+- If the scope needs adjustment based on findings, negotiate with the user
 
-**CHECKPOINT CP-RW-1**: Refactoring scope and goals confirmed by user.
+### Step 1.5: Confirm & Generate Analysis
 
----
-
-## Phase 2: Analyze — Code Analysis
+After the collaborative discussion concludes:
 
-**Goal**: Assess current code state, identify refactoring targets, establish baseline.
+1. **Ask the user**: "Is there anything else you'd like to add or adjust before we finalize the refactoring scope?"
+2. **If yes**: Incorporate feedback, revisit relevant points
+3. **If no**: Generate `refactor-analysis.md` at `.prizmkit/refactor/<refactor-slug>/refactor-analysis.md`
 
-**STEPS:**
+**`refactor-analysis.md` required sections:**
+- **Refactoring Type**: Incremental / Full / Targeted (from Step 1.1)
+- **Current State**: module overview, file inventory, dependency graph, complexity metrics (from Agent A)
+- **Refactoring Goals**: what structural improvements are targeted, why — aligned with collaborative discussion
+- **Risk Assessment**: what could break, cross-module impact, fragile areas (from Agent B + discussion)
+- **Baseline Tests**: test suite status, coverage estimate, behavior contracts to preserve (from Agent C)
+- **Scope Boundary**: what IS in scope, what is explicitly OUT of scope — confirmed with user
+- **Reference Materials**: list of docs/paths the user provided and key insights from each
 
-1. **Read target code**: Thoroughly read and understand the target module/files:
-   - Code structure and architecture
-   - Dependencies (incoming and outgoing)
-   - Current test coverage
-   - Known tech debt (from `.prizm-docs/` TRAPS)
-2. **Perform code analysis** on target area:
-   - Identify code smells: long functions, deep nesting, duplicated logic, excessive coupling
-   - Assess complexity metrics: function length, parameter count, cyclomatic complexity
-   - Identify highest-impact refactoring opportunities
-   - Check for TODO/FIXME/HACK comments indicating known debt
-3. **Establish baseline**:
-   - Run full test suite — record pass/fail counts
-   - Note any pre-existing test failures (isolate from refactor impact)
-   - Document current behavior contracts (public API, interfaces)
-4. **Generate `refactor-analysis.md`** at `.prizmkit/refactor/<refactor-slug>/refactor-analysis.md`:
-   Required sections:
-   - **Current State**: module overview, file inventory, dependency graph, complexity metrics
-   - **Refactoring Goals**: what structural improvements are targeted, why (debt items, complexity, maintainability) — aligned with user's confirmed goals from Phase 1
-   - **Risk Assessment**: what could break, cross-module impact, data migration needs
-   - **Baseline Tests**: test suite status (total, passing, failing), coverage estimate, behavior contracts to preserve
-   - **Scope Boundary**: what IS in scope, what is explicitly OUT of scope — carried from Phase 1 confirmation
-
-**CHECKPOINT CP-RW-2**: `refactor-analysis.md` exists with baseline test results.
+**CHECKPOINT CP-RW-1**: `refactor-analysis.md` exists with confirmed scope, baseline test results, and user agreement.
 
 ---
 
-## Phase 3: Plan — Refactor Plan & Tasks
+## Phase 2: Plan — Refactor Plan & Tasks
 
 **Goal**: Generate technical refactoring plan that preserves behavior, including task breakdown.
 
@@ -199,11 +215,11 @@ Ask the user: "Is this scope accurate? Anything to adjust?"
    - Tasks ordered to minimize risk (safe renames first, structural changes later)
    - Every task ends with "run full test suite"
 
-**CHECKPOINT CP-RW-3**: `plan.md` exists with behavior preservation strategy and Tasks section.
+**CHECKPOINT CP-RW-2**: `plan.md` exists with behavior preservation strategy and Tasks section.
 
 ---
 
-## Phase 4: Implement
+## Phase 3: Implement
 
 **Goal**: Execute refactoring tasks with mandatory test verification after each task.
 
@@ -218,9 +234,9 @@ Ask the user: "Is this scope accurate? Anything to adjust?"
    - Mark tasks complete in plan.md Tasks section as they finish
    - Record test results after each task
 
-**CHECKPOINT CP-RW-4**: All tasks complete, full test suite green.
+**CHECKPOINT CP-RW-3**: All tasks complete, full test suite green.
 
-**Important constraints for Phase 4:**
+**Important constraints for Phase 3:**
 - Never skip the test gate between tasks — a broken intermediate state compounds into much harder debugging later
 - Never allow temporary test failures ("we'll fix it in the next task") — this assumption is almost always wrong in refactoring
 - If a task cannot be completed without breaking tests → split it into smaller tasks
@@ -228,7 +244,7 @@ Ask the user: "Is this scope accurate? Anything to adjust?"
 
 ---
 
-## Phase 5: Code Review
+## Phase 4: Code Review
 
 **Goal**: Verify refactoring quality and behavior preservation.
 
@@ -244,14 +260,14 @@ Ask the user: "Is this scope accurate? Anything to adjust?"
    - Verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
 2. **Run full test suite one final time**: All tests must pass
 3. **Handle review results**:
-   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 6
-   - **NEEDS_FIXES**: Return to Phase 4 following Fix Instructions (max 2 review rounds)
+   - **PASS / PASS_WITH_WARNINGS**: Proceed to Phase 5
+   - **NEEDS_FIXES**: Return to Phase 3 following Fix Instructions (max 2 review rounds)
 
-**CHECKPOINT CP-RW-5**: Code review passes, all tests green.
+**CHECKPOINT CP-RW-4**: Code review passes, all tests green.
 
 ---
 
-## Phase 6: Verify, Commit & Merge
+## Phase 5: Verify, Commit & Merge
 
 **Goal**: Let user verify, commit with refactor convention, and merge back.
 
@@ -262,7 +278,7 @@ Ask the user: "Is this scope accurate? Anything to adjust?"
      - **(a) Run the app** — Start dev server for manual verification
      - **(b) Run a specific command** — Specify a test or script
      - **(c) Skip** — Proceed to commit (tests already pass)
-   - If user reports issues: return to Phase 4
+   - If user reports issues: return to Phase 3
 2. **Invoke `/prizmkit-retrospective`** (Job 1: structural sync only):
    - Update KEY_FILES/INTERFACES/DEPENDENCIES in affected `.prizm-docs/` files
    - Skip knowledge injection unless refactoring revealed a genuinely new pitfall (e.g. a non-obvious coupling)
@@ -288,7 +304,7 @@ Ask the user: "Is this scope accurate? Anything to adjust?"
    ```
 6. **If (b)**: Inform user: "Branch `refactor/<slug>` retained. Create a PR when ready."
 
-**CHECKPOINT CP-RW-6**: Commit recorded with `refactor()` prefix. Merge decision made.
+**CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix. Merge decision made.
 
 ---
 
@@ -297,10 +313,10 @@ Ask the user: "Is this scope accurate? Anything to adjust?"
 For single-file refactoring (rename, extract method, <30 lines changed):
 
 ```
-Phase 0 (Branch) → Phase 1 (Simplified Q&A) → Phase 2 (Analyze) → Phase 3 (Simplified Plan) → Phase 4 (Implement) → Phase 5 (Review) → Phase 6 (Commit & Merge)
+Phase 0 (Branch) → Phase 1 (Simplified) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit & Merge)
 ```
 
-Phase 1 is simplified to 2-3 quick confirmation questions instead of deep dive. Skip Phase 3's detailed planning process, but still generate a lightweight `plan.md` with a simplified Tasks section (typically 1-2 tasks).
+Phase 1 is simplified: skip parallel Agents, use a quick 2-3 question confirmation instead. Skip detailed doc collection. Still generate a lightweight `refactor-analysis.md`.
 
 **CRITERIA** (ALL must be true):
 - Single file change
@@ -310,9 +326,11 @@ Phase 1 is simplified to 2-3 quick confirmation questions instead of deep dive.
 - No dependency changes
 
 **Fast Path implementation differs from full path:**
-- Phase 1 is simplified: confirm goal and scope in 2-3 questions
-- Phase 3 is simplified: generate a lightweight plan.md with 1-2 tasks directly from refactor-analysis.md, without deep architecture research
-- Phase 4 still reads plan.md Tasks as normal, marks tasks `[x]` on completion
+- Phase 1 Steps 1.2-1.3 are skipped (no doc collection, no parallel Agents)
+- Step 1.1 simplified to quick confirmation of refactoring goal
+- Step 1.4 simplified to brief scope confirmation
+- Phase 2 is simplified: generate a lightweight plan.md with 1-2 tasks directly from refactor-analysis.md
+- Phase 3 still reads plan.md Tasks as normal, marks tasks `[x]` on completion
 - Single-task refactors typically have just one task in plan.md
 
 **Fast Path still requires:**
@@ -336,12 +354,11 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Artifact Found | Resume From |
 |---------------|------------|
 | (nothing) | Phase 0: Branch Setup |
-| On `refactor/<slug>` branch, no artifacts | Phase 1: Understand |
-| Scope confirmed, no analysis | Phase 2: Analyze |
-| `refactor-analysis.md` only | Phase 3: Plan |
-| `refactor-analysis.md` + `plan.md` | Phase 4: Implement |
-| All docs + code changes exist | Phase 5: Review |
-| All docs + review passed | Phase 6: Verify & Commit |
+| On `refactor/<slug>` branch, no artifacts | Phase 1: Understand & Analyze |
+| `refactor-analysis.md` only | Phase 2: Plan |
+| `refactor-analysis.md` + `plan.md` | Phase 3: Implement |
+| All docs + code changes exist | Phase 4: Review |
+| All docs + review passed | Phase 5: Verify & Commit |
 
 **Resume**: If `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
 
@@ -352,9 +369,10 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Scenario | Action |
 |----------|--------|
 | Cannot identify target module | Ask user for clarification |
-| User's refactoring goal is unclear | Ask systematic clarification questions (Phase 1) |
+| User's refactoring goal is unclear | Use Step 1.1 structured choices to narrow down |
 | No tests exist for target module | WARN user, recommend writing tests first |
 | Baseline tests already failing | Isolate failures, document, proceed with caution |
+| Parallel Agent fails to read a file | Log warning, continue with available results, notify user |
 | Test fails after a refactoring task | Revert task, investigate, retry or split |
 | Implementation fails after 3 rounds | Escalate to user with analysis |
 | Review fails after 2 rounds | Escalate with review findings |
@@ -368,14 +386,14 @@ The pipeline supports resuming from the last completed phase by detecting existi
 
 | Skill | Role in Refactor Workflow |
 |-------|-----------------------------|
-| (built-in code analysis) | Phase 2: identify debt and complexity |
-| `/prizmkit-plan` | Phase 3: refactoring plan + task generation |
-| `/prizmkit-implement` | Phase 4: execute refactoring tasks |
-| `/prizmkit-code-review` | Phase 5: review quality and behavior preservation |
-| `/prizmkit-committer` | Phase 6: commit with `refactor()` convention |
-| `/prizmkit-retrospective` | Phase 6: structural sync before commit (Job 1 only, skip knowledge injection unless new pitfall) |
+| (parallel Agents) | Phase 1: concurrent code & doc reading |
+| `/prizmkit-plan` | Phase 2: refactoring plan + task generation |
+| `/prizmkit-implement` | Phase 3: execute refactoring tasks |
+| `/prizmkit-code-review` | Phase 4: review quality and behavior preservation |
+| `/prizmkit-committer` | Phase 5: commit with `refactor()` convention |
+| `/prizmkit-retrospective` | Phase 5: structural sync before commit (Job 1 only, skip knowledge injection unless new pitfall) |
 | `feature-workflow` | Handoff target when new behavior is needed |
-| `/prizmkit-specify` | NOT used (no user stories for refactoring) |
+| `/prizmkit-plan` | NOT used (no user stories for refactoring) |
 | `/prizmkit-analyze` | NOT used (no spec <-> plan consistency needed) |
 
 ---
@@ -385,22 +403,22 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Dimension | Feature Workflow | Refactor Workflow | Bug Fix Workflow |
 |-----------|-----------------|-------------------|------------------|
 | Input | Natural language requirement | Module/code target | Bug description |
-| Deep Q&A | Yes (brainstorm) | Yes (scope & goals) | Yes (diagnosis) |
+| Deep Q&A | Yes (brainstorm) | Yes (structured scoping + parallel analysis) | Yes (diagnosis) |
 | Branch | Pipeline manages per-feature | `refactor/<slug>` | `fix/<BUG_ID>-*` |
-| Pipeline Phases | 4 (brainstorm → plan → launch → monitor) | 7 (branch → understand → analyze → plan → implement → review → commit) | 8 (branch → diagnose → triage → reproduce → fix → review → verify → commit) |
-| Phase 1 | Brainstorm (requirements Q&A) | Understand (scope & goals Q&A) | Deep Bug Diagnosis (symptom Q&A) |
+| Pipeline Phases | 4 (brainstorm → plan → launch → monitor) | 6 (branch → understand & analyze → plan → implement → review → commit) | 8 (branch → diagnose → triage → reproduce → fix → review → verify → commit) |
+| Phase 1 | Brainstorm (requirements Q&A) | Understand & Analyze (structured scoping + parallel reading + collaborative planning) | Deep Bug Diagnosis (symptom Q&A) |
 | Artifact Path | `.prizmkit/specs/<slug>/` | `.prizmkit/refactor/<slug>/` | `.prizmkit/bugfix/<id>/` |
 | Commit Prefix | `feat(<scope>):` | `refactor(<scope>):` | `fix(<scope>):` |
 | Test Strategy | TDD per task | Full suite after EVERY task | Reproduction test |
 | Scope Guard | N/A | Enforced | N/A |
 | Behavior Change | Expected | Forbidden | Fix behavior |
-| User Verification | Yes (brainstorm confirmation) | Yes (Phase 6) | Yes (Phase 6) |
+| User Verification | Yes (brainstorm confirmation) | Yes (Phase 5) | Yes (Phase 6) |
 
 ## Output
 
-- `refactor-analysis.md` (Phase 2 artifact)
-- `plan.md` with Tasks section (Phase 3 artifact)
-- Refactored implementation code (Phase 4)
-- Code review report (Phase 5, conversation only)
-- Git commit with `refactor(<scope>):` prefix on dedicated refactor branch (Phase 6)
+- `refactor-analysis.md` (Phase 1 artifact)
+- `plan.md` with Tasks section (Phase 2 artifact)
+- Refactored implementation code (Phase 3)
+- Code review report (Phase 4, conversation only)
+- Git commit with `refactor(<scope>):` prefix on dedicated refactor branch (Phase 5)
 - Updated `.prizm-docs/` (if applicable)

package/bundled/team/prizm-dev-team.json

@@ -2,19 +2,13 @@
   "name": "prizm-dev-team",
   "team_name": "prizm-dev-team",
   "description": "PrizmKit-integrated Multi-Agent software development team. 3 specialized agents (Dev, Reviewer, Critic) following PrizmKit spec-driven workflow with pipeline and checkpoints.",
-  "lead": "team-lead",
+  "lead": "orchestrator",
   "communication": {
     "protocol": "SendMessage",
     "routing": "mesh",
-    "note": "Teammates communicate directly via SendMessage; key messages must also be sent to Orchestrator"
+    "note": "Teammates communicate directly via SendMessage; key messages must also be sent to Orchestrator (the main agent session)"
   },
   "members": [
-    {
-      "name": "team-lead",
-      "role": "lead",
-      "agentDefinition": "prizm-dev-team-dev",
-      "subscriptions": []
-    },
     {
       "name": "dev",
       "role": "developer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.153",
+  "version": "1.1.0",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/clean.js

@@ -119,6 +119,10 @@ export async function runClean(directory, options = {}) {
     '.prizm-docs',        // AI-generated project context docs
     'CODEBUDDY.md',
     'CLAUDE.md',
+    'feature-list.json',          // app-planner output
+    'bug-fix-list.json',          // bug-planner output
+    'project-brief.md',           // app-planner project brief
+    'project-conventions.json',   // app-planner coding conventions
     path.join('.codebuddy', 'settings.json'),
     path.join('.claude', 'settings.json'),
     path.join('.claude', 'team-info.json'),
@@ -136,6 +140,10 @@ export async function runClean(directory, options = {}) {
   const claudeCommandEntries = allSkillNames.flatMap(name => [name, `${name}.md`]);
   results.push(...await removeKnownEntries(claudeCommandsDir, claudeCommandEntries, dryRun));
 
+  // .claude/command-assets/ — skill assets installed by adapter
+  const claudeCommandAssetsDir = path.join(projectRoot, '.claude', 'command-assets');
+  results.push(...await removeKnownEntries(claudeCommandAssetsDir, allSkillNames, dryRun));
+
   // .codebuddy/skills/ — skills installed as subdirectories
   const cbSkillsDir = path.join(projectRoot, '.codebuddy', 'skills');
   results.push(...await removeKnownEntries(cbSkillsDir, allSkillNames, dryRun));

package/src/gitignore-template.js

@@ -14,9 +14,21 @@ export function generateGitignore(options = {}) {
     '# PrizmKit Runtime Artifacts',
     '# ===========================',
     '',
+    '# PrizmKit 运行时配置与产物',
+    '.prizmkit/',
+    '',
+    '# 多 Agent 协作临时工作区',
+    '.dev-team/',
+    '',
     '# Prizm 文档（按需决定是否提交）',
     '# .prizm-docs/',
     '',
+    '# 规划产物（按需决定是否提交）',
+    '# feature-list.json',
+    '# bug-fix-list.json',
+    '# project-brief.md',
+    '# project-conventions.json',
+    '',
   ];
 
   if (options.pipeline) {

package/src/index.js

@@ -64,7 +64,7 @@ export async function runScaffold(directory, options) {
     }
     const config = {
       platform: options.platform,
-      skills: options.skills || 'full',
+      skills: options.skills || 'core',
       team: options.team !== false,
       pipeline: options.pipeline !== false,
       playwrightCli: options.playwrightCli !== false,
@@ -144,10 +144,6 @@ export async function runScaffold(directory, options) {
     const skillSuiteChoice = await select({
       message: '选择技能套件:',
       choices: [
-        {
-          name: `Full — 全部 ${totalSkills} 个技能`,
-          value: 'full',
-        },
         {
           name: `Core — 核心工作流 (${metadata.suites.core.skills.length} 个技能)`,
           value: 'core',
@@ -156,25 +152,11 @@ export async function runScaffold(directory, options) {
           name: `Minimal — 最小可用 (${metadata.suites.minimal.skills.length} 个技能)`,
           value: 'minimal',
         },
-        {
-          name: 'Recommended — 按项目类型推荐 ▸',
-          value: 'recommended',
-        },
       ],
-      default: 'full',
+      default: 'core',
     });
 
     let skillSuite = skillSuiteChoice;
-    if (skillSuiteChoice === 'recommended') {
-      const projectType = await select({
-        message: '选择项目类型:',
-        choices: Object.entries(metadata.recommendations || {}).map(([key, val]) => ({
-          name: val.label,
-          value: `recommended:${key}`,
-        })),
-      });
-      skillSuite = projectType;
-    }
 
     // 2.5. 外部 Skill 选择（可选）
     let selectedExternalSkills = [];
@@ -223,8 +205,7 @@ export async function runScaffold(directory, options) {
     // 显示安装摘要
     const platformLabel = platform === 'both' ? 'CodeBuddy + Claude Code'
       : platform === 'codebuddy' ? 'CodeBuddy' : 'Claude Code';
-    const suiteLabel = skillSuite === 'full' ? `Full (${totalSkills} 个)`
-      : skillSuite === 'core' ? `Core (${metadata.suites.core.skills.length} 个)`
+    const suiteLabel = skillSuite === 'core' ? `Core (${metadata.suites.core.skills.length} 个)`
       : skillSuite === 'minimal' ? `Minimal (${metadata.suites.minimal.skills.length} 个)`
       : `Recommended (${skillSuite})`;