@caiqueoak/flow 0.2.1 → 0.3.0

package/README.md

@@ -1,134 +1,58 @@
 # Flow
 
-Flow is a readability-first, agent-agnostic software-development workflow for coding agents. It maximizes autonomous delivery while keeping consequential product and engineering decisions explicit and approved.
+Flow is a readability-first, agent-agnostic software delivery workflow for coding agents. It maximizes autonomous execution while keeping consequential product and engineering decisions under developer control.
 
-## Workflow
-
-```text
-idea / existing project
-        ↓
-global discovery
-(product + engineering + production constraints)
-        ↓
-independent consequential decisions, batched for approval
-        ↓
-production-capable MVP
-        ↓
-work DAG (feature + technical + maintenance)
-        ↓
-/flow-next
-        ↓
-plan → build → gates → review → fixes → done
-        ↓
-next safe work item automatically
-```
-
-The agent continues until it reaches a consequential decision, external approval, unrecoverable blocker, or no ready work. Every requested decision must include **Decision, Context, Options, Recommended option, Why recommended, and Impact**.
-
-## Project state
-
-```text
-.flow/
-├── config.yaml
-├── PRD.md
-├── ENGINEERING.md
-├── SUMMARY.md
-├── DECISIONS.yaml
-├── BACKLOG.yaml
-├── STATE.yaml
-├── gates/
-└── work-items/
-    ├── 001F-user-profile/
-    │   ├── SPEC.md
-    │   └── TASKS.yaml
-    ├── 002T-production-baseline/
-    │   ├── SPEC.md
-    │   └── TASKS.yaml
-    └── 003M-auth-reconciliation/
-        ├── SPEC.md
-        └── TASKS.yaml
-```
-
-`F`, `T`, and `M` mean **feature**, **technical**, and **maintenance**. The numeric prefix is a stable readable sequence, not execution order. Dependencies determine execution. `work-items` is intentionally generic enough to cover all three kinds while remaining explicit to readers.
-
-## CLI
-
-The CLI is intentionally small:
+## Install
 
 ```bash
-flow init
-flow install
-flow update
+npm install --save-dev @caiqueoak/flow
+npx flow init
 ```
 
-### Requirements
-
-Flow requires Node.js 18 or newer.
-
-- `flow init` creates `.flow/`.
-- `flow install` installs the bundled skills into a coding-agent skill directory.
-- `flow update` fetches the latest published Flow package and replaces the installed Flow skills.
+`flow init` is interactive, or use `--runtime codex,claude` in automation. Built-in adapters install the public `/flow` skill in `.codex/skills/flow/` or `.claude/skills/flow/`; a custom project-local skills directory is also available interactively.
 
-The CLI does **not** plan work, schedule tasks, invoke models, or orchestrate subagents. Those responsibilities stay in the skills and coding-agent runtime.
+Skills are always installed inside the current project. Runtime integration directories never contain project state. If `.flow/` already exists, `flow init` only adds coding-agent integrations and updates `.flow/config.yaml`; it does not modify canonical project artifacts.
 
-Use an explicit skill directory when needed:
+## Project bootstrap
 
-```bash
-flow install --target .agents/skills
-flow update --target .agents/skills
-```
-
-Then start a project in the coding agent:
+`flow init` creates only:
 
 ```text
-/flow-new "I want to build a diet app"
+.flow/
+└── config.yaml
 ```
 
-Normal operation after discovery is primarily:
+It does not create a PRD, engineering guide, backlog, state, decisions, work items, gates, or templates. The `/flow` skill creates those artifacts only when they become valid canonical project information.
 
-```text
-/flow-next
-```
+## Workflow
 
-## Parallelism
+There is one public skill:
 
