prizmkit 1.0.122 → 1.0.124

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

@@ -1,12 +1,12 @@
 ---
 name: "feature-workflow"
 tier: companion
-description: "One-stop entry point for feature development. Orchestrates app-planner → dev-pipeline-launcher → background execution. Handles multi-feature batch development from a single request. Use this skill whenever the user wants to build an app, develop multiple features at once, or go from idea to running code in one step. Trigger on: 'build an app', 'develop features', 'implement all features', 'one-stop development', 'batch implement', 'build a new application', 'build a system', 'one-click complete', 'batch implement'. (project)"
+description: "One-stop entry point for feature development. Brainstorms requirements with the user until fully clarified, then orchestrates app-planner → dev-pipeline-launcher → execution. Handles multi-feature batch development from a single request. Use this skill whenever the user wants to build an app, develop multiple features at once, or go from idea to running code in one step. Trigger on: 'build an app', 'develop features', 'implement all features', 'one-stop development', 'batch implement', 'build a new application', 'build a system', 'one-click complete', 'batch implement'. (project)"
 ---
 
 # Feature Workflow
 
-One-stop entry point for feature development. Orchestrates the complete flow from requirements to committed code in a single invocation.
+One-stop entry point for feature development. Covers the complete journey from a vague idea to running code: deep requirement brainstorming → structured planning → autonomous pipeline execution.
 
 ## When to Use
 
@@ -28,33 +28,38 @@ User says:
 ## Overview
 
 ```
-feature-workflow <requirements description>
+feature-workflow <idea / requirements>
    │
-   ├── Phase 1: Plan → app-planner → feature-list.json
+   ├── Phase 1: Brainstorm → deep interactive Q&A until requirements are crystal clear
    │
-   ├── Phase 2: Launch → dev-pipeline-launcher → pipeline execution
+   ├── Phase 2: Plan → app-planner → feature-list.json
    │
-   └── Phase 3: Monitor → track progress → report results
+   ├── Phase 3: Launch → dev-pipeline-launcher → pipeline execution
+   │
+   └── Phase 4: Monitor → track progress → report results
 ```
 
 ### What This Skill Does
 
 | Phase | Action | Result |
 |-------|--------|--------|
-| 1 | Call `app-planner` | `feature-list.json` with N features |
-| 2 | Call `dev-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
-| 3 | Monitor progress | Status updates, completion report |
+| 1 | **Brainstorm** — interactive Q&A with user | Fully clarified requirements document |
+| 2 | Call `app-planner` with clarified requirements | `feature-list.json` with N features |
+| 3 | Call `dev-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
+| 4 | Monitor progress | Status updates, completion report |
 
 ### Why This Skill Exists
 
 Without this skill, users must:
-1. Invoke `app-planner` → wait for feature-list.json
-2. Invoke `dev-pipeline-launcher` → wait for pipeline start
-3. Manually check progress
+1. Figure out all requirements themselves
+2. Invoke `app-planner` → wait for feature-list.json
+3. Invoke `dev-pipeline-launcher` → wait for pipeline start
+4. Manually check progress
 
 With this skill, users can:
-1. Say "Build a task management App" and walk away
-2. All planning + execution happens automatically
+1. Say "Build a task management App" with a rough idea
+2. The skill brainstorms to fill in all gaps
+3. All planning + execution happens automatically
 
 ### Branch Management
 
@@ -74,18 +79,19 @@ Natural language description of the project or features. Can be:
 - A batch of features: "Implement user registration, login, and password recovery features"
 - An incremental request: "Add user avatar upload and nickname modification to the existing system"
 
-Flow: app-planner → dev-pipeline-launcher → monitor
+Flow: brainstorm → app-planner → dev-pipeline-launcher → monitor
 
 **Mode B: From existing feature-list.json**
 
 When user says "run pipeline from existing file" or feature-list.json already exists:
-- Skip `app-planner` (file already exists)
+- Skip brainstorm and `app-planner` (file already exists)
 - Invoke `dev-pipeline-launcher` directly
 - Monitor and report progress
 
 **Mode C: Incremental (add to existing project)**
 
 When user says "add features to existing project" or the project already has features:
