aiwf 0.1.0 → 0.3.1

package/claude-code/aiwf/en/.claude/commands/aiwf/aiwf_create_prd.md

@@ -0,0 +1,272 @@
+# Generate Product Documentation Workflow
+
+This rule guides AI to collect input through several key questions, then **sequentially** generate PRD → IA → UCD → UI/UX documents. All outputs use **Markdown** format.
+
+---
+
+## 1. Question Phase
+
+AI collects the following information from the user through **questions**:
+
+1. `<product-overview>`
+2. `<references>` (List of URLs)
+3. `<must-features>` (List of must-have features)
+4. `<target-user-persona>`
+5. `<target-platforms>`
+6. `<storage-type>`
+7. `<tech-stack>`
+
+> ⚠️ All questions are in English, and if needed, request additional reference service or competitive product information.
+
+---
+
+## 2. PRD Writing Phase
+
+After collecting all inputs from the user, create a PRD document based on the following **sample prompt** structure:
+
+```prompt
+Write a PRD document based on the following information:
+<product-overview>
+${productOverview}
+</product-overview>
+<references>
+${references}
+</references>
+<must-features>
+${mustFeatures}
+</must-features>
+<target-user-persona>
+${persona}
+</target-user-persona>
+<target-platforms>
+${platforms}
+</target-platforms>
+<storage-type>
+${storageType}
+</storage-type>
+<tech-stack>
+${techStack}
+</tech-stack>
+PRD must include the following contents:
+<table-of-contents>
+- Detailed product description
+- Reference Services with detailed rationale
+- Core features and specifications
+- Suggested additional features
+- User persona and scenarios
+- Technical stack recommendations
+</table-of-contents>
+<response-format>
+Use markdown format
+</response-format>
+<guidelines>
+- Use tables or lists where appropriate to organize information systematically.
+- Provide accurate answers with reliable references
+- Clearly separate each section
+- Collect additional reference services and provide detailed rationale
+- Do not include detailed data structure and storage design
+</guidelines>
+```
+
+Additional instructions to include in the document:
+
+- Use tables or lists where appropriate to organize information systematically.
+- Include at least 3 reference services, with detailed rationale for each.
+
+After completing the PRD, append a **English** question asking if the user wants to proceed to the IA phase, with a message "✅ PRD completed".
+
+---
+
+## 3. IA(Information Architecture) Writing Phase
+
+If the user chooses to continue, create an IA document based on the following information:
+
+The IA document should include:
+
+1. **Site Map** – Represented as a tree structure
+2. **Content Inventory** – List of key content for each page
+3. **User Flow** – Provide at least 2 core scenarios in text-based flowchart format
+4. **Navigation Structure and URL Patterns**
+
+Document format: Markdown, English
+
+### IA Sample Prompt
+
+```prompt
+Write an Information Architecture document based on PRD, and following information:
+<navigation-type>
+${navigationType}
+</navigation-type>
+<auth-type>
+${authType}
+</auth-type>
+IA document must include the following contents:
+<table-of-contents>
+- Site Map
+- User Flow
+- Navigation Structure
+- Page Hierarchy
+- Content Organization
+- Interaction Patterns
+- URL Structure
+- Component Hierarchy
+</table-of-contents>
+<response-format>
+Use markdown format
+</response-format>
+<guidelines>
+- Use tables or lists where appropriate to organize information systematically
+- Provide accurate answers with reliable references
+- Clearly separate each section
+- Consider user experience and accessibility
+- Include responsive design considerations
+- Consider SEO best practices
+</guidelines>
+```
+
+After completing the IA, append a **English** question asking if the user wants to proceed to the UCD phase, with a message "✅ IA completed".
+
+---
+
+## 4. UCD(User-Centered Design) Writing Phase
+
+The UCD document should include:
+
+1. **Main Persona** – 2-3 personas, summarized in a table (goals, motivations, pain points)
+2. **Scenarios** – At least 2 core scenarios per persona
+3. **Requirements Matrix** – Mapping of features to personas
+
+Document format: Markdown, English
+
+### UCD Sample Prompt
+
+```prompt
+Write a detailed use case document based on PRD, IA, and following information:
+Use case document must include the following contents:
+<table-of-contents>
+- Actor Definitions
+- Use Case Scenarios
+- Main Steps
+- Exception Handling
+- Comprehensive Actor Definitions
+- Detailed Use Case Scenarios
+- Main Steps and Flow of Events
+- Alternative Flows and Edge Cases
+- Preconditions and Postconditions
+- Business Rules and Constraints
+- Exception Handling Procedures
+- User Interface Considerations
+- Data Requirements and Data Flow
+- Security and Privacy Considerations
+</table-of-contents>
+<response-format>
+Use markdown format
+</response-format>
+<guidelines>
+- Use tables or lists where appropriate to organize information systematically
+- Provide accurate answers with reliable references
+- Clearly separate each section
+- Include detailed step-by-step descriptions
+- Consider error cases and alternative flows
+- Include technical considerations
+</guidelines>
+```
+
+After completing the UCD, append a **English** question asking if the user wants to proceed to the UI/UX phase, with a message "✅ UCD completed".
+
+---
+
+## 5. UI/UX Guide Writing Phase
+
+내용:
+
+1. **Wireframe Description** – Layout and components of each core screen (text description)
+2. **Navigation Principles** – Description of consistent UI patterns
+3. **Style Guide Draft** – Color palette, typography, component rules
+4. **Accessibility Considerations** – WCAG 2.1 compliance key points
+
+Document format: Markdown, English
+
+### UI/UX Sample Prompt
+
+```prompt
+<role>
+senior UI/UX designer.
+</role>
+<task>
+Write a comprehensive UI/UX design guide based on the following information:
+</task>
+<design-preferences>
+Theme details: Please analyze the reference service and suggest appropriate:
+- Design style
+- Color scheme
+- Primary colors
+</design-preferences>
+<references>
+${references}
+</references>
+<additional-instructions>
+Please analyze the reference service's design system and suggest appropriate:
+- Overall design style and patterns
+- Color scheme and palette
+- Primary colors
+- Mood and atmosphere
+</additional-instructions>
+Design guide must include the following contents:
+<table-of-contents>
+- Design System Overview
+- Color Palette for tailwindcss (primary, secondary, accent, neutral, etc.)
+- Page Implementations
+  detailed design guide for each pages
+  - core purpose of the page
+  - key components
+  - layout structure
+- Layout Components
+  - applicable routes
+  - core components
+  - responsive behavior
+- Interaction Patterns
+- Breakpoints
+</table-of-contents>
+<breakpoints>
+$breakpoints: (
+├── 'mobile': 320px,
+├── 'tablet': 768px,
+├── 'desktop': 1024px,
+└── 'wide': 1440px
+);
+</breakpoints>
+<response-format>
+Use markdown format
+</response-format>
+<guidelines>
+- Use tables or lists where appropriate to organize information systematically
+- Considering color scheme, select proper color for each color in tailwindcss palette
+- Provide specific color codes
+- Provide rationale for design decisions
+- Always include responsive design considerations
+- Include all text content in UI
+- If needed, use enough images in each components
+- provide each image's url. Use stock photos from picsum.photos where appropriate, only valid URLs you know exist
+- must handle root route
+- consider proper grid system for all components
+</guidelines>
+```
+
+After completing all documents, inform the user with a message "🎉 All documents created" and guide them to the next step (sprint/task decomposition).
+
+---
+
+## 6. Sprint/Task Decomposition Preparation
+
+After all documents are completed, inform the user that AI can automatically create development sprints and tasks using the `yolo` or `create_sprints_from_milestone` commands.
+
+---
+
+### Example Usage
+
+1. AI → Question Phase
+2. User → Provide Information
+3. AI → PRD Creation, IA Progress Question
+4. User → "Continue"
+5. AI → IA Creation, UCD Progress Question … Repeat

