ai-workflow-init 3.0.0 → 3.2.2

package/.cursor/CLAUDE.md

@@ -0,0 +1,114 @@
+# AI Agent Workflow Standards
+
+## Core Coding Philosophy
+
+Apply these principles when providing solutions, generating code, or making technical decisions:
+
+### 1. Simplicity First
+- Choose the simplest solution that meets requirements
+- Avoid over-engineering and unnecessary abstractions
+- Simple code = fewer bugs, easier to maintain, easier to understand
+- Ask: "Can this be done more simply while still working?"
+- Complexity is a last resort, not a first choice
+
+### 2. Deep Understanding
+- Understand requirements fully before planning or coding
+- If unclear about requirement, flow, edge cases, or expected behavior → Ask the user
+- Never assume or guess - clarification prevents wasted effort
+- Ask questions like:
+  - "What should happen when X occurs?"
+  - "How should the system behave if Y fails?"
+  - "Is this the expected flow: A → B → C?"
+
+### 3. Multiple Options
+- Provide 2-5 solution options for each problem when appropriate
+- Present trade-offs clearly: pros/cons, complexity, performance, maintainability
+- Format: "Option 1: [approach] - Pros: [...] Cons: [...]"
+- Let user choose based on their context and priorities
+- Not every problem has one "best" solution
+
+### 4. Think Ahead
+- While keeping solutions simple, consider future implications:
+  - How will this scale with more data/users?
+  - What if requirements change slightly?
+  - Are there security vulnerabilities?
+  - What are performance bottlenecks?
+- Balance: Simple now + adaptable for reasonable future needs
+- Do not build for hypothetical futures, but be aware of likely changes
+
+**Philosophy in practice:**
+- Simplicity: Use built-in array methods instead of custom loop logic
+- Deep Understanding: "Should this API return 404 or 400 for invalid IDs?"
+- Multiple Options: "We can use: 1) localStorage (simple), 2) IndexedDB (scalable), or 3) Backend API (persistent)"
+- Think Ahead: "This works for 100 items, but consider pagination for 10,000+"
+
+---
+
+## Core Workflow: Plan → Implement → Test → Review
+
+### Workflow Alignment
+- **Plan:** Create feature planning doc at `docs/ai/planning/feature-{name}.md` before coding. Do not start until planning exists and is agreed.
+- **Implement:** Provide 1-3 sentence status updates before operations. Use file editing tools, not copy-paste. Update checkboxes `[ ]` → `[x]` in planning doc.
+- **Test:** Run linter/type-check/build on changed files after each batch. Auto-fix issues (up to 3 attempts) before asking for help.
+- **Review:** When complete, validate against planning doc acceptance criteria and CODE_CONVENTIONS.md.
+
+## File Structure
+
+### Planning Documents
+- Location: `docs/ai/planning/feature-{name}.md` (kebab-case)
+- Must include: Goal, Acceptance Criteria (GWT), Risks, Implementation Phases, Follow-ups
+- Template: `docs/ai/planning/feature-template.md`
+
+### Project Standards
+- Coding conventions: `docs/ai/project/CODE_CONVENTIONS.md`
+- Architecture guide: `docs/ai/project/PROJECT_STRUCTURE.md`
+- Language templates: `docs/ai/project/template-convention/`
+
+## Tooling Strategy
+- Prefer semantic search across codebase; use grep only for exact matches
+- Default to parallel execution for independent operations
+- Quality tools: ESLint, TypeScript, Prettier (auto-format/auto-fix when possible)
+
+## Communication
+- Use Markdown only when necessary; backticks for `files/dirs/functions/classes`
+- Status updates before/after important actions
+- Mirror user's chat language; code/comments always in English
+
+## Code Presentation
+- Existing code: cite with `startLine:endLine:filepath` (no language tag)
+- New code: fenced blocks with language tag, no line numbers
+
+## TODO Policy
+- For medium/large tasks: create todos (≤14 words, verb-led)
+- Keep only ONE `in_progress` item
+- Update immediately after progress; mark completed upon finish
+
+## Git Workflow
+- Feature branches: `feature/{name}` (match planning doc name)
+- Commit format: `[phase] brief description`
+- Examples: `[planning] create user auth plan`, `[phase-1] implement database schema`
+
+## Slash Commands
+- `/create-plan` - Generate planning doc
+- `/execute-plan` - Implement tasks from planning doc
+- `/modify-plan` - Modify plan after implementation
+- `/code-review` - Validate against standards
+- `/generate-standards` - Update CODE_CONVENTIONS.md
+- `/writing-test` - Generate tests from acceptance criteria
+- `/init-chat` - Load project rules (AGENTS.md)
+
+## Quality Gates
+### Before marking task complete:
+- Code matches planning doc specification
+- Linting passes (no warnings)
+- Type checking passes (if applicable)
+- Build succeeds (if applicable)
+- Checkbox updated in planning doc: `[x]`
+
+---
+
+**Claude Code Specifics:**
+- This file is automatically loaded every session
+- Commands inherit these standards
+- Use `/context` to see loaded memory
+- Use `/usage` to monitor token consumption

