ai-workflow-init 3.4.0 → 3.6.0

package/.cursor/commands/create-plan.md

@@ -13,61 +13,146 @@ Generate a single planning doc at `docs/ai/planning/feature-{name}.md` using the
 - For medium/large tasks, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
 - Update todos immediately after progress; mark completed upon finish.
 
-## Step 1: Clarify Scope (Focused Q&A Guidelines)
+## Step 1: Analyze User Prompt
 
-Purpose: the agent MUST generate a short, numbered Q&A for the user to clarify scope; keep it relevant, avoid off-topic, and do not build a static question bank.
+**Parse user request to identify:**
+- **Feature type:** UI/Page, API/Service, Data/Database, Full-stack, Other
+- **Explicit requirements:** Framework, libraries, constraints mentioned
+- **Design context:**
+  - Has Figma URL/mention? → Flag for Step 4
+  - Has design description/screenshot? → Skip Steps 4-5
+  - No design source? → Flag for Step 5 (theme selection)
+- **Scope hints:** MVP mentions, deadlines, specific exclusions
 
-Principles:
+**Design Source Priority** (if multiple sources detected):
+1. **Figma URL** (highest priority) → Extract from Figma MCP (Step 4)
+2. **Screenshot/Image** → Use as visual reference, skip Figma extraction
+3. **Design description** → Use as text reference, skip Figma extraction
+4. **Multiple sources** → Ask user which to prioritize by asking user:
+   - Example: "You provided both Figma URL and screenshots. Which should I use as primary design source?"
+   - Options: "Figma design (extract full specs)", "Screenshots (visual reference only)", "Combine both"
 
-- Quickly classify context: a) Micro-UI, b) Page/Flow, c) Service/API/Data, d) Cross-cutting.
-- Ask only what is missing to produce Goal, Tasks, Risks, and DoD. Keep to 3–7 questions.
-- Do not re-ask what the user already stated; if ambiguous, confirm briefly (yes/no or single choice).
-- Keep each question short and single-purpose; avoid multi-part questions.
-- Answers may be a/b/c or free text; the agent is not required to present fixed option lists.
+**Output:** Internal classification to make Step 2 (Q&A) adaptive.
 
-Output format for Q&A:
+**Purpose:** Understand what user provided → Ask only what's missing in Step 2.
 
-- Number questions sequentially starting at 1 (e.g., "1.", "2.").
-- Under each question, provide 2–4 suggested options labeled with lowercase letters + ")" (e.g., "a)", "b)").
-- Keep options short (≤7 words) and add an "other" when useful.
-- Example:
-  1. UI library?
-     a) TailwindCSS b) Bootstrap c) SCSS d) Other
+## Step 2: Clarify Scope (Adaptive Q&A)
 
-Scope checklist to cover (ask only missing items, based on context):
+**Purpose:** Generate short Q&A (3-7 questions) to clarify scope. Ask only what's missing for Goal/Tasks/Risks/DoD.
 
-1. Problem & Users: the core problem and target user groups.
-2. In-scope vs Out-of-scope: what is included and excluded (e.g., MVP, no i18n, no payments).
-3. Acceptance Criteria (GWT): 2–3 key Given–When–Then scenarios.
-4. Constraints & Dependencies: technical constraints, libraries, real API vs mock, deadlines, external deps.
-5. Risks & Assumptions: known risks and key assumptions.
-6. Tasks Overview: 3–7 high-level work items.
-7. Definition of Done: completion criteria (build/test/docs/review).
+**Tool:** ask user for clarification
 
-Adaptive behavior:
+**Q&A Strategy** (based on Step 1 classification):
+- **If feature type clear:** Skip feature type question
+- **If design source detected:** Skip design-related questions
+- **If tech stack mentioned:** Skip framework questions
+- Prioritize scope/acceptance criteria over implementation details
 
