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

package/docs/{CHANGELOG.md → common/CHANGELOG.md}

@@ -1,128 +1,132 @@
-# Changelog
-
-All notable changes to **@relipa/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).
-
----
-
-## [0.0.4-beta.5] - 2026-04-21
-
-### Added
-- Created a dedicated `docs/` folder to house all developer-facing documentation.
-- Integrated AI Skill Registry into all tool templates (Claude, Cursor, Gemini, Copilot) for better skill discovery.
-
-### Changed
-- Moved `README.md`, `QUICK_START.md`, `AIFLOW.md`, `CHANGELOG.md`, and `IMPLEMENTATION_SUMMARY.md` into the `docs/` directory.
-- Updated `package.json` to exclude internal-only files (`CONTRIBUTING.md`, `plan.md`) from the NPM package distribution.
-- Updated `scripts/init.js` to source documentation from the new `docs/` location.
-- Updated all internal documentation links to reflect the new directory structure.
-
----
-
-## [0.0.5-beta.0] - 2026-04-23
-
-### Added
-- **`aiflow gate <n> <action>` command** — Called automatically by AI during gate transitions. Supports `start` and `approved` actions for gates 1-5. Options: `--ticket <id>`, `--ai-tool <tool>`.
-- **Telemetry gate logging** — Gate workflow templates now emit `aiflow gate N start/approved --ticket [id]` telemetry calls at each gate transition for usage metrics.
-- **`aiflow telemetry flush` command** — Force-sends buffered telemetry events immediately.
-
-### Changed
-- **Fix TEAM_SECRET input** — Replaced `password()` prompt with `input()` using a masked hint `[Reli***!@#]`; pressing Enter retains the existing value.
-- **Fix Apps Script URL input** — Same pattern as TEAM_SECRET: masked hint `[https://script.google.com/macros/s/AKfy***xxxx/exec]`; pressing Enter retains the existing value.
-- **Downgrade dependencies for Node >=16 compatibility** — `@inquirer/prompts` downgraded from `^8.3.2` to `^3.0.0`; `commander` downgraded from `^14.0.3` to `^11.0.0`.
-- **`engines.node`** updated from `>=14.0.0` to `>=16.0.0`.
-
----
-
-## [0.0.5] - 2026-04-23
-
-### Added
-- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption. 
-  - `aiflow telemetry enable/disable/status` commands to easily opt-in or opt-out.
-  - Automatically captures environment metadata and Git email via `git config --global user.email`.
-  - Secure payload signing natively using Node `crypto` HMAC-SHA256 to ensure data authenticity.
-  - Asynchronous payload flusher to ensure zero impact on command execution time (`< 5ms` overhead).
-- Support tracking for multiple AI platforms including Cursor and Gemini via Command Execution events and the new Telemetry SDK.
-
-### Security
-- **Strict Privacy**: Explicitly removed all prompt content and chat history tracking to ensure 100% confidentiality of company code and PII.
-
----
-
-## [Unreleased]
-
-## [0.0.3-beta.0] - 2026-04-13
-### Security
-- Removed internal GitLab repository links and tracking information.
-- Cleaned `.npmrc` configuration.
-- Added helper scripts for beta and stable releases.
-
-## [0.0.2] - 2026-04-13
-### Changed
-- Updated package to scoped name `@relipa/ai-flow-kit` in documentation and configuration.
-- Fixed installation guides in README and QUICK_START.
-
-## [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
-- `.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 @relipa/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
-```
+# Changelog
+
+All notable changes to **@relipa/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).
+
+---
+
+## [0.0.4-beta.5] - 2026-04-21
+
+### Added
+- Created a dedicated `docs/` folder to house all developer-facing documentation.
+- Integrated AI Skill Registry into all tool templates (Claude, Cursor, Gemini, Copilot) for better skill discovery.
+
+### Changed
+- Moved `README.md`, `QUICK_START.md`, `AIFLOW.md`, `CHANGELOG.md`, and `IMPLEMENTATION_SUMMARY.md` into the `docs/` directory.
+- Updated `package.json` to exclude internal-only files (`CONTRIBUTING.md`, `plan.md`) from the NPM package distribution.
+- Updated `scripts/init.js` to source documentation from the new `docs/` location.
+- Updated all internal documentation links to reflect the new directory structure.
+
+---
+
+## [0.0.5-beta.0] - 2026-04-23
+
+### Added
+- **`aiflow gate <n> <action>` command** — Called automatically by AI during gate transitions. Supports `start` and `approved` actions for gates 1-5. Options: `--ticket <id>`, `--ai-tool <tool>`.
+- **Telemetry gate logging** — Gate workflow templates now emit `aiflow gate N start/approved --ticket [id]` telemetry calls at each gate transition for usage metrics.
+- **`aiflow telemetry flush` command** — Force-sends buffered telemetry events immediately.
+
+### Changed
+- **`aiflow init` safe overwrite flow** — When a project already has `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, etc., `aiflow init` now prompts before overwriting:
+  - **No (default):** keeps existing file untouched; saves the aiflow template to `.aiflow/reference/<file>` for manual comparison/merge.
+  - **Yes:** backs up the existing file to `.aiflow/backup/<file>` before overwriting — nothing is permanently lost.
+- **`aiflow use --manual` pre-fill (Edit mode)** — Re-running `aiflow use --manual` when context already exists now pre-fills all fields (Ticket ID, Title, Description, Task type) with the current values; press Enter on any field to keep it unchanged.
+- **Fix TEAM_SECRET input** — Replaced `password()` prompt with `input()` using a masked hint `[Reli***!@#]`; pressing Enter retains the existing value.
+- **Fix Apps Script URL input** — Same pattern as TEAM_SECRET: masked hint `[https://script.google.com/macros/s/AKfy***xxxx/exec]`; pressing Enter retains the existing value.
+- **Downgrade dependencies for Node >=16 compatibility** — `@inquirer/prompts` downgraded from `^8.3.2` to `^3.0.0`; `commander` downgraded from `^14.0.3` to `^11.0.0`.
+- **`engines.node`** updated from `>=14.0.0` to `>=16.0.0`.
+
+---
+
+## [0.0.5] - 2026-04-23
+
+### Added
+- **Telemetry System (MVP)**: Added anonymous usage tracking to measure command metrics and user adoption. 
+  - `aiflow telemetry enable/disable/status` commands to easily opt-in or opt-out.
+  - Automatically captures environment metadata and Git email via `git config --global user.email`.
+  - Secure payload signing natively using Node `crypto` HMAC-SHA256 to ensure data authenticity.
+  - Asynchronous payload flusher to ensure zero impact on command execution time (`< 5ms` overhead).
+- Support tracking for multiple AI platforms including Cursor and Gemini via Command Execution events and the new Telemetry SDK.
+
+### Security
+- **Strict Privacy**: Explicitly removed all prompt content and chat history tracking to ensure 100% confidentiality of company code and PII.
+
+---
+
+## [Unreleased]
+
+## [0.0.3-beta.0] - 2026-04-13
+### Security
+- Removed internal GitLab repository links and tracking information.
+- Cleaned `.npmrc` configuration.
+- Added helper scripts for beta and stable releases.
+
+## [0.0.2] - 2026-04-13
+### Changed
+- Updated package to scoped name `@relipa/ai-flow-kit` in documentation and configuration.
+- Fixed installation guides in README and QUICK_START.
+
+## [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 `.aiflow/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)
+- `read-study-requirement` — 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
+- `.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 @relipa/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
+```

package/docs/{cli-reference.md → common/cli-reference.md}

@@ -237,7 +237,7 @@ aiflow context --show
 
 **What it does:**
 1. Lists, saves, loads, or deletes contexts
-2. Manages context history in `.claude/context/history/`
+2. Manages context history in `.aiflow/context/history/`
 3. Makes it easy to switch between tasks
 
 **Example:**

package/docs/project/ARCHITECTURE.md

@@ -0,0 +1,28 @@
+# Architecture Overview
+
+> **Template file** — Replace this with your project's actual architecture.
+
+## System Architecture
+
+```
+[Describe your system layers here]
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | |
+| Frontend | |
+| Database | |
+| Infrastructure | |
+
+## Key Components
+
+- 
+
+## Data Flow
+
+```
+[Describe main data flows]
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.0.5-beta.0",
+  "version": "0.0.5",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Relipa AI Team",
   "publishConfig": {
@@ -19,7 +19,8 @@
     "custom",
     "scripts",
     "upstream",
-    "docs",
+    "docs/common",
+    "docs/project",
     "package.json",
     "index.js"
   ],

package/scripts/context.js

@@ -3,7 +3,7 @@ const path = require('path');
 const chalk = require('chalk');
 
 const PROJECT_DIR  = process.cwd();
-const CONTEXT_DIR  = path.join(PROJECT_DIR, '.claude', 'context');
+const CONTEXT_DIR  = path.join(PROJECT_DIR, '.aiflow', 'context');
 const HISTORY_DIR  = path.join(CONTEXT_DIR, 'history');
 const CURRENT_FILE = path.join(CONTEXT_DIR, 'current.json');
 

package/scripts/hooks/session-start.js

@@ -1,145 +1,145 @@
-#!/usr/bin/env node
-/**
- * SessionStart hook for ai-flow-kit
- * Injects:
- *   1. using-superpowers skill content
- *   2. Active ticket context + gate workflow (if context exists)
- * Cross-platform replacement for the bash session-start hook.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { record } = require('../telemetry/record');
-
-// Record session start telemetry
-record('session.start');
-
-// This script lives at .claude/hooks/session-start.js
-// Project root is 3 levels up
-const projectRoot = path.resolve(__dirname, '..', '..', '..');
-const skillPath = path.join(projectRoot, '.claude', 'skills', 'using-superpowers', 'SKILL.md');
-const contextPath = path.join(projectRoot, '.aiflow', 'context', 'current.json');
-
-// ── 1. Load superpowers skill ──────────────────────────────────
-let skillContent = '';
-try {
-    skillContent = fs.readFileSync(skillPath, 'utf-8');
-} catch (_) {
-    // Skill file missing — continue without it
-}
-
-// ── 2. Load active ticket context ──────────────────────────────
-let contextBlock = '';
-try {
-    if (fs.existsSync(contextPath)) {
-        const ctx = JSON.parse(fs.readFileSync(contextPath, 'utf-8'));
-        if (ctx.taskId && ctx.title) {
-            contextBlock = buildContextPrompt(ctx);
-        }
-    }
-} catch (_) {
-    // Context missing or invalid — continue without it
-}
-
-// ── 3. Combine and output ──────────────────────────────────────
-const parts = [];
-
-if (skillContent) {
-    parts.push(`<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${skillContent}\n\n</EXTREMELY_IMPORTANT>`);
-}
-
-if (contextBlock) {
-    parts.push(contextBlock);
-}
-
-const combined = parts.join('\n\n');
-
-// Escape for JSON string embedding
-const escaped = combined
-    .replace(/\\/g, '\\\\')
-    .replace(/"/g, '\\"')
-    .replace(/\n/g, '\\n')
-    .replace(/\r/g, '\\r')
-    .replace(/\t/g, '\\t');
-
-process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-        hookEventName: 'SessionStart',
-        additionalContext: escaped
-    }
-}));
-
-process.exit(0);
-
-// ── Helper ─────────────────────────────────────────────────────
-
-function buildContextPrompt(ctx) {
-    const taskType = ctx.taskType || 'feature';
-
-    const lines = [];
-    lines.push('<ACTIVE_TASK>');
-    lines.push(`**Active Ticket:** ${ctx.taskId} — ${ctx.title}`);
-    lines.push(`**Type:** ${taskType}`);
-    lines.push(`**Status:** ${ctx.status || 'Unknown'}`);
-    lines.push(`**Assignee:** ${ctx.assignee || 'Unknown'}`);
-    lines.push('');
-
-    if (ctx.description) {
-        lines.push('**Description:**');
-        lines.push(ctx.description.substring(0, 2000));
-        lines.push('');
-    }
-
-    if (ctx.acceptanceCriteria && ctx.acceptanceCriteria.length > 0) {
-        lines.push('**Acceptance Criteria:**');
-        for (const c of ctx.acceptanceCriteria) {
-            lines.push(`- ${c}`);
-        }
-        lines.push('');
-    }
-
-    if (ctx.comments && ctx.comments.length > 0) {
-        lines.push(`**Comments (${ctx.comments.length}):**`);
-        // Include last 5 comments to keep context manageable
-        const recent = ctx.comments.slice(-5);
-        for (const c of recent) {
-            lines.push(c);
-            lines.push('');
-        }
-    }
-
-    if (ctx.context && ctx.context.files && ctx.context.files.length > 0) {
-        lines.push('**Related Files:**');
-        for (const f of ctx.context.files) {
-            lines.push(`- \`${f}\``);
-        }
-        lines.push('');
-    }
-
-    // ── Gate workflow instruction ──
-    lines.push('---');
-    lines.push('');
-    lines.push('**AUTO-START GATE 1: You MUST begin analyzing this ticket immediately.**');
-    lines.push('');
-    lines.push(`INVOKE the \`validate-ticket\` skill NOW for ticket ${ctx.taskId}.`);
-    lines.push('');
-    lines.push('Gate 1 process:');
-    lines.push('1. Read the ticket context above');
-    lines.push('2. Read CLAUDE.md — understand project architecture and conventions');
-    lines.push('3. Read source code — identify related files, data flow, patterns');
-    lines.push('4. If anything is unclear — ask ONE question at a time');
-    lines.push('5. Output plan/' + ctx.taskId + '/requirement.md with:');
-    lines.push('   - Requirements summary');
-    lines.push('   - Source code analysis');
-    lines.push('   - Proposed solution and approach');
-    lines.push('   - Impact analysis');
-    lines.push('   - Effort estimate');
-    lines.push('   - Testing plan');
-    lines.push('6. Display GATE 1 prompt and wait for APPROVED');
-    lines.push('');
-    lines.push('DO NOT wait for the developer to ask. START NOW.');
-    lines.push('If you have not started automatically, begin as soon as the developer types **"start"**.');
-    lines.push('</ACTIVE_TASK>');
-
-    return lines.join('\n');
-}
+#!/usr/bin/env node
+/**
+ * SessionStart hook for ai-flow-kit
+ * Injects:
+ *   1. using-superpowers skill content
+ *   2. Active ticket context + gate workflow (if context exists)
+ * Cross-platform replacement for the bash session-start hook.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { record } = require('../telemetry/record');
+
+// Record session start telemetry
+record('session.start');
+
+// This script lives at .claude/hooks/session-start.js
+// Project root is 2 levels up from __dirname (.claude/hooks → .claude → project root)
+const projectRoot = path.resolve(__dirname, '..', '..');
+const skillPath = path.join(projectRoot, '.claude', 'skills', 'using-superpowers', 'SKILL.md');
+const contextPath = path.join(projectRoot, '.aiflow', 'context', 'current.json');
+
+// ── 1. Load superpowers skill ──────────────────────────────────
+let skillContent = '';
+try {
+    skillContent = fs.readFileSync(skillPath, 'utf-8');
+} catch (_) {
+    // Skill file missing — continue without it
+}
+
+// ── 2. Load active ticket context ──────────────────────────────
+let contextBlock = '';
+try {
+    if (fs.existsSync(contextPath)) {
+        const ctx = JSON.parse(fs.readFileSync(contextPath, 'utf-8'));
+        if (ctx.taskId && ctx.title) {
+            contextBlock = buildContextPrompt(ctx);
+        }
+    }
+} catch (_) {
+    // Context missing or invalid — continue without it
+}
+
+// ── 3. Combine and output ──────────────────────────────────────
+const parts = [];
+
+if (skillContent) {
+    parts.push(`<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${skillContent}\n\n</EXTREMELY_IMPORTANT>`);
+}
+
+if (contextBlock) {
+    parts.push(contextBlock);
+}
+
+const combined = parts.join('\n\n');
+
+// Escape for JSON string embedding
+const escaped = combined
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+
+process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: escaped
+    }
+}));
+
+process.exit(0);
+
+// ── Helper ─────────────────────────────────────────────────────
+
+function buildContextPrompt(ctx) {
+    const taskType = ctx.taskType || 'feature';
+
+    const lines = [];
+    lines.push('<ACTIVE_TASK>');
+    lines.push(`**Active Ticket:** ${ctx.taskId} — ${ctx.title}`);
+    lines.push(`**Type:** ${taskType}`);
+    lines.push(`**Status:** ${ctx.status || 'Unknown'}`);
+    lines.push(`**Assignee:** ${ctx.assignee || 'Unknown'}`);
+    lines.push('');
+
+    if (ctx.description) {
+        lines.push('**Description:**');
+        lines.push(ctx.description.substring(0, 2000));
+        lines.push('');
+    }
+
+    if (ctx.acceptanceCriteria && ctx.acceptanceCriteria.length > 0) {
+        lines.push('**Acceptance Criteria:**');
+        for (const c of ctx.acceptanceCriteria) {
+            lines.push(`- ${c}`);
+        }
+        lines.push('');
+    }
+
+    if (ctx.comments && ctx.comments.length > 0) {
+        lines.push(`**Comments (${ctx.comments.length}):**`);
+        // Include last 5 comments to keep context manageable
+        const recent = ctx.comments.slice(-5);
+        for (const c of recent) {
+            lines.push(c);
+            lines.push('');
+        }
+    }
+
+    if (ctx.context && ctx.context.files && ctx.context.files.length > 0) {
+        lines.push('**Related Files:**');
+        for (const f of ctx.context.files) {
+            lines.push(`- \`${f}\``);
+        }
+        lines.push('');
+    }
+
+    // ── Gate workflow instruction ──
+    lines.push('---');
+    lines.push('');
+    lines.push('**AUTO-START GATE 1: You MUST begin analyzing this ticket immediately.**');
+    lines.push('');
+    lines.push(`INVOKE the \`read-study-requirement\` skill NOW for ticket ${ctx.taskId}.`);
+    lines.push('');
+    lines.push('Gate 1 process:');
+    lines.push('1. Read the ticket context above');
+    lines.push('2. Read CLAUDE.md — understand project architecture and conventions');
+    lines.push('3. Read source code — identify related files, data flow, patterns');
+    lines.push('4. If anything is unclear — ask ONE question at a time');
+    lines.push('5. Output plan/' + ctx.taskId + '/requirement.md with:');
+    lines.push('   - Requirements summary');
+    lines.push('   - Source code analysis');
+    lines.push('   - Proposed solution and approach');
+    lines.push('   - Impact analysis');
+    lines.push('   - Effort estimate');
+    lines.push('   - Testing plan');
+    lines.push('6. Display GATE 1 prompt and wait for APPROVED');
+    lines.push('');
+    lines.push('DO NOT wait for the developer to ask. START NOW.');
+    lines.push('If you have not started automatically, begin as soon as the developer types **"start"**.');
+    lines.push('</ACTIVE_TASK>');
+
+    return lines.join('\n');
+}