-```yaml
-parallelism:
-  strategy: maximum_safe
-  max_concurrent_work_items: auto
-  max_concurrent_tasks_per_work_item: auto
-  delegation: allowed
+```text
+/flow
 ```
 
-`auto` means the orchestrating agent chooses the largest set it can safely coordinate for the current scheduling cycle. It considers real dependencies, decision dependencies, likely write/contract overlap, uncertainty, runtime/tool capacity, merge risk, and **token/coordination overhead**. It must prefer fewer workers when additional concurrency would waste tokens or lower confidence.
-
-Before work starts, selected work items/tasks are marked `in_progress` with an execution ID. Another chat or agent must respect those claims and choose other ready work. Flow has no automatic claim timeout and never silently steals in-progress work.
+Use `/flow <intent>` to start or change work, for example `/flow I want to build a diet app`. Use `/flow` with no extra input to continue from `.flow/STATE.md`.
 
-## Token efficiency
+Flow internally loads only the guidance needed for discovery, planning, build, review, or reconciliation. It asks only for consequential decisions and uses the largest safe degree of parallelism.
 
-Token efficiency is a framework constraint, not an afterthought. Skills must use the smallest sufficient context, avoid repeatedly loading historical documents, prefer targeted repository inspection, keep canonical artifacts concise, reuse accepted decisions, prefer deterministic gates to extra reviewer agents, and spawn subagents only when the expected parallel benefit exceeds duplicated context and coordination cost.
+## Update
 
-## Updates
+Updates are explicit:
 
-`flow update` is explicit and deterministic. The default project template also contains:
-
-```yaml
-updates:
-  check_on_run: true
-  auto_update: false
+```bash
+npx flow update
 ```
 
-For now, automatic checks are advisory rather than silently changing the installation. This avoids a framework update changing workflow behavior in the middle of active work. Projects can adopt a newer Flow version intentionally with `flow update`.
-
-## Package
+`flow update` updates the npm package and refreshes `/flow` for every coding agent configured in `.flow/config.yaml`. There is no background update check or automatic update mechanism.
 
-The executable is `flow`. The npm package is currently `@caiqueoak/flow` so it does not collide with the pre-existing unscoped `flow` package.
+## CLI
 
