@relipa/ai-flow-kit 0.0.1

package/AIFLOW.md

@@ -0,0 +1,432 @@
+# AIFLOW — Software Development Workflow with AI
+
+**Version:** 2.0.0 | **Package:** ai-flow-kit
+
+> This workflow applies to all tasks: feature, bug-fix, refactor, investigation.
+> **Absolute Rule: Complete Gate N → Only then can you enter Gate N+1. No exceptions.**
+
+---
+
+## Workflow Overview
+
+```
+PM writes ticket on Backlog/Jira
+        │
+        ▼
+⛩️ GATE 1 — AI Analyze Requirement          [AI + DEV]
+  AI loads ticket + reads source code
+  AI asks clarifying questions until clear
+  AI outputs: requirement.md
+    (requirements, solution, impact analysis, estimate)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Implementation Plan             [AI + DEV]
+  AI creates detailed coding plan (TDD steps)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 3 — Code Generation (TDD)           [AI]
+  AI writes tests first → implement → tests pass
+  Commit each small step
+        │ Code done
+        ▼
+⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
+  AI runs: verification + impact-analysis + checklist
+  AI generates summary report
+  DEV reviews → "APPROVED" or "BUG: [description]"
+        │ APPROVED
+        ▼
+⛩️ GATE 5 — Peer Review & PR                [DEV + Peer]
+  requesting-code-review skill
+  Create Pull Request → merge
+        │
+        ▼
+       DONE
+```
+
+---
+
+## Roles
+
+| Role | Responsibility |
+|------|---------------|
+| **PM** | Write ticket on Backlog/Jira with description, acceptance criteria, context |
+| **DEV** | Trigger workflow, review AI outputs at each gate, type APPROVED or provide feedback |
+| **AI** | Analyze requirements, propose solutions, generate code (TDD), self-review |
+
+---
+
+## Gate Details
+
+---
+
+### ⛩️ GATE 1 — AI Analyze Requirement
+
+**Who performs:** AI (analyze) + DEV (review & approve)
+
+**Trigger:**
+```bash
+aiflow use PROJ-33              # load ticket from Backlog/Jira
+claude                           # open Claude → AI auto-starts Gate 1
+```
+
+> `aiflow prompt` is optional — use it only when pasting into Claude Desktop/Web.
+> In Claude Code CLI, AI auto-starts Gate 1 via SessionStart hook.
+
+**What AI does (in order):**
+
+| Step | Action | Purpose |
+|------|--------|---------|
+| 1 | Load ticket from `.claude/context/current.json` | Get PM's requirements, comments |
+| 2 | Read `CLAUDE.md` + source code | Understand architecture, tech stack, patterns |
+| 3 | Investigate related files & data flow | Identify affected areas, dependencies |
+| 4 | Ask clarifying questions (one at a time) | Ensure full understanding |
+| 5 | Write `plan/[ticket-id]/requirement.md` | Structured requirement document |
+
+**AI asks questions when:**
+- Business requirements are vague or ambiguous
+- Acceptance criteria are not measurable
+- Edge cases are discovered in source code
+- Multiple approaches are possible and need input
+- Impact on existing features is unclear
+
+**Requirement Document Output (`plan/[ticket-id]/requirement.md`):**
+
+```
+├── 1. Requirements Summary
+│   ├── Description (AI's understanding in technical language)
+│   ├── Current behavior / Business goal
+│   ├── Acceptance Criteria (refined, measurable)
+│   └── Context & Constraints
+├── 2. Source Code Analysis
+│   ├── Related files & their roles
+│   ├── Data flow diagram
+│   ├── Existing patterns to follow
+│   └── Current test coverage
+├── 3. Proposed Solution & Approach
+│   ├── Option A (recommended) — pros/cons
+│   ├── Option B (alternative) — pros/cons
+│   ├── Chosen approach & rationale
+│   ├── Files to create/modify
+│   └── Database changes (if any)
+├── 4. Impact Analysis
+│   ├── Impact level (Low/Medium/High)
+│   ├── Affected areas
+│   ├── Breaking changes
+│   └── Risks & mitigations
+├── 5. Effort Estimate
+│   ├── Task breakdown with size (S/M/L/XL)
+│   └── Sub-task split for XL tasks
+└── 6. Testing Plan
+    ├── Unit tests
+    ├── Integration tests
+    └── Manual test cases
+```
+
+**Gate 1 Display:**
+
+```
+⏸️ GATE 1: REQUIREMENT DOCUMENT READY
+
+Summary:
+- Type: [feature / bug-fix / refactor]
+- Impact: [Low / Medium / High]
+- Estimate: [S / M / L / XL]
+- Approach: [brief description]
+- Files affected: [N] files
+
+→ Review: plan/[ticket-id]/requirement.md
+→ Type APPROVED to proceed
+→ Or provide feedback to update
+```
+
+**Gate 1 Output:**
+- `plan/[ticket-id]/requirement.md` approved by DEV
+- DEV has typed "APPROVED"
+
+---
+
+### ⛩️ GATE 2 — Implementation Plan
+
+**Who performs:** AI (create plan) + DEV (review & approve)
+
+**What AI does:**
+
+1. Read the approved requirement document
+2. **Invoke** `superpowers:writing-plans` → create detailed implementation plan
+3. Break down into TDD tasks: test first → implement → verify
+4. Define commit strategy (small, focused commits)
+5. Present plan and wait for APPROVED
+
+**Implementation Plan Structure:**
+
+```
+├── Task Breakdown (TDD Order)
+│   ├── Task 1: Write test for [scenario]
+│   ├── Task 2: Implement [component]
+│   ├── Task 3: Write test for [next scenario]
+│   └── ...
+├── Commit Strategy
+└── Test Commands
+```
+
+**Gate 2 Display:**
+
+```
+⏸️ GATE 2: IMPLEMENTATION PLAN READY
+
+Tasks: [N] | Commits: [N] | Test-first tasks: [N]
+
+→ Type APPROVED to start coding
+→ Or provide feedback to adjust
+```
+
+**Gate 2 Output:**
+- Implementation plan approved by DEV
+- DEV has typed "APPROVED"
+
+---
+
+### ⛩️ GATE 3 — Code Generation
+
+**Who performs:** AI
+
+**Only runs after Gate 2 APPROVED.**
+
+**Mandatory Order:**
+
+#### Feature task:
+1. Complex feature (3+ files) → `superpowers:subagent-driven-development`
+2. `superpowers:test-driven-development` — write tests FIRST
+3. Run tests → confirm FAIL
+4. Implement code → tests PASS
+5. Commit each small step
+
+#### Bug fix task (extra):
+1. `superpowers:systematic-debugging` — trace root cause, NO guessing
+2. `investigate-bug` skill — trace Controller→Service→Repository
+3. Then TDD: write test to reproduce bug → fix → tests PASS
+
+#### Refactor task (extra):
+1. Ensure tests cover current behavior
+2. Refactor in small steps — keep tests green continuously
+
+**Gate 3 Output:**
+- Code implementation finished
+- All tests PASS
+- Committed
+
+---
+
+### ⛩️ GATE 4 — AI Self-Review
+
+**Who performs:** AI (self-review) + DEV (final approve)
+
+**AI runs in mandatory order:**
+
+| Step | Action | Required Result |
+|------|--------|------------|
+| 1 | `superpowers:verification-before-completion` | All tests PASS |
+| 2 | `impact-analysis` skill | No breaking changes outside scope |
+| 3 | `custom/rules/review-checklist.md` | All items ticked |
+| 4 | Create `plan/[ticket-id]/summary.md` | File exists and is complete |
+
+**If any step fails → AI fixes it first, without showing DEV.**
+
+**Summary report output:**
+
+```
+plan/[ticket-id]/summary.md
+├── List of changed files + reasons
+├── Acceptance Criteria → results (Done/Not Done)
+├── Tests: quantity, coverage
+├── Impact Analysis: level (Low/Medium/High)
+└── Review Checklist: N/N items ✅
+```
+
+**Gate 4 Display:**
+```
+⏸️ GATE 4: WAITING FOR DEV REVIEW
+
+Tests: ✅ [N] passed
+Impact: [Low/Medium/High]
+Checklist: [N/N] ✅
+Summary: plan/[ticket-id]/summary.md
+
+Type APPROVED if OK
+Type BUG: [description] if there are issues
+```
+
+**DEV Response:**
+- `APPROVED` → move to Gate 5
+- `BUG: coding bug` → AI fixes → repeat Gate 4
+- `BUG: requirement bug` → AI updates requirement doc → back to Gate 1
+
+**Gate 4 Output:**
+- `plan/[ticket-id]/summary.md` completed
+- DEV has typed "APPROVED"
+
+---
+
+### ⛩️ GATE 5 — Peer Review & Pull Request
+
+**Who performs:** DEV + Peer reviewer
+
+**Only runs after Gate 4 APPROVED.**
+
+**AI invokes:** `superpowers:requesting-code-review`
+
+**AI guides PR creation:**
+
+```markdown
+## Pull Request Template
+
+**Title:** [feat/fix/refactor]: [PROJ-XX] [Short description]
+
+**Description:**
+Closes [PROJ-XX]
+
+### Changes
+- [File A] — [what changed]
+- [File B] — [what changed]
+
+### Acceptance Criteria
+- [x] [Criteria 1]
+- [x] [Criteria 2]
+
+### Testing
+- Unit tests: [N] cases
+- Integration tests: [N] cases
+- Manual test: [tested manually?]
+
+### Impact
+[Low/Medium/High] — [short description]
+
+### Reviewer notes
+[Anything special for the reviewer to notice]
+```
+
+**Peer reviewer checks:**
+- Code logic matches requirement document
+- Tests are sufficient and meaningful
+- No security issues
+- Acceptable performance
+- Follows team conventions
+
+**Gate 5 Output:**
+- PR created with full description
+- Peer reviewer APPROVED
+- Merged into main/develop
+
+---
+
+## Workflow by Task Type
+
+### Bug Fix
+```
+Gate 1 (AI analyzes bug: root cause hypothesis + solution + impact + estimate)
+→ Gate 2 (implementation plan: test reproduce bug → fix → verify)
+→ Gate 3 (systematic-debugging + investigate-bug + TDD fix)
+→ Gate 4 (verify fix + no regression)
+→ Gate 5 (peer review + PR)
+```
+
+### Feature
+```
+Gate 1 (AI analyzes feature: architecture + solution options + impact + estimate)
+→ Gate 2 (implementation plan: TDD task breakdown)
+→ Gate 3 (TDD: test first, implement, subagent if complex)
+→ Gate 4 (verify all AC done + impact check)
+→ Gate 5 (peer review + PR)
+```
+
+### Investigation
+```
+Gate 1 (AI investigates: analyze scope, trace code, document findings + recommendations)
+→ DEV reviews → APPROVED
+→ DONE (no Gates 2-5, create new ticket if action needed)
+```
+
+### Refactor
+```
+Gate 1 (AI analyzes: current state, target state, impact + estimate)
+→ Gate 2 (implementation plan: ensure tests cover behavior → refactor steps)
+→ Gate 3 (TDD: cover behavior → refactor → tests green)
+→ Gate 4 (verify no regressions)
+→ Gate 5 (peer review + PR)
+```
+
+### Impact Analysis
+```
+Gate 1 (AI analyzes: dependency map, risk level, breaking changes, recommendations)
+→ DEV reviews → APPROVED
+→ DONE (no Gates 2-5, implementation needs a separate ticket)
+```
+
+---
+
+## Skills Used in Workflow
+
+| Skill | Gate | Purpose |
+|-------|------|---------|
+| `validate-ticket` | Gate 1 | AI reads, analyzes, asks questions, outputs requirement doc |
+| `superpowers:brainstorming` | Gate 1 | Explore solution approaches for complex problems |
+| `superpowers:systematic-debugging` | Gate 1 (bug) | Trace root cause hypothesis |
+| `generate-spec` | Gate 2 | Create implementation plan |
+| `superpowers:writing-plans` | Gate 2 | Detailed TDD task breakdown |
+| `investigate-bug` | Gate 3 (bug) | Trace data flow per framework |
+| `superpowers:test-driven-development` | Gate 3 | TDD workflow |
+| `superpowers:subagent-driven-development` | Gate 3 (complex) | Parallel implementation |
+| `review-plan` | Gate 4 | Orchestrate self-review |
+| `superpowers:verification-before-completion` | Gate 4 | Verify tests pass |
+| `impact-analysis` | Gate 4 | Check breaking changes |
+| `superpowers:requesting-code-review` | Gate 5 | Peer review workflow |
+
+---
+
+## Commands Reference
+
+```bash
+# Setup (once per project)
+aiflow init --framework spring-boot --adapter backlog
+
+# Per task (2 commands only)
+aiflow use PROJ-33                    # load ticket context
+claude                                # AI auto-starts Gate 1
+
+# Optional: generate prompt for Claude Desktop/Web
+aiflow prompt bug-fix                 # generate prompt to paste
+aiflow prompt feature --output p.md   # save prompt to file
+
+# Utilities
+aiflow context show                   # view active context
+aiflow memory save "key" "value"      # save team knowledge
+aiflow doctor                         # health check
+aiflow guide                          # view quickstart guide
+```
+
+---
+
+## FAQ
+
+**Q: PM didn't write enough on the ticket, what happens?**
+A: AI at Gate 1 will read what's available, then ask clarifying questions one at a time until the requirement is clear enough to propose a solution.
+
+**Q: Does AI just check format or actually understand the requirement?**
+A: AI actively reads source code, traces data flow, identifies related files, and proposes solutions. It asks questions based on what it finds in the code — not just checking if fields exist.
+
+**Q: Can I skip Gate 2 for simple tasks?**
+A: No. Gate 2 can be brief (simple plan), but DEV must still type "APPROVED" to confirm the approach.
+
+**Q: AI reports test failures at Gate 4, what to do?**
+A: AI will try to fix them before showing DEV. If it can't, it will report the reason and ask for DEV's support.
+
+**Q: What's the difference between a requirement bug and a coding bug?**
+A: Requirement bug = wrong/missing in requirement doc → back to Gate 1. Coding bug = wrong code but correct requirement → fix at Gate 4.
+
+**Q: Who performs peer review (Gate 5)?**
+A: Another developer in the team. Not the code author. The reviewer uses the `superpowers:receiving-code-review` skill.
+
+**Q: How does AI estimate effort?**
+A: AI analyzes the scope of changes (files affected, complexity, test requirements) and categorizes: S (< 1h), M (1-4h), L (4-8h), XL (8h+, should split).

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to **ai-flow-kit** will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+> Changes that are merged but not yet released.
+
+---
+
+## [0.0.1] - 2026-04-13 — Initial Release
+
+### Added
+
+#### CLI (`aiflow`)
+- `aiflow init` — scaffold AI workflow config into any project
+  (supports `--framework` spring-boot/reactjs, `--adapter` jira/backlog)
+- `aiflow use <skill>` — activate a custom skill in the current project
+- `aiflow remove` — cleanly remove `ai-flow-kit` scaffolding from a project
+- `aiflow guide` — interactive onboarding guide
+- `aiflow update` — sync upstream skill/hook updates
+- `aiflow doctor` — validate config, detect missing keys, report issues
+- `aiflow --version` — print installed version
+
+#### 5-Gate AI Workflow
+- **Gate 1 — AI Analyze Requirement**: Auto-starts when a ticket context exists
+  in `.claude/context/current.json`; outputs `plan/[ticket-id]/requirement.md`
+- **Gate 2 — Implementation Plan**: TDD plan generation, gated by `APPROVED`
+- **Gate 3 — Code Generation**: TDD-only, test-first discipline enforced
+- **Gate 4 — AI Self-Review**: Verification + impact analysis + checklist, gated by `APPROVED`
+- **Gate 5 — Peer Review & PR**: Guided PR creation via `requesting-code-review` skill
+
+#### Custom Skills (7 skills)
+- `validate-ticket` — Gate 1 requirement analysis with clarifying Q&A loop
+- `generate-spec` — Gate 2 TDD implementation spec generator
+- `impact-analysis` — breaking-change and dependency impact assessment
+- `investigate-bug` — systematic bug investigation (reproduce → root cause → fix)
+- `report-customer` — customer-facing incident report generator
+- `review-plan` — Gate 4 self-review orchestrator
+- `figma-to-component` — Figma design → UI component code generator
+
+#### Multi-AI Support
+- **Claude Code** integration via `CLAUDE.md` + `.claude/` directory structure
+- **Gemini CLI** integration via `GEMINI.md`
+- **GitHub Copilot** integration via agents config
+- Superpowers skill library bundled as `upstream/` (pinned to v5.0.5)
+
+#### Project Templates
+- `AIFLOW.md` — team workflow reference document
+- `QUICK_START.md` — 5-minute setup guide
+- `CONTRIBUTING.md` — contributor guide
+- `.aiflowrc.json.example` — configuration file reference
+
+### Architecture Notes
+- Stateless per-ticket design — no persistent memory across sessions (planned: v0.1.x)
+- Manual skill sync model via `aiflow use` (managed `aiflow skill` CLI planned: v0.1.x)
+- Spring Boot (Java 17+) used as the reference framework in `CLAUDE.md` coding rules
+
+---
+
+## How to upgrade
+
+```bash
+npm install -g ai-flow-kit@latest
+aiflow --version
+```
+
+After upgrading, run `aiflow update` inside your project to sync the latest skills and hooks:
+
+```bash
+cd your-project
+aiflow update
+```