ai-workflow-init 6.0.0 → 6.2.1

package/.claude/CLAUDE.md

@@ -0,0 +1,88 @@
+# AI Agent Workflow Standards
+
+## Core Coding Philosophy
+
+### 1. Simplicity First (with Strategic Exceptions)
+- **Default: Keep it simple**
+  - Choose simplest solution that meets requirements
+  - Avoid over-engineering and unnecessary abstractions
+  - Don't build for hypothetical futures
+
+- **Think ahead ONLY for:**
+  - **Security**: Input validation, authentication, authorization
+  - **Performance**: Scalability bottlenecks, query optimization
+  - All other cases → Choose simplicity
+
+- **Examples:**
+  - ✅ Use array methods instead of custom loops
+  - ✅ Add input validation for user data (security)
+  - ✅ Consider pagination for large datasets (performance)
+  - ❌ Don't create abstractions for one-time operations
+
+### 2. Deep Understanding
+- If unclear about requirements, edge cases, or expected behavior → **Ask first**
+- Never assume or guess - clarification prevents wasted effort
+- Key questions:
+  - "What should happen when X occurs?"
+  - "Is this the expected flow: A → B → C?"
+
+### 3. Multiple Options When Appropriate
+- Present 2-3 solution options with clear trade-offs
+- Format: "Option 1: [approach] - Pros: [...] Cons: [...]"
+- Let user choose based on their priorities
+
+---
+
+## Workflow Guidelines
+
+**Tooling:**
+- Prefer semantic search; grep for exact matches only
+- Run independent operations in parallel
+
+**Communication:**
+- Use Markdown minimally; backticks for `files/functions/classes`
+- Mirror user's language; code/comments in English
+- Status updates before/after key actions
+
+**Code Presentation:**
+- Existing code: `startLine:endLine:filepath`
+- New code: fenced blocks with language tag
+
+**TODO Management:**
+- Create todos for medium/large tasks (≤14 words, verb-led)
+- Keep ONE `in_progress` item only
+- Update immediately; mark completed when done
+
+---
+
+## Skill Reporting (MANDATORY)
+
+**CRITICAL REQUIREMENT - ALWAYS follow this:**
+
+At the START of EVERY response, BEFORE any other content, report skills:
+
+```
+📚 Skills: skill-name-1, skill-name-2
+```
+
+**Rules:**
+- If skills were activated → List them
+- If NO skills activated → Write: `📚 Skills: none`
+- This line MUST appear in EVERY response, no exceptions
+- Place BEFORE greeting, explanation, or any other content
+
+**Example responses:**
+
+```
+📚 Skills: design-fundamentals, theme-factory
+
+I'll help you create a modern login page...
+```
+
+```
+📚 Skills: none
+
+Sure, I can help you fix that bug...
+```
+
+Skills are defined in `.claude/skills/`.

package/.claude/agents/review-plan.md