+- Brainstorm new feature requirements with the user
 - Invoke `app-planner` in incremental mode (reads existing feature-list.json)
 - Append new features to existing list
 - Invoke `dev-pipeline-launcher`
@@ -93,19 +99,151 @@ When user says "add features to existing project" or the project already has fea
 
 ---
 
-## Phase 1: Plan
+## Phase 1: Brainstorm — Deep Requirement Clarification
+
+**Goal**: Through interactive Q&A, transform the user's rough idea into fully clarified, implementation-ready requirements. This phase is the foundation for high-quality code generation — vague requirements produce vague code.
+
+**CRITICAL RULE**: The number of questions is **unlimited**. Do NOT rush through this phase. Ask as many rounds as needed until every aspect is clear. The framework strives for perfect code generation, which requires perfect understanding of requirements.
+
+### Step 1.1: Understand the User's Vision
+
+Ask the user to describe what they want to build. Listen for:
+- **What** the system/feature does (core functionality)
+- **Who** uses it (user roles, personas)
+- **Why** it's needed (business value, problem being solved)
+
+### Step 1.2: Context Gathering
+
+Before asking detailed questions, gather existing project context:
+- If `.prizm-docs/root.prizm` exists → read it to understand existing architecture, tech stack, patterns
+- If `.prizmkit/config.json` exists → read tech stack preferences
+- If existing source code exists → scan directory structure:
+  ```bash
+  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+  ```
+- If database/schema files exist → scan them to understand existing data model:
+  ```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/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' | head -20
+  ```
+
+This context informs better questions — e.g., if the project uses PostgreSQL + Prisma, ask about schema design in those terms.
+
+### Step 1.3: Adaptive Deep-Dive Questioning
+
+Based on the user's description, ask questions across these dimensions. **Adapt question depth to the feature complexity** — a simple CRUD feature needs fewer questions than a real-time collaboration system.
+
+**Functional Requirements:**
+- What are the core user actions/workflows?
+- What inputs does the system accept? What outputs does it produce?
+- What are the key business rules and validation logic?
+- Are there different user roles with different permissions?
+
+**Data Model & Database** (if applicable):
+- What entities/data need to be stored?
+- What are the relationships between entities?
+- Are there existing database tables this feature must integrate with?
+- What fields are required vs optional? What data types?
+- Any unique constraints, indexes, or special query patterns needed?
+- **RULE**: If the project has existing database tables, ALL new table designs must reference and conform to the existing schema style (naming conventions, ID strategy, timestamp patterns, constraint patterns). Ask the user to confirm the data model before proceeding.
+
+**User Experience:**
+- What does the user see and interact with?
+- What is the expected flow/sequence of actions?
+- How should errors be displayed to the user?
+- Are there any specific UI/UX requirements?
+
+**Integration & Architecture:**
+- Does this feature depend on or affect other features/modules?
+- Any external APIs or services involved?
+- What authentication/authorization model applies?
+- Any real-time requirements (WebSocket, SSE, polling)?
+
+**Edge Cases & Error Handling:**
+- What happens when things go wrong? (network failure, invalid input, concurrent access)
+- What are the boundary conditions? (empty states, max limits, permissions denied)
+- Any rate limiting, quotas, or resource constraints?
+
+**Non-Functional Requirements:**
+- Performance expectations? (response time, throughput)
+- Scalability considerations?
+- Security requirements? (encryption, audit logs, compliance)
+
+### Step 1.4: Iterative Clarification Loop
+
+After the initial deep-dive:
+
+1. **Summarize** what you've understood so far — present it back to the user
+2. **Identify gaps** — explicitly list any areas that are still unclear or ambiguous
+3. **Ask follow-up questions** for each gap
+4. **Repeat** until the user confirms: "Yes, that covers everything" or "That's clear enough"
+
+**Signs that brainstorming is complete:**
+- All functional requirements have concrete acceptance criteria
+- Data model entities and relationships are defined
+- Edge cases and error handling are addressed
+- Integration points are identified
+- The user has confirmed the summary is accurate
+
+**Signs that more questions are needed:**
+- User's answers contain vague terms ("handle it appropriately", "make it user-friendly", "standard behavior")
+- Core business rules are undefined ("depends on the situation")
+- Data relationships are unclear ("somehow connected")
+- User says "I'm not sure" — help them think through it with concrete options
+
+### Step 1.5: Requirements Summary
+
+Once brainstorming is complete, produce a structured requirements summary:
+
+```markdown
+## Requirements Summary
+
+### Project/Feature: [Name]
+
+### Core Functionality
+- [Bullet list of what the system does]
+
+### User Roles
+- [Role]: [What they can do]
+
+### Data Model Overview
+- [Entity]: [Key fields, relationships]
+
+### Key Business Rules
+- [Rule 1]
+- [Rule 2]
+
+### Integration Points
+- [External system/API/module]
+
+### Edge Cases & Error Handling
+- [Case]: [Expected behavior]
+
+### Non-Functional Requirements
+- [Requirement]
+
+### Confirmed by user: ✓
+```
+
+Present this summary to the user and get explicit confirmation before proceeding to Phase 2.
+
+**CHECKPOINT CP-FW-0**: Requirements fully clarified and confirmed by user.
+
+---
+
+## Phase 2: Plan
 
