Adding A Skill

Use this for public skill work in this repo. Keep ordinary skill changes in skills/<skill-name>/; keep repo-only guidance under .agents/skills/.

First Decide The Skill Kind

• Plain public skill: a normal folder under skills/<name>/ with SKILL.md. This is the common case. @agent-native/skills discovers these dynamically from BuilderIO/skills@main, so there is no framework registry to edit just to make npx @agent-native/skills@latest add --skill <name> work.
• Instruction-style skill: a plain skill that should optionally write an always-on managed AGENTS.md / CLAUDE.md line when users pass --update-instructions. These need one extra framework change; see "Managed Instruction Blocks" below.
• App-backed / MCP skill: a skill that registers a hosted/local MCP server or uses framework-owned install behavior. These are not plain public skills; inspect ../agent-native/framework/packages/core/src/cli/skills.ts and ../agent-native/framework/packages/skills/src/built-in-apps.ts.
• Plan skills: visual-plan and visual-recap have generated/synced copies between this repo and ../agent-native/framework. Do not treat them like a standalone prose folder.

Plain Public Skill Checklist

1. Create or update skills/<skill-name>/SKILL.md.

2. Add skills/<skill-name>/README.md when the skill should appear in the public catalog. This repo intentionally uses READMEs for public skill pages.

3. If the collection positioning changes, update root README.md, .codex-plugin/plugin.json, .claude-plugin/plugin.json, and package.json descriptions.

4. Keep the skill concise. Put only essential agent instructions in SKILL.md; avoid extra docs unless they directly support the skill.

5. Validate with:

   python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<skill-name>
   

6. Smoke-test install discovery locally before claiming the CLI path works:

   node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <skill-name> --client codex --scope project --dry-run --json
   

7. Run npm run check. If it fails on visual-plan / visual-recap sync while the change is unrelated, report that specifically instead of rewriting those skills casually.

@agent-native/skills Install Path

For a plain public skill, the install path is dynamic:

• ../agent-native/framework/packages/skills/src/index.ts sets DEFAULT_SKILLS_SOURCE = "BuilderIO/skills".