-```bash
-npx @caiqueoak/flow install --target .agents/skills
-npx @caiqueoak/flow init
+```text
+flow init
+flow update
+flow --version
+flow --help
 ```
 
-## Releases
-
-Flow follows [Semantic Versioning](https://semver.org/). A merge to `main` publishes only when the version in `package.json` does not already exist on npm. GitHub Actions runs the test and packaging checks, then publishes the package with provenance. Release PRs must update both `package.json` and `package-lock.json`.
+The CLI bootstraps project-local integrations and configuration. The coding agent plus `/flow` owns discovery, planning, scheduling, delegation, build, gates, review, reconciliation, and state synchronization.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {
@@ -13,7 +13,6 @@
   "files": [
     "src",
     "skills",
-    "templates",
     "README.md",
     "LICENSE"
   ],

package/skills/flow/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: flow
+description: Autonomous, readability-first software delivery workflow. Continue from project state or incorporate new intent, ask only for consequential decisions, then plan, build, validate, reconcile, and continue as far as safely possible.
+---
+
+# Flow
+
+## Public contract
+
+`/flow` is the only public workflow skill.
+
+- `/flow` with no additional intent continues from `.flow/STATE.md` as far as safely possible.
+- `/flow <freeform intent>` incorporates the intent into current project context and continues appropriately.
+- If `.flow/STATE.md` does not exist, begin global discovery using the idea, repository, or source documents supplied.
+
+Do not require the developer to know or invoke internal workflow phases.
+
+## Core principles
+
+1. **Readability first.** Canonical artifacts must be understandable without Flow internals.
+2. **Decision ownership.** The developer owns consequential product and engineering decisions; the agent executes within approved rules and obvious conventions.
+3. **Autonomy by default.** Continue until a consequential decision, external approval, unrecoverable blocker, or no-ready-work condition.
+4. **Just-in-time detail.** Resolve global decisions during discovery and work-item detail only when that item becomes active.
+5. **Production-aware MVP.** MVP includes product capability plus the technical, infrastructure, quality, deployment, and operational work needed to run it.
+6. **Parallelism first.** Execute the largest safe independent set while preserving correctness and token efficiency.
+7. **Automatic synchronization.** Keep state, decisions, PRD, engineering definition, backlog, specs, and summaries aligned.
+
+## Canonical project artifacts
+
+Create artifacts only when they become valid. `flow init` creates only `.flow/config.yaml`.
+
+Developer-facing knowledge is Markdown:
+
+- `.flow/PRD.md` - current global product truth and MVP boundary.
+- `.flow/ENGINEERING.md` - global engineering truth.
+- `.flow/SUMMARY.md` - concise project overview derived from canonical state.
+- `.flow/DECISIONS.md` - consequential decision record and rationale.
+- `.flow/STATE.md` - concise navigation/status view.
+- `.flow/work-items/<folder>/SPEC.md` - readable lifecycle/specification of one work item.
+
+Graph/control data is YAML:
+
+- `.flow/BACKLOG.yaml` - work-item DAG.
+- `.flow/work-items/<folder>/TASKS.yaml` - task DAG and execution ownership.
+
+Do not create completion logs. Completed `SPEC.md` files retain concise Overview and Validation sections.
+
+## Work item model
+
+- `feature` (`F`) - product/user capability.
+- `technical` (`T`) - architecture, infrastructure, platform, quality, deployment, or enabling work.
+- `maintenance` (`M`) - reconciliation, migration, refactor, or corrective work.
+
+Folder format is `<three-digit-sequence><kind-code>-<slug>` (for example, `001F-user-profile`). The sequence is a stable readability aid, never execution order. Dependencies determine readiness.
+
+## Decision authority
+
+Apply low-impact and conventional choices automatically. A decision requires developer approval when materially different choices affect product behavior or scope; architecture/public contracts; production infrastructure or cost; persistent data; security/privacy; testing strategy or gates; project-wide conventions; or other work-item assumptions.
+
+## Decision presentation protocol
+
+Every requested decision must use this readable structure:
+
+### Decision
+
+What needs to be chosen.
+
+### Problem
+
+The concrete uncertainty.
+
+### Context
+
+Relevant product, engineering, production, and existing-decision context.
+
+### Options
+
+Realistic alternatives and trade-offs.
+
+### Recommended option
+
+Exactly one recommendation when evidence permits.
+
+### Why recommended
+
+Concise justification grounded in current goals and constraints.
+
+### Approach
+
+The high-level direction following the recommendation.
+
+### Impact
+
+Affected definitions, rules, gates, work items, tasks, or implementation.
+
+Never hide a consequential choice inside an implementation plan. Batch the largest currently-known set of independent decisions; do not invent hypothetical questions.
+
+## Decision lifecycle and impact
+
+Decision states are `candidate`, `pending_user`, `accepted`, `rejected`, and `superseded`. Preserve the rationale in `DECISIONS.md`. Reconcile pending work before execution, stop only affected in-progress paths, and create maintenance work rather than rewriting completed history.
+
+## Internal workflow routing
+
+Load only the reference needed for current state:
+
+- Missing state or global definition: `references/discovery.md`
+- Ready/unplanned work: `references/planning.md`
+- Ready planned tasks: `references/build.md`
+- Completed implementation awaiting validation: `references/review.md`
+- Decision impact or inconsistent artifacts: `references/reconcile.md`
+
+## Orchestration loop
+
+1. Read `.flow/config.yaml`.
+2. Read only the minimum navigation context from `.flow/STATE.md` and `.flow/SUMMARY.md` when present.
+3. Classify new intent and its impact on canonical truth, backlog, active work, or execution detail.
+4. Respect work/tasks already `in_progress` under another execution ID.
+5. Route to the minimal internal reference.
+6. Claim selected work before parallel execution.
+7. Continue planning, build, gates, review, fixes/reconciliation, and completion without another invocation.
+8. Recompute readiness after completion and continue if configured.
+
+## Parallelism and gates
+
+`auto` means the largest safe concurrency the orchestrator can reliably coordinate, considering dependencies, shared decisions/files/contracts, integration risk, available capacity, context complexity, and token overhead. It is not unlimited. Prefer one primary orchestrator and delegate only where independent substantial work justifies it.
+
+Gates may be deterministic commands or agentic policy checks. Define/refine them during discovery or planning when relevant. Build agents know applicable gates before implementation; review validates requirements, integration, and blocking gates.
+
+## Git and token efficiency
+
+Follow the approved Git strategy in `ENGINEERING.md`; by default create one atomic commit per completed task. Read the minimum relevant canonical context, avoid repeated large-document ingestion and duplicate prose, reuse accepted decisions, prefer deterministic checks, and delegate only with narrow ownership/context packets.

package/skills/flow/references/artifact-guidance.md

@@ -0,0 +1,5 @@
+# Canonical Artifact Guidance
+
+Create canonical project files only when they become valid. `PRD.md` holds global product truth; `ENGINEERING.md` holds current global engineering truth; `SUMMARY.md` is a concise derived orientation view; `STATE.md` is a concise navigation/status view; and `DECISIONS.md` preserves consequential decisions, options, rationale, and impacts.
+
+`BACKLOG.yaml` is the work-item DAG. Each work item has a readable `SPEC.md` and a `TASKS.yaml` task DAG with status, dependencies, acceptance/validation, and optional ownership areas. Do not create a separate completion log: keep delivered behavior and validation in the completed spec.

package/skills/flow/references/build.md

@@ -0,0 +1,5 @@
+# Build
+
+Compute ready tasks, exclude claims by another execution ID, select the largest safe set, and mark it `in_progress` before editing or delegating. Load only relevant specs, decisions, code, and gates. Follow approved conventions, avoid unrelated refactors, run the cheapest relevant deterministic checks, make atomic commits, and mark tasks complete only after acceptance checks pass.
+
+Synchronize TASKS, STATE, and affected canonical artifacts at each meaningful transition. If a consequential new choice emerges, stop only the affected path and present the decision while independent paths continue when safe.

package/skills/flow/references/discovery.md

@@ -0,0 +1,13 @@
+# Global Discovery
+
+## Goal
+
+Define the smallest coherent, production-capable MVP and the global product/engineering rules required to plan it. Do not specify work-item detail prematurely.
+
+## Scope
+
+Resolve only consequential global decisions affecting the problem, users, MVP, business constraints, production environment, deployment, architecture, persistence, integrations, security, observability, testing, conventions, documentation, Git strategy, and reusable gates. Infer trivial conventions from the existing codebase or chosen ecosystem.
+
+## Outputs
+
+Create or update only valid canonical artifacts: `PRD.md`, `ENGINEERING.md`, `DECISIONS.md`, `BACKLOG.yaml`, `STATE.md`, `SUMMARY.md`, and approved gate definitions. Discovery ends when no unresolved global decision is needed for a coherent production-capable MVP and initial work-item DAG.

package/skills/flow/references/planning.md

@@ -0,0 +1,5 @@
+# Work-item Planning
+
+Read only relevant global decisions, backlog context, existing spec/tasks, and source. Ask consequential work-item decisions only when viable answers materially change behavior, contracts, data semantics, technical boundaries, security, UX, or gates.
+
+Create `.flow/work-items/<id>/SPEC.md` with goal, scope/non-goals, relevant decisions, approach, requirements, acceptance criteria, gates, dependencies/impacts, and validation. Create `TASKS.yaml` with bounded, testable, independently executable tasks, real blocking dependencies only, and concise acceptance/validation expectations.

package/skills/flow/references/reconcile.md

@@ -0,0 +1,3 @@
+# Reconciliation
+
+Keep canonical truth and active plans aligned when new intent or accepted decisions affect work. Reconcile pending/planned work before execution, preserve unaffected in-progress work, and create maintenance work for completed work that must change. Preserve superseded decisions with links to their replacements. Update only artifacts whose current truth changed.

package/skills/flow/references/review.md

@@ -0,0 +1,3 @@
+# Review
+
+Verify completed work against its spec and applicable gates: inspect task completion and diff, validate requirements and acceptance criteria, run deterministic blocking gates, then applicable agentic gates, and check integration/regressions. Create targeted fix tasks within approved scope; request a decision only for consequential new choices. On success, update the spec Overview and Validation, then synchronize backlog, state, and summary.

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,170 @@ 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 copyDir(source, target, { overwrite = false } = {}) {
+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() {
+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 rl.question('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(); }
+}
+
+async function promptText(message, defaultValue = '') {
+  const rl = readline.createInterface({ input: inputStream, output: outputStream });
+  try {
+    const answer = (await rl.question(`${message}${defaultValue ? ` [${defaultValue}]` : ''}: `)).trim();
+    return answer || defaultValue;
+  } 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 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}`);
-    return;
+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 selected = parseRuntimeFlag() || 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.'); }
+}
 
