@hassangameryt/freeflow 0.1.0 → 0.2.0

package/plugins/freeflow/skills/research/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: research
+description: Use when shaping an idea, feature, architecture direction, vague task, or consequential question before spec, plan, build, or durable memory. Use when evidence, brainstorming, targeted questions, and decision checkpointing need to interleave.
+---
+
+# Research
+
+Research is the discovery loop before action: evidence-guided back-and-forth that finds high-leverage decisions and ends in a checkpoint.
+
+For short-lived work, the checkpoint can stay in chat. When it must guide later work, save it in the narrowest owning artifact: spec, plan, handoff, decision note, ADR, or domain memory.
+
+Goal: enough evidence and shared understanding to checkpoint the current direction and route to spec, plan, more research, durable memory, build, or stop without inventing product, domain, scope, public API, security, privacy, billing, data-loss, compatibility, or architecture decisions.
+
+## Language
+
+Use the same architecture language when shaping work. Read `LANGUAGE.md` when the research needs deeper language mapping or the checkpoint will shape architecture:
+
+- **Module** — the thing being understood, built, or reshaped; it has an **interface** and an **implementation**.
+- **Interface** — what users, callers, or future agents must know to use or continue the work correctly.
+- **Implementation** — the details that can stay hidden behind the interface.
+- **Depth** — leverage at the interface. **Deep** means a small interface carries a lot of useful behavior. **Shallow** means the user, caller, or future agent must coordinate too many details.
+- **Seam** — where behavior, ownership, or variation can change without rewriting the surrounding work.
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Leverage** — how much future work one question, decision, or interface unlocks.
+- **Locality** — keeping evidence, decisions, tests, and changes where future work can find them.
+
+Use the **deletion test** on questions, decisions, and proposed modules: if skipping it makes complexity spread downstream, it matters. If skipping it makes complexity vanish, it was ceremony.
+
+## Loop
+
+1. Identify the target: repo area, artifact, URL, product, model, package, paper, issue, or idea. If multiple plausible targets would change research, ask for the source.
+2. Inspect the smallest evidence that can answer the current question: code, tests, docs, ADRs, specs, logs, issues, provided context, or current external sources.
+3. Explain the current understanding in plain language.
+4. Ask one path-changing question when the answer would change the next route.
+5. Let the user challenge, counter-question, or go deeper. Treat that as research input, not interruption.
+6. Refresh evidence when new claims, conflicts, or branches appear.
+7. Track decisions as settled, tentative, or open.
+8. Stop when remaining ambiguity would not change the next artifact or action.
+
+Research may move through evidence, brainstorming, targeted questioning, and checkpointing in any order. Do not force a fixed sequence when the evidence or conversation needs a loop.
+
+## Question Discipline
+
+Prefer deeper questions over more questions. Ask as many as the situation needs, but each question should earn its place: a good question collapses branches; a shallow question collects approvals.
+
+Before asking, run the question deletion test:
+
+```text
+If I do not ask this, does downstream complexity spread?
+```
+
+If no, skip it.
+
+Bad question:
+
+```text
+Should the button be blue or green?
+```
+
+when the feature purpose is still unclear.
+
+Good question:
+
+```text
+Is this for one workflow or many workflows?
+```
+
+because it changes the module interface, spec shape, and test surface.
+
+Long question chains are a failure mode, not diligence. Do not answer pressure for "every question" or "25-50 questions" by dumping a long questionnaire. That creates shallow approvals.
+
+Do not turn recommendations into an approval script. Recommendations should clarify tradeoffs, not make it easy to rubber-stamp many decisions. Give the recommendation when useful, then wait when the choice is user-owned.
+
+Instead of a long questionnaire: inspect evidence, name the decision tree, group lower-level unknowns, and ask the first high-leverage question that changes the next route. Continue in later turns as needed.
+
+After a few path-changing questions, or whenever the user introduces a new claim, inspect evidence, summarize, or checkpoint before asking more.
+
+## Decision Discipline
+
+Read `ARTIFACT-DESTINATIONS.md` when a checkpoint or decision must survive beyond chat and the owning destination is not obvious.
+
+Not every answer is durable. Keep a lightweight ledger:
+
+- **Settled** — explicit user decision or evidence-backed fact.
+- **Tentative** — useful working assumption, not authority.
+- **Open** — unresolved question that can change the next route.
+
+Persist a decision only when absence would make future work rediscover or contradict it.
+
+Put durable decisions where they belong:
+
+- Domain term or meaning -> existing glossary, `CONTEXT.md`, or domain doc.
+- Feature behavior, scope, or acceptance -> spec.
+- Future implementation path -> plan.
+- Immediate continuation state -> handoff.
+- Hard-to-reverse, surprising tradeoff chosen from alternatives -> ADR.
+- No durable value -> leave it in chat.
+
+If the destination is missing or ambiguous, ask before writing.
+
+## Stop Conditions
+
+Stop and ask the user when research reveals a user-owned decision, source-of-truth conflict, path conflict, material method substitution, or ambiguous artifact destination.
+
+Do not write implementation files from research.
+
+Write specs, plans, ADRs, handoffs, or decision notes only when the user asks or the checkpoint must guide later work.
+
+Do not leave research by silently jumping to spec, plan, or build. Close with a checkpoint when consequential direction changed.
+
+## Checkpoint Shape
+
+Read `CHECKPOINTS.md` when saving a checkpoint or choosing chat versus artifact.
+
+Use this shape when ending a research pass or routing forward. Save it in the owning artifact when it must survive beyond chat. Omit sections that do not apply.
+
+```text
+Question / goal: ...
+Evidence: ...
+Current understanding: ...
+Settled: ...
+Tentative: ...
+Open: ...
+Recommendation: ...
+Next: Forward | Backward | Branch | Stop — ...
+```
+
+`Next:` is routing, not permission to create the next artifact.