• It materializes that repo, reads plugin manifests via resolveSkillsRoot, and discovers every skills/*/SKILL.md through discoverSkills.

• Therefore a new folder under skills/<name>/ is enough for:

  npx @agent-native/skills@latest add --skill <name>
  

No @agent-native/core built-in registry change is needed unless the skill is app-backed or needs custom install behavior.

Managed Instruction Blocks

If the skill should affect AGENTS.md / CLAUDE.md through --update-instructions, update the framework wrapper:

• Add a concise line in ../agent-native/framework/packages/skills/src/index.ts inside instructionContentForSkill(skillName).

• Add or update tests in ../agent-native/framework/packages/skills/src/index.spec.ts.

• Run:

  pnpm --filter @agent-native/skills test -- src/index.spec.ts --runInBand
  

Use this for durable behavior rules like quick-recap, efficient-fable, stay-within-limits, and likely docs-first behavior such as read-the-damn-docs.

App-Backed Or MCP Skills

If a skill needs hosted tools, auth, MCP registration, local-files mode, or special install flags, inspect the framework before editing:

• ../agent-native/framework/packages/core/src/cli/skills.ts
• ../agent-native/framework/packages/skills/src/built-in-apps.ts
• ../agent-native/framework/packages/skills/src/sync-with-core.spec.ts

Keep the core and standalone @agent-native/skills MCP descriptors in sync.

Plan Skill Sync Gotchas

visual-plan and visual-recap are special:

• Framework contains canonical/generated copies and Plan marketplace bundles.
• This repo's npm run check compares those copies and can fail for drift unrelated to a new plain skill.
• When intentionally changing Plan skills, use the framework sync paths instead of hand-editing generated copies. Search the framework for sync-plan-marketplace, sync-workspace-skills, and skills.sync.spec.ts.

Final Reporting

When finishing a skill change, tell the user:

• Which skill files changed.
• Whether @agent-native/skills dynamic install discovery is enough.
• Whether a framework managed-instruction change was added or intentionally left as a follow-up.
• Which validation commands passed or failed, including unrelated Plan sync failures.

Agent Watchdog

Watch another agent's work like a reviewer with a pager: wait for completion when needed, reconstruct the request, verify the evidence, and close the gap between what was asked and what actually happened.

Choose The Mode

Infer the mode from the user's wording:

• Watch only: monitor a session, PR, branch, CI run, or transcript until it reaches a terminal state. Do not edit files.
• Audit: read the prompt, transcript, diff, tests, CI, comments, screenshots, or final claims and return a gap report. Do not edit files.
• Audit and fix: audit first, then make narrow fixes for clear gaps. Avoid broad rewrites, branch movement, or speculative changes.
• Compare: when given multiple sessions or agents, compare their work against the same original request and reconcile the important differences.

If authority is unclear, default to audit-only and say what you would fix.

Resolve The Target

1. Identify every artifact the user supplied: session ID, transcript path, thread URL, PR, branch, commit, CI run, issue, Slack link, or pasted summary.
2. Use the host's native thread/history tools, local transcript files, repo logs, GitHub tools, or pasted content to resolve the artifact. Prefer the most direct source over summaries.
3. If the artifact is still running and the user asked to watch, poll at a reasonable interval until it is done, blocked, stale, or clearly waiting on a human/external system.
4. If the artifact cannot be resolved, ask for the missing identifier or path.

Reconstruct The Contract

Build a compact contract before judging the work:

• Original user request and any later changes in scope.
• Explicit constraints: branch rules, no-edit requests, deadlines, package versions, validation expectations, design requirements, or security/privacy limits.
• Implied acceptance criteria: user-visible behavior, tests, CI, docs, deploys, screenshots, review replies, or status updates.
• The other agent's final claims and any "could not do" caveats.

Treat the user's request as the source of truth, not the other agent's summary.

Audit The Evidence

Inspect evidence, not vibes:

• Read changed files and relevant unchanged files around the touched paths.
• Check git status/diff without reverting unrelated work.
• Compare commands the agent claimed to run with actual output when available.
• Inspect failed or skipped tests, CI logs, browser screenshots, review comments, deploy output, and error traces.
• For PR/review work, verify unresolved threads and CI state from the source system when tools are available.
• For UI work, prefer screenshots or browser checks over prose claims.

Classify each issue as:

• Gap: requested behavior is missing or incomplete.
• Bug: the implementation likely fails or regresses behavior.
• Verification miss: the work may be right but the evidence is weak.
• Scope drift: the agent changed something unrelated or skipped a constraint.
• No issue: the concern is already handled, with evidence.

Fix Narrowly

When the user authorized repair:

1. Fix only gaps with clear evidence.
2. Preserve unrelated local changes and do not move branches unless explicitly asked for that branch operation.
3. Use existing repo patterns and targeted tests.
4. Re-run the smallest useful validation after each meaningful fix.
5. If a fix would require a product decision, credential, destructive action, or broad rewrite, stop and report the decision instead of guessing.

Report

Lead with the outcome. Keep the report short enough to scan:

Status
- Done, blocked, stale, or still running.

Requested
- What the user asked the watched agent to do.

Observed
- What the watched agent changed, claimed, and verified.

Gaps
- Missing behavior, bugs, weak verification, or scope drift.

Fixes made
- Files changed and validation run. Omit this section for audit-only work.

Remaining risk
- Anything still unverified or waiting on CI/review/deploy/human input.

Name exact files, commands, PRs, or thread IDs when they matter.

Efficient Fable

Use Claude Fable as the orchestrator, architect, synthesizer, and final judge. Use cheaper subagents for token-heavy research, coding, testing, and summarization that do not require Fable's full judgment.

Where Fable Shines

Reserve Fable for:

• Decomposing ambiguous work into clean parallel slices.
• Architecture, product, and safety tradeoffs.
• Reading conflicting subagent reports and deciding what matters.
• Integrating partial implementations into one coherent plan.
• Final review, risk assessment, and user-facing synthesis.

Delegation Pattern

1. Name the expensive-token risk: large repo search, long logs, broad docs, or repetitive edits.
2. Split independent work into subagents before reading everything yourself.
3. Use cheaper models for research scans, inventory, search summaries, narrow bug hunts, browser/testing passes, test output reduction, and bounded code edits.
4. Ask subagents for concise evidence: files, line references, commands run, diffs, uncertainties, and stop conditions they hit.
5. Spend Fable tokens on the decision layer: compare results, resolve conflicts, choose the implementation path, and review the final patch.

Prefer parallel subagents when the slices do not depend on each other. Keep blocking or highly coupled work local.

Handoff Packets

Write delegated prompts as if the subagent has no useful chat context. Include only the context it needs:

• The repo path and exact objective.
• The files, packages, or surfaces in scope and anything explicitly out of scope.
• The evidence format to return: files, line refs, commands, diffs, failures, screenshots, and uncertainty.
• The verification commands or browser flows to run, plus what success should look like when that is knowable.
• Stop conditions: if the code does not match the prompt, a command fails after a reasonable retry, or the task needs out-of-scope files, stop and report instead of improvising.

Vetting Delegated Work

Treat subagent reports as leads, not facts. Before using a high-impact finding, opening a PR, or telling the user the work is done, Fable should reopen the important cited files, confirm the relevant line refs or failures, and review the final diff against the task. Let lighter agents gather signal; keep truth-judgment with Fable.

Common Scenarios

Treat these as soft defaults, not rigid rules:

• Research: ask lighter agents to scan docs, prior art, APIs, and repo surfaces; Fable decides what evidence changes the plan.
• Coding: give cheaper agents bounded edits or candidate patches; Fable owns shared-file coordination, integration, and final review.
• Testing: have Fable suggest the validation direction and the scripts or browser checks that matter. Let lighter agents run targeted tests, browser flows, screenshots, and log reduction, then report exact commands, failures, likely causes, and whether failures look flaky, environmental, or real.
• Debugging: use cheaper agents to cluster logs, reproduce issues, and try small fixes; Fable decides which diagnosis is most trustworthy.

If a task is tiny or the validation itself needs delicate judgment, keep it with Fable.

Diagram

Use assets/fable-orchestrator.excalidraw when a visual explanation helps.

Claims

For codebase-heavy work, it is reasonable to describe this as up to 3-5x more cost-efficient and 2-4x faster when independent research, coding, or testing slices can run in parallel. Treat those as workload-dependent estimates, not guarantees.

Good launch copy:

Make Claude Fable more efficient by using cheaper subagents for token-heavy research, coding, and testing, saving Fable for judgment, architecture, synthesis, and final review.

Plan Arbiter

Turn competing plans into one executable direction. Preserve the best ideas, reject weak assumptions, and produce a clear handoff instead of a blended mush.

Workflow

1. Collect the source plans.
2. Normalize each plan into comparable claims.
3. Cross-review the plans against each other and the real codebase or task context.
4. Choose a winner, merge a better hybrid, or send the plans back for revision.
5. Produce one execution handoff with verification gates and rejected alternatives.

Planning is read-only unless the user explicitly asks you to implement after the decision.

Collect Source Plans

Accept plans as pasted text, local files, session IDs, transcript paths, PRs, comments, visual-plan links, or chat history. Resolve the original artifacts when possible so you can see prompt changes and assumptions that may be missing from a final summary.

If a plan is still being written and the user asked you to wait, monitor it until it is done or blocked. If a plan cannot be resolved, continue with the available plan text and mark the missing source as a risk.

Normalize

For each plan, extract:

• Objective and scope.
• Key assumptions and unresolved questions.
• Proposed files, modules, APIs, data shapes, UI states, or workflows.
• Implementation sequence.
• Validation strategy.
• Rollback or migration concerns.
• Cost, complexity, and expected executor fit.

Do not reward verbosity. Prefer plans that are concrete, grounded in real code, and honest about tradeoffs.

Cross-Review

Review each plan as if another capable agent wrote it:

• Check whether it satisfies the user's actual request.
• Verify claims against the repo, docs, tests, screenshots, or external systems when those are relevant and available.
• Identify hidden dependencies, missing tests, risky sequencing, vague steps, unnecessary scope, and hard-to-reverse decisions.
• Notice complementary strengths: one plan may have the better architecture while another has the better migration or validation path.
• Separate plan quality from executor preference. A cheaper/faster executor can be the right choice for implementation even when another model produced the best critique.

Use subagents for independent review when the plans are large, the codebase is wide, or the decision would benefit from separate technical and product passes.

Decide

Choose one of three outcomes:

• Adopt: pick one plan mostly as written.
• Hybrid: combine specific pieces into a stronger execution plan.
• Revise first: request another planning pass because both plans miss a key constraint or depend on an unresolved decision.

Use this tie-break order:

1. Correctness and fit to the user's request.
2. Grounding in real files, APIs, tests, data, and UI behavior.
3. Simpler first implementation that does not block the intended future.
4. Better validation and rollback story.
5. Lower token/time cost for execution once quality is acceptable.

Handoff

Return a compact decision memo:

Decision
- Adopt Plan A / Hybrid / Revise first.

Why
- The deciding evidence and tradeoffs.

Execution Plan
- Ordered steps with files or surfaces to touch.

Borrowed From Other Plans
- Useful pieces kept from non-winning plans.

Rejected
- Ideas intentionally not taking, with reasons.

Verification
- Tests, browser checks, screenshots, CI, review, or deploy checks needed.

Executor Recommendation
- Which agent/model should implement and why.

When the user already asked for execution and the chosen path is clear, proceed with the selected plan after reporting the decision briefly. Otherwise stop at the handoff and ask for approval.

Plow Ahead

Proceed through ordinary ambiguity. Make reasonable assumptions, keep momentum, validate as you go, and make the final recap strong enough that the user can see what decisions were made while they were away.

Autonomy Contract

Treat the user's instruction as permission to continue through normal uncertainty:

• Turn routine questions into explicit assumptions.
• Prefer the smallest reversible choice that satisfies the request.
• Use repo conventions, nearby patterns, local docs, tests, and existing product behavior as the decision source.
• Keep working through normal test failures, missing context, implementation choices, and minor ambiguity.
• Use subagents for independent research, implementation, or verification when parallel work can reduce idle time or improve coverage.
• Do not pause merely to ask which reasonable option the user prefers. Pick one, record why, and keep going.

Stop Conditions

Stop and ask only for true blockers:

• Required credentials, secrets, accounts, paid services, or private data are unavailable.
• The next step would be destructive, irreversible, or production-mutating.
• The task requires an explicit branch operation, history rewrite, force push, or deletion that the user did not directly request.
• Legal, safety, privacy, or security risk is high and cannot be reduced by a conservative local choice.
• The user explicitly reserved a decision for themselves.
• A verification failure repeats after reasonable investigation and the next fix would be speculative or broad.

If blocked, leave a self-contained handoff: what was done, what blocks progress, what exact input is needed, and the next command or file to inspect.

Decision Rules

When choosing without the user:

1. Reuse existing patterns before inventing new ones.
2. Prefer local, reversible, low-blast-radius changes.
3. Keep scope tight to the user's request.
4. Choose correctness and maintainability over cleverness.
5. Validate with the smallest meaningful test first, then broaden only when the risk justifies it.
6. If two options are close, choose the one that is easier for the user or a reviewer to understand later.

Maintain a lightweight decision log while working. It can live in notes, the plan, or your final answer, but do not create a new repo artifact unless the task needs one.

Work Loop

1. Restate the goal internally and identify likely acceptance criteria.
2. Inspect the real files, docs, issue, PR, screenshots, or runtime behavior before editing.
3. Make assumptions explicit, then act on them.
4. Implement in small coherent steps.
5. Run targeted validation and fix issues found by validation.
6. Repeat until the requested work is complete or a stop condition applies.
7. Before final response, review the diff and verification evidence against the original request.

Final Recap

End with a recap that makes autonomous decisions auditable:

Goal
- What you completed.

Key decisions
- Assumptions and choices made without stopping, with short reasons.

Changes
- Files, behavior, docs, or configuration changed.

Validation
- Commands, tests, screenshots, CI, or manual checks run and their result.

Remaining risk
- Anything not verified, deferred, or blocked.

Keep the recap factual. Do not hide uncertainty, skipped validation, or judgment calls.

Quick Recap

Make completion state obvious at the end of every response.

Status Block

Every response that completes a unit of work must end with:

🟢 Actual concise status sentence

Rules:

• Keep the status line under 100 characters.
• Use 🟢 when the requested work is finished.
• Use 🟡 when non-routine follow-up remains; name the pending item.
• Use 🔴 only when blocked on user input.
• Put the status line at the very end of the response.
• Do not add ---, spacer lines, or any content after the status line.

Installer Behavior

This convention is only automatic when it is present in project or user instructions. When installing this skill, prefer adding the managed AGENTS.md / CLAUDE.md block unless the user opts out.

If you are following the convention manually, choose the status from the user's perspective: finished, pending a specific non-routine step, or blocked.

Examples

Finished work:

🟢 Updated quick recap docs with output examples

Non-routine follow-up remains:

🟡 Code updated, set PROVIDER_WEBHOOK_SECRET before testing webhooks

Blocked on user input:

🔴 Need the production API key to continue

Stay Within Limits

Keep long-running agent work inside the current 5-hour and weekly usage windows. Check usage before launching substantial work and between waves of parallel subagents. If an active 5-hour or weekly limit is at or above 95%, pause new work until the window is clear enough to continue safely.

Core Loop

1. Run a bounded wave of work. Default to at most 3 parallel subagents unless the user or host gives a different throttle.
2. Wait for the wave to finish. Do not interrupt in-flight subagents just to save budget; that usually loses work.
3. Check current 5-hour and weekly usage with the host's usage/budget tool.
4. If either window is at or above 95%, stop launching work and schedule a self-contained resume when the relevant window should clear.
5. On resume, re-check the real window or block before continuing. Do not trust elapsed wall-clock time alone.

Usage Signals

Prefer a first-party host usage tool when available. In Claude Code, use:

npx -y ccusage@latest blocks --active --json

Use the JSON to identify the active block start, current cost or percentage, and time remaining. On wake, compare the active block start timestamp with the previous one; a new timestamp is stronger evidence than "enough time passed."

If the tool reports cost instead of a direct percentage, convert through the current account limit when known. For Claude Max-style 5-hour blocks, some users prefer an earlier caution threshold around $500-550; treat that as a user-configured guardrail, not a universal rule. The default stop rule is still 95% of the active 5-hour or weekly limit.

Pausing And Resuming

When a wake/resume tool is available, schedule a wakeup for:

min(3600, secondsUntilWindowClears)

If the runtime clamps wake delays to 60-3600 seconds, chain wakeups for longer waits. Each wakeup should re-check usage, reschedule if still over budget, and continue only when the window is safely below the threshold.

Make wake prompts self-contained. Include:

• The remaining plan.
• The check-then-reschedule rule.
• The 95% threshold and wave throttle.
• The exact usage command or host usage tool to run.
• The previous block/window identifier when available.
• The next verification steps.
• The next wave's handoff packets, including scope, verification commands, and stop conditions, if delegation will resume.

Choosing The Wait Mechanism

• Use a wake/resume tool when the agent needs instructions attached to the future resume.
• Use a background sleep or watcher for fixed timers and things a process can observe directly.
• Use cron or recurring schedules only for recurring fresh-session work.

Avoid short-interval polling for things the host will notify you about, such as background task or subagent completion. For budget pauses, a prompt-cache miss after a long sleep is acceptable; preserving the limit matters more.

Reporting

If you pause, tell the user which window is over threshold, the observed usage, when you scheduled or expect the next check, and what work remains. Keep enough state in the wake prompt that the next turn can resume without relying on conversation momentum.

Agent-Native Plans

Agent-Native Plans is structured visual planning mode for coding agents. Build the plan you would normally write in Markdown, but as a scannable document with editable blocks mixed in: inline diagrams, code snippets, open questions, and an optional top visual review area (wireframe canvas, live prototype, or both in tabs). Architecture and backend plans stay document-only; UI and product plans start with the top canvas/prototype (the Visual Surface Choice section owns that rule).

/visual-plan is the packaged command and main entry point. Choose the review mode from the task: UI-first when the work is primarily product UI and review should start with screens, prototype-first when review should start with a functional live prototype, design-first when review needs full-fidelity branded screens, or visual-intake when the user explicitly wants a questionnaire before planning. When a Codex, Claude Code, Markdown, or pasted plan already exists, /visual-plan uses that source plan as the starting point and builds the review surface from it instead of starting over.

When To Use

Create or adapt a visual plan whenever the plan would be better as a reviewable artifact than a chat paragraph. This includes modest work such as a single UI surface with states, a small workflow, a before/after product change, or a component/API/data-shape decision that needs alignment, plus larger multi-file, ambiguous, long-running, risky, or UI-heavy work. Use it when architecture / data flow / UI direction / options / open questions would benefit from inline diagrams or structured blocks, when the user needs to react to a direction before you implement, or when an existing text plan needs a richer review surface.

Plan Discipline

• Gate thoughtfully. A visual plan is a richer review surface, not only a tool for giant projects. Use it when the user needs to see, compare, comment on, or approve a direction before code, even for a modest UI/state/workflow change. Skip it for truly trivial, unambiguous work — typos, one-line fixes, a single well-specified function, anything whose diff you could describe in one sentence — and just make the change. Never pad a plan with filler and never ship a single-step plan.
• Research before you draft. Read the real files, actions, schema, and patterns first; name actual files, symbols, and data shapes instead of inventing them. Check existing actions/ before proposing endpoints and prefer named client helpers over raw fetch. Delegate wide exploration to a sub-agent. Lead with reuse: for each step, name what it reuses — existing actions, schema, components, helpers — before what it adds, so the plan explains the genuinely new delta instead of redescribing what already exists.
• Decide the hard-to-reverse bets first. For non-trivial backend, data, or API work, sketch where the feature is headed, then call out the decisions that are expensive to undo once data or callers depend on them — wire format, public ids, data-model shape, auth and ownership boundaries — and get those right in the plan even if most of the feature ships later. Then scope to the smallest first cut that proves the approach without foreclosing it, stating both what is in and what is explicitly deferred.
• Keep examples at the right altitude. When the user's idea is a broad framework, product, or operating-model change, do not collapse it into the first concrete example, provider, or sync path they mention. Separate the core abstraction from motivating examples and app/provider adapters. Use examples to make the plan legible, but label them as examples unless they are the whole requested scope.
• Publish standalone plans. If the user pasted, referenced, or already has a Codex / Claude Code / Markdown plan, treat it as source material, but rewrite the published plan as a clean standalone proposal. Preserve the source plan's useful intent and codebase facts, label inferred visuals as inferred, and avoid revision language such as "preserve the prior plan", "do not drop the old idea", "unlike the previous version", or "this revision changes...". A reader who never saw the chat or earlier drafts should understand the plan.
• Make the first read concrete. If the plan is meant to be shared with someone outside the chat, or if the concept is abstract, lead near the top with one concrete product example before mode tables, architecture, or roadmaps. For UI-capable concepts, that usually means a top-canvas app state that shows the real user workflow in product terms. Do not rely on phrases that only make sense in conversation, and do not frame the plan as "not the old idea"; state the positive model directly.
• Planning is read-only. Make no source edits while building or reviewing the plan. Start editing only after the user approves the direction.
• Clarify vs. assume. Do not ask how to build it — explore and present the approach and options in the plan. Ask a clarifying question only when an ambiguity would change the design and you cannot resolve it from the code; use the host agent's normal ask-user-question flow and batch 2-4 high-leverage questions before finalizing. Do not call create-visual-questions for ordinary clarification or preflight; reserve it for the visual-intake mode when the user explicitly asks for a visual intake questionnaire. Otherwise state the assumption explicitly and proceed, and keep anything unresolved in the plan's single bottom question-form Open Questions block. For complex plans, do a final open-question pass before handoff: if a decision would affect architecture, scope, UX, data shape, or rollout, either decide it in the plan with rationale or put it in that bottom form with a recommended default.
• The plan is the approval gate. After surfacing it, ask the user to review and approve before you write code, and name which files/areas the work touches. Presenting the plan and requesting sign-off is the approval step — do not ask a separate "does this look good?" question.
• The document is the source of truth, not the chat. When scope shifts, update the plan with update-visual-plan rather than only changing course in chat, and make the updated document stand alone. Do not describe the update as a correction to an earlier draft inside the plan itself. Re-read the approved plan before major steps.

Create A Structured Agent-Native Plan — Never Inline

The deliverable is ALWAYS a structured Agent-Native Plan, not a chat-only plan. The hosted Plan MCP connector (plan server, or legacy agent-native-plans) is the default collaboration and commenting surface; it is not a reason to reject the planning pattern as an external dependency or rented layer. Plans are portable source artifacts (plan.mdx, optional canvas.mdx / prototype.mdx, JSON, and HTML export), and ownership-sensitive workflows can use local-files mode or a self-hosted/custom Plan app URL without abandoning the skill's review discipline. Do not advise the user to skip /visual-plan because the default surface is hosted; choose the right Plan mode for the user's ownership, privacy, sharing, and branding needs.

By default, create the plan via the Plan MCP connector and NEVER hand it over as inline chat content — no Markdown prose, ASCII sketch, table, or fenced wireframe. If the plan (or legacy agent-native-plans) tools are not visible, discover them through the host's tool_search first; if they are still missing, STOP and give the user the client-specific reconnect step rather than improvising an inline plan. Before publishing, or whenever a connector or auth error appears, READ references/connection.md in this skill directory — it is the single source of truth for the never-inline rule, connector discovery, and the per-client reconnect steps. Local-files privacy mode (after Tool Guidance) is the exception.

Core Workflow

This section describes the default hosted Plan MCP workflow. If AGENT_NATIVE_PLANS_MODE=local-files is set, or the user asks for fully local files/no hosted Plan writes, use Local-Files Privacy Mode instead; carry forward only the code-research and plan-composition guidance here.

1. Follow the host agent's normal planning flow: inspect the codebase, delegate wide exploration when useful, gather the info needed, and ask native clarifying questions as needed before generating the plan. If a source plan already exists, gather its exact text from the user's paste, a referenced file, or recent visible agent context; do not invent source text.
2. Call get-plan-blocks for the authoritative block catalog — do not author from memorized tags. Then call the mode-matched create tool: create-visual-plan for document-first plans (architecture, backend, data, refactor, API), create-ui-plan for UI-first plans, create-prototype-plan for prototype-first plans, create-plan-design for design-first plans, create-visual-questions only when the user explicitly asks for a visual intake questionnaire. When a source plan already exists, pass it as planText and preserve the original plan's useful intent while producing a standalone plan document, not a revision memo.
3. For UI/product plans, compose the top canvas first with the primary wireframes and annotated states, then write the document with native blocks (see references/canvas.md and references/document-quality.md). For broad product architecture plans with a user-facing implication, add a concrete "what this looks like in the app" visual before the abstract architecture or mode tables. Keep the document close to the standalone Markdown plan the agent would normally output. If an existing plan was provided, carry forward the right facts and decisions without referring to the previous draft or explaining how this version differs. For non-visual plans, skip the top visual surface (Visual Surface Choice below owns the rule) and put diagram, data-model, api-endpoint, diff, file-tree, code, and annotated-code blocks directly next to the relevant prose. Wide document layout is renderer-owned and intentionally allowlisted: only literal code-review surfaces (diff, annotated-code) and tabs blocks with vertical orientation or diff-like children break out wider than prose. Keep api-endpoint, openapi-spec, data-model, json-explorer, wireframe, question, and custom-html blocks in normal document flow unless their own renderer says otherwise.
4. Surface the returned Plans link or inline MCP App and ask the user to review. Always include the actual URL in chat so the next step is a click in CLI or other text-only hosts. When the host exposes an embedded browser/preview panel and a tool can open arbitrary URLs there, open the returned plan URL automatically for convenient review — a convenience and smoke test, never the only handoff or the access model. Plans should load out of the box for the local agent and local browser session; if a signed-in embedded browser cannot read a local plan that an anonymous/tool check can read, fix the app/action ownership or access path rather than patching one plan by hand. For high-stakes plans (architecture, backend, data, multi-file, or risky), also kick off the self-review pass in Self-Review Before Handoff while the user reads, instead of blocking the handoff on it.
5. For hosted plans, call get-plan-feedback before editing, after review, after any long pause, and before the final response. Treat anchorDetails, resolver intent, recent review events, and any focused screenshots from browser handoff as the source of truth for exactly what changed and exactly what each comment points at.
6. For hosted plans, apply changes with update-visual-plan, preferring targeted contentPatches. Treat the top-level content payload as a full replacement, not a merge; do not send a partial content object to add a canvas or one block. If a full replacement is unavoidable, first read the complete plan source/content, carry forward every existing block and visual surface, and verify the source/export afterward so the document body was not truncated. When the user wants source-control friendly edits, use patch-visual-plan-source against the MDX files instead of regenerating the plan.
7. For hosted plans, export with export-visual-plan only when the user wants a shareable receipt or repo-check-in artifacts.

Self-Review Before Handoff

For high-stakes plans — architecture, backend, data-model, migration, multi-file, or otherwise risky work — run one adversarial self-review pass before treating the plan as final. Skip it for small, UI-only, or single-decision plans where the cost outweighs the value. Keep the pass cheap and non-blocking:

• Surface the plan first, review concurrently. Post the link and let the user start reading, then run the review in parallel — never make the user wait on it.
• Review the written plan; do not re-research. Critique the plan text and its own blocks. The grounding was already done while drafting, so the review checks the output instead of re-exploring the repo.
• Spawn one skeptical reviewer whose only job is to find what is weak, missing, or wrong — not to praise. Point it at: hard-to-reverse decisions made implicitly or not at all (wire format, public ids, data-model shape, auth, ownership); steps not anchored in real files or symbols; a menu of options where the plan should commit to one; obvious missing decisions ("what happens when X?", "why not Y?"); and padding or single-step filler.
• Fix vs. ask. Apply clear-cut fixes yourself with update-visual-plan contentPatches — vague non-goals, unanchored claims, an obvious missing decision. Route genuine judgment calls back to the user instead: add them to the bottom question-form Open Questions block or batch them into the normal ask-user-question flow. Do not silently decide them.
• Do not surprise the user mid-read. On a large plan, apply the patches before the editor loads; otherwise note briefly that a self-review is running so the plan changing under them is expected. When you next respond, summarize what the review changed and what it surfaced for the user to decide.

Visual Surface Choice

Choose the surface before creating the plan or after reading the source plan. Do not add visual chrome by default:

For UI/product plans, the top canvas is usually the primary review surface. Put the first meaningful wireframes there, not buried as document-body blocks. Use multiple canvas artboards when states matter, such as the default view, an overflow menu or popover, a side panel, loading, or error. Put short annotations beside frames with targetId plus placement; keep implementation details, tradeoffs, file maps, data contracts, risks, and verification in the document body below the canvas.

When the user asks for a flow, storyboard, journey, wireframe, canvas, or "what this looks like", treat that as a canvas-first request. Make one artboard per user-visible state, connect only adjacent transitions, and use short canvas annotations for the product notes. Do not substitute a document-body diagram block for the requested storyboard just because HTML diagrams are faster to write; diagrams belong below the canvas for backend mechanics, architecture, or data-flow explanation.

Keep product wireframes and explanatory/meta diagrams separate. Start with pure screens that look like the app state under discussion, without callout prose or architecture notes embedded inside the UI. Put arrows, labels, contracts, data flow, and mode explanations in separate annotations, separate canvas diagrams, or the document body.

When the plan touches an existing app, inspect the current shell/components before drawing. The first artboard should look like the real app at the same density: existing sidebars, toolbar placement, overflow menus, app chrome, and framework agent chrome stay in their real places. Model secondary surfaces as separate states, such as a top-right overflow popover, sheet, panel, loading state, or separate AgentSidebar, rather than inventing a permanent inspector or folding framework chrome into the product UI.

• No visual surface for architecture-only, backend-only, data migration, copy-only, or otherwise non-visual plans. Do not use the top canvas for architecture diagrams, dependency maps, file plans, API contracts, or data-flow-only reviews. Use a strong document with local inline diagrams only when relationships need a visual explanation, usually one spatial diagram per recommendation or decision. Prefer grouped regions, layers, quadrants, matrices, or before/after panels over a single-axis chain unless the relationship is truly sequential.
• Canvas only for one static screen, a before/after comparison, a component state, a small popover, or a visual direction that does not require clicking. Put those wireframes in content.canvas and omit content.prototype.
• Canvas + prototype for multi-step UI flows, onboarding, wizards, review/approval flows, navigation changes, or anything where the reviewer needs to operate the behavior. Keep the static wireframes in content.canvas, add the aligned functional prototype in content.prototype, and rely on the top visual tabs to switch between them.
• Prototype-first when the user asks to operate the UI or when interaction is the main question. Use create-prototype-plan, which still preserves static mocks where useful.

For mixed canvas + prototype plans, reuse the same real labels, app statuses, and screen ids across both surfaces. The canvas is the inspectable static reference; the prototype is the interactive version of that same flow, not a separate design direction.

Wireframe quality — read references/wireframe.md

UI recap/plan wireframes must meet a strict quality bar — full-width chrome, pinned bottom bars, real product content, before/after comparability, the right surface preset, --wf-* tokens instead of hex, and no <html>/<style>/font tags. Before authoring ANY wireframe / <Screen> / WireframeBlock, READ references/wireframe.md in this skill directory — it is the single source of truth for HTML wireframe quality, shared word for word with /visual-plan and /visual-recap. Do not author wireframes from memory.

Canvas — read references/canvas.md

The canvas is the single source of truth for static UI mockups: the surface locks each artboard's footprint, mixed surfaces lay out in lanes, annotations are plain-text designer notes anchored by targetId/placement, and edits are surgical contentPatches. Before authoring or editing ANY canvas, artboard, or annotation, READ references/canvas.md in this skill directory — it is the single source of truth for canvas/artboard mechanics. Do not author canvas layouts from memory. Canvas artboards use the same HTML wireframe path as document-body WireframeBlock screens: author <Screen surface="..." html={...} /> with a semantic HTML fragment. Do not author fresh kit-tree children such as <FrameScreen>, <Card>, <Row>, or <Btn> inside canvas <Screen> tags; those are legacy compatibility markup for old plans and produce brittle canvas layouts.

Document quality — read references/document-quality.md

The document is a serious technical plan, not marketing: outcome-first, prose-first, self-contained, built from the right native blocks, with open questions in a single bottom question-form and a pre-handoff visual check. Before authoring the plan document, READ references/document-quality.md in this skill directory — it is the single source of truth for the document quality bar. Do not write the document from memory.

Good vs. bad exemplar — read references/exemplar.md

For a worked example of the bar — a great UI-first plan and /visual-plan, plus the anti-patterns to avoid — READ references/exemplar.md in this skill directory before authoring a plan.

Tool Guidance

• create-visual-plan: start one structured visual plan per agent task/run, or import an existing text plan by passing planText; content may include no visual surface, canvas only, or canvas + prototype.
• create-ui-plan: start a UI-first plan when the work is primarily product UI.
• create-prototype-plan: start a prototype-first plan with a functional top review surface.
• create-plan-design: start a full-fidelity branded Design-tab plan with an optional matching Prototype tab.
• convert-visual-plan-to-prototype: convert an existing HTML wireframe canvas into a prototype plan.
• create-visual-questions: use only when the user explicitly asks for a visual intake questionnaire, not as /visual-plan preflight.
• update-visual-plan: revise content, status, or comments with targeted contentPatches (see Core Workflow step 6).
• read-visual-plan-source: read the normalized plan as plan.mdx, optional canvas.mdx, optional .plan-state.json, and JSON.
• patch-visual-plan-source: apply granular MDX AST patches by stable block, artboard, annotation, component, or wireframe-node id.
• import-visual-plan-source: create or replace a plan from an MDX folder.
• get-visual-plan: read the current structured plan, exported HTML, and annotations; it also returns the MDX folder for source workflows.
• get-plan-feedback: read unconsumed human feedback. Use it frequently; it returns grouped threads, exact anchor details, expected resolver, and recent review-event payloads so agents can act only on the comments meant for them.
• get-plan-blocks: resolve block tags before authoring — do not memorize tags; call this first to get the authoritative tag names, required fields, and prop shapes from the live block registry.
• export-visual-plan: export HTML, Markdown fallback, structured JSON, and MDX files for repo check-in.

When the user critiques a plan's look or structure, fix the renderer or this skill — never hand-edit one stored plan. Turn feedback into better guidance.

Local-Files Privacy Mode — read references/local-files.md

When the user wants no hosted Plan database writes — no DB writes, no Plan MCP publish, fully local/offline/private planning, repo-owned source-controlled artifacts, or AGENT_NATIVE_PLANS_MODE=local-files — do not call any hosted Plan tool except the schema-only get-plan-blocks catalog lookup. Author a local MDX folder and preview it with plan local check / plan local serve / plan local verify. Before using local-files mode, READ references/local-files.md in this skill directory — it is the single source of truth for the full contract (catalog lookup, MDX folder layout, the local bridge commands, and the hosted tools you must not call). Carry forward only the code-research and plan-composition guidance from Core Workflow; everything hosted is replaced by the local bridge.

Interpreting comment anchors

This section applies to hosted plans with get-plan-feedback / update-visual-plan. In local-files mode, do not call hosted feedback or update tools; interpret file/chat feedback directly, edit the MDX files, rerun the local bridge check/serve/verify command, and report the new local URL.

get-plan-feedback returns rich anchors — read them before acting on any comment.

• Coordinate frames. targetX/targetY are percentages within the element named by targetSelector/targetKind. Bare x/y are percentages of the whole plan document. canvasX/canvasY are raw board-world pixels on the design canvas (board size given when available).
• Wireframe pins. Anchors on wireframes include targetNodeId and targetNodePath (e.g. card > list > listItem "Acme Inc") identifying the exact kit node. Use targetNodeId directly with wireframe node patch ops; use data-design-id values from design artboards with update-design-element-style. Prefer the node id/path over raw coordinates; fall back to coordinates plus the focused screenshot (red ring marks the exact point) only when no node id is present.
• Text quotes. Resolve textQuote against current prose using contextBefore/contextAfter for disambiguation. If ambiguous: true, ask the user — do not guess which occurrence is meant.
• Detached comments. get-plan-feedback flags threads whose quoted text no longer exists as detached (in detachedThreads). Reconcile these against rewritten content — never silently drop them.
• Routing. resolutionTarget is the only routing signal: act on agent, treat human as context only. @mentions are people to notify, never a routing signal.
• Two-axis state. Mark every ingested comment as consumed (consumedCommentIds on update-visual-plan). Set status=resolved only on agent-targeted comments you actually addressed; leave human-targeted comments open.

Visibility & Sharing

Use set-resource-visibility to change who can see a plan (e.g. public, login, or org-scoped). Use share-resource to grant specific users or roles access by email or role. Gate visibility before sharing any plan that covers unreleased or private work — default to the narrowest scope that meets the review need.

Setup & Authentication

There are two ways into Plans.

Coding agent (CLI). Install once with the Agent-Native CLI. The command installs the Plans skills, registers the hosted Plans MCP connector, and runs auth/setup for the selected local client(s) in the same step (a one-time browser sign-in at setup — this is intended), so the first tool call in that client does not hit an OAuth wall:

npx @agent-native/core@latest skills add visual-plans

After that, /visual-plan, /visual-recap, and /visualize-repo are the installed slash commands. If you only need one command, use skills add visual-plan, skills add visual-recap, or skills add visualize-repo instead. The other planning modes (create-ui-plan, create-prototype-plan, create-plan-design, create-visual-questions) are MCP tools reachable from /visual-plan, not separate slash commands. Pass --no-connect to register the connector without authenticating, then run npx @agent-native/core@latest connect https://plan.agent-native.com --client all whenever you are ready, or choose a narrower --client. Auth and MCP tool loading are per client config/session.

Browser (people you share with). Open the Plans editor and create & edit with no sign-up — you work as a guest. Sign in only when you want to save or share; signing in claims the plans you made as a guest into your account.

Sharing and commenting require an account: public/shared plans are viewable by anyone with the link, but commenting on them needs an agent-native account.

For fully offline, no-account use, run the Plans app locally and sync plans to your repo as MDX. This local mode is a separate advanced path, not the default hosted flow.

For repo-wide visual docs, run npx @agent-native/core@latest visualize-repo --open to create/update agent-native.json, seed .agent-native/visual-docs/repo-overview, and open the local bridge.

If a Plans tool returns needs auth, Unauthorized, or Session terminated, do not keep retrying it — stop and give the user the per-client reconnect step from references/connection.md, then continue once the connector is available.

Hosted default: connect https://plan.agent-native.com/_agent-native/mcp. Do not put shared secrets in skill files.

Visual Recap

/visual-recap creates a visual plan built from a diff, not toward one. It is the reverse of forward planning: instead of describing the change you are about to make, you describe the change that was just made, at a higher altitude than line-by-line review. The same plan data model serves both directions — schema, API, file, and architecture changes become the same data-model, api-endpoint, file-tree, and diagram blocks a forward plan would use, only now they summarize work that exists. A reviewer scans the shape of the change before spending attention on the literal lines.

Publish As An Agent-Native Plan — Never Inline

The deliverable is ALWAYS a published Agent-Native Plan, created with create-visual-recap on the Plan MCP connector — NEVER inline chat content (not Markdown prose, an ASCII sketch, a table, a fenced "wireframe", or a "here's the recap" summary). A recap's entire value is the hosted, interactive, annotatable plan; an inline summary is not a degraded recap, it is the thing a recap replaces. If the plan (or legacy agent-native-plans) tools are not visible, discover them through the host's tool_search first; if they are still missing, STOP and give the user the client-specific reconnect step rather than improvising an inline recap. Before publishing, or whenever a connector or auth error appears, READ references/connection.md in this skill directory — it is the single source of truth for the never-inline rule, connector discovery, and the per-client reconnect steps. Local-files privacy mode (below) is the one exception.

Local-Files Privacy Mode — read references/local-files.md

When the user wants no hosted Plan database writes — no DB writes, no Plan MCP publish, fully local/offline/private recaps, or AGENT_NATIVE_PLANS_MODE=local-files — do not call any hosted Plan tool except the schema-only get-plan-blocks catalog lookup. Read the diff with the local recap collect-diff / scan / build-prompt --local-files helpers, author a local MDX folder (set kind: "recap" and localOnly: true), and preview it with plan local check, plan local serve --kind recap, and plan local verify --kind recap. Before using local-files mode, READ references/local-files.md in this skill directory — it is the single source of truth for the full contract.

When To Use

Build a recap when a PR or commit is large, multi-file, or touches schema, API contracts, or architecture, and a reviewer would benefit from seeing the change mapped to structured blocks before reading the raw diff. A GitHub Action can generate one automatically from a PR diff; an agent can generate one on request ("recap this PR", "show me what this branch changed"). Skip it for small, single-file, or obvious diffs — a recap is review overhead, and a tiny change reviews faster as plain diff.

Recap The Whole Work Unit

When /visual-recap is invoked in a chat thread after work has already happened, the default scope is the whole current work unit/thread, not only the most recent user message, tool action, or follow-up fix. Gather the thread-owned changes across the conversation: original implementation work, later bug fixes, UI follow-ups, tests, changesets, skill/instruction updates, generated plan/source artifacts, and any local import/linking fixes needed to make the recap open.

Use the current diff plus conversation context to separate thread-owned changes from unrelated dirty work that existed before the thread. Exclude unrelated pre-existing edits. If the scope is genuinely ambiguous and cannot be inferred, state the assumption or ask a concise question before publishing.

When updating an existing recap after feedback, revise the recap so it still covers the whole thread/work unit plus the new correction. Do not replace a broad recap with a narrow recap of only the latest feedback unless the user explicitly asks for that narrower scope.

Keep The Recap Body Lean

Do not add boilerplate intro, disclaimer, provenance, or summary prose blocks to the generated plan body. In particular, do not create a rich-text block just to say the recap is an aid, that the reviewer should still review the diff, how many files changed, or which ref/working tree generated the recap. The plan title, brief, and file-tree (which carries the per-file change stats) already carry that context.

Only add prose blocks when they tell the reviewer something specific about the change that the structured blocks do not: the objective, a real compatibility risk, an important decision visible in the diff, or a grounded review note.

Recaps Must Be Substantial

Lean is not the same as thin. A recap is not a single wireframe plus one sentence — that under-serves the reviewer as much as boilerplate prose over-serves them. Alongside the visual/structural headline (wireframes, data-model, api-endpoint, diagram), a substantial recap also carries the implementation evidence:

• A short surface/state inventory before authoring: list the changed routes, components, popovers/dialogs, role/access states, empty/error states, and shared abstractions visible in the diff. The final recap must either represent each meaningful item with a block or intentionally omit it because it is tiny, redundant, or not user-visible.
• A file-tree of the changed files with each entry's change flag, so the reviewer sees the footprint of the work at a glance.
• The split diff of the KEY changed files, grouped under a ## Key changes rich-text heading in a single horizontal tabs block (the default orientation, one file per tab), with a one-line summary and a few annotations on each — so the reviewer can drop from the high-altitude shape straight into the load-bearing code. Use horizontal file tabs, not a vertical side rail, so the selected file has enough width for the side-by-side diff.

Skip the diff appendix only for a genuinely tiny change that reviews faster as plain diff (see "When To Use"); for any change worth recapping, the file-tree and key-change diffs belong in the plan.

Canonical Shape And Budgets

A strong recap follows one skeleton, top to bottom:

1. UI-impact headline — wireframes first, when the diff changed rendered UI.
2. Short outcome narrative (rich-text): what changed and why, 1-3 paragraphs.
3. data-model / api-endpoint blocks for schema and contract changes.
4. file-tree of the changed files with change flags.
5. ## Key changes — one horizontal tabs block of diff / annotated-code.

Budgets that keep the recap reviewable:

• 3-8 key-change tabs. Fewer than 3 on a large change under-serves the reviewer; more than 8 stops being a summary.
• Keep each diff/annotated-code excerpt focused — prefer under ~150 lines per tab; summarize or link the rest of a long file instead of dumping it.
• Title at most ~70 characters; brief 1-3 sentences.

GOOD. A 25-file auth change: Before/After wireframes of the login surface, a two-paragraph narrative, a diff-aware data-model of the sessions table, an api-endpoint for the new refresh route, a file-tree with change flags, and ## Key changes with five focused tabs, each with a one-line summary and a few annotations on the load-bearing hunks.

BAD. One giant unsegmented diff dump with no summaries or annotations; or a sparse three-block recap of a 40-file change (one wireframe, one sentence, one file list) that forces the reviewer back into the raw diff anyway.

UI Impact Needs Wireframes

When the diff changes rendered UI, layout, density, visual state, interaction affordances, navigation, controls, menus, dialogs, or design tokens, the recap MUST include one or more wireframes. Prose and file diffs are not a substitute for showing what changed visually.

Before choosing wireframes, make a UI coverage pass from the diff:

• Identify the entry surface where the change appears, such as a page header, list row, toolbar, route shell, or menu trigger.
• Identify the interaction surface that opens or changes, such as a popover, dialog, tab, sheet, dropdown, inline editor, or toast.
• Identify the resulting destination or persistent state, such as a public page, read-only view, empty state, error state, loading state, permission-denied state, or saved/shared state.
• Identify access or role variants when permissions change. Owner/admin/editor versus viewer/non-manager differences are visual behavior and need a compact matrix, paired wireframes, or clearly labeled state sequence.

For UI-heavy PRs, a single before/after of the entry surface is not enough. Show the changed entry point, the main changed interaction surface, and the resulting/destination state. Add more states when the diff adds tabs, role-based controls, public/private visibility, invite/manage flows, destructive controls, or empty/error branches.

Choose the smallest visual surface that makes the review clear:

• Use a Before / After wireframe pair when the reviewer benefits from direct comparison, such as a removed or added control, a changed state, layout density, ordering, navigation, or a visible component replacement. references/wireframe.md owns how to lay that pair out (columns vs. vertical stack by geometry).
• Use an after-only wireframe when the change is purely additive or the "before" state would only show absence without adding review value.
• Use more than two wireframes when the UI change is flow-dependent, responsive, or stateful; show the meaningful states in order instead of forcing a single before/after pair.
• For tiny surfaces like menus, popovers, dialogs, toasts, or panels, use the matching surface (popover, panel, etc.) and show the focused sub-surface. Do not redraw a full page unless placement in the page is itself part of the change.

Ground each wireframe in the changed UI behavior, component names, file paths, and diff-visible labels/states. If exact pixels are inferred rather than captured, say so in the wireframe caption or a concise annotation. For local/manual recaps, import or update the plan source that holds the wireframes so the rendered recap opens with the UI visual available.

Wireframe Quality — read references/wireframe.md

UI recap/plan wireframes must meet a strict quality bar — full-width chrome, pinned bottom bars, real product content, before/after comparability, the right surface preset, --wf-* tokens instead of hex, and no <html>/<style>/font tags. Before authoring ANY wireframe / <Screen> / WireframeBlock, READ references/wireframe.md in this skill directory — it is the single source of truth for HTML wireframe quality, shared word for word with /visual-plan and /visual-recap. Do not author wireframes from memory.

Use the standard WireframeBlock / <Screen> format so the Plan viewer owns the surface frame, theme, and sketchy/clean toggle. HTML wireframes are appropriate when placement precision matters, especially popovers, menus, dialogs, and dense forms. For HTML wireframes, keep renderMode unset or wireframe unless a design-only editable mockup is explicitly required, because renderMode="design" disables the sketchy rough overlay.

When a browser tool is available, render a UI-impact recap in the Plan viewer and visually inspect it at the current theme before sharing. If any label, annotation, toolbar, or wireframe content overlaps another element, fix the MDX and re-import before reporting the link. A text-match screenshot is not enough; visually inspect the captured image. When no browser is available (for example a headless CI agent), state that in the recap handoff instead.

Top Canvas Recaps — read ../visual-plan/references/canvas.md

When a recap includes a top canvas, storyboard, or flow view, READ ../visual-plan/references/canvas.md before authoring canvas.mdx. Recap canvas artboards must use the same HTML wireframe path as good document-body wireframes: <Screen surface="..." html={...} /> with a semantic HTML fragment. Do not author fresh kit-tree children such as <FrameScreen>, <Card>, <Row>, <Title>, or <Btn> inside canvas <Screen> tags. Those components are legacy compatibility markup for old plans; in new canvas storyboards they can produce cramped or overlapping layouts even when the inline body wireframe looks good. If a canvas mockup looks worse than the same screen below the fold, assume it used the legacy kit path and replace it with an HTML screen.

Open And Report The Recap

In local-files privacy mode, run plan local check first, then report the local bridge URL from npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open or from <plan-dir>/.plan-url. It opens the hosted Plan UI but reads from the localhost bridge on this machine, so it is not shareable across machines. If the Plan app itself is running locally with the same PLAN_LOCAL_DIR, the /local-plans/<slug> route is also valid. Do not invent a hosted database URL and do not publish just to get an absolute Plan link.

After creating the recap, link the reviewer to the rendered plan with an absolute URL on the origin whose database actually holds the plan. That origin is the Plan MCP server you just created the recap through — NOT whatever dev server you happen to know is running. The create tool returns the correct link; report THAT. Never make the primary link a local plan.mdx file, a local mirror folder, or a relative path such as /plans/<id>.

When the recap is posted to a PR for a private repo, the plan link is not a public URL. Make the PR comment/handoff copy explicit: reviewers may need to sign in to Agent-Native Plans with an account that has access to the owning organization before the link loads. Use wording like: "Private repo recap: sign in with access to this org if the plan does not open." Do not imply the link is broken or public when access is gated by repo/org visibility.

A recap lives only in the database of the MCP that created it. A separately running local dev server (e.g. http://localhost:8081) has its OWN database and will NOT contain a recap created through the hosted MCP, so a hand-built localhost link returns "Plan not found". This is the most common recap mistake — do not guess an origin you have not confirmed shares the MCP's data.

Resolve the URL in this order:

1. Use the absolute URL the create tool RETURNS — openLink.webUrl, else the visualUrl in the returned plan.mdx frontmatter, else url/path resolved against the MCP server's own origin (for the hosted MCP that is https://plan.agent-native.com). This always points at the database that has the plan.
2. Use a localhost/dev origin ONLY when the recap was created through a Plan MCP bound to that same origin — i.e. that MCP's url is http://localhost:<port>/_agent-native/mcp. Creating through the hosted MCP and linking to localhost is the exact mismatch that 404s.
3. If only a plan id is available, build the MCP origin's absolute URL (hosted: https://plan.agent-native.com/plans/<id>) and say it was inferred.

If the user wants to review on localhost but the recap was created through the hosted MCP, say so plainly: the local dev server cannot see it. To view a recap on localhost (e.g. to exercise un-deployed local renderer changes), they must connect a LOCAL Plan MCP (http://localhost:<port>/_agent-native/mcp) and re-create the recap through it so it lands in the local database; offer to do that rather than handing over a localhost URL that will not resolve.

When running in Codex and the Browser/in-app side browser tools are available, open the returned absolute recap URL there automatically after creation. Still include the same absolute URL in the final response. Local mirror files like plans/<slug>/plan.mdx may be mentioned only as secondary source-control artifacts, not as the main way to open the recap.

Diff → Block Mapping

Map each kind of change to the block that carries it, derived mechanically from the actual diff. The names below are the CONCEPTUAL block types, not the JSX tags — resolve every conceptual name to its exact tag + prop schema with the get-plan-blocks tool (see "Block reference" below) before authoring.

• Schema / migration change → data-model for the resulting entities, fields, and relations. Flag what moved per field/entity with change: "added" | "modified" | "removed" | "renamed", and for a changed type set was to the prior value (e.g. the old column type) — grounded in the real migration diff. That diff-aware data-model is the headline; reach for a split diff of the literal SQL only when the exact statement still matters, not by default.
• API / action / route change → api-endpoint with the method, path, params, request, and responses as they are after the change. Flag each changed param/response with change (and was on a param whose type/shape changed), and set change on the endpoint root for a wholly added or removed route. Mark removed endpoints with deprecated: true and explain in prose. Keep multiple API endpoints in the normal single-column document flow unless they are an explicit before/after contract comparison. Author each request/response example as a SINGLE valid JSON value — one top-level object or array, parseable on its own — so it renders in the collapsible JSON explorer. Do not put // or /* */ comments, prose, trailing commas, or two or more concatenated top-level objects inside one example; a non-parseable body falls back to flat text and loses the explorer. When an endpoint has several distinct message shapes (for example separate websocket frame types, or a success body versus an error body), give each its OWN example with its own label rather than cramming them into one body.
• Compatibility-sensitive change → short rich-text notes beside the relevant data-model / api-endpoint block. Name the changed field, endpoint, or behavior and mark whether it is breaking, risky, or non-breaking; pair that note with a split diff for the literal lines.
• Any meaningful code hunk → diff with mode: "split", carrying the real before / after text and the filename / language. Split mode is the default for recap code review because before/after legibility is the point; use mode: "unified" only for a genuinely narrow standalone hunk where side-by-side would hide the code. Give every diff a one-line summary saying what the hunk changes and why; it renders as a description above the code so the reviewer reads intent first. Never leave a diff unlabeled. For the KEY changed files, attach annotations to the diff so the recap calls out what each important hunk does — this is the headline affordance for annotating the key files updated. Each annotation anchors to the AFTER-side line numbers by default (set side: "before" to point at removed lines). Keep it to a few high-signal notes per file, not one per line. When several key files each need a substantial diff, introduce the group with a rich-text heading block whose markdown is ## Key changes, then place the diff blocks under it in a reusable tabs block with horizontal orientation (the default — omit orientation) so the selected file's split diff gets the full document width. Let that heading label the section — do NOT also set a title on the tabs block. Keep each tab label to the file path or a short basename plus directory hint. The renderer's wide document layout is intentionally allowlisted: diff, annotated-code, vertical tabs, and tabs containing diff-like children break out wider than prose. Do not put API endpoints, OpenAPI specs, data models, JSON explorers, wireframes, question forms, or custom HTML into tabs merely to make them wide. If the recap ends with more than one supporting diff, that trailing diff appendix should be one horizontal tabs block under its own ## Key changes heading, not a stack of separate diff blocks.
• Brand-new file or a substantial added block with no meaningful "before" → annotated-code rather than a one-sided split diff. Carry the real new code with its filename / language and anchor a few high-signal notes to the lines that matter so the reviewer reads what the new code does, not code for code's sake. Keep split diff for true before/after hunks where the removed lines still carry meaning, and group several annotated walkthroughs in a horizontal tabs block the same way diffs are grouped.
• Files added / removed / renamed → file-tree with each entry's change flag (added, removed, modified, renamed) and a short note; attach a snippet only when one tells the reviewer something the path does not.
• Rendered UI / interaction change → one or more wireframes showing the visible UI delta before the reviewer reads code. Use Before / After wireframes when the comparison clarifies the change; otherwise use after-only or a short state/flow sequence. Use realistic UI surfaces: for a popover change, show a popover with its title row, top-right actions, options/fields, tabs, selected/disabled states, people/lists/rows, and any opened prompt/menu anchored to the correct trigger. If a route was added, show the route body and the unavailable/empty state when the diff implements one. If permissions changed, show what managers can do and what viewers/non-managers see instead. Keep the body lean: the wireframe carries the UI story, while the file tree and diff blocks carry implementation evidence.
• Architecture or data-flow shift → diagram with data.html / data.css as a two-panel before/after, layered, or swimlane layout, or mermaid for a quick graph. Use two-dimensional layouts; do not reduce a structural change to a left-to-right chain. Do not use diagram as a stand-in for rendered UI controls; UI changes need wireframe blocks. Author diagram HTML/CSS with the renderer-owned .diagram-* primitives (.diagram-panel, .diagram-node, .diagram-pill, [data-rough], …) and the same --wf-* theme tokens references/wireframe.md defines — never font-family, hex, rgb/hsl literals, or one-off dark/light palettes. Choose the outer frame intentionally: recap diagrams usually benefit from frame: "show" when they stand alone, but use frame: "hide" when columns, tabs, a card, or the diagram's own panels already provide the boundary.
• Outcome-first narrative → rich-text for the "what changed and why" prose: the objective the diff served, the key decisions visible in it, and the risks a reviewer should weigh. This is the only place the model writes freely.

