# Veda Plan Implement Review

> Use when you need to plan an approach, execute it, and review the outcome, plan AND implement with the Veda Navigator model, then review the result: align on an approach with Navigator, carry it out, then close with a reviewer pass (fix P0/P1, re-review until pass). Drives `veda -S impl-TASKNAME -m flash -p navigator-plan` to align, implements with native tools, then `-p reviewer`. Navigator has read-only tools only.

- Skill: `ryan-brosas/veda-plan-implement-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ryan-brosas/veda-plan-implement-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryan-brosas/veda-plan-implement-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ryan-brosas (https://skillmd.com/u/ryan-brosas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ryan-brosas/veda-plan-implement-review

---


## Core Principle

Align → implement → close with a reviewer loop until `review: pass`. Navigator has read-only tools and advises; you implement; the reviewer persona grades the diff against the session's `design.json`.

## When to Use / NOT

- Use when you need to plan an approach, execute it, and review the outcome in one lane.
- NOT when only planning is wanted (`veda-plan`) or when the whole cycle should be delegated to the worker agent (`veda-worker`).

## Workflow

1. Align: `veda -S impl-TASKNAME sel add` + `-p navigator-plan` (user ask verbatim, committed position); iterate via `resume`/`navigator-chat`.
2. Implement with native tools, checkpointing with evidence.
3. Capture the diff into selection, run `-p reviewer` against the auto-attached `design.json`.
4. Fix P0/P1 yourself, regenerate the diff, re-review. Stop at `review: pass` (P2 stays open, non-blocking).


## Model routing (authoritative, do not substitute)

- Load-bearing planning / architecture / high-risk review → `agy --model claude-opus-4-6-thinking --mode plan` (direct `agy` CLI, NOT veda/gemini).
- Critique / follow-up → `agy --model claude-sonnet-4-6 --mode plan`.
- Cheap discovery / context curation → `veda` + gemini (`gemini-3.7-flash-*`, `gemini-3.1-pro-low`).
- `veda deep` (parallel solvers) runs on gemini and is only for "N independent attempts"; the final architecture decision still comes from claude-opus.

## Invocation, veda CLI (confirmed working)

Use the veda CLI with **positional** prompts. Default backend/model now fixed in `~/.config/veda/config` (`BACKEND="agy"`, `MODEL="gemini-3.7-flash-high"`):

```bash
veda -S impl-<task> -p navigator-plan '<goal + context>'     # align (read-only)
# … you implement with native tools …
veda -S impl-<task> -p reviewer '<diff + design contract>'   # review pass (fix P0/P1, re-review until pass)
```

- Pin explicitly with `-b agy -m gemini-3.7-flash-high` if you ever need to override.

**Do NOT use `agents.run({ runner: "veda", ... })`:** broken with veda-ts 0.75.8, pi-fabric pipes the prompt to stdin, but veda reads positionals only (`src/cli/validate.ts` throws "No prompt provided"). Use the CLI until pi-fabric fixes the runner.

## Your Task

Collaborate, discuss, align, implement, and review with the Navigator model using `veda -S impl-TASKNAME -m flash -p navigator-plan`. First align on the plan with Navigator, then execute it, then close with a reviewer pass. The Navigator has **read-only tools** (`Read`, `Grep`, `Glob`, `LS`, `git status/log/diff`) but cannot edit or run mutating commands, it advises, you implement. You still provide curated context via `veda sel add` so the Navigator can verify your claims against the actual code; selection focuses attention and controls token cost.

**Model:** `flash` is auto-detected by `veda init` from your installed harnesses. If a `-m`/`-b` (or other veda flags) was passed when this skill was invoked, use those instead of `-m flash` in every `veda` command below.

**Reuse the same `-S` session name** across `navigator-plan` and follow-up `resume`/`navigator-chat` so the conversation continues rather than restarting.

Use `-p navigator-plan` to start, then switch to `-p navigator-chat` for follow-up discussion. Only use `navigator-plan` once per task unless the user instructs otherwise.

**Involve the user when the work requires them.** Use your `ask_user` tool (or plain questions if unavailable) when the goal is ambiguous, a decision would change scope, cost, or direction, or input only the user can provide. Navigator advises; the user decides. Otherwise, when you have enough information to act, act.

### Escaping Backticks in Prompts (Critical)

**Backticks in double-quoted prompts get evaluated by bash as command substitution.** If your prompt contains examples with backticks, they will be executed as commands:

```bash
# BAD - double quotes evaluate backticks:
veda -p navigator-plan "The function uses `console.log`"
# Results in: sh: console.log: command not found