-- Always reduce questions to what is necessary; once Goal/Tasks/Risks/DoD can be written, stop asking.
-- Prioritize clarifying scope and acceptance criteria before implementation details.
-- If the user already specified items (framework, API/Mock, deadlines, etc.), confirm briefly only.
+**Core Scope Questions** (ask only missing items):
+1. **Problem & Users:** What problem does this solve? Who uses it?
+2. **In-scope vs Out-of-scope:** What's included/excluded? (MVP features, no i18n, etc.)
+3. **Acceptance Criteria:** 2-3 Given-When-Then scenarios
+4. **Constraints:** Tech stack, libraries, APIs (real/mock), deadlines
+5. **Risks & Assumptions:** Known blockers or assumptions
+6. **Tasks:** 3-7 high-level work items
+7. **Definition of Done:** Build/test/review/docs criteria
 
-Then collect inputs (after Q&A):
+**Q&A Format:** Use ask user with 2-4 options per question.
+- Example: "1. UI library? a) TailwindCSS b) Bootstrap c) Other"
 
-- Feature name (kebab-case, e.g., `user-authentication`)
-- Short goal and scope
-- High-level tasks overview (3–7 items)
-- Definition of Done (build/test/review/docs)
+**Collect after Q&A:**
+- Feature name (kebab-case) - Ask if not derivable from prompt
+- Goal, scope, tasks, DoD
 
-## Step 2: Load Template
+---
+
+
+## Step 3: Research Codebase 
+
+**Purpose:** Understand existing patterns to ensure plan follows project standards and reuses existing features.
+
+**Automated process:**
+- Use workspace search and analysis to accomplish this task
+
+**What to explore** (based on feature type from Step 1):
+- **UI/Page:** Component patterns, styling approach, state management
+- **API/Service:** Endpoint patterns, middleware, validation, error handling
+- **Data:** Schema patterns, migration structure, model definitions
+- **Full-stack:** Both frontend and backend patterns
+
+**Exploration output** (concise summary, focus on actionable findings):
+- Similar features: [2-3 implementations]
+- Reusable components/utils: [key files]
+- Patterns to follow: [architecture patterns]
+- Files to reference: [key file paths]
+
+**Skip exploration if:**
+- New project (no similar patterns exist)
+- User says "fresh start"
+
+## Step 4: Extract Figma Design (Optional)
+
+**Trigger:** User mentions "figma", "design file", "mockup", or provides Figma URL (detected in Step 1).
+
+**Follow step by step in `.claude/skills/design/figma-extraction/SKILL.md`:**
+- Validate Figma MCP connection
+- Extract design tokens (colors, typography, spacing, shadows, border radius)
+- Extract component specs (states, variants, dimensions, hierarchies)
+- Extract responsive breakpoints (mobile/tablet/desktop)
+- Document extraction in planning doc format
+
+**Expected output:** "Design Specifications" section in planning doc with:
+- Reference (file name, frame, link, timestamp)
+- Design Tokens (complete palette, typography scale, spacing scale)
+- Component Breakdown (all components with detailed specs)
+- Responsive Specs (breakpoints and layout changes)
+
+**If extraction fails:**
+- Figma MCP not connected: Ask user to configure MCP or provide design description
+- Extraction fails: Ask user for alternative design source (screenshot, description)
+- Continue to Step 5 for theme selection if needed
+
+**Skip this step if:** No Figma URL/mention detected in Step 1.
+
+## Step 5: Design System & Theme (Optional)
+
+**Trigger:** Step 4 skipped (no Figma) AND user has NOT provided detailed design description/screenshot.
+
+**Follow design guidelines in `.claude/skills/design/` to guide design decisions:**
+- Design fundamentals (`.claude/skills/design/fundamentals/SKILL.md`): Core principles (spacing, typography, color, hierarchy)
+- Theme selection (`.claude/skills/design/theme-factory/SKILL.md`): Interactive theme selection based on brand personality
+- Responsive design (`.claude/skills/design/responsive/SKILL.md`): Mobile-first responsive patterns and breakpoints
+
+**Expected workflow:**
+1. Ask about brand personality/preferences if needed
+2. Choose aesthetic direction (minimal, bold, elegant, etc.)
+3. Propose complete design system (colors, fonts, spacing)
+4. Consider responsive strategy (mobile-first for target devices)
+5. Document theme/design specs in planning doc
 
