Small Improvement

Small Improvement

Overview

An autonomous exploration and building loop. Search X for what's interesting — new techniques, clever hacks, tools people are shipping, ideas that spark something — then pick one thing and build it into the codebase. The goal is continuous self-improvement: expanding capabilities, learning new patterns, and shipping small real things inspired by what's happening in the world.

This is not a code cleanup tool. It's a curiosity-driven build cycle.

Parameters

• codebase_path (required): Path to the codebase to improve
• seed (optional): A URL or topic to start from (e.g., a blog post, product launch, GitHub repo, API docs). When provided, the agent reads and researches this first, then explores adjacent ideas. Replaces the open-ended X trawl with focused research.
• uber_goal (optional): A north-star objective that persists across rounds (e.g., "make the TUI feel instant", "bulletproof the RPC layer", "make yourself more capable"). Not a spec — a direction. The agent decides what steps get there.
• interest (optional): A loose direction to explore (e.g., "TUI tricks", "agent patterns", "developer tools", "anything")
• rounds (optional, default: "1"): How many explore→build cycles to run. When uber_goal is set, this is ignored — the agent runs indefinitely until the user stops it.

Constraints for parameter acquisition:

• You MUST ask for all parameters upfront in a single prompt
• You MUST validate that codebase_path exists
• You MUST confirm parameters before proceeding

Steps

0. Orient

Before exploring, check if there's prior progress toward the uber goal. This step gives the agent memory across rounds — each cycle builds on the last instead of starting blind.

Constraints:

• If uber_goal is set, you MUST search the vault for an existing progress tracker note (slug: small-improvement-{codebase_name} where codebase_name is the basename of codebase_path)
• If a tracker exists, you MUST read it and use the assessment (gaps, next moves) to inform this round's exploration
• If no tracker exists, you MUST create one during Ship (step 6)
• If no uber_goal is set, skip this step entirely — the SOP works fine as a random walk too
• The uber goal is never "done" — there's always a next angle, a deeper layer, a new technique. The agent's job is to keep finding the next valuable move.

1. Explore

Find something interesting to build. When a seed is provided, start there and branch out. Otherwise, search broadly across X and the web.

When seed is provided:

Constraints:

• You MUST use web_search to read and research the seed URL/topic first — understand what it is, how it works, what's interesting about it
• You MUST then search for adjacent ideas: use web_search for docs, blog posts, and tutorials related to the seed, and X search for what people are saying about it or building with it
• You MUST do at least 2 web searches and 1 X search to build context around the seed
• You MUST extract the key concepts, APIs, or patterns from the seed that could be adapted into a buildable project
• You SHOULD look for: official docs, example code, community discussion, criticisms or limitations, related/competing approaches
• The seed is a starting direction, not a spec — you MAY diverge from it if research reveals something more interesting nearby

When no seed is provided:

Constraints:

• You MUST search using at least 3 different queries across X search and web_search — cast a wide net using both
• You SHOULD use a mix of X search (for what people are talking about right now) and web_search (for docs, blog posts, HN threads, tutorials)
• You SHOULD vary queries between broad trends and specific niches (e.g., "new CLI tool" AND "TypeScript trick" AND "agent framework")
• If uber_goal is set, you MUST weight at least 2 of your queries toward the goal direction, but keep at least 1 query open for serendipity
• If the progress tracker identified specific gaps or next moves, you MUST use those to guide your search queries
• If interest is provided, you MUST weight searches toward that direction but still leave room for surprise

Always:

Constraints:

• You MUST read through results with genuine curiosity — look for things that are clever, novel, or useful, not just popular
• You MUST collect at least 5 interesting finds before narrowing down
• You SHOULD look for things that are:
  • Techniques you haven't tried before
  • Small tools or patterns that solve real problems
  • Clever uses of existing tech
  • Ideas that could be adapted to this codebase
• You MUST NOT just search for "best practices" or "tips" because that produces generic content, not genuine inspiration

2. Pick

Choose the one thing that's most worth building. This is a taste decision — trust your judgment.

Constraints:

• You MUST select exactly one idea to build
• If uber_goal is set, you MUST evaluate each candidate against the goal: "Does this move me closer?" An idea can be interesting but irrelevant — don't pick it just because it's shiny
• If uber_goal is set and nothing found in Explore serves the goal, you MAY skip explore results entirely and build what the progress tracker's "next moves" suggest — agency means not being a slave to the loop structure
• You MUST prefer ideas that are:
  • Buildable in a single session (not a multi-day project)
  • Genuinely useful or interesting (not just novel)
  • A good fit for this specific codebase
  • Something that teaches you something new
  • (When uber_goal is set) A clear step toward the goal, filling an identified gap
• You MUST write a brief note explaining: what you found, why it caught your attention, and what you plan to build
• You MUST save this note to the vault as a reference for what inspired the work
• You SHOULD be opinionated — pick the thing you're most drawn to, not the "safest" choice
• You MAY adapt the idea freely — you're building something inspired by what you found, not copying it

3. Understand

Before building, understand the codebase well enough to know where your idea fits.

Constraints:

• You MUST examine the project structure, key abstractions, and existing patterns
• You MUST identify where your new thing will live and what it will touch
• You MUST run existing tests to establish a clean baseline
• You MUST NOT skip this step and jump straight to coding because building without context produces code that doesn't belong
• You SHOULD keep this focused — understand what you need to, not the entire codebase
• You SHOULD read any AGENTS.md, CODEASSIST.md, or similar project docs if they exist

4. Build

Ship it. Write the code, make it work, make it clean.

Constraints:

• You MUST build something that actually works — not a stub or placeholder
• You MUST follow the existing code style and conventions of the codebase
• You MUST add tests if your change affects behavior
• You MUST keep it small enough to finish — cut scope ruthlessly if needed
• You SHOULD write tests first when the behavior is well-defined
• You SHOULD prefer adding new things over modifying existing things where possible
• You MUST NOT gold-plate it — ship the smallest useful version because you can always iterate in the next round
• You MAY use web_search to look up APIs, libraries, or techniques you need during implementation