@caiqueoak/flow 0.3.0 → 0.3.2

package/README.md

@@ -11,7 +11,7 @@ npx flow init
 
 `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.
 
-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.
+Skills are always installed inside the current project. Runtime integration directories never contain project state. If `.flow/` already exists, `flow init` only adds missing coding-agent integrations and updates `.flow/config.yaml`. If all built-in integrations are already configured, it exits without prompting. It does not modify canonical project artifacts.
 
 ## Project bootstrap
 
@@ -22,7 +22,7 @@ Skills are always installed inside the current project. Runtime integration dire
 └── config.yaml
 ```
 
-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.
+It does not create a PRD, engineering guide, backlog, graph, state, decisions, work items, gates, or templates. During `/flow`, new project documents and artifacts are created only when the developer explicitly requests or authorizes them. Flow updates existing approved artifacts instead of inventing ad-hoc progress, summary, handoff, or status documents.
 
 ## Workflow
 
@@ -34,17 +34,31 @@ There is one public skill:
 
 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`.
 
-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.
+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. Once execution is underway, it does not stop merely to announce completed tasks, progress, or next steps; it continues automatically until developer input, external approval, an unrecoverable blocker, or no ready work requires a real stop.
+
+When authorized, Flow keeps a concise artifact model: product truth in `PRD.md`, engineering truth in `ENGINEERING.md`, decisions in `DECISIONS.md`, execution context in `STATE.md`, the canonical work-item DAG in `BACKLOG.yaml`, and a human-readable derived projection in `GRAPH.md`. Work items use `SPEC.md` plus `TASKS.yaml`. `SUMMARY.md` is not part of the model.
+
+In `GRAPH.md`, work-item states are consistent: complete is green, in progress is blue, blocked is red when unfinished dependencies remain, and pending is yellow when all dependencies are complete and the item is ready to execute. Each Mermaid card contains only the work-item ID and canonical title. Every dependency arrow goes from dependency to dependent item and uses the color and line style of its source card.
 
 ## Update
 
 Updates are explicit:
 
 ```bash