-**Before creating the plan doc, read the following file:**
+**Expected output:** "Design System" or "Theme Specification" section in planning doc.
 
-- `docs/ai/planning/feature-template.md` - Template structure to follow
+**Skip this step if:** User provided design description/screenshot in Step 1.
+
+## Step 6: Load Template
+
+**Tool:** read `docs/ai/planning/feature-template.md`
+
+- Validate template contains required sections: Goal, Implementation Plan, DoD
+- If template not found: Use fallback minimal structure (Goal → Tasks → DoD)
 
 This template defines the required structure and format. Use it as the baseline for creating the planning doc.
 
-## Step 3: Draft the Plan (auto-generate)
+## Step 7: Draft the Plan (Auto-generate)
 
-Using the Q&A results and template, immediately generate the plan without asking for confirmation.
+**Using inputs from:**
+- Step 2: Scope, acceptance criteria, tasks, DoD
+- Step 3: Codebase patterns (if done)
+- Step 4: Figma design specs (if done)
+- Step 5: Theme specification (if done)
+- Step 6: Template structure
+
+**Generate immediately without asking for confirmation.**
 
 Auto-name feature:
 
@@ -77,15 +162,39 @@ Auto-name feature:
 
 ### Generate Single Planning Doc
 
-Produce a Markdown doc following `docs/ai/planning/feature-template.md` with all 5 sections:
+Produce a Markdown doc following `docs/ai/planning/feature-template.md`.
+
+**Include these sections** (in suggested order):
+
+1. **Codebase Context** (if exploration was done):
+   - Similar features found
+   - Reusable components/utils to use
+   - Architectural patterns to follow
+   - Key files to reference
+
+2. **Design Specifications** (if Figma extraction was done):
+   - Complete Figma design specs from Step 4
+   - Design tokens, component breakdown, responsive specs
+
+   **OR**
+
+   **Theme Specification** (if theme selection was done):
+   - Theme name and source file
+   - Color palette (primary, neutral, semantic)
+   - Typography (fonts, scale)
+   - Spacing scale and visual style
 
-1. **Goal & Acceptance Criteria**: Brief goal + Given-When-Then scenarios
-2. **Risks & Assumptions**: Known risks and key assumptions
-3. **Definition of Done**: Build/test/review/docs checklist
-4. **Implementation Plan**:
+3. **Goal & Acceptance Criteria**: Brief goal + Given-When-Then scenarios
+
+4. **Risks & Assumptions**: Known risks and key assumptions
+
+5. **Definition of Done**: Build/test/review/docs checklist
+
+6. **Implementation Plan**:
    - Summary: Brief description of solution approach (1-3 sentences)
    - Phases: Detailed tasks with pseudo-code
-5. **Follow-ups**: TODOs or deferred work
+
+7. **Follow-ups**: TODOs or deferred work
 
 **Estimate phase scope**:
 - Count total tasks from Q&A
@@ -93,40 +202,28 @@ Produce a Markdown doc following `docs/ai/planning/feature-template.md` with all
 - If tasks 6–12: suggest 2–3 phases (group by feature area or dependency order)
 - If tasks > 12: suggest 3–5 phases; prioritize logical grouping
 
-**For each phase, generate**:
-- Phase name (descriptive, e.g., "Database Schema Setup", "API Endpoints", "UI Components")
+**For each phase:**
+- Phase name: Descriptive (e.g., "API Endpoints", "UI Components")
 - Tasks list: `[ ] [ACTION] path/to/file — Summary`