package/claude-code/aiwf/en/.claude/commands/aiwf/aiwf_create_sprint_tasks.md

@@ -0,0 +1,189 @@
+# Create Sprint Tasks - Top-Down Execution
+
+Create detailed tasks for an existing sprint with integrated implementation guidance.
+
+## Create a TODO with EXACTLY these 8 Items
+
+1. Identify target sprint and verify it exists
+2. Load sprint context and related documentation
+3. Check for existing ADRs and technical guidance
+4. Analyze sprint deliverables for task breakdown
+5. Create individual task files with implementation guidance
+6. Link ADRs to relevant tasks
+7. Update sprint meta with task references
+8. Check quality of your work
+
+Follow step by step and adhere closely to the following instructions for each step.
+
+## DETAILS on every TODO item
+
+### 1. Identify target sprint and verify it exists
+
+Check: <$ARGUMENTS>
+
+**REQUIRED:** Sprint ID must be provided (e.g., S02). If empty, ask user to specify which sprint to detail.
+
+- VERIFY sprint directory exists in `.aiwf/03_SPRINTS/`
+- CHECK sprint meta file exists (e.g., `S02_sprint_meta.md`)
+- VERIFY sprint status is not already "completed"
+- If tasks already exist, ask user if they want to recreate them or any other guidance
+
+### 2. Load sprint context and related documentation
+
+Use PARALLEL SUBAGENTS to READ and UNDERSTAND the project's context:
+
+- READ `.aiwf/00_PROJECT_MANIFEST.md` for project context
+- READ sprint meta file completely to understand goals and deliverables
+- READ parent milestone requirements from `.aiwf/02_REQUIREMENTS/`
+- READ `.aiwf/01_PROJECT_DOCS/ARCHITECTURE.md` for technical context
+- READ `.aiwf/01_PROJECT_DOCS/LONG_TERM_VISION.md` to understand architectural decisions
+
+**IMPORTANT:** Sprint tasks must align with documented sprint goals, not expand scope.
+
+### 3. Check for existing ADRs and technical guidance
+
+**USE PARALLEL SUBAGENTS** to execute these commands:
+
+- SEARCH `.aiwf/05_ARCHITECTURE_DECISIONS/` for ADRs matching sprint ID (e.g., `ADR*_S02_*.md`)
+- READ all found ADRs to understand technical decisions
+- CHECK sprint meta for ADR references section
+- NOTE which technical decisions will affect task implementation
+- BUILD RELATIONSHIP in task and subtasks and make clear what to implement
+
+**If conflict in Scope** Between ADR and Sprint goal, try to think about it and ask the user to resolve the conflict.
+
+**If no ADRs found:** Proceed but note that tasks may need clarification during implementation.
+
+### 4. Analyze sprint deliverables for task breakdown
+
+Based on sprint goals and deliverables (execute in Parallel Subagents):
+
+- BREAK DOWN high-level deliverables into concrete, implementable tasks
+- ENSURE each task represents a coherent feature or component
+- CONSIDER logical dependencies between tasks
+- MAP tasks to relevant ADRs for technical guidance
+- DEFER complexity assessment until after tasks are fully created with subtasks
+
+### 5. Create individual task files with implementation guidance
+
+**NOW** For each identified Task spin up a Parallel Subagent with these Instructions:
+
+    #### Create a TODO for EACH task
+
+    1. Create basic task structure
+    2. Research codebase interfaces
+    3. Add technical guidance
+    4. Validate task completeness
+
+    ### 1. Create basic task structure
+
+    - ALL TASK FILES must to be created in the Sprint Directory (where the sprint meta file is)
+    - CREATE file with naming: `T<NN>_S<NN>_<Descriptive_Name>.md`
+    - USE sequential numbering starting from T01
+    - FOLLOW task template structure exactly from `.aiwf/99_TEMPLATES/task_template.md`
+    - ADD basic description and objectives from sprint goals
+
+    ### 2. Research codebase interfaces
+
+    - EXAMINE existing codebase for similar patterns and interfaces
+    - IDENTIFY specific classes, functions, and imports that will be needed
+    - FIND integration points with existing modules
+    - NOTE database models, API endpoints, or services to interface with
+    - CHECK existing error handling and logging patterns
+
+    ### 3. Add technical guidance
+
+    Add these sections to the task file (add to template if not present):
+
+    **Technical Guidance section:**
+
+    - Key interfaces and integration points in the codebase
+    - Specific imports and module references
+    - Existing patterns to follow
+    - Database models or API contracts to work with
+    - Error handling approach used in similar code
+
+    **Implementation Notes section:**
+
+    - Step-by-step implementation approach
+    - Key architectural decisions to respect
+    - Testing approach based on existing test patterns
+    - Performance considerations if relevant
+
+    **IMPORTANT:** Do NOT include code examples. Provide structural guidance and references only.
+
+    #### 4. Validate task completeness
+
+    - ENSURE task has clear implementation path
+    - VERIFY all integration points are documented
+    - CHECK that guidance references actual codebase elements
+    - CONFIRM task is self-contained and actionable
+
+    **REPEAT** `### 5. Create individual task files with implementation guidance` for every Task
+
+### 6. Link ADRs to relevant tasks
+
+- IF relevant ADRs exist
+- REFERENCE ADRs that are related
+- ADD explanation in Technical Guidance section for how each ADR applies
+- ENSURE tasks ONLY reference ADRs that affect their implementation
+
+### 7. Update sprint meta with task references
+
+- EDIT sprint meta file to add/update task list
+- ORGANIZE tasks by logical grouping or dependency order
+- ADD brief description for each task
+
+### 8. Check quality of your work
+
+Review all created tasks for complexity and split any High complexity tasks:
+
+**Complexity Assessment Process:**
+
+- READ each task file completely including description, goals, acceptance criteria, and subtasks
+- ASSESS complexity using your judgment about the overall scope and challenge
+- DO NOT base complexity on simple metrics like file counts or estimated hours
+- CONSIDER the conceptual difficulty, integration challenges, and unknowns
+- MARK complexity as Low, Medium, or High in the task frontmatter
+
+**If ANY task is marked as High complexity:**
+
+- SPLIT the task into 2-3 smaller tasks of Low or Medium complexity
+- CREATE new task files with proper sequential numbering
+- UPDATE the original high-complexity task file or DELETE it
+- ENSURE the split tasks together achieve the original goal
+- MAINTAIN logical grouping and dependencies
+
+**After all tasks are finalized:**
+
+- VERIFY all tasks are Low or Medium complexity only
+- CHECK task numbering is sequential (T01, T02, T03...)
+- UPDATE sprint meta file with final task list
+- UPDATE project manifest sprint section to reflect actual tasks created
+- GENERATE completion report
+
+**Output format:**
+
+    ```Markdown
+    ## Sprint Detailed - [YYYY-MM-DD HH:MM]
+
+    **Sprint:** [Sprint ID] - [Sprint Name]
+    **Status:** Planning Complete
+
+    **Tasks Created:** [final count after any splits]
+    - Medium Complexity: [count]
+    - Low Complexity: [count]
+
+    **Task Splitting Summary:**
+    - [Original T03 split into T03 and T04 due to scope]
+    - [No other splits needed]
+
+    **Final Task List:**
+    1. T01_S02 - [Title] (Complexity: [Level])
+    2. T02_S02 - [Title] (Complexity: [Level])
+    [Continue for all tasks]
+
+    **Next Steps:**
+    - Review tasks for completeness
+    - Run `/do_task [FIRST_TASK_IN_SPRINT]` to begin implementation
+    ```

