ai-workflow-init 6.6.0 → 7.0.0

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/commands/create-plan.md

@@ -15,47 +15,6 @@ Generate a single planning doc at `docs/ai/planning/feature-{name}.md` using the
 
 ---
 
-## Step 0: Check Beads Context (Optional Integration)
-
-> **Purpose**: Detect if this plan is for a Beads task. If so, link to epic and inherit context.
-
-**Read:** `.beads/current-task.json`
-
-**If file exists (Beads workflow active):**
-
-```json
-{
-  "task_id": "bd-auth.1",
-  "task_title": "Setup JWT infrastructure",
-  "epic_id": "bd-auth",
-  "epic_title": "User Authentication System",
-  "epic_plan": "docs/ai/planning/epic-auth-system.md"
-}
-```
-
-Set internal flags:
-- `BEADS_MODE = true`
-- `beads_task = task_id`
-- `beads_epic = epic_id`
-- `suggested_title = task_title`
-- `epic_plan_path = epic_plan`
-
-**If epic_plan exists:**
-- Read epic plan for architecture context
-- Extract relevant sections:
-  - Architecture overview (for codebase context)
-  - Key decisions (for constraints)
-  - Data flow (for understanding)
-- Use as additional context in Step 3 (Explore)
-
-**If file does not exist:**
-- `BEADS_MODE = false`
-- Proceed with normal workflow (no Beads integration)
-
-**Output:** Internal state set. No user-visible output for this step.
-
----
-
 ## Step 1: Analyze User Prompt
 
 **Parse user request to identify:**
@@ -339,38 +298,19 @@ Create the file automatically:
 
 - `docs/ai/planning/feature-{name}.md` - Use complete structure from `feature-template.md`
 
-**If BEADS_MODE = true:**
-- Add frontmatter with Beads metadata:
-  ```yaml
-  ---
-  beads_task: {task_id}
-  beads_epic: {epic_id}
-  epic_plan: {epic_plan_path}
-  ---
-  ```
-- Update Beads task with plan doc reference:
-  ```bash
-  bd update {task_id} --notes "plan: docs/ai/planning/feature-{name}.md"
-  ```
-
 **Notify user:** "Created plan with X phases: [Phase 1], [Phase 2], ..."
 
 ## Step 8: Next Actions
 
-**If BEADS_MODE = true:**
+**Suggest next command:**
+
 ```
 ✓ Created plan: docs/ai/planning/feature-{name}.md
-✓ Linked to Beads task: {task_id}
 
 Next steps:
-  /execute-plan    → Implement this task
-  /beads-status    → View epic progress
+  /execute-plan    → Implement this feature
 ```
 
-**If normal mode:**
-
-Suggest: `/execute-plan` to begin implementation.
-
 Implementation will be driven from `docs/ai/planning/feature-{name}.md`.
 
 Note: Test documentation will be created separately using the `writing-test` command.

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

@@ -40,36 +40,6 @@ Expected speedup: 30-40% for context loading phase.
 
 ---
 
-## Step 0: Check Beads Context (Optional Integration)
-
-> **Purpose**: Detect if this plan is for a Beads task. If so, track for final suggestions.
-
-**Read:** `.beads/current-task.json`
-
-**If file exists (Beads workflow active):**
-
-```json
-{
-  "task_id": "bd-auth.1",
-  "task_title": "Setup JWT infrastructure",
-  "epic_id": "bd-auth",
-  "epic_title": "User Authentication System"
-}
-```
-
-Set internal flags:
-- `BEADS_MODE = true`
-- `beads_task_id = task_id`
-- `beads_task_title = task_title`
-
-**If file does not exist:**
-- `BEADS_MODE = false`
-- Proceed with normal workflow (no Beads integration)
-
-**Output:** Internal state set. No user-visible output for this step.
-
----
-
 ## Step 1: Gather Context
 
 **Tools:**
@@ -254,31 +224,20 @@ Only run after ALL phases are marked complete. If incomplete phases remain, skip
 
 ## Step 6: Next Actions
 
-**If BEADS_MODE = true AND all phases complete:**
+**If all phases complete:**
 
 ```
-✓ All phases complete for Beads task: {beads_task_id} "{beads_task_title}"
+✓ All phases complete!
 
 Next steps:
-  /beads-done           → Close task, sync to git, see next ready tasks
-  /beads-status         → View epic progress
-
-Optional quality checks:
   /code-review          → Verify against standards
   /writing-test         → Add test coverage
   /check-implementation → Validate alignment with plan
 ```
 
-**If BEADS_MODE = false AND all phases complete:**
-
-- Suggest running `code-review` to verify against standards
-- Suggest running `writing-test` if edge cases need coverage
-- Suggest running `check-implementation` to validate alignment with planning entries
-
-**If phases remain (both modes):**
+**If phases remain:**
 
 - User runs `/execute-plan` again; Phase detection (Step 1d) will resume correctly
-- **If BEADS_MODE = true:** Remind user task is still in_progress in Beads
 
 ## Notes