# GOOD - use single quotes (simplest):
veda -S impl-auth-feature -m flash -p navigator-plan 'The function uses `console.log` to output.'

# GOOD - escape backticks in double quotes:
veda -p navigator-plan "The function uses \`console.log\`"
```

**Recommendation:** Use single quotes (`'...'`) for prompts containing backticks. If you need variable expansion, escape backticks with backslash in double quotes.

## Session Naming (Critical for Multi-Agent)

**Use a descriptive, contextual session ID** with `-S` to isolate your selection from other concurrent agents. Format: `impl-TASKNAME` where TASKNAME briefly describes the work.

```bash
veda -S impl-auth-refactor -m flash ...    # Implementing a refactor
veda -S impl-pricing-research -m flash ... # Researching pricing options
veda -S impl-launch-doc -m flash ...       # Drafting a launch document
```

---

## Setting Context (Critical)

**You must run `veda sel add` before sending prompts.** This is how Navigator sees your working materials: source code, drafts, notes, specs, data, research documents, transcripts. Any text file works.

```bash
# Clear and build selection (use your session name)
veda -S impl-auth-refactor sel clear
veda -S impl-auth-refactor sel add "src/feature/" "docs/notes.md"

# Check token count
veda -S impl-auth-refactor sel ls
```

**Token budget (one rule):** Always start with full files. Check `sel ls`. 75k-125k tokens is acceptable. Only use slices if you exceed 125k, and pare down starting with the largest files. More context is better for Navigator, so prefer full files when possible.

**What to share:** whatever the problem touches, plus its immediate neighbors. Navigator cannot see your terminal or environment, so put observations in the prompt itself: error output, a causal timeline, data you collected, drafts under discussion. State your hypothesis if you have one; if you are stuck, say where.

### File Slices (Line Ranges)

Only when over the 125k budget:

```bash
veda -S impl-auth-refactor sel add main.c:10-50       # Lines 10-50 only
veda -S impl-auth-refactor sel add main.c:100-        # Line 100 to end of file
veda -S impl-auth-refactor sel add config.ts:25       # Single line 25
veda -S impl-auth-refactor sel add "src/*.c:1-80"     # First 80 lines of each file
```

| Syntax | Description |
|--------|-------------|
| `file.c:10-20` | Lines 10 to 20 (inclusive) |
| `file.c:15-` | Line 15 to end of file |
| `file.c:8` | Single line 8 |
| `"src/*.c:1-50"` | First 50 lines of each matched file |

---

## Collaborating with Navigator

Think of Navigator as a senior collaborator you're pairing with. Your opening message should commit to a position, not ask an open-ended question:

- Share the user's prompt verbatim, plus who the work is for and what the output enables, so Navigator understands the actual ask rather than your interpretation
- State the goal and your proposed approach (take a stance; Navigator stress-tests it)
- Provide evidence anchors: file and section references for your key claims
- Name constraints and non-goals
- Ask 1-2 specific questions where you are uncertain
- Invite Navigator to help in any way, especially if you're stuck; a fresh perspective on a dead end is often the breakthrough

Example flow:
```bash
# 1. Set the context
veda -S impl-auth-refactor sel clear
veda -S impl-auth-refactor sel add "src/auth/" "src/api/users.ts"

# 2. Start planning conversation - commit to a position, carrying the ask VERBATIM
#
# Lead with the USER'S EXACT WORDS (quoted verbatim), then your framing —
# Navigator plans against the ask as given, so don't paraphrase it away:
veda -S impl-auth-refactor -m flash -p navigator-plan \
  '<USER PROMPT, verbatim, exactly as the user wrote it>

My understanding: [situation + evidence]. Proposed approach: [details]. Non-goals: [scope limits]. Key question: [your real uncertainty]. What do you think?'