-  info(`Updating Flow skills ${VERSION} → ${latest}...`);
-  const execArgs = ['exec', '--yes', `--package=${PACKAGE_NAME}@${latest}`, '--', 'flow', 'install', '--target', target, '--force'];
+function dependencySection(root) {
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) return '--save-dev';
   try {
-    execFileSync(npmCommand(), execArgs, { stdio: 'inherit' });
-  } catch {
-    fail('update failed. Your existing installation was not intentionally removed.');
-  }
-  info(`Skills updated to Flow ${latest}.`);
-  info(`If Flow itself is globally installed, update the CLI with: npm install -g ${PACKAGE_NAME}@latest`);
+    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 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.');
+  info(`Updating ${PACKAGE_NAME}...`);
+  try { execFileSync(npmCommand(), ['install', dependencySection(root), `${PACKAGE_NAME}@latest`], { cwd: root, stdio: 'inherit' }); }
+  catch { fail('npm update failed. Existing project state and installed skills were not intentionally removed.'); }
+  const packageRoot = path.join(root, 'node_modules', '@caiqueoak', 'flow');
+  if (!fs.existsSync(path.join(packageRoot, 'package.json'))) fail(`updated package not found at ${path.relative(root, packageRoot)}.`);
+  const latest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  for (const runtime of config.runtimes) info(`✓ ${runtime.type}: ${path.relative(root, installRuntimeSkill(root, runtime, 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.\nThere is no flow install command and no automatic/background update mechanism.`);
 }
 
