@caiqueoak/flow 0.4.0 → 0.5.0

package/src/shared/profiles.mjs

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import { parse } from 'yaml';
+const text = fs.readFileSync(
+  new URL('../../skills/flow/engineering/profiles/readability-first.md', import.meta.url),
+  'utf8'
+);
+export const READABILITY_FIRST_PROFILE = parse(text.match(/^---\n([\s\S]*?)\n---/)[1]);
+export const ENGINEERING_PROFILES = {
+  'readability-first': READABILITY_FIRST_PROFILE,
+  [READABILITY_FIRST_PROFILE.id]: READABILITY_FIRST_PROFILE
+};
+export const BROWNFIELD_POLICIES = {
+  improve: {
+    label: 'Improve existing structure — Recommended',
+    description:
+      'Preserve behavior and external contracts; recommend clearer structure where justified. Does not authorize refactoring.'
+  },
+  preserve: {
+    label: 'Keep existing structure',
+    description: 'Retain consistent conventions unless a concrete problem warrants an approved change.'
+  }
+};

package/src/shared/project-config.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+
+export function configPath(root) {
+  return path.join(root, '.flow', 'config.yaml');
+}
+
+export function defaultConfig() {
+  return {
+    schema_version: 2,
+    runtimes: [],
+    engineering: { profile: 'flow/readability-first@1', existing_code_policy: 'not_applicable' }
+  };
+}
+
+export function readConfig(root) {
+  const file = configPath(root);
+  if (!fs.existsSync(file)) return null;
+  const raw = parse(fs.readFileSync(file, 'utf8')) ?? {};
+  const config = defaultConfig();
+  config.schema_version = raw.schema_version ?? 1;
+  config.runtimes = Array.isArray(raw.runtimes) ? raw.runtimes : [];
+  config.engineering = { ...config.engineering, ...(raw.engineering ?? {}) };
+  return config;
+}
+
+export function writeConfig(root, config) {
+  const normalized = {
+    schema_version: 2,
+    runtimes: config.runtimes ?? [],
+    engineering: {
+      profile: config.engineering?.profile ?? defaultConfig().engineering.profile,
+      existing_code_policy: config.engineering?.existing_code_policy ?? 'not_applicable'
+    }
+  };
+  fs.mkdirSync(path.join(root, '.flow'), { recursive: true });
+  fs.writeFileSync(configPath(root), stringify(normalized, { lineWidth: 0 }), 'utf8');
+}

package/src/shared/project-path.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path';
+
+export function valueAfter(args, name) {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+export function projectRoot(args) {
+  return path.resolve(valueAfter(args, '--path') || process.cwd());
+}

package/src/shared/skill-installer.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function copyDirectory(source, target) {
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) copyDirectory(sourcePath, targetPath);
+    else fs.copyFileSync(sourcePath, targetPath);
+  }
+}
+
+export function installRuntimeSkill(root, runtime, packageRoot) {
+  if (
+    typeof runtime.skills_path !== 'string' ||
+    !runtime.skills_path ||
+    path.isAbsolute(runtime.skills_path) ||
+    runtime.skills_path.split(/[\\/]/).includes('..')
+  )
+    throw new Error('Runtime skills_path must remain project-local.');
+  const target = path.join(root, runtime.skills_path, 'flow');
+  let ancestor = root;
+  for (const segment of path.relative(root, target).split(path.sep)) {
+    ancestor = path.join(ancestor, segment);
+    if (fs.existsSync(ancestor) && fs.lstatSync(ancestor).isSymbolicLink())
+      throw new Error('Refusing a symlinked runtime path.');
+  }
+  if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink())
+    throw new Error('Refusing to overwrite a symlinked skill.');
+  fs.rmSync(target, { recursive: true, force: true });
+  copyDirectory(path.join(packageRoot, 'skills', 'flow'), target);
+  return target;
+}

package/skills/flow/references/build.md

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

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

@@ -1,74 +0,0 @@
-# `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.
-
-## Generation
-
-After every change to work-item existence, title, status, or dependencies, run:
-
-```text
-flow graph --path .
-```
-
-The command validates the backlog DAG and regenerates the complete file. Do
-not edit `GRAPH.md` directly. It always emits Mermaid with `curve: 'linear'`;
-do not replace that setting or introduce curved arrows.
-
-## 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

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

