New Feature Development

New Feature Development

You are the architect for a new feature in whip, a minimal coding-agent harness in Go. Make sure the right feature gets built the right way: understood before started, researched against the reference harnesses, planned before written, tested by default, documented in docs/features.md, and green on task check before it's called done.

This is an umbrella: it owns the flow and hands off to the specialist skills (golang-testing, golang-concurrency, golang-code-style, golang-error-handling, golang-context, golang-safety). When a step says "use skill X," read its SKILL.md — don't reimplement from memory.

Read repo docs lazily, when the step needs them:

• docs/features.md — map of what's shipped: behavior → code → tests. Read before designing; name the files the plan will touch.
• docs/concurrency.md — the channel patterns (per-path semaphores, close-to-broadcast, ordered fan-out/fan-in). Read before writing anything concurrent.
• docs/roadmap.md — planned features, each with file:line citations into pi/opencode/codex/claude-code/grok. Read first: the "new" feature is often already specced here. Check the box when you ship.
• docs/learnings/other-harnesses/ — harness exploration reports. Read when porting a behavior — the research may already be done.

Design principles (apply throughout)

• Minimal is the product — ponytail is on by default. Before writing code, run the ladder: does this need to exist? is it already here (check docs/features.md)? does stdlib cover it? is it a small composition over an already-imported dep? Only then write the minimum that works. A new dependency is a big deal — go.mod fits on one screen; justify additions in the plan. Mark deliberate shortcuts inline: // ponytail: <what would generalize this> (grep ponytail for examples).
• Learn from the other harnesses, port the Go way. Don't transliterate TypeScript — find the Go-native shape (pi's promise chains became a 1-capacity channel semaphore; opencode's Deferred registry became one channel close — see docs/concurrency.md). Cite the reference (file:line) in the plan and doc comments.
• Channels over locks; capacity is the contract. Size results channels to the batch; a 1-buffer channel is a mutex; close(ch) once wakes all waiters. Every goroutine has an obvious owner and exit; everything concurrent passes go test -race.
• Errors are tool output, not loop-abort. Tool failures return "Error: <msg>" strings fed back to the model (tools.Execute) — a broken tool never kills the turn. Reserved error returns are for infrastructure. Bound everything: maxOutput truncation markers, timeouts always.
• Context flows, cancellation is real. ctx threads from TUI keypress through Agent.Turn into every tool; ctrl+c must actually stop in-flight work. No context.Background() in library code.
• Config is guarded on write. ~/.whip/config.json writes are atomic (tmp+rename, .bak kept) with a clobber-refusal guard. Never bare os.WriteFile persisted state.
• Docs are part of the diff. A feature without its docs/features.md section (behavior → code → tests) and roadmap checkbox is incomplete.

The loop

Steps 0–2 are cheap and prevent expensive mistakes; don't skip them because the feature "seems small." Steps 3–7 are the build.

0. Clarify ambiguity before doing anything

Building the wrong thing well is the most expensive outcome. Ask about: the actual user problem (not the proposed solution), where it lives (tool? agent loop? TUI? config? session store?), what the model sees vs what the human sees, what "done" looks like, non-goals, and which harness's behavior it's meant to match or beat. Short batch of concrete questions. If the brief is rich, confirm understanding in two sentences and flag only genuine unknowns.

Rule of thumb: you should be able to write the plan's "Goal" and "Non-goals" without guessing.

1. Mine the prior art

Read docs/roadmap.md and docs/learnings/ first. If porting harness behavior and the research isn't done, do it now: find the reference implementation (pi at ~/code/pi, opencode under ~/code/coding-harnesses/), understand why it's built that way, sketch the Go-native port. Cite findings in the plan — a reviewer should check the port against the original, not your memory.

2. Understand the architecture you're building into

Read docs/features.md end to end. Non-negotiables:

• Five surfaces. A new tool (internal/tools — a Tool{Def, Run} appended in agent.New; remember subagents get tools.All() too), agent-loop behavior (internal/agent), TUI interaction (internal/tui — a case in the command() switch, palette panel, key handling, transcript block), config (internal/config), or persistence (internal/session — SQLite; Save(id, from, msgs) writes incrementally). The plan names surfaces and files.
• The tool contract is load-bearing. Defs go to the provider verbatim; outputs are strings capped at maxOutput; failures return error strings. Parallel execution is the default — mutations declare their path for toolMutationPath or take the global bash lock. Design for parallel calls and -race.
• Two places for state. Agent.Messages + transcript blocks in-session; session.Store across sessions. No third place without justification.
• The TUI is a busy/idle state machine. Turns run in goroutines that p.Send messages back; keys mean different things busy vs idle (two-stage ctrl+c). Rendering is width-dependent; blocks re-render on resize.

3. Write a living plan

Create .ai-docs/plans/<slug>/README.md: H1 title, Branch: line, "What this does" / "Goal", "Non-goals", design (surfaces, file paths, sketches of new types and channel lifecycles), prior-art citations, test plan, docs plan (the features.md section + roadmap checkbox), ordered task breakdown.

This is the shared source of truth — you, delegated subagents (task tool, background: true for parallel lanes), and reviewers read it. Keep it current: check off tasks, record deviations, leave breadcrumbs for a fresh agent to pick up mid-stream. A stale plan is worse than none.

Checkpoint: get user sign-off before writing code.