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"):

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:

# 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.

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.

# 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:

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

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:

# 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:

  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:

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.