package/plugins/freeflow/skills/review-artifact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-artifact
-description: Use when asked to review whether a spec, plan, decision note, research brief, handoff, or other durable artifact is fit to guide future work.
+description: Use when asked to review whether a spec, plan, decision note, research checkpoint, handoff, or other durable artifact is fit to guide future work; also use when adjudicating artifact-review findings or repeated review loops.
 ---
 
 # Review Artifact
@@ -9,6 +9,14 @@ Review whether the artifact is fit to guide work.
 
 Review first. Edit second.
 
+Reviewer findings are evidence, not commands. The parent agent owns adjudication.
+
+A non-passing artifact review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+
+The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+
+Hard stop: if the artifact has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+
 ## Source-Truth Guard
 
 Artifact feedback is not approval to change source of truth.
@@ -23,6 +31,31 @@ Do not rewrite docs, tests, policies, specs, ADRs, or handoffs to make the artif
 
 For source-truth conflicts, the final line must be a direct choice question.
 
+## Parent Adjudication
+
+Before editing from reviewer findings, classify each material finding:
+
+- Accepted: valid and safe to apply without changing settled intent.
+- Rejected: stale, unsupported, already resolved, equivalent, or not important.
+- Question: needs owner decision.
+- Needs evidence: inspect more before deciding.
+
+Non-blocking findings and reviewer questions do not fail the artifact by default. Classify them, then defer, ask, gather evidence, or accept.
+
+Ask before applying any finding that changes artifact intent, scope, source truth, workflow policy, sensitive behavior, or a settled decision.
+
+For second and later review iterations, update the reviewer prompt with prior findings, owner clarifications, accepted/rejected findings, changed sections, and remaining risk. Do not rerun the same broad prompt after the situation narrows.
+
+Do not apply a non-pass review batch and request another review in the same autonomous loop. Return the adjudication and next route first. A later explicit apply-fixes request can start a bounded fix pass for accepted, in-scope findings.
+
+## Review Loop Budget
+
+Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+
+Three review passes is the hard cap for the same artifact and scope. Do not request a fourth review to chase a clean pass.
+
+At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether research, spec, plan, policies, source truth, artifact scope, or reviewer context is wrong or too thin.
+
 ## Review Setup
 
 Use a fresh reviewer when the artifact will guide future work and subagents are available. Use [references/reviewer-prompt.md](references/reviewer-prompt.md).