@@ -0,0 +1,168 @@
+---
+name: review-plan
+description: Senior Technical Architect reviews planning docs for clarity, completeness, logic, and AI-executability before implementation.
+tools: Read, Glob, Grep
+model: inherit
+---
+
+You are a **Senior Technical Architect and QA Lead** reviewing feature plans before implementation.
+
+Your role is NOT to check formatting - it's to ensure the plan is **clear, complete, logical, and executable** by an AI agent.
+
+## Context
+
+- Plans are created by `/create-plan` and executed by `/execute-plan`
+- The executing AI agent will read the plan and implement code based on it
+- Poor plans lead to wrong implementations, wasted effort, and bugs
+
+## When Invoked
+
+1. Read the provided planning doc carefully
+2. Read project context:
+   - `docs/ai/project/CODE_CONVENTIONS.md` - coding standards
+   - `docs/ai/project/PROJECT_STRUCTURE.md` - architecture patterns
+3. Evaluate against 5 critical criteria
+4. Output actionable review with clear verdict
+
+## 5 Critical Evaluation Criteria
+
+### 1. Clarity - Is the plan clear enough to implement?
+
+**Ask yourself:**
+- Can I understand exactly what needs to be built?
+- Are there ambiguous terms or vague descriptions?
+- Would two different developers interpret this the same way?
+- Are edge cases explicitly defined or left to assumption?
+
+**Red flags:**
+- "Handle errors appropriately" (what does appropriately mean?)
+- "Similar to existing feature" (which feature? how similar?)
+- "Should support various formats" (which formats exactly?)
+- Missing details on user flows, states, or interactions
+
+### 2. Completeness - Does the plan cover the full requirement?
+
+**Ask yourself:**
+- Are all user scenarios covered?
+- Are error states and edge cases addressed?
+- Is the happy path AND unhappy paths defined?
+- Are there missing pieces that will block implementation?
+
+**Red flags:**
+- Only happy path described
+- No mention of error handling
+- Missing validation rules
+- Unclear what happens in edge cases
+- Dependencies not identified
+
+### 3. Project Context Alignment - Does it follow project patterns?
+
+**Compare against:**
+- `CODE_CONVENTIONS.md` - naming, structure, patterns
+- `PROJECT_STRUCTURE.md` - where files should go, architecture
+
+**Ask yourself:**
+- Does the plan use existing patterns/components?
+- Are file paths consistent with project structure?
+- Does it follow established conventions?
+- Is it reinventing something that already exists?
+
+**Red flags:**
+- Creating new patterns when existing ones apply
+- File paths that don't match project structure
+- Ignoring existing utilities/components
+- Inconsistent naming with codebase
+
+### 4. Logic Soundness - Is the technical approach correct?
+
+**Ask yourself:**
+- Does the data flow make sense?
+- Are there circular dependencies?
+- Is the sequence of operations correct?
+- Are there race conditions or timing issues?
+- Does the architecture scale appropriately?
+
+**Red flags:**
+- Steps that depend on something not yet created
+- Missing state management considerations
+- API calls without error handling strategy
+- Database operations without transaction considerations
+- Security gaps (auth, validation, sanitization)
+
+### 5. AI Executability - Can an AI agent implement this correctly?
+
+**Ask yourself:**
+- Are instructions specific enough for AI to follow?
+- Is there room for misinterpretation?
+- Are pseudo-code blocks clear on logic flow?
+- Would AI know EXACTLY what code to write?
+
+**Red flags:**
+- "Implement similar to X" without specifying what aspects
+- Pseudo-code that's too abstract or hand-wavy
+- Missing input/output specifications
+- Unclear success criteria for each task
+- Tasks that require human judgment calls
+
+## Output Format
+
+```markdown
+## Plan Review: {feature-name}
+
+### Verdict
+**Status**: ✅ Ready to Execute | ⚠️ Needs Clarification | ❌ Not Ready
+
+**Confidence**: High / Medium / Low
+(How confident that AI agent will implement correctly)
+
+---
+
+### 1. Clarity Assessment
+**Score**: ✅ Clear | ⚠️ Some Ambiguity | ❌ Too Vague
+
+[Specific findings - what's clear, what's not]
+
+### 2. Completeness Assessment
+**Score**: ✅ Complete | ⚠️ Gaps Found | ❌ Major Missing Pieces
+
+[What's covered, what's missing]
+
+### 3. Project Context Alignment
+**Score**: ✅ Aligned | ⚠️ Minor Deviations | ❌ Misaligned
+
+[How well it follows conventions and structure]
+
+### 4. Logic Soundness
+**Score**: ✅ Sound | ⚠️ Minor Issues | ❌ Flawed Logic
+
+[Technical concerns, if any]
+
+### 5. AI Executability
+**Score**: ✅ Executable | ⚠️ Risky Areas | ❌ Likely Misimplementation
+
+[Areas where AI might go wrong]
+
+---
+
+### Critical Issues (Must Fix)
+1. [Issue] → [Suggested fix]
+
+### Warnings (Should Fix)
+1. [Issue] → [Suggested fix]
+
+### Suggestions (Nice to Have)
+1. [Improvement idea]
+
+---
+
+### Recommendation
+[Clear next action: proceed / revise specific sections / major rework needed]
+```
+
+## Review Mindset
+
+- Think like you're preventing bugs BEFORE they're written
+- Assume the AI agent is literal - it will do exactly what's written
+- Ambiguity = AI will guess = likely wrong implementation
+- Your review saves hours of debugging and rework
+- Be specific and actionable - vague feedback is useless

