ai-workflow-init 6.6.0 → 6.6.1

package/.claude/CLAUDE.md

@@ -8,6 +8,11 @@
   - Avoid over-engineering and unnecessary abstractions
   - Don't build for hypothetical futures
 
+- **Readability > Cleverness**
+  - Prefer clear, readable code over clever one-liners
+  - Code is read more often than written - optimize for understanding
+  - If code needs a comment to explain what it does, consider rewriting it
+
 - **Think ahead ONLY for:**
   - **Security**: Input validation, authentication, authorization
   - **Performance**: Scalability bottlenecks, query optimization
@@ -18,9 +23,11 @@
   - ✅ Add input validation for user data (security)
   - ✅ Consider pagination for large datasets (performance)
   - ❌ Don't create abstractions for one-time operations
+  - ❌ Don't write clever one-liners that require mental parsing
 
 ### 2. Deep Understanding
 - If unclear about requirements, edge cases, or expected behavior → **Ask first**
+- Use `AskUserQuestion` tool to ask multiple questions at once (up to 4)
 - Never assume or guess - clarification prevents wasted effort
 - Key questions:
   - "What should happen when X occurs?"

package/.claude/commands/audit-workflow.md

@@ -0,0 +1,209 @@
+---
+name: audit-workflow
+description: Audit Claude Code workflow configuration (agents, skills, commands, hooks, output-styles) and provide improvement recommendations.
+---
+
+# Workflow Audit
+
+Analyze the Claude Code workflow configuration in this project and provide actionable recommendations.
+
+## Audit Process
+
+### Step 1: Gather Workflow Files
+
+Collect all workflow configuration files:
+
+```
+Read and analyze:
+- .claude/CLAUDE.md (main instructions)
+- .claude/settings.json (hooks configuration)
+- .claude/settings.local.json (local hooks)
+- .claude/agents/*.md (all agent definitions)
+- .claude/skills/*/SKILL.md (all skill definitions)
+- .claude/commands/*.md (all command definitions)
+- .claude/output-styles/*.md (all output styles)
+```
+
+Use Glob to find all files, then Read each one.
+
+### Step 2: Analyze Each Category
+
+For each category, evaluate:
+
+#### 2.1 Skills Analysis
+
+| Criteria | Check |
+|----------|-------|
+| **Trigger clarity** | Is `description` specific about when to load? |
+| **Overlap detection** | Do multiple skills cover same triggers? |
+| **Size efficiency** | Is SKILL.md < 500 lines? Uses references for large content? |
+| **Progressive disclosure** | Does it use references/ for optional content? |
+| **Auto-load frequency** | Does "ALWAYS load when..." appear too often? |
+
+**Overlap detection keywords to check:**
+- UI/frontend: `frontend-design-*`, `ux-*`
+- Code quality: `quality-*`, `*-review`
+- Testing: `*-test`, `writing-test`
+
+#### 2.2 Commands Analysis
+
+| Criteria | Check |
+|----------|-------|
+| **Purpose clarity** | Is the command's purpose clear from name + description? |
+| **Workflow alignment** | Does it follow CLAUDE.md guidelines? |
+| **Agent delegation** | Does it use Task tool for complex sub-tasks? |
+| **Duplication** | Are there commands that do similar things? |
+
+#### 2.3 Agents Analysis
+
+| Criteria | Check |
+|----------|-------|
+| **Role clarity** | Is the agent's specialized role well-defined? |
+| **Tool access** | Does it have appropriate tool restrictions? |
+| **Prompt quality** | Is the prompt concise but complete? |
+
+#### 2.4 Hooks Analysis
+
+| Criteria | Check |
+|----------|-------|
+| **Necessity** | Is each hook actually needed? |
+| **Performance** | Are hooks lightweight (< 1 second execution)? |
+| **Error handling** | Do hooks exit gracefully on failure? |
+| **Matcher specificity** | Are matchers precise enough? |
+
+#### 2.5 Output Styles Analysis
+
+| Criteria | Check |
+|----------|-------|
+| **Use case clarity** | When should this style be applied? |
+| **Conflict potential** | Does it conflict with other styles? |
+
+#### 2.6 CLAUDE.md Analysis
+
+| Criteria | Check |
+|----------|-------|
+| **Conciseness** | Is it under 500 lines? No redundant info? |
+| **Actionability** | Are instructions clear and actionable? |
+| **Conflicts** | Does it conflict with skill instructions? |
+
+### Step 3: Context Usage Estimation
+
+Estimate token usage for each component:
+
+```
+Token estimation formula:
+- ~4 characters = 1 token (rough estimate)
+- Metadata always loaded: name + description (~100-200 tokens each)
+- Body loaded on trigger: full content
+```
+
+Calculate:
+1. **Always-loaded tokens**: Sum of all metadata
+2. **Frequently-loaded tokens**: Skills with "ALWAYS load" triggers
+3. **On-demand tokens**: Skills with specific triggers
+
+### Step 4: Generate Report
+
+Output format:
+
+```markdown
+# Workflow Audit Report
+
+## Summary
+
+| Category | Count | Issues | Recommendations |
+|----------|-------|--------|-----------------|
+| Skills | X | Y | Z |
+| Commands | X | Y | Z |
+| Agents | X | Y | Z |
+| Hooks | X | Y | Z |
+| Output Styles | X | Y | Z |
+
+## Context Budget Analysis
+
+### Always-Loaded (~X tokens)
+- CLAUDE.md: ~X tokens
+- Skill metadata: ~X tokens (Y skills × ~100 tokens)
+- Total baseline: ~X tokens
+
+### Frequently-Loaded (~X tokens per session)
+- skill-name-1 (ALWAYS load for frontend): ~X tokens
+- skill-name-2 (ALWAYS load for React): ~X tokens
+
+### On-Demand
+- skill-name-3: ~X tokens (loads for specific trigger)
+
+## Detailed Findings
+
+### 🔴 Critical Issues
+Issues that significantly impact performance or cause errors.
+
+### 🟡 Improvements
+Optimizations that would improve efficiency.
+
+### 🟢 Best Practices Followed
+Positive patterns worth maintaining.
+
+## Recommendations
+
+### High Priority
+1. [Specific actionable recommendation]
+   - **Impact**: [What improves]
+   - **Effort**: [Low/Medium/High]
+
+### Medium Priority
+...
+
+### Low Priority (Nice to Have)
+...
+
+## Overlap Analysis
+
+### Potential Skill Overlaps
+| Skills | Overlap Area | Recommendation |
+|--------|--------------|----------------|
+| A, B | frontend triggers | Consider merging or clarifying triggers |
+
+### Command Redundancies
+...
+
+## Suggested Consolidations
+
+If skills/commands can be merged:
+- Merge `skill-a` + `skill-b` → `combined-skill` (saves ~X tokens)
+```
+
+## Analysis Guidelines
+
+### What Makes a Good Workflow
+
+1. **Minimal always-loaded content**: Only essential instructions in CLAUDE.md
+2. **Specific triggers**: Skills load only when truly needed
+3. **No overlaps**: Each skill/command has unique purpose
+4. **Progressive disclosure**: Large content split into references
+5. **Lightweight hooks**: Fast execution, graceful failures
+
+### Red Flags to Watch For
+
+- Skills with "ALWAYS load" for broad triggers (e.g., "any code")
+- Multiple skills triggering on same keywords
+- Commands that duplicate skill functionality
+- Hooks that run on every tool use
+- CLAUDE.md > 300 lines
+- Skills > 500 lines without using references/
+
+### Token Budget Guidelines
+
+| Budget Level | Always-Loaded | Recommendation |
+|--------------|---------------|----------------|
+| Lean | < 2000 tokens | Excellent |
+| Normal | 2000-5000 | Good |
+| Heavy | 5000-10000 | Consider optimization |
+| Bloated | > 10000 | Needs consolidation |
+
+## Execution
+
+1. Run full analysis
+2. Generate report with findings
+3. Prioritize recommendations by impact/effort ratio
+4. Offer to implement quick wins if user approves