@@ -1,161 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { parseDocument } from 'yaml';
-
-const KINDS = new Set(['feature', 'technical', 'maintenance']);
-const STATUSES = new Set(['completed', 'in_progress', 'pending', 'blocked']);
-
-export class GraphValidationError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'GraphValidationError';
-  }
-}
-
-function compareIds(left, right) { return left < right ? -1 : left > right ? 1 : 0; }
-function fail(message) { throw new GraphValidationError(message); }
-function requireString(value, label) {
-  if (typeof value !== 'string' || !value.trim()) fail(`${label} must be a non-empty string.`);
-  return value;
-}
-function requireObject(value, label) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${label} must be a mapping.`);
-  return value;
-}
-
-function parseBacklog(text) {
-  const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
-  if (document.errors.length) fail(`BACKLOG.yaml is invalid: ${document.errors[0].message}`);
-  const backlog = requireObject(document.toJS(), 'BACKLOG.yaml');
-  if (backlog.schema_version !== 1) fail('BACKLOG.yaml schema_version must be 1.');
-  requireString(backlog.source_of_truth, 'BACKLOG.yaml source_of_truth');
-  if (!Array.isArray(backlog.work_items)) fail('BACKLOG.yaml work_items must be a list.');
-
-  const ids = new Set();
-  const items = backlog.work_items.map((raw, index) => {
-    const label = `work_items[${index}]`;
-    const item = requireObject(raw, label);
-    const id = requireString(item.id, `${label}.id`);
-    if (ids.has(id)) fail(`BACKLOG.yaml contains duplicate work-item ID '${id}'.`);
-    ids.add(id);
-    const folder = requireString(item.folder, `${label}.folder`);
-    if (!KINDS.has(item.kind)) fail(`${label}.kind must be feature, technical, or maintenance.`);
-    const title = requireString(item.title, `${label}.title`);
-    if (!STATUSES.has(item.status)) fail(`${label}.status must be completed, in_progress, pending, or blocked.`);
-    if (!Number.isInteger(item.priority) || item.priority < 1) fail(`${label}.priority must be a positive integer.`);
-    if (!Array.isArray(item.depends_on)) fail(`${label}.depends_on must be a list.`);
-    const dependencySet = new Set();
-    for (const dependency of item.depends_on) {
-      requireString(dependency, `${label}.depends_on entry`);
-      if (dependency === id) fail(`Work item '${id}' cannot depend on itself.`);
-      if (dependencySet.has(dependency)) fail(`Work item '${id}' lists dependency '${dependency}' more than once.`);
-      dependencySet.add(dependency);
-    }
-    return { id, folder, kind: item.kind, title, status: item.status, priority: item.priority, depends_on: [...dependencySet] };
-  });
-  const byId = new Map(items.map((item) => [item.id, item]));
-  for (const item of items) for (const dependency of item.depends_on) {
-    if (!byId.has(dependency)) fail(`Work item '${item.id}' depends on unknown work item '${dependency}'.`);
-  }
-  return items;
-}
-
-function topology(items) {
-  const byId = new Map(items.map((item) => [item.id, item]));
-  const remaining = new Map(items.map((item) => [item.id, item.depends_on.length]));
-  const dependents = new Map(items.map((item) => [item.id, []]));
-  for (const item of items) for (const dependency of item.depends_on) dependents.get(dependency).push(item.id);
-  for (const ids of dependents.values()) ids.sort(compareIds);
-  const ready = items.filter((item) => item.depends_on.length === 0).map((item) => item.id).sort(compareIds);
-  const levels = new Map(ready.map((id) => [id, 0]));
-  const orderedIds = [];
-  while (ready.length) {
-    const id = ready.shift();
-    orderedIds.push(id);
-    for (const dependent of dependents.get(id)) {
-      levels.set(dependent, Math.max(levels.get(dependent) ?? 0, levels.get(id) + 1));
-      const count = remaining.get(dependent) - 1;
-      remaining.set(dependent, count);
-      if (count === 0) { ready.push(dependent); ready.sort(compareIds); }
-    }
-  }
-  if (orderedIds.length !== items.length) fail('BACKLOG.yaml work-item dependencies contain a cycle.');
-  const ordered = orderedIds.map((id) => byId.get(id)).sort((left, right) => (levels.get(left.id) - levels.get(right.id)) || compareIds(left.id, right.id));
-  return { ordered, byId };
-}
-
-function displayStatus(item, byId) {
-  if (item.status === 'completed') return 'complete';
-  if (item.status === 'in_progress') return 'active';
-  const derived = item.depends_on.every((id) => byId.get(id).status === 'completed') ? 'pending' : 'blocked';
-  if (item.status !== derived) fail(`Work item '${item.id}' is declared ${item.status} but derives as ${derived}.`);
-  return derived;
-}
-
-function escapeMermaid(text) {
-  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-const CLASS_DEFINITIONS = [
-  '  classDef complete fill:#dcfce7,stroke:#16a34a,color:#14532d;',
-  '  classDef active fill:#dbeafe,stroke:#2563eb,color:#1e3a8a;',
-  '  classDef pending fill:#fef3c7,stroke:#d97706,color:#78350f;',
-  '  classDef blocked fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;'
-];
-const LINK_STYLES = {
-  complete: 'stroke:#16a34a,stroke-width:2px',
-  active: 'stroke:#2563eb,stroke-width:3px',
-  pending: 'stroke:#d97706,stroke-width:2px,stroke-dasharray:6 3',
-  blocked: 'stroke:#dc2626,stroke-width:2px,stroke-dasharray:2 3'
-};
-
-export function generateGraphMarkdown(backlogText) {
-  const items = parseBacklog(backlogText);
-  const { ordered, byId } = topology(items);
-  const statuses = new Map(ordered.map((item) => [item.id, displayStatus(item, byId)]));
-  const edges = ordered.flatMap((source) => ordered
-    .filter((target) => target.depends_on.includes(source.id))
-    .map((target) => ({ source: source.id, target: target.id, status: statuses.get(source.id) })));
-  const lines = [
-    '# Work-item dependency graph', '', '## Status', '',
-    '- <span style="color:#16a34a">Complete</span> — all work accepted.',
-    '- <span style="color:#2563eb">In progress</span> — active delivery path.',
-    '- <span style="color:#d97706">Pending</span> — all dependencies complete; ready to start.',
-    '- <span style="color:#dc2626">Blocked</span> — one or more dependencies remain incomplete.',
-    '', '```mermaid',
-    "%%{init: {'flowchart': {'curve': 'linear', 'nodeSpacing': 32, 'rankSpacing': 54}} }%%",
-    'flowchart TD'
-  ];
-  for (const item of ordered) lines.push(`  ${item.id}["${escapeMermaid(item.id)}<br/>${escapeMermaid(item.title)}"]`);
-  lines.push('');
-  for (const edge of edges) lines.push(`  ${edge.source} --> ${edge.target}`);
-  lines.push('', ...CLASS_DEFINITIONS);
-  for (const status of ['complete', 'active', 'pending', 'blocked']) {
-    const ids = ordered.filter((item) => statuses.get(item.id) === status).map((item) => item.id);
-    if (ids.length) lines.push(`  class ${ids.join(',')} ${status};`);
-  }
-  for (const status of ['complete', 'active', 'pending', 'blocked']) {
-    const indices = edges.map((edge, index) => edge.status === status ? index : null).filter((index) => index !== null);
-    if (indices.length) lines.push(`  linkStyle ${indices.join(',')} ${LINK_STYLES[status]};`);
-  }
-  lines.push(
-    '```', '',
-    'Cards in the same vertical rank have no dependency between them and can be',
-    'worked in parallel. Arrow color and line style are inherited from the source',
-    'card: solid green for complete, solid blue for active, dashed yellow for',
-    'pending, and dotted red for blocked.', ''
-  );
-  return lines.join('\n');
-}
-
-export function writeGraph(projectRoot) {
-  const flowDir = path.join(projectRoot, '.flow');
-  const backlogPath = path.join(flowDir, 'BACKLOG.yaml');
-  if (!fs.existsSync(backlogPath)) fail(`Backlog not found: ${backlogPath}`);
-  const markdown = generateGraphMarkdown(fs.readFileSync(backlogPath, 'utf8'));
-  const graphPath = path.join(flowDir, 'GRAPH.md');
-  const temporaryPath = path.join(flowDir, `.GRAPH.md.${process.pid}.${Date.now()}.tmp`);
-  fs.writeFileSync(temporaryPath, markdown, 'utf8');
-  fs.renameSync(temporaryPath, graphPath);
-  return { graphPath, markdown };
-}