@relipa/ai-flow-kit 0.0.5-beta.0 → 0.0.5-beta.1

package/README.md

@@ -21,13 +21,13 @@ Developers only need a single command to load ticket context → AI automaticall
 ## Documentation & Guides
 
 > [!TIP]
-> After running `aiflow init`, all documentation files are automatically copied to your project root and `.aiflow/docs/` for easy access.
+> After running `aiflow init`, documentation files are automatically copied to `.aiflow/docs/` in your project for easy access.
 
-- **[Quick Start Guide](./docs/QUICK_START.md)** — Step-by-step instructions for developers.
-- **[Full Workflow (5 Gates)](./docs/AIFLOW.md)** — In-depth look at the Gate process.
-- **[Developer Onboarding](./docs/developer-overview.md)** — Presentation-ready guide for new team members.
-- **[Troubleshooting](./docs/troubleshooting.md)** — Common issues and fixes.
-- **[Integration Guide](./docs/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Quick Start Guide](./docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
+- **[Full Workflow (5 Gates)](./docs/common/AIFLOW.md)** — In-depth look at the Gate process.
+- **[Troubleshooting](./docs/common/troubleshooting.md)** — Common issues and fixes.
+- **[Integration Guide](./docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Changelog](./docs/common/CHANGELOG.md)** — Version history and release notes.
 
 ---
 
@@ -50,8 +50,10 @@ Developers only need a single command to load ticket context → AI automaticall
                     │  .claude/                                   │
                     │  ├── skills/          ← superpowers + custom│
                     │  ├── hooks/           ← SessionStart hook   │
-                    │  ├── settings.json    ← hook config         │
-                    │  └── context/         ← ticket context      │
+                    │  └── settings.json    ← hook config         │
+                    │  .aiflow/                                   │
+                    │  ├── context/         ← ticket context      │
+                    │  └── versions/        ← versioned skills    │
                     │  .rules/              ← team rules (java/)  │
                     │  CLAUDE.md            ← framework template  │
                     │  .mcp.json            ← MCP adapter config  │
@@ -229,9 +231,9 @@ aiflow validate src/Payment.java --ruleset strict
 Save/search team knowledge.
 
 ```bash
-aiflow memory --save "payment-flow" "Payment flow description..."
-aiflow memory --search "payment"
-aiflow memory --list
+aiflow memory save "payment-flow" "Payment flow description..."
+aiflow memory search "payment"
+aiflow memory list
 ```
 
 ---
@@ -283,11 +285,15 @@ aiflow memory --list
 ai-flow-kit/
 ├── README.md                        # Main documentation
 ├── bin/aiflow.js                    # CLI entry
-├── docs/                            # Documentation and Guides
-│   ├── QUICK_START.md               # Quick start guide
-│   ├── AIFLOW.md                    # Workflow (5 Gates) detail
-│   ├── CHANGELOG.md                 # Version history
-│   └── ...                          # Other guides
+├── docs/
+│   ├── common/                      # Published with package
+│   │   ├── QUICK_START.md           # Quick start guide
+│   │   ├── AIFLOW.md                # Workflow (5 Gates) detail
+│   │   ├── CHANGELOG.md             # Version history
+│   │   ├── cli-reference.md         # Full CLI reference
+│   │   └── workflows/               # Per-task workflow guides
+│   └── project/                     # Project template files
+│       └── ARCHITECTURE.md          # Architecture doc template
 ├── scripts/
 │   ├── init.js                      # Project initialization
 │   ├── update.js                    # Version management
@@ -353,4 +359,4 @@ aiflow init --adapter backlog
 aiflow doctor
 ```
 
-See more: [docs/troubleshooting.md](./docs/troubleshooting.md)
+See more: [docs/common/troubleshooting.md](./docs/common/troubleshooting.md)

package/custom/skills/{validate-ticket → read-study-requirement}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: validate-ticket
-description: Gate 1 — AI reads ticket from Backlog/Jira + reads source code, then uses superpowers:brainstorming for collaborative Q&A and solution proposal. Adds impact analysis and effort estimate. Outputs requirement.md for DEV to approve.
-keywords: ticket, validate, context, requirement, backlog, jira, analyze, understand, solution, estimate
+name: read-study-requirement
+description: Gate 1 — AI reads ticket from Backlog/Jira + reads source code, then uses collaborative Q&A and solution proposal. Adds impact analysis and effort estimate. Outputs requirement.md for DEV to approve.
+keywords: ticket, requirement, study, read, context, backlog, jira, analyze, understand, solution, estimate
 ---
 
 # Analyze Requirement — Gate 1
@@ -19,31 +19,40 @@ keywords: ticket, validate, context, requirement, backlog, jira, analyze, unders
 1. Read `.aiflow/context/current.json` — ticket info from Backlog/Jira
 2. Read `CLAUDE.md` — understand project architecture, tech stack, conventions
 3. Read related source files — trace data flow, identify patterns, dependencies
+   - **If task is a Bug Fix:** Invoke `superpowers:systematic-debugging` to trace root cause before proposing fixes.
 4. Read ticket comments — additional context from PM/team
 
 Do this investigation **before** asking any questions. Come prepared.
 
 ---
 
-### Step 2: Clarify Requirements via Brainstorming
+### Step 2: Clarify Requirements via Q&A
 
-**INVOKE: `superpowers:brainstorming`**
+Ask clarifying questions directly — **one question at a time**, wait for the developer's response before asking the next.
 
-Use brainstorming's collaborative Q&A process to:
-- Ask clarifying questions **one at a time** — never batch multiple questions
-- Understand purpose, constraints, and success criteria from the developer
-- Propose **2–3 solution approaches** with trade-offs and a recommendation
-- Present the proposed design and get developer confirmation
+**When to ask:**
+- Business requirements are vague or ambiguous
+- Acceptance criteria are not measurable
+- Edge cases discovered in source code need input
+- Multiple approaches exist and the developer's preference matters
 
-Brainstorming handles the full Q&A loop automatically. Let it run until the developer has confirmed the design direction.
+**When NOT to ask:**
+- The ticket and source code together make the intent clear → proceed directly
 
-**Do NOT proceed to Step 3 until brainstorming confirms the design is approved.**
+Once you have sufficient clarity, propose **2–3 solution approaches** with trade-offs and a recommendation:
+- Present options conversationally, lead with your recommendation
+- Get developer confirmation on the chosen approach
+
+**Do NOT proceed to Step 3 until the developer has confirmed the design direction.**
+
+> ⚠️ **DO NOT invoke `superpowers:brainstorming`** — brainstorming's terminal state invokes
+> `writing-plans` (Gate 2), which would bypass Gate 1's approval gate. All Q&A happens here.
 
 ---
 
 ### Step 3: Extend with Impact Analysis & Effort Estimate
 
-After brainstorming completes, add what brainstorming does not cover:
+After the developer confirms the design direction (Step 2), extend with:
 
 **Impact Analysis:**
 - Which services, modules, and jobs are affected?
@@ -219,8 +228,8 @@ Please review the requirement document.
 
 | Concern | Handled by |
 |---------|-----------|
-| Q&A loop (one question at a time) | `superpowers:brainstorming` |
-| Propose 2–3 solution approaches | `superpowers:brainstorming` |
+| Q&A loop (one question at a time) | This skill (inline) |
+| Propose 2–3 solution approaches | This skill (inline) |
 | Root cause tracing (bug tasks) | `superpowers:systematic-debugging` |
 | Impact analysis | This skill |
 | Effort estimate | This skill |
@@ -231,10 +240,11 @@ Please review the requirement document.
 
 ## Mandatory Rules
 
-- ❌ **DO NOT** skip invoking `superpowers:brainstorming` — it owns the Q&A loop
+- ❌ **DO NOT** invoke `superpowers:brainstorming` — its terminal state calls `writing-plans` and bypasses Gate 1 approval
+- ❌ **DO NOT** invoke `superpowers:writing-plans` — that belongs to Gate 2 (`generate-spec` skill)
 - ❌ **DO NOT** proceed past Step 2 if design is not confirmed by developer
 - ❌ **DO NOT** write code at any point in this skill
 - ❌ **DO NOT** skip impact analysis and effort estimate
-- ✅ **MUST** read source code before brainstorming begins
+- ✅ **MUST** read source code before Q&A begins
 - ✅ **MUST** save `plan/[ticket-id]/requirement.md`
 - ✅ **MUST** display Gate 1 prompt and wait for `APPROVED`

package/custom/skills/review-plan/SKILL.md

@@ -128,7 +128,7 @@ Summary: plan/[ticket-id]/summary.md
 
 ✅ If OK: type **"APPROVED"**
 🐛 If there are bugs: type **"BUG: [description]"**
-   → If a requirement bug: I will return to Gate 2
+   → If a requirement bug: I will return to Gate 1
    → If a coding bug: I will fix and repeat Gate 4
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```

package/custom/templates/shared/gate-workflow.md

@@ -1,88 +1,88 @@
-## MANDATORY: Strict Gate Workflow
-
-> **Absolute Rule: Complete Gate N before entering Gate N+1.**
-> **Do not skip, shorten, or merge Gates.**
-
-You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
-- **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
-- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
-- Read instructions and follow the gate sequence below — NO EXCEPTIONS.
-
----
-
-### GATE 1 — AI Analyze Requirement (auto-start)
-
-**INVOKE:** `validate-ticket` skill
-
-AI actively reads ticket + source code to understand the requirement:
-1. Read `.aiflow/context/current.json` — ticket info
-2. Read source code — architecture, related files, data flow
-3. If anything is unclear — ask ONE question at a time, wait for reply
-4. Output `plan/[ticket-id]/requirement.md` with:
-   - Requirements summary, source code analysis
-   - Proposed solution and approach
-   - Impact analysis, effort estimate, testing plan
-5. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
-
-> **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
-
-DO NOT just check format — **understand the content and propose solutions**.
-
-> **Telemetry:** Run `aiflow gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1").
-> Run `aiflow gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
-
----
-
-### GATE 2 — Implementation Plan (wait for APPROVED)
-
-**INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
-
-- Create a detailed TDD implementation plan based on the approved requirement.
-- Display: "GATE 2 PAUSED: type APPROVED to start coding".
-- CODE WILL NOT BE GENERATED until "APPROVED" is received.
-
-> **Telemetry:** Run `aiflow gate 2 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
-
----
-
-### GATE 3 — Code Generation (TDD only)
-
-Only runs after Gate 2 has been APPROVED.
-
-**INVOKE:** `superpowers:test-driven-development`
-- Complex feature (3+ files): `superpowers:subagent-driven-development`
-- Write tests FIRST — run to confirm FAIL -> implement -> PASS.
-- Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
-
-> **Telemetry:** Run `aiflow gate 3 start --ticket [ticket-id]` when starting this gate.
-
----
-
-### GATE 4 — AI Self-Review (wait for APPROVED)
-
-**INVOKE:** `review-plan` skill
-
-Mandatory order:
-1. `superpowers:verification-before-completion` — all tests must PASS
-2. `impact-analysis` skill — check for breaking changes
-3. Tick `custom/rules/review-checklist.md`
-4. Create `plan/[ticket-id]/summary.md`
-
-Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
-- Coding bug -> fix -> repeat Gate 4.
-- Requirement bug -> return to Gate 1.
-
-> **Telemetry:** Run `aiflow gate 4 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
-
----
-
-### GATE 5 — Peer Review and Done
-
-Only runs after Gate 4 has been APPROVED.
-
-**INVOKE:** `superpowers:requesting-code-review`
-Guide on creating a Pull Request with the ticket link.
-
-> **Telemetry:** Run `aiflow gate 5 start --ticket [ticket-id]` when starting this gate.
+## MANDATORY: Strict Gate Workflow
+
+> **Absolute Rule: Complete Gate N before entering Gate N+1.**
+> **Do not skip, shorten, or merge Gates.**
+
+You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
+- **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
+- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
+- Read instructions and follow the gate sequence below — NO EXCEPTIONS.
+
+---
+
+### GATE 1 — AI Analyze Requirement (auto-start)
+
+**INVOKE:** `read-study-requirement` skill
+
+AI actively reads ticket + source code to understand the requirement:
+1. Read `.aiflow/context/current.json` — ticket info
+2. Read source code — architecture, related files, data flow
+3. If anything is unclear — ask ONE question at a time, wait for reply
+4. Output `plan/[ticket-id]/requirement.md` with:
+   - Requirements summary, source code analysis
+   - Proposed solution and approach
+   - Impact analysis, effort estimate, testing plan
+5. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
+
+> **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+
+DO NOT just check format — **understand the content and propose solutions**.
+
+> **Telemetry:** Run `aiflow gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1").
+> Run `aiflow gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
+---
+
+### GATE 2 — Implementation Plan (wait for APPROVED)
+
+**INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
+
+- Create a detailed TDD implementation plan based on the approved requirement.
+- Display: "GATE 2 PAUSED: type APPROVED to start coding".
+- CODE WILL NOT BE GENERATED until "APPROVED" is received.
+
+> **Telemetry:** Run `aiflow gate 2 start --ticket [ticket-id]` when starting this gate.
+> Run `aiflow gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
+---
+
+### GATE 3 — Code Generation (TDD only)
+
+Only runs after Gate 2 has been APPROVED.
+
+**INVOKE:** `superpowers:test-driven-development`
+- Complex feature (3+ files): `superpowers:subagent-driven-development`
+- Write tests FIRST — run to confirm FAIL -> implement -> PASS.
+- Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
+
+> **Telemetry:** Run `aiflow gate 3 start --ticket [ticket-id]` when starting this gate.
+
+---
+
+### GATE 4 — AI Self-Review (wait for APPROVED)
+
+**INVOKE:** `review-plan` skill
+
+Mandatory order:
+1. `superpowers:verification-before-completion` — all tests must PASS
+2. `impact-analysis` skill — check for breaking changes
+3. Tick `custom/rules/review-checklist.md`
+4. Create `plan/[ticket-id]/summary.md`
+
+Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
+- Coding bug -> fix -> repeat Gate 4.
+- Requirement bug -> return to Gate 1.
+
+> **Telemetry:** Run `aiflow gate 4 start --ticket [ticket-id]` when starting this gate.
+> Run `aiflow gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
+---
+
+### GATE 5 — Peer Review and Done
+
+Only runs after Gate 4 has been APPROVED.
+
+**INVOKE:** `superpowers:requesting-code-review`
+Guide on creating a Pull Request with the ticket link.
+
+> **Telemetry:** Run `aiflow gate 5 start --ticket [ticket-id]` when starting this gate.

package/custom/templates/tools/claude.md

@@ -8,6 +8,6 @@ If Gate 1 does not auto-start, wait for the developer to type **"start"**, **"Ga
 
 ## Interaction Rules:
 
-- **COLLABORATIVE SKILLS:** When a skill (like `brainstorming`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
 - **NEVER BATCH QUESTIONS:** Only ask one question per message.
 - **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/copilot.md

@@ -7,6 +7,6 @@ You are an expert AI assistant specialized in this project's stack. Follow the G
 If the Gate Workflow hasn't started, wait for the developer to type **"start"** or **"Gate 1"**.
 
 ## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `brainstorming`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
 - **NEVER BATCH QUESTIONS:** Only ask one question per message.
 - **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/cursor.md

@@ -7,6 +7,6 @@ You are an expert AI assistant specialized in this project's stack. Follow the G
 If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
 
 ## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `brainstorming`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
 - **NEVER BATCH QUESTIONS:** Only ask one question per message.
 - **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/gemini.md

@@ -7,6 +7,6 @@ You are an expert AI assistant specialized in this project's stack. Follow the G
 If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
 
 ## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `brainstorming`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
 - **NEVER BATCH QUESTIONS:** Only ask one question per message.
 - **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/generic.md

@@ -12,6 +12,6 @@ Follow the gated workflow and rules defined below.
 If Gate 1 does not start automatically, please start it when the developer types **"Gate 1"**.
 
 ## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `brainstorming`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
 - **NEVER BATCH QUESTIONS:** Only ask one question per message.
 - **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".