package/.claude/commands/cleanup.md

@@ -0,0 +1,184 @@
+---
+name: cleanup
+description: Cleans up workflow markdown files older than the configured retention period.
+---
+
+## Configuration
+
+```
+RETENTION_DAYS = 7
+```
+
+> **To change retention period**: Update the `RETENTION_DAYS` value above.
+
+---
+
+## Goal
+
+Clean up workflow markdown files older than `RETENTION_DAYS` in `docs/ai/` directories.
+
+---
+
+## Step 1: Select Cleanup Scope
+
+**Tool:** AskUserQuestion
+
+```
+Question: Which scope do you want to clean up?
+Options:
+  1. Main files only - Delete main files (exclude archive/ folders)
+  2. Archive only - Delete only files in archive/ folders
+  3. All files - Delete both main files and archive/
+```
+
+**Set internal flag:** `CLEANUP_SCOPE = main_only | archive_only | all`
+
+---
+
+## Step 2: Scan Files
+
+**Directories to scan:**
+
+```
+docs/ai/planning/             # epic-*.md, feature-*.md
+docs/ai/planning/archive/     # backup files
+docs/ai/testing/              # unit-*.md, integration-*.md
+docs/ai/requirements/         # req-*.md
+docs/ai/requirements/agents/  # ba-*.md, sa-*.md, research-*.md, uiux-*.md
+docs/ai/requirements/archive/ # backup files
+```
+
+**Based on CLEANUP_SCOPE:**
+- `main_only`: Scan all except `archive/` folders
+- `archive_only`: Scan only `archive/` folders
+- `all`: Scan everything
+
+**Command to find old files (older than RETENTION_DAYS):**
+
+```bash
+find docs/ai/planning docs/ai/testing docs/ai/requirements -name "*.md" -type f -mtime +{RETENTION_DAYS} 2>/dev/null
+```
+
+**For archive only:**
+
+```bash
+find docs/ai/planning/archive docs/ai/requirements/archive -name "*.md" -type f -mtime +{RETENTION_DAYS} 2>/dev/null
+```
+
+**For main only (exclude archive):**
+
+```bash
+find docs/ai/planning docs/ai/testing docs/ai/requirements -name "*.md" -type f -mtime +{RETENTION_DAYS} -not -path "*/archive/*" 2>/dev/null
+```
+
+---
+
+## Step 3: Build File List
+
+**For each file found:**
+1. Get file path
+2. Get last modified date
+3. Calculate age in days
+
+**Format output:**
+
+```markdown
+## Files older than {RETENTION_DAYS} days
+
+| File | Last Modified | Age |
+|------|---------------|-----|
+| docs/ai/planning/feature-login.md | 2025-01-10 | 15 days |
+| docs/ai/planning/archive/feature-auth_20250105.md | 2025-01-05 | 20 days |
+| docs/ai/testing/unit-auth.md | 2025-01-12 | 13 days |
+
+**Total: X files**
+```
+
+**If no files found:**
+
+```
+✓ No files older than {RETENTION_DAYS} days found in the selected scope.
+```
+
+Then exit.
+
+---
+
+## Step 4: Confirm Deletion
+
+**Tool:** AskUserQuestion
+
+```
+Question: Confirm deletion of {X} files listed above?
+Options:
+  1. Yes, delete all - Delete all listed files
+  2. No, cancel - Cancel, do not delete anything
+```
+
+**If user chooses "No, cancel":**
+
+```
+✓ Cancelled. No files were deleted.
+```
+
+Then exit.
+
+---
+
+## Step 5: Execute Deletion
+
+**For each file in the list:**
+
+```bash
+rm "{file_path}"
+```
+
+**Track results:**
+- Files deleted successfully
+- Files failed to delete (if any)
+
+---
+
+## Step 6: Report Results
+
+```markdown
+## Cleanup Complete
+
+✓ Deleted: {success_count} files
+✗ Failed: {failed_count} files
+
+### Deleted Files
+- docs/ai/planning/feature-login.md
+- docs/ai/planning/archive/feature-auth_20250105.md
+- docs/ai/testing/unit-auth.md
+
+{If any failed:}
+### Failed to Delete
+- {file_path}: {error message}
+```
+
+---
+
+## Notes
+
+- **Retention period**: Configured via `RETENTION_DAYS` variable (default: 7)
+- **Safe by default**: Always requires confirmation before deletion
+- **No orphan detection**: Only checks file age, not relationships
+- **Templates excluded**: Does not delete `*-template.md` files
+
+### File Patterns Affected
+
+| Directory | Patterns |
+|-----------|----------|
+| `docs/ai/planning/` | `epic-*.md`, `feature-*.md` |
+| `docs/ai/planning/archive/` | `epic-*_*.md`, `feature-*_*.md` |
+| `docs/ai/testing/` | `unit-*.md`, `integration-*.md` |
+| `docs/ai/requirements/` | `req-*.md` |
+| `docs/ai/requirements/agents/` | `ba-*.md`, `sa-*.md`, `research-*.md`, `uiux-*.md` |
+| `docs/ai/requirements/archive/` | `req-*_*.md` |
+
+### Excluded from Cleanup
+
+- Template files: `*-template.md`
+- Non-markdown files
+- Files in other directories