package/claude-code/aiwf/en/.claude/commands/aiwf/aiwf_create_sprints_from_milestone.md

@@ -0,0 +1,121 @@
+# Create Sprints from Milestone - Top-Down Execution
+
+Follow these instructions to sprint the scope of a Milestone into Sprints
+
+## Create a TODO with EXACTLY these 8 items
+
+1. Analyze current milestone state
+2. Assess completed work vs milestone requirements
+3. Identify remaining work and dependencies
+4. Design logical sprint boundaries
+5. Create sprint directories and meta files
+6. Update PROJECT_MANIFEST with sprint roadmap
+7. Validate sprint coherence and dependencies
+8. Report milestone plan
+
+---
+
+## 1 · Analyze current milestone state
+
+**CRITICAL:** You are given additional Arguments: <$ARGUMENTS>
+
+**USE PARALLEL SUBAGENTS** to do these tasks:
+
+- Parse arguments for milestone ID (defaults to current milestone from PROJECT_MANIFEST)
+- Read `.aiwf/00_PROJECT_MANIFEST.md` to understand current progress
+- Scan `.aiwf/03_SPRINTS/` to identify existing sprints for the target milestone
+- For each existing sprint, read its sprint meta file to determine status from YAML frontmatter
+- Analyze the Tasks in Sprints to understand that work that has been done (from Subtasks)
+
+## 2 · Assess completed work vs milestone requirements
+
+- Read milestone meta file from `.aiwf/02_REQUIREMENTS/$MILESTONE_ID/`
+- **CRITICAL:** Follow and read ALL linked documents in the milestone meta:
+  - Product Requirements (PRD.md)
+  - Database Specifications (SPECS_DB.md)
+  - API Specifications (SPECS_API.md)
+  - Tool Specifications (SPECS_TOOLS.md)
+  - Any other linked specifications
+- Study the milestone's Definition of Done (DoD) carefully and **think deeply** about what each DoD criterion actually requires in terms of specific deliverables
+- For each existing sprint, analyze what deliverables have been completed by reading sprint meta and task files
+- **Think more carefully** about the gap analysis: map each completed deliverable against specific DoD requirements and identify what's genuinely missing vs what might already be covered
+- Create clear picture: "What's done vs what's required for milestone completion" with specific justification for each gap identified
+
+## 3 · Identify remaining work and dependencies
+
+- Based on gap analysis, identify remaining deliverables for milestone completion
+- Group related deliverables that have natural dependencies
+- **CRITICAL:** Each deliverable group should be:
+  - **Independently valuable** (shippable increment)
+  - **Completable in ~1 week** by one person
+  - **Has clear validation criteria**
+- Consider technical dependencies (e.g., auth before UI, LLM integration before tools)
+
+## 4 · Design logical sprint boundaries
+
+- Design sprint structure to complete the milestone
+- Each sprint should have:
+  - **Clear focus**: One main deliverable theme
+  - **Natural boundaries**: Minimal dependencies between sprints
+  - **Incremental value**: Each sprint advances toward milestone DoD
+- Sprint naming: `S<nn>_$milestone_id_$focus_slug`
+- **IMPORTANT:** Don't create sprints for work that's already completed
+
+## 5 · Create sprint directories and meta files
+
+- For each planned sprint that doesn't exist:
+  - Create directory `.aiwf/03_SPRINTS/$FULL_SPRINT_NAME/` (using complete sprint name like "S02_M01_LLM_Integration")
+  - Use template from `.aiwf/99_TEMPLATES/sprint_meta_template.md`
+  - Fill in sprint meta with:
+    - High-level goal and scope
+    - Key deliverables (bullet points, not detailed tasks)
+    - Clear Definition of Done for the sprint
+    - Status: "planned"
+
+## 6 · Update PROJECT_MANIFEST with sprint roadmap
+
+- Update `.aiwf/00_PROJECT_MANIFEST.md`:
+  - Set `highest_sprint_in_milestone` to the highest planned sprint
+  - Update sprint summary section with overview of remaining sprints
+  - Mark completed sprints as ✅ COMPLETED
+  - Show planned sprints with their focus areas
+  - Update `last_updated` timestamp
+
+## 7 · Validate sprint coherence and dependencies
+
+- Review the planned sprint sequence for logical flow
+- Ensure each sprint builds naturally on previous work
+- Verify no sprint has impossible dependencies
+- Check that sprint sequence leads to milestone DoD completion
+- **Think about** whether each sprint is independently testable and valuable
+
+## 8 · Report milestone plan
+
+Provide comprehensive summary:
+
+**Milestone Status:**
+
+- Target milestone: $milestone_id
+- Sprints completed: $count
+- Sprints planned: $count
+- Estimated completion: $sprint_sequence
+
+**Sprint Roadmap:**
+
+For each sprint (existing and planned):
+
+- **$Sprint_ID**: $status - $focus_description
+- Key deliverables: $bullet_list
+- Dependencies: $if_any
+
+**Next Steps:**
+
+- Immediate next sprint to detail: $sprint_id
+
+**Validation:**
+
+Summarize your validation analysis covering:
+
+- All milestone DoD items are covered by sprint plan
+- Sprint dependencies are logical and minimal
+- Each sprint delivers independent value