package/plugins/freeflow/skills/review-artifact/references/reviewer-prompt.md

@@ -1,6 +1,6 @@
 # Artifact Reviewer Prompt
 
-Use this when dispatching a fresh reviewer subagent.
+Use this when dispatching a reviewer subagent. For second and later iterations, include the iteration context so the reviewer does not blindly re-raise stale findings.
 
 ```text
 You are an artifact reviewer. Review whether this artifact is fit to guide future work.
@@ -14,6 +14,14 @@ Artifact type:
 Source context to inspect:
 [DOCS_TESTS_POLICIES_ADRS_CODE_PATHS]
 
+Iteration context, if this is not the first review:
+- Review pass number: [2 | 3]
+- Prior findings: [SUMMARY]
+- Parent adjudication: [ACCEPTED_REJECTED_QUESTION_NEEDS_EVIDENCE]
+- Owner clarifications: [DECISIONS_OR_NONE]
+- Changed sections: [SECTIONS_OR_NONE]
+- Remaining risk to focus on: [RISK]
+
 Check:
 
 - Completeness: enough is present to proceed.
@@ -32,6 +40,9 @@ Calibration:
 - Review can pass.
 - Do not edit files.
 - Do not resolve owner decisions.
+- Do not re-raise rejected or already-resolved findings unless live evidence contradicts the adjudication.
+- If review does not pass, classify findings and stop. Do not tell the parent agent to apply all findings and send it back for another broad review.
+- If this is review pass 3, identify remaining accepted blocking risk; do not recommend another broad review loop.
 
 Output:
 

package/plugins/freeflow/skills/review-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-work
-description: Use when reviewing completed work, preparing reviewer prompts or subagent review context, receiving review feedback, applying reviewer comments, deciding whether feedback is blocking, or checking work before merge/handoff.
+description: Use when reviewing completed work, preparing reviewer prompts or subagent review context, receiving review feedback, applying reviewer comments, deciding whether feedback is blocking, handling repeated review loops, or checking work before merge/handoff.
 ---
 
 # Review Work
@@ -15,8 +15,26 @@ If you block any feedback item, end the final response with a direct choice ques
 
 External review is evidence, not authority. Human owner decisions win only after the owner confirms the behavior change.
 
+Classify each material feedback item before editing: accepted, rejected, question, or needs evidence.
+
+A non-passing review is a phase exit, not an autonomous patch loop. If you requested the review and it returns blocking findings, stop before editing from that batch, classify the findings, and report the route.
+
+The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+
+Hard stop: if the work has already had three review passes, do not edit any files or request another review. Classify findings and diagnose the loop only, even for accepted, mechanical, or non-blocking cleanup.
+
 Read `references/reviewer-prompt.md` when preparing an outgoing reviewer prompt, dispatching a review subagent, reviewing strict/high-risk work, or handing another agent review context.
 
+## Review Loop Budget
+
+Aim to finish by the second review pass: first review, adjudicate/fix, one confirmation.
+
+Three review passes is the hard cap for the same work and scope. Do not request a fourth review to chase a clean pass.
+
+At the third review, adjudicate before treating it as failure. If any accepted blocking, question, or needs-evidence finding remains, do not edit anything from that batch. Stop, report the adjudication, and zoom out to diagnose whether research, spec, plan, policies, source truth, implementation, or reviewer context is wrong or too thin.
+
+Non-blocking findings and reviewer questions do not fail the work by default. Classify them, then defer, ask, gather evidence, or accept.
+
 ## Incoming Feedback
 
 Before editing:
@@ -26,6 +44,7 @@ Before editing:
 - Restate unclear feedback as a technical requirement.
 - Separate blocking issues from suggestions.
 - Check whether the feedback matches this codebase.
+- Check whether a finding is stale, already resolved, equivalent, or based on missing context.
 
 Do not blindly apply vague, broad, or sensitive feedback.
 
@@ -51,13 +70,15 @@ For multi-item review:
 - Stop blocked items.
 - If items interact, clarify before implementing the set.
 
-When feedback is clear and correct:
+When feedback is clear and correct and the current route is an apply-fixes pass:
 
 - Apply one item at a time.
 - Keep the diff scoped to the review item.
 - Verify each fix.
 - Push back on incorrect feedback with code, tests, or docs.
 
+Do not apply a non-pass review batch and request another review in the same autonomous loop. Return the adjudication and next route first. A later explicit apply-fixes request can start a bounded fix pass for accepted, in-scope findings.
+
 ## Outgoing Review
 
 When reviewing work, lead with bugs, regressions, missing tests, and requirement gaps.
@@ -71,3 +92,5 @@ Classify findings:
 Review can pass. Do not invent issues to justify the review.
 
 When asking another agent to review, give it source truth, changed files, risk lenses, and pass/fail criteria. Do not hand it only the previous agent's summary or your chat history.
+
+For second and later review iterations, update the prompt with prior findings, owner clarifications, accepted/rejected findings, changed files, and remaining risk. Do not rerun the same broad prompt after the situation narrows.

package/plugins/freeflow/skills/review-work/references/reviewer-prompt.md

@@ -13,9 +13,12 @@ The reviewer should get the work product and source truth, not your session memo
 - Risk lenses relevant to the work.
 - Required output shape and severity labels.
 - Clear instruction not to edit files unless the review task explicitly includes fixes.
+- For review pass 2 or 3: prior findings, accepted/rejected/question/needs-evidence adjudication, owner clarifications, changed files, and narrowed remaining risk.
 
 Do not forward only a previous-agent summary. Summaries are useful context, not authority.
 
+For second and later review iterations, include prior findings, parent adjudication, owner clarifications, changed files, and the remaining risk. Do not rerun the same broad prompt after the situation narrows.
+
 ## Risk Lenses
 
 Pick the lenses that fit the work:
@@ -58,8 +61,12 @@ Reasoning: ...
 
 If review passes, the reviewer should say that clearly and name any residual test gaps or assumptions.
 
+If review does not pass, the reviewer should classify findings and stop. Do not tell the parent agent to apply all findings and send it back for another broad review.
+
 Do not ask reviewers to invent issues. A clean pass is valid.
 
+If this is review pass 3, ask for remaining accepted blocking risk only. Do not recommend a fourth broad review loop.
+
 ## Minimal Template
 
 ```md