package/.claude/output-styles/qna-consultant.md

@@ -0,0 +1,237 @@
+# Q&A Consultant Output Style
+
+Consultation and idea discussion mode. Claude Code is READ-ONLY - no workspace modifications.
+
+## Core Behavior
+
+**Read-Only Mode:**
+- ✅ Read files, search code, explore codebase
+- ✅ Explain, analyze, give opinions
+- ❌ NO creating new files
+- ❌ NO editing files
+- ❌ NO running commands that modify workspace
+
+If user requests modifications:
+> "Currently in Q&A mode (read-only). Would you like to switch to normal mode to edit code?"
+
+---
+
+## The 4 Rules Framework
+
+### Rule 1: Stop & Ask (Solving "Lack of Context")
+
+**Before answering, MUST identify missing context:**
+
+```
+🔍 Understanding the question:
+- Core problem: [1 short sentence]
+- Scope: [small/medium/large]
+- Type: [concept/how-to/decision/debug/architecture]
+
+❓ Missing context: [list what's unclear or needed]
+```
+
+**CRITICAL:**
+- If missing context is critical → **ASK before answering**
+- If missing context is minor → State assumption and proceed
+- Never guess on: requirements, constraints, or user's actual goal
+
+**Stop & Ask triggers:**
+- Ambiguous terms ("make it better", "optimize this")
+- Missing constraints (scale, timeline, team size)
+- Unclear scope (one file vs entire system)
+- Multiple valid interpretations
+
+**Example:**
+```
+❓ Missing context:
+- What's the expected traffic? (affects caching strategy)
+- Is this for a new project or existing codebase?
+
+→ Before I answer, can you clarify these?
+```
+
+---
+
+### Rule 2: Rate Your Confidence
+
+**Every answer MUST include confidence rating:**
+
+```
+🎯 Confidence: [HIGH/MEDIUM/LOW]
+- HIGH (90%+): Well-understood problem, proven solution
+- MEDIUM (60-89%): Good understanding, some assumptions
+- LOW (<60%): Limited context, speculative answer
+```
+
+**What affects confidence:**
+- ⬆️ Higher: Saw the actual code, clear requirements, standard problem
+- ⬇️ Lower: Assumptions made, edge cases unknown, novel situation
+
+**When LOW confidence:**
+1. State what would increase confidence
+2. Offer to investigate further (read more code, ask questions)
+3. Mark speculative parts clearly
+
+**Example:**
+```
+🎯 Confidence: MEDIUM (70%)
+- Based on: Standard React patterns
+- Assumption: You're using React 18+
+- Would increase to HIGH if: I could see your component structure
+```
+
+---
+
+### Rule 3: Ockham's Razor (Solving "Over-engineering")
+
+**The simplest solution that works is the best solution.**
+
+**Before every answer, run this check:**
+
+```
+⚖️ Simplicity Check:
+- Is this complexity necessary? [yes/no]
+- Simplest solution: [describe]
+- Am I solving a real problem or imaginary one?
+```
+
+**Ockham's Razor rules:**
+1. **Start minimal** - Add complexity only when proven needed
+2. **Challenge assumptions** - "Do you actually need X?"
+3. **Prefer boring tech** - Standard library > fancy framework
+4. **One step at a time** - Don't suggest 10 steps when 3 work
+
+**Red flags (over-engineering signals):**
+- "Let me create an abstraction layer..."
+- "We should consider 15 edge cases..."
+- "This is a common enterprise pattern..."
+- Suggesting major refactor for a small question
+
+**Good patterns:**
+- "The simplest approach is..."
+- "You don't need to complicate this, just..."
+- "For your use case, X is enough"
+- "Over-engineering alert: You're solving a problem that doesn't exist yet"
+
+---
+
+### Rule 4: Context-Aware Constraints
+
+**Adapt answer based on user's actual context, not ideal scenarios.**
+
+**Context factors to consider:**
+
+| Factor | Questions to ask |
+|--------|------------------|
+| Scale | How many users? Requests/sec? |
+| Team | Solo dev or team? Experience level? |
+| Timeline | MVP or production-ready? |
+| Existing code | Greenfield or legacy? |
+| Constraints | Budget? Infra limitations? |
+
+**Constraint-aware responses:**
+
+```
+📋 Applying to your context:
+- Given [constraint], I recommend [simpler option]
+- If [context changes], then consider [complex option]
+```
+
+**Examples:**
+
+| Context | DON'T suggest | DO suggest |
+|---------|---------------|------------|
+| Solo dev, MVP | Microservices, K8s | Monolith, simple deploy |
+| 100 users | Redis cluster | In-memory cache |
+| Legacy codebase | Full rewrite | Incremental improvement |
+| Tight deadline | Perfect architecture | Good-enough solution |
+
+---
+
+## Response Template
+
+Every response should follow this structure:
+
+```
+🔍 Understanding the question:
+- Core problem: [...]
+- Scope: [...]
+- Type: [...]
+❓ Missing context: [list or "None - clear question"]
+
+⚖️ Simplicity Check:
+- Complexity necessary? [yes/no + why]
+- Simplest solution: [...]
+
+🎯 Confidence: [HIGH/MEDIUM/LOW] ([%])
+- Based on: [...]
+- Assumptions: [...]
+
+---
+
+📌 TL;DR: [1-2 sentence summary]
+
+[Detailed explanation if needed]
+
+💡 Simplest approach: [concrete recommendation]
+
+📋 Context considerations:
+- If [context A]: [adjust recommendation]
+- If [context B]: [adjust recommendation]
+```
+
+---
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Unclear requirements | Rule 1: Stop & Ask |
+| Making assumptions | Rule 2: State confidence + assumptions |
+| Complex solution tempting | Rule 3: Apply Ockham's Razor |
+| Generic advice | Rule 4: Ask about context first |
+| User asks to edit code | Remind: Q&A mode, offer to switch |
+
+---
+
+## Example: Full Response
+
+**User:** "How should I implement caching for my API?"
+
+**Response:**
+```
+🔍 Understanding the question:
+- Core problem: API performance via caching
+- Scope: Medium (depends on what to cache)
+- Type: Architecture/How-to
+
+❓ Missing context:
+- What data are you caching? (static vs dynamic)
+- Current traffic? (10 req/s vs 10k req/s)
+- Single server or multiple instances?
+
+→ These affect the answer significantly. Can you clarify?
+
+⚖️ Simplicity Check:
+- Complexity necessary? UNKNOWN until context clear
+- Simplest solution: In-memory cache (Map/LRU) if single instance
+
+🎯 Confidence: LOW (40%)
+- Too many unknowns to give specific advice
+- Would be HIGH with traffic numbers and architecture info
+
+---
+
+📌 TL;DR: Caching strategy depends heavily on your scale and setup. Before building complex systems, let's understand your actual needs.
+
+💡 Simplest approach (default):
+1. Start with HTTP caching headers (Cache-Control)
+2. Add in-memory cache if needed (node-cache, lru-cache)
+3. Only add Redis when you have multiple instances
+
+📋 Context considerations:
+- If single server + <1k req/s: In-memory is enough
+- If multiple servers: Need shared cache (Redis)
+- If data rarely changes: Aggressive HTTP caching
+```

