@relipa/ai-flow-kit 0.1.1 → 0.1.2-beta.0

package/bin/aiflow.js

@@ -19,6 +19,8 @@ const taskCommand     = require('../scripts/task');
 const checkpointCommand = require('../scripts/checkpoint');
 const { record }      = require('../scripts/telemetry/record');
 const { updateTaskGateState } = require('../scripts/task');
+const semver = require('semver');
+const { execSync: execSyncChild, spawnSync } = require('child_process');
 
 // ── DEPRECATION WARNING ───────────────────────────────────────
 if (!process.env.AIFLOW_IS_AK) {
@@ -415,6 +417,50 @@ function showTelResult(result, label) {
     } catch (e) { /* never block main flow */ }
 }
 
+// ── Gate start helpers ────────────────────────────────────────
+
+function checkNodeVersionForGate() {
+    try {
+        const minRaw = packageJson.engines && packageJson.engines.node
+            ? packageJson.engines.node
+            : '>=16.0.0';
+        const min = minRaw.replace('>=', '').trim();
+        const current = process.version.replace('v', '').trim();
+        if (semver.gte(current, min)) {
+            console.log(chalk.green(`  ✓ Node ${process.version}`));
+        } else {
+            console.log(chalk.yellow(`  ⚠ Node ${process.version} — minimum required: v${min}. Please upgrade Node.js.`));
+        }
+    } catch (_) {
+        console.log(chalk.gray(`  Node ${process.version}`));
+    }
+}
+
+function checkAndInstallAiflowGlobal() {
+    try {
+        const out = execSyncChild('npm list -g --depth 0 @relipa/ai-flow-kit', {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        if (!out.includes('@relipa/ai-flow-kit')) {
+            throw new Error('not found');
+        }
+        // Already installed — silent
+    } catch (_) {
+        console.log(chalk.yellow('  ⚠ @relipa/ai-flow-kit not found globally. Installing latest...'));
+        const result = spawnSync(
+            'npm',
+            ['install', '-g', '@relipa/ai-flow-kit@latest'],
+            { stdio: 'inherit', shell: process.platform === 'win32' }
+        );
+        if (result.status !== 0) {
+            console.log(chalk.red('  ✗ Install failed. Please run manually: npm install -g @relipa/ai-flow-kit@latest'));
+        } else {
+            console.log(chalk.green('  ✓ @relipa/ai-flow-kit installed successfully.'));
+        }
+    }
+}
+
 // ── gate (telemetry for gate workflow events) ─────────────────
 program
     .command('gate <number> <action>')
@@ -426,6 +472,12 @@ program
         if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
         if (!['start', 'approved'].includes(action)) return;
 
+        if (action === 'start') {
+            console.log(chalk.cyan(`\n  [aiflow] Gate ${gateNum} environment check:`));
+            checkNodeVersionForGate();
+            checkAndInstallAiflowGlobal();
+        }
+
         const ticketId = options.ticket || '';
 
         const telResult = record(`gate.${action}`, {
@@ -489,12 +541,13 @@ program
         }
 
         const state = await fs.readJson(stateFile);
-        const frameworks = state.frameworks || [];
+        // Support both old 'framework' (singular string) and new 'frameworks' (array)
+        const frameworks = state.frameworks || (state.framework ? [state.framework] : []);
         const selectedTools = state.aiTools || Object.keys(AI_TOOL_FILES);
 
         console.log(chalk.cyan('⟳ Syncing AI Instruction files...'));
         for (const fw of frameworks) {
-            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools);
+            await setupFramework(projectDir, fw, frameworks.length > 1, selectedTools, { force: true });
         }
         await ensureAiflowGitignored(projectDir);
         console.log(chalk.green('✨ Sync completed!'));

package/custom/mcp-presets/README.md

@@ -1,237 +1,204 @@
-# MCP Presets
-
-Pre-configured MCP (Model Context Protocol) adapters for various project management and collaboration tools.
-
-## Available Presets
-
-### Jira (`jira.json`)
-
-Connect to Atlassian Jira for loading issues and context.
-
-**Setup:**
-```bash
-aiflow init --adapter jira
-```
-
-**Required Environment Variables:**
-- `JIRA_API_TOKEN` — Your Jira API token
-- `JIRA_EMAIL` — Your Jira account email
-- `JIRA_DOMAIN` — Your Jira domain (e.g., "company" in company.atlassian.net)
-
-**Get API Token:**
-1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
-2. Create new API token
-3. Copy the token
-
-**Usage:**
-```bash
-aiflow use JIRA-123
-# Loads issue JIRA-123 from your Jira instance
-```
-
-### Backlog (`backlog.json`)
-
-Connect to Nulab Backlog for loading tasks and context.
-
-**Setup:**
-```bash
-aiflow init --adapter backlog
-```
-
-**Required Environment Variables:**
-- `BACKLOG_API_KEY` — Your Backlog API key
-- `BACKLOG_SPACE_KEY` — Your Backlog space key
-
-**Get API Key:**
-1. Log in to Backlog
-2. Go to Personal Settings → API Settings
-3. Generate new API token
-
-**Usage:**
-```bash
-aiflow use BACKLOG-456
-# Loads task from your Backlog instance
-```
-
-### Figma (`figma.json`)
-
-Connect to Figma via REST API to read design files and generate components.
-
-**When to use:** Default choice. Works anywhere — no Desktop app required.
-
-**Setup:**
-```bash
-aiflow init --adapter figma
-```
-
-**Required Environment Variables:**
-- `FIGMA_API_TOKEN` — Your Figma Personal Access Token
-
-**Get API Token:**
-1. Go to https://www.figma.com/settings → Security → Personal access tokens
-2. Create a new token with File content (read) scope
-3. Copy the token
-
-**Tools provided by `figma-developer-mcp`:**
-- `get_figma_data(fileKey, nodeId, depth)` — fetch node layout, styles, components
-- `download_figma_images(fileKey, nodes, localPath)` — export images
-
-**Usage:**
-```
-Generate component from Figma:
-https://www.figma.com/design/XXXXX/App?node-id=123-456
-```
-
-See: [Figma workflow guide](../../docs/common/workflows/figma.md)
-
----
-
-### Figma Desktop (`figma-desktop.json`)
-
-Connect via the official Figma MCP server. Requires Figma Desktop app open.
-
-**When to use:** When your team prefers the official Figma tooling and has Desktop app licenses.
-**When NOT to use:** CI environments, headless servers, team members without Desktop licenses.
-
-**Setup:**
-```bash
-aiflow init --adapter figma-desktop
-```
-
-**Requirements:**
-- Figma Desktop app installed
-- A Figma file open in Desktop when invoking the skill
-- No API token needed — uses Desktop session
-
-**Tools provided by `@figma/mcp-server`:**
-- `get_figma_data(fileKey, nodeId)` — fetch design data for open file
-- `get_node_children(nodeId)` — traverse component tree
-- `get_local_components()` — list components in the open file
-
-| | `figma` (REST API) | `figma-desktop` (Official) |
-|---|---|---|
-| Needs Desktop app | No | Yes (must be open) |
-| Auth | API Token | Desktop session |
-| Works in CI | Yes | No |
-| Access scope | Full REST API | Currently open file |
-
-See: [Figma workflow guide](../../docs/common/workflows/figma.md)
-
----
-
-### Playwright (`playwright.json`)
-
-Drive a real browser to explore selectors, verify flows, and capture evidence. Powers the `automation-testing` skill (Phase 3 — Explore).
-
-**When to use:** Generating E2E UI tests. The skill uses MCP to read the live DOM (real selectors, not guessed) and screenshot each step, then emits durable `.spec.ts` files for CI.
-
-**Setup:**
-```bash
-aiflow init --adapter playwright
-```
-
-**Requirements:**
-- The web app under test must be running and reachable at `baseUrl`
-- No API token needed
-- First run downloads browsers via `npx playwright install` (one-time)
-
-**Tools provided by `@playwright/mcp`:**
-- `browser_navigate(url)` — open a page
-- `browser_snapshot()` — accessibility tree (source of real selectors)
-- `browser_click` / `browser_type` / `browser_fill` — interact with elements
-- `browser_take_screenshot(path)` — capture evidence
-
-**Usage:**
-```
-/automation-testing baseUrl: http://localhost:3000 explore: true
-```
-
-> **Hybrid principle:** MCP is for *exploration + evidence* only. It does not replace test files — the skill always emits committable `.spec.ts` so CI can re-run.
-
-See: [automation-testing design](../../requirements/autotest/AutomationTestWorkflow.md)
-
----
-
-### Google Sheets (`google-sheets.json`)
-
-Connect to Google Sheets for loading task context.
-
-**Setup:**
-```bash
-aiflow init --adapter google-sheets
-```
-
-**Required Environment Variables:**
-- `GOOGLE_SHEETS_CREDS` — Path to service account JSON
-
-**Get Credentials:**
-1. Create Google Cloud project
-2. Enable Sheets API
-3. Create service account
-4. Download JSON credentials
-5. Store securely and set path
-
-**Usage:**
-```bash
-aiflow use SHEET-A1:D5
-# Loads data from Google Sheet
-```
-
-## Creating Custom Presets
-
-To add a new MCP adapter:
-
-1. Create `<adapter-name>.json`:
-
-```json
-{
-  "mcpServers": {
-    "<adapter-name>": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-<adapter-name>"
-      ],
-      "env": {
-        "ENV_VAR_1": "{{PLACEHOLDER}}",
-        "ENV_VAR_2": "{{PLACEHOLDER}}"
-      }
-    }
-  }
-}
-```
-
-2. Document in this README
-
-3. Users can install with:
-```bash
-aiflow init --adapter <adapter-name>
-```
-
-## Validators
-
-Each preset should be validated during `aiflow init`:
-
-- ✓ Environment variables set
-- ✓ API connectivity working
-- ✓ Proper permissions configured
-
-## Best Practices
-
-1. **Use placeholders** — {{VAR_NAME}} for env variables
-2. **Document setup** — Include step-by-step guide
-3. **Provide examples** — Show usage patterns
-4. **Handle errors** — Clear error messages if setup fails
-5. **Support multiple instances** — Allow team variations
-
-## Security
-
-- **Never commit credentials** — Use environment variables
-- **Use secure storage** — Store API tokens securely
-- **Rotate tokens** — Regularly update API tokens
-- **Restrict permissions** — Use minimal required permissions
-- **Audit access** — Monitor who accesses what
-
----
-
-For more info: See [Configuration Guide](../../docs/configuration.md)
+# MCP Presets
+
+Pre-configured MCP (Model Context Protocol) adapters for various project management and collaboration tools.
+
+## Available Presets
+
+### Jira (`jira.json`)
+
+Connect to Atlassian Jira for loading issues and context.
+
+**Setup:**
+```bash
+aiflow init --adapter jira
+```
+
+**Required Environment Variables:**
+- `JIRA_API_TOKEN` — Your Jira API token
+- `JIRA_EMAIL` — Your Jira account email
+- `JIRA_DOMAIN` — Your Jira domain (e.g., "company" in company.atlassian.net)
+
+**Get API Token:**
+1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
+2. Create new API token
+3. Copy the token
+
+**Usage:**
+```bash
+aiflow use JIRA-123
+# Loads issue JIRA-123 from your Jira instance
+```
+
+### Backlog (`backlog.json`)
+
+Connect to Nulab Backlog for loading tasks and context.
+
+**Setup:**
+```bash
+aiflow init --adapter backlog
+```
+
+**Required Environment Variables:**
+- `BACKLOG_API_KEY` — Your Backlog API key
+- `BACKLOG_SPACE_KEY` — Your Backlog space key
+
+**Get API Key:**
+1. Log in to Backlog
+2. Go to Personal Settings → API Settings
+3. Generate new API token
+
+**Usage:**
+```bash
+aiflow use BACKLOG-456
+# Loads task from your Backlog instance
+```
+
+### Figma (`figma.json`)
+
+Connect to Figma via REST API to read design files and generate components.
+
+**When to use:** Default choice. Works anywhere — no Desktop app required.
+
+**Setup:**
+```bash
+aiflow init --adapter figma
+```
+
+**Required Environment Variables:**
+- `FIGMA_API_TOKEN` — Your Figma Personal Access Token
+
+**Get API Token:**
+1. Go to https://www.figma.com/settings → Security → Personal access tokens
+2. Create a new token with File content (read) scope
+3. Copy the token
+
+**Tools provided by `figma-developer-mcp`:**
+- `get_figma_data(fileKey, nodeId, depth)` — fetch node layout, styles, components
+- `download_figma_images(fileKey, nodes, localPath)` — export images
+
+**Usage:**
+```
+Generate component from Figma:
+https://www.figma.com/design/XXXXX/App?node-id=123-456
+```
+
+See: [Figma workflow guide](../../docs/common/workflows/figma.md)
+
+---
+
+### Figma Desktop (`figma-desktop.json`)
+
+Connect via the official Figma MCP server. Requires Figma Desktop app open.
+
+**When to use:** When your team prefers the official Figma tooling and has Desktop app licenses.
+**When NOT to use:** CI environments, headless servers, team members without Desktop licenses.
+
+**Setup:**
+```bash
+aiflow init --adapter figma-desktop
+```
+
+**Requirements:**
+- Figma Desktop app installed
+- A Figma file open in Desktop when invoking the skill
+- No API token needed — uses Desktop session
+
+**Tools provided by `@figma/mcp-server`:**
+- `get_figma_data(fileKey, nodeId)` — fetch design data for open file
+- `get_node_children(nodeId)` — traverse component tree
+- `get_local_components()` — list components in the open file
+
+| | `figma` (REST API) | `figma-desktop` (Official) |
+|---|---|---|
+| Needs Desktop app | No | Yes (must be open) |
+| Auth | API Token | Desktop session |
+| Works in CI | Yes | No |
+| Access scope | Full REST API | Currently open file |
+
+See: [Figma workflow guide](../../docs/common/workflows/figma.md)
+
+---
+
+### Google Sheets (`google-sheets.json`)
+
+Connect to Google Sheets for loading task context.
+
+**Setup:**
+```bash
+aiflow init --adapter google-sheets
+```
+
+**Required Environment Variables:**
+- `GOOGLE_SHEETS_CREDS` — Path to service account JSON
+
+**Get Credentials:**
+1. Create Google Cloud project
+2. Enable Sheets API
+3. Create service account
+4. Download JSON credentials
+5. Store securely and set path
+
+**Usage:**
+```bash
+aiflow use SHEET-A1:D5
+# Loads data from Google Sheet
+```
+
+## Creating Custom Presets
+
+To add a new MCP adapter:
+
+1. Create `<adapter-name>.json`:
+
+```json
+{
+  "mcpServers": {
+    "<adapter-name>": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-<adapter-name>"
+      ],
+      "env": {
+        "ENV_VAR_1": "{{PLACEHOLDER}}",
+        "ENV_VAR_2": "{{PLACEHOLDER}}"
+      }
+    }
+  }
+}
+```
+
+2. Document in this README
+
+3. Users can install with:
+```bash
+aiflow init --adapter <adapter-name>
+```
+
+## Validators
+
+Each preset should be validated during `aiflow init`:
+
+- ✓ Environment variables set
+- ✓ API connectivity working
+- ✓ Proper permissions configured
+
+## Best Practices
+
+1. **Use placeholders** — {{VAR_NAME}} for env variables
+2. **Document setup** — Include step-by-step guide
+3. **Provide examples** — Show usage patterns
+4. **Handle errors** — Clear error messages if setup fails
+5. **Support multiple instances** — Allow team variations
+
+## Security
+
+- **Never commit credentials** — Use environment variables
+- **Use secure storage** — Store API tokens securely
+- **Rotate tokens** — Regularly update API tokens
+- **Restrict permissions** — Use minimal required permissions
+- **Audit access** — Monitor who accesses what
+
+---
+
+For more info: See [Configuration Guide](../../docs/configuration.md)

package/custom/rules/ml-conventions.md

@@ -0,0 +1,88 @@
+# ML Conventions (Override Skill Defaults)
+
+> **MANDATORY:** These rules override ANY upstream skill default (including `writing-plans`, `generate-spec`, `train-model`, `evaluate-model`, and all superpowers skills).
+> Read this file before writing any output file during the ML Gate Workflow.
+
+---
+
+## ML Plan Output Paths
+
+| Output | Path | Note |
+|--------|------|------|
+| ML problem doc | `plan/[ticket-id]/ml-problem.md` | Gate 1 output |
+| Experiment plan | `plan/[ticket-id]/experiment-plan.md` | Gate 2 output — **NOT** `docs/superpowers/plans/` |
+| Evaluation report | `plan/[ticket-id]/eval-report.md` | Gate 4 output |
+
+> The `[ticket-id]` comes from `.aiflow/context/current.json`.
+> If no ticket context exists, use a descriptive slug: `plan/<feature-name>/ml-problem.md`.
+
+---
+
+## Reproducibility Rules
+
+Every experiment must be fully reproducible from its logged artifacts alone:
+
+- **Set all seeds** before any randomness: `random.seed(n)`, `numpy.random.seed(n)`, and the framework seed (`torch.manual_seed(n)`, `tf.random.set_seed(n)`).
+- **Enable deterministic flags** where feasible (`torch.use_deterministic_algorithms(True)`; note and document any performance trade-off).
+- **Pin the environment:** `requirements.txt` or a lockfile must be committed alongside every model artifact.
+- **Log seed, config, and commit SHA** with every tracked run — a run is not reproducible unless these three are recorded.
+
+---
+
+## Experiment Naming Scheme
+
+Pattern: `[ticket-id]_[approach]_[yyyymmdd-n]`
+
+- `[ticket-id]` — Jira/linear ticket key (from `.aiflow/context/current.json`)
+- `[approach]` — short slug describing the method (lowercase, hyphens, no spaces)
+- `[yyyymmdd-n]` — date + 1-based daily sequence counter
+
+**Concrete example:**
+
+```
+ML-42_lgbm-tfidf_20241115-1
+ML-42_lgbm-tfidf_20241115-2
+ML-42_bert-finetune_20241116-1
+```
+
+Use this name as the MLflow `run_name` / wandb `run` name and as the artifact folder name under `experiments/`.
+
+---
+
+## Data & Model Versioning
+
+- **Datasets** must be versioned with DVC (or an equivalent registry). Never commit raw data or large processed files to git.
+- **Model artifacts** must be registered in the artifact store (MLflow Model Registry, DVC, or equivalent). Record the data version used to produce each artifact.
+- Each artifact's metadata must include: data version, code commit SHA, config file path, and eval metric.
+- `models/` and `data/` directories are git-ignored; tracked via DVC or the registry instead.
+
+---
+
+## Anti-Leakage Rules (Hard Rules)
+
+These rules are non-negotiable and override any convenience shortcut:
+
+- **Split before fit** — perform the train/validation/test split BEFORE fitting any transformer, imputer, scaler, or encoder.
+- **Fit transforms on train only** — all preprocessing must live inside a `Pipeline` that is fit exclusively on the training fold. Never fit on the full dataset and then split.
+- **No target leakage** — features must not be derived from or computed after the prediction target. Explicitly check every feature's availability time relative to the target.
+- **No temporal leakage** — for time-series data, use time-aware splits (no future data for past predictions). Validate that no feature uses information from future time steps.
+- **Test set is held-out** — the test set is touched only at Gate 4 evaluation. No hyperparameter tuning, no feature selection, and no threshold selection on the test set.
+
+---
+
+## Checklist Before Writing Any Output File
+
+Before saving any ML plan, experiment plan, or eval report, verify:
+
+- [ ] Output path follows the table above — NOT the skill's default path
+- [ ] `[ticket-id]` is read from `.aiflow/context/current.json`
+- [ ] Directory `plan/[ticket-id]/` exists or will be created
+- [ ] Announced path in the handoff message matches the actual saved path
+
+---
+
+## Other Conventions
+
+- **ML review checklist:** `custom/rules/ml-review-checklist.md`
+- **Code style:** `custom/rules/code-style.md`
+- **Naming:** `custom/rules/naming.md`