@relipa/ai-flow-kit 0.0.1

package/docs/architecture.md

@@ -0,0 +1,395 @@
+# AI Flow Kit Architecture
+
+This document explains how AI Flow Kit works and how to customize it for your team.
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   Developer                              │
+│              (runs aiflow commands)                      │
+└────────────────────┬────────────────────────────────────┘
+                     │
+        ┌────────────▼──────────────┐
+        │      CLI (bin/aiflow.js)  │
+        │  ├─ init                  │
+        │  ├─ use (load context)    │
+        │  ├─ prompt (generate)     │
+        │  ├─ detect (task type)    │
+        │  ├─ update                │
+        │  ├─ doctor                │
+        │  └─ validate              │
+        └────────────────┬──────────┘
+                         │
+        ┌────────────────┼──────────────────┐
+        │                │                  │
+   ┌────▼────┐   ┌──────▼──────┐   ┌───────▼──────┐
+   │ Scripts │   │ Adapters    │   │ Config       │
+   │ ├─ init │   │ ├─ jira     │   │ (.aiflowrc)  │
+   │ ├─ use  │   │ ├─ backlog  │   └──────────────┘
+   │ ├─ detect
+   │ ├─ context
+   │ └─ validate
+   └────┬────┘   │ └─ sheets   │
+        │        └─────┬──────┘
+        │              │
+   ┌────┴──────┬──────┴───┐
+   │            │          │
+┌──▼──┐  ┌──────▼──┐  ┌───▼────┐
+│.claude   │.rules  │  │.aiflow  │
+│          │        │  │(state)  │
+│├─skills  │├─code  │  └─────────┘
+│├─context ││  style│
+│└─prompts │├─naming│
+│          │└─review│
+└──────────└────────┘
+          ▲
+          │
+    ┌─────┴──────┐
+    │   Upstream │
+    │ (obra.dev) │
+    │   Skills   │
+    │ & Prompts  │
+    └────────────┘
+```
+
+## Key Components
+
+### 1. CLI (bin/aiflow.js)
+
+Entry point for all user commands. Routes to appropriate script.
+
+**Commands:**
+- `init` — Initialize project with skills and templates
+- `use` — Load context from ticket or file
+- `prompt` — Generate AI prompt with context
+- `detect` — Auto-detect task type from description
+- `update` — Update to latest version
+- `doctor` — Health check
+- `validate` — Validate AI output quality
+
+### 2. Configuration System
+
+Three levels of configuration:
+
+**Global** (`~/.claude/ai-flow-kit.json`)
+```json
+{
+  "defaultModel": "claude-opus-4-6",
+  "globalSkills": ["investigate-bug"]
+}
+```
+
+**Project** (`.aiflowrc.json`)
+```json
+{
+  "team": "engineering",
+  "adapters": ["jira"],
+  "frameworks": ["laravel"],
+  "autoDetectTasks": true
+}
+```
+
+**Local** (`.aiflow/state.json`)
+```json
+{
+  "current_version": "1.0.0",
+  "current_context": "JIRA-123"
+}
+```
+
+### 3. Skill System
+
+Skills are step-by-step instructions for AI workflows.
+
+**Upstream skills** (from obra/superpowers):
+- `brainstorming` — Explore ideas
+- `writing-plans` — Create implementation plans
+- `executing-plans` — Execute plans with checkpoints
+- `systematic-debugging` — Debug issues methodically
+- `test-driven-development` — TDD workflow
+- etc.
+
+**Custom skills** (in `custom/skills/`):
+- `investigate-bug` — Trace bugs through data flow
+- `impact-analysis` — Assess change scope
+- `generate-spec` — Create feature specifications
+- etc.
+
+Skills are merged during `aiflow init` and `aiflow update`.
+
+### 4. Task Detection
+
+Auto-classifies what the developer is doing:
+
+```
+Input: "Payment integration broken in checkout"
+  ↓
+Analysis:
+  - Contains: "broken" (bug indicator)
+  - Location: "checkout" (specific area)
+  - Type: Bug fix
+  ↓
+Output: "investigate-bug" skill
+```
+
+**Detection rules** (in `scripts/detect.js`):
+- Keywords: "bug", "error", "broken", "crash" → bug fix
+- Keywords: "add", "create", "build", "new" → feature
+- Keywords: "improve", "optimize", "refactor" → refactor
+- Keywords: "analyze", "investigate", "understand" → investigation
+
+### 5. Context System
+
+Stores task information for AI reference.
+
+**Structure:**
+```
+.claude/context/
+├── current.json        # Current task
+├── history/
+│   ├── JIRA-123.json
+│   ├── JIRA-124.json
+│   └── ...
+└── templates/
+    ├── bug-fix.json
+    ├── feature.json
+    └── ...
+```
+
+**Content:**
+```json
+{
+  "taskId": "JIRA-123",
+  "taskType": "bug-fix",
+  "title": "Payment processing fails",
+  "description": "Users see error...",
+  "acceptanceCriteria": ["...", "..."],
+  "context": {
+    "files": ["src/Payment.php"],
+    "services": ["PaymentService"],
+    "models": ["Transaction"],
+    "relatedTickets": ["JIRA-120", "JIRA-121"]
+  },
+  "metadata": {
+    "created": "2024-04-03T10:00:00Z",
+    "loadedFrom": "jira",
+    "adapter": "jira"
+  }
+}
+```
+
+### 6. MCP Adapter System
+
+Integrates with external tools (Jira, Backlog, etc).
+
+**How it works:**
+1. User runs: `aiflow use JIRA-123`
+2. CLI checks MCP config for `jira` server
+3. Calls Jira API via MCP to fetch issue
+4. Parses and stores in `context/current.json`
+5. Generates prompt with context
+
+**Adapters:**
+```json
+custom/mcp-presets/jira.json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-jira"],
+      "env": {
+        "JIRA_API_TOKEN": "{{API_TOKEN}}",
+        "JIRA_EMAIL": "{{EMAIL}}",
+        "JIRA_DOMAIN": "{{DOMAIN}}"
+      }
+    }
+  }
+}
+```
+
+### 7. Template System
+
+Pre-made structures for different task types and frameworks.
+
+**Prompt Templates** (`custom/prompts/`):
+- `bug-fix.md` — Template for bug fixing workflow
+- `feature.md` — Template for feature building
+- `investigation.md` — Template for code investigation
+- etc.
+
+**Framework Templates** (`custom/templates/`):
+- `laravel.md` — Laravel-specific rules and patterns
+- `nextjs.md` — Next.js specific rules
+- etc.
+
+## Data Flow Examples
+
+### Example 1: Load and Prompt
+
+```
+aiflow use JIRA-123
+  ↓
+[Load from MCP Adapter]
+  - Fetch issue from Jira
+  - Parse description, criteria
+  - Save to .claude/context/current.json
+  ↓
+aiflow prompt bug-fix
+  ↓
+[Generate Prompt]
+  - Read context from current.json
+  - Load bug-fix template
+  - Load laravel rules
+  - Merge all content
+  - Print to console (copy to Claude)
+  ↓
+Developer copies → Claude Code
+  ↓
+Claude runs appropriate skill (auto-detected)
+```
+
+### Example 2: Auto-Detection
+
+```
+Prompt: "We have users reporting that orders aren't saved"
+  ↓
+aiflow detect "We have users reporting that orders aren't saved"
+  ↓
+[Analysis]
+  Keywords: "orders aren't saved" (bug pattern)
+  Type: Bug fix
+  Confidence: 95%
+  ↓
+Output: Use "investigate-bug" skill
+  ↓
+Claude will follow:
+  1. Understand context
+  2. Trace data flow
+  3. Check git history
+  4. Propose solution
+```
+
+## Folder Structure
+
+```
+ai-flow-kit/
+├── bin/
+│   └── aiflow.js                 # CLI entry point
+│
+├── scripts/                      # Core functionality
+│   ├── init.js                   # Initialize project
+│   ├── update.js                 # Update version
+│   ├── use.js                    # Load context
+│   ├── detect.js                 # Detect task type
+│   ├── doctor.js                 # Health check
+│   ├── validate.js               # Validate output
+│   ├── context.js                # Context management
+│   ├── config.js                 # Config loader
+│   └── memory.js                 # Memory system
+│
+├── custom/                       # Team customizations
+│   ├── skills/                   # Custom skills
+│   │   ├── investigate-bug/
+│   │   ├── impact-analysis/
+│   │   ├── report-customer/
+│   │   └── generate-spec/
+│   ├── rules/                    # Team standards
+│   │   ├── code-style.md
+│   │   ├── naming.md
+│   │   └── review-checklist.md
+│   ├── templates/                # Framework rules
+│   │   ├── laravel.md
+│   │   ├── nextjs.md
+│   │   └── vue-nuxt.md
+│   ├── prompts/                  # Task templates
+│   │   ├── bug-fix.md
+│   │   ├── feature.md
+│   │   ├── investigation.md
+│   │   └── refactor.md
+│   └── mcp-presets/              # MCP configs
+│       ├── jira.json
+│       ├── backlog.json
+│       └── google-sheets.json
+│
+├── upstream/                     # Original obra/superpowers
+│   ├── skills/
+│   ├── agents/
+│   └── commands/
+│
+├── docs/                         # Documentation
+│   ├── architecture.md           # This file
+│   ├── getting-started.md
+│   ├── configuration.md
+│   ├── cli-reference.md
+│   ├── workflows/
+│   │   ├── bug-fix.md
+│   │   ├── feature.md
+│   │   ├── investigation.md
+│   │   └── refactor.md
+│   └── troubleshooting.md
+│
+├── package.json
+├── README.md
+├── CONTRIBUTING.md
+└── .gitignore
+```
+
+## Customization Points
+
+### Add a Custom Skill
+
+1. Create `custom/skills/my-skill/SKILL.md`
+2. Follow [skill format](../CONTRIBUTING.md#1-add-a-custom-skill)
+3. Run `aiflow update` to activate
+4. Skill appears in `.claude/skills/`
+
+### Add a Rule
+
+1. Create `custom/rules/my-rule.md`
+2. Describe the rule with examples
+3. Run `aiflow update`
+4. Rule appears in prompts via `aiflow prompt`
+
+### Add a Task Type
+
+1. Create `custom/prompts/my-task.md`
+2. Design template structure
+3. Run `aiflow update`
+4. Use with `aiflow prompt my-task`
+
+### Add Framework Support
+
+1. Create `custom/templates/my-framework.md`
+2. Define framework-specific rules
+3. Users can: `aiflow init --framework my-framework`
+
+## Extension Points
+
+The system is designed to extend:
+
+- **Custom skills:** Add domain-specific workflows
+- **Rules:** Add team standards and best practices
+- **Adapters:** Connect to more tools (Linear, GitHub, etc)
+- **Validators:** Check output quality
+- **Plugins:** Custom commands and functionality
+
+See [Contributing Guide](../CONTRIBUTING.md) for details.
+
+## Best Practices
+
+1. **Keep upstream separate** — Don't modify `upstream/`. Copy to `custom/` if needed.
+
+2. **Version your customizations** — Track `custom/` in git, not `upstream/`.
+
+3. **Document team rules** — Add to `custom/rules/`. Make them explicit.
+
+4. **Use configuration** — Store team settings in `.aiflowrc.json`.
+
+5. **Test before sharing** — Use `aiflow doctor` and test each contribution.
+
+6. **Share with team** — Version control makes updates easy: `git pull && aiflow update`.
+
+---
+
+**Understanding the architecture helps you customize AI Flow Kit for your team's needs!**