@@ -82,6 +89,7 @@ Review the completed work. Do not edit files.
 ## Check
 
 - [risk lenses and concrete requirements]
+- [if pass 2 or 3: prior findings, adjudication, owner clarifications, changed files, and narrowed remaining risk]
 
 ## Output
 

package/plugins/freeflow/skills/setup-freeflow/SKILL.md

@@ -9,6 +9,8 @@ Use `references/activation-contract.md` before rendering activation text, config
 
 Use `references/host-setup.md` when the request mentions Codex, Claude, both hosts, team setup, solo setup, strict defaults, hooks, CLI, or setup profiles.
 
+Use `references/output-router-setup.md` when setup explicitly asks for output-router repo config, generated-path hints, native safety-net routing, vault settings, or output thresholds.
+
 ## Stop Before Editing
 
 Do not create config, add activation blocks, imports, or rule files until setup has a clear host target and no unresolved repo-rule conflict.
@@ -46,11 +48,17 @@ Update an existing `## Freeflow` block in place. Otherwise place the block near
 
 Create or update `.freeflow/config.json` using the config adapter in `references/activation-contract.md`.
 
-Use `workflow` unless the user explicitly asks to persist a valid repo default: `conversation`, `workflow`, or `strict-workflow`.
+Minimal setup writes only `defaultMode`. Use `workflow` unless the user explicitly asks to persist a valid repo default: `conversation`, `workflow`, or `strict-workflow`.
+
+Optional `outputRouter` config belongs here only when explicitly requested. Read `references/output-router-setup.md` first. Do not add an empty `outputRouter`, dump router defaults, or ask every setup user about router config.
+
+If the user asks for router setup but gives no config knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need a repo-specific hint or native safety-net behavior.
+
+Never enable native safety-net routing by default. `postToolRouting: "safety-net"` requires an explicit request; `strict` is reserved and needs a separate confirmation before writing.
 
 Do not infer `strict-workflow` from "team", "strict gates", "careful", or high-risk examples. Recommend or ask unless the user explicitly says to make a mode the repo default.
 