package/claude-code/aiwf/en/.claude/commands/aiwf/aiwf_discuss_review.md

@@ -0,0 +1,29 @@
+# Discuss Review Results
+
+Engage in technical discussion about recent review findings based on discussion starter.
+
+Discussion Starter: <$ARGUMENTS>
+
+## Discussion Primer
+
+**IMPORTANT:** Maintain John Carmack perspective - brutally honest, practical, focused on shipping working software.
+
+### Discussion Tone
+
+- **Be conversational** but maintain technical depth
+- **Challenge assumptions** - question if issues are real problems for current development stage
+- **Explore trade-offs** - suggest multiple approaches with pros/cons
+- **Focus on decisions** - what to do next, not just analysis
+- **Consider context** - balance technical perfection vs delivery timeline
+
+### Potential Discussion Outcomes
+
+Based on the conversation, you may suggest:
+
+- **Amending review findings** if new context changes severity/priority
+- **Updating documentation** in `.aiwf/01_PROJECT_DOCS/` if architectural decisions need clarification
+- **Revising requirements** in `.aiwf/02_REQUIREMENTS/` if scope understanding was incorrect
+- **Creating tasks** for specific technical debt items that need addressing
+- **Adjusting sprint priorities** based on refined understanding
+
+**IMPORTANT:** Help make practical engineering decisions. Be John Carmack: direct, experienced, and focused on what actually matters for shipping.