@relipa/ai-flow-kit 0.0.1

package/docs/configuration.md

@@ -0,0 +1,412 @@
+# Configuration Guide
+
+Configure AI Flow Kit for your team's specific needs.
+
+## Configuration Levels
+
+### 1. Global Config (`~/.claude/ai-flow-kit.json`)
+
+User-level settings, applied to all projects.
+
+```json
+{
+  "defaultModel": "claude-opus-4-6",
+  "globalSkills": ["investigate-bug"],
+  "cacheContexts": true,
+  "contextCachePath": "~/.claude/ai-flow-kit/context-cache"
+}
+```
+
+### 2. Project Config (`.aiflowrc.json`)
+
+Team-level settings, applied to this project. **Recommended to commit to git.**
+
+```json
+{
+  "team": "engineering-team",
+  "description": "Configuration for engineering team projects",
+  
+  "adapters": ["jira", "google-sheets"],
+  "frameworks": ["laravel"],
+  "customSkills": ["investigate-bug", "impact-analysis"],
+  
+  "defaultModel": "claude-opus-4-6",
+  "autoDetectTasks": true,
+  "strictMode": false,
+  
+  "contextTemplate": "standard",
+  "prompting": {
+    "language": "english",
+    "detail": "comprehensive"
+  },
+  
+  "mcp": {
+    "timeout": 30000,
+    "retries": 3,
+    "fallback": "manual"
+  },
+  
+  "validation": {
+    "enabled": true,
+    "ruleSet": "default"
+  }
+}
+```
+
+### 3. Local State (`.aiflow/state.json`)
+
+Auto-generated, not recommended to edit manually.
+
+```json
+{
+  "current_version": "1.0.0",
+  "current_context": "JIRA-123",
+  "installed_adapters": ["jira"],
+  "last_update": "2024-04-03T10:00:00Z"
+}
+```
+
+## Configuration Options
+
+### Team Settings
+
+```json
+{
+  "team": "my-team",
+  "description": "Team name and description"
+}
+```
+
+### Adapter Configuration
+
+```json
+{
+  "adapters": ["jira", "backlog", "google-sheets"],
+  
+  "mcp": {
+    "timeout": 30000,              // MCP call timeout in ms
+    "retries": 3,                  // Retry failed calls
+    "fallback": "manual"           // Use manual entry if MCP fails
+  },
+  
+  "jira": {
+    "domain": "your-company",      // For auto-construction
+    "project": "DEFAULT"           // Default project
+  },
+  
+  "backlog": {
+    "spaceKey": "your-space"
+  }
+}
+```
+
+### Framework Configuration
+
+```json
+{
+  "frameworks": ["laravel", "nextjs"],
+  "defaultFramework": "laravel",
+  
+  "laravel": {
+    "phpVersion": "8.3",
+    "testFramework": "pest"
+  },
+  
+  "nextjs": {
+    "reactVersion": "18",
+    "styleFramework": "tailwind"
+  }
+}
+```
+
+### Skills Configuration
+
+```json
+{
+  "customSkills": ["investigate-bug", "impact-analysis"],
+  
+  "skillConfig": {
+    "investigate-bug": {
+      "traceDepth": "full",
+      "includeGitBlame": true,
+      "suggestSolutions": true
+    },
+    
+    "impact-analysis": {
+      "analyzeDeepDependencies": true,
+      "suggestTests": true
+    }
+  }
+}
+```
+
+### AI Model Configuration
+
+```json
+{
+  "defaultModel": "claude-opus-4-6",
+  
+  "modelFallback": [
+    "claude-opus-4-6",
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5"
+  ],
+  
+  "modelConfig": {
+    "temperature": 0.7,
+    "maxTokens": 8000,
+    "topP": 1.0
+  }
+}
+```
+
+### Task Detection Configuration
+
+```json
+{
+  "autoDetectTasks": true,
+  
+  "detection": {
+    "confidence_threshold": 0.8,    // Minimum confidence to auto-detect
+    "fallback": "ask",              // "ask" or "generic"
+    "debug": false                  // Log detection reasoning
+  },
+  
+  "taskTypes": {
+    "bug-fix": {
+      "keywords": ["bug", "error", "broken", "crash"],
+      "icon": "🐛"
+    },
+    
+    "feature": {
+      "keywords": ["add", "create", "build", "new"],
+      "icon": "✨"
+    },
+    
+    "refactor": {
+      "keywords": ["improve", "optimize", "refactor"],
+      "icon": "♻️"
+    },
+    
+    "investigation": {
+      "keywords": ["analyze", "investigate", "understand"],
+      "icon": "🔍"
+    }
+  }
+}
+```
+
+### Context Configuration
+
+```json
+{
+  "contextTemplate": "standard",   // "standard", "minimal", "comprehensive"
+  
+  "context": {
+    "includeGitHistory": true,
+    "includeFileTree": true,
+    "maxFileSize": 1000000,        // 1MB max per file
+    "cacheContexts": true,
+    "cacheTTL": 86400              // 24 hours
+  }
+}
+```
+
+### Prompting Configuration
+
+```json
+{
+  "prompting": {
+    "language": "english",         // "english", "vietnamese", etc
+    "detail": "comprehensive",     // "minimal", "standard", "comprehensive"
+    "examples": true,              // Include code examples
+    "bestPractices": true,         // Include team best practices
+    "warningLevel": "medium"       // "low", "medium", "high"
+  }
+}
+```
+
+### Validation Configuration
+
+```json
+{
+  "validation": {
+    "enabled": true,
+    "ruleSet": "default",          // or "strict", "custom"
+    "autoFix": false,
+    "reportLevel": "warning"       // "warning" or "error"
+  },
+  
+  "validationRules": {
+    "codeStyle": true,
+    "naming": true,
+    "performance": true,
+    "security": true,
+    "testing": false
+  }
+}
+```
+
+### Memory Configuration
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "autoLoadRelevant": true,
+    "maxMemorySize": 1000000,
+    "persistPath": ".aiflow/memory"
+  }
+}
+```
+
+### Strict Mode
+
+When `"strictMode": true`, AI Flow Kit will:
+- Require explicit confirmation for risky changes
+- Enforce all validation rules
+- Require full test coverage
+- Enforce strict code standards
+
+```json
+{
+  "strictMode": true,
+  
+  "strictModeRules": {
+    "requireTests": true,
+    "requireDocumentation": true,
+    "requireReview": false,
+    "autoCommit": false
+  }
+}
+```
+
+## Example Configurations
+
+### Startup Configuration (Minimal)
+```json
+{
+  "team": "startup",
+  "adapters": ["google-sheets"],
+  "frameworks": ["nextjs"],
+  "autoDetectTasks": true,
+  "strictMode": false
+}
+```
+
+### Enterprise Configuration (Strict)
+```json
+{
+  "team": "enterprise-backend",
+  "adapters": ["jira", "google-sheets"],
+  "frameworks": ["laravel"],
+  "customSkills": ["investigate-bug", "impact-analysis", "generate-spec"],
+  
+  "defaultModel": "claude-opus-4-6",
+  "autoDetectTasks": true,
+  "strictMode": true,
+  
+  "validation": {
+    "enabled": true,
+    "ruleSet": "strict"
+  },
+  
+  "strictModeRules": {
+    "requireTests": true,
+    "requireDocumentation": true,
+    "requireReview": true,
+    "autoCommit": false
+  }
+}
+```
+
+### API/Backend Configuration
+```json
+{
+  "team": "api-team",
+  "frameworks": ["laravel"],
+  "customSkills": ["investigate-bug", "impact-analysis"],
+  
+  "prompting": {
+    "detail": "comprehensive"
+  },
+  
+  "validationRules": {
+    "security": true,
+    "performance": true,
+    "testing": true
+  }
+}
+```
+
+### Frontend Configuration
+```json
+{
+  "team": "frontend-team",
+  "frameworks": ["nextjs"],
+  
+  "prompting": {
+    "examples": true
+  },
+  
+  "validationRules": {
+    "performance": true,
+    "accessibility": true,
+    "styling": true
+  }
+}
+```
+
+## Overriding Configuration
+
+Priority order (highest to lowest):
+1. **Environment variables** — `AIFLOW_*`
+2. **Local flags** — `aiflow prompt --model claude-opus-4-6`
+3. **Project config** — `.aiflowrc.json`
+4. **Global config** — `~/.claude/ai-flow-kit.json`
+5. **Defaults** — Built-in defaults
+
+### Environment Variables
+
+```bash
+# Override model
+export AIFLOW_MODEL=claude-opus-4-6
+
+# Override adapters
+export AIFLOW_ADAPTERS=jira,google-sheets
+
+# Enable debug
+export AIFLOW_DEBUG=true
+
+# Custom context path
+export AIFLOW_CONTEXT_PATH=/custom/path
+```
+
+## Tips
+
+1. **Commit `.aiflowrc.json`** — Makes it easy to onboard new team members
+2. **Don't commit global config** — It's user-specific
+3. **Use environment variables for secrets** — MCP credentials should be in env
+4. **Version your config** — If you make significant changes, increment version
+5. **Test config** — Run `aiflow doctor` to validate
+
+## Troubleshooting
+
+**Q: Changes not taking effect?**
+```bash
+# Check current config
+aiflow doctor
+
+# Reload config
+aiflow update
+```
+
+**Q: Unsure what config to use?**
+```bash
+# Create recommended config for your stack
+aiflow init --framework laravel --adapter jira
+```
+
+---
+
+See [Architecture Guide](./architecture.md) for how configuration is used.

package/docs/getting-started.md

@@ -0,0 +1,248 @@
+# Getting Started with AI Flow Kit
+
+This guide walks you through setting up AI Flow Kit for your first project.
+
+## Prerequisites
+
+- Node.js 14+ installed
+- Claude Code installed (with access to Claude)
+- A project you want to work on
+- Optional: Jira, Backlog, or Google Sheets account (for pulling task context)
+
+## Step 1: Install AI Flow Kit
+
+### Global Installation (Recommended for teams)
+```bash
+npm install -g ai-flow-kit
+aiflow --version
+```
+
+### Local Installation
+```bash
+cd your-project
+npm install ai-flow-kit
+npx aiflow --version
+```
+
+## Step 2: Initialize Your Project
+
+Navigate to your project directory and run:
+
+```bash
+aiflow init
+```
+
+This will:
+- Create `.claude/skills/` — AI skills for your team
+- Create `.rules/` — Team coding standards
+- Create `.aiflow/` — Internal configuration
+- Prompt you to set framework (optional)
+
+### With Framework & Adapter
+
+```bash
+# Full setup with framework and project management tool
+aiflow init --framework laravel --adapter jira
+```
+
+**Available frameworks:**
+- `laravel` — PHP/Laravel projects
+- `nextjs` — Next.js (React) projects
+- `vue-nuxt` — Vue/Nuxt projects
+
+**Available adapters:**
+- `jira` — Atlassian Jira
+- `backlog` — Nulab Backlog
+- `google-sheets` — Google Sheets for task tracking
+
+## Step 3: Verify Setup
+
+Check that everything is configured correctly:
+
+```bash
+aiflow doctor
+```
+
+Expected output:
+```
+Running health check for AI Flow Kit...
+
+✓ .claude/skills exists
+✓ .rules exists
+✓ CLAUDE.md exists
+✓ Version tracking active (v1.0.0)
+
+✨ Everything looks healthy! You are ready to fly.
+```
+
+## Step 4: Your First Task
+
+Let's walk through a complete workflow.
+
+### Example: Fix a Bug
+
+**1. Load the bug context:**
+```bash
+# From Jira
+aiflow use JIRA-2024-123
+
+# From Backlog
+aiflow use BACKLOG-456
+
+# Or just create context manually
+aiflow use --manual
+```
+
+This pulls:
+- Bug description
+- Reproduction steps
+- Acceptance criteria
+- Related files/links
+
+**2. Generate a prompt:**
+```bash
+aiflow prompt bug-fix
+```
+
+This creates a prompt template with:
+- Your bug context
+- Team coding rules
+- Investigation workflow
+- Example solutions
+
+**3. Use in Claude Code:**
+- Copy the generated prompt
+- Open Claude Code
+- Paste the prompt
+- Claude will auto-detect it's a bug fix and run the `investigate-bug` skill
+- Follow along as Claude traces through your code
+
+**4. After Claude fixes it:**
+```bash
+# Verify the fix doesn't break anything
+npm test
+
+# Review changes
+git diff
+
+# Commit when satisfied
+git add .
+git commit -m "fix: [JIRA-2024-123] Resolve payment processing issue"
+```
+
+## Configuration
+
+Create `.aiflowrc.json` in your project root (optional):
+
+```json
+{
+  "team": "my-team",
+  "adapters": ["jira"],
+  "frameworks": ["laravel"],
+  "customSkills": ["investigate-bug", "impact-analysis"],
+  "defaultModel": "claude-opus-4-6",
+  "autoDetectTasks": true,
+  "strictMode": false
+}
+```
+
+See [Configuration Guide](./configuration.md) for all options.
+
+## Next Steps
+
+- 📖 [Read workflow examples](./workflows/)
+- ⚙️ [Configure adapters](./configuration.md)
+- 🎯 [Understand available tasks](./cli-reference.md)
+- 🔧 [Customize for your team](./architecture.md)
+
+## Common Tasks
+
+### Load context from a ticket
+```bash
+aiflow use JIRA-123
+# or
+aiflow use BACKLOG-456
+# or create manually
+aiflow use --manual
+```
+
+### Generate a prompt for different task types
+```bash
+aiflow prompt bug-fix        # For fixing bugs
+aiflow prompt feature        # For building features
+aiflow prompt investigation  # For analyzing code
+aiflow prompt refactor       # For improving code
+aiflow prompt impact         # For assessing changes
+```
+
+### Update to latest version
+```bash
+aiflow update
+# Will download latest skills and templates
+```
+
+### Switch between versions
+```bash
+aiflow use 1.0.0  # Use specific version
+```
+
+### Check project setup
+```bash
+aiflow doctor
+```
+
+## Troubleshooting
+
+### "aiflow command not found"
+```bash
+# If installed globally
+npm install -g ai-flow-kit
+
+# If installed locally
+npx aiflow --version
+```
+
+### "Cannot load context from Jira"
+```bash
+# Verify credentials
+echo $JIRA_API_TOKEN
+echo $JIRA_EMAIL
+echo $JIRA_DOMAIN
+
+# Check health
+aiflow doctor
+```
+
+### "CLAUDE.md not found"
+```bash
+# Regenerate it
+aiflow init
+# or with specific framework
+aiflow init --framework laravel
+```
+
+See [Troubleshooting Guide](./troubleshooting.md) for more help.
+
+## Tips for Success
+
+1. **Use task context** — Always pull from tickets when possible. It helps Claude understand requirements.
+
+2. **Follow the prompt template** — The generated prompt includes best practices and examples. Don't skip sections.
+
+3. **Commit frequently** — After Claude makes changes, review and commit. Makes it easier to review and rollback.
+
+4. **Use the right task type** — Picking the correct task type helps Claude use the right workflow.
+
+5. **Customize rules** — Add team-specific rules in `custom/rules/`. Claude will follow them.
+
+6. **Share with team** — Once setup, other developers just need to run `aiflow update`.
+
+## Getting Help
+
+- 📖 [Full Documentation](../README.md)
+- 💬 [Ask a question](../issues)
+- 🤝 [See how others use it](../discussions)
+
+---
+
+**Ready to supercharge your development?** Run `aiflow init` and start with your first task! 🚀