-Do not add current mode, task, phase, file inventory, active plans, version metadata, or activation file path.
+Do not add current mode, task, phase, file inventory, active plans, version metadata, activation file path, or unrequested router keys.
 Mode switches are task/conversation scoped unless the user explicitly asks to persist a different default mode.
 
 ## Activation
@@ -65,7 +73,7 @@ Do not list the whole workflow, every mode, or full `interview-gate` skill in al
 
 ## Do Not Create
 
-Setup must not create empty `CONTEXT.md`, docs pages, repo-local hooks, state files, handoffs, skill inventories, or `.codex/rules` behavior files.
+Setup must not create empty `CONTEXT.md`, docs pages, repo-local hooks, state files, handoffs, skill inventories, `setup-output-router` skills, or `.codex/rules` behavior files.
 `CONTEXT.md` is domain language memory, not plugin state.
 Plugin-bundled context hooks are installed with Freeflow, not created by repo setup.
 
@@ -73,7 +81,9 @@ Plugin-bundled context hooks are installed with Freeflow, not created by repo se
 
 Before claiming setup is complete, check:
 - config JSON parses
-- config contains only `defaultMode` with the requested explicit default, or `workflow` when no explicit default was requested
+- minimal config contains only `defaultMode` with the requested explicit default, or `workflow` when no explicit default was requested
+- optional `outputRouter` config appears only when explicitly requested and contains only requested valid keys
+- native safety-net routing is off unless explicitly requested
 - Codex setup has exactly one `## Freeflow` block in `AGENTS.md`
 - Claude setup has exactly one `CLAUDE.md` import and one `.claude/rules/freeflow-core.md` core file
 - `.codex/rules` was not created or changed for Freeflow behavior

package/plugins/freeflow/skills/setup-freeflow/references/activation-contract.md

@@ -10,6 +10,7 @@ Use this Markdown reference as the v0.1 contract module:
 getActivationContract(defaultMode) -> ActivationContract
 planActivation(contract, repoState, request) -> ActivationPlan | ActivationStop
 renderActivation(contract, target) -> rendered text or checks