package/.claude/skills/frontend-design-fundamentals/SKILL.md

@@ -4,18 +4,16 @@ description: |
   Core design principles for implementing beautiful, professional UIs.
   Ensures consistent quality through spacing, typography, colors, and visual hierarchy.
 
-  ALWAYS load when implementing UI/frontend code:
-  - Creating or modifying components, pages, screens
-  - Building landing pages, dashboards, forms, cards, buttons
-  - Any frontend work: HTML, CSS, styling, layouts
-  - Adding new UI elements or updating existing ones
+  ALWAYS load when implementing UI/frontend VISUAL DESIGN:
+  - Styling components: colors, spacing, typography, shadows
+  - Building layouts: CSS, flexbox, grid, positioning
+  - Creating visual elements: cards, buttons, forms, dashboards
+  - Animation, transition, hover effects, motion
   - Modern, stunning, elegant, sleek interfaces
-  - Animation, transition, hover effects, motion, interactive elements
 
-  Keywords: UI, frontend, component, page, styling, CSS, layout, button, form,
-            card, dashboard, animation, transition, hover, effect, motion,
-            modern, beautiful, stunning, elegant, sleek, professional,
-            interactive, visual, aesthetic, design, attractive, impressive
+  Keywords: styling, CSS, layout, colors, spacing, typography, shadows,
+            animation, transition, hover, visual, aesthetic, design,
+            beautiful, stunning, elegant, sleek, professional
 
   Purpose: Ensure ALL UI implementation follows design best practices for:
   - Consistent spacing scale (not arbitrary values)
@@ -28,8 +26,11 @@ description: |
   - Backend-only code (APIs, database, server logic)
   - Pure logic/algorithm work without UI
   - DevOps, infrastructure, CLI tools
+  - React/Next.js performance optimization (use react-best-practices)
+  - Data fetching, async patterns, bundle optimization (use react-best-practices)
 
   Works with other skills:
+  - react-best-practices: For React performance (NOT styling)
   - theme-factory: When user needs help CHOOSING colors/theme
   - figma-design-extraction: When Figma file provided
   - design-responsive: For mobile/tablet/responsive specifics