-npx flow update
+flow update
 ```
 
-`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.
+`flow update` detects how the active Flow CLI is installed. If the project contains `@caiqueoak/flow`, it updates that project dependency; if the CLI is globally installed, it updates the global package instead. It then refreshes `/flow` for every coding agent configured in `.flow/config.yaml` without modifying canonical project state.
+
+On Windows, npm is invoked through the command shell so `npm.cmd` can be executed correctly. When Flow is installed as a project dependency, `npx flow update` is equivalent.
+
+There is no background update check or automatic update mechanism.
+
+## Releases
+
+Merges to `main` are released automatically after the test matrix passes. The release pipeline uses npm Trusted Publishing (OIDC), creates a signed npm provenance record, and tags the release; no npm token or manual version bump is needed.
+
+Use Conventional Commit prefixes in the PR title (and retained commits): `fix:` produces a patch, `feat:` a minor, and `feat!:` or a `BREAKING CHANGE:` footer a major release. `docs:`, `test:`, `chore:`, and `ci:` do not publish a package.
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {

package/skills/flow/SKILL.md

@@ -19,31 +19,35 @@ Do not require the developer to know or invoke internal workflow phases.
 
 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.
+3. **Autonomy by default.** Continue until a consequential decision requiring developer input, 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.
+7. **Automatic synchronization.** Keep state, decisions, PRD, engineering definition, backlog, graph, specs, and tasks aligned.
+8. **Artifact restraint.** Never create a new project document or artifact unless the developer explicitly requests or authorizes it. Update existing approved artifacts instead whenever possible.
+9. **Execution continuity.** Do not pause execution merely to report progress, completion, or next steps. Continue automatically while ready work exists. Surface status only when execution has actually stopped or when developer input is required.
 
 ## Canonical project artifacts
 
-Create artifacts only when they become valid. `flow init` creates only `.flow/config.yaml`.
+Create artifacts only when they become valid and only when the developer has explicitly requested or authorized their creation. `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/STATE.md` - concise current execution/navigation checkpoint and resume context.
+- `.flow/GRAPH.md` - human-readable derived projection of the work-item dependency graph and current readiness state.
 - `.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/BACKLOG.yaml` - canonical work-item DAG and work-item state.
 - `.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.
+Do not create `SUMMARY.md`, completion logs, ad-hoc progress documents, handoff documents, reports, or any other new project artifact unless the developer explicitly requests or authorizes them. Completed `SPEC.md` files retain concise Overview and Validation sections.
+
+`GRAPH.md` is derived only. It must never become an independent source of truth and must be reconciled whenever work-item existence, title, dependencies, or status change. Before creating or changing it, read `references/graph.md` and follow that contract exactly; do not preserve an established style that conflicts with it.
 
 ## Work item model
 
@@ -53,6 +57,15 @@ Do not create completion logs. Completed `SPEC.md` files retain concise Overview
 
 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.
 
+Work-item states are derived consistently:
+
+- `complete` (`✅`, green) - the item is completed.
+- `in_progress` (`🔵`, blue) - the item has active execution.
+- `blocked` (`🔴`, red) - the item is neither complete nor in progress and at least one work-item dependency is not complete.
+- `pending` (`🟡`, yellow) - the item is neither complete nor in progress and every work-item dependency is complete; it is ready to execute.
+
+The graph must use these meanings consistently for nodes and outgoing dependency-line styling.
+
 ## 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.
@@ -108,17 +121,21 @@ Load only the reference needed for current state:
 - Ready planned tasks: `references/build.md`
 - Completed implementation awaiting validation: `references/review.md`
 - Decision impact or inconsistent artifacts: `references/reconcile.md`
+- Creating or updating `GRAPH.md`: additionally load `references/graph.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.
+2. Read only the minimum navigation context from `.flow/STATE.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.
+8. Recompute work-item states and readiness after every meaningful transition, synchronize `BACKLOG.yaml`, `STATE.md`, and `GRAPH.md`, and continue if ready work exists.
+9. Do not stop or return control merely to announce that a task/work item completed or to describe the next step. Stop only when developer input is required for a consequential decision, an external approval is required, an unrecoverable blocker prevents useful progress, or no ready work remains.
+
+When execution stops, report the stopping reason and the smallest relevant status summary. During uninterrupted execution, avoid progress-only messages.
 
 ## Parallelism and gates
 

package/skills/flow/references/build.md

@@ -2,4 +2,6 @@
 
 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.
+Synchronize `TASKS.yaml`, `BACKLOG.yaml`, `STATE.md`, `GRAPH.md`, and other affected approved canonical artifacts at each meaningful transition. Never create a new document or artifact unless the developer explicitly requested or authorized it. If a consequential new choice emerges, stop only the affected path and present the decision while independent paths continue when safe.
+
+Do not pause or return control merely to report that a task or work item completed, to announce progress, or to state the next step. Recompute readiness and continue automatically while useful ready work exists. Surface execution status only when developer input is required or execution has actually stopped.

package/skills/flow/references/discovery.md

@@ -10,4 +10,6 @@ Resolve only consequential global decisions affecting the problem, users, MVP, b
 
 ## 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.
+Update valid canonical artifacts when their truth changes. Create `PRD.md`, `ENGINEERING.md`, `DECISIONS.md`, `BACKLOG.yaml`, `STATE.md`, `GRAPH.md`, work-item artifacts, or gate definitions only when the developer explicitly requested or authorized creation of that artifact class. Never create substitute, progress, summary, handoff, or ad-hoc documents to capture information that belongs in an existing approved artifact.
+
+`GRAPH.md` is a derived human-readable projection of `BACKLOG.yaml`, not an independent source of truth. Discovery ends when no unresolved global decision is needed for a coherent production-capable MVP and initial work-item DAG.

package/skills/flow/references/graph.md

@@ -0,0 +1,62 @@
+# `GRAPH.md` Rules
+
+Every Flow `GRAPH.md` must be a derived, human-readable projection of
+`.flow/BACKLOG.yaml`. It never becomes an independent source of truth.
+
+## Card content
+
+Each Mermaid card contains exactly two lines:
+
+```text
+<work-item ID>
+<work-item title>
+```
+
+Do not include status, priority, folder, dependency lists, or explanatory
+prose inside a card. The title is the canonical `title` value from
+`BACKLOG.yaml`.
+
+## Status derivation and colors
+
+Derive status from the backlog and dependencies after every meaningful state
+transition.
+
+| Status | Meaning | Card color | Outgoing arrow style |
+| --- | --- | --- | --- |
+| Complete | Work item is accepted and complete. | Green (`#16a34a`) | Solid green |
+| In progress | Work item has active execution. | Blue (`#2563eb`) | Solid blue, thicker |
+| Pending | Every dependency is complete and the item is ready to start. | Yellow (`#d97706`) | Dashed yellow |
+| Blocked | The item is neither complete nor in progress and one or more dependencies are incomplete. | Red (`#dc2626`) | Dotted red |
+
+Use matching fill, stroke, and readable text colors for cards. Every graph
+must include a titled status legend using these colors.
+
+## Dependencies and arrows
+
+- Draw one arrow for every `depends_on` relationship in `BACKLOG.yaml`.
+- The arrow goes from dependency to dependent item.
+- Every outgoing arrow inherits the color and line style of its source card.
+- Recalculate Mermaid `linkStyle` indexes whenever edges change; do not leave
+  a stale style assignment behind.
+- Do not add visual-only dependency edges to force layout.
+
+## Parallelism and layout
+
+- Items on the same vertical rank must have no dependency on one another and
+  are candidates for parallel work.
+- Keep independent, ready items on the same vertical rank where Mermaid can
+  represent the real dependency graph without artificial edges.
+- Do not represent blocked items as pending merely because they are planned;
+  dependency readiness determines their graph status.
+
+## Synchronization checklist
+
+When work-item state, existence, title, or dependencies change:
+
+1. Update `BACKLOG.yaml` first.
+2. Recompute derived statuses using the definitions above.
+3. Update `GRAPH.md`, including cards, arrows, styles, legend, and parallel
+   layout.
+4. Update `STATE.md` when the active path or next ready work changes.
+5. Verify that every backlog item appears exactly once and every dependency
+   appears exactly once in the graph.

package/skills/flow/references/planning.md

@@ -2,4 +2,6 @@
 
 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.
+For an already authorized work-item artifact class, create or update `.flow/work-items/<id>/SPEC.md` with goal, scope/non-goals, relevant decisions, approach, requirements, acceptance criteria, gates, dependencies/impacts, and validation. Create or update `TASKS.yaml` with bounded, testable, independently executable tasks, real blocking dependencies only, and concise acceptance/validation expectations.
+
+If the required `SPEC.md` or `TASKS.yaml` does not yet exist and the developer has not explicitly requested or authorized creation of that artifact class, request authorization before creating it. Do not create substitute planning documents. After planning, continue automatically into ready execution instead of stopping to report the plan unless a consequential developer decision is required.

package/skills/flow/references/reconcile.md

@@ -1,3 +1,5 @@
 # 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.
+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 approved artifacts whose current truth changed, including the derived `GRAPH.md` whenever work-item existence, dependencies, or status change.
+
+Never create a new document or artifact during reconciliation unless the developer explicitly requested or authorized it. After reconciliation, recompute readiness and continue execution automatically when safe rather than pausing to report status.

package/skills/flow/references/review.md

@@ -1,3 +1,5 @@
 # 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.
+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.yaml`, `STATE.md`, `GRAPH.md`, and other affected approved canonical artifacts.
+
+Never create a new document or artifact during review unless the developer explicitly requested or authorized it. Do not stop merely to announce successful validation or the next ready work item; return to orchestration and continue while useful ready work exists.

package/src/cli.mjs

@@ -27,6 +27,38 @@ function valueAfter(name) { const i = args.indexOf(name); return i >= 0 ? args[i
 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 runNpm(npmArgs, options = {}) {
+  return execFileSync(npmCommand(), npmArgs, {
+    ...options,
+    shell: process.platform === 'win32'
+  });
+}
 
 function copyDir(source, target) {
   fs.mkdirSync(target, { recursive: true });
@@ -82,6 +114,11 @@ function parseRuntimeFlag() {
   return raw ? raw.split(',').map((x) => x.trim().toLowerCase()).filter(Boolean) : null;
 }
 
+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 }));
@@ -92,7 +129,7 @@ async function promptMultiSelect(existing) {
   const rl = readline.createInterface({ input: inputStream, output: outputStream });
   try {
     while (true) {
-      const answer = (await rl.question('Selection: ')).trim();
+      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.');
@@ -103,7 +140,7 @@ async function promptMultiSelect(existing) {
 async function promptText(message, defaultValue = '') {
   const rl = readline.createInterface({ input: inputStream, output: outputStream });
   try {
-    const answer = (await rl.question(`${message}${defaultValue ? ` [${defaultValue}]` : ''}: `)).trim();
+    const answer = (await question(rl, `${message}${defaultValue ? ` [${defaultValue}]` : ''}: `)).trim();
     return answer || defaultValue;
   } finally { rl.close(); }
 }
@@ -129,7 +166,15 @@ async function initProject() {
     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 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;
+  }
+
+  const selected = requested || await promptMultiSelect(config.runtimes);
   const knownTypes = new Set(config.runtimes.map((r) => r.type));
   const added = [];
   for (const type of selected) {
@@ -156,29 +201,88 @@ function dependencySection(root) {
   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 {
+    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'
+    };
+  }
+
+  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.');
-  info(`Updating ${PACKAGE_NAME}...`);
-  try { execFileSync(npmCommand(), ['install', dependencySection(root), `${PACKAGE_NAME}@latest`], { cwd: root, stdio: 'inherit' }); }
+
+  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.'); }
-  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))}`);
+
+  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>] [--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.`);
+  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 || 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.`);
+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/references/artifact-guidance.md

@@ -1,5 +0,0 @@
-# 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.