+planOptionalOutputRouterConfig(request) -> OutputRouterConfigPlan | ActivationStop
 ```
 
 Do not add a code module until setup behavior needs logic that cannot be kept clear in the skill and this reference.
@@ -17,7 +18,8 @@ Do not add a code module until setup behavior needs logic that cannot be kept cl
 ## Invariants
 
 - Activation text contains always-on invariants only, not the full workflow spine.
-- Config has exactly one field: `defaultMode`.
+- Minimal config has exactly one field: `defaultMode`.
+- Optional `outputRouter` config is allowed only when explicitly requested.
 - Valid defaults are exactly `conversation`, `workflow`, and `strict-workflow`.
 - Default mode is `workflow` unless the user explicitly persists another valid mode.
 - Codex activation writes `AGENTS.md`, not `.codex/rules`.
@@ -25,7 +27,7 @@ Do not add a code module until setup behavior needs logic that cannot be kept cl
 - Multi-agent setup updates both host surfaces only on explicit request and reports drift risk.
 - Existing repo instructions remain source truth.
 - Setup hard-stops before unresolved host ambiguity or repo-rule conflict.
-- Setup does not create repo-local hooks, docs inventories, state files, handoffs, empty `CONTEXT.md`, skill inventories, version metadata, activation path, current task, or current phase.
+- Setup does not create repo-local hooks, docs inventories, state files, handoffs, empty `CONTEXT.md`, skill inventories, `setup-output-router` skills, version metadata, activation path, current task, or current phase.
 - Plugin-bundled context hooks may load workflow and interview-gate context at session start, but they are package runtime, not setup output.
 - After successful setup verification, setup reads the workflow skill, workflow map, and interview-gate skill before its final response so the current session is immediately usable.
 
@@ -46,8 +48,11 @@ Claude adapter:
 Config adapter:
 
 - Create or update `.freeflow/config.json`.
-- Write exactly `{ "defaultMode": "<mode>" }`.
+- For minimal setup, write exactly `{ "defaultMode": "<mode>" }`.
 - Use `workflow` unless the user explicitly asks to persist `conversation` or `strict-workflow`.
+- Add `outputRouter` only when explicitly requested, using `output-router-setup.md`.
+- Missing `outputRouter` means built-in defaults, not a setup warning.
+- Never enable native safety-net routing by default.
 
 ## Codex Core Block
 

package/plugins/freeflow/skills/setup-freeflow/references/host-setup.md

@@ -16,6 +16,8 @@ Current runtime is not enough to choose a host when both `AGENTS.md` and `CLAUDE
 
 Solo setup is the default: one host target, compact activation, `defaultMode: "workflow"`, no extra docs.
 
+Output-router setup is an opt-in config branch inside normal setup, not a separate host profile. Use `output-router-setup.md`; keep minimal setup config unchanged unless the user explicitly asks for router config.
+
 Team setup still uses compact activation. Add both hosts only if requested. Do not add team standards, onboarding docs, owners, approvers, repo-local hooks, or CLI checks as part of setup unless the user separately asks and the repo has a validated path for them.
 
 Strict setup changes `.freeflow/config.json` to `strict-workflow` only when the user explicitly asks to make that the repo default. Otherwise recommend strict-workflow for high-risk work without persisting it.
@@ -24,7 +26,7 @@ Valid persisted defaults are exactly `conversation`, `workflow`, and `strict-wor
 
 ## Not Setup
 
-Do not install repo-local hooks, CLI commands, lint rules, global standards, docs inventories, or state files during setup.
+Do not install repo-local hooks, CLI commands, lint rules, global standards, docs inventories, setup-output-router skills, or state files during setup.
 
 Freeflow's plugin-bundled context hooks are package runtime. They load workflow and interview-gate context at session start, but setup should not copy hook files into the target repo.
 

package/plugins/freeflow/skills/setup-freeflow/references/output-router-setup.md

@@ -0,0 +1,52 @@
+# Output Router Setup
+
+Use this only when setup explicitly asks for output-router repo config, generated-path hints, native safety-net routing, vault settings, or output thresholds.
+
+## Defaults
+
+- The output router has built-in defaults. A repo does not need `outputRouter` config to use it.
+- Minimal `/setup-freeflow` must still write only `defaultMode`.
+- Do not ask every setup user about router config.
+- Do not create a separate `setup-output-router` skill.
+
+If the user says only “set up the output router” with no requested knobs, say the router works with built-in defaults and ask which optional config they want persisted. Recommend no repo config unless they need a repo-specific hint or safety-net behavior.
+
+## Config Keys
+
+Write only keys the user explicitly requests. Do not dump all defaults and do not create an empty `outputRouter` object.
+
+Supported repo config keys:
+
+```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`. Use `safety-net` only when explicitly requested. Treat `strict` as reserved; ask before writing it.
+- `largeOutputBytes`, `largeOutputLines`, and `vaultRetentionDays` must be positive integers.
+- `vaultRoot` must be a non-empty string.
+- `generatedPaths` are broad-scan generated-path hints. Explicit file or directory retrieval must remain available.
+- `noisyCommandHints` is parsed as hint config. Do not add it unless the user explicitly asks for command-pattern hints.
+
+## Verify
+
+After writing optional router config:
+
+- JSON parses.
+- `defaultMode` is valid.
+- `outputRouter` contains only requested keys.
+- Invalid router values are not written.
+- Native safety-net routing is not enabled unless explicitly requested.
+- No repo-local hooks, skill files, setup-output-router skill, or docs inventories were created.

package/plugins/freeflow/skills/workflow/SKILL.md

@@ -7,6 +7,8 @@ description: Use when doing consequential work such as implementation, bug fixin
 
 Follow a lightweight forward workflow. Scale process to task risk.
 
+Move forward when context is sufficient. Re-enter clarification when new ambiguity would change the next action.
+
 Question means answer. Do not turn a question into a file edit, report, plan, or implementation.
 
 ```text