-**Goal**: Generate structured feature-list.json from natural language requirements.
+**Goal**: Generate structured feature-list.json from the clarified requirements.
 
 **STEPS**:
 
-1. **Invoke `app-planner` skill** with the user's requirement description:
+1. **Invoke `app-planner` skill** with the full requirements summary from Phase 1:
+   - Pass the structured requirements summary as input — NOT the raw user conversation
    - For new projects: standard planning mode
    - For existing projects with `--incremental`: incremental planning mode
 
 2. **Interactive planning** (if app-planner requires clarification):
-   - Pass through any questions to the user
-   - Collect responses and continue planning
+   - Because Phase 1 was thorough, app-planner should need minimal clarification
+   - If questions arise, answer from the Phase 1 context or pass through to user
 
 3. **Validate output**:
    - Confirm `feature-list.json` exists
@@ -113,11 +251,11 @@ When user says "add features to existing project" or the project already has fea
 
 **CHECKPOINT CP-FW-1**: `feature-list.json` generated and validated.
 
-**If user says `--from <file>`**: Skip this phase entirely.
+**If user says `--from <file>`**: Skip Phase 1 and Phase 2 entirely.
 
 ---
 
-## Phase 2: Launch
+## Phase 3: Launch
 
 **Goal**: Start the development pipeline.
 
@@ -136,18 +274,19 @@ When user says "add features to existing project" or the project already has fea
 2. **Invoke `dev-pipeline-launcher` skill**:
    - The launcher handles all prerequisites checks
    - The launcher presents execution mode choices to the user (foreground/background/manual)
-   - Do NOT duplicate execution mode selection here — let the launcher handle it
+   - The launcher asks whether to enable Critic Agent (adversarial review) — passes `--critic` flag if chosen
+   - Do NOT duplicate execution mode or critic selection here — let the launcher handle it
    - Returns PID/status and log file location
 
 3. **Verify launch success**:
    - Confirm pipeline is running
-   - Record PID and log path for Phase 3
+   - Record PID and log path for Phase 4
 
 **CHECKPOINT CP-FW-2**: Pipeline launched successfully.
 
 ---
 
-## Phase 3: Monitor
+## Phase 4: Monitor
 
 **Goal**: Track pipeline progress and report to user.
 
@@ -196,9 +335,9 @@ The workflow supports resuming by detecting existing state:
 
 | State Found | Resume From |
 |-------------|------------|
