Exhaustively dogfood Kovo, file or triage bugz/papercuts ledgers, then implement the fixes through verified parallel worktree batches. Use when asked to dogfood and fix, handle remaining dogfood reports, continue after bugz/papercuts reports, implement newly found Kovo issues, parallelize dogfood remediation, push fixes, keep going until no new dogfood issues remain, or monitor CI until the reports no longer expose open issues.
Exhaustively dogfood Kovo, file or triage bugz/papercuts ledgers, then implement the fixes through verified parallel worktree batches. Use when asked to dogfood and fix, handle remaining dogfood reports, continue after bugz/papercuts reports, implement newly found Kovo issues, parallelize dogfood remediation, push fixes, keep going until no new dogfood issues remain, or monitor CI until the reports no longer expose open issues.
Dogfood And Fix
Overview
Run the complete Kovo feedback loop: exercise real apps against the local framework, classify
confirmed failures into plans/bugz-*.md or plans/papercuts-*.md, implement the fixes, verify
the exact claims, push coherent batches, follow CI until the pushed state is known, then continue
with the next dogfood or report-closure pass until no confirmed issues remain or the user stops.
This skill composes the repo-local dogfood and implementation disciplines. Use the current
SPEC.md, AGENTS.md, rules/, active plans/, and existing dogfood / implement-plan
skills as governing context when available, but keep this loop focused on closing reports rather
than only writing them.
Entry Modes
Named reports first. If the user names specific plans/bugz-*.md or
plans/papercuts-*.md files, implement those before creating new reports. Treat each unchecked
task-list item as open until same-session evidence proves it fixed. If a named current report is
not registered, enroll it before treating it as an active transient ledger.
Dogfood then fix. If the user asks for a fresh dogfood pass, create the next appropriate
ledger(s), reproduce and classify issues, then immediately implement the confirmed items unless
the user explicitly asks for report-only mode.
Resume loop. If prior batches were pushed, inspect git status, recent commits, open plan
checkboxes, and CI before continuing. Do not redo closed work unless a regression reproduces.
Keep going. If the user says to keep going until there are no bugs or papercuts, alternate
report closure, fresh dogfood, focused verification, and CI repair until the current evidence has
no open dogfood-derived items. Respect any explicit deferrals, such as postponing a performance
optimization, and record the deferral instead of silently doing that work.
Sources Of Truth
Read enough before editing to judge behavior correctly:
SPEC.md is normative. Cite the relevant section in tests, diagnostics, plan evidence, or handoff
notes when it prevents ambiguity.
AGENTS.md and rules/*.md govern repo discipline, plan evidence, compiler behavior, API
surface, workflow edits, docs, and release claims.
plans/security-ledger-index.json and plans/security-ledger-index.md define active roadmaps,
transient reports, historical dedup roots, and the closure/publication/archive lifecycle. Do not
infer active reports from filename patterns or checkbox counts.
packages/create-kovo, packages/compiler, packages/server, packages/browser,
packages/drizzle, examples, templates, and generated app output identify whether a symptom is a
framework bug, starter papercut, docs gap, or app-author mistake.
Dogfood Rules
Dogfood the local monorepo, not published packages, unless explicitly requested.
Rebuild scaffold output before create-kovo testing:
pnpm --filter create-kovo run build:dist.
Scaffold under a stable real path, not /tmp, then run
node <kovo>/packages/create-kovo/dist/index.mjs <appDir> --sqlite --disable-git,
node <kovo>/scripts/link-local-kovo.mjs <appDir> <kovo>, and pnpm install in the app.
After multi-app dogfood, run root pnpm install in the monorepo to repair link-local workspace
side effects before trusting repo checks.
Parse the actual dev URL from vp dev / pnpm run dev logs; ports can auto-increment and bind
localhost. Kill every server started.
Exercise the real author workflow: scaffold, install, dev boot, browser/HTTP interactions,
per-form CSRF submission, HMR or source edits when relevant, pnpm run check,
pnpm run test, and pnpm run build:prod.
File security, soundness, provenance, fail-open, and data-corruption defects in bugz; file
rough edges, missing diagnostics, starter friction, docs gaps, and awkward but safe workflows in
papercuts.
Ledger Discipline
Use GitHub task-list checkboxes for every actionable item. Avoid free-form open items.
Mark [x] only after the same session verifies the exact claim with a named file, artifact, or
command. If evidence is weaker than the checkbox, leave it open and note the gap.
Close at the bug's own layer, not an adjacent proxy. The closing evidence MUST be the ledger
item's own Acceptance:/Repro clause, executed at the layer where the bug is observable. A
passing unit test that asserts build-graph/renderer internals does NOT close an item whose symptom
is in the deployed artifact (a kovo build output served by node dist/server/server.mjs). For
any item observable end-to-end (mutation success body, island deploy/hydrate, response headers,
static-export output, streaming), the close-out must run the relevant split starter e2e
(packages/create-kovo/src/index.build.prod-artifact.test.ts,
packages/create-kovo/src/index.build.runtime.test.ts, or
packages/create-kovo/src/index.build.scaffold.test.ts, and the CI starter job) GREEN — and add the
item's repro there as a new it() when it is not already covered. Do not merge or push a batch while that
e2e is red.
Keep active ledgers compact. Replace stale evidence with current proof; do not append long command
transcripts or historical logs.
When integrating a branch forked before ledger cleanup, preserve the compact main-thread ledger
and port only the new evidence required by the integrated fix.
Keep every current report explicitly registered with the transient content marker and a deadline
no more than 30 days after opening. Multiple transient reports are valid.
When all items close, record exact evidence, closedOn, and closed-pending-publication. After the
closing commit reaches the intended remote ref and required CI is known, record publication proof
and use published-pending-archive. Before archiveBy, replace the transient marker with
<!-- kovo-security-ledger: archived -->, move the report to its declared plans/history/ path,
and remove its transient entry; preserve one compact series summary for future deduplication.
Run pnpm run check:security-ledger-index after every lifecycle transition.
Parallel Strategy
Default to a fan-out when reports expose independent ownership boundaries. Keep the main agent on
the integration lane and delegate closure-oriented slices where sub-agent tools are available. Do
not wait for the user to ask how to parallelize if the active ledgers already expose disjoint
compiler, runtime, browser, Drizzle, starter, docs, or verification surfaces.
Main agent owns:
reading sources of truth and sequencing reports;
creating or selecting ledgers;
assigning non-overlapping worker scopes;
reviewing worker commits;
integrating one branch at a time;
updating plan evidence after local verification;
checkpoint commits, pushes, and CI monitoring.
Dogfood fan-out candidates:
baseline create-kovo starter, check, test, build, dev smoke;
realistic commerce or CRM browser workflows;
Drizzle relational queries, aggregates, callbacks, and query-builder extraction;
compiler lowering, query-shape facts, live-targets, optimistic actions, and generated stamps;
server/runtime forms, CSRF, headers, cookies, redirects, and error reporting;
build/export/deploy skew between vp check, kovo build, and dev.
Implementation fan-out candidates:
compiler/analyzer fixes and fixtures;
Drizzle static extraction and helper families;
server/runtime behavior and conformance tests;
browser/client transforms and hydration or live-target behavior;
create-kovo starter/template fixes and generated app gates;
docs, examples, and plan evidence after production behavior is already proven.
Worker rules:
Each worker uses its own sibling git worktree and branch from the current integration HEAD.
Assign broad but bounded ownership: package paths, tests, generated artifacts, and report items.
Do not let workers edit active plan ledgers, push branches, or revert unrelated work.
Require a scoped commit plus handoff: worktree path, branch, commit SHA/range, changed files,
tests run, results, and remaining risks.
Prefer 3-5 workers for broad independent surfaces. Use higher-reasoning models for compiler,
runtime, security, Drizzle extraction, and high-conflict integration; use cheaper bounded models
for straightforward fixtures, docs, and narrow template changes.
Integrate one worker branch at a time. Review the diff, run the worker's focused verification in
the integration worktree, port only concise plan evidence, then checkpoint before taking the next
branch when the integration risk is material.
If no sub-agent mechanism is available, still parallelize mentally: group by ownership, avoid
alternating across conflicting files, and commit verified batches as each coherent surface closes.
Implementation Loop
Inspect state with git status --short --branch, recent commits, and any CI results for the
current head. Leave unrelated untracked or modified files alone.
Create a goal if goal tools are available. Keep it active until named reports are closed,
pushed, and CI has been monitored or a real blocker is reached.
For substantial plan work, create an integration worktree from current mainline. If the user is
already operating in a chosen checkout and asks to continue there, protect unrelated changes and
use the current worktree carefully.
Reproduce before fixing when the issue is not already proven by current evidence.
Implement the smallest production change that satisfies the SPEC.md contract and report
acceptance criteria. Prefer stronger preview-era defaults over compatibility shims.
Add or update focused tests for the touched surface. Broaden checks when crossing package,
compiler, runtime, or generated-artifact boundaries.
Run the narrow verification first, then shared gates such as vp check, relevant vitest
suites, pnpm exec tsc --noEmit, git diff --check, or package-specific scripts.
Update report checkboxes only after verification, with concise evidence beside the item. Move a
fully closed transient report to closed-pending-publication in the registry.
Commit coherent batches. Push after meaningful closure or when CI feedback is needed.
Monitor GitHub Actions for the pushed commit. If CI fails, inspect logs, fix the root cause,
push again, and continue monitoring.
Record verified publication, then archive the report before its registered deadline.
After named reports close, run at least one fresh dogfood or targeted regression pass that
exercises the just-fixed surfaces. If it finds new confirmed issues, create or update the next
compact registered ledger and loop back through implementation.
Completion Criteria
Finish only when all of these are true:
every named report has no unchecked actionable items;
any newly created dogfood ledger either has no confirmed issues or all confirmed issues are fixed
with current evidence;
explicit deferrals are listed as deferred, not silently counted as complete;
no transient ledger is overdue or missing its marker/registry entry;
relevant local gates passed, or each skipped gate has a concrete reason;
the branch or local main containing the fixes has been pushed when pushing is in scope;
CI for the pushed commit has been checked, and any failures attributable to the work are handled
or explicitly reported as remaining risk.
Handoff
Report the final state succinctly:
reports closed or created;
commits pushed and branch/SHA;
key verification commands;
CI status;
known remaining risks or intentionally deferred work.
