@relipa/ai-flow-kit 0.0.1

package/docs/troubleshooting.md

@@ -0,0 +1,587 @@
+# Troubleshooting Guide
+
+Solutions to common issues with AI Flow Kit.
+
+## Installation & Setup
+
+### "aiflow command not found"
+
+**Global installation:**
+```bash
+npm install -g ai-flow-kit
+aiflow --version
+```
+
+**Local installation:**
+```bash
+cd your-project
+npm install ai-flow-kit
+npx aiflow --version
+```
+
+**Windows cmd/PowerShell:**
+```cmd
+npm install -g ai-flow-kit
+refreshenv
+aiflow --version
+```
+
+### "Permission denied" on Mac/Linux
+
+```bash
+# Make script executable
+chmod +x ~/.npm/_npx/*/bin/aiflow.js
+
+# Or reinstall globally
+npm uninstall -g ai-flow-kit
+npm install -g ai-flow-kit
+```
+
+---
+
+## Initialization
+
+### "aiflow init" fails with error
+
+**Check Node.js version:**
+```bash
+node --version  # Should be 14 or higher
+npm --version   # Should be 6 or higher
+```
+
+**Clear npm cache:**
+```bash
+npm cache clean --force
+npm install -g ai-flow-kit
+```
+
+**Check disk space:**
+```bash
+# On Mac/Linux
+df -h
+
+# On Windows
+dir C:\
+```
+
+---
+
+## Context Loading
+
+### "Cannot load context from Jira"
+
+**Verify credentials:**
+```bash
+echo $JIRA_API_TOKEN
+echo $JIRA_EMAIL
+echo $JIRA_DOMAIN
+```
+
+If empty, set them:
+
+**Mac/Linux:**
+```bash
+export JIRA_API_TOKEN=your-token
+export JIRA_EMAIL=your-email
+export JIRA_DOMAIN=your-domain
+```
+
+**Windows PowerShell:**
+```powershell
+$env:JIRA_API_TOKEN = "your-token"
+$env:JIRA_EMAIL = "your-email"
+$env:JIRA_DOMAIN = "your-domain"
+```
+
+**Verify connection:**
+```bash
+aiflow doctor
+# Should show: ✓ Jira adapter configured
+```
+
+### "Cannot connect to Backlog"
+
+```bash
+# Check credentials
+echo $BACKLOG_API_KEY
+echo $BACKLOG_SPACE_KEY
+
+# Verify API key is valid
+# Visit: https://<space-key>.backlogtool.com/api/v2/users/me
+# (Use API key as username, empty password)
+```
+
+### "Cannot load from Google Sheets"
+
+```bash
+# Verify Google Sheets service account
+ls ~/.config/google-sheets-key.json
+
+# Or set path
+export GOOGLE_SHEETS_CREDS=/path/to/credentials.json
+```
+
+---
+
+## Configuration
+
+### ".aiflowrc.json" not being read
+
+**Verify file exists:**
+```bash
+ls -la .aiflowrc.json
+# Should show file in current directory
+```
+
+**Check file format:**
+```bash
+# Verify it's valid JSON
+cat .aiflowrc.json | jq .
+# Should not show errors
+```
+
+**Reload configuration:**
+```bash
+aiflow update
+aiflow doctor
+```
+
+### "Config option not working"
+
+**Verify option name:**
+```bash
+# Check configuration guide
+# for correct spelling and format
+cat docs/configuration.md
+```
+
+**Check precedence:**
+Options are overridden in this order:
+1. Environment variables (highest)
+2. CLI flags
+3. `.aiflowrc.json`
+4. Global config
+5. Defaults (lowest)
+
+---
+
+## Context Management
+
+### "Context file not found"
+
+```bash
+# Check context exists
+ls .claude/context/
+
+# If missing, reload context
+aiflow use JIRA-123  # Reload from ticket
+# or
+aiflow use --file path/to/context.json
+```
+
+### "Cannot save context"
+
+**Check permissions:**
+```bash
+ls -ld .claude
+# Should show: drwxr-xr-x
+
+chmod -R 755 .claude
+```
+
+**Check disk space:**
+```bash
+df -h
+# Should have > 100MB free
+```
+
+---
+
+## Prompting
+
+### "Generated prompt is incomplete"
+
+**Check context loaded:**
+```bash
+aiflow context --show
+# Should show title, description, criteria
+```
+
+**Try with more detail:**
+```bash
+aiflow prompt bug-fix --detail comprehensive
+```
+
+**Check framework template:**
+```bash
+ls CLAUDE.md
+cat CLAUDE.md | head -20
+```
+
+### "Prompt has formatting issues"
+
+**Save to file instead:**
+```bash
+aiflow prompt bug-fix -o prompt.md
+# Review file before copying
+cat prompt.md
+```
+
+**Copy from file carefully:**
+```bash
+# Ensure all text is selected
+# Including blank lines
+```
+
+---
+
+## Task Detection
+
+### "Task type not detected"
+
+**Show detection confidence:**
+```bash
+aiflow detect "Your description" --verbose
+```
+
+**Manually specify type:**
+```bash
+aiflow prompt bug-fix      # If you know it's a bug
+aiflow prompt feature      # If you know it's a feature
+```
+
+**Lower confidence threshold:**
+```json
+{
+  "detection": {
+    "confidence_threshold": 0.7
+  }
+}
+```
+
+### "Wrong task type detected"
+
+**Improve description:**
+```bash
+# Bad: "Something is broken"
+# Better: "Payment processing fails on checkout"
+
+aiflow detect "Payment processing fails on checkout" --verbose
+```
+
+**Provide context ticket:**
+```bash
+aiflow use JIRA-123
+# Better context helps detection
+```
+
+---
+
+## Version Management
+
+### "Cannot update to latest"
+
+**Check internet connection:**
+```bash
+ping npm.js
+```
+
+**Clear npm cache:**
+```bash
+npm cache clean --force
+```
+
+**Force update:**
+```bash
+aiflow update --force
+```
+
+### "Want to use older version"
+
+**See available versions:**
+```bash
+ls .aiflow/versions/
+```
+
+**Switch to older version:**
+```bash
+aiflow use 0.9.0
+aiflow doctor
+# Verify it works
+```
+
+### "Updated but changes not appearing"
+
+```bash
+# Update and clear cache
+aiflow update
+
+# Verify update
+aiflow doctor
+
+# Reload in Claude Code
+# (Close and reopen)
+```
+
+---
+
+## Skills & Rules
+
+### "Custom skill not showing up"
+
+**Verify file created:**
+```bash
+ls custom/skills/my-skill/SKILL.md
+```
+
+**Check file format:**
+```bash
+# Should have frontmatter
+head -5 custom/skills/my-skill/SKILL.md
+# Should show: ---\nname: my-skill
+```
+
+**Reload skills:**
+```bash
+aiflow update
+aiflow doctor
+```
+
+### "Custom rule not applied"
+
+**Verify rule file:**
+```bash
+ls custom/rules/my-rule.md
+cat custom/rules/my-rule.md | head -10
+```
+
+**Check rule is in prompt:**
+```bash
+aiflow prompt bug-fix | grep -i "my-rule"
+```
+
+**Verify rule syntax:**
+```bash
+# Rules are markdown with examples
+# Check for proper formatting
+```
+
+---
+
+## Memory System
+
+### "Memory not saving"
+
+**Check directory exists:**
+```bash
+ls -la .aiflow/memory/
+```
+
+**Create if missing:**
+```bash
+mkdir -p .aiflow/memory
+chmod 755 .aiflow/memory
+```
+
+**Try again:**
+```bash
+aiflow memory --save "test" "value"
+aiflow memory --get "test"
+```
+
+### "Memory not loading automatically"
+
+**Check auto-load enabled:**
+```json
+{
+  "memory": {
+    "autoLoadRelevant": true
+  }
+}
+```
+
+**Manually load relevant memory:**
+```bash
+aiflow memory --search "payment"
+# Then manually reference in prompt
+```
+
+---
+
+## Health Check
+
+### "aiflow doctor shows errors"
+
+**Run with fix:**
+```bash
+aiflow doctor --fix
+# Automatically fix common issues
+```
+
+**Reinitialize:**
+```bash
+aiflow init
+# Recreates missing files
+```
+
+**Detailed check:**
+```bash
+aiflow doctor --verbose
+# Shows detailed checks
+```
+
+---
+
+## Performance Issues
+
+### "aiflow commands slow"
+
+**Check disk I/O:**
+```bash
+# Try on different disk
+# (SSD vs HDD makes difference)
+```
+
+**Check file size:**
+```bash
+du -sh .claude/
+du -sh .aiflow/
+# Should be < 100MB combined
+```
+
+**Clear old contexts:**
+```bash
+aiflow context --clear
+# Removes cached contexts
+```
+
+### "Context loading slow"
+
+**Check MCP timeout:**
+```json
+{
+  "mcp": {
+    "timeout": 30000
+  }
+}
+```
+
+**Use manual context:**
+```bash
+aiflow use --manual
+# Faster than MCP queries
+```
+
+---
+
+## Validation & Quality
+
+### "Validation is too strict"
+
+**Use less strict ruleset:**
+```bash
+aiflow validate output.php --ruleset default
+# Instead of: --ruleset strict
+```
+
+**Disable specific rules:**
+```json
+{
+  "validationRules": {
+    "naming": false,
+    "codeStyle": true
+  }
+}
+```
+
+### "Validation not catching issues"
+
+**Use strict ruleset:**
+```bash
+aiflow validate output.php --ruleset strict
+```
+
+**Add custom rules:**
+```bash
+touch custom/rules/my-strict-rule.md
+aiflow update
+```
+
+---
+
+## Claude Code Integration
+
+### "Claude doesn't detect skill"
+
+**Verify skill is in `.claude/skills/`:**
+```bash
+ls .claude/skills/investigate-bug/
+```
+
+**Check CLAUDE.md includes context:**
+```bash
+cat CLAUDE.md | head -20
+# Should reference skills
+```
+
+**Update Claude Code:**
+- Close Claude Code
+- `aiflow update`
+- Reopen Claude Code
+
+### "AI not following team rules"
+
+**Verify rules in `.rules/`:**
+```bash
+ls .rules/
+```
+
+**Check CLAUDE.md loaded:**
+```bash
+cat CLAUDE.md | grep -i "rule"
+```
+
+**Refresh Claude Code:**
+- Close and reopen
+- Run `aiflow doctor` to verify setup
+
+---
+
+## Getting More Help
+
+1. **Check logs:**
+   ```bash
+   aiflow doctor --verbose
+   ```
+
+2. **Check documentation:**
+   ```bash
+   cat docs/getting-started.md
+   cat docs/architecture.md
+   ```
+
+3. **Verify setup:**
+   ```bash
+   aiflow doctor
+   ```
+
+4. **Ask for help:**
+   - Create an issue on GitHub
+   - Check existing issues/discussions
+   - Contact team lead
+
+---
+
+## Quick Fixes Checklist
+
+- [ ] `npm install -g ai-flow-kit` — Fresh install
+- [ ] `aiflow update` — Update to latest
+- [ ] `aiflow doctor` — Verify setup
+- [ ] `aiflow doctor --fix` — Auto-fix issues
+- [ ] `aiflow init --framework <name>` — Reinitialize
+- [ ] Clear contexts: `aiflow context --clear`
+- [ ] Restart Claude Code — Reload configuration
+
+---
+
+**Still stuck?** Check [Getting Started](./getting-started.md) or create an issue. 🆘