Block reference — call get-plan-blocks, do not memorize tags

The conceptual block names above (api-endpoint, data-model, json-explorer, tabs, …) are NOT the JSX tags you author with, and the exact tags, required fields, and prop shapes change as the block library evolves. Do not author from memorized tags — they drift and silently produce a wrong tag (ApiEndpoint instead of Endpoint, JsonExplorer instead of Json, Tabs instead of TabsBlock) that errors on import.

Before writing any structured plan content, fetch/read the block catalog. In hosted or self-hosted mode, call get-plan-blocks on the Plan MCP connector (plan or legacy agent-native-plans). If no Plan tools are visible yet in a lazy-loading client, search/load them through the host's tool discovery surface first (tool_search when available). In local-files mode, or when the skill was installed as plain text and no MCP tools are registered after discovery, run npx @agent-native/core@latest plan blocks --out plan-blocks.md and read that file first. The CLI command calls the public no-auth get-plan-blocks route and sends no plan/recap content. If network access is unavailable, use the bundled references and validate with plan local check; run plan local serve only when the hosted Plan UI is reachable or a local Plan app is already running.

The catalog returns the authoritative, always-current block vocabulary generated live from the app's own block registry — the same config the renderer and MDX round-trip use — so it can never be stale even if this SKILL.md is an old installed copy:

• get-plan-blocks (default format: "reference") → a compact table of every block's runtime type, exact MDX <Tag>, placement, and key data fields. This is your map from each conceptual name above to its real tag and props.
• get-plan-blocks with format: "schema" → the full per-block JSON Schema plus a worked example for each block, when you need exact field types, enums, or nesting (e.g. Diff.annotations, Endpoint.params[].in, DataModel.entities[].fields[]).

Author the recap source against the tags and schemas that call returns. The complete set of valid block-level tags is whatever get-plan-blocks lists; any other capitalized tag at the block level is rejected on import with an "Unknown plan block" / "did you mean" error. Lowercase HTML tags inside rich-text/markdown prose (<div>, <span>, <code>, <br>, …) are always fine — only capitalized component-style block tags are validated.

A few recap-specific authoring rules the registry table cannot encode:

• Every structured block takes a REQUIRED id (unique across the whole plan) plus the shared optional summary / editable envelope. Ordinary top-level Markdown prose imports as rich-text automatically; use <RichText id="..."> only when prose needs explicit metadata or a preserved referenced block id.
• Every capitalized block component must be self-closing (<Diagram ... />) or explicitly closed around children (<RichText ...>...</RichText>). Never leave a bare opening tag like <RichText ...> in a paragraph; MDX treats it as unclosed JSX and import fails before the recap can render.
• Code-bearing blocks (Code, AnnotatedCode, and Diff) are whitespace-sensitive. Prefer the exact MDX form from the get-plan-blocks examples / source exporter, where multiline code is encoded as JSON string attributes such as code={"const x =\n y"}. Static template literals are accepted only when they are static strings with no ${...} interpolation.
• Endpoint: prose description is the MDX children (body between the tags), not an attribute; for a WebSocket upgrade use method="GET". Each request/response example is a JSON string (the renderer parses it into the JSON explorer), so keep it a single parseable JSON value.
• TabsBlock: the whole tabs array (including nested child blocks) is ONE JSON tabs={[…]} prop — there is NO nested <Tab> element.
• WireframeBlock: its body is a single <Screen surface ... html=… /> subtree (nested MDX, not a flat prop); html must be a single-quoted string or static template literal, never a dynamic html={someVar} expression. See references/wireframe.md for the HTML rules.
• Diagram: the whole payload is one data={{ html?, css?, nodes?, edges?, … }} attribute and requires either html or at least one node; Mermaid is its own separate block (source text), not a Diagram prop.