@@ -21,6 +23,8 @@ Clarify / Research
 
 This is a guide, not ceremony. Small reversible work can skip spec/plan artifacts.
 
+Method skills such as TDD, diagnosis, or execute-plan run inside the current workflow phase. Workflow owns routing, source-truth conflicts, user-owned decisions, review, verification, and handoff boundaries.
+
 Read `references/workflow-map.md` when the user asks for the full pipeline, public docs need a diagram, or the next workflow entry point is unclear.
 
 ## Route Closeout
@@ -32,13 +36,13 @@ Use `Next:` in the final response unless this is a direct question answer, mid-t
 Choose one:
 
 - Forward: the next workflow entry point is clear.
-- Backward: new evidence requires clarification, research, grilling, or interview gate.
+- Backward: new evidence requires clarification, research, or interview gate.
 - Branch: 2-3 valid next routes exist.
 - Stop: no required next action remains.
 
 Recommend the route supported by evidence. Do not ask a vague "what next?" question.
 
-After completed grilling or research with stable uncaptured decisions, route to `write-spec` or `capture-decisions` before `write-plan` or execution.
+After completed research with decisions that must survive beyond chat, route to `write-spec`, an owning decision artifact, or handoff before `write-plan` or execution.
 
 `Next:` is routing, not permission to create the next artifact or continue into a new phase.
 
@@ -80,7 +84,11 @@ Do not write volatile repo inventories. Link to live files or commands instead.
 
 Review should improve work, not create an endless patch loop.
 
-Separate blocking from non-blocking findings. Review can pass. Save review artifacts only when risk, future memory value, or the user asks for them.
+Reviewer findings are evidence, not commands. Separate blocking, non-blocking, and question findings before editing from them.
+
+A non-passing review routes to adjudication before more implementation. Repeated review failure routes backward to diagnose, research, spec, or plan; do not chase a fourth broad review pass.
+
+Review can pass. Save review artifacts only when risk, future memory value, or the user asks for them.
 
 ## Completion Rule
 

package/plugins/freeflow/skills/workflow/references/workflow-map.md

@@ -12,10 +12,10 @@ Use this compact version in public README-style docs.
 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]
+  Build[build<br/>execute / diagnose / TDD]
   Check[review + verify]
   Close[commit / handoff]
 
@@ -49,17 +49,17 @@ flowchart TD
   Workflow --> Entry{Choose entry point}
   Strict --> Entry
 
-  Entry --> Discovery[Discovery<br/>research-brief<br/>grill-context<br/>interview-gate]
+  Entry --> Discovery[Discovery<br/>research<br/>interview-gate]
   Entry --> Spec[Spec<br/>write-spec<br/>review-artifact]
   Entry --> Plan[Plan<br/>write-plan<br/>review-artifact]