package/docs/workflows/bug-fix.md

@@ -0,0 +1,126 @@
+# Bug Fix Workflow
+
+> See the full workflow at [AIFLOW.md](../../AIFLOW.md)
+> **Gates must pass in order: 1 → 2 → 3 → 4 → 5**
+
+---
+
+## Step 1: Load ticket & AI analyzes (Gate 1)
+
+```bash
+aiflow use PROJ-33 --with-comments    # get both comments — important for bugs
+claude                                # AI auto-starts Gate 1
+```
+
+AI will **automatically**:
+1. Load ticket info + comments from Backlog/Jira
+2. Read source code — trace data flow related to the bug
+3. Use `superpowers:systematic-debugging` to form root cause hypothesis
+4. Ask clarifying questions if reproduction steps are unclear
+5. Output `plan/[ticket-id]/requirement.md` containing:
+   - Bug analysis (current vs expected behavior)
+   - **Root cause hypothesis** with evidence from source code
+   - **Proposed fix approach** (with alternatives if applicable)
+   - **Impact analysis** — will the fix break anything else?
+   - **Effort estimate** (S/M/L/XL)
+   - Testing plan (reproduce bug + verify fix)
+
+**PM needs to prepare on the ticket:**
+```markdown
+## Description
+Bug description: current behavior vs expected.
+
+## Acceptance Criteria
+- [ ] Bug no longer occurs
+- [ ] [Other specific conditions]
+
+## Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+3. Actual result: [what error, what screen]
+4. Expected result: [...]
+
+## Context
+Error log (if any), environment (browser, OS, app version).
+```
+
+**If reproduction steps are unclear:** AI will ask based on what it found in the code.
+
+**When satisfied with the requirement document, type:**
+```
+APPROVED
+```
+
+---
+
+## Step 2: Review Implementation Plan (Gate 2)
+
+AI generates:
+- TDD plan: write test to reproduce bug → implement fix → verify
+- Minimal fix approach (only edit the bug location)
+
+**When agreed, type:**
+```
+APPROVED
+```
+
+---
+
+## Step 3: AI Fix Code (Gate 3)
+
+AI performs in the following order:
+1. `superpowers:systematic-debugging` — confirm root cause
+2. `investigate-bug` skill — trace Controller→Service→Repository to identify the bug layer
+3. Write test to reproduce bug → run → confirm FAIL
+4. Implement fix → tests PASS
+5. Commit
+
+**Principle:** Minimal fix — only edit the bug location, no extra changes.
+
+---
+
+## Step 4: Review Summary (Gate 4)
+
+AI runs:
+1. `superpowers:verification-before-completion` — all tests PASS (including old tests)
+2. `impact-analysis` — fix doesn't cause new bugs elsewhere
+3. Create `plan/[ticket-id]/summary.md`
+
+**If OK, type:**
+```
+APPROVED
+```
+
+**If the fix is incorrect:**
+```
+BUG: [describe specifically what is wrong]
+```
+
+---
+
+## Step 5: Peer Review & PR (Gate 5)
+
+```bash
+git push origin fix/PROJ-33-description
+# PR title: fix: [PROJ-33] Short description
+```
+
+Commit message format:
+```
+fix: [PROJ-33] Payment processing timeout
+
+Root cause: API timeout too short (5s), needs at least 10s
+Fix: Increase timeout + add retry logic
+
+Closes PROJ-33
+```
+
+---
+
+## Completion Checklist
+
+- [ ] Gate 1 APPROVED — requirement doc with root cause, fix approach, impact, estimate
+- [ ] Gate 2 APPROVED — implementation plan confirmed
+- [ ] Gate 3 done — test reproduce bug + fix → green
+- [ ] Gate 4 APPROVED — no regression
+- [ ] Gate 5 done — PR merged