@kontourai/flow-agents 0.1.1

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: "frontend-design"
+description: "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics."
+---
+
+# Frontend Design
+
+Delegate frontend implementation to `tool-worker` with the design guidelines below included in the prompt. The orchestrator's job is to understand the user's requirements, choose an aesthetic direction, and hand off to tool-worker with clear instructions plus the full aesthetics guidelines.
+
+## Trigger Patterns
+
+This skill activates when the user:
+
+- Asks to build a UI, page, component, or web application
+- Wants a landing page, dashboard, form, or interactive interface
+- Mentions design quality, aesthetics, or visual polish
+- Asks for something "that looks good" or "production-grade"
+
+## Workflow
+
+### Step 1: UNDERSTAND REQUIREMENTS
+Gather from the user:
+- What to build (component, page, app)
+- Purpose and audience
+- Technical constraints (framework, existing codebase)
+- Any aesthetic preferences or references
+
+### Step 2: DELEGATE TO tool-worker
+Spawn `tool-worker` with a prompt that includes:
+- Delegate to the exact `tool-worker` role; do not spawn an unnamed/default implementation agent.
+1. The specific implementation task (what to build, where files go, framework)
+2. The **full Design Guidelines section below** — copy it into the delegation prompt so tool-worker has it in context
+
+### Step 3: VERIFY VISUALLY (mandatory)
+After tool-worker completes, you MUST delegate to tool-playwright to screenshot the result and confirm it renders correctly. Do NOT skip this step. Do NOT treat implementation as the final step. Visual verification is required before relaying results to the user.
+
+## Design Guidelines
+
+Include everything below this line in the tool-worker delegation prompt.
+
+---
+
+### Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+### Frontend Aesthetics
+
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt for distinctive choices that elevate the aesthetic. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, and grain overlays.
+
+### Anti-Patterns (NEVER use)
+
+- Generic font families (Inter, Roboto, Arial, system fonts)
+- Cliched color schemes (particularly purple gradients on white backgrounds)
+- Predictable layouts and cookie-cutter component patterns
+- Converging on the same "safe" choices across generations (e.g., Space Grotesk every time)
+
+Vary between light and dark themes, different fonts, different aesthetics. Every design should feel unique to its context.
+
+### Calibration
+
+Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details.

package/skills/github-cli/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: "github-cli"
+description: "Interact with GitHub via gh CLI — PRs, issues, repos, releases, workflows, gists."
+---
+
+# GitHub CLI
+
+Interact with GitHub using the `gh` CLI — manage pull requests, issues, repos, releases, Actions workflows, and more without leaving the terminal.
+
+## Trigger Patterns
+
+This skill activates when the user:
+
+- Wants to create, view, merge, or review pull requests
+- Wants to create, list, or manage issues
+- Wants to check GitHub Actions workflow runs or status
+- Wants to create or manage releases, gists, or repos
+- Wants to search GitHub for repos, issues, or PRs
+- Wants to browse a repo or PR in the browser
+- Mentions `gh` by name or references GitHub operations
+
+## Prerequisites
+
+Confirm `gh` is available by running `gh --help`. If not found, tell the user it's not installed and stop.
+
+The user must be authenticated. If a command fails with an auth error, suggest `gh auth login` and let the user handle it interactively.
+
+## What `gh` Does
+
+`gh` is GitHub's official CLI. Key capability areas:
+
+- **Pull Requests** — create, list, view, checkout, review, merge, close, diff, checks
+- **Issues** — create, list, view, close, reopen, comment, assign, label
+- **Repos** — create, clone, fork, view, archive, rename, sync
+- **Releases** — create, list, view, delete, upload assets
+- **Actions** — view workflow runs, watch live logs, re-run failed jobs, list workflows
+- **Gists** — create, list, view, edit, delete
+- **Search** — search repos, issues, PRs, code across GitHub
+- **API** — make arbitrary authenticated GitHub API requests
+- **Browse** — open any repo/issue/PR in the default browser
+
+Run `gh --help` for the full command list and `gh <command> --help` for subcommand details. Defer to the CLI as the source of truth.
+
+## Workflow
+
+### Step 1: VERIFY
+Run `gh --help` to confirm availability. If not found, stop.
+
+### Step 2: UNDERSTAND INTENT
+Map the user's request to the right `gh` command area. If unsure which subcommand to use, run `gh <command> --help` to discover options.
+
+### Step 3: EXECUTE
+Run the appropriate `gh` command. For commands that create or mutate (PR create, issue close, release create, etc.), confirm the action with the user first unless they were explicit.
+
+### Step 4: PRESENT RESULTS
+Format output clearly. For list commands, summarize key fields. For view commands, highlight the important details. Offer follow-up actions where natural (e.g. after listing PRs, offer to check out or review one).
+
+## Key Principles
+- ALWAYS verify `gh` is available before any operation
+- Use `gh <command> --help` to discover flags and subcommands — don't assume syntax
+- Confirm destructive or mutating operations before executing
+- If auth fails, direct the user to `gh auth login` — don't attempt to authenticate programmatically
+- Prefer `gh` over raw `git` commands when the operation involves GitHub-specific features (PRs, issues, Actions, etc.)