Before / After Is The Headline

The recap's center of gravity is the before/after comparison. For document-body comparisons there are two primitives, and they cover the whole need together:

• columns — the side-by-side container, for structured comparisons. Use two columns labeled Before and After, each holding a block (commonly a data-model, api-endpoint, or rich-text), so the reviewer reads the old shape against the new shape in one glance. This is the right primitive for "the schema went from X to Y" or "the endpoint contract changed like this." Do not use columns simply to compact or group a list of API endpoints.
• diff — for code. It renders the literal removed and added lines. Use it for the actual hunks. Use split mode by default for recap code review; reserve mode: "unified" for genuinely narrow standalone hunks where side-by-side would hide the code. Key-file diff groups should use horizontal tabs so split diffs get the full document width.

For UI diffs, wireframes are the visual comparison primitive. Use before/after wireframes when the comparison clarifies the change; use after-only or a state sequence when that better matches the change. The visual headline must show exact placement, realistic chrome, and adequate padding before any abstract explanation. Do not stop at the first visible affordance when the diff adds a flow; show the entry point, the opened surface, and the resulting state or page so the reviewer can trace the actual user path. references/wireframe.md owns the before/after layout choice — the columns renderer keeps narrow surfaces side by side and auto-stacks wide desktop/browser frames vertically; never hand-build a side-by-side wireframe layout in custom-html. For document-body comparisons, there is no other multi-column primitive — columns plus the diff block are the whole comparison vocabulary. Do not hand-build side-by-side layouts in custom-html, and do not stack two data-model blocks vertically and call it a comparison when columns exists to put them side by side.

