@hassangameryt/freeflow 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "freeflow",
       "description": "Conversation, workflow, and strict-workflow skills for coding agents.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "category": "development",
       "source": "./plugins/freeflow",
       "author": {

package/README.md

@@ -22,7 +22,7 @@ Use strict-workflow for security, privacy, billing, public APIs, migrations, dat
 flowchart LR
   Request{request}
   Talk[conversation<br/>answer directly]
-  Discover[discover<br/>research / grill]
+  Discover[discover<br/>research checkpoint]
   Spec[spec]
   Plan[plan]
   Build[build<br/>execute / diagnose]
@@ -155,16 +155,17 @@ Use Freeflow workflow mode for this task.
 Keep this in conversation mode.
 Use strict-workflow for this billing change.
 Verify before claiming completion.
-Capture the durable decision.
+Create a research checkpoint.
 ```
 
-Slash-style prompts are model-routed in v0.1:
+Slash-style prompts are model-routed in Codex and Claude:
 
 ```text
 /workflow conversation
 /workflow workflow
 /workflow strict-workflow
 /workflow reset
+/research
 /write-spec
 /write-plan
 /execute-plan
@@ -196,7 +197,10 @@ Freeflow does not claim to beat Matt Pocock's skills or Obra's Superpowers. Thos
 | Write plan with hidden billing decision | 4/10 | 10/10 | Freeflow created no plan, named the policy conflict, and asked which path to follow. |
 | Cold spec call without context | 2/10 | 10/10 | Freeflow did not invent onboarding behavior from adjacent files. |
 | Workflow context lifecycle | fail | pass | Setup loads workflow context for the same session; session-start hooks load workflow context without `PostToolUse`. |
-| Command surface audit | - | Pass | 3 mode commands, 13 direct skill calls, and 2 developer skill calls are covered while native slash handlers remain disabled. |
+| Output router retrieval | - | 7/7 pass | Deterministic router evidence fixes generated-artifact false positives while keeping scanner retrieval default. |
+| Output router command recovery | - | 8/8 pass | `freeflow_run` preserves exact facts and verifies raw vault recovery for routed command output. |
+| Codex Structured Q&A | native proxy 0/1 | improved router 1/1 | Sandbox Permissions Q&A resolves to the source markdown instead of a generated `graphify-out` decoy. |
+| Command surface audit | - | Pass | 4 mode commands, 11 direct skill calls, and 2 developer skill calls are covered while native slash handlers remain disabled. |
 
 Eval sources and reports live with the plugin under `plugins/freeflow/evals/`; generated run output is ignored. Concise release evidence is summarized in [plugins/freeflow/docs/release-evidence.md](plugins/freeflow/docs/release-evidence.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightweight workflow for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -15,6 +15,14 @@
   },
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "build:router": "tsc -p plugins/freeflow/router/tsconfig.json",
+    "test:router": "npm run build:router && node --test plugins/freeflow/router/tests/*.test.js",
+    "bench:router": "npm run build:router && node plugins/freeflow/router/dist/benchmarks.js",
+    "bench:router:commands": "npm run build:router && node plugins/freeflow/router/dist/command-benchmarks.js",
+    "bench:router:index": "npm run build:router && node plugins/freeflow/router/dist/index-benchmarks.js",
+    "bench:router:codex-qa": "npm run build:router && node plugins/freeflow/router/dist/codex-qa-benchmarks.js"
+  },
   "keywords": [
     "pi-package",
     "agent-skills",
@@ -48,6 +56,11 @@
     "plugins/freeflow/docs/**",
     "plugins/freeflow/hooks/**",
     "plugins/freeflow/pi-extension/**",
+    "plugins/freeflow/router/dist/**",
     "plugins/freeflow/skills/**"
-  ]
+  ],
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "typescript": "^5.8.3"
+  }
 }