package/cli.js

@@ -244,6 +244,20 @@ async function main() {
     } catch (_) {
       run(`wget -qO .claude/hooks.json ${RAW_BASE}/.claude/hooks.json`);
     }
+
+    // Download skills folder (always overwrite to get latest)
+    step("🚚 Downloading Claude Code skills (.claude/skills)...");
+    if (!existsSync(".claude/skills")) {
+      mkdirSync(".claude/skills", { recursive: true });
+    }
+    run(`npx degit ${REPO}/.claude/skills .claude/skills --force`);
+
+    // Download themes folder (always overwrite to get latest)
+    step("🚚 Downloading Claude Code themes (.claude/themes)...");
+    if (!existsSync(".claude/themes")) {
+      mkdirSync(".claude/themes", { recursive: true });
+    }
+    run(`npx degit ${REPO}/.claude/themes .claude/themes --force`);
   }
 
   // Clone Cursor prompts (luôn ghi đè)

package/docs/ai/planning/feature-template.md

@@ -2,7 +2,221 @@
 
 Note: All content in this document must be written in English.
 
-## 1. Goal & Acceptance Criteria
+## 1. Codebase Context
+
+> **Note**: This section is auto-generated by `/create-plan` exploration phase. Include only if relevant patterns were found.
+
+### Similar Features
+- {path/to/similar-feature-1} - {brief description of what to learn from it}
+- {path/to/similar-feature-2} - {brief description of what to learn from it}
+
+### Reusable Components/Utils
+- {path/to/component.tsx} - {what it does, how to use}
+- {path/to/util.ts} - {what it does, when to use}
+
+### Architectural Patterns
+- {Pattern name}: {description}
+- {Pattern name}: {description}
+
+### Key Files to Reference
+- {path/to/file} - {why it's relevant}
+
+---
+
+## 2. Design Specifications
+
+> **Note**: This section is for design specifications from any source (Figma, screenshot, detailed description, etc.). Include only if design source was provided.
+
+### Reference
+- **File**: {Figma file name}
+- **Frame**: {Frame name/ID}
+- **Link**: {Figma URL}
+- **Extracted**: {date/time}
+
+### Design Tokens
+
+**Colors**:
+- Primary: #{hex} (Usage: buttons, links, key actions)
+- Secondary: #{hex} (Usage: secondary actions)
+- Accent: #{hex} (Usage: highlights, badges)
+- Neutral-50: #{hex}
+- Neutral-100: #{hex}
+- [... all colors with usage notes]
+
+**Typography**:
+- Heading 1: {font-family}, {size}px, {weight}, {line-height}
+- Heading 2: {font-family}, {size}px, {weight}, {line-height}
+- Body: {font-family}, {size}px, {weight}, {line-height}
+- Caption: {font-family}, {size}px, {weight}, {line-height}
+
+**Spacing Scale**: {4, 8, 16, 24, 32, 48, 64}px
+
+**Border Radius**: {4, 8, 12, 16}px
+
+**Shadows**:
+- sm: {shadow definition}
+- md: {shadow definition}
+- lg: {shadow definition}
+
+### Component Breakdown
+
+**{Component Name}** (Figma ID: {component-id})
+- **States**: default, hover, active, disabled, loading, error
+- **Variants**: primary, secondary, outline, ghost
+- **Dimensions**: {width}px × {height}px (or min/max)
+- **Specifications**:
+  - Padding: {top}px {right}px {bottom}px {left}px
+  - Border: {width}px solid {color}
+  - Border radius: {value}px
+  - Typography: {style from above}
+  - Colors:
+    - Background: #{hex}
+    - Text: #{hex}
+    - Border: #{hex}
+  - States:
+    - Hover: {changes}
+    - Active: {changes}
+    - Disabled: {changes}
+
+[Repeat for each component in the design]
+
+### Responsive Specifications
+
+**Mobile (320-640px)**:
+- Layout: {description}
+- Component adjustments: {what changes}
+- Typography scaling: {changes}
+
+**Tablet (641-1024px)**:
+- Layout: {description}
+- Component adjustments: {what changes}
+
+**Desktop (1025px+)**:
+- Layout: {description}
+- Component adjustments: {what changes}
+
+### Assets
+- Icons: {list icon names and sources}
+- Images: {list image URLs or file references}
+
+---
+
+## 2. Theme Specification
+
+> **Note**: This section is auto-generated by `/create-plan` theme selection. Include only if theme was selected (no design source provided).
+> **Important**: Use EITHER "Design Specifications" OR "Theme Specification", not both. Any design source (Figma, screenshot, description) takes precedence over theme.
+
+### Selected Theme
+- **Name**: {Theme Name}
+- **Source**: .claude/themes/{filename}.theme.json
+- **Personality**: {personality traits}
+
+### Color Palette
+
+**Primary**:
+- 50: #{hex} (lightest backgrounds, subtle highlights)
+- 100: #{hex}
+- 200: #{hex}
+- 300: #{hex}
+- 400: #{hex}
+- 500: #{hex} (buttons, links, primary actions)
+- 600: #{hex} (hover states)
+- 700: #{hex} (active states)
+- 800: #{hex}
+- 900: #{hex} (darkest, high emphasis)
+
+**Secondary** (if applicable):
+- 500: #{hex} (secondary actions, supporting UI)
+- 600: #{hex} (hover)
+- 700: #{hex} (active)
+
+**Accent**:
+- 500: #{hex} (highlights, calls-to-action)
+- 600: #{hex} (hover)
+
+**Neutral**:
+- 50: #{hex} (backgrounds, lightest)
+- 100: #{hex}
+- 200: #{hex} (subtle borders)
+- 300: #{hex} (borders)
+- 400: #{hex} (placeholders, disabled)
+- 500: #{hex} (secondary text)
+- 600: #{hex}
+- 700: #{hex} (body text)
+- 800: #{hex}
+- 900: #{hex} (headings, darkest)
+
+**Semantic**:
+- Success: #{hex} (confirmations, positive actions)
+- Warning: #{hex} (warnings, caution)
+- Error: #{hex} (errors, destructive actions)
+- Info: #{hex} (informational messages)
+
+### Typography
+
+**Font Families**:
+- Heading: {font-family} (with web-safe fallbacks)
+- Body: {font-family} (with web-safe fallbacks)
+- Mono: {font-family} (for code blocks)
+
+**Type Scale**:
+- xs: {size}px
+- sm: {size}px
+- base: {size}px (body text default)
+- lg: {size}px
+- xl: {size}px
+- 2xl: {size}px
+- 3xl: {size}px
+- 4xl: {size}px
+- 5xl: {size}px
+
+**Font Weights**:
+- normal: {weight}
+- medium: {weight}
+- semibold: {weight}
+- bold: {weight}
+
+**Line Heights**:
+- tight: {value} (headings)
+- normal: {value} (body)
+- relaxed: {value} (long-form content)
+
+### Spacing Scale
+
+**Scale**: {4, 8, 16, 24, 32, 48, 64}px (base-{4/8} system)
+
+**Usage**:
+- xs: {value}px (tight spacing, small gaps)
+- sm: {value}px (component internal padding)
+- md: {value}px (standard spacing between elements)
+- lg: {value}px (section spacing)
+- xl: {value}px (large gaps)
+- 2xl: {value}px (very large spacing)
+
+### Visual Style
+
+**Border Radius**:
+- sm: {value}px (buttons, inputs)
+- md: {value}px (cards)
+- lg: {value}px (modals)
+- xl: {value}px (large components)
+- full: 9999px (pills, circular)
+
+**Shadows**:
+- sm: {shadow definition}
+- md: {shadow definition}
+- lg: {shadow definition}
+- xl: {shadow definition}
+
+**Usage Notes**:
+- Apply colors from palette only (no arbitrary hex codes)
+- Use spacing scale values only (no arbitrary margins/paddings)
+- Follow typography scale (no font sizes outside scale)
+- Semantic colors for their intended purpose only
+
+---
+
+## 3. Goal & Acceptance Criteria
 
 ### Goal
 - [Brief description: what problem this solves and why it matters]
@@ -12,7 +226,7 @@ Note: All content in this document must be written in English.
 - When [action or event occurs]
 - Then [expected result or outcome]
 
-## 2. Risks & Assumptions
+## 4. Risks & Assumptions
 
 ### Risks
 - [Potential issues, blockers, or unknowns]
@@ -20,7 +234,7 @@ Note: All content in this document must be written in English.
 ### Assumptions
 - [What we assume is true for this plan to work]
 
-## 3. Definition of Done
+## 5. Definition of Done
 - [ ] Build passes (linter, type checks, compile)
 - [ ] Tests added and passing
 - [ ] Code reviewed and approved
@@ -28,7 +242,7 @@ Note: All content in this document must be written in English.
 
 ---
 
-## 4. Implementation Plan
+## 6. Implementation Plan
 
 ### Summary
 [Brief description of the solution approach in 1-3 sentences]
@@ -64,6 +278,6 @@ Notes:
 - Each phase groups related tasks; phases execute sequentially
 - Use only one phase for small features (≤ 5 tasks); use multiple phases for larger features
 
-## 5. Follow-ups
+## 7. Follow-ups
 - [ ] [TODO item or deferred work]
 - [ ] [Future improvements]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-workflow-init",
-  "version": "3.0.0",
+  "version": "3.2.2",
   "description": "Initialize AI workflow docs & commands into any repo with one command",
   "bin": {
     "ai-workflow-init": "./cli.js"