package/skills/idea-to-backlog/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: "idea-to-backlog"
+description: "Turn raw product or technical ideas into shaped, prioritized, executable GitHub issue backlog. Use for idea intake, ideation, product shaping, spike/prototype decisions, PRD-like feature briefs, prioritization, and backlog creation before implementation starts."
+---
+
+# Idea To Backlog
+
+Convert raw ideas into shaped, prioritized, executable backlog without starting production implementation.
+
+## Contract
+
+- Produce durable reasoning artifacts before creating execution issues.
+- Own the human-readable backlog issue contract; downstream delivery workflows inherit and refine it rather than inventing a new shape.
+- Create GitHub issues only for committed or near-committed work.
+- Do not write production code or edit implementation files.
+- Do not invoke downstream delivery skills while shaping upstream work.
+- After the backlog gate, hand off to `pull-work` only if the user explicitly asks to continue.
+- Never invoke `plan-work`, `execute-plan`, `review-work`, `verify-work`, `evidence-gate`, or release skills from this workflow.
+- Stop at gates unless the user explicitly asks to continue.
+- Treat GitHub issues as executable backlog, not the whole reasoning store.
+- Keep separate ideas separate until a shared outcome, hard dependency, or sequencing reason justifies bundling them.
+- Push back when the user blends unrelated ideas, and ask them to justify why the ideas belong together before shaping bundled work.
+
+## Artifact Contract
+
+Create or update `.flow-agents/<slug>/<slug>--idea-to-backlog.md` with:
+
+- `source_ideas`: raw inputs and dedupe links
+- `idea_inventory`: one record per distinct idea, classification, outcome, and reason
+- `slice_candidates`: thinnest meaningful slice for each buildable idea, success signal, and non-goals
+- `bundle_justification`: why grouped ideas belong together, or explicit decision to split
+- `dependency_map`: blocks / blocked-by / related-only relationships between ideas or slices
+- `phase`: intake, opportunity, explore, shape, prioritize, backlog, blocked, complete
+- `decisions`: decision, rationale, decision maker, date
+- `opportunity_briefs`: problem, stakeholder, outcome, confidence, size
+- `shaped_work`: scope, non-goals, requirements, acceptance criteria
+- `risk_release_notes`: risk class, rollout, rollback, observability
+- `backlog_links`: GitHub issue URLs and status
+- `parked_or_rejected`: reason and revisit trigger
+- `open_questions`: owner and needed evidence
+- `next_gate`: gate name and pass/fail/block status
+
+## Workflow
+
+### 1. Intake
+
+Normalize and deduplicate raw ideas.
+
+Classify each item as:
+
+- feature
+- bug
+- research question
+- spike
+- prototype
+- chore
+- cleanup
+- parked thought
+
+Outcome: `discard`, `park`, `merge`, `research`, `shape`, or `commit`.
+
+Gate: every idea has exactly one outcome and a recorded reason.
+
+### 2. Separate Ideas And Slice
+
+Create an idea inventory before shaping. Treat each distinct user problem, workflow, stakeholder, risk, or success metric as a separate idea unless proven otherwise.
+
+When multiple ideas arrive together:
+
+- name each idea separately
+- identify the thinnest meaningful slice for each buildable idea
+- challenge accidental bundles
+- require a bundle justification before shaping grouped work
+- distinguish hard dependencies from "related-only" context
+
+A thinnest meaningful slice is the smallest independently valuable and testable unit that can reach evidence/release gates without leaving dependent half-work behind.
+
+Bundled work is allowed only when at least one is true:
+
+- one slice cannot deliver value without the other
+- the same user outcome and acceptance signal require both
+- the dependency order is explicit and the first slice unlocks the second
+- grouping reduces delivery risk more than it increases scope risk
+
+If the user is blending ideas without justification, push back directly and stop shaping the bundle until the relationship is clear.
+
+Gate: every shaped candidate has one outcome, one thinnest meaningful slice, and either a split decision or a recorded bundle justification and dependency map.
+
+### 3. Opportunity Review
+
+For ideas worth shaping, capture:
+
+- product/theme goal
+- user or stakeholder
+- problem / opportunity
+- expected outcome
+- confidence
+- rough investment size
+- tradeoffs and what this displaces
+
+Gate: the opportunity is worth shaping, or it is parked/rejected.
+
+### 4. Explore Options
+
+Use `knowledge-search`, `search-first`, `explore`, or `crowdsource` when context is missing.
+
+Decide the path:
+
+- `shape-work`: enough is known to define the feature.
+- `spike-research`: unknowns need investigation, no production code.
+- `prototype-mvp`: visual or interaction proof is needed in an isolated worktree.
+- `reject/park`: not worth current backlog.
+
+For spikes and prototypes, define the learning question, timebox, artifact, and cleanup expectation. Prototype work must be isolated and must not silently become production implementation.
+
+### 5. Shape Work
+
+Create a brief with:
+
+- story / user outcome: `As a <user/persona>, I want <capability>, so that <outcome>` when a user-facing story fits; otherwise use a concise system/operator outcome
+- problem statement
+- users / stakeholders
+- scope
+- non-goals
+- requirements with stable ids, such as `R1`, `R2`
+- UX/API implications
+- acceptance criteria with stable ids, such as `AC1`, `AC2`; criteria must be testable and map back to requirements
+- verification expectations that preserve AC ids and name expected command/test evidence plus source evidence/permalink expectations when implementation behavior is claimed
+- risk class
+- rollout / rollback notes
+- observability or release concerns
+- open questions
+
+Gate: acceptance criteria are testable and scope/non-goals are stable enough for planning.
+
+The backlog issue shape should optimize for human readability first, then workflow traceability:
+
+- `Story / Outcome`
+- `Problem`
+- `Scope`
+- `Non-goals`
+- `Requirements` with stable `R*` ids
+- `Acceptance Criteria` with stable `AC*` ids
+- `Verification Expectation`
+- `Acceptance Evidence` expectation: closure/provider comments must map AC ids to status, command/test evidence, source evidence/permalinks, and gaps
+- `Milestone / Delivery Outcome`
+- `Dependencies / Blockers`
+- `Source Artifact`
+
+Downstream `pull-work`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, and `evidence-gate` must preserve the `R*` and `AC*` ids and add readiness, execution, modified-file scope, critique, and evidence mappings.
+
+### 6. Prioritize
+
+Produce a priority brief:
+
+- recommendation: do / defer / reject
+- why now
+- expected outcome
+- confidence
+- cost / size
+- risks
+- dependencies
+- alternatives
+- human decision
+
+Gate: tradeoff, priority, and decision maker are explicit.
+
+### 7. Sync Executable Backlog
+
+Use `github-cli` / `gh` for issues when available.
+
+Create GitHub issues only for committed or near-committed execution units. Each issue should include:
+
+- story / outcome
+- problem
+- scope
+- non-goals
+- requirements with stable `R*` ids
+- acceptance criteria
+- links to source brief / session artifact
+- priority rationale
+- milestone or milestone decision: assign a milestone when the work contributes to a named delivery outcome, or record why no milestone is appropriate
+- expected size
+- thinnest meaningful slice
+- dependencies / blockers
+- bundle justification if grouped with other issues
+- verification expectation
+- release/evidence expectation
+- acceptance evidence expectation, including source evidence refs for behavior claims and immutable GitHub blob permalinks pinned to commit SHA when a provider change is available
+- owner or assignee when known
+
+Each synced issue body must preserve the human-readable `Dependencies / Blockers` prose for people and also include a provider-neutral structured metadata marker for adapters. The marker is workflow metadata embedded in the body, not a requirement to use provider-native dependency, sub-issue, project, or custom-field APIs. Native dependency surfaces are adapter-specific enhancements and are outside the generic skill contract.
+
+At sync time, capture the source revision assumptions that shaped the issue:
+
+- `planned_base_ref`: target branch or ref used during shaping
+- `planned_base_sha`: exact commit SHA for that ref at shaping time
+- `planned_at`: timestamp when the issue scope was shaped or last materially refreshed
+- `planning_artifact_ref`: idea-to-backlog artifact, brief, design, ADR, or other source artifact that produced the issue
+- `planning_scope_refs`: key docs, contracts, schemas, files, packages, or provider records considered while shaping
+
+Represent source revision per relevant repository. Single-repo work may use one source revision group; cross-repo work should use an array of scoped groups so downstream consumers can compare each repository against its own planned base.
+
+Emit structured `blockers[]` in the marker in addition to the prose `Dependencies / Blockers` section. Use structured entries for provider refs, artifact refs, decisions, external dependencies, and text blockers. Keep the prose section concise and readable; the structured marker carries normalized fields for `pull-work`, pickup Probe, and provider adapters.
+
+Provider-neutral marker example:
+
+```markdown
+<!-- flow-agents:work-item-metadata
+{
+  "schema_version": "1.0",
+  "source_revisions": [
+    {
+      "repo": "owner/repo",
+      "planned_base_ref": "main",
+      "planned_base_sha": "0123456789abcdef0123456789abcdef01234567",
+      "planned_at": "2026-06-03T03:23:14Z",
+      "planning_artifact_ref": ".flow-agents/example/example--idea-to-backlog.md",
+      "planning_scope_refs": [
+        "skills/idea-to-backlog/SKILL.md",
+        "context/contracts/work-item-contract.md"
+      ]
+    }
+  ],
+  "blockers": [
+    {
+      "type": "work_item",
+      "ref": "provider://work-items/123",
+      "status": "blocked",
+      "summary": "Needs the upstream contract issue to land first."
+    },
+    {
+      "type": "text",
+      "status": "blocked",
+      "summary": "Needs product decision on rollout scope."
+    }
+  ]
+}
+-->
+```
+
+For one-repo issues, adapters may normalize the first source revision group to top-level `planned_base_ref`, `planned_base_sha`, `planned_at`, `planning_artifact_ref`, and `planning_scope_refs` while preserving `source_revisions` when present.
+
+Avoid creating tiny implementation tasks too early; `plan-work` can decompose inside an execution artifact later.
+
+Gate: every created issue is ready for `pull-work` or explicitly marked blocked/needs shaping.
+
+Backlog issue bodies should not require live provider calls to create permalinks during shaping. They should require downstream closure comments to include an `Acceptance Evidence` table with columns `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence / Permalinks`, and `Gaps`; source evidence can start as local file/line refs during verification and should be upgraded to immutable provider permalinks before closure when available.
+
+When a GitHub Project is used, decide whether milestones are represented as repo milestones, project fields, issue labels, or intentionally omitted. Record the chosen milestone strategy in the artifact and apply it consistently to created issues/project items when the provider supports it.
+
+## Gates
+
+- Idea Gate: deduped, classified, and either discarded, parked, merged, researched, shaped, or committed.
+- Slice Gate: every candidate has one outcome, one thinnest meaningful slice, and explicit split/bundle/dependency reasoning.
+- Shape Gate: brief is coherent and acceptance criteria are stable enough.
+- Priority Gate: priority and tradeoff are explicit.
+- Backlog Gate: GitHub issues are ready for `pull-work`.
+
+If a gate fails, update the artifact with the missing evidence or decision and stop.
+
+## Backlog Hygiene
+
+- Do not let every qualified idea become an issue.
+- Use an inbox, opportunity store, shaped queue, executable backlog, and archive.
+- Parked ideas need a reason and revisit trigger.
+- Stale issues should be closed, archived, or returned to discovery.