package/.claude/commands/check-implementation.md

@@ -0,0 +1,161 @@
+---
+name: check-implementation
+description: Validates implementation against planning doc.
+---
+
+Compare current implementation against planning doc to ensure all requirements are met and completed tasks have corresponding code.
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- For medium/large validations, create todos (≤14 words, verb-led). Keep only one `in_progress` item.
+- Update todos immediately after progress; mark completed upon finish.
+- Provide a high-signal summary at completion highlighting key mismatches and next steps.
+
+---
+
+## Step 1: Load Planning Doc
+
+**Tools:**
+- AskUserQuestion(questions=[...]) if feature name not provided
+- Read(file_path="docs/ai/planning/feature-{name}.md")
+
+**Purpose:** Load planning doc to extract:
+- Acceptance criteria (Given-When-Then scenarios)
+- Implementation plan tasks (with `[ ]` or `[x]` status)
+- Expected file changes mentioned in tasks
+
+**Error handling:**
+- Planning doc not found: Cannot proceed, notify user and exit
+- Invalid format: Parse available content, warn about missing sections
+- No completed tasks: Nothing to validate, notify user
+
+---
+
+## Step 2: Discover Implementation Files
+
+**Strategy (in order):**
+1. Extract file paths from planning doc task list
+2. If no file paths found: Read implementation doc `docs/ai/implementation/feature-{name}.md`
+3. If no implementation doc: Use git diff to find changed files
+4. If no git changes: Ask user for file paths
+
+**Tools:**
+- Read(file_path="docs/ai/planning/feature-{name}.md") - extract file mentions
+- Read(file_path="docs/ai/implementation/feature-{name}.md") - fallback
+- Bash(command="git diff --name-only main") - find changed files
+- Glob(pattern="src/**/*.{js,ts,py}") - last resort full scan
+- AskUserQuestion - ask user if all else fails
+
+**Output:** List of files to validate against planning doc
+
+**Error handling:**
+- No files found: Cannot validate, notify user
+- File paths invalid: Skip broken paths, continue with valid ones
+- Git not available: Fall back to asking user
+
+---
+
+## Step 3: Validate Implementation vs Planning
+
+**Tool:** Task(
+  subagent_type='Explore',
+  thoroughness='medium',
+  prompt="Compare implementation in discovered files against planning doc at docs/ai/planning/feature-{name}.md:
+
+    For each completed task marked [x]:
+    - Check if corresponding code exists in mentioned files
+    - Verify implementation matches task description
+
+    For each acceptance criteria:
+    - Verify code satisfies the Given-When-Then scenario
+    - Check expected behavior is implemented
+
+    Identify:
+    - Completed tasks [x] with missing/partial implementation
+    - Mismatches between planning description and actual code
+    - Acceptance criteria not met by code
+
+    Return structured report with findings categorized by severity."
+)
+
+**Fallback:** If Explore agent unavailable, manually:
+1. Read each file from Step 2
+2. For each completed task `[x]`, search for related code
+3. Compare against acceptance criteria
+4. Document mismatches
+
+**Validation scope (no inference):**
+- Verify code follows the acceptance criteria from planning doc
+- Verify code matches the implementation plan task descriptions
+- Check completed tasks `[x]` have corresponding code changes
+- **Do NOT** invent or infer alternative logic beyond what docs specify
+
+**Error handling:**
+- Agent timeout: Retry with thoroughness='quick', then fall back to manual
+- No completed tasks: Report "Nothing to validate"
+- Ambiguous results: Flag for manual review
+
+---
+
+## Step 4: Generate Validation Report
+
+**Report structure:**
+
+### Summary
+- Total tasks in planning: `X`
+- Completed tasks `[x]`: `Y`
+- Validated successfully: `Z`
+- Mismatches found: `N` (critical: `C`, minor: `M`)
+- Missing implementations: `P`
+
+### Completed Tasks Without Implementation
+
+For each task marked `[x]` but code not found:
+
+```
+- [ ] Task: [Task description from planning]
+  - Expected file: [file mentioned in task or "not specified"]
+  - Status: Missing or Partial
+  - Action: Implement missing code or update task to [ ]
+```
+
+### Mismatches (Code ≠ Planning)
+
+For each discrepancy between planning and code:
+
+```
+- File: path/to/file.ext
+  - Planning requirement: [what planning doc says]
+  - Current implementation: [what code actually does]
+  - Severity: Critical / Minor
+  - Action: Update code to match planning OR revise planning doc
+```
+
+### Acceptance Criteria Status
+
+For each acceptance criteria:
+
+```
+- [x] AC1: [Description] → ✅ Verified (code satisfies criteria)
+- [ ] AC2: [Description] → ❌ Not implemented
+- [x] AC3: [Description] → ⚠️ Partial (missing edge cases)
+```
+
+### Next Steps (Prioritized)
+
+1. **Critical issues** (blocking):
+   - [ ] Fix mismatch in [file]: [specific issue]
+   - [ ] Implement missing task: [task name]
+
+2. **Minor issues** (non-blocking):
+   - [ ] Address partial implementation in [file]
+   - [ ] Update planning doc to reflect changes
+
+3. **Follow-up**:
+   - [ ] Re-run `/check-implementation` after fixes
+   - [ ] Run `/code-review` for standards compliance
+
+---
+
+**Note:** This validation checks implementation completeness, not code quality. Run `/code-review` separately for standards compliance.

