Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.
TypeScript ai-sdkclaude-codeclicode-searchcodexcoding-agentscontext-retrievaldeveloper-toolsjevsemantic-searchtypescriptvercel-ai-gateway
docs: preserve validated spike behavior in planning and implementation skills
David Zhang7e4f38ae42b8
diff --git a/.agents/skills/implement-spec/SKILL.md b/.agents/skills/implement-spec/SKILL.mdindex 2fb3d6e..3440bb9 100644--- a/.agents/skills/implement-spec/SKILL.md+++ b/.agents/skills/implement-spec/SKILL.md@@ -6,8 +6,8 @@ description: Implement an existing spec through committed passes. Use for long o# Implement SpecBuild the active spec to completion, one reviewable pass at a time. The spec is-the source of truth, but the architecture is allowed to improve when the code-teaches you the plan is stale.+the implementation plan; user constraints and accepted experimental evidence+remain binding when the architecture changes.A pass (usually one slice) is a **commit checkpoint, not a stopping point.** Thejob is the whole spec — every slice, every global TODO — not the first green@@ -27,6 +27,7 @@ depends on prior work.Load any skills named by the spec. Identify the current pickup point, globalTODOs, required gates, and what must stay green. If a multi-slice spec lacksa live handoff prompt, add one before the first pass ends.+ For a validated spike, apply **Preserve the winner** below before editing.2. Reconcile the plan with the current code. If the slice would preserve adevelopment-only shim, duplicated type, weak wrapper, or obsolete path,replace it with the simpler architecture and update the spec handoff.@@ -49,9 +50,10 @@ depends on prior work.5. **Review the change list and clean up after every pass, before committing.**Read `git status`/`git diff --stat` line by line and account for every path:one-off probes, shot scripts, scratch files, `nohup.out`, ad-hoc screenshot- dirs, and SPIKE/debug notes never enter a commit — scratch stays out of the- tree; review evidence belongs in the spec's `assets/`; anything else gets- deleted. A file you can't name the durable purpose of does not ship.+ dirs, and disposable SPIKE/debug notes never enter a commit — scratch stays+ out of the tree. Preserve frozen references, fixtures, and research evidence+ in the project's reference or spec assets area. A file without a durable+ purpose does not ship.Delegated agents leak these; the integrating reviewer re-checks the mergedtree with the same eye.@@ -129,6 +131,22 @@ depends on prior work.by verdict, ranked least-confident-first, every entry ELI5 and standalone.*Then* close the spec with [close-spec](../close-spec/SKILL.md).+## Preserve the winner++- Read the frozen winning code, configuration, prompts/skills, and evidence.+ Preserve actual behavior, including quirks whose contribution is unknown.+ A rewritten spec or cleaner design does not supersede measured results.+- Port first; experiment separately. Give delegates the same reference and+ constraints. Record user-required differences; validate other behavioral+ changes against the winner before adopting them.+- Prove parity through the production entry point with matched inputs and+ controlled external responses. Compare computed requests, decisions, complete+ outputs, and relevant recovery paths—not just templates or component tests.+ Normalize only documented intentional differences. Run these cheap checks+ before costly confirmation, retaining the original quality gates.+- Missing parity evidence means unfinished. Preserve the reference and continue+ independent work rather than declaring equivalence.+## Rules- **Delegate independent work to subagents so passes run in parallel.** Thediff --git a/.agents/skills/write-spec/SKILL.md b/.agents/skills/write-spec/SKILL.mdindex 34ed051..64a0f04 100644--- a/.agents/skills/write-spec/SKILL.md+++ b/.agents/skills/write-spec/SKILL.md@@ -1,6 +1,6 @@---name: write-spec-description: Break large features into independently verifiable, human-reviewable slices under specs/<feature>/. Use for risky or multi-step feature work that needs upfront questioning, API seams, browser-playable checkpoints, HTML visualizations, screenshot gates, staged implementation plans, recursive fog-of-war reslicing, or proactive research into reference implementations/best practices before slicing. Pairs with your project's verification harness and screenshot gates (the browser checkpoints), [refactor-clean](../refactor-clean/SKILL.md) (review the materialized spec so the plan describes one-owner architecture, not the feature bolted on), [screenshot-critique](../screenshot-critique/SKILL.md) and [compare-screenshots](../compare-screenshots/SKILL.md) (the visual gates), and a code-review pass (audit each slice before it lands).+description: Break large features into independently verifiable, human-reviewable slices under a feature directory in specs/. Use for risky or multi-step feature work that needs upfront questioning, API seams, browser-playable checkpoints, HTML visualizations, screenshot gates, staged implementation plans, recursive fog-of-war reslicing, or proactive research into reference implementations/best practices before slicing. Pairs with your project's verification harness and screenshot gates (the browser checkpoints), [refactor-clean](../refactor-clean/SKILL.md) (review the materialized spec so the plan describes one-owner architecture, not the feature bolted on), [screenshot-critique](../screenshot-critique/SKILL.md) and [compare-screenshots](../compare-screenshots/SKILL.md) (the visual gates), and a code-review pass (audit each slice before it lands).---# Write Spec@@ -89,6 +89,8 @@ whole feature is done.standard, visual target, or performance pattern. Capture the discoveredsource/repo/article/paper links in the spec and turn any exemplar into areproduction spike before a porting slice.+ If prior experiments already established an accepted approach, apply+ **From research to implementation** below before drafting alternatives.3. **Draft in parallel:** for a multi-slice feature, spawn **at least threeindependent subagents** to draft the whole plan — fresh context each, a gitworktree apiece if they must run or build to validate, otherwise have them@@ -182,6 +184,23 @@ whole feature is done.resume from the first new slice. Then continue. Reslicing is progress, notfailure.+## From research to implementation++Freeze the accepted spike's runnable code, dependencies, configuration,+inputs, prompts/skills, and evidence by immutable identity. Inspect what it+actually does; option names and summaries are not proof of behavior.++Map **proven behavior → evidence → owning slice → parity gate** in the spec.+Give every drafter this contract and the limits of the findings. Separate+user-required differences from untested proposals; cleanup must not silently+redesign the winner.++Plan an early production-entry-point comparison against the frozen reference+with matched inputs and controlled responses. Check computed requests,+decisions, and complete outputs; name permitted differences. Every preservation+row needs an owner and a check. Run parity before expensive confirmation and+retain the original quality gates.+## Plan FolderUse `specs/<feature>.md` only for a small, single-slice problem. Large