-- Pseudo-code outline (show logic structure, not real code):
+- Pseudo-code: 3-5 lines, natural language, show inputs → logic → outputs
   ```
-  Pseudo-code:
-  - [Step 1]: what will be done
-  - [Step 2]: validation or check
-  - [Step 3]: data storage/return
-  ```
-
-**Pseudo-code guidelines**:
-- Keep to 3–5 lines per task
-- Show inputs, key logic, outputs
-- Use natural language, not actual syntax
-- Example for "Create user endpoint":
-  ```
-  Pseudo-code:
+  Example:
   - Parse username + password from request
-  - Validate password strength
-  - Hash password with bcrypt
-  - Store user in database
-  - Return success + user ID
+  - Validate password strength → Hash with bcrypt
+  - Store user in database → Return success + user ID
   ```
 
 Create the file automatically:
 
 - `docs/ai/planning/feature-{name}.md` - Use complete structure from `feature-template.md`
 
-Notify the user when done with summary: "Created plan with X phases: Phase 1 (name), Phase 2 (name), ..."
+**Notify user:** "Created plan with X phases: [Phase 1], [Phase 2], ..."
+
+## Step 8: Next Actions
 
-## Step 4: Next Actions
+Suggest: `/execute-plan` to begin implementation.
 
-Suggest running `execute-plan` to begin task execution. Implementation work will be driven from `docs/ai/planning/feature-{name}.md` as the task source.
+Implementation will be driven from `docs/ai/planning/feature-{name}.md`.
 
 Note: Test documentation will be created separately using the `writing-test` command.
 

package/.cursor/commands/execute-plan.md

@@ -19,13 +19,79 @@ Execute the feature plan by implementing tasks from the planning doc and updatin
 - Feature name (kebab-case, e.g., `user-authentication`)
 - Planning doc exists: `docs/ai/planning/feature-{name}.md`
 
+---
+
+
 ## Step 1: Gather Context
 
-- Ask for feature name if not provided (must be kebab-case).
-- Load planning doc: `docs/ai/planning/feature-{name}.md`.
-- **Load template:** Read `docs/ai/planning/feature-template.md` to understand required structure.
+**Tools:**
+- ask user for clarification if feature name not provided
+- read `docs/ai/planning/feature-{name}.md`
+- read `docs/ai/planning/feature-template.md`
+- read `docs/ai/project/CODE_CONVENTIONS.md`
+- read `docs/ai/project/PROJECT_STRUCTURE.md`
+
+**Process:**
+- Ask for feature name if not provided (must be kebab-case)
+- Load planning doc: `docs/ai/planning/feature-{name}.md`
+- Load template: `docs/ai/planning/feature-template.md` to understand required structure
+
+**Error handling:**
+- Planning doc not found: Cannot proceed, notify user and exit
+- Template not found: Continue without template structure validation
+- Standards docs not found: Warn user, proceed without standards guidance
+
+### 1a: Load Project Standards
+
+**Read and extract relevant sections** (keep summaries, not full content):
+
+1. **CODE_CONVENTIONS.md** (`docs/ai/project/CODE_CONVENTIONS.md`):
+   - Identify sections relevant to this feature type (e.g., frontend conventions for UI features)
+   - Extract key rules: naming patterns, file organization, code structure
+   - Keep concise summary of applicable rules
+
+2. **PROJECT_STRUCTURE.md** (`docs/ai/project/PROJECT_STRUCTURE.md`):
+   - Understand project architecture
+   - Identify where new files should go
+   - Note existing patterns to follow
+
+**Purpose**: These standards will guide implementation quality. Refresh this context at each phase boundary to prevent quality degradation in long plans.
+
+### 1b: Load Design/Theme Specifications (If Exists)
+
+**Check planning doc for design section**:
+
+**If "Design Specifications" exists** (Figma extraction):
+- Extract complete design specs into memory
+- Design tokens, component breakdown, responsive specs
+- **Note**: DO NOT fetch from Figma MCP again
+
+**If "Theme Specification" exists** (Theme selection):
+- Load theme details from planning doc
+- Extract: color palette, typography, spacing, visual style
+
+**Priority** (if multiple design sources exist):
+1. **Use Figma Design Specifications** (highest fidelity) - ignore Theme if Figma exists
+2. **Use Theme Specification** only if no Figma design
+3. **No design constraints** if neither exists
+
+If both Figma and Theme sections exist, use ONLY Figma and ignore Theme completely.
+
+**Purpose**: Implementation must match these exact specifications for consistency.
+
+### 1c: Load Codebase Context (If Exists)
+
+**Check planning doc for "Codebase Context" section**:
+
+If exists (exploration was done):
+- Similar features to reference
+- Reusable components/utils
+- Architectural patterns to follow
+- Key files to study
+
+**Purpose**: Follow existing patterns for consistency.
 