package/plugins/freeflow/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "freeflow",
   "description": "Lightweight workflow for coding agents. Conversation, workflow, and strict-workflow skills for planning, execution, review, verification, handoff, and decision capture.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": {
     "name": "Hassan Mohiddin"
   },

package/plugins/freeflow/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "freeflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightweight workflow for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"

package/plugins/freeflow/command-surface.json

@@ -20,12 +20,8 @@
   ],
   "directSkillCalls": [
     {
-      "command": "/grill-context",
-      "skill": "grill-context"
-    },
-    {
-      "command": "/research-brief",
-      "skill": "research-brief"
+      "command": "/research",
+      "skill": "research"
     },
     {
       "command": "/write-spec",
@@ -59,10 +55,6 @@
       "command": "/commit-work",
       "skill": "commit-work"
     },
-    {
-      "command": "/capture-decisions",
-      "skill": "capture-decisions"
-    },
     {
       "command": "/handoff",
       "skill": "handoff"

package/plugins/freeflow/docs/README.md

@@ -30,10 +30,11 @@ Or install directly from GitHub:
 pi install git:github.com/hassan-mohiddin/freeflow
 ```
 
-The package exposes `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`. The Pi extension registers direct Freeflow commands, keeps `/workflow` mode changes scoped to the Pi session, refreshes workflow and interview-gate context on session start and compact, and injects that context before agent turns. It does not enforce policy, block tools, grant permissions, or create repo-local hooks.
+The package exposes `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`. The Pi extension registers direct Freeflow commands, keeps `/workflow` mode changes scoped to the Pi session, refreshes workflow, interview-gate, and output-router context on session start and compact, and injects that context before agent turns. Output-router context includes its safety-policy reference. The extension does not enforce policy, block tools, grant permissions, or create repo-local hooks.
 
 - [Workflow](workflow.md): modes, entry points, loops, and the compact workflow map.
 - [Skills](skills.md): shipped skills and what each one is for.
 - [Architecture](architecture.md): package layout, runtime boundary, context hooks, and progressive disclosure model.
-- [Release evidence](release-evidence.md): v0.1 acceptance evidence and deferred checks.
+- [Output Router](output-router.md): compact guide to routed retrieval, command output routing, vault recovery, and config.
+- [Release evidence](release-evidence.md): current release evidence and deferred checks.
 - [ADRs](adr/README.md): durable release decisions.

package/plugins/freeflow/docs/adr/0002-evals-before-hooks.md

@@ -6,7 +6,7 @@ Accepted.
 
 ## Decision
 
-Freeflow v0.1 ships plugin-bundled context-loading runtime: Codex/Claude hooks and a Pi extension that load existing workflow and interview-gate context. It still ships without enforcement hooks or CLI enforcement. Behavior must first be proven with baseline-vs-with-skill evals before mechanical enforcement is added.
+Freeflow ships plugin-bundled context-loading runtime: Codex/Claude hooks and a Pi extension that load existing workflow and interview-gate context. It still ships without enforcement hooks or CLI enforcement. Behavior must first be proven with baseline-vs-with-skill evals before mechanical enforcement is added.
 
 ## Rationale
 

package/plugins/freeflow/docs/adr/0003-release-boundary.md

@@ -6,7 +6,7 @@ Accepted.
 
 ## Decision
 
-Freeflow v0.1 ships as a marketplace repo with one plugin runtime under `plugins/freeflow/`.
+Freeflow ships as a marketplace repo with one plugin runtime under `plugins/freeflow/`.
 
 The plugin runtime includes skills, bundled references, context-loading runtime, public docs, eval sources/reports, command-surface metadata, Codex/Claude metadata, and Pi package metadata/extension.
 

package/plugins/freeflow/docs/adr/0004-research-replaces-shallow-discovery-skills.md

@@ -0,0 +1,26 @@
+# ADR 0004: Research Replaces Shallow Discovery Skills
+
+## Status
+
+Accepted.
+
+## Decision
+
+Freeflow uses one active `research` skill for discovery work before spec, plan, build, or durable memory.
+
+The previous active skills `research-brief`, `grill-context`, and `capture-decisions` are deprecated and moved to root `deprecated/skills/`. They are no longer part of the runtime skill surface or direct command surface.
+
+The active direct command is `/research`.
+
+## Rationale
+
+The three older skills were useful independently but shallow as a workflow module. In real use, research, brainstorming, targeted questions, and decision checkpointing need to interleave. Splitting them made the user or agent coordinate the sequence and made long grilling chains or uncaptured research decisions more likely.
+
+The `research` skill uses the same module/interface/depth/seam/leverage/locality language as architecture review so discovery can shape deep modules from the beginning, not only rescue shallow code later.
+
+## Consequences
+
+- `/research-brief`, `/grill-context`, and `/capture-decisions` are removed from the current command surface.
+- Historical evals and reports for the deprecated skills remain as development evidence.
+- Current discovery eval evidence lives in `plugins/freeflow/evals/reports/by-skill/research-1-report.md`.
+- Durable decisions now belong to the checkpoint destination chosen by `research`: spec, plan, handoff, decision note, ADR, domain memory, or chat.

package/plugins/freeflow/docs/adr/README.md

@@ -4,4 +4,5 @@ Durable decisions for the public Freeflow package:
 
 - [ADR 0001: Three Workflow Modes](0001-three-modes.md)
 - [ADR 0002: Evals Before Enforcement Hooks](0002-evals-before-hooks.md)
-- [ADR 0003: v0.1 Release Boundary](0003-release-boundary.md)
+- [ADR 0003: Release Boundary](0003-release-boundary.md)
+- [ADR 0004: Research Replaces Shallow Discovery Skills](0004-research-replaces-shallow-discovery-skills.md)

package/plugins/freeflow/docs/architecture.md

@@ -4,7 +4,7 @@ Freeflow is a portable skill pack for coding agents.
 
 ## Runtime Boundary
 
-Freeflow ships Markdown skills, bundled references, lightweight context-loading hooks, and a Pi extension. It does not ship a CLI, Codex/Claude native slash handlers, enforcement hooks, or a new agent runtime in v0.1.
+Freeflow ships Markdown skills, bundled references, lightweight context-loading hooks, and a Pi extension. It does not ship a CLI, Codex/Claude native slash handlers, enforcement hooks, or a new agent runtime in this release.
 
 Host runtimes still control tools, sandboxing, approvals, and permissions. Freeflow controls workflow pressure:
 
@@ -77,10 +77,10 @@ Setup handles the same-session case directly: after successful setup verificatio
 
 Host runtimes may require plugin hooks to be reviewed and trusted after install. If the host skips untrusted hooks, setup still writes activation/config files, but future session-start runtime context will not load until hooks are trusted and the session is restarted, resumed, cleared, or compacted.
 
-Pi uses an extension instead of `hooks/hooks.json`. The Pi extension registers direct commands, reads `workflow/SKILL.md`, `workflow/references/workflow-map.md`, and `interview-gate/SKILL.md`, refreshes that context on `session_start` and `session_compact`, and injects it during Pi's `before_agent_start` lifecycle event. Pi `/workflow` commands set a session-scoped current-mode override, while `.freeflow/config.json` remains the default-mode source. It follows the same boundary as the Codex/Claude hooks: context loading only, no enforcement.
+Pi uses an extension instead of `hooks/hooks.json`. The Pi extension registers direct commands, reads `workflow/SKILL.md`, `workflow/references/workflow-map.md`, `interview-gate/SKILL.md`, `output-router/SKILL.md`, and `output-router/references/safety-policy.md`, refreshes that context on `session_start` and `session_compact`, and injects it during Pi's `before_agent_start` lifecycle event. The same extension registers `freeflow_retrieve` and `freeflow_run` and gives them compact/expanded TUI renderers so collapsed tool rows stay readable while `ctrl+o` shows structured evidence and recovery details. Pi `/workflow` commands set a session-scoped current-mode override, while `.freeflow/config.json` remains the default-mode source. It follows the same boundary as the Codex/Claude hooks: context loading only, no enforcement.
 
 ## Deferred Enforcement
 
 Enforcement hooks and CLI checks are intentionally deferred. They are useful only after skill wording and evals prove a repeated behavior needs mechanical enforcement.
 
-For v0.1, commands are model-routed language such as `/write-spec` or `/verify-work`; they are not native registered slash handlers.
+For this release, commands are model-routed language such as `/write-spec` or `/verify-work`; they are not native registered slash handlers.

package/plugins/freeflow/docs/output-router.md

@@ -0,0 +1,212 @@
+# Output Router
+
+Freeflow Output Router keeps agent context focused while preserving exact evidence outside context.
+
+Use it when broad repo exploration, generated artifacts, large logs, or noisy command output would otherwise flood the model.
+
+For the full architecture, see [`docs/designs/freeflow-output-router-architecture.md`](../../../docs/designs/freeflow-output-router-architecture.md) in the repo root.
+
+## Core Idea
+
+```text
+smallest sufficient evidence in context
++ exact raw recovery outside context
++ no surprise native tool semantics
+```
+
+The router ships two explicit tools:
+
+- `freeflow_retrieve`: retrieve targeted repo/vault evidence.
+- `freeflow_run`: run likely-large/noisy commands, vault raw output, and return compact evidence.
+
+Native tools still matter:
+
+- use native `read` for known whole files,
+- use native `bash` for small/direct raw shell behavior,
+- use native `edit`/`write` for mutations.
+
+## Tiny Map
+
+```mermaid
+flowchart LR
+  Agent[agent]
+  Retrieve[freeflow_retrieve]
+  Run[freeflow_run]
+  Repo[repo files]
+  Vault[Freeflow vault]
+  Native[native read/bash]
+  Evidence[bounded evidence]
+  Raw[exact recovery]
+
+  Agent -->|existing info| Retrieve
+  Agent -->|noisy command| Run
+  Agent -->|direct/raw known output| Native
+  Retrieve --> Repo --> Evidence
+  Retrieve --> Vault --> Evidence
+  Run --> Vault
+  Run --> Evidence
+  Vault --> Raw
+```
+
+## Tool Choice
+
+| Need | Use |
+| --- | --- |
+| Find repo evidence before reading files | `freeflow_retrieve action=query` |
+| Get candidate paths first | `freeflow_retrieve action=locate` |
+| Retrieve exact repo/vault lines | `freeflow_retrieve action=retrieve` with `lineRange` |
+| Widen previous evidence | `freeflow_retrieve action=expand` |
+| Explain a previous routed decision/output | `freeflow_retrieve action=explain` |
+| Run noisy/large command output | `freeflow_run` |
+| Read a known whole file | native `read` |
+| Run small exact command | native `bash` |
+
+## `freeflow_retrieve`
+
+Sources:
+
+- `repo`: local repo files.
+- `vault`: previous routed command/native output.
+
+Actions:
+
+- `query`: returns best evidence packets; default `topK=1`.
+- `locate`: returns candidate locations; default `topK=5`.
+- `retrieve`: returns explicit path/line range evidence.
+- `expand`: expands a previous evidence packet to `lines_30`, `lines_80`, or `full`.
+- `explain`: explains a route decision or vault output.
+
+Example:
+
+```json
+{
+  "action": "query",
+  "source": { "kind": "repo" },
+  "query": "Sandbox Permissions UseDefault RequireEscalated WithAdditionalPermissions",
+  "preserve": "important"
+}
+```
+
+Evidence packets include:
+
+- source/path,
+- line range,
+- exact excerpt,
+- why the router selected it,
+- expansion/recovery guidance.
+
+Repo retrieval uses deterministic scanner ranking by default. Broad scans skip generated/dependency/cache paths such as `graphify-out/**`, but explicit path retrieval remains available.
+
+## `freeflow_run`
+
+`freeflow_run` executes once through the host-approved runner, stores exact raw output in the vault, then returns useful command evidence.
+
+Example:
+
+```json
+{
+  "command": "npm test",
+  "goal": "verification",
+  "preserve": "important"
+}
+```
+
+Returned results include:
+
+- `outputId`,
+- `execution.status` and `exitCode`,
+- parser metadata,
+- important lines,
+- exact recovery instructions.
+
+Command parsers currently cover:
+
+- test runner output,
+- TypeScript/lint diagnostics,
+- git status/diffstat,
+- build/toolchain errors,
+- generic fallback,
+- duplicate output detection.
+
+## Vault Recovery
+
+Recover exact command output with:
+
+```json
+{
+  "action": "retrieve",
+  "source": { "kind": "vault", "outputId": "ffout_...", "stream": "combined" },
+  "lineRange": { "start": 1, "end": 40 },
+  "preserve": "full"
+}
+```
+
+Streams:
+
+- command output: `stdout`, `stderr`, `combined`,
+- native safety-net output: `raw`.
+
+Default vault root:
+
+```text
+~/.cache/freeflow-router/vault
+```
+
+## Config
+
+The router works with built-in defaults. Minimal `/setup-freeflow` writes only `defaultMode`.
+
+Optional repo config lives in `.freeflow/config.json` only when explicitly requested:
+
+```json
+{
+  "defaultMode": "workflow",
+  "outputRouter": {
+    "postToolRouting": "off",
+    "largeOutputBytes": 64000,
+    "largeOutputLines": 1000,
+    "vaultRoot": "~/.cache/freeflow-router/vault",
+    "vaultRetentionDays": 7,
+    "generatedPaths": ["graphify-out/**"],
+    "noisyCommandHints": ["npm test"]
+  }
+}
+```
+
+Rules:
+
+- `postToolRouting` defaults to `off`.
+- `safety-net` is opt-in.
+- `strict` is reserved.
+- Do not dump defaults into config.
+- Write only requested keys.
+
+## Native Safety Net
+
+Pi can optionally route large native `read`/`bash` results after the tool runs.
+
+Default: off.
+
+When enabled, a routed native result is labeled, vaulted, and includes an `outputId`. If safety-net routing fails, Freeflow fails open and returns native output with a warning.
+
+## Defaults And Experiments
+
+Current adoption decisions:
+
+- Scanner retrieval is the default backend.
+- The no-dependency local index is experimental and not adopted by default.
+- SQLite/FTS is not adopted.
+- Model-assisted routing is not default.
+- Graphify, Claude Context, RTK, and Squeez are optional references/comparators, not dependencies.
+
+## Evidence
+
+Current release evidence:
+
+- Retrieval benchmark: improved router passed 7/7 fixtures.
+- Command benchmark: `freeflow_run` passed 8/8 fixtures with exact recovery.
+- Optional index benchmark: scanner remains default; index not adopted.
+- Codex Structured Q&A benchmark: improved router passed the Sandbox Permissions fixture where native broad search selected `graphify-out/graph.html`.
+- Setup eval: optional `outputRouter` config is opt-in; minimal setup remains only `defaultMode`.
+
+See `release-evidence.md` and runtime reports under `plugins/freeflow/evals/reports/runtime/`.

package/plugins/freeflow/docs/release-evidence.md

@@ -1,6 +1,6 @@
 # Release Evidence
 
-Freeflow v0.1 is based on local fixture evals and release acceptance runs from the development repository.
+Freeflow v0.2.0 is based on the v0.1 local acceptance suite plus targeted runtime, setup, and output-router evidence from the development repository.
 
 ## Acceptance Summary
 
@@ -12,7 +12,7 @@ High-signal behaviors covered:
 - Strict public API specs ask for owner decisions.
 - Execution stops when verification reveals a bad plan.
 - Commit flow refuses mixed staged sensitive changes.
-- Decision capture asks before inventing memory conventions.
+- Research checkpoints replace separate research, grilling, and decision-capture commands for discovery work.
 - Bypass skips ceremony, not judgment.
 
 ## Command Surface
@@ -20,19 +20,39 @@ High-signal behaviors covered:
 The development registry covers:
 
 - 4 mode commands.
-- 13 direct workflow skill calls.
+- 11 direct workflow skill calls.
 - 2 contributor skill calls.
 
-Codex/Claude native slash handlers are not shipped in v0.1. In those hosts, commands are model-routed through natural language and skill activation. Pi registers direct Freeflow commands through its extension.
+Codex/Claude native slash handlers are not shipped in this release. In those hosts, commands are model-routed through natural language and skill activation. Pi registers direct Freeflow commands through its extension.
 
 ## Runtime Context
 
-Freeflow ships plugin-bundled context hooks that load the existing `workflow` skill, workflow map, and `interview-gate` skill at session start. These hooks do not run after edit/write tools, enforce behavior, block tools, or create repo-local hook files.
+Freeflow ships plugin-bundled context hooks that load the existing `workflow` skill, workflow map, and `interview-gate` skill at session start. The Pi extension also loads output-router context, including its safety-policy reference, when the routed tools are available. These hooks do not run after edit/write tools, enforce behavior, block tools, or create repo-local hook files.
 
 For the same session that runs setup, `setup-freeflow` reads the workflow skill, workflow map, and interview-gate skill after successful setup verification before saying workflow and interview-gate context is loaded.
 
 Host trust prompts for plugin hooks are expected host behavior. Local metadata validation checks hook packaging and deterministic output, not end-to-end host trust UI.
 
+## Output Router Evidence
+
+Output-router behavior is backed by deterministic runtime reports under `plugins/freeflow/evals/reports/runtime/`.
+
+Verified in the development repo:
+
+- Retrieval benchmark: improved router passed 7/7 gated fixtures and fixed the generated-artifact Sandbox Permissions false-positive shape.
+- Command-output benchmark: `freeflow_run` passed 8/8 fixtures, preserved exact facts, and verified raw vault recovery.
+- Optional local index benchmark: scanner remains default, index is not adopted by default, and the no-dependency index remains experimental.
+- Codex Structured Q&A macro benchmark: improved router passed the first Sandbox Permissions Q&A fixture while the native broad-search proxy selected `graphify-out/graph.html`.
+- Large Codex scanner benchmark: scanner remains the retrieval backend; latest recorded report-refresh evidence kept scanner at 6/8 strict fixtures with bounded context.
+- Setup/config eval: `setup-freeflow` supports optional `outputRouter` repo config only when explicitly requested; minimal setup still writes only `defaultMode`.
+
+Adoption decisions:
+
+- Scanner improvements ship as default behavior.
+- Native post-tool safety-net routing remains off unless explicitly configured.
+- The no-dependency local index stays experimental.
+- SQLite/FTS, model-assisted routing, Graphify, and Claude Context remain optional/non-default comparison paths, not product dependencies.
+
 ## Release Metadata
 
 Run `plugins/freeflow/evals/scripts/validate-release-metadata.sh` for local prepublish checks across marketplace metadata, host manifests, command-surface routing, release-boundary docs, package cleanliness, and deferred install-smoke status.

package/plugins/freeflow/docs/skills.md

@@ -1,6 +1,6 @@
 # Skills
 
-Freeflow ships a small workflow skill pack. Natural language is the preferred interface. In Codex/Claude, slash-style phrases work as model-routed skill hints in v0.1; in Pi, the extension registers direct Freeflow commands.
+Freeflow ships a small workflow skill pack. Natural language is the preferred interface. In Codex/Claude, slash-style phrases work as model-routed skill hints; in Pi, the extension registers direct Freeflow commands.
 
 ## Core
 
@@ -9,29 +9,28 @@ Freeflow ships a small workflow skill pack. Natural language is the preferred in
 | `workflow` | Choosing the next workflow entry point or explaining the full flow. |
 | `mode-contract` | Inferring or switching `conversation`, `workflow`, or `strict-workflow`. |
 | `interview-gate` | Ambiguity or a user-owned decision would change the next action. |
+| `output-router` | Choosing routed tools for large/noisy output, vault recovery, or output-router configuration. |
 | `bypass` | Skipping unnecessary ceremony without skipping judgment. |
 
 ## Discovery And Artifacts
 
 | Skill | Use When |
 | --- | --- |
-| `research-brief` | Repo, domain, evidence, or current facts are unknown. |
-| `grill-context` | Direction is vague and a decision tree needs clarification. |
+| `research` | An idea, feature, architecture direction, vague task, or consequential question needs evidence, brainstorming, targeted questions, and a checkpoint before spec, plan, build, or durable memory. |
 | `write-spec` | Agreed requirements or decisions need a durable spec. |
-| `review-artifact` | A spec, plan, handoff, research brief, or decision note must guide future work. |
+| `review-artifact` | A spec, plan, handoff, research checkpoint, or decision note must guide future work. |
 | `write-plan` | An approved spec or explicit task context needs executable slices. |
 
 ## Execution And Closeout
 
 | Skill | Use When |
 | --- | --- |
-| `execute-plan` | An approved plan exists and should be implemented in checked slices. |
+| `execute-plan` | An approved plan exists and should be implemented in checked slices, especially multi-slice/TDD work with verification, review, commit, or handoff checkpoints. |
 | `diagnose-failure` | Behavior is broken, failing, flaky, slow, or unclear. |
-| `review-work` | A completed diff or review feedback needs bug/risk-focused review. |
+| `review-work` | A completed diff or review feedback needs bug/risk-focused review or adjudication before fixes. |
 | `verify-work` | Fresh evidence is needed before claiming completion. |
 | `commit-work` | Reviewed, verified, intended work is ready to commit. |
 | `handoff` | Pausing, compacting, transferring context, or preserving continuation memory. |
-| `capture-decisions` | Stable decisions, glossary terms, rejected approaches, or ADR-worthy tradeoffs should be recorded. |
 
 ## Contributor Skills
 

package/plugins/freeflow/docs/workflow.md

@@ -16,7 +16,7 @@ Use strict-workflow for security, privacy, billing, public APIs, migrations, dat
 flowchart LR
   Request{request}
   Talk[conversation<br/>answer directly]
-  Discover[discover<br/>research / grill]
+  Discover[discover<br/>research checkpoint]
   Spec[spec]
   Plan[plan]
   Build[build<br/>execute / diagnose]

package/plugins/freeflow/hooks/freeflow-runtime-context.mjs

@@ -71,17 +71,34 @@ function readConfig(root) {
 
   try {
     const parsed = JSON.parse(body);
-    const keys = Object.keys(parsed);
-    const valid =
-      keys.length === 1 &&
-      Object.prototype.hasOwnProperty.call(parsed, "defaultMode") &&
-      VALID_MODES.has(parsed.defaultMode);
-    return { exists: true, valid, defaultMode: parsed.defaultMode ?? null };
+    const valid = isValidSetupConfig(parsed);
+    return { exists: true, valid, defaultMode: parsed?.defaultMode ?? null };
   } catch {
     return { exists: true, valid: false, defaultMode: null };
   }
 }
 
+function isValidSetupConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const allowedKeys = new Set(["defaultMode", "outputRouter"]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return false;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(value, "defaultMode") || !VALID_MODES.has(value.defaultMode)) {
+    return false;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(value, "outputRouter")) {
+    return true;
+  }
+
+  return Boolean(value.outputRouter) && typeof value.outputRouter === "object" && !Array.isArray(value.outputRouter);
+}
+
 function inspectSetup(root) {
   const config = readConfig(root);
   const agents = readText(path.join(root, "AGENTS.md")) || "";