package/skills/knowledge-capture/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: "knowledge-capture"
+description: "Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when another workflow creates an artifact that should be indexed."
+---
+
+# Knowledge Capture
+
+Capture context so it is findable later without copying every source system into notes.
+
+## Capture Modes
+
+### Pointer
+
+Use a pointer when an artifact already exists elsewhere: email, CRM record, calendar event, document, issue, chat thread, or generated report.
+
+```markdown
+- [YYYY-MM-DD] [entity/topic] Summary - source:<system> id:<identifier> tool:<access method>
+```
+
+Write pointers automatically after creating or discovering important artifacts. Do not ask for permission when the pointer is purely an index entry.
+
+### Curated Knowledge
+
+Use curated knowledge when the note contains durable context not present in any single source:
+
+- user corrections or preferences
+- relationship context
+- decisions and rationale
+- lessons learned
+- cross-system synthesis
+- career or project milestones
+
+Before saving proactively, state why it is worth keeping: future query, delta from source systems, shelf life, and whether it is fact or inference.
+
+## Where To Write
+
+Follow the knowledge base's existing structure. Prefer:
+
+- entity folder or hub for account/project/person-specific context
+- `knowledge/memories/decisions.md` for decisions
+- `knowledge/memories/lessons.md` for lessons
+- `knowledge/memories/preferences.md` for user preferences
+- `knowledge/memories/bookmarks.md` for links
+- journal/raw capture only when no durable structure exists yet
+
+If a note belongs to a person, use the `contacts` skill. If it is a meeting note, use `meeting-notes`.
+
+## Rules
+
+- Always include date, source, and retrieval path for pointers.
+- Save confirmed facts; label inferences explicitly.
+- Do not save low-signal routine summaries.
+- Do not overwrite existing notes without reading them first.
+- Link from an entity hub when the knowledge base uses hubs.
+- Run `post-write` after writing or updating a knowledge file.

