@caiqueoak/flow 0.2.1 → 0.3.1

package/src/cli.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import readline from 'node:readline/promises';
+import { stdin as inputStream, stdout as outputStream } from 'node:process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -14,116 +15,274 @@ const VERSION = PACKAGE.version;
 const PACKAGE_NAME = PACKAGE.name;
 const args = process.argv.slice(2);
 
-function fail(message, code = 1) {
-  console.error(`flow: ${message}`);
-  process.exit(code);
-}
+const RUNTIME_DEFINITIONS = {
+  codex: { label: 'Codex', skillsPath: '.codex/skills' },
+  claude: { label: 'Claude Code', skillsPath: '.claude/skills' }
+};
 
-function info(message) { console.log(message); }
+function fail(message, code = 1) { console.error(`flow: ${message}`); process.exit(code); }
+function info(message = '') { console.log(message); }
 function hasFlag(name) { return args.includes(name); }
 function valueAfter(name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
 function npmCommand() { return process.platform === 'win32' ? 'npm.cmd' : 'npm'; }
+function projectRoot() { return path.resolve(valueAfter('--path') || process.cwd()); }
+function configPath(root) { return path.join(root, '.flow', 'config.yaml'); }
+function packagePath(root) { return path.join(root, 'node_modules', '@caiqueoak', 'flow'); }
+
+function abortedPromptError() {
+  const error = new Error('Prompt aborted.');
+  error.code = 'ABORT_ERR';
+  return error;
+}
+
+function question(rl, message) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      rl.removeListener('close', onClose);
+      callback(value);
+    };
+    const onClose = () => finish(reject, abortedPromptError());
+    rl.once('close', onClose);
+    rl.question(message).then(
+      (answer) => finish(resolve, answer),
+      (error) => finish(reject, error)
+    );
+  });
+}
 
-function copyDir(source, target, { overwrite = false } = {}) {
+function runNpm(npmArgs, options = {}) {
+  return execFileSync(npmCommand(), npmArgs, {
+    ...options,
+    shell: process.platform === 'win32'
+  });
+}
+
+function copyDir(source, target) {
   fs.mkdirSync(target, { recursive: true });
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
     const src = path.join(source, entry.name);
     const dst = path.join(target, entry.name);
-    if (entry.isDirectory()) copyDir(src, dst, { overwrite });
-    else if (!fs.existsSync(dst) || overwrite) fs.copyFileSync(src, dst);
+    if (entry.isDirectory()) copyDir(src, dst);
+    else fs.copyFileSync(src, dst);
   }
 }
 