# 3. Continue discussion (session-scoped resume)
veda -S impl-auth-refactor -m flash resume "What about edge case X?"
# Or switch to chat mode for back-and-forth
veda -S impl-auth-refactor -m flash -p navigator-chat "What about edge case X?"
```

Confirm alignment before you start executing. **Once aligned, you (the Driver) proceed to implementation.** Navigator does not execute; you do.

---

## Execution

After aligning with Navigator:
- Carry out the plan using your native tools; keep it scoped to what was agreed
- Validate as you go (check files, search for issues)
- Checkpoint with Navigator at plan-step boundaries, reporting only what you can point to evidence for: "step N done, verified by X"
- When results contradict expectations, paste the actual output verbatim and ask "repair or switch?"
- Two similar failures = mandatory Navigator consult before a third attempt
- Escalate to the user (via `ask_user`) per the rule above: scope, cost, or direction changes, or input only the user can provide
- You can consult Navigator mid-execution:
  ```bash
  veda -S impl-auth-refactor -m flash -p navigator-chat "Quick question: should X handle Y this way?"
  ```

Before ending your turn, check your last paragraph. If it is a plan, a list of next steps, or a promise about work you have not done ("I'll...", "let me know when..."), do that work now. End your turn only when the task is complete or you are blocked on input only the user can provide.

When you write your final summary, write it for a reader who did not see any of the working thread. Lead with the outcome in one sentence, then the supporting detail. Drop the working shorthand: write complete sentences, spell out terms, and don't use arrow chains or labels you made up earlier. If you have to choose between short and clear, choose clear.

## Review the Result (closing reviewer pass)

After execution, close with a **review-fix loop** using the `-p reviewer`
persona (no tools, it reviews the diff + selected context + the session's
`design.json`, auto-attached). Capture the diff into selection, then review
against the same design Navigator aligned on:

```bash
git diff -- . ':(exclude)*.png' ':(exclude)*.jpg' ':(exclude)*.woff*' > /tmp/impl.diff
veda -S impl-auth-refactor sel add /tmp/impl.diff
veda -S impl-auth-refactor sel ls      # verify the diff is in selection
veda -S impl-auth-refactor -m flash -p reviewer \
  'Implementation complete. Review the diff against this session's design.json (auto-attached) and report P0/P1/P2 findings. End with review: pass or review: needs-fix.'
```

The reviewer reports **P0** (must fix), **P1** (should fix), **P2** (consider)
findings and ends with `review: pass` (no P0/P1) or `review: needs-fix`
(P0/P1 present).

- **`review: needs-fix` with P0/P1 findings** → fix them yourself (you are the
 implementer in this lane), regenerate the diff, and re-run the reviewer.
- **Review errors on design grounds** → go back to Navigator to revise the
 design, then re-implement.
- Loop until `review: pass`. P2 findings stay open but do not block.
- **Don't pipe veda with `2>&1`**, the response goes to stdout, progress to
 stderr.

## Reminders

Onboard yourself with veda at `~/.pi/agent/docs/veda.md` before acting.
Key commands:
- `veda -S impl-TASKNAME sel add` to build context (quote globs: `"src/*.c"`)
- `veda -S impl-TASKNAME sel add file.c:10-50` to add line-range slices
- `veda -S impl-TASKNAME sel ls` to verify selection and token count
- `veda -S impl-TASKNAME -m flash -p navigator-plan` for initial planning (high reasoning)
- `veda -S impl-TASKNAME -m flash -p navigator-chat` for follow-up discussion (medium reasoning)
- `veda -S impl-TASKNAME -m flash resume` to continue a conversation (session-scoped)
- `veda -S impl-TASKNAME -m flash -p reviewer` for the closing review pass (P0/P1/P2, fix + re-review until `review: pass`)
- Output goes to stdout; use `-o file.md` to save response; don't pipe `2>&1`

## Red Flags

Letting the reviewer persona fix code (it has no tools); skipping the re-review after a fix; patching over a design-ground error instead of revising the design with Navigator; piping veda with `2>&1`.

## Verification

The diff is in selection (`sel ls` shows it); the reviewer ends with `review: pass` (no P0/P1 findings) against the session's `design.json`.


## References

No reference capsules, the skill is self-contained.