-| No `feature-list.json` | Phase 1: Plan |
-| `feature-list.json` exists, no pipeline state | Phase 2: Launch |
-| `feature-list.json` + pipeline state exists | Phase 3: Monitor (check status) |
+| No `feature-list.json` | Phase 1: Brainstorm |
+| `feature-list.json` exists, no pipeline state | Phase 3: Launch |
+| `feature-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
 | All features completed | Report completion, suggest next steps |
 
 **Resume**: If `feature-list.json` exists, ask user: "Existing feature plan found with N features. Resume pipeline or re-plan?"
@@ -222,11 +361,13 @@ While the pipeline runs, the user can continue the conversation:
 
 | Error | Action |
 |-------|--------|
-| `app-planner` cannot parse requirements | Ask user for clarification |
+| User's idea is too vague to brainstorm | Ask for more context: "Can you describe the main problem this solves?" |
+| Brainstorming stalls | Offer concrete options: "Would you prefer A or B?" |
+| `app-planner` cannot parse requirements | Refine the requirements summary and retry |
 | `feature-list.json` generation failed | Show error, retry with refined input |
 | Pipeline launch failed | Show daemon log, suggest manual start |
 | All features blocked/failed | Show status, suggest retrying specific features |
-| User wants to cancel mid-planning | Stop and save partial feature-list.json |
+| User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
 
 ---
 
@@ -234,8 +375,8 @@ While the pipeline runs, the user can continue the conversation:
 
 | Skill | Relationship |
 |-------|-------------|
-| `app-planner` | **Called by Phase 1** — generates feature-list.json |
-| `dev-pipeline-launcher` | **Called by Phase 2** — starts pipeline (handles execution mode selection) |
+| `app-planner` | **Called by Phase 2** — generates feature-list.json from clarified requirements |
+| `dev-pipeline-launcher` | **Called by Phase 3** — starts pipeline (handles execution mode selection) |
 | `bug-planner` | **Alternative** — for bug fix workflows |
 | `bugfix-pipeline-launcher` | **Alternative** — for bug fix pipelines |
 | `refactor-workflow` | **Alternative** — for code restructuring |
@@ -247,12 +388,13 @@ While the pipeline runs, the user can continue the conversation:
 | Dimension | feature-workflow | bug-fix-workflow | refactor-workflow |
 |-----------|-----------------|------------------|-------------------|
 | **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring |
+| **Brainstorming** | Yes — deep interactive Q&A | No (bug report is input) | No (analysis built-in) |
 | **Planning Skill** | `app-planner` | None (triage built-in) | None (analysis built-in) |
 | **Branch** | Pipeline manages per-feature | `fix/<BUG_ID>-*` | `refactor/<slug>` |
 | **Execution** | Foreground or background daemon | In-session, interactive | In-session |
-| **Input** | Requirements description | Bug report / stack trace | Module / code target |
+| **Input** | Rough idea or requirements | Bug report / stack trace | Module / code target |
 | **Output** | Multiple `feat()` commits | Single `fix()` commit | Single `refactor()` commit |
-| **User verification** | No (pipeline automated) | Yes (Phase 5) | Yes (Phase 5) |
+| **User verification** | Yes (Phase 1 brainstorm confirmation) | Yes (Phase 5) | Yes (Phase 5) |
 | **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | N/A |
 
 ---
@@ -263,8 +405,9 @@ All internal asset paths use `${SKILL_DIR}` placeholder for cross-IDE compatibil
 
 ## Output
 
-- `feature-list.json` (Phase 1 artifact)
-- Pipeline execution (Phase 2)
-- Progress updates (Phase 3)
+- Structured requirements summary (Phase 1 artifact)
+- `feature-list.json` (Phase 2 artifact)
+- Pipeline execution (Phase 3)
+- Progress updates (Phase 4)
 - Multiple git commits with `feat(<scope>):` prefix
 - Updated `.prizm-docs/` (via prizmkit-retrospective per feature)

package/bundled/skills/prizm-kit/SKILL.md

@@ -115,6 +115,6 @@ python3 ${SKILL_DIR}/scripts/install-prizmkit.py --target <project-skills-dir>
 
 Both CodeBuddy and Claude Code use unified commands for automatic doc updates and commit enforcement.
 Hooks and rules are configured automatically by `prizmkit-init`. See:
-- `core/templates/hooks/commit-intent.json` for the commit hook template
+- The commit hook template is configured automatically during `prizmkit-init`
 - `assets/project-memory-template.md` for the project memory template
 - The init skill creates `prizm-documentation.md` and `prizm-commit-workflow.md` rules