-if (args.length === 0 || hasFlag('--help') || hasFlag('-h')) help();
+if (!args.length || 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.`);
-  }
-}
+else if (args[0] === 'init') await initProject();
+else if (args[0] === 'update') update();
+else fail(`unknown command '${args[0]}'. Run flow --help.`);

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.

package/skills/flow-plan/SKILL.md

@@ -1,86 +0,0 @@
----
-name: flow-plan
-description: Plan a ready feature, technical, or maintenance work item just in time, resolve consequential local decisions, reconcile cross-work impacts, define gates, and create a dependency-aware task DAG.
----
-
-# Flow Plan
-
-## Objective
-
-Turn one ready work item into an implementation-ready specification and task DAG while preserving all approved global product and engineering decisions.
-
-## Context loading
-
-Start with `.flow/STATE.yaml`, `.flow/BACKLOG.yaml`, and `.flow/SUMMARY.md`. Read only the relevant sections of `PRD.md`, `ENGINEERING.md`, `DECISIONS.yaml`, and gates needed for this work item. Do not reload unrelated completed work.
-
-## Work item selection
-
-Plan a requested work item or the highest-priority ready work item selected by the orchestrator. Mark it `in_progress` with the current `execution_id` before beginning mutating work.
-
-Create `.flow/work-items/<sequence-padded><kind-code>-<slug>/SPEC.md` and `TASKS.yaml` from templates.
-
-## Just-in-time discovery
-
-Ask detailed questions only when answers materially affect this work item's behavior, scope, UX, contracts, data semantics, architecture application, infrastructure interaction, security/reliability, acceptance criteria, or gates.
-
-Reuse accepted global decisions. Applying an approved rule is not a new decision.
-
-Do not ask trivial implementation questions when a clear language/framework/repository convention or approved engineering rule provides the answer.
-
-## Consequential decisions
-
-Never silently choose a consequential local or global decision. Use the same six-part decision format as `flow-new`: Decision, Context, Options, Recommended option, Why recommended, Impact.
-
-Batch the maximum set of currently-known independent decisions; do not invent speculative future cases to create a larger batch.
-
-If a work-item decision establishes or changes a project-wide rule, treat it as a global technical/product decision, obtain developer approval, record it in `DECISIONS.yaml`, update `PRD.md` or `ENGINEERING.md`, and calculate impacted work.
-
-## Reconciliation and cross-work impact
-
-When a new accepted decision impacts another work item:
-- pending/ready/planned item: mark `needs_reconciliation` when its assumptions/spec may be stale;
-- in-progress item owned by another execution: do not modify its work; record the impact and surface the coordination issue;
-- completed item: create a `maintenance` work item when code/data/config must be reconciled or migrated.
-
-Decision impact is not the same as dependency. Use dependencies only for actual execution blockers.
-
-## Gates
-
-Resolve all global gates applicable to the work item. During planning, propose work-item-specific gates when needed. If a proposed gate establishes a reusable project-wide standard, it requires developer approval and should be promoted to `.flow/gates/`. Keep one-off validation criteria in `SPEC.md`.
-
-## Task DAG
-
-Each task must include:
-- ID and clear title;
-- status;
-- `depends_on` with only real blockers;
-- affected areas when reasonably predictable;
-- concise acceptance criteria;
-- decision/gate references when relevant;
-- execution ID when claimed.
-
-Validate the DAG is acyclic. Do not create explicit waves; execution groups are derived dynamically from the DAG and conflict analysis.
-
-## Specification readability
-
-`SPEC.md` is the readable lifecycle document for the work item. Use:
-- Overview
-- Goal
-- Scope / Non-Goals
-- Product Decisions
-- Engineering Decisions
-- Requirements
-- Acceptance Criteria
-- Dependencies & Impact
-- Validation Gates
-- Validation Result
-- Delivery Notes
-
-Keep it concise. Update `Overview` on completion to reflect what was actually delivered. Do not create a completion-log or separate summary file per work item.
-
-## Token-efficiency rules
-
-- Inspect only code likely relevant to current decisions/tasks.
-- Reuse global definitions instead of copying them into the spec.
-- Refer to decision/gate IDs instead of duplicating long policies.
-- Avoid research unless current evidence is insufficient for a consequential decision.

package/skills/flow-review/SKILL.md

@@ -1,47 +0,0 @@
----
-name: flow-review
-description: Validate implemented work against its spec and configured gates, create targeted fixes or maintenance work, and close the work item automatically when it passes.
----
-
-# Flow Review
-
-## Objective
-
-Provide the final safety net after build while avoiding redundant re-analysis already covered by deterministic or approved agentic gates.
-
-## Required behavior
-
-1. Read the active SPEC/TASKS, relevant diff/commits, applicable gate definitions, and only the global decisions/engineering rules needed to validate them.
-2. Verify every requirement and acceptance criterion.
-3. Run all applicable blocking command gates and targeted checks.
-4. Run applicable agentic gates only for policy that tools cannot determine reliably.
-5. Check cross-task integration, obvious regressions, unexpected scope changes, and contract mismatches.
-6. Produce manual validation steps only where automated/agentic validation cannot establish confidence.
-
-## Failure
-
-If review fails:
-- create narrow fix tasks with real dependencies;
-- leave the work item `in_progress`;
-- return it to build automatically;
-- create maintenance work instead of reopening completed unrelated items directly.
-
-If review exposes a consequential decision, stop the affected path and use the required decision presentation protocol. Never silently resolve it during review.
-
-## Success
-
-When review passes:
-- mark the work item `done`;
-- update the SPEC `Overview`, `Validation Result`, and concise `Delivery Notes`;
-- update BACKLOG and STATE;
-- synchronize SUMMARY only when project-level understanding materially changed (for example work-item completion, MVP progress, architecture/production model, or key decision change);
-- recompute the ready work graph.
-
-Do NOT create `COMPLETION-LOG.md` or a separate per-work-item summary.
-
-## Token-efficiency rules
-
-- Do not repeat analysis already proven by command gates.
-- Review the smallest relevant diff/contract surface.
-- Avoid general-purpose reviewer subagents when a targeted gate answers the question.
-- Keep review output concise and write only durable information to canonical artifacts.

package/skills/flow-status/SKILL.md

@@ -1,26 +0,0 @@
----
-name: flow-status
-description: Orient a developer or fresh agent from small readable Flow state without rediscovering the repository.
----
-
-# Flow Status
-
-## Objective
-
-Explain where the project is, what is running, what is blocked, and what can run next with minimal context.
-
-## Required behavior
-
-1. Read `.flow/SUMMARY.md`, `.flow/STATE.yaml`, and `.flow/BACKLOG.yaml`.
-2. Read active work-item TASKS/SPEC only when needed for active progress details.
-3. Report concisely:
-   - project stage and MVP progress;
-   - active/in-progress work items and execution IDs;
-   - ready work items;
-   - pending consequential decisions;
-   - blockers/reconciliation work;
-   - current effective parallelism if work is active;
-   - recommended next action.
-4. Never scan the whole repository just to report status.
-5. Never silently reclaim another execution's in-progress work.
-6. Repair purely mechanical state inconsistencies only when the correct state is provable from canonical artifacts; otherwise surface the exact inconsistency.

package/templates/BACKLOG.yaml

@@ -1,15 +0,0 @@
-work_items: []
-
-# Work item example:
-# - id: W001
-#   sequence: 1
-#   kind: feature | technical | maintenance
-#   title: Example
-#   slug: example
-#   folder: 001F-example  # F=feature, T=technical, M=maintenance
-#   mvp: true
-#   priority: high
-#   status: pending | ready | in_progress | blocked | needs_reconciliation | done
-#   depends_on: []
-#   impacted_by: []
-#   execution_id: null

package/templates/DECISIONS.yaml

@@ -1,18 +0,0 @@
-decisions: []
-
-# Consequential decisions only.
-# Lifecycle: candidate -> pending_user -> accepted -> superseded | rejected
-# Recommended fields:
-# - id
-# - kind: product | technical
-# - scope: global | work_item
-# - subject
-# - status
-# - context
-# - options
-# - recommendation
-# - choice
-# - rationale
-# - depends_on
-# - affects
-# - superseded_by

package/templates/ENGINEERING.md

@@ -1,35 +0,0 @@
-# Engineering Definition
-
-## Overview
-
-_To be defined by `flow-new` from product requirements, production constraints, existing code, and approved technical decisions._
-
-## Production Environment & Constraints
-
-## Architecture
-
-## Project Structure & Boundaries
-
-## Data & Persistence
-
-## Integration & Communication Patterns
-
-## Infrastructure & Deployment
-
-## Security & Privacy Baseline
-
-## Observability & Operations
-
-## Testing Strategy
-
-## Engineering Principles
-
-## Naming & Code Conventions
-
-Record only conventions that are worth making explicit. Infer trivial ecosystem conventions when a clear language/framework/repository standard exists.
-
-## Documentation Standards
-
-## Quality Gates
-
-## Sources

package/templates/PRD.md

@@ -1,23 +0,0 @@
-# Product Definition
-
-## Overview
-
-_To be defined by `flow-new`._
-
-## Problem
-
-## Target Users
-
-## Product Principles
-
-## MVP Outcome
-
-## MVP Scope
-
-## Post-MVP Scope
-
-## Global Product Constraints
-
-## Non-Goals
-
-## Sources

package/templates/STATE.yaml

@@ -1,11 +0,0 @@
-stage: initialized
-active_work_items: []
-pending_decisions: []
-last_completed_work_item: null
-recommended_action: flow-new
-
-execution:
-  current_run_id: null
-  effective_parallelism:
-    work_items: 0
-    tasks: {}

package/templates/SUMMARY.md

@@ -1,29 +0,0 @@
-# Project Overview
-
-## What We Are Building
-
-_Not defined yet._
-
-## MVP
-
-_Not defined yet._
-
-## Key Product Decisions
-
-_None yet._
-
-## Key Engineering Decisions
-
-_None yet._
-
-## Production Model
-
-_Not defined yet._
-
-## Quality Model
-
-_Not defined yet._
-
-## Current Progress
-
-Project discovery has not been completed.

package/templates/TASKS.yaml

@@ -1,13 +0,0 @@
-tasks: []
-
-# Task example:
-# - id: T001
-#   title: Example
-#   status: pending | ready | in_progress | blocked | done
-#   depends_on: []
-#   affected_areas: []
-#   acceptance: []
-#   decision_refs: []
-#   gate_refs: []
-#   execution_id: null
-#   commit: null

package/templates/WORK_ITEM_SPEC.md

@@ -1,29 +0,0 @@
-# Work Item
-
-## Overview
-
-Concise explanation of what this work item changes and why it exists. On completion, update this section to describe what was actually delivered.
-
-## Goal
-
-## Scope
-
-## Non-Goals
-
-## Product Decisions
-
-## Engineering Decisions
-
-## Requirements
-
-## Acceptance Criteria
-
-## Dependencies & Impact
-
-## Validation Gates
-
-## Validation Result
-
-## Delivery Notes
-
-Keep this concise. Git history carries implementation history; do not duplicate it here.

package/templates/config.yaml

@@ -1,29 +0,0 @@
-schema_version: 1
-framework_version: 0.2.0
-
-workflow:
-  autonomous_until:
-    - consequential_decision
-    - external_approval
-    - unrecoverable_blocker
-    - no_ready_work
-  continue_across_work_items: true
-
-parallelism:
-  strategy: maximum_safe
-  max_concurrent_work_items: auto
-  max_concurrent_tasks_per_work_item: auto
-  delegation: allowed
-
-execution:
-  primary_orchestrator: true
-
-commands:
-  test: null
-  lint: null
-  typecheck: null
-  build: null
-
-updates:
-  check_on_run: true
-  auto_update: false

package/templates/gates/README.md

@@ -1,19 +0,0 @@
-# Quality Gates
-
-This directory contains reusable project-wide validation gates created or refined during project discovery and work-item planning.
-
-A gate should be concise, readable, and actionable. Prefer deterministic command checks when tools can verify a rule reliably; use agentic policy gates only when judgment is required.
-
-Suggested frontmatter:
-
-```yaml
----
-id: architecture-boundaries
-kind: agentic # agentic | command
-blocking: true
-applies_when:
-  - architecture_changed
----
-```
-
-A gate may be introduced during a work item. If it establishes a reusable project-wide rule, treat that as a consequential technical decision and obtain developer approval before promoting it to this directory.