Grounding Rule

Structured blocks are true by construction only if they are derived from the actual changed lines. The diff, data-model, api-endpoint, and file-tree blocks MUST be built mechanically from the real diff — real paths, real fields, real method/path, real before/after text — never inferred, rounded, or invented. The model writes only the prose: the "why", the narrative, the risk read. A confidently wrong recap is dangerous in a review context, because a reviewer who trusts the summary may skip the very line the summary got wrong. When the diff does not contain a fact, leave it out rather than guess; mark anything the model inferred (not extracted) as inferred in prose.

Security

• Gate visibility. Recaps of a private repo are org/login-gated — set the plan's visibility to the owning org or login, never auto-public. A recap can expose unreleased schema, internal endpoints, and architecture; treat it like the source it summarizes. Any PR comment or handoff that links to the recap must say that private-repo recaps require signing in with access to the owning org if the link does not load.
• Never transcribe secrets. A diff can contain API keys, tokens, webhook URLs, signing secrets, .env values, or credential-looking literals. Do not copy any of these into a diff, file-tree snippet, api-endpoint, or prose block — redact them (sk-•••, <redacted>). This mirrors the repo's hardcoded-secret rule: obviously fake placeholders only, never the real value, in any block, caption, or note.

Bidirectional Loop

In hosted mode, because a recap is a real, editable plan, the same review loop as forward plans applies: a reviewer can annotate any block, and the coding agent reads get-plan-feedback to drive fixes back into the code — annotation → agent → diff, the same close-the-loop flow forward plans use. After a reviewer annotates a block, call get-plan-feedback to read the structured feedback, then either update the recap with create-visual-recap (passing the existing planId to replace it in place) or apply targeted changes with update-visual-plan. The loop is live and wired. In local-files privacy mode, do not call those hosted tools; read review notes from chat or local files, edit <plan-dir>/*.mdx directly, and rerun plan local check, serve, or verify for <plan-dir>. The one thing not yet automatic is PR-comment-triggered re-runs: the GitHub Action creates an initial recap per PR, but it does not yet re-run automatically when new review feedback is posted in GitHub — that auto-re-run is the remaining fast-follow.

Related Skills

• visual-plan — the canonical command and the source of the shared Wireframe & Canvas and Document Quality cores; a recap follows the same block discipline in reverse.
• comment anchors — recap comments use the same anchor rules as forward plans; see "Interpreting comment anchors" in the visual-plan skill for coordinate frames, wireframe node ids, text-quote resolution, detached threads, routing via resolutionTarget, and two-axis consumed/resolved state.
• security — data scoping, secret handling, and the hardcoded-secret rule the recap's redaction and visibility gating mirror.
• sharing — org/login-gated visibility for the plan that holds the recap.

Read The Damn Docs

Do not guess where authoritative docs can answer the question. The most common right move is to web-search for the current official docs, open the relevant pages, and read them before coding. For APIs, versions, provider behavior, config, limits, lifecycle hooks, or security-sensitive flows, ground the answer in what the docs actually say.

Docs-First Triggers

Read docs before proceeding when any of these are true:

• The user asks for "latest", "current", "official", "supported", "best practice", "recommended", "today", "now", or "look it up".
• The needed docs are not already in the repo or supplied by the user. Search the web for the official docs rather than hoping model memory is current.
• The task adds, upgrades, configures, or imports a package, SDK, framework, plugin, CLI, model, cloud resource, or provider integration.
• The API is fast-moving or version-sensitive: AI SDKs, OpenAI/Anthropic/Google APIs, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub, Slack, Notion, browser APIs, deployment platforms, auth libraries, and similar.
• The implementation depends on auth, OAuth scopes, permissions, secrets, webhooks, billing, payments, PII, encryption, data retention, migrations, retries, rate limits, quotas, caching, deploys, or compliance.
• An error mentions deprecation, unknown options, missing exports, invalid config, unsupported fields, changed defaults, or version mismatch.
• A repo has local docs, ADRs, generated schemas, OpenAPI specs, route/action registries, design-system docs, or package-level READMEs that could define the contract.
• The choice is expensive to reverse: public wire formats, database schema, migration strategy, persistent IDs, event names, customer-visible behavior, or external automation contracts.
• You catch yourself about to write "usually", "probably", "I think", "from memory", or code copied from model memory for an external API.

What Counts As Docs

Use the most authoritative source available:

• Local repo docs, specs, ADRs, schemas, generated types, package READMEs, and tests for project-specific behavior.
• Official product docs, API references, migration guides, changelogs, release notes, and SDK source/types for third-party behavior. Find these with web search when you do not already have the exact URL.
• Package registry metadata for versions. Before adding a dependency, run npm view <pkg> version, pnpm view <pkg> version, or the ecosystem equivalent, then read the docs for that major version.
• Source code or type definitions when official docs are incomplete. Treat this as evidence, not folklore.

Avoid Stack Overflow, old blog posts, random snippets, and memory as the primary source when official docs exist. Use community sources only to debug symptoms after the authoritative contract is known.

Required Workflow

1. Identify the exact surface: package name, installed version, target version, provider endpoint, CLI command, config file, local helper, schema, or product feature.
2. Search the web for the current official docs unless the relevant docs are already local or the user supplied a URL. Use targeted searches such as <product> <feature> official docs, <package> migration guide, or <provider> API reference.
3. Open and read the docs closest to that surface. Prefer local docs first for internal code, then official upstream docs. For new packages, verify the latest version before writing imports, config, or install commands.
4. Extract the few facts needed for the task: option names, imports, lifecycle rules, default behavior, breaking changes, limits, permissions, and examples for the current major version.
5. Implement or answer using those facts. If the docs conflict with existing code, inspect the local code path and call out the discrepancy.
6. Verify with the smallest useful check: typecheck, tests, build, CLI dry run, API schema validation, or a local reproduction.
7. In the final answer, name the docs or local files consulted when that evidence affects the recommendation or implementation.

Examples That Must Trigger Docs

• "Add Tailwind to this app." Check the current Tailwind major and its install docs from the web before creating config files or assuming old PostCSS setup.
• "Use the AI SDK to stream responses." Verify the current AI SDK major, imports, provider package names, streaming helpers, and server/runtime examples from official docs.
• "Wire up Stripe webhooks." Read Stripe's current signature verification, event retry, endpoint secret, and framework body-parsing docs before coding.
• "Fix this Next.js caching bug." Read the docs for the installed Next.js major and router mode before assuming cache invalidation semantics.
• "Add Drizzle migrations." Read the current Drizzle kit docs and existing repo migration conventions before generating files.
• "Create a GitHub Action." Read official Actions syntax and permissions docs, especially for pull_request, workflow_run, OIDC, tokens, and artifacts.
• "Why does this OAuth flow fail?" Read the provider's scopes, redirect URI, PKCE, token refresh, and app verification docs before changing code.
• "Use this repo's plan/comment/action system." Read local docs, route/action registries, schemas, and tests before inventing endpoints or props.
• "Upgrade Vite/Nitro/React." Read the migration guide for the exact target major before editing config or imports.
• "What model should we use?" Read current provider model docs, pricing/limits pages, and SDK examples before recommending.

When A Quick Local Read Is Enough

Do not browse the web for every tiny edit. A docs pass can be local and brief when the answer is already in the repo: existing helper usage, nearby tests, typed interfaces, generated clients, ADRs, or package READMEs. But if the task depends on an external tool, package, provider, or current product behavior, web search is usually the right first step. For trivial language syntax, typo fixes, formatting, or self-contained code with no external contract, proceed normally.

If Docs Are Unavailable

If network access, auth, or missing local files prevents reading the docs, say that plainly before relying on memory. Narrow the uncertainty, inspect source or types if available, and avoid presenting the result as confirmed-current.