package/.claude/commands/clarify-requirements.md

@@ -0,0 +1,287 @@
+---
+name: clarify-requirements
+description: Clarify and document requirements through iterative Q&A sessions. (project)
+---
+
+## Goal
+
+Facilitate requirement gathering through structured Q&A sessions. Output a comprehensive requirement document at `docs/ai/requirements/req-{name}.md` that can be used as input for `/create-plan`.
+
+## When to Use
+
+- Complex features requiring multiple clarification rounds
+- Business logic is unclear or needs detailed specification
+- Design decisions need to be documented before planning
+- Stakeholder input needs to be captured and organized
+
+## Workflow Alignment
+
+- Provide brief status updates (1–3 sentences) before/after important actions.
+- 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: Analyze Initial Request
+
+**Parse user request to identify:**
+- **Feature scope**: What is the user trying to build?
+- **Feature type**: Backend-only, Frontend-only, Full-stack, Data/API, etc.
+- **Clarity level**: What's clear vs. ambiguous?
+- **Missing information**: What needs clarification?
+- **Complexity indicators**: Simple (skip this skill) vs. complex (proceed)
+- **Domain complexity**: Detect specialized terminology (finance, medical, legal, etc.)
+- **Existing requirement**: Check if user references existing `req-{name}.md` file
+
+**If feature is simple** (can be fully specified in 1-2 Q&A rounds):
+- Suggest: "This feature seems straightforward. Consider using `/create-plan` directly."
+- Proceed only if user confirms they want detailed requirement doc.
+
+**If existing requirement doc detected:**
+- Read the existing file: `Read(file_path="docs/ai/requirements/req-{name}.md")`
+- Ask user: "Found existing requirement doc. What would you like to do?"
+  - Options:
+    - "Update existing" → Load content, identify gaps, continue Q&A from where it left off
+    - "Start fresh" → Backup existing to archive, create new
+    - "Review only" → Display current content, ask for specific sections to update
+
+**Output:**
+- List of areas needing clarification
+- Recommended rounds to skip (based on feature type)
+- Flag if Glossary section is needed (domain-specific terms detected)
+- Mode: "new" | "update" | "review"
+
+---
+
+## Step 2: Structured Q&A Session
+
+**Purpose:** Gather requirements through focused questions. This step may repeat multiple times.
+
+**Tool:** AskUserQuestion(questions=[...])
+
+### Smart Round Selection
+
+Before each round, evaluate relevance based on:
+- **Feature type** from Step 1
+- **Previous answers** collected
+
+**Skip Round Logic:**
+| Feature Type | Skip Rounds |
+|--------------|-------------|
+| Backend-only / API | Round 2 (User Flows) if no UI |
+| Data processing | Round 4 (Edge Cases) → ask minimal |
+| Simple CRUD | Round 3 (Business Rules) if straightforward |
+| UI-only | Round 5 (Performance/Security) → ask minimal |
+
+**Before skipping, confirm with user:**
+> "Based on your answers, Round {N} ({topic}) seems less relevant for this feature. Should we skip it or cover briefly?"
+
+Options: "Skip entirely", "Cover briefly (1-2 questions)", "Cover in full"
+
+---
+
+### Question Categories (ask in priority order, 2-4 questions per round):
+
+### Round 1: Problem & Users (Required)
+1. **Problem Statement**: What specific problem does this solve?
+2. **Target Users**: Who are the primary users? What are their goals?
+3. **Success Metrics**: How will we know this feature is successful?
+
+### Round 2: Functional Requirements (Required)
+4. **Core Functionality**: What are the must-have features?
+5. **User Flows**: What are the main user journeys? *(Skip if backend-only)*
+6. **Inputs/Outputs**: What data goes in? What comes out?
+
+### Round 3: Business Rules & Logic (Conditional)
+7. **Business Rules**: What rules govern the behavior?
+8. **Calculations/Logic**: Any specific formulas or logic?
+9. **Validations**: What validations are needed?
+
+### Round 4: Edge Cases & Constraints (Conditional)
+10. **Edge Cases**: What happens in unusual situations?
+11. **Error Handling**: How should errors be handled?
+12. **Constraints**: Technical, business, or time limitations?
+
+### Round 5: Non-Functional & Scope (Conditional)
+13. **Performance**: Any performance requirements? *(Skip if UI-only)*
+14. **Security**: Authentication, authorization, data protection?
+15. **Out of Scope**: What is explicitly NOT included?
+
+---
+
+**Q&A Format:**
+- Use AskUserQuestion with 2-4 options per question
+- Include "I need to think about this" option for complex questions
+- Allow multi-select where appropriate
+
+**After each round:**
+- Summarize what was learned
+- Identify remaining gaps
+- Evaluate if next round is relevant
+- Ask if user wants to continue clarifying or finalize
+
+---
+
+## Step 3: Document Clarifications
+
+**After each Q&A round, update internal notes:**
+
+```
+## Clarifications Log
+| # | Question | Answer | Category |
+|---|----------|--------|----------|
+| 1 | {question} | {answer} | {FR/BR/NFR/Edge} |
+```
+
+**Categorize answers:**
+- **FR**: Functional Requirement
+- **BR**: Business Rule
+- **NFR**: Non-Functional Requirement
+- **Edge**: Edge Case
+- **OOS**: Out of Scope
+- **TERM**: Terminology/Glossary item
+
+**Track domain terms:**
+- If user uses specialized terms, add to Glossary section
+- Ask for definitions if terms are ambiguous
+
+---
+
+## Step 4: Generate Requirement Document
+
+**Trigger:** User indicates they're ready to finalize OR all key areas are covered.
+
+### Load Template
+
+**Tool:** Read(file_path="docs/ai/requirements/req-template.md")
+
+**Instructions:**
+1. Read the template file to understand the required structure and format
+2. Use the template as the baseline - follow its section order and formatting exactly
+3. Fill in sections with data collected from Q&A rounds
+4. For optional sections with no data collected → remove the section entirely (don't leave placeholders)
+5. Keep required sections even if minimal data (Problem Statement, Functional Requirements, Acceptance Criteria)
+
+**Template Section Mapping:**
+| Template Section | Data Source |
+|------------------|-------------|
+| 1. Problem Statement | Round 1: Problem & Users |
+| 2. User Stories | Round 1: Target Users + Round 2: Core Functionality |
+| 3. Business Rules | Round 3: Business Rules |
+| 4. Functional Requirements | Round 2: Core Functionality, Inputs/Outputs |
+| 5. Non-Functional Requirements | Round 5: Performance, Security |
+| 6. Edge Cases & Constraints | Round 4: Edge Cases, Constraints |
+| 7. Clarifications Log | All rounds: Q&A history |
+| 8. Out of Scope | Round 5: Out of Scope |
+| 9. Acceptance Criteria | Derived from Functional Requirements |
+| 10. References | User-provided links |
+| 11. Glossary | Domain terms collected (TERM category) |
+
+### File Naming & Versioning Strategy
+
+**Auto-name requirement:**
+- Derive `req-{name}` from feature description (kebab-case, concise)
+- Example: "User Authentication Flow" → `req-user-authentication`
+
+**If file already exists:**
+1. **Backup existing file** to archive folder:
+   ```
+   docs/ai/requirements/archive/req-{name}_{timestamp}.md
+   ```
+   - Timestamp format: `YYYYMMDD-HHMMSS`
+   - Example: `archive/req-user-authentication_20250115-143022.md`
+
+2. **Overwrite** the main file: `docs/ai/requirements/req-{name}.md`
+
+3. **Notify user:**
+   > "Previous version backed up to `archive/req-{name}_{timestamp}.md`"
+
+**Create archive folder if not exists:**
+```bash
+mkdir -p docs/ai/requirements/archive
+```
+
+---
+
+### Generate document sections:
+
+1. **Problem Statement**: From Round 1 answers
+2. **User Stories**: Derived from users + functionality
+3. **Business Rules**: From Round 3
+4. **Functional Requirements**: From Rounds 2-3, prioritized
+5. **Non-Functional Requirements**: From Round 5
+6. **Edge Cases & Constraints**: From Round 4
+7. **Clarifications Log**: Complete Q&A history
+8. **Out of Scope**: Explicit exclusions
+9. **Acceptance Criteria**: Derived from requirements (Given/When/Then)
+10. **References**: Links to related docs
+11. **Glossary**: Domain-specific terms *(only if terms were collected)*
+
+**Write file:**
+- Path: `docs/ai/requirements/req-{name}.md`
+
+---
+
+## Step 5: Review & Confirm
+
+**Present summary to user:**
+
+```
+## Requirement Document Created
+
+**File:** docs/ai/requirements/req-{name}.md
+{If backup created: **Previous version:** archive/req-{name}_{timestamp}.md}
+
+### Summary
+- {X} Functional Requirements
+- {Y} Business Rules
+- {Z} Edge Cases documented
+- {N} Clarification rounds completed
+- {M} Rounds skipped (not relevant)
+{If glossary: - {T} Terms defined in Glossary}
+
+### Key Requirements
+1. [FR-01] {main requirement}
+2. [FR-02] {second requirement}
+3. [BR-01] {key business rule}
+
+### Next Steps
+1. Review the requirement document
+2. Run `/create-plan` to generate implementation plan
+```
+
+**Offer options:**
+- "Review document" → Read and display full content
+- "Continue clarifying" → Return to Step 2
+- "Proceed to planning" → Suggest `/create-plan docs/ai/requirements/req-{name}.md`
+
+---
+
+## Step 6: Next Actions
+
+Suggest next steps based on user choice:
+
+- **If more clarification needed:** Continue Q&A session
+- **If ready to plan:** `/create-plan` with requirement doc reference
+- **If needs stakeholder review:** Share the requirement doc for review
+
+---
+
+## Tips for Effective Requirement Gathering
+
+1. **Start broad, then narrow**: Begin with problem/users, then dive into specifics
+2. **Confirm understanding**: Summarize after each round
+3. **Document everything**: Even "obvious" decisions should be recorded
+4. **Identify assumptions**: Make implicit assumptions explicit
+5. **Define boundaries**: Clear out-of-scope prevents scope creep
+6. **Skip smartly**: Not every feature needs all rounds - adapt to context
+7. **Capture terminology**: Domain terms prevent miscommunication later
+
+---
+
+## Notes
+
+- This command is designed for iterative use - user can clear chat and resume with the requirement doc
+- The output requirement doc serves as single source of truth for `/create-plan`
+- Requirement doc can be updated later using `/modify-plan` workflow
+- Previous versions are preserved in `archive/` folder for reference