-### 1a: Phase Progress Detection
+### 1d: Phase Progress Detection
 
 If planning doc exists, scan for phase markers (`### Phase X:`):
 
@@ -49,7 +115,7 @@ If no phases detected (old format):
 
 ## Step 2: Build Task Queue
 
-- Parse tasks (checkboxes `[ ]`, `[x]`) from **current phase only** (from phase detection in Step 1a):
+- Parse tasks (checkboxes `[ ]`, `[x]`) from **current phase only** (from phase detection in Step 1d):
   - Primary source: Tasks under `### Phase X:` with `[ ] [ACTION] ...` entries (incomplete only).
   - For `[MODIFIED]` files, parse sub-bullets representing distinct logic items with line ranges.
   - **Skip completed phases** entirely (do not re-execute)
@@ -60,48 +126,53 @@ Note: Do not include Follow-ups section unless explicitly in current phase.
 
 ## Step 3: Implement Iteratively (per task)
 
+**Tools:**
+- Read(file_path=...) to check existing files
+- Write(file_path=..., content=...) for new files
+- Edit(file_path=..., old_string=..., new_string=...) for modifications
+- edit `docs/ai/planning/feature-{name}.md` to update checkboxes
+
+**At Phase Boundary** (when starting new phase):
+
+Refresh context to prevent quality degradation (see Notes for template format):
+- Remind code standards from CODE_CONVENTIONS.md
+- Remind design/theme specs if applicable
+- Remind codebase patterns to follow
+
+This reminder keeps standards visible during long implementations.
+
+---
+
 For each task in queue:
 
 1. **Status update**: Brief note (1–3 sentences) on what will be done.
 2. Plan minimal change set:
    - Identify files/regions to modify
    - Map changes to acceptance criteria from plan (reference if needed)
+   - **If design/theme specs exist**: Verify implementation matches colors, spacing, typography
+   - **Follow CODE_CONVENTIONS**: Apply naming patterns, file organization rules
 3. Implement changes:
    - Write/edit code according to the planning doc entries (`[ACTION]` items)
+   - **Apply design/theme specifications** (if exists): Use exact values from design specs (colors, spacing, typography, etc.)
+   - **Follow codebase patterns** (if exists): Match existing implementation style
    - Keep changes minimal and incremental
    - Avoid speculative changes beyond implementation scope
-4. Quick validation:
-   - Run build/compile if available
-   - Run fast unit/smoke tests if available
-   - Fix immediate issues before proceeding
-5. Persist notes to planning doc:
+4. Persist notes to planning doc:
    - File: `docs/ai/planning/feature-{name}.md`
    - Update the relevant `[ ]` entry to `[x]` when completed
    - For `MODIFIED` files with sub-bullets, mark each completed sub-bullet `[x]`
    - Include line ranges and concise summaries as per template
-6. Update planning doc:
+5. Update planning doc:
    - Mark completed tasks `[x]` with brief notes
    - Mark blocked tasks with reason
 
