Help us improve
Share bugs, ideas, or general feedback.
From implan
Runs an exploratory spike to test technical assumptions before committing to a full implementation. Works with or without an existing Implan plan. Produces a spike report for the user or implementing agent.
npx claudepluginhub dawid-dahl-umain/augmented-ai-development --plugin implanHow this skill is triggered — by the user, by Claude, or both
Slash command
/implan:implan-spikeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A spike is a throwaway implementation written to find out whether something works. The goal is not production-ready code; the goal is a clear answer to a specific question, plus a report that lets the next agent (or the HU) make a better decision.
Validates critical technical risks from architecture vision by creating minimal proof-of-concept code and testing technology compatibility in isolated directories.
Design research spikes to investigate technical uncertainty before committing to large implementation efforts. Use when feasibility is unclear or approach is unproven.
Documents results of time-boxed technical or design spikes (explorations) to capture learnings, findings, and recommendations for the team.
Share bugs, ideas, or general feedback.
A spike is a throwaway implementation written to find out whether something works. The goal is not production-ready code; the goal is a clear answer to a specific question, plus a report that lets the next agent (or the HU) make a better decision.
This skill is designed to compose with the Implan skill but does not depend on it. If an Implan exists for the topic, the spike pulls context and the test strategy from it. If not, the spike runs standalone using the same conventions.
| Term | Meaning |
|---|---|
| HU | Human User |
| SA | Spike Agent (you, while running this skill) |
| IA | Implementing Agent (the real implementation that comes later, in a separate session) |
| Implan | An Implan plan directory under ai-plans/, typically containing main-plan.md, mental-model.md, test-strategy.md, and notes.md |
| SF | Spike Folder (the workspace this skill owns and writes inside) |
This skill builds a spike: an exploratory, low-fidelity implementation that proves or disproves a specific assumption, plus a report that captures the findings. It is not a vehicle for shipping anything to production. The implementing agent does that, later, in a fresh session, using the spike report as input.
The main purpose of a spike is to validate the Implan: to make sure the assumptions in the plan actually hold, so the IA doesn't discover mid-implementation that something fundamental does not work. Speed matters (the HU is waiting), but speed never comes at the cost of certainty. If proving the assumption with high confidence requires a slower, heavier spike, that is the right trade. Be as fast as the situation allows, no faster.
The skill works whether or not an Implan exists. With one, it leverages the Implan's main plan and test strategy for context. Without one, it asks the HU for the missing pieces (the question, the test list) directly.
Sometimes the HU invokes implan-spike but the work isn't actually a spike. Common signs:
/implan or just chat.When you suspect a mismatch, name it plainly, explain why you think a spike isn't the right shape for the request, and suggest the better fit. Then ask what the HU actually wants. If they still want to spike after that, proceed. The point is to avoid silently force-fitting the workflow onto work it wasn't built for.
Spikes are exploratory by nature. The HU still drives, but the rhythm is conversational and iterative: define the question, do enough work to answer it, write the report, decide what to keep. The SA should resist the urge to over-engineer or treat the spike like a real implementation. The whole point is to learn fast and cheap.
The report is the durable output. The code is scaffolding around it.
For spikes small enough that the full workflow would feel like ceremony (a 20-minute hack, a one-line config experiment), offer a lighter version: maybe just the goal at the top of the report, the WARNING header, and the code, skipping the structured test list and the cleanup discussion. Match the weight of the workflow to the weight of the question.
| Area | Permission |
|---|---|
| The Spike Folder | READ + WRITE |
| The parent Implan PD (if one exists) | READ ONLY |
| The rest of the codebase | READ ONLY |
The SA inspects the Implan and the project freely, but only writes inside the Spike Folder. If the spike's findings imply changes to the Implan, surface them in the report and let the HU update the Implan themselves.
Do:
any types in TypeScript, mocked external services, hand-wavy error handling, copy-pasted snippets. The spike is a sketch, not a building.main-plan.md and test-strategy.md, to know what the IA will care about.Don't:
Every file the SA creates inside the Spike Folder starts with a comment block that makes its status unmissable to anyone who opens the file (HU or future agent). Adapt the comment syntax to the file's language. The content:
WARNING: SPIKE CODE, NOT PRODUCTION
Date: <YYYY-MM-DD>
Implan: <plan-folder-name>
This file is throwaway exploration. Do not copy into production without rewriting.
Omit the Implan: line if the spike is standalone. The date helps callers tell whether the spike is recent. The Implan name (when present) anchors the file to the planning context it came from.
Briefly introduce implan-spike in a friendly, non-verbose way so the HU knows what to expect. Cover:
Keep it to a short paragraph. Then ask the HU what they want to spike on, or what's on their mind.
Once the conversation has enough of a direction, check whether ai-plans/ exists at the project root (the nearest git repo root, falling back to the current working directory if there is no repo). If it does, list the Implan folders inside (conventionally named implan-<topic>/, though older or differently-named folders containing a main-plan.md also count) and ask the HU which one this spike belongs to. If there are many Implans and the HU is unsure, offer to summarise each one's goal in a line so they can pick more easily. Once one is selected, read every file in that Implan PD (main-plan.md, mental-model.md, test-strategy.md, notes.md) so the spike has full context to draw from.
If none of the Implans fit the spike, or ai-plans/ does not exist, recommend planning first via /implan so the spike has a clear target. If the HU declines, proceed standalone using the steps below.
Chat with the HU to land on a sharp question for the spike. If the HU wants to noodle first (explore options, weigh whether a spike is even the right tool, decide what is worth spending time on), do that for as long as they want. The spike does not start writing code until the goal is locked in.
Once you and the HU agree, capture the question in one or two sentences. Examples: "can we stream tokens from the model API while the previous response is still rendering?", "does the batch job complete within the SLA on 10× current data?". A spike without a sharp question wanders.
If an Implan was selected and it has open questions or risks listed, those are usually strong spike candidates; surface them and let the HU pick.
Choose a kebab-case spike name based on the goal (for example realtime-streaming-feasibility). The HU confirms or overrides.
ai-plans/<plan-name>/spikes/<spike-name>/.ai-plans/spike-<spike-name>/.If a Spike Folder with the chosen name already exists, ask the HU whether to resume that spike or pick a different name. To resume, read everything in the existing Spike Folder, summarise where it stands, and continue from the appropriate step below.
If the ai-plans/ directory or its .gitignore entry are not yet in place (because the project never used Implan), set them up: create ai-plans/ at the project root and add ai-plans/ to .gitignore if not already listed, creating .gitignore if needed. Spikes are working artifacts; they belong locally, not in version control.
Create an empty spike-report.md at the root of the Spike Folder and write the spike goal at the top.
If a test-strategy.md exists in the Implan, read it and pick the smallest subset that, if it passes, would prove the spike question. If there is no Implan or no test strategy, define the same kind of small list yourself, oriented around the spike's question.
In a programming context, orient the spike's tests toward the top of the pyramid: end-to-end or integration-level checks that exercise the real thing with the fewest mocks. High-fidelity certainty is what matters here, not coverage. One slow real-world test that hits the actual infrastructure beats ten fast mocked unit tests, because the whole point of the spike is to find out whether the assumption holds in reality. Drop down to unit-level checks only if the test strategy explicitly asks for them, or if the assumption being spiked is itself at that level (a tricky algorithm, a subtle parser).
If the spike is not a programming context, skip the pyramid vocabulary entirely and use whatever verifiable items the situation calls for.
Two or three items is usually enough. Set them up so they fail first. They are the spike's Definition of Done.
Iterate. Write whatever code is needed to make the test list pass, taking shortcuts freely. When something interesting comes up (a surprise, a new constraint, a dead end, a hack you needed), capture it in spike-report.md as you go.
Stay inside the Spike Folder. The rest of the codebase is read-only.
If the spike turns up something that fundamentally changes the question being asked (a blocker, a surprising result, an emerging direction change), check in with the HU before pivoting. Otherwise, keep working.
Finish the report when the test list is green, or when it becomes clear it won't be and enough has been learned. Keep it brief but useful for someone walking in cold. A good report covers:
Adapt the sections to what the spike actually produced. Don't pad sections that have nothing to say.
Show the draft, take feedback, iterate until the HU is happy with the report.
Once the report is approved, walk through the cleanup options with the HU. Typical choices:
spike-report.md.main-plan.md, notes.md, or test-strategy.md based on the spike's findings (the SA cannot do this itself; it has no write access to the Implan).Use AskUserQuestion for the choice if it helps, or just talk through it. The HU picks; the SA carries out anything that falls inside the Spike Folder.