@relipa/ai-flow-kit 0.0.1

package/QUICK_START.md

@@ -0,0 +1,392 @@
+# Quick Start — AI Flow Kit
+
+> Full workflow: [AIFLOW.md](./AIFLOW.md) | Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+---
+
+## Installation
+
+```bash
+npm install -g ai-flow-kit
+aiflow --version
+```
+
+---
+
+## Project Setup (One-time)
+
+```bash
+cd your-project
+
+# Single framework + adapter
+aiflow init --framework spring-boot --adapter backlog
+
+# Or multiple
+aiflow init --framework spring-boot,reactjs --adapter backlog,jira
+```
+
+During init:
+- Enter `BACKLOG_API_KEY` and `BACKLOG_SPACE_KEY` when prompted
+- Press Enter to keep the old value (if previously set up)
+- The package automatically verifies credentials right after input
+
+Results after init:
+```
+✓ Superpowers skills ready (built-in)
+✓ Applied java rules
+✓ CLAUDE.md updated for framework: spring-boot
+✓ Credentials verified successfully
+✓ Superpowers SessionStart hook configured
+✨ Initialized AI Flow Kit successfully!
+```
+
+Check setup:
+```bash
+aiflow doctor
+```
+
+---
+
+## Complete Developer Workflow (Start → Finish)
+
+> **5-Gate workflow: Gate must pass in order. No skipping.**
+>
+> See [AIFLOW.md](./AIFLOW.md) for full details on each gate.
+
+### Step 1: Load ticket context
+
+```bash
+# Load from Backlog (description only)
+aiflow use PROJ-33
+
+# Load with comments (recommended for bug-fix)
+aiflow use PROJ-33 --with-comments
+
+# Load from Backlog URL
+aiflow use https://mycompany.backlog.com/view/PROJ-33
+
+# Load newest 5 comments
+aiflow use PROJ-33 --comments-last 5
+
+# Manual input (no Backlog/Jira)
+aiflow use --manual
+```
+
+Output:
+```
+✓ Context loaded
+
+  Ticket:   PROJ-33
+  Type:     bug-fix
+  Title:    [ticket title]
+  Status:   In Progress
+  Assignee: yourname
+```
+
+### Step 2: Open Claude — AI auto-starts
+
+```bash
+claude                        # AI auto-starts Gate 1 immediately
+```
+
+> **Note:** `aiflow prompt` is optional — only needed when pasting into Claude Desktop/Web.
+> In Claude Code CLI, the SessionStart hook auto-injects ticket context and triggers Gate 1.
+
+### Step 3: GATE 1 — AI Analyzes Requirement
+
+**What happens:** AI reads your ticket + source code + asks questions.
+
+When you open Claude, AI will **automatically** start analyzing:
+
+1. **Read ticket** from `.claude/context/current.json`
+2. **Read source code** — understand architecture, related files, data flow
+3. **Ask clarifying questions** (one at a time) if anything is unclear
+4. **Output** `plan/PROJ-33/requirement.md` containing:
+   - Requirements summary (AI's technical understanding)
+   - Source code analysis (related files, data flow, patterns)
+   - **Proposed solution** with recommendation
+   - **Impact analysis** — what areas are affected, risks
+   - **Effort estimate** (S/M/L/XL)
+   - Testing plan
+
+**Your action:** Review the requirement document.
+
+```
+# If satisfied:
+APPROVED
+
+# If something needs to change:
+"The solution should use Redis cache instead of in-memory"
+→ AI updates the document and asks again
+```
+
+### Step 4: GATE 2 — Review Implementation Plan
+
+**What happens:** AI creates a detailed coding plan based on the approved requirement.
+
+AI outputs:
+- TDD task breakdown (test first → implement → verify)
+- Commit strategy (small, focused commits)
+- Test commands
+
+**Your action:**
+
+```
+# If the plan looks good:
+APPROVED
+
+# If you want changes:
+"Split task 3 into smaller steps"
+→ AI adjusts the plan
+```
+
+### Step 5: GATE 3 — AI Generates Code (TDD)
+
+**What happens:** AI writes code following the approved plan.
+
+- Writes tests FIRST → runs → confirms FAIL
+- Implements code → tests PASS
+- Commits each small step
+
+**Your action:** Monitor. No action needed unless AI asks a question.
+
+### Step 6: GATE 4 — Review AI's Work
+
+**What happens:** AI self-reviews before showing you.
+
+AI runs automatically:
+1. `verification-before-completion` — all tests PASS
+2. `impact-analysis` — no breaking changes
+3. Review checklist — all items checked
+4. Creates `plan/PROJ-33/summary.md`
+
+Then shows you:
+```
+⏸️ GATE 4: WAITING FOR DEV REVIEW
+
+Tests: ✅ 12 passed
+Impact: 🟢 Low
+Checklist: 7/7 ✅
+Summary: plan/PROJ-33/summary.md
+```
+
+**Your action:**
+
+```
+# If everything is OK:
+APPROVED
+
+# If there's a bug in the code:
+BUG: The cache invalidation doesn't handle concurrent writes
+
+# If the requirement was wrong:
+BUG: Actually we need to support pagination, not just single page
+→ AI goes back to Gate 1 to update requirement
+```
+
+### Step 7: GATE 5 — Create PR & Peer Review
+
+**What happens:** AI helps create the Pull Request.
+
+```bash
+git push origin feature/PROJ-33-description
+# AI suggests PR title, description, and checklist
+```
+
+Ask a teammate to review. They can use `superpowers:receiving-code-review` skill.
+
+### Step 8: Done!
+
+After peer reviewer approves → merge → task complete.
+
+---
+
+## Workflow Summary Diagram
+
+```
+Developer                          AI                              Peer
+   │                                │                                │
+   │  aiflow use PROJ-33            │                                │
+   │  claude                        │                                │
+   │                                │                                │
+   │  ─── GATE 1 ──────────────────►│                                │
+   │                                │  Read ticket + source code     │
+   │                                │  Ask questions (1 at a time)   │
+   │  ◄─── requirement.md ─────────│                                │
+   │                                │                                │
+   │  "APPROVED" ──────────────────►│                                │
+   │                                │                                │
+   │  ─── GATE 2 ──────────────────►│                                │
+   │                                │  Create implementation plan    │
+   │  ◄─── plan ───────────────────│                                │
+   │                                │                                │
+   │  "APPROVED" ──────────────────►│                                │
+   │                                │                                │
+   │        GATE 3                  │  Write tests → implement       │
+   │        (monitor)               │  Commit each step              │
+   │                                │                                │
+   │  ─── GATE 4 ──────────────────►│                                │
+   │                                │  Self-review + summary         │
+   │  ◄─── summary.md ────────────│                                │
+   │                                │                                │
+   │  "APPROVED" ──────────────────►│                                │
+   │                                │                                │
+   │  ─── GATE 5 ─────────────────────────────────────────────────►│
+   │                                │                         Review PR
+   │  ◄──────────────────────────────────────────── APPROVED ──────│
+   │                                │                                │
+   │  Merge ✅                      │                                │
+```
+
+---
+
+## Use Cases
+
+### Bug Fix
+
+```bash
+aiflow use PROJ-33 --with-comments
+claude                                # AI auto-starts: analyze bug → trace root cause → propose fix
+```
+
+### New Feature
+
+```bash
+aiflow use PROJ-99
+claude                                # AI auto-starts: analyze requirements → propose architecture
+```
+
+### Investigation (no coding)
+
+```bash
+aiflow use PROJ-50
+claude                                # AI auto-starts: investigate → output findings report
+```
+
+### Refactoring
+
+```bash
+aiflow use PROJ-77
+claude                                # AI auto-starts: analyze impact → plan refactor steps
+```
+
+### Impact Analysis (no coding)
+
+```bash
+aiflow use PROJ-88
+claude                                # AI auto-starts: map dependencies → assess risk → output report
+```
+
+---
+
+## All Commands
+
+```bash
+# Setup
+aiflow init --framework spring-boot --adapter backlog
+aiflow doctor                         # health check
+aiflow update                         # update to latest version
+aiflow update --force                 # force update (same version)
+
+# Per task
+aiflow use PROJ-33                    # load ticket context
+aiflow use PROJ-33 --with-comments    # load with comments
+aiflow use PROJ-33 --comments-last 5  # newest 5 comments
+aiflow use --manual                   # manual input
+aiflow prompt bug-fix                 # generate prompt
+aiflow prompt feature --output p.md   # save prompt to file
+aiflow prompt --list                  # list all prompt types
+
+# Context management
+aiflow context show                   # view active context
+aiflow context list                   # list saved contexts
+aiflow context save my-snapshot       # save named snapshot
+aiflow context load my-snapshot       # load named snapshot
+aiflow context clear                  # clear active context
+
+# Team knowledge
+aiflow memory save "key" "value"      # save knowledge
+aiflow memory get "key"               # retrieve
+aiflow memory search "keyword"        # search
+aiflow memory list                    # list all
+
+# Utilities
+aiflow validate src/File.java         # validate code
+aiflow detect "description"           # detect task type
+aiflow guide                          # full quickstart guide
+aiflow guide --flow                   # architecture diagram
+aiflow guide --commands               # command reference
+
+# Maintenance
+aiflow remove                         # remove from project
+aiflow remove --global                # uninstall globally
+aiflow remove --version 1.0.0         # remove cached version
+```
+
+---
+
+## Documentation Files
+
+After installing `ai-flow-kit`, these docs are available:
+
+| File | Description |
+|------|-------------|
+| [QUICK_START.md](./QUICK_START.md) | This file — step-by-step guide for developers |
+| [AIFLOW.md](./AIFLOW.md) | Complete 5-Gate workflow: who does what, outputs, templates |
+| [README.md](./README.md) | Package overview, architecture, all features |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | How to add skills, templates, adapters, rules |
+| [IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md) | Technical implementation details |
+| [docs/workflows/](./docs/workflows/) | Per-task-type workflow guides |
+| [docs/architecture.md](./docs/architecture.md) | System architecture |
+| [docs/cli-reference.md](./docs/cli-reference.md) | CLI command reference |
+| [docs/configuration.md](./docs/configuration.md) | Configuration guide |
+| [docs/troubleshooting.md](./docs/troubleshooting.md) | Common issues & fixes |
+| [docs/getting-started.md](./docs/getting-started.md) | Getting started guide |
+
+Access docs after install:
+```bash
+# Docs are in the package directory
+npm root -g     # find global packages directory
+# → <path>/ai-flow-kit/AIFLOW.md, QUICK_START.md, etc.
+
+# Or use the built-in guide
+aiflow guide
+```
+
+---
+
+## Troubleshooting
+
+**`aiflow` not found:**
+```bash
+npm install -g ai-flow-kit
+```
+
+**Incorrect credentials:**
+```bash
+# Re-running will prompt again; press Enter to keep the old value
+aiflow init --adapter backlog
+```
+
+**Context not loading:**
+```bash
+# Check if credentials are saved
+cat .aiflow/credentials.json
+
+# Try loading again
+aiflow use PROJ-33
+```
+
+**Skills not working in Claude:**
+```bash
+# init must be run outside the Claude terminal (once)
+# Then reopen Claude
+aiflow doctor
+```
+
+**Need to see all available prompt types:**
+```bash
+aiflow prompt --list
+```
+
+See more: [docs/troubleshooting.md](./docs/troubleshooting.md)

package/README.md

@@ -0,0 +1,323 @@
+# AI Flow Kit
+
+**All-in-one package for software development teams using Claude AI.**
+
+Developers only need a single command to load ticket context → AI automatically understands the requirements, chooses the workflow, and follows team rules — no long prompts needed, no need to know the templates.
+
+---
+
+## Problems Solved
+
+| Problem | Solution |
+|--------|-----------|
+| Multi-step, complex installation | `aiflow init` — 1 command to set up everything |
+| Need long prompts for AI to understand | `aiflow use PROJ-33` — AI automatically reads from ticket |
+| Too many templates, not sure which to use | AI auto-detects task type and selects the appropriate skill |
+| New plugins (superpowers, MCP...) require manual setup | Package auto-sets up hooks, skills, and MCP on init |
+| Missing investigation / bug reproduction flow | Skill `investigate-bug` (inherits systematic-debugging) |
+| Missing impact analysis flow | Skill `impact-analysis` |
+
+---
+
+## Overview Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        TECH LEAD                                 │
+│  npm publish ai-flow-kit  →  developer: npm install -g          │
+└─────────────────────────────────┬───────────────────────────────┘
+                                  │
+                    ┌─────────────▼─────────────┐
+                    │      aiflow init           │
+                    │  --framework spring-boot   │
+                    │  --adapter backlog         │
+                    └─────────────┬─────────────┘
+                                  │ setup
+                    ┌─────────────▼──────────────────────────────┐
+                    │           Project                           │
+                    │  .claude/                                   │
+                    │  ├── skills/          ← superpowers + custom│
+                    │  ├── hooks/           ← SessionStart hook   │
+                    │  ├── settings.json    ← hook config         │
+                    │  └── context/         ← ticket context      │
+                    │  .rules/              ← team rules (java/)  │
+                    │  CLAUDE.md            ← framework template  │
+                    │  .mcp.json            ← MCP adapter config  │
+                    └─────────────┬──────────────────────────────┘
+                                  │
+               ┌──────────────────▼──────────────────┐
+               │          Developer workflow          │
+               │                                      │
+               │  1. aiflow use PROJ-33                │
+               │     └─ Pull title, description,      │
+               │        and comments from Backlog     │
+               │     └─ Save → .claude/context/       │
+               │                                      │
+               │  2. claude  (open Claude terminal)    │
+               │                                      │
+               │  3. "Fix bug PROJ-33"  (1 line)       │
+               └──────────────────┬──────────────────┘
+                                  │
+               ┌──────────────────▼──────────────────┐
+               │           Claude AI                  │
+               │                                      │
+               │  SessionStart hook injected          │
+               │  using-superpowers skill             │
+               │       ↓                              │
+               │  Read CLAUDE.md (spring-boot rules)  │
+               │       ↓                              │
+               │  Read context/current.json (PROJ-33) │
+               │       ↓                              │
+               │  Auto-detect: bug-fix task           │
+               │       ↓                              │
+               │  Invoke investigate-bug skill        │
+               │  → inherits systematic-debugging     │
+               │  → trace Controller→Service→Repo     │
+               │  → git blame to understand history   │
+               │  → propose minimal fix               │
+               │       ↓                              │
+               │  Invoke impact-analysis skill        │
+               │  → check breaking changes            │
+               └──────────────────┬──────────────────┘
+                                  │
+               ┌──────────────────▼──────────────────┐
+               │          Developer review            │
+               │  git diff → test → commit            │
+               └──────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+npm install -g ai-flow-kit
+```
+
+---
+
+## Commands
+
+### `aiflow init`
+
+Initial setup for the project. Run once per project.
+
+```bash
+# Single framework + adapter
+aiflow init --framework spring-boot --adapter backlog
+
+# Multiple frameworks and adapters
+aiflow init --framework spring-boot,reactjs --adapter backlog,jira
+```
+
+**What gets automatically set up:**
+- `.claude/skills/` — superpowers skills + team custom skills
+- `.claude/hooks/session-start.js` — SessionStart hook
+- `.claude/settings.json` — hook configuration
+- `.rules/` — team coding rules (based on framework language)
+- `CLAUDE.md` — framework-specific AI prompt
+- `.mcp.json` + Claude Desktop config — MCP adapter
+- `.aiflow/credentials.json` — save API credentials
+
+**Supported Frameworks:** `spring-boot`, `laravel`, `reactjs`, `nextjs`, `vue-nuxt`
+
+**Supported Adapters:** `backlog`, `jira`, `google-sheets`, `figma`
+
+---
+
+### `aiflow use <ticket>`
+
+Load ticket context into `.claude/context/current.json`.
+
+```bash
+# Backlog
+aiflow use PROJ-33
+aiflow use https://mycompany.backlog.com/view/PROJ-33
+
+# Jira
+aiflow use PROJ-123
+
+# Default: only load description
+aiflow use PROJ-33
+
+# Load with all comments
+aiflow use PROJ-33 --with-comments
+
+# Load newest 5 comments
+aiflow use PROJ-33 --comments-last 5
+
+# Load comments from index 3 onwards
+aiflow use PROJ-33 --comments-from 3
+
+# Manual input
+aiflow use --manual
+
+# Save with custom name
+aiflow use PROJ-33 --save sprint-42-bug
+```
+
+---
+
+### `aiflow doctor`
+
+Check if the setup is complete.
+
+```bash
+aiflow doctor
+```
+
+```
+✓ .claude/skills exists (42 skills)
+✓ .rules exists
+✓ CLAUDE.md exists
+✓ SessionStart hook configured
+✓ Version tracking active (v1.0.0)
+✨ Everything looks healthy!
+```
+
+---
+
+### `aiflow update`
+
+Update skills, rules, and templates to the latest version.
+
+```bash
+aiflow update
+```
+
+---
+
+### `aiflow validate <file>`
+
+Validate code output against team rules.
+
+```bash
+aiflow validate src/Payment.java --ruleset strict
+```
+
+---
+
+### `aiflow memory`
+
+Save/search team knowledge.
+
+```bash
+aiflow memory --save "payment-flow" "Payment flow description..."
+aiflow memory --search "payment"
+aiflow memory --list
+```
+
+---
+
+## Available Skills
+
+### Custom skills (team-specific)
+
+| Skill | Trigger | Description |
+|-------|---------|-------|
+| `investigate-bug` | "fix bug", "error", "crash" | Investigate bugs via data flow, inherits `systematic-debugging` |
+| `impact-analysis` | "impact scope", "breaking change" | Analyze the impact when changing code |
+| `generate-spec` | "new feature", "spec", "design" | Write technical specs, integrates `brainstorming` |
+| `report-customer` | "customer report", "incident" | Write incident reports for Customer Service |
+| `figma-to-component` | "figma", "design", "generate component" | Read Figma design → generate React/Next.js/Vue component |
+
+### Superpowers skills (upstream, inherited from obra/superpowers)
+
+| Skill | Description |
+|-------|-------|
+| `systematic-debugging` | Core debugging methodology — NO FIX WITHOUT ROOT CAUSE |
+| `brainstorming` | Explore requirements before coding |
+| `writing-plans` | Create bite-sized implementation plans |
+| `executing-plans` | Execute plans with review checkpoints |
+| `test-driven-development` | RED→GREEN→REFACTOR |
+| `subagent-driven-development` | Dispatch subagents for independent tasks |
+| `requesting-code-review` | Review code before merging |
+| `verification-before-completion` | Verify before claiming done |
+| `using-git-worktrees` | Isolated workspace for feature work |
+| `finishing-a-development-branch` | Complete branch and merge options |
+
+---
+
+## Framework Templates
+
+| Framework | Language | Rules applied |
+|-----------|---------|--------------|
+| `spring-boot` | Java 17+ | `rules/java/` |
+| `laravel` | PHP 8.1+ | `rules/php/` |
+| `reactjs` | TypeScript | `rules/javascript/` |
+| `nextjs` | TypeScript | `rules/javascript/` |
+| `vue-nuxt` | TypeScript | `rules/javascript/` |
+
+---
+
+## Project Structure
+
+```
+ai-flow-kit/
+├── bin/aiflow.js                    # CLI entry
+├── scripts/
+│   ├── init.js                      # Project initialization
+│   ├── update.js                    # Version management
+│   ├── doctor.js                    # Health check
+│   ├── use.js                       # Context loading (Backlog/Jira)
+│   ├── config.js                    # Config system
+│   ├── detect.js                    # Task type detection
+│   ├── validate.js                  # Code validation
+│   ├── memory.js                    # Knowledge management
+│   └── hooks/session-start.js       # SessionStart hook (Node.js)
+├── custom/
+│   ├── skills/                      # Team-specific AI skills
+│   ├── rules/java/                  # Java/Spring Boot rules
+│   ├── rules/php/                   # PHP/Laravel rules
+│   ├── rules/javascript/            # JS/TS rules
+│   ├── templates/                   # Framework CLAUDE.md templates
+│   ├── prompts/                     # Task prompt templates
+│   └── mcp-presets/                 # Backlog/Jira/Sheets config
+└── upstream/                        # obra/superpowers (inherited)
+```
+
+---
+
+## Adding new frameworks / adapters
+
+**New Framework:** create `custom/templates/<name>.md` + `custom/rules/<lang>/`
+
+**New Adapter:** create `custom/mcp-presets/<name>.json`
+
+**Custom skill:** create `custom/skills/<name>/SKILL.md`
+
+Then run `aiflow update` to apply.
+
+---
+
+## Usage Environments
+
+| Environment | Experience | Notes |
+|-----------|------------|---------|
+| Claude Code CLI (`claude`) | ⭐⭐⭐⭐⭐ | Full auto — skills, hook, automatically loaded context |
+| Claude Extension (VS Code) | ⭐⭐⭐ | `aiflow prompt <type>` → copy paste |
+| Antigravity / Cursor | ⭐⭐⭐ | `aiflow prompt <type>` → copy paste |
+
+---
+
+## Troubleshooting
+
+**`aiflow` not found:**
+```bash
+npm install -g ai-flow-kit
+```
+
+**Backlog load fails:**
+```bash
+aiflow doctor
+# Re-setup credentials
+aiflow init --adapter backlog
+```
+
+**Skills not loading in Claude:**
+```bash
+# Ensure init was run outside Claude terminal (session-start hook needs restart)
+aiflow doctor
+```
+
+See more: [docs/troubleshooting.md](./docs/troubleshooting.md)