-## Step 4: Quality Checks
-
-After completing each task batch:
-
-- Detect available tools from project config (e.g., `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, build files) and run the appropriate non-interactive checks.
-- Linting on changed files (prefer non-interactive):
-  - JavaScript/TypeScript: `npx eslint .` or `pnpm eslint .` (add `--max-warnings=0` if desired)
-  - Python: `ruff .` or `flake8 .`
-  - Go: `golangci-lint run` or `go vet ./...`
-  - Rust: `cargo clippy -- -D warnings`
-  - Java: `./gradlew check` or `mvn -q -DskipTests=false -Dspotbugs.failOnError=true verify`
-  - Scope to changed files when possible for speed
-- Type checks (non-emitting where applicable):
-  - TypeScript: `npx tsc --noEmit`
-  - Python: `mypy .` (if configured) or `pyright` if present
-  - Go/Rust/Java: rely on compiler/type system via build step
-- Parallelize lint and type-check when safe; fix issues (up to 3 attempts) before proceeding.
+**Error handling:**
+- File write/edit fails: Retry once, then notify user
+- Design specs reference missing value: Use fallback or ask user
+- Cannot parse task description: Skip task, flag for manual review
+- Code generation uncertain: Ask user for clarification before implementing
 
-## Step 5: Phase Completion Check
+## Step 4: Phase Completion Check
 
 After completing all tasks in current phase:
 
@@ -113,13 +184,26 @@ After completing all tasks in current phase:
      Ready for Phase 3 (Frontend)?
      Run: /execute-plan
      ```
-   - If this is final phase:
+   - If all phases are complete:
      ```
      ✓ All phases complete!
-     Ready for code review?
-     Run: /code-review
+     Running quality checks now...
      ```
 
+## Step 5: Final Quality Checks (After All Phases Complete)
+
+Only run after ALL phases are marked complete. If incomplete phases remain, skip to Step 6.
+
+**Follow step by step in `.claude/skills/quality/code-check/SKILL.md` for automated validation:**
+- **Linting**: Code style and best practices validation
+- **Type Checking**: Type safety verification across modules
+- **Build Verification**: Ensure code compiles and bundles successfully
+
+**Error handling:**
+- Quality checks fail: Fix issues and retry until checks pass
+- Persistent failures: Document issues, proceed with caution
+- See Notes section for manual commands if needed
+
 ## Step 6: Next Actions
 
 After all phases complete:
@@ -130,12 +214,38 @@ After all phases complete:
 
 If phases remain:
 
-- User runs `/execute-plan` again; Phase detection (Step 1a) will resume correctly
+- User runs `/execute-plan` again; Phase detection (Step 1d) will resume correctly
 
 ## Notes
 
+### General Guidelines
+
 - Keep code changes minimal and focused on planning tasks
 - Document all changes by updating checkboxes in the planning doc
 - Avoid implementing features not in the planning doc scope
 - Modifies source code per planning scope; updates `docs/ai/planning/feature-{name}.md`. Does not modify unrelated files.
 - Idempotent: safe to re-run; updates checkboxes deterministically.
+
+### Context Refresh Template (Step 3 - Phase Boundary)
+
+When starting a new phase, remind agent of key context:
+
+```
+Phase X: [Phase Name]
+
+Code Standards Reminder:
+  - [Key convention 1 from CODE_CONVENTIONS.md]
+  - [Key convention 2 from CODE_CONVENTIONS.md]
+  - [Key pattern from PROJECT_STRUCTURE.md]
+
+Design/Theme Active: [Yes/No]
+  - Colors: [primary colors if applicable]
+  - Typography: [font families if applicable]
+  - Spacing: [scale values if applicable]
+
+Codebase Patterns:
+  - Reference: [similar feature files]
+  - Reuse: [components/utils to use]
+```
+
+This reminder keeps standards visible during long implementations and prevents quality degradation.