ai-sprint-kit 1.1.5 → 1.1.8

package/README.md

@@ -1,5 +1,7 @@
 # AI Sprint Kit
 
+[English](./README.md) | [ภาษาไทย](./README-th.md)
+
 [![npm version](https://img.shields.io/npm/v/ai-sprint-kit.svg)](https://www.npmjs.com/package/ai-sprint-kit)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
@@ -46,6 +48,34 @@ claude
 
 ### 9 Specialized Agents
 
+```mermaid
+flowchart LR
+    subgraph Planning
+        R[🔍 Researcher]
+        P[📋 Planner]
+    end
+
+    subgraph Development
+        I[💻 Implementer]
+        T[🧪 Tester]
+    end
+
+    subgraph Quality
+        RV[👀 Reviewer]
+        S[🔒 Security]
+    end
+
+    subgraph Operations
+        D[🚀 DevOps]
+        DC[📄 Docs]
+        DB[🐛 Debugger]
+    end
+
+    R --> P --> I --> T --> RV --> S --> D
+    DB -.-> I
+    DC -.-> D
+```
+
 | Agent | Superpower |
 |-------|------------|
 | **Planner** | Researches & architects solutions before coding |
@@ -118,6 +148,18 @@ ai-sprint init
 --no-scan        # Skip codebase scanning
 ```
 
+### Updating
+
+To update to the latest version:
+
+```bash
+# Re-run init to update templates
+npx ai-sprint-kit@latest init --force
+
+# Or update globally installed version
+npm update -g ai-sprint-kit
+```
+
 ---
 
 ## Project Structure After Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-sprint-kit",
-  "version": "1.1.5",
+  "version": "1.1.8",
   "description": "CLI installer for autonomous coding agent framework - security-first, production-grade Claude Code setup",
   "main": "lib/installer.js",
   "bin": {
@@ -21,7 +21,7 @@
     "code-generation",
     "ai-sprint"
   ],
-  "author": "Apiasak Pungpapong",
+  "author": "Apipoj Piasak <https://data-espresso.com>",
   "license": "PolyForm-Noncommercial-1.0.0",
   "repository": {
     "type": "git",

package/templates/.claude/commands/auto.md

@@ -3,83 +3,148 @@ description: Automatic full development cycle (plan → code → test → review
 argument-hint: [feature description]
 ---
 
-## Command: /auto
+**ULTRATHINK** - Execute complete autonomous development workflow.
 
-Execute complete autonomous development workflow from planning to deployment-ready code.
+**Objective:** $ARGUMENTS
 
-## Usage
+## MANDATORY Workflow Execution
+
+**CRITICAL:** You MUST execute each phase in order. Do NOT skip to coding.
+
+---
+
+### Phase 1: Planning (MANDATORY - Execute First)
+
+**⚠️ STOP! Before ANY code, execute `/plan` command:**
 
 ```
-/auto "implement user authentication"
-/auto "add payment processing with Stripe"
-/auto "create REST API for products"
+/plan "$ARGUMENTS"
 ```
 
-## Workflow
+The `/plan` command will:
+1. Research best practices and approaches
+2. Ask clarifying questions if needed
+3. Create implementation plan with architecture
+4. Save plan to `ai_context/plans/`
 
-### 1. Plan
-- Research approaches
-- Create implementation plan
-- Define architecture
+**Validation Gate:** Plan MUST exist before proceeding.
+- Check: `ai_context/plans/` has new plan directory
+- If NO plan exists → STOP and run `/plan` first
 
-### 2. Implement
-- Generate production code
-- Follow security best practices
-- Handle errors properly
+---
 
-### 3. Test
-- Generate unit tests
-- Generate integration tests
-- Ensure >80% coverage
+### Phase 2: Implementation
 
-### 4. Review
-- Code quality analysis
-- Best practices check
-- Refactoring suggestions
+Only after plan exists, execute:
+```
+/code "implement the plan at ai_context/plans/{plan-path}"
+```
 
-### 5. Security Scan
-- SAST scanning
-- Secret detection
-- Dependency check
+**Requirements:**
+- Follow the plan phases step by step
+- Generate production-quality code
+- Follow security best practices (OWASP Top 10)
+- Handle errors properly (no silent failures)
 
-### 6. Documentation
-- Update README
-- Generate API docs
-- Add code comments
+---
 
-## Human-in-the-Loop Gates
+### Phase 3: Testing
 
-You will be asked to approve:
-- Deployment actions
-- Infrastructure changes
-- Security vulnerability fixes
+After implementation, execute:
+```
+/test
+```
 
-## Output
+**Requirements:**
+- Generate unit tests for business logic
+- Generate integration tests for APIs
+- Ensure >80% code coverage
+- All tests must pass
 
-Complete, deployment-ready feature:
-- ✅ Implemented code
-- ✅ Passing tests (>80% coverage)
-- ✅ Security validated
-- ✅ Code reviewed
-- ✅ Documented
+**Validation Gate:** Tests must pass before proceeding.
+- If tests fail → Fix issues → Rerun `/test`
+- Do NOT proceed with failing tests
 
-## Success Criteria
+---
+
+### Phase 4: Code Review
+
+After tests pass, execute:
+```
+/review
+```
+
+**Requirements:**
+- Code quality analysis (YAGNI, KISS, DRY)
+- Best practices verification
+- No critical issues allowed
 
-- All tests pass
-- No critical security issues
-- Code review approved
-- Documentation updated
+**Validation Gate:** Review must pass.
+- If critical issues → Fix → Rerun `/review`
 
-## Estimated Time
+---
+
+### Phase 5: Security Scan
+
+After review passes, execute:
+```
+/secure
+```
+
+**Requirements:**
+- SAST scanning for vulnerabilities
+- Secret detection (no hardcoded credentials)
+- Dependency vulnerability check
 
-- Simple features: 5-15 minutes
-- Medium features: 15-45 minutes
-- Complex features: 45+ minutes
+**Validation Gate:** No high/critical security issues.
+- If issues found → Fix → Rerun `/secure`
 
-## Next Steps
+---
+
+### Phase 6: Documentation
+
+After security passes, execute:
+```
+/docs
+```
+
+**Requirements:**
+- Update relevant documentation
+- Add code comments where needed
+- Generate API docs if applicable
+
+---
+
+## Human-in-the-Loop Gates
+
+Pause and ask for approval before:
+- Deployment actions
+- Infrastructure changes
+- Critical security vulnerability fixes
+- Database schema migrations
+
+## Success Criteria
 
-After /auto completion:
-1. Review generated code
-2. Test manually if needed
-3. Commit and push
-4. Deploy (with /deploy if needed)
+All gates must pass:
+- ✅ Plan created and approved
+- ✅ Code implemented per plan
+- ✅ Tests passing (>80% coverage)
+- ✅ Code review approved
+- ✅ Security scan clean
+- ✅ Documentation updated
+
+## Final Report
+
+After all phases complete, provide summary:
+1. What was implemented
+2. Test coverage achieved
+3. Security scan results
+4. Files created/modified
+5. Next steps (commit, deploy)
+
+## REMEMBER
+
+- **Phase 1 is MANDATORY** - Always run `/plan` first
+- **No skipping** - Execute each phase in order
+- **Validation gates** - Do not proceed if a gate fails
+- **Fix and retry** - If any phase fails, fix issues and rerun

package/templates/.claude/commands/code.md

@@ -1,32 +1,47 @@
 ---
 description: Generate or refactor code with best practices and security
-argument-hint: [what to build or refactor]
+argument-hint: [plan-path or task description]
 ---
 
-## Command: /code
+**THINK HARDER** - Follow plan or implement with security-first approach.
 
-Generate production-grade code or refactor existing code following best practices, security guidelines, and design patterns.
+**Objective:** $ARGUMENTS
 
-## Usage
+## Workflow
 
-```
-/code "implement user authentication with JWT"
-/code "refactor the payment service to use async/await"
-/code "add input validation to all API endpoints"
-/code "optimize database queries in user service"
-```
+### Step 0: Check for Plan (IMPORTANT)
 
-## Workflow
+**If argument contains a plan path (e.g., `ai_context/plans/...`):**
+1. Read the plan: `plan.md` and `phase-*.md` files
+2. Follow implementation phases in order
+3. Mark phases complete as you progress
+
+**If no plan exists:**
+- Ask: "No plan found. Run `/plan` first or proceed with direct implementation?"
+- If direct implementation requested, continue to Step 1
+
+---
+
+### Step 1: Understand Requirements
 
-### 1. Understand Requirements
+- Read plan phases if available
 - Clarify what needs to be built or refactored
 - Ask questions if requirements unclear
 - Identify affected files and components
 
-### 2. Delegate to Implementer Agent
-- Spawn implementer agent with detailed instructions
-- Agent follows security-first principles
-- Implements with proper error handling
+---
+
+### Step 2: Delegate to Implementer Agent
+
+```
+Task(subagent_type="implementer", prompt="Implement: $ARGUMENTS. Follow security-first principles, YAGNI/KISS/DRY. Handle errors properly.", description="Implement code")
+```
+
+Agent responsibilities:
+- Follow plan phases if provided
+- Security-first implementation
+- Proper error handling
+- Type safety
 
 ### 3. Code Generation
 - Generate clean, maintainable code

package/templates/.claude/commands/debug.md

@@ -3,6 +3,10 @@ description: Investigate and fix bugs with root cause analysis
 argument-hint: [bug description or error message]
 ---
 
+**THINK HARDER** - Systematic root cause analysis requires careful investigation.
+
+**Objective:** $ARGUMENTS
+
 ## Command: /debug
 
 Systematically investigate bugs, perform root cause analysis, and provide fixes with regression tests.

package/templates/.claude/commands/plan.md

@@ -3,55 +3,134 @@ description: Create comprehensive implementation plan with research and architec
 argument-hint: [feature or task description]
 ---
 
-## Command: /plan
+**ULTRATHINK** - Deep thinking mode for comprehensive planning.
 
-Create a detailed implementation plan for the given feature or task.
+**Objective:** $ARGUMENTS
 
-## Usage
+## MANDATORY Workflow
+
+**CRITICAL:** Follow these steps in order. Do NOT skip research.
+
+---
+
+### Step 1: Context & Memory
+
+```bash
+# Get current timestamp (DO NOT guess dates)
+date "+%y%m%d-%H%M"
+```
+
+Check memory for past lessons:
+- Read `ai_context/memory/learning.md` for mistakes to avoid
+- Read `ai_context/memory/decisions.md` for past architectural decisions
+
+---
+
+### Step 2: Clarification
+
+Use `AskUserQuestion` tool if requirements are unclear:
+- Technical constraints?
+- Performance requirements?
+- Security considerations?
+- Integration points?
+
+---
+
+### Step 3: Research (MANDATORY)
+
+**⚠️ Do NOT skip research. Use researcher agent:**
 
 ```
-/plan "implement user authentication with OAuth2"
-/plan "add real-time notifications"
-/plan "refactor database layer for PostgreSQL"
+Task(subagent_type="researcher", prompt="Research best practices and approaches for: $ARGUMENTS. Find: 1) Common patterns 2) Security considerations 3) Potential pitfalls 4) Recommended libraries/tools. Limit to 5 sources.", description="Research task requirements")
 ```
 
-## Workflow
+Research must cover:
+- Industry best practices
+- Security considerations (OWASP if applicable)
+- Common implementation patterns
+- Potential risks and mitigation
 
-1. **Get timestamp** - `date "+%y%m%d-%H%M"` (DO NOT guess dates)
-2. **Check memory** - Read `ai_context/memory/learning.md` for past lessons
-3. **Understand** the requirement
-4. **Ask** clarifying questions if needed
-5. **Delegate** to planner agent
-6. **Research** best practices and approaches
-7. **Create** comprehensive plan in `ai_context/plans/` directory
-8. **Update memory** - Record decisions in `ai_context/memory/decisions.md`
+---
 
-## Plan Contents
+### Step 4: Architecture Planning
 
-- **Overview** - Summary with phases
-- **Architecture** - Technical decisions
-- **Phases** - Step-by-step implementation
-- **Risks** - Potential issues and mitigation
-- **Security** - Security considerations
-- **Success Criteria** - Definition of done
+Use planner agent with research results:
 
-## Output
+```
+Task(subagent_type="planner", prompt="Create implementation plan for: $ARGUMENTS. Use research findings. Include: architecture, phases, risks, security, success criteria.", description="Create implementation plan")
+```
 
-Plan created at: `ai_context/plans/YYMMDD-HHMM-feature-name/`
-- `plan.md` - Main overview
-- `phase-*.md` - Detailed phases
+---
 
-## Memory Integration
+### Step 5: Create Plan Files
 
-Before planning:
-- Check `ai_context/memory/learning.md` for past mistakes to avoid
+Create plan directory: `ai_context/plans/YYMMDD-HHMM-feature-name/`
 
-After planning:
-- Update `ai_context/memory/decisions.md` with key decisions
+**Required files:**
+
+1. **plan.md** - Overview (keep under 80 lines)
+   ```yaml
+   ---
+   title: "Feature name"
+   status: pending
+   created: YYYY-MM-DD
+   ---
+   ```
+   - Summary
+   - Phase list with links
+   - Success criteria
+
+2. **phase-XX-name.md** - Detailed phases
+   - Requirements
+   - Architecture decisions
+   - Implementation steps
+   - Security considerations
+   - Success criteria
+
+3. **research/researcher-report.md** - Research findings
+
+---
+
+### Step 6: Update Memory
+
+After plan creation:
+- Add key decisions to `ai_context/memory/decisions.md`
+- Note any lessons learned
+
+---
+
+## Plan Contents
+
+Every plan must include:
+- **Overview** - What we're building and why
+- **Architecture** - Technical decisions with rationale
+- **Phases** - Step-by-step implementation (ordered)
+- **Risks** - Potential issues and mitigation strategies
+- **Security** - Security considerations and requirements
+- **Success Criteria** - Definition of done
+
+## Output
+
+Plan directory structure:
+```
+ai_context/plans/YYMMDD-HHMM-feature-name/
+├── plan.md           # Overview
+├── phase-01-*.md     # Phase details
+├── phase-02-*.md
+└── research/
+    └── researcher-report.md
+```
 
 ## Next Steps
 
 After plan creation:
-1. Review plan
-2. Approve or request changes
-3. Execute with `/code` or `/auto`
+1. Review plan with user
+2. Get approval or make adjustments
+3. Execute with `/code {plan-path}` or continue `/auto`
+
+## REMEMBER
+
+- **ULTRATHINK** - Take time to think deeply about architecture
+- **Research FIRST** - Always research before planning
+- **No shortcuts** - Complete all steps in order
+- **Memory matters** - Check past lessons, record new decisions

package/templates/.claude/commands/review.md

@@ -3,6 +3,10 @@ description: Comprehensive code quality review and best practices analysis
 argument-hint: [optional: specific file or directory to review]
 ---
 
+**THINK HARDER** - Thorough code review requires careful security and quality analysis.
+
+**Objective:** $ARGUMENTS
+
 ## Command: /review
 
 Perform comprehensive code quality review focusing on security, maintainability, performance, and best practices.