package/skills/learning-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: "learning-review"
+description: "Capture post-merge, post-deploy, or post-incident learnings and feed them back into backlog, workflow skills, tests, docs, or knowledge. Use after release readiness, post-deploy checks, retrospectives, failed gates, or repeated workflow friction."
+---
+
+# Learning Review
+
+Turn delivery outcomes into durable learning and follow-up work.
+
+## Contract
+
+- Do not rewrite history or mark failed work as successful.
+- Do not implement fixes during the review.
+- Capture facts, decisions, and follow-up issues separately.
+- Feed actionable changes back to `idea-to-backlog`, GitHub issues, tests, docs, or knowledge.
+- Use `knowledge-capture` or `observe` when the learning should persist beyond the repo.
+- Compare long-lived docs against the local `.flow-agents/<slug>/` plan and the final acceptance artifact so implementation intent is not lost after merge.
+- Treat `learning-review` as the terminal closeout decision point for correction telemetry. Compare intended behavior to observed behavior before writing `learning.json`, then record either `correction.needed: false` for a clean run or `correction.needed: true` for a mismatch.
+
+## Inputs
+
+- Release-readiness artifact, evidence-gate artifact, PR/issue links, deploy notes, incidents, telemetry, user feedback, and reviewer/verifier notes.
+
+## Artifact Contract
+
+Create or update `.flow-agents/<slug>/<slug>--learning-review.md` with:
+
+- `scope`: delivered work, issue/PR/release links, dates
+- `outcomes`: expected vs observed behavior and signals
+- `evidence`: telemetry, support notes, incidents, CI/review patterns
+- `decisions`: what changed, why, and who decided
+- `gaps`: process, tests, docs, skill, tooling, product, or ownership gaps
+- `followups`: GitHub issues, idea-to-backlog items, docs/tests/eval work
+- `knowledge_updates`: notes captured or observations proposed
+- `docs_promotion`: durable docs updated, source artifacts archived/linked, and gaps routed
+- `runtime_artifact_cleanup`: `.flow-agents/` runtime artifacts remain untracked or a blocker is recorded
+- `verdict`: LEARNED, FOLLOWUP_REQUIRED, or BLOCKED
+
+When the repository provides `npm run workflow:sidecar --`, also write `learning.json` with:
+
+```bash
+npm run workflow:sidecar -- record-learning .flow-agents/<slug> \
+  --status learned \
+  --record-json '{"id":"...","source_refs":["release.json"],"outcome":"success","facts":["..."],"interpretation":"...","routing":[{"target":"none","action":"No follow-up required after intended-vs-observed closeout.","status":"completed"}],"correction":{"needed":false,"evidence":"Acceptance, release, docs promotion, and learning closeout behaved as intended."}}' \
+  --summary "..."
+```
+
+Use `followup_required` or `blocked` when facts are captured but follow-up routing is still open.
+
+Clean terminal runs must record a lightweight no-correction-needed record, not an invented lesson. Use `correction.needed: false`, a brief `correction.evidence` summary, and closed routing such as `target: "none"` with `status: "completed"`.
+
+Mismatch terminal runs must record `correction.needed: true` with:
+
+- `correction.type`: one of `workflow`, `skill`, `agent`, `tooling`, `test`, `doc`, `process`, `product`, `provider`, or `none`
+- `correction.recurrence_key`: a stable free-form key for grouping repeated failures
+- `correction.intended_behavior`: what the workflow, artifact, skill, agent, or provider was supposed to do
+- `correction.observed_behavior`: what actually happened
+- `correction.gap`: the difference between intended behavior and observed behavior
+- `correction.prevention`: a routed prevention action, or `correction.no_change_rationale` when no change is intentionally made
+
+If a correction-needed prevention route is still open, use `learning.status: followup_required` unless the route is already represented by a durable provider issue, deferred with a trigger, accepted, or rejected with a rationale.
+
+After writing `learning.json`, run artifact validation when available. If `record-learning` is unavailable or blocked, keep the learning verdict at `FOLLOWUP_REQUIRED` or `BLOCKED` in the Markdown artifact and record the sidecar-write gap explicitly.
+
+For Flow Agents repo changes, prefer the combined self-validation command when evidence and critique are part of the same pass:
+
+```bash
+npm run workflow:sidecar -- dogfood-pass \
+  --check-json '{"id":"...","kind":"test","status":"pass","summary":"..."}' \
+  --require-critique \
+  --critique-id "..." \
+  --critique-summary "..." \
+  --learning-record-json '{"id":"...","source_refs":["evidence.json","critique.json"],"outcome":"success","facts":["..."],"interpretation":"...","routing":[{"target":"none","action":"No correction required.","status":"completed"}],"correction":{"needed":false,"evidence":"Evidence and critique matched the intended closeout behavior."}}'
+```
+
+Use `dogfood-pass` only when it can preserve the real evidence state. It must not turn `NOT_VERIFIED` or missing critique into a clean learning outcome.
+
+## Workflow
+
+### 1. Reconstruct Outcome
+
+Compare the original intent, acceptance criteria, release decision, and post-deploy signals. Distinguish facts from interpretation.
+
+### 1a. Decide Correction State
+
+Before identifying durable learnings, write down the intended behavior, observed behavior, and any gap. If there is no gap, record `correction.needed: false`. If there is a gap, record `correction.needed: true` with typed `correction.type`, stable `correction.recurrence_key`, intended behavior, observed behavior, gap, and either a prevention route or an explicit no-change rationale.
+
+### 2. Identify Learning
+
+Classify learnings as product, technical, operational, workflow, test, documentation, eval, or agent-behavior learning.
+
+### 3. Route Follow-Up
+
+Route raw ideas or ambiguous improvements to `idea-to-backlog`. Create GitHub issues only for executable follow-up. Use `evidence-gate` again when unresolved trust questions remain.
+
+### 4. Capture Durable Knowledge
+
+Use `knowledge-capture` for durable project or relationship knowledge and `observe` for repeated agent workflow patterns or corrections.
+
+### 5. Confirm Docs Promotion
+
+Check whether accepted delivery artifacts were promoted into long-lived documentation and whether `.flow-agents/` runtime artifacts remained untracked before merge to `main`. If not, route the missing doc or cleanup work as an owned follow-up or explicitly record why the delivery was self-explanatory.
+
+### 6. Close The Loop
+
+Record which follow-ups were created, which were intentionally deferred, and what trigger should revisit deferred work.
+
+## Gates
+
+- Learning Gate: observed outcome is recorded with evidence.
+- Follow-Up Gate: every actionable gap is routed, owned, or intentionally deferred.
+- Knowledge Gate: durable learning is captured in the right store.
+- Docs Gate: accepted planning and final acceptance artifacts are archived and linked from durable docs when useful.
+- Closure Gate: the artifact says what is done, what remains, and why.
+- Correction Gate: every terminal learning review records whether correction was needed; clean runs do not invent lessons, and mismatch runs have a recurrence key plus prevention route or no-change rationale.