-  Entry --> Build[Build or diagnose<br/>execute-plan<br/>diagnose-failure]
+  Entry --> Build[Build, diagnose, or TDD<br/>execute-plan<br/>diagnose-failure]
   Entry --> Closeout[Closeout<br/>review-work<br/>verify-work<br/>commit-work]
 
   Discovery --> Spec
   Spec --> Plan
   Plan --> Build
   Build --> Closeout
-  Closeout --> Handoff[handoff<br/>capture-decisions when durable]
+  Closeout --> Handoff[handoff<br/>durable checkpoint when needed]
   Handoff --> Done
 
   Reenter[Re-enter discovery<br/>new evidence, owner decision,<br/>source conflict, or failed check]
@@ -76,17 +76,16 @@ flowchart TD
 ## Common Entry Points
 
 - Use `conversation mode` when the user asks a question, wants critique, or is exploring.
-- Use `research-brief` when repo, domain, evidence, or current facts are unknown.
-- Use `grill-context` or `interview-gate` when direction is vague, source truth conflicts, or user-owned decisions are still open.
+- Use `research` when repo, domain, evidence, current facts, brainstorming, targeted questions, or a decision checkpoint are needed before spec, plan, build, or durable memory.
+- Use `interview-gate` when direction is vague, source truth conflicts, or user-owned decisions are still open.
 - Use `write-spec` when requirements are agreed but not durable.
 - Use `review-artifact` when a spec, plan, handoff, or decision note must guide future work.
 - Use `write-plan` when an approved spec or explicit task context exists.
-- Use `execute-plan` when an approved plan exists.
+- Use `execute-plan` when an approved plan exists; method skills like TDD run inside that build phase when requested or appropriate.
 - Use `diagnose-failure` when behavior is broken, failing, flaky, slow, or unclear.
 - Use `review-work` and `verify-work` before claiming consequential work is ready.
 - Use `commit-work` only after the intended diff is reviewed and verification evidence exists.
 - Use `handoff` when pausing, compacting, or transferring context.
-- Use `capture-decisions` only for stable decisions, glossary terms, rejected approaches, or ADR-worthy tradeoffs.
 - Use `bypass` only to skip unnecessary ceremony. It cannot skip user-owned decisions, source-truth conflicts, risky checks, or verification claims.
 
 ## Phase Exits
@@ -94,10 +93,10 @@ flowchart TD
 End completed consequential phases with `Next:` unless this is a direct answer, mid-task status, or clarification-only turn.
 
 - Forward: name the next entry point, such as `write-spec`, `write-plan`, `execute-plan`, `review-work`, `verify-work`, `commit-work`, or `handoff`.
-- Backward: return to `interview-gate`, `research-brief`, or `grill-context` when evidence changes the path.
+- Backward: return to `interview-gate`, `research`, `diagnose-failure`, or plan/spec revision when evidence, failed checks, or repeated review findings change the path.
 - Branch: show 2-3 valid next routes when more than one is reasonable.
 - Stop: say no required next action remains.
 
-After completed grilling or research with stable uncaptured decisions, prefer `write-spec` or `capture-decisions` before planning or execution.
+After completed research with decisions that must survive beyond chat, prefer `write-spec`, an owning decision artifact, or handoff before planning or execution.
 
 Do not create the next artifact just because it is the next route.

package/plugins/freeflow/skills/write-skill/SKILL.md

@@ -21,7 +21,7 @@ Do not add references, examples, README files, changelogs, or metadata when a co
 
 Do not add helper scripts for commands the agent can run directly, such as `git log`, `git diff`, search, formatting, or line counts. Scripts are for repeated deterministic work that would be risky or wasteful to retype.
 
-Follow the repo's line budget. If none exists, keep `SKILL.md` under 100 lines unless the extra lines clearly earn their place.
+Treat the repo's line budget as a best practice, not a hard cap. If none exists, aim to keep `SKILL.md` under 100 lines for normal skills. Let deep skills exceed it when the active rules, examples, or structure clearly earn their place.
 
 ## Description First