-function conventionalSkillTargets(cwd) {
-  const candidates = [
-    path.join(cwd, '.agents', 'skills'),
-    path.join(cwd, '.claude', 'skills'),
-    path.join(os.homedir(), '.agents', 'skills'),
-    path.join(os.homedir(), '.claude', 'skills')
-  ];
-  return [...new Set(candidates)].filter((candidate) => fs.existsSync(candidate));
+function quoteYaml(value) { return /^[A-Za-z0-9_.\/-]+$/.test(value) ? value : JSON.stringify(value); }
+function defaultConfig() {
+  return { frameworkVersion: VERSION, runtimes: [], continueAcrossWorkItems: true, workItemsConcurrency: 'auto', taskConcurrency: 'auto' };
 }
 
-function resolveInstallTarget() {
-  const explicit = valueAfter('--target');
-  if (explicit) return path.resolve(explicit.replace(/^~(?=$|\/|\\)/, os.homedir()));
-  const detected = conventionalSkillTargets(process.cwd());
-  if (detected.length === 1) return detected[0];
-  if (detected.length > 1) fail(`multiple skill directories detected:\n${detected.map((x) => `  - ${x}`).join('\n')}\nUse --target <skills-directory>.`);
-  fail('no skill directory detected. Use --target <skills-directory>. This keeps Flow runtime-agnostic.');
+function readConfig(root) {
+  const file = configPath(root);
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  const cfg = defaultConfig();
+  const v = text.match(/^[ \t]*version:[ \t]*([^\s#]+)[ \t]*$/m);
+  if (v) cfg.frameworkVersion = v[1].replace(/^['"]|['"]$/g, '');
+  const runtimeBlock = text.match(/^runtimes:\s*\n([\s\S]*?)(?=^[A-Za-z_][A-Za-z0-9_]*:|\Z)/m)?.[1] || '';
+  const entries = runtimeBlock.split(/(?=^\s*-\s+type:)/m).filter((x) => /-\s+type:/.test(x));
+  for (const entry of entries) {
+    const type = entry.match(/-\s+type:\s*([^\s#]+)/)?.[1]?.replace(/^['"]|['"]$/g, '');
+    const skillsPath = entry.match(/skills_path:\s*([^\n#]+)/)?.[1]?.trim().replace(/^['"]|['"]$/g, '');
+    if (type && skillsPath) cfg.runtimes.push({ type, skills_path: skillsPath });
+  }
+  return cfg;
 }
 
-function initProject() {
-  const projectRoot = path.resolve(valueAfter('--path') || process.cwd());
-  const flowDir = path.join(projectRoot, '.flow');
-  if (fs.existsSync(flowDir) && !hasFlag('--force')) fail(`${flowDir} already exists. Use --force only to add missing templates without replacing project state.`);
-  fs.mkdirSync(flowDir, { recursive: true });
-  copyDir(path.join(ROOT, 'templates'), flowDir, { overwrite: false });
-  fs.mkdirSync(path.join(flowDir, 'work-items'), { recursive: true });
-  fs.mkdirSync(path.join(flowDir, 'gates'), { recursive: true });
-  info(`Initialized Flow project at ${flowDir}`);
-  info('Next: open your coding agent and run /flow-new with the idea or existing source documents.');
+function writeConfig(root, config) {
+  const lines = ['schema_version: 1', 'framework:', '  name: flow', `  version: ${VERSION}`, 'runtimes:'];
+  if (!config.runtimes.length) lines.push('  []');
+  else for (const runtime of config.runtimes) {
+    lines.push(`  - type: ${quoteYaml(runtime.type)}`);
+    lines.push(`    skills_path: ${quoteYaml(runtime.skills_path)}`);
+  }
+  lines.push('autonomy:', '  continue_across_work_items: true', '  stop_on:', '    - consequential_decision', '    - external_approval', '    - unrecoverable_blocker', '    - no_ready_work', 'parallelism:', '  strategy: maximum_safe', '  max_concurrent_work_items: auto', '  max_concurrent_tasks_per_work_item: auto', 'efficiency:', '  token_usage: optimize', '  prefer_primary_orchestrator: true', '  delegate_only_when_beneficial: true', '');
+  fs.mkdirSync(path.join(root, '.flow'), { recursive: true });
+  fs.writeFileSync(configPath(root), lines.join('\n'), 'utf8');
 }
 
-function installSkills({ force = hasFlag('--force') } = {}) {
-  const target = resolveInstallTarget();
-  fs.mkdirSync(target, { recursive: true });
-  copyDir(path.join(ROOT, 'skills'), target, { overwrite: force });
-  info(`Installed Flow ${VERSION} skills to ${target}`);
-  if (!force) info('Existing skill files were preserved. Use --force to replace them.');
+function installRuntimeSkill(root, runtime, packageRoot = ROOT) {
+  const target = path.join(root, runtime.skills_path, 'flow');
+  copyDir(path.join(packageRoot, 'skills', 'flow'), target);
   return target;
 }
+function parseRuntimeFlag() {
+  const raw = valueAfter('--runtime');
+  return raw ? raw.split(',').map((x) => x.trim().toLowerCase()).filter(Boolean) : null;
+}
 
-function latestPublishedVersion() {
+function missingBuiltinRuntimes(existing) {
+  const existingTypes = new Set(existing.map((r) => r.type));
+  return Object.keys(RUNTIME_DEFINITIONS).filter((type) => !existingTypes.has(type));
+}
+
+async function promptMultiSelect(existing) {
+  const existingTypes = new Set(existing.map((r) => r.type));
+  const options = Object.entries(RUNTIME_DEFINITIONS).filter(([type]) => !existingTypes.has(type)).map(([value, def]) => ({ value, label: def.label }));
+  options.push({ value: 'custom', label: 'Custom coding agent / skills path' });
+  info(existing.length ? 'Select coding agents to add:' : 'Select coding agents:');
+  options.forEach((opt, i) => info(`  [ ] ${i + 1}. ${opt.label}`));
+  info('  (Select multiple with comma-separated numbers, e.g. 1,2)');
+  const rl = readline.createInterface({ input: inputStream, output: outputStream });
   try {
-    return execFileSync(npmCommand(), ['view', PACKAGE_NAME, 'version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 15000 }).trim();
-  } catch {
-    return null;
-  }
+    while (true) {
+      const answer = (await question(rl, 'Selection: ')).trim();
+      const indices = [...new Set(answer.split(',').map((v) => Number.parseInt(v.trim(), 10)).filter(Number.isInteger))];
+      if (indices.length && indices.every((n) => n >= 1 && n <= options.length)) return indices.map((n) => options[n - 1].value);
+      info('Choose one or more valid numbers.');
+    }
+  } finally { rl.close(); }
 }
 
-function compareVersions(a, b) {
-  const pa = a.split('.').map((n) => Number.parseInt(n, 10) || 0);
-  const pb = b.split('.').map((n) => Number.parseInt(n, 10) || 0);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const d = (pa[i] || 0) - (pb[i] || 0);
-    if (d) return d;
+async function promptText(message, defaultValue = '') {
+  const rl = readline.createInterface({ input: inputStream, output: outputStream });
+  try {
+    const answer = (await question(rl, `${message}${defaultValue ? ` [${defaultValue}]` : ''}: `)).trim();
+    return answer || defaultValue;
+  } finally { rl.close(); }
+}
+
+async function resolveRuntime(type, existing) {
+  if (RUNTIME_DEFINITIONS[type]) return { type, skills_path: RUNTIME_DEFINITIONS[type].skillsPath };
+  if (type !== 'custom') fail(`unsupported runtime '${type}'. Use codex, claude, or custom.`);
+  const fallback = `custom-${existing.filter((r) => r.type.startsWith('custom')).length + 1}`;
+  const name = await promptText('Custom coding agent id', fallback);
+  while (true) {
+    const skillsPath = await promptText('Project-local skills directory', `.${name}/skills`);
+    if (!path.isAbsolute(skillsPath) && !skillsPath.split(/[\\/]/).includes('..')) return { type: name, skills_path: skillsPath };
+    info('Skills path must be relative and remain inside the project.');
   }
-  return 0;
 }
 
-function update() {
-  const target = resolveInstallTarget();
-  const latest = latestPublishedVersion();
-  if (!latest) fail(`could not read the latest ${PACKAGE_NAME} version from npm.`);
-  if (compareVersions(latest, VERSION) <= 0) {
-    copyDir(path.join(ROOT, 'skills'), target, { overwrite: true });
-    info(`Flow ${VERSION} is already current. Skills refreshed at ${target}`);
+async function initProject() {
+  const root = projectRoot();
+  const flowDir = path.join(root, '.flow');
+  const existed = fs.existsSync(flowDir);
+  const config = readConfig(root) || defaultConfig();
+  if (existed) {
+    info('Flow project already exists. Canonical project artifacts will not be created or modified.');
+    if (config.runtimes.length) info(`Configured coding agents: ${config.runtimes.map((r) => r.type).join(', ')}`);
+  }
+
+  const requested = parseRuntimeFlag();
+  if (existed && !requested && missingBuiltinRuntimes(config.runtimes).length === 0) {
+    info('All built-in coding agents are already configured. Nothing to add.');
+    info('Use --runtime custom only when you intentionally want to add a custom coding agent.');
     return;
   }
 
-  info(`Updating Flow skills ${VERSION} → ${latest}...`);
-  const execArgs = ['exec', '--yes', `--package=${PACKAGE_NAME}@${latest}`, '--', 'flow', 'install', '--target', target, '--force'];
+  const selected = requested || await promptMultiSelect(config.runtimes);
+  const knownTypes = new Set(config.runtimes.map((r) => r.type));
+  const added = [];
+  for (const type of selected) {
+    if (knownTypes.has(type)) continue;
+    const runtime = await resolveRuntime(type, config.runtimes);
+    if (knownTypes.has(runtime.type)) continue;
+    config.runtimes.push(runtime); knownTypes.add(runtime.type); added.push(runtime);
+  }
+  fs.mkdirSync(flowDir, { recursive: true });
+  writeConfig(root, config);
+  for (const runtime of added) info(`✓ ${runtime.type}: ${path.relative(root, installRuntimeSkill(root, runtime))}`);
+  if (!added.length) info('No new coding-agent integration was added.');
+  else { info(); info('Flow is ready. Open a configured coding agent and invoke /flow.'); }
+}
+
+function dependencySection(root) {
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) return '--save-dev';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (pkg.dependencies?.[PACKAGE_NAME]) return '--save';
+    if (pkg.optionalDependencies?.[PACKAGE_NAME]) return '--save-optional';
+  } catch { /* use default */ }
+  return '--save-dev';
+}
+
+function containingNodeModules(packageRoot) {
+  let current = path.resolve(packageRoot);
+  while (true) {
+    if (path.basename(current).toLowerCase() === 'node_modules') return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function updatePlan(root) {
+  const projectPackageRoot = packagePath(root);
+  if (fs.existsSync(path.join(projectPackageRoot, 'package.json'))) {
+    return {
+      npmArgs: ['install', dependencySection(root), `${PACKAGE_NAME}@latest`],
+      cwd: root,
+      packageRoot: projectPackageRoot,
+      mode: 'project'
+    };
+  }
+
   try {
-    execFileSync(npmCommand(), execArgs, { stdio: 'inherit' });
-  } catch {
-    fail('update failed. Your existing installation was not intentionally removed.');
+    const globalNodeModules = path.resolve(runNpm(['root', '--global'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim());
+    const globalPackageRoot = path.join(globalNodeModules, '@caiqueoak', 'flow');
+    if (path.resolve(ROOT).startsWith(`${globalNodeModules}${path.sep}`) && fs.existsSync(path.join(globalPackageRoot, 'package.json'))) {
+      return {
+        npmArgs: ['install', '--global', `${PACKAGE_NAME}@latest`],
+        cwd: root,
+        packageRoot: globalPackageRoot,
+        mode: 'global'
+      };
+    }
+  } catch { /* fall through to local installation detection */ }
+
+  const nodeModules = containingNodeModules(ROOT);
+  if (nodeModules) {
+    const installRoot = path.dirname(nodeModules);
+    return {
+      npmArgs: ['install', dependencySection(installRoot), `${PACKAGE_NAME}@latest`],
+      cwd: installRoot,
+      packageRoot: ROOT,
+      mode: 'local'
+    };
   }
-  info(`Skills updated to Flow ${latest}.`);
-  info(`If Flow itself is globally installed, update the CLI with: npm install -g ${PACKAGE_NAME}@latest`);
+
+  fail('cannot determine how this Flow CLI was installed. Reinstall @caiqueoak/flow with npm, then run flow update again.');
+}
+
+function update() {
+  const root = projectRoot();
+  const config = readConfig(root);
+  if (!config) fail('this project is not initialized. Run flow init first.');
+  if (!config.runtimes.length) fail('no coding agents are configured. Run flow init to add one.');
+
+  const plan = updatePlan(root);
+  info(`Updating ${PACKAGE_NAME} (${plan.mode} installation)...`);
+  try { runNpm(plan.npmArgs, { cwd: plan.cwd, stdio: 'inherit' }); }
+  catch { fail('npm update failed. Existing project state and installed skills were not intentionally removed.'); }
+
+  if (!fs.existsSync(path.join(plan.packageRoot, 'package.json'))) fail(`updated package not found at ${plan.packageRoot}.`);
+  const latest = JSON.parse(fs.readFileSync(path.join(plan.packageRoot, 'package.json'), 'utf8'));
+  for (const runtime of config.runtimes) info(`✓ ${runtime.type}: ${path.relative(root, installRuntimeSkill(root, runtime, plan.packageRoot))}`);
+  const text = fs.readFileSync(configPath(root), 'utf8');
+  fs.writeFileSync(configPath(root), text.replace(/(^framework:\s*\n(?:.*\n)*?\s+version:\s*)[^\n]+/m, `$1${latest.version}`), 'utf8');
+  info(`Flow updated to ${latest.version}.`);
 }
 
 function help() {
-  info(`Flow ${VERSION}\n\nUsage:\n  flow init [--path <project>] [--force]\n  flow install [--target <skills-directory>] [--force]\n  flow update [--target <skills-directory>]\n  flow --version\n\nThe CLI only initializes project state and installs/updates skills.\nWorkflow orchestration is performed by the coding agent through the Flow skills.`);
+  info(`Flow ${VERSION}\n\nUsage:\n  flow init [--path <project>] [--runtime codex,claude]\n  flow update [--path <project>]\n  flow --version\n\nflow init creates only .flow/config.yaml and installs the project-local /flow skill for selected coding agents.\nIf .flow already exists, init only adds coding-agent integrations and exits without prompting when all built-in integrations are already configured.\nflow update updates the installation that provides the Flow CLI (project-local or global) and refreshes every configured project-local skill.\nThere is no flow install command and no automatic/background update mechanism.`);
 }
 
-if (args.length === 0 || hasFlag('--help') || hasFlag('-h')) help();
-else if (hasFlag('--version') || hasFlag('-v')) info(VERSION);
-else {
-  switch (args[0]) {
-    case 'init': initProject(); break;
-    case 'install': installSkills(); break;
-    case 'update': update(); break;
-    default: fail(`unknown command '${args[0]}'. Run flow --help.`);
+try {
+  if (!args.length || hasFlag('--help') || hasFlag('-h')) help();
+  else if (hasFlag('--version') || hasFlag('-v')) info(VERSION);
+  else if (args[0] === 'init') await initProject();
+  else if (args[0] === 'update') update();
+  else fail(`unknown command '${args[0]}'. Run flow --help.`);
+} catch (error) {
+  if (error?.code === 'ABORT_ERR') {
+    info('\nFlow command canceled.');
+    process.exitCode = 130;
+  } else {
+    throw error;
   }
 }

package/skills/flow-build/SKILL.md

@@ -1,73 +0,0 @@
----
-name: flow-build
-description: Implement ready tasks with maximum-safe parallelism, approved decisions and gates, token-efficient context packets, automatic claims, tests, commits, and state synchronization.
----
-
-# Flow Build
-
-## Objective
-
-Implement an active work item efficiently while preserving approved product/engineering constraints and exploiting safe parallelism without turning parallelism into coordination or token waste.
-
-## Context loading
-
-Start with STATE, the current work item's SPEC/TASKS, and only the relevant global decisions/engineering/gates. Workers or subagents receive the smallest context packet needed for their task.
-
-## Claims
-
-Before implementation/delegation, mark selected tasks `in_progress` and set their `execution_id`. Synchronize state BEFORE code edits. Never take over a task or work item already `in_progress` under another execution ID.
-
-There is no claim timeout. If ownership appears abandoned or inconsistent, surface it for explicit reconciliation rather than silently reclaiming it.
-
-## Maximum-safe parallelism
-
-The configured limits may be an integer or `auto`.
-
-`auto` means the orchestrating agent must choose, for each scheduling cycle, the largest concurrency it can reliably coordinate without unacceptable risk. Consider:
-- DAG independence;
-- likely file/module/contract overlap;
-- shared mutable state and migrations;
-- unresolved or interacting decisions;
-- task size and uncertainty;
-- available runtime/subagent capabilities;
-- context-window and tool limits;
-- expected coordination/merge overhead;
-- token efficiency.
-
-The safe answer may be 1. Do not spawn workers merely because tasks are technically independent. Parallelize when the time/clarity benefit exceeds the context and coordination cost.
-
-When `auto` is used, record the chosen effective concurrency for the current cycle in `STATE.yaml` so another agent or reader can understand what is happening.
-
-## Execution
-
-1. Compute all ready tasks.
-2. Exclude tasks owned by another execution.
-3. Determine the maximum-safe set under configuration.
-4. Claim the complete selected set before implementation.
-5. Execute directly or delegate safe independent tasks.
-6. Apply approved conventions automatically; do not ask about already-settled rules.
-7. Run applicable cheap/deterministic gates during implementation where practical.
-8. Implement the smallest changes satisfying each task.
-9. Run narrow relevant checks first, then broader checks when needed.
-10. Create atomic commits when the environment permits; never include unrelated worktree changes.
-11. Mark completed tasks `done`, record commit SHAs when available, recompute readiness, and synchronize state.
-
-If implementation exposes a consequential unapproved decision, STOP affected work, preserve completed independent work, record the pending decision using the required decision format, and return control to the orchestrator for developer input.
-
-If implementation reveals additional required work, add a task or backlog work item with real dependencies instead of silently expanding scope.
-
-## Scope guard
-
-Do not opportunistically refactor unrelated code. Record separate technical/maintenance work when useful.
-
-## Token-efficiency rules
-
-Token efficiency is a first-class optimization alongside correctness and maintainability:
-- never provide each worker the full project history;
-- prefer SUMMARY + exact relevant sections/IDs;
-- avoid rereading completed specs and large historical sources;
-- avoid multiple agents doing the same repository exploration;
-- prefer deterministic tools/tests over reasoning-heavy review where possible;
-- do not generate long execution narratives;
-- use Git for implementation history;
-- choose sequential execution when delegation overhead would cost more than it saves.

package/skills/flow-new/SKILL.md

@@ -1,104 +0,0 @@
----
-name: flow-new
-description: Bootstrap Flow from a broad idea or existing project sources, resolve consequential global product and engineering decisions, define a production-capable MVP, and create the initial work DAG.
----
-
-# Flow New
-
-## Objective
-
-Create enough shared product, engineering, infrastructure, and quality context to define a coherent production-capable MVP without prematurely specifying work-item details.
-
-## Readability principle
-
-Flow is readability first. Write canonical artifacts so a reader can understand the project without knowing Flow internals. Prefer clear prose and explicit names over compressed notation.
-
-## Inputs
-
-Support all of these without changing the workflow contract:
-- greenfield idea;
-- existing PRD/PRFAQ/specifications;
-- existing codebase;
-- existing codebase plus product documentation.
-
-Existing source documents are inputs, not permanent runtime context. Synthesize them into small canonical `.flow/` artifacts and refer back to sources only when a later work item requires specific detail.
-
-## Global discovery
-
-Resolve only consequential global decisions needed to define:
-- product problem, users, boundaries, and MVP outcome;
-- production constraints and deployment model;
-- architecture and project/module boundaries;
-- infrastructure, persistence, integrations, security/privacy, observability, and operations;
-- global testing strategy and documentation expectations;
-- reusable quality gates;
-- technical constraints that shape product scope or work ordering.
-
-Do not ask work-item-level questions that can safely wait for just-in-time planning.
-
-## Decision authority
-
-The agent MUST NOT silently make a consequential product or technical decision.
-
-A decision is consequential when materially different choices can change product scope/behavior, MVP composition, architecture, module boundaries, public contracts, persistent data semantics, production infrastructure, security/privacy, operational cost/model, testing strategy, reusable quality gates, or cross-work assumptions.
-
-Infer without asking when a choice is low-impact, reversible, and has a clear ecosystem/repository convention. Do not ask trivial convention questions such as kebab-case vs snake_case when the selected language/framework or existing repository establishes a normal choice.
-
-## Decision batch protocol
-
-Ask the largest set of consequential decisions that are CURRENTLY KNOWN and can be answered independently. Do not speculate about future scenarios merely to enlarge a batch.
-
-If decision B depends on decision A, ask A first and defer B until A is resolved.
-
-Every decision presented for approval MUST include:
-1. **Decision** — what must be chosen.
-2. **Context** — why the choice exists now and why it matters.
-3. **Options** — realistic alternatives and their meaningful trade-offs.
-4. **Recommended option** — exactly one when a recommendation is possible.
-5. **Why recommended** — concise reasoning grounded in current constraints.
-6. **Impact** — product, engineering, gates, and work items likely affected.
-
-Record unresolved consequential decisions as `pending_user` in `DECISIONS.yaml`. After a choice is provided, record the accepted choice and synchronize affected canonical artifacts.
-
-## MVP rule
-
-Discovery MUST converge on a production-capable MVP, not only a feature list. Include both product and technical work required to build, validate, deploy, and operate the MVP at its intended scale.
-
-Stop global discovery when there are no unresolved global decisions necessary to define a coherent production-capable MVP and its initial work DAG.
-
-## Work DAG
-
-Populate `BACKLOG.yaml` with work items of kind:
-- `feature` — user/product capability;
-- `technical` — enabling architecture, infrastructure, quality, or platform work;
-- `maintenance` — reconciliation, migration, refactor, or corrective work created by later decisions.
-
-Dependencies represent real blockers only. A work item may be impacted by a decision without depending on another work item.
-
-Use universal IDs (`W001`, `W002`, ...). Work item folders use `<sequence-padded><kind-code>-<slug>` where `F` = feature, `T` = technical, and `M` = maintenance. Examples: `001F-user-profile`, `002T-production-baseline`, `003M-auth-reconciliation`. The numeric prefix is a stable readable sequence, NOT execution order; the DAG controls execution.
-
-## Gates
-
-During discovery, propose reusable gates when they materially increase confidence in approved engineering/product rules. Explicit approval is required for consequential reusable gate policy. Prefer command gates for objectively testable rules and agentic gates for judgment-based policy.
-
-## Required outputs
-
-Synchronize automatically:
-- `.flow/PRD.md`
-- `.flow/ENGINEERING.md`
-- `.flow/SUMMARY.md`
-- `.flow/DECISIONS.yaml`
-- `.flow/BACKLOG.yaml`
-- `.flow/STATE.yaml`
-- `.flow/gates/` when gates are approved
-
-The user must never need to say “update state/docs”.
-
-## Token-efficiency rules
-
-- Synthesize large source documents once; do not keep re-reading them wholesale.
-- Read only source sections needed to resolve the current decision.
-- Do not map the whole repository when targeted inspection answers the question.
-- Avoid duplicated prose across PRD, ENGINEERING, SUMMARY, and decisions.
-- `SUMMARY.md` is a concise derived view, not another source of truth.
-- Do not spawn subagents unless parallel research/inspection has clear value greater than coordination/context overhead.

package/skills/flow-next/SKILL.md

@@ -1,55 +0,0 @@
----
-name: flow-next
-description: Autonomous Flow orchestrator: advance all currently safe work through planning, build, gates, review, fixes, reconciliation, and completion until a consequential decision or real blocker requires developer input.
----
-
-# Flow Next
-
-## Objective
-
-Make Flow autonomous by default. The user should not manually drive feature -> build -> review transitions or remind the agent to synchronize state.
-
-## Stop conditions
-
-Continue automatically until one of the configured conditions occurs:
-- consequential decision requires explicit approval;
-- external approval/action cannot be safely performed autonomously;
-- unrecoverable blocker;
-- no ready work remains;
-- configuration explicitly says not to continue across work items.
-
-`continue_across_work_items: true` means that after one work item passes review and closes, immediately recompute the work DAG and continue with the next safe ready work instead of waiting for another command.
-
-## Main loop
-
-1. Read `config.yaml`, `STATE.yaml`, `BACKLOG.yaml`, `SUMMARY.md`.
-2. Respect all work/tasks already marked `in_progress` under other execution IDs.
-3. If global discovery is incomplete, invoke/follow `flow-new` until it completes or requires a decision.
-4. Reconcile any `needs_reconciliation` work before execution when necessary.
-5. Compute ready work items from dependencies, decision impacts, status, and ownership.
-6. Determine the maximum-safe work-item set under parallelism configuration.
-7. Mark the selected work items `in_progress` with the current run/execution ID BEFORE planning/delegation.
-8. Plan unplanned items via `flow-plan` semantics. If a consequential decision emerges, preserve independent progress and stop only the affected path; present the maximal currently-known independent decision batch.
-9. Build ready planned work via `flow-build` semantics, including safe task parallelism and delegation when beneficial.
-10. Run configured gates and `flow-review` semantics.
-11. If review creates fix tasks, return them automatically to build and review again.
-12. Close passing work items, create maintenance work for completed items impacted by new decisions, synchronize canonical artifacts, and recompute the DAG.
-13. If `continue_across_work_items` is true, continue the loop.
-
-## Decision discipline
-
-Never infer a consequential choice merely to preserve autonomy. Autonomy means doing everything that follows from approved rules; it does not mean owning approved product or engineering decisions.
-
-Every requested decision uses the six-part format: Decision, Context, Options, Recommended option, Why recommended, Impact.
-
-Batch the maximum set of currently-known decisions that do not depend on each other. Do not speculate about future decisions to make the batch larger.
-
-## Parallelism and token efficiency
-
-Parallelism-first means exploiting safe independent work, not maximizing agent count. Under `auto`, choose the largest concurrency that can be reliably coordinated given dependencies, overlap, uncertainty, context/tool capacity, merge risk, and token cost. Record the effective choice in state.
-
-Prefer one primary orchestrator. Spawn subagents/workers only when their independence and expected benefit justify extra context. Give each worker a narrow context packet and explicit ownership.
-
-## State synchronization
-
-Every transition that changes decisions, work status, tasks, gates, PRD, engineering definition, or project overview must synchronize the affected canonical artifacts before continuing. The user should never need to request housekeeping updates.