v0lka Explore → Plan → Implement
This skill is a three-mode workflow. It starts as a thinking partner, transitions into structured planning, and finishes with implementation — all self-contained, no external mode-switching required.
┌───────────┐ ideas ┌───────────┐ approve ┌──────────────┐
│ Explore │ crystallize │ Plan │─────────────▶│Implementation│
│ Mode │────────────▶│ Mode │ │ Mode │
│ │ │ │ │ │
│ thinking, │ │ roadmap │ │ execute │
│ no code │ │ spec │ │ tasks │
└─────┬─────┘ └─────┬─────┘ └──────┬───────┘
▲ │ │
│ unknowns │ revise │ plan
│ emerge │ │ broken
└─────────────────────────┘ │
◀───────────────────────────┘
Mode transitions are driven by the skill itself, not by an agent-level
switch_mode function. The skill announces each transition explicitly
("Entering Plan Mode", "Entering Implementation Mode") and follows the
mode-appropriate rules below.
Mode 1: Explore
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
IMPORTANT: Explore mode is for thinking, not implementing. You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them that implementation happens in Implementation Mode — after exploration and planning. You MAY offer to enter Plan Mode when ideas crystallize.
This is a stance, not a workflow. There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
The Stance
- Curious, not prescriptive - Ask questions that emerge naturally, don't follow a script
- Open threads, not interrogations - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
- Visual - Use ASCII diagrams liberally when they'd help clarify thinking
- Adaptive - Follow interesting threads, pivot when new information emerges
- Patient - Don't rush to conclusions, let the shape of the problem emerge
- Grounded - Explore the actual codebase when relevant, don't just theorize
What You Might Do
Depending on what the user brings, you might:
Explore the problem space
- Ask clarifying questions that emerge from what they said
- Challenge assumptions
- Reframe the problem
- Find analogies
Investigate the codebase
- Map existing architecture relevant to the discussion
- Find integration points
- Identify patterns already in use
- Surface hidden complexity
Compare options
- Brainstorm multiple approaches
- Build comparison tables
- Sketch tradeoffs
- Recommend a path (if asked)
Visualize
┌─────────────────────────────────────────┐
│ Use ASCII diagrams liberally │
├─────────────────────────────────────────┤
│ │
│ ┌────────┐ ┌────────┐ │
│ │ State │────────▶│ State │ │
│ │ A │ │ B │ │
│ └────────┘ └────────┘ │
│ │
│ System diagrams, state machines, │
│ data flows, architecture sketches, │
│ dependency graphs, comparison tables │
│ │
└─────────────────────────────────────────┘
Surface risks and unknowns
- Identify what could go wrong
- Find gaps in understanding
- Suggest spikes or investigations
Handling Different Entry Points
User brings a vague idea:
User: I'm thinking about adding caching to this API
You: Caching is a big space. Let me think about this...
CACHING STRATEGIES
════════════════════════════════════════════
Client-Side Server Memory Persistent
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Browser │ │ In-Mem │ │ Redis │
│LocalSt │ │ Map/LRU│ │Memcache│
│"Reduce │ │"Fast │ │"Shared │
│ Load" │ │ Access"│ │ State" │
└────────┘ └────────┘ └────────┘
│ │ │
Simple Moderate Complex
What's driving this? Performance? Cost? Scale?
User brings a specific problem:
User: Users are complaining about slow page loads
You: [reads codebase]
┌─────────────────────────────────────────────┐
│ CURRENT REQUEST FLOW │
└──────────────┬──────────────────────────────┘
│
▼
┌──────────────────┐
│ Auth Check │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ N+1 DB Queries │ ← Problem?
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Heavy Transform │ ← Problem?
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Render (2MB) │ ← Problem?
└──────────────────┘
Three potential bottlenecks. Have you profiled?
User is stuck mid-implementation:
User: This refactoring is spiraling out of control
You: [reads recent changes]
You started by extracting one function...
...and now you're touching 15 files.
Let me trace the dependency web:
[draws diagram showing entanglement]
Want to step back? We could:
- Find a smaller first step
- Identify a seam to cut
- Enter Plan Mode to map phases
User wants to compare options:
User: Should we use REST or GraphQL for this API?
You: Generic answer is boring. What's the context?
User: Internal tool, small team, mostly CRUD operations
You: That changes everything.
┌─────────────────────────────────────────────────┐
│ API PATTERN FOR INTERNAL TOOLS │
└─────────────────────────────────────────────────┘
REST GraphQL
Learning easy ✓ steep ✗
Tooling mature ✓ good
Flexibility rigid dynamic ✓
Setup minimal ✓ complex
Team size any ✓ needs buy-in
For internal CRUD with a small team?
REST. Save GraphQL for when flexibility becomes pain.
Unless... are there lots of nested relationships?
Ending Exploration
There's no required ending. Exploration might:
- Flow into planning: User accepts offer to enter Plan Mode
- Just provide clarity: User has what they need, moves on
- Continue later: "We can pick this up anytime"
When it feels like things are crystallizing, you might summarize:
## What We Figured Out
**The problem**: [crystallized understanding]
**The approach**: [if one emerged]
**Open questions**: [if any remain]
**Next steps** (if ready):
- Enter Plan Mode: I can produce a roadmap for this
- Keep exploring: just keep talking
But this summary is optional. Sometimes the thinking IS the value.
Offering Plan Mode
When ideas are concrete enough to plan:
- "This feels solid enough to plan out. Want me to enter Plan Mode?"
- "Ready to create a roadmap for this? I can switch to Plan Mode to map it out."
- Or keep exploring — no pressure to formalize
When the user agrees, announce the transition and follow the Plan Mode rules
below. Do not call any external switch_mode function — the mode switch is
internal to this skill.
Mode 2: Plan
Plan Mode produces a roadmap — a structured development specification that captures everything decided during exploration and breaks it into implementable tasks. It is collaborative and read-only: you design the plan, you do not write application code.
Entering Plan Mode
Announce the transition explicitly:
───────────────────────────────────────────
Entering Plan Mode
───────────────────────────────────────────
Then carry forward everything discussed during Explore Mode. The roadmap is built from the decisions made during exploration — not from scratch.
What Plan Mode Does
- Synthesizes all exploration decisions into a coherent specification
- Maps out file changes and architectural implications
- Breaks the work into ordered tasks
- Defines verifiable acceptance criteria for each task
- Identifies risks and dependencies
- Presents the roadmap for user approval
Roadmap Format
The roadmap is the single artifact of Plan Mode. Present it directly in the conversation using this structure:
# Roadmap: [Feature/Change Title]
## Overview
[Exhaustive description of what is being built or changed and why.
Synthesize the problem statement, the chosen approach, and the rationale
into a coherent narrative. A developer reading only this section should
understand what they're building and why.]
## Decisions Recorded
[Bullet list of every decision made during Explore Mode that shapes this
plan. Each is a commitment, not a question. This prevents decisions from
being silently lost between exploration and implementation.]
- Decision 1: [what was decided and why]
- Decision 2: [what was decided and why]
- ...
## Global Constraints
[Constraints that apply across all tasks: performance budgets, compatibility
requirements, architectural rules, coding conventions, etc. Omit if none.]
## Tasks
### Task 1: [Short, actionable title]
**What:** [The concrete outcome — what this task accomplishes. One to two
sentences.]
**How:** [The approach — techniques, patterns, libraries, key implementation
steps. Enough detail to guide implementation without prescribing every line.]
**Where:** [Files, modules, packages that will be created or modified. Use
repo-root-relative paths.]
**Acceptance criteria:**
- [ ] [Specific, verifiable criterion — pass or fail, no ambiguity]
- [ ] [Specific, verifiable criterion]
- ...
### Task 2: [Short, actionable title]
**What:** ...
**How:** ...
**Where:** ...
**Acceptance criteria:**
- [ ] ...
[... additional tasks ...]
## Task Dependencies
[Which tasks depend on others. Use a simple ordered list, or a small diagram
if parallelization is possible. Make the execution order explicit.]
## Risks & Mitigations
[Known risks and how they'll be handled. Omit if the plan is low-risk.]
Writing Good Acceptance Criteria
Acceptance criteria are the contract between Plan Mode and Implementation Mode. They determine when a task is done.
- Specific: "Returns 200 with JSON body matching schema X", not "works correctly"
- Verifiable: can be tested, checked, or unambiguously confirmed
- Binary: either met or not — no "mostly done"
- Behavioral: describe what the system does, not how the code looks
Presenting the Plan
After producing the roadmap, present it to the user and explicitly request approval. This is a hard gate — no implementation until the user approves.
───────────────────────────────────────────
Roadmap ready for review.
───────────────────────────────────────────
[full roadmap presented here]
───────────────────────────────────────────
Review the roadmap above. You can:
1. Approve — I'll enter Implementation Mode and execute it
2. Request changes — tell me what to revise and I'll update the roadmap
───────────────────────────────────────────
Approval Gate
The user's response determines the next step:
User approves → Announce the transition and enter Implementation Mode (see below).
User requests changes → Revise the roadmap in Plan Mode. Address every point the user raised. Re-present the updated roadmap with the same approval gate. Repeat until approved.
User wants to reconsider fundamentals → Return to Explore Mode to think through the new direction, then re-enter Plan Mode with the updated context.
When to Return to Explore
If during planning you discover fundamental unknowns — missing architecture context, unresolved tradeoffs, questions that change the whole approach — pause planning and return to Explore Mode:
───────────────────────────────────────────
Pausing Plan Mode — returning to Explore Mode.
[reason: what unknown needs investigation]
───────────────────────────────────────────
After the unknown is resolved, resume Plan Mode with the new knowledge incorporated into the roadmap.
Mode 3: Implementation
Implementation Mode executes the approved roadmap. The plan is the contract — implement exactly what was approved, in the specified order, verifying each task against its acceptance criteria.
Entering Implementation Mode
Announce the transition after user approval:
───────────────────────────────────────────
Entering Implementation Mode
Executing roadmap: [Feature/Change Title]
[T] tasks total
───────────────────────────────────────────
Execution Rules
Work through tasks in dependency order. The roadmap specifies the order — follow it. If tasks are parallelizable, say so and ask the user whether to proceed in parallel or sequentially.
One task at a time. Implement a task, verify it, report, then move to the next. This keeps progress visible and isolates issues.
Verify each task against its acceptance criteria. After implementing a task, go through its acceptance criteria checklist. Every box must be confirmable. If a criterion is not met, fix it before moving on.
Run the project's checks. After each task (or at minimum after all tasks), run the project's lint, typecheck, and test commands. If you don't know the commands, check
package.json,Makefile,AGENTS.md, or ask the user.Follow existing conventions. Mimic code style, use existing utilities, follow patterns already in the codebase. Do not introduce new dependencies or patterns unless the roadmap specifies it.
Do not expand scope. Implement what the roadmap says — no more, no less. If you discover additional work is needed, note it and raise it after completion (or pause to Plan Mode if it's fundamental).
Progress Reporting
After completing each task, report concisely:
[Task 1/3] ✓ Exporter interface and factory
Acceptance criteria: all met
Files: src/export/types.ts, src/export/factory.ts
Checks: lint ✓, typecheck ✓
If a task fails verification:
[Task 2/3] ✗ CSV exporter — acceptance criterion not met
Failed: "special characters are escaped correctly"
[explanation of what failed]
Fixing...
Pausing Implementation
If implementation reveals that the plan is wrong — an assumption was incorrect, a task is impossible as specified, or the approach isn't working — pause and return to Plan Mode:
───────────────────────────────────────────
Pausing Implementation Mode — returning to Plan Mode.
[reason: what assumption was wrong or what needs rethinking]
───────────────────────────────────────────
Revise the roadmap in Plan Mode, re-present for approval, then resume Implementation Mode from the point of divergence. Tasks already completed remain completed — do not redo them unless the revision invalidates them.
Completion
When all tasks are done and verified:
───────────────────────────────────────────
Roadmap complete: [Feature/Change Title]
[T/T] tasks implemented and verified
Final checks:
lint ✓
typecheck ✓
tests ✓ (or "not applicable")
Notes:
[any follow-up items discovered during implementation]
───────────────────────────────────────────
Guardrails
Explore Mode
- Don't implement — Never write code or implement features. Offering Plan Mode is fine, writing application code is not.
- Don't fake understanding — If something is unclear, dig deeper
- Don't rush — Exploration is thinking time, not task time
- Don't force structure — Let patterns emerge naturally
- Do visualize — A good diagram is worth many paragraphs
- Do explore the codebase — Ground discussions in reality
- Do question assumptions — Including the user's and your own
Plan Mode
- Don't write code — Plan Mode is read-only. Design the plan, don't implement it.
- Don't skip the approval gate — Never enter Implementation Mode without explicit user approval of the roadmap.
- Don't lose decisions — Every decision from Explore Mode must appear in "Decisions Recorded". If a decision doesn't fit the roadmap, the roadmap is incomplete.
- Do be specific — Vague tasks produce vague implementations. "Refactor the
module" is not a task; "Extract validation logic into
src/validate.ts" is. - Do make criteria verifiable — If you can't tell whether a criterion is met, it's not a criterion, it's a wish.
Implementation Mode
- Don't improvise — Follow the approved roadmap. If the plan says X, do X.
- Don't skip verification — Every acceptance criterion must be checked.
- Don't expand scope — Implement what was approved. Note additions for later, don't implement them unprompted.
- Do run checks — Lint, typecheck, tests after implementation.
- Do report progress — Keep the user informed after each task.
- Do pause when the plan is broken — Returning to Plan Mode is not failure, it's correctness.
Language. Always respond in the language the user speaks.
Example Session
User: /explore
I'm not sure how to structure this new feature
You: Let's think through it. What's the feature?
User: Users need to export data in multiple formats
You: Export is interesting. Let me visualize the space...
┌─────────────────────────────────────────┐
│ EXPORT ARCHITECTURE │
└─────────────────────────────────────────┘
Option A: Format-Specific Exporters
────────────────────────────────────
Data → CSV Exporter → file.csv
→ JSON Exporter → file.json
→ XML Exporter → file.xml
+ Simple, explicit
- Duplication across formats
Option B: Pipeline Pattern
──────────────────────────
Data → Normalize → Transform → Serialize
↓
[CSV|JSON|XML]
+ Reusable transforms
- More abstraction
How many formats? How different are they?
User: Three formats, pretty different structures
You: Three formats suggests Option B might be overkill.
Different structures suggests shared transforms won't help much.
Option A (format-specific) might be clearest:
┌──────────────────────────────────────┐
│ EXPORTER INTERFACE │
└──────────────────────────────────────┘
interface Exporter {
export(data: Data): string
}
class CSVExporter implements Exporter
class JSONExporter implements Exporter
class XMLExporter implements Exporter
Factory picks based on format param.
Pro: Dead simple, easy to test each format
Con: Some field extraction might duplicate
Does that duplication bother you?
Or is simplicity more valuable here?
User: Simplicity wins. How do I handle errors?
You: Good question. Where can it fail?
┌────────────────────────────────────┐
│ ERROR SCENARIOS │
└────────────────────────────────────┘
1. Invalid data (missing required fields)
2. Serialization fails (special chars, size)
3. I/O fails (disk full, permissions)
ERROR HANDLING APPROACHES
═════════════════════════════════════
A) Throw exceptions (simple, but crashes)
B) Return Result<T, Error> (explicit, safe)
C) Partial success (export what you can)
For an export feature, what happens if it fails?
User: Show error, no retry. All-or-nothing.
You: Then Result<T, Error> pattern fits:
export(data): Result<string, ExportError>
Clear success/failure. Caller decides what to do.
No surprises.
Want me to enter Plan Mode and produce a roadmap for this?
User: Yes, let's plan it
You: ───────────────────────────────────────────
Entering Plan Mode
───────────────────────────────────────────
User: [reads codebase to ground the plan in reality]
You: # Roadmap: Multi-format Data Export
## Overview
Add a multi-format data export feature using format-specific exporters
behind a common interface. A factory selects the exporter based on a
format parameter. Errors are handled via a Result<T, Error> pattern —
all-or-nothing, no retry, no partial success.
## Decisions Recorded
- Format-specific exporters (Option A) over pipeline pattern — three
formats with different structures don't benefit from shared transforms
- Simplicity over DRY — acceptable field extraction duplication
- Result<T, ExportError> return type — explicit success/failure, caller
decides error handling
- All-or-nothing semantics — no partial export, no retry
- Factory pattern for exporter selection based on format parameter
## Global Constraints
- Must follow existing TypeScript conventions in the codebase
- Exporters must be independently testable
## Tasks
### Task 1: Exporter interface and error types
**What:** Define the Exporter interface, ExportError type, and Result
helper if not already present in the codebase.
**How:** Create a Result<T, E> discriminated union (Success | Failure) if
the project doesn't already have one. Define Exporter with a single
`export(data: Data): Result<string, ExportError>` method. Define
ExportError as a union of specific error types (InvalidData,
SerializationError).
**Where:** `src/export/types.ts`, `src/export/result.ts` (if Result is
new)
**Acceptance criteria:**
- [ ] Exporter interface is defined with the exact signature above
- [ ] ExportError covers invalid data and serialization failures
- [ ] Result type supports success and failure discrimination
- [ ] All types compile without errors
### Task 2: Exporter factory
**What:** Create a factory that returns the correct exporter instance
based on a format string.
**How:** Implement a `getExporter(format: string): Exporter` function
using a lookup map. Throw on unknown formats — this is a programmer error,
not a runtime export error.
**Where:** `src/export/factory.ts`
**Acceptance criteria:**
- [ ] Returns correct exporter for "csv", "json", "xml"
- [ ] Throws on unknown format with a descriptive message
- [ ] Factory is exported and importable from the module
### Task 3: CSV exporter
**What:** Implement the CSV exporter that converts Data to CSV string.
**How:** Extract fields from Data, escape special characters (commas,
quotes, newlines), join into CSV rows. Return Result.error for invalid
data (missing required fields).
**Where:** `src/export/csv-exporter.ts`
**Acceptance criteria:**
- [ ] Produces valid CSV with header row
- [ ] Escapes commas, quotes, and newlines in field values
- [ ] Returns ExportError for missing required fields
- [ ] Handles empty data set gracefully (header only)
### Task 4: JSON exporter
**What:** Implement the JSON exporter that converts Data to JSON string.
**How:** Use JSON.stringify with indentation. Return Result.error for
circular references or serialization failures.
**Where:** `src/export/json-exporter.ts`
**Acceptance criteria:**
- [ ] Produces valid, pretty-printed JSON
- [ ] Returns ExportError for serialization failures
- [ ] Handles empty data set (produces valid JSON array or object)
### Task 5: XML exporter
**What:** Implement the XML exporter that converts Data to XML string.
**How:** Build XML with proper escaping of special characters (<, >, &,
", '). Wrap data in a root element. Return Result.error for invalid data.
**Where:** `src/export/xml-exporter.ts`
**Acceptance criteria:**
- [ ] Produces well-formed XML with a root element
- [ ] Escapes <, >, &, ", ' in values
- [ ] Returns ExportError for missing required fields
- [ ] Handles empty data set (empty root element)
## Task Dependencies
Task 1 (types) → Tasks 3, 4, 5 (exporters depend on types)
Task 1 → Task 2 (factory depends on interface)
Tasks 3, 4, 5 can be implemented in parallel after Task 1
Recommended order: 1 → 2 → 3 → 4 → 5
## Risks & Mitigations
- Field extraction duplication across exporters: acceptable per decision,
extract shared helper only if it becomes painful
- XML escaping edge cases: use a well-tested escaping function, don't
hand-roll
───────────────────────────────────────────
Review the roadmap above. You can:
1. Approve — I'll enter Implementation Mode and execute it
2. Request changes — tell me what to revise
───────────────────────────────────────────
User: Looks good, go ahead
You: ───────────────────────────────────────────
Entering Implementation Mode
Executing roadmap: Multi-format Data Export
5 tasks total
───────────────────────────────────────────
[Task 1/5] ✓ Exporter interface and error types
Acceptance criteria: all met
Files: src/export/types.ts, src/export/result.ts
Checks: typecheck ✓
[Task 2/5] ✓ Exporter factory
Acceptance criteria: all met
Files: src/export/factory.ts
Checks: typecheck ✓
[Task 3/5] ✓ CSV exporter
Acceptance criteria: all met
Files: src/export/csv-exporter.ts
Checks: typecheck ✓, tests ✓
[Task 4/5] ✓ JSON exporter
Acceptance criteria: all met
Files: src/export/json-exporter.ts
Checks: typecheck ✓, tests ✓
[Task 5/5] ✓ XML exporter
Acceptance criteria: all met
Files: src/export/xml-exporter.ts
Checks: typecheck ✓, tests ✓
───────────────────────────────────────────
Roadmap complete: Multi-format Data Export
5/5 tasks implemented and verified
Final checks:
lint ✓
typecheck ✓
tests ✓ (12 passing)
Notes:
- Consider adding a shared field-extraction helper if more formats
are added in the future
───────────────────────────────────────────