ftown-bridge 0.11.0 → 0.11.2

package/skills/ftown-workflows/SKILL.md

@@ -22,6 +22,147 @@ human-in-the-loop playbook). Use ftown-workflows when the work is scripted and
 repeatable; use ftown-orchestrator when you need to improvise or keep a human in
 the loop.
 
+## Operating Contract
+
+Use ftown-workflows to encode deterministic multi-session control flow: fan-out,
+verification, synthesis, loops, retries, and resumable handoffs. The workflow
+script is where the structure lives: which workers run independently, which
+results are verified, where a barrier is necessary, and what gets returned.
+
+Do not infer workflow permission just because a task might benefit from
+parallelism. Run a workflow only when the user explicitly asks for one, asks for
+multi-agent orchestration, asks to fan out workers, names `ftown-workflows`, asks
+to run a specific workflow, or invokes a skill/command whose instructions require
+this skill. Otherwise, answer inline or describe the workflow you would run and
+ask before spending the user's tokens.
+
+If the user explicitly says this task **must use ftown-workflows**, a manual
+simulation is not enough. Create a `.flow.mjs` script and run it with
+`~/.ftown/ftown-workflows`.
+
+## Scout First
+
+Start with a cheap inline scout before writing the workflow script: list relevant
+files, search call sites, scope the diff, read key modules, and identify whether
+the task is understanding, design, review, research, migration, or greenfield
+build. You do not need the final DAG before starting the task; you need the
+work-list and shape before orchestration.
+
+Common single-phase shapes:
+
+| Intent | Shape |
+| --- | --- |
+| Understand | readers over subsystems -> structured map |
+| Design | independent approaches -> judge panel -> scored synthesis |
+| Review or audit | dimensions -> find -> adversarial verify -> synthesis |
+| Research | search/read sweep -> deep read -> verify -> cited synthesis |
+| Migrate | discover sites -> transform isolated slices -> verify |
+| Greenfield build | scout stack -> contract-first prep -> modules -> compile/review |
+
+For large work, run several small workflows in sequence instead of one giant
+script. Read each result before deciding the next phase. A practical split is:
+
+```text
+discovery-design.flow.mjs -> implementation-review.flow.mjs
+```
+
+The discovery/design workflow discovers constraints, compares approaches, writes
+a durable handoff (`discovery-design.handoff.json`, `plan.json`, `specs/`, a
+rubric), and stops. The implementation/review workflow consumes that handoff,
+implements the work-list, integrates, verifies, and repairs against the rubric.
+
+## Pipeline By Default
+
+Default to `ctx.pipeline(...)` for multi-stage work. Each item should advance as
+soon as its previous stage finishes; do not make fast items wait for the slowest
+item unless the next stage genuinely needs all prior results at once.
+
+A barrier with `ctx.parallel(...)` is correct when a later stage needs
+cross-item context:
+
+- deduping or merging all findings before expensive verification
+- early exit when the full result set is empty
+- comparing one finding against the other findings
+
+A barrier is not justified by ordinary mapping/filtering, by conceptual phase
+boundaries, or by code tidiness. Put per-item transforms inside a pipeline stage.
+When unsure, pipeline.
+
+Use explicit `phase` names in `ctx.agent(..., { phase })` inside pipelines and
+parallel stages so progress groups are stable even when stages interleave.
+
+## Quality Patterns
+
+Pick and compose these patterns based on the user's request:
+
+- **Adversarial verify:** for each claim/finding, spawn independent skeptics
+  asked to refute it. Keep a finding only if it survives the vote.
+- **Perspective-diverse verify:** use distinct verifier lenses such as
+  correctness, security, performance, reproducibility, and UX instead of cloned
+  prompts.
+- **Judge panel:** generate multiple independent solutions, have judges score
+  them, then synthesize from the winner while preserving useful ideas from
+  runners-up.
+- **Loop-until-dry:** for unknown-size discovery, keep launching finder rounds
+  until a fixed number of consecutive rounds returns nothing new.
+- **Multi-modal sweep:** search by different axes (file path, call graph,
+  content, timestamp, dependency, runtime behavior) and merge findings.
+- **Completeness critic:** end with a worker that asks what was missed: unread
+  sources, unverified claims, uncovered modalities, or dropped work.
+- **No silent caps:** if you cap coverage, sampling, retries, or result counts,
+  log what was skipped with `ctx.log()`.
+
+Scale to the wording. "Find any bugs" can be a small finder set and one verifier.
+"Thoroughly audit" or a large explicit budget should increase finder diversity,
+verification votes, and loop-until-dry depth.
+
+## Dependent Phases
+
+`ctx.agent()` returns `null` instead of throwing when a worker times out, exits
+without a result, exhausts budget, or writes `{ "ok": false }`. That is useful
+for optional fan-out, but dangerous for dependent phases. Fail fast before
+implementation, verification, or synthesis depends on a missing result.
+
+Use this guard in workflow scripts:
+
+```js
+function requireAgentResult(value, label) {
+  if (value == null) {
+    throw new Error(`${label} failed; aborting dependent workflow phases`);
+  }
+  return value;
+}
+```
+
+Optional fan-out may filter failures with `.filter(Boolean)`. Required handoffs,
+module implementations, verifiers, and final synthesis should use the guard.
+
+## Greenfield Builds
+
+When a workflow is building a whole app, game, service, library, or system from
+scratch, the discovery/design phase should include contract-first prep before
+implementation fan-out. Read and apply:
+
+```text
+~/.claude/skills/contract-first-prep/SKILL.md
+~/.claude/skills/contract-first-prep/references/contract-guide.md
+```
+
+The prep worker should produce the parallel-safe handoff:
+
+- minimal scaffold with a strict typecheck/build gate
+- immutable type/interface contract for cross-module boundaries
+- pure-data config plus shared low-level helpers
+- disjoint module decomposition (`plan.json`) and per-module specs
+
+The later implementation/review workflow treats that contract, config, and shared
+helpers as frozen. Workers adapt their modules to the contract; only the
+integrator performs broad wiring. If review finds a design flaw, launch a new
+discovery/design workflow instead of letting implementers redesign in parallel.
+
+Skip contract-first prep for small edits, single-file scripts, or established
+codebases that already have their own architecture.
+
 ## Running a workflow
 
 You must be **inside an ftown session** — `FTOWN_SESSION_ID` must be set.
@@ -35,6 +176,12 @@ You must be **inside an ftown session** — `FTOWN_SESSION_ID` must be set.
 > workers become **siblings** of the orchestrator rather than its children. Results
 > are file-based, so this does not affect correctness — only the dashboard topology.
 
+Child/subagent sessions **can run workflows**. Do not refuse just because
+`FTOWN_PARENT_SESSION_ID` is set or because the current session was spawned by
+another agent. The only hard requirement is `FTOWN_SESSION_ID` plus a reachable
+bridge. The parent/child caveat above is about dashboard topology, not
+capability: results still flow through files under `~/.ftown/workflows/<run-id>/`.
+
 Full options:
 
 ```bash
@@ -101,7 +248,7 @@ Key options:
 |---|---|---|
 | `label` | `step-<n>` | step key used for the result file and resume |
 | `phase` | — | progress grouping shown in logs |
-| `schema` | — | JSON Schema; forces JSON result |
+| `schema` | — | JSON Schema embedded in the worker prompt; requests JSON result |
 | `shell` | run-level default | `claude` / `cursor` / `codex` / `opencode` / `shell` |
 | `model` | — | model override passed to the session |
 | `workdir` | run-level default | working directory for the child session |
@@ -173,83 +320,133 @@ once the result is read, or on timeout/exit.
 **You do not write this file yourself** — the child agent is instructed to do it.
 The prompt injected by the engine tells the child agent exactly what to write.
 
-## Patterns
+## Script Patterns
 
-### Parallel fan-out
+Scripts are plain JavaScript modules. Avoid nondeterministic labels or control
+flow (`Date.now()`, `Math.random()`, timestamp-derived labels) when you care
+about resume, because cached results are matched by step order and label.
 
-```js
-export default async function (ctx) {
-  const items = ctx.args.items;  // e.g. ["auth.ts", "api.ts", "db.ts"]
+### Canonical Pipeline
 
-  ctx.phase('Review');
-  const reviews = await ctx.parallel(
-    items.map(f => () => ctx.agent(`Review ${f} for security issues`, {
-      label: `review-${f}`,
-    }))
-  );
+Each item moves through review and verification independently. One file can be
+verifying while another is still reviewing.
 
-  ctx.phase('Synthesise');
-  const report = await ctx.agent(
-    `Synthesise these security reviews:\n${reviews.filter(Boolean).join('\n---\n')}`,
-    { label: 'synthesis' },
+```js
+export default async function (ctx) {
+  const results = await ctx.pipeline(
+    ctx.args.files,
+    (file) => ctx.agent(`Find bugs in ${file}`, {
+      label: `find-${file}`,
+      phase: 'Find',
+      schema: FINDINGS_SCHEMA,
+    }),
+    (review, file) => ctx.parallel(
+      (review?.findings ?? []).map((finding, i) => () => ctx.agent(
+        `Try to refute this finding:\n${JSON.stringify(finding)}`,
+        { label: `verify-${file}-${i}`, phase: 'Verify', schema: VERDICT_SCHEMA },
+      ).then((verdict) => ({ file, finding, verdict })))
+    ),
   );
 
-  return report;
+  return results.flat().filter(Boolean).filter((r) => r.verdict?.isReal);
 }
 ```
 
-### Pipeline (multi-stage per item)
+### Correct Barrier
+
+Use a barrier when deduplication or comparison needs every prior result.
 
 ```js
 export default async function (ctx) {
-  return ctx.pipeline(
-    ctx.args.files,
-    (file) => ctx.agent(`Lint ${file}`, { label: `lint-${file}` }),
-    (lintOut, file) => ctx.agent(`Fix ${file} based on: ${lintOut}`, { label: `fix-${file}` }),
-    (fixOut, file) => ctx.agent(`Write tests for ${file}`, { label: `test-${file}` }),
+  ctx.phase('Find');
+  const reviews = await ctx.parallel(
+    ctx.args.dimensions.map((d) => () => ctx.agent(d.prompt, {
+      label: `find-${d.key}`,
+      schema: FINDINGS_SCHEMA,
+    })),
   );
+
+  const allFindings = reviews.filter(Boolean).flatMap((r) => r.findings ?? []);
+  const deduped = dedupeByFileAndTitle(allFindings);
+  if (deduped.length === 0) return { confirmed: [] };
+
+  ctx.phase('Verify');
+  const verified = await ctx.parallel(
+    deduped.map((finding, i) => () => ctx.agent(
+      `Verify this deduped finding:\n${JSON.stringify(finding)}`,
+      { label: `verify-${i}`, schema: VERDICT_SCHEMA },
+    ).then((verdict) => ({ finding, verdict }))),
+  );
+
+  return { confirmed: verified.filter(Boolean).filter((r) => r.verdict?.isReal) };
 }
 ```
 
-### Adversarial verify (majority vote)
+### Loop Until Dry
+
+Use this for unknown-size searches. Dedup against everything seen, including
+rejected findings, so the loop converges.
 
 ```js
 export default async function (ctx) {
-  const claim = ctx.args.claim;
-  const REVIEWERS = 3;
-
-  ctx.phase('Verify');
-  const verdicts = await ctx.parallel(
-    Array.from({ length: REVIEWERS }, (_, i) =>
-      () => ctx.agent(
-        `You are a skeptical reviewer. Is this claim correct? "${claim}" Reply with just "yes" or "no".`,
-        { label: `skeptic-${i}` },
-      )
-    )
-  );
+  const seen = new Set();
+  const confirmed = [];
+  let dryRounds = 0;
+
+  while (dryRounds < 2 && ctx.budget.remaining() > 0) {
+    ctx.phase(`Find round ${dryRounds + 1}`);
+    const found = await ctx.agent('Find more bugs not already covered.', {
+      label: `find-round-${confirmed.length}-${dryRounds}`,
+      schema: FINDINGS_SCHEMA,
+    });
+
+    const fresh = (found?.findings ?? []).filter((finding) => {
+      const key = `${finding.file}:${finding.title}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+    if (fresh.length === 0) {
+      dryRounds += 1;
+      ctx.log(`dry round ${dryRounds}/2`);
+      continue;
+    }
+    dryRounds = 0;
+
+    const judged = await ctx.parallel(
+      fresh.map((finding, i) => () => ctx.agent(
+        `Try to refute this finding:\n${JSON.stringify(finding)}`,
+        { label: `judge-${seen.size}-${i}`, phase: 'Verify', schema: VERDICT_SCHEMA },
+      ).then((verdict) => ({ finding, verdict }))),
+    );
+    confirmed.push(...judged.filter(Boolean).filter((r) => r.verdict?.isReal));
+  }
 
-  const yes = verdicts.filter(v => v?.toLowerCase().startsWith('yes')).length;
-  return { claim, verdict: yes > REVIEWERS / 2 ? 'accepted' : 'rejected', votes: verdicts };
+  return { confirmed };
 }
 ```
 
-### Loop-until-dry
+### Budget-Bounded Depth
+
+Guard loops with a real cap. With no `--max-agents`, `ctx.budget.remaining()` is
+`Infinity`, so add an explicit round limit or require a max-agent budget.
 
 ```js
 export default async function (ctx) {
-  let queue = [...ctx.args.items];
-  const done = [];
-
-  while (queue.length > 0 && ctx.budget.remaining() > 0) {
-    ctx.phase(`Batch (${queue.length} remaining)`);
-    const batch = queue.splice(0, 4);
-    const results = await ctx.parallel(
-      batch.map(item => () => ctx.agent(`Process: ${item}`, { label: `proc-${item}` }))
-    );
-    done.push(...results.filter(Boolean));
+  const rounds = ctx.budget.maxAgents == null ? 3 : ctx.budget.maxAgents;
+  const results = [];
+
+  for (let i = 0; i < rounds && ctx.budget.remaining() > 0; i += 1) {
+    const result = await ctx.agent(`Research angle ${i + 1}`, {
+      label: `research-${i + 1}`,
+      schema: RESEARCH_SCHEMA,
+    });
+    if (result) results.push(result);
+    ctx.log(`${i + 1}/${rounds} research rounds complete`);
   }
 
-  return done;
+  return results;
 }
 ```
 

package/skills/ftown-workflows/scripts/example.flow.mjs

@@ -1,5 +1,5 @@
 /**
- * example.flow.mjs — template workflow: parallel code review fan-out + synthesis.
+ * example.flow.mjs - template workflow: review files, verify each finding, synthesize.
  *
  * Run it inside an ftown session:
  *
@@ -9,114 +9,162 @@
  *
  * Add --run-id <previous-id> to resume a partial run without re-running
  * steps whose result files already exist.
- *
- * The script exports a default async function that receives a WorkflowContext.
- * The engine wires FTOWN_SESSION_ID from the calling session so children are
- * registered as its children and are cleaned up on completion.
  */
 
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  required: ['findings'],
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title', 'file', 'severity', 'evidence'],
+        properties: {
+          title: { type: 'string' },
+          file: { type: 'string' },
+          severity: { type: 'string' },
+          evidence: { type: 'string' },
+          recommendation: { type: 'string' },
+        },
+      },
+    },
+  },
+};
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['isReal', 'reason'],
+  properties: {
+    isReal: { type: 'boolean' },
+    reason: { type: 'string' },
+  },
+};
+
+const REPORT_SCHEMA = {
+  type: 'object',
+  required: ['summary', 'confirmed', 'rejected'],
+  properties: {
+    summary: { type: 'string' },
+    confirmed: { type: 'array', items: { type: 'string' } },
+    rejected: { type: 'array', items: { type: 'string' } },
+  },
+};
+
+function requireAgentResult(value, label) {
+  if (value == null) {
+    throw new Error(`${label} failed; aborting dependent workflow phases`);
+  }
+  return value;
+}
+
+function stepKey(value) {
+  return String(value).replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '') || 'item';
+}
+
+function asFindings(value) {
+  return value && Array.isArray(value.findings) ? value.findings : [];
+}
+
 /**
  * @param {import('../../../src/workflow-runner.js').WorkflowContext} ctx
  */
 export default async function (ctx) {
-  // ── 1. Unpack args ──────────────────────────────────────────────────────────
-  // ctx.args is whatever was passed via --args (JSON-parsed).
-  // Provide a sensible fallback so the example runs without arguments too.
-  const files = /** @type {string[]} */ (
-    Array.isArray(ctx.args?.files)
-      ? ctx.args.files
-      : ['src/auth.ts', 'src/api.ts', 'src/db.ts']
-  );
+  const files = Array.isArray(ctx.args?.files)
+    ? ctx.args.files
+    : ['src/auth.ts', 'src/api.ts', 'src/db.ts'];
 
   ctx.phase('Setup');
   ctx.log(`Reviewing ${files.length} file(s): ${files.join(', ')}`);
   ctx.log(`Budget: ${ctx.budget.maxAgents ?? 'unlimited'} agents`);
 
-  // ── 2. Fan-out: one reviewer per file, all running in parallel ───────────────
-  // ctx.parallel() is a BARRIER — it waits for every thunk before returning.
-  // A thunk that errors or whose agent returns null produces a null entry;
-  // the whole call never rejects.
-  // The concurrency cap (--concurrency, default 4) limits how many real sessions
-  // run simultaneously — you can safely pass more thunks than the cap.
-  ctx.phase('Review');
-
-  const reviews = await ctx.parallel(
-    files.map((file) => async () => {
-      // Each thunk is an async function returning a string (or null on failure).
-      const result = await ctx.agent(
-        // The prompt is the full task description for this child session.
-        // Keep it self-contained — the child has no other context.
-        `You are a code reviewer. Review the file \`${file}\` for:
-- Security vulnerabilities (auth bypass, injection, secret leakage)
-- Correctness bugs (off-by-one, null dereference, missing error handling)
-- Style issues that reduce readability
-
-Reply with a concise bullet-point list. Start with "## ${file}".`,
+  const reviewed = await ctx.pipeline(
+    files,
+    async (file) => {
+      const review = await ctx.agent(
+        `Review ${file} for correctness, security, and maintainability bugs.
+Return only concrete findings with evidence. Do not include style preferences.`,
         {
-          // label becomes the step key and the result filename.
-          // Unique, filesystem-safe labels enable per-step resume.
-          label: `review-${file.replace(/[^a-z0-9]/gi, '-')}`,
-          // phase groups events in the log output.
-          phase: 'review',
-          // shell defaults to 'claude'; override here if needed.
-          // shell: 'claude',
+          label: `review-${stepKey(file)}`,
+          phase: 'Review',
+          schema: FINDINGS_SCHEMA,
         },
       );
 
-      if (result == null) {
-        ctx.log(`WARN: review of ${file} failed or timed out`);
+      return {
+        file,
+        findings: asFindings(requireAgentResult(review, `review ${file}`)),
+      };
+    },
+    async (review) => {
+      if (review.findings.length === 0) {
+        ctx.log(`No findings reported for ${review.file}`);
+        return { file: review.file, confirmed: [], rejected: [] };
+      }
+
+      const verified = await ctx.parallel(
+        review.findings.map((finding, index) => async () => {
+          const verdict = await ctx.agent(
+            `Try to refute this finding. Default to isReal=false if the evidence is weak,
+not reproducible, or not actually caused by the code.
+
+Finding:
+${JSON.stringify(finding, null, 2)}`,
+            {
+              label: `verify-${stepKey(review.file)}-${index}`,
+              phase: 'Verify',
+              schema: VERDICT_SCHEMA,
+            },
+          );
+
+          return {
+            finding,
+            verdict: requireAgentResult(verdict, `verify ${review.file} #${index + 1}`),
+          };
+        }),
+      );
+
+      const kept = [];
+      const rejected = [];
+      for (const item of verified.filter(Boolean)) {
+        if (item.verdict.isReal === true) kept.push(item.finding);
+        else rejected.push({ finding: item.finding, reason: item.verdict.reason });
       }
-      return result;
-    }),
-  );
 
-  // ── 3. Filter out any failed reviews before synthesising ────────────────────
-  const successfulReviews = reviews.filter(
-    /** @param {string | null} r */ (r) => r != null,
+      return { file: review.file, confirmed: kept, rejected };
+    },
   );
 
-  if (successfulReviews.length === 0) {
-    ctx.log('ERROR: all reviews failed — cannot synthesise');
-    return null;
-  }
+  const completed = reviewed.filter(Boolean);
+  const confirmed = completed.flatMap((entry) => entry.confirmed);
+  const rejected = completed.flatMap((entry) => entry.rejected);
 
-  ctx.log(`${successfulReviews.length}/${files.length} reviews succeeded`);
+  ctx.phase('Synthesis');
+  if (confirmed.length === 0) {
+    ctx.log('No confirmed findings survived verification');
+    return {
+      summary: 'No confirmed findings survived adversarial verification.',
+      confirmed: [],
+      rejected: rejected.map((entry) => entry.finding.title),
+    };
+  }
 
-  // ── 4. Single synthesis agent consolidates all reviewer findings ─────────────
-  // This is a sequential step — one agent, no parallelism needed.
-  ctx.phase('Synthesise');
+  const report = await ctx.agent(
+    `Write a concise final code-review report from these verified findings.
+Group by severity and include evidence. Mention rejected findings only if useful.
 
-  const synthesis = await ctx.agent(
-    `You are a senior engineer writing a final code-review report.
-Below are ${successfulReviews.length} individual file reviews.
-Consolidate them into a single report with:
-1. An executive summary (2-3 sentences).
-2. Critical issues (must fix before merge).
-3. Minor issues (nice to fix).
-4. Positive observations.
+Confirmed:
+${JSON.stringify(confirmed, null, 2)}
 
---- REVIEWS ---
-${successfulReviews.join('\n\n---\n\n')}`,
+Rejected:
+${JSON.stringify(rejected, null, 2)}`,
     {
       label: 'synthesis',
-      phase: 'synthesise',
-      // Use schema to get a structured JSON response instead of a string.
-      // When schema is set, agent() returns the parsed object (or null).
-      // Comment it out to get a plain string instead.
-      schema: {
-        type: 'object',
-        required: ['summary', 'critical', 'minor', 'positives'],
-        properties: {
-          summary: { type: 'string' },
-          critical: { type: 'array', items: { type: 'string' } },
-          minor: { type: 'array', items: { type: 'string' } },
-          positives: { type: 'array', items: { type: 'string' } },
-        },
-      },
+      phase: 'Synthesis',
+      schema: REPORT_SCHEMA,
     },
   );
 
-  // ── 5. Return value is printed by the CLI (pretty by default, --json for raw) ─
   ctx.log(`Done. Budget used: ${ctx.budget.spent()} agent spawn(s).`);
-  return synthesis;
+  return requireAgentResult(report, 'synthesis');
 }