whetstone_DSL/docs/AGENT_PLAYBOOK_WHESTONE_FIRST_SPRINT_EXECUTION_2026-03-20.md

Agent Playbook: Whetstone-First Sprint Execution

This document is for agents working across Whetstone and target projects such as whimpwm.

It captures the working method that produced better results on 2026-03-20 when executing structured sprint work through the Whetstone MCP/taskitem pipeline.

Why This Exists

Two failure modes show up repeatedly:

1. Agents bypass Whetstone too early and manually code around a weak planning pipeline.
2. Agents trust generated taskitems too easily even when they are broad, duplicated, off-project, or not executable by smaller workers.

The intended method is a middle path:

• use Whetstone first
• inspect the output critically
• correct taskitems manually when needed
• record the generator miss
• only then hand execution to constrained workers or continue with senior review

Core Principle

Whetstone should remain the planning and task-shaping source of truth as early as possible.

That does not mean raw markdown specs are ignored.

The phase model is:

1. Spec markdown is the source of truth before code exists.
2. Parsed planning artifacts are the source of truth after intake.
3. AST is the source of truth once code structure exists.

Agents should push work toward that progression, not collapse back to ad hoc manual execution.

Default Workflow

For a sprint execution request:

1. Find the active sprint spec or execution spec.
2. Run the Whetstone sprint taskitem pipeline.
3. Inspect generated taskitems before writing code.
4. Decide whether taskitems are:
   • ready to execute
   • salvageable with manual correction
   • unusable and requiring a recorded gap
5. If taskitems are good, use them as the execution substrate.
6. If taskitems need correction, edit the taskitems manually and preserve the corrected artifact in the run directory.
7. If taskitems are unusable, record the generator/validator failure in the gap registry and do not pretend the pipeline succeeded.
8. Preserve run artifacts for LoRA and smaller-model training data.
9. After code generation or worker execution, perform a stronger model review and tighten the result.

The Important Distinction

Manual correction of taskitems is allowed when the generator is close but not yet reliable enough.

Manual bypass of the taskitem layer is not the default.

That means:

• acceptable:
  • rewrite titles
  • narrow target files
  • fix acceptance commands
  • split one broad task into several bounded tasks
  • add missing execution-contract fields
• not acceptable:
  • ignore obviously bad taskitems and jump straight to handwritten code as if the planning layer were fine
  • treat a failed taskitem run as a success without recording what was wrong

Taskitem Quality Bar

Generated taskitems are not execution-ready just because validation returned score=100.

Before handing them to smaller agents, check:

• Does each task have a bounded objective?
• Do targetFiles point to the actual project and the likely ownership slice?
• Are acceptance commands valid for the project language?
• Are test files real?
• Is the title specific enough that a constrained worker could act on it?
• Is the task a concrete implementation slice rather than a broad planning bucket?

Red flags include:

• blanket file sets repeated across every task
• wrong-project paths
• fabricated tests
• mixed-language commands such as go test ./... in a Rust repo
• titles like Architect Review, Define verification surface, or generic Plan ... tasks with wide ownership

When To Use Smaller Workers

Use smaller agents or AST-first codegen only after the taskitem is narrow enough that a constrained worker can succeed without inventing scope.

Good worker task shape:

• one main objective
• a small, real file set
• valid verification commands
• explicit acceptance evidence

If the taskitem still requires a senior model to infer the real work, reshape it first.

Review Role Of The Stronger Model

The stronger model should own:

• sprint interpretation
• taskitem quality review
• manual taskitem correction
• gap diagnosis and registry updates
• final code review and hardening

The stronger model should not waste tokens doing narrow mechanical generation if the taskitem is already well-shaped for a smaller worker.

Gap Recording Rule

If the generator or validator fails in a meaningful way, record it.

Typical examples:

• generated taskitems are project-grounded but still not executable
• validator over-scores clearly weak tasks
• subsection/work-item structure is ignored
• self-targeting Whetstone sprints collapse into blanket internal tasks

Record the miss in the relevant Whetstone gap or registry path instead of silently compensating for it.

Data Capture Rule

Every meaningful run should leave artifacts useful for later LoRA or SLM work.

Preserve:

• raw pipeline run directory
• corrected taskitem artifact when manual fixes were required
• gap note or registry update when generation was wrong

The long-term goal is to make smaller models reliable on constrained workitems, so the correction path itself is training data.

Recommended Prompting Stance For Other Agents

When another agent is asked to execute a sprint:

• tell it Whetstone is the first stop, not optional scaffolding
• tell it to inspect generated taskitems critically
• tell it manual taskitem correction is permitted
• tell it manual code bypass is not the default when the planning layer failed
• tell it to record generator misses in the gap registry
• tell it to preserve corrected artifacts for training data

One short instruction that often helps:

Use Whetstone first. If taskitems are weak, fix the taskitems and record the generator miss. Do not skip directly to handwritten code unless the user explicitly tells you to bypass the planning layer.

Suggested Use

Point other agents at this file before asking them to:

• execute a sprint
• generate taskitems for another repo
• prepare bounded work for smaller workers
• review whether a Whetstone run is actually handoff-ready

Current Practical Naming

If "bootstrapping" feels ambiguous, use:

Whetstone-first sprint execution playbook

That name is explicit about what the document is for and how agents should use it.