plan-viz
Visualize planned changes before implementation. Use when reviewing plans, comparing before/after architecture, assessing risk, or analyzing execution order and impact.
How do I install this agent skill?
npx skills add https://github.com/yonatangross/orchestkit --skill plan-vizIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is safe for visualizing development plans by analyzing repository state. It presents an indirect prompt injection surface through its integration with external GitHub issue content.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · No issues
- Runlayerwarn
3/17 files flagged
What does this agent skill do?
Plan Visualization
Render planned changes as structured ASCII visualizations with risk analysis, execution order, and impact metrics. Every section answers a specific reviewer question.
Core principle: Encode judgment into visualization, not decoration.
/ork:plan-viz # Auto-detect from current branch
/ork:plan-viz billing module redesign # Describe the plan
/ork:plan-viz #234 # Pull from GitHub issue
Argument Resolution
PLAN_INPUT = "$ARGUMENTS" # Full argument string
PLAN_TOKEN = "$ARGUMENTS[0]" # First token — could be issue "#234" or plan description
# If starts with "#", treat as GitHub issue number. Otherwise, plan description.
# $ARGUMENTS (full string) for multi-word descriptions (CC 2.1.59 indexed access)
STEP 0: Detect or Clarify Plan Context
First, attempt auto-detection by running scripts/detect-plan-context.sh:
bash "$SKILL_DIR/scripts/detect-plan-context.sh"
This outputs branch name, issue number (if any), commit count, and file change summary.
If auto-detection finds a clear plan (branch with commits diverging from main, or issue number in args), proceed to Step 1.
If ambiguous, clarify with AskUserQuestion:
AskUserQuestion(
questions=[{
"question": "What should I visualize?",
"header": "Source",
"options": [
{"label": "Current branch changes (Recommended)", "description": "Auto-detect from git diff against main", "markdown": "```\nBranch Diff Analysis\n────────────────────\n$ git diff main...HEAD\n\n→ File change manifest (+A, M, -D)\n→ Execution swimlane by phase\n→ Risk dashboard + pre-mortems\n→ Impact summary (lines, tests, API)\n```"},
{"label": "Describe the plan", "description": "I'll explain what I'm planning to change", "markdown": "```\nPlan Description\n────────────────\nYou describe → I visualize:\n\n→ Before/after architecture diagrams\n→ Execution order with dependencies\n→ Risk analysis per component\n→ Decision log (ADR-lite format)\n```"},
{"label": "GitHub issue", "description": "Pull plan from a specific issue number", "markdown": "```\nGitHub Issue Source\n───────────────────\n$ gh issue view #N\n\n→ Extract requirements from body\n→ Map to file-level changes\n→ Generate execution phases\n→ Link back to issue for tracking\n```"},
{"label": "Quick file diff only", "description": "Just show the change manifest, skip analysis", "markdown": "```\nQuick File Diff\n───────────────\n[A] src/new-file.ts +120\n[M] src/existing.ts +15 -8\n[D] src/old-file.ts -45\n─────────────────────────────\nNET: +82 lines, 3 files\n\nNo risk analysis or swimlanes\n```"}
],
"multiSelect": false
}]
)
STEP 1: Gather Data
Run scripts/analyze-impact.sh for precise counts:
bash "$SKILL_DIR/scripts/analyze-impact.sh"
This produces: files by action (add/modify/delete), line counts, test files affected, and dependency changes.
For architecture-level understanding, spawn an Explore agent on the affected directories:
Agent(
subagent_type="Explore",
prompt="Explore the architecture of {affected_directories}. Return: component diagram, key data flows, health scores per module. Use the ascii-visualizer skill for diagrams.",
model="haiku"
)
STEP 2: Render Tier 1 Header (Always)
Use assets/tier1-header.md template. Load Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/visualization-tiers.md") for field computation (risk level, confidence, reversibility).
PLAN: {plan_name} ({issue_ref}) | {phase_count} phases | {file_count} files | +{added} -{removed} lines
Risk: {risk_level} | Confidence: {confidence} | Reversible until {last_safe_phase}
Branch: {branch} -> {base_branch}
[1] Changes [2] Execution [3] Risks [4] Decisions [5] Impact [all]
STEP 3: Ask Which Sections to Expand
AskUserQuestion(
questions=[{
"question": "Which sections to render?",
"header": "Sections",
"options": [
{"label": "All sections", "description": "Full visualization with all 5 core sections", "markdown": "```\n[1] Change Manifest [A]/[M]/[D] file tree\n[2] Execution Swimlane with phases\n[3] Risks Dashboard + pre-mortems\n[4] Decisions ADR-lite decision log\n[5] Impact Lines, tests, API, deps\n```"},
{"label": "Changes + Execution", "description": "File diff tree and execution swimlane", "markdown": "```\n[1] Change Manifest\n [M] src/auth.ts +45 -12\n [A] src/oauth.ts +89\n\n[2] Execution Swimlane\n Phase 1 ====[auth]========▶\n Phase 2 ----[blocked]--===▶\n```"},
{"label": "Risks + Decisions", "description": "Risk dashboard and decision log", "markdown": "```\n[3] Risk Dashboard\n MEDIUM ██░░ migration reversible\n HIGH ███░ API breaking change\n Pre-mortem: \"What if auth fails?\"\n\n[4] Decision Log\n D1: OAuth2 over JWT (security)\n D2: Postgres over Redis (durability)\n```"},
{"label": "Impact only", "description": "Just the numbers: files, lines, tests, API surface", "markdown": "```\n[5] Impact Summary\n ┌──────────┬─────┬───────┐\n │ Metric │Count│ Delta │\n ├──────────┼─────┼───────┤\n │ Files │ 12 │ +3 │\n │ Lines │ 450 │ +127 │\n │ Tests │ 8 │ +4 │\n │ API sfc │ 3 │ +1 │\n └──────────┴─────┴───────┘\n```"}
],
"multiSelect": false
}]
)
STEP 4: Render Requested Sections
Render each requested section following ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/rules/section-rendering.md conventions. Use the corresponding reference for ASCII patterns:
| Section | Reference | Key Convention |
|---|---|---|
| [1] Change Manifest | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/change-manifest-patterns.md) | [A]/[M]/[D] + +N -N per file |
| [2] Execution Swimlane | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/execution-swimlane-patterns.md) | === active, --- blocked, | deps |
| [3] Risk Dashboard | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/risk-dashboard-patterns.md) | Reversibility timeline + 3 pre-mortems |
| [4] Decision Log | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/decision-log-patterns.md) | ADR-lite: Context/Decision/Alternatives/Tradeoff |
| [5] Impact Summary | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/assets/impact-dashboard.md) | Table: Added/Modified/Deleted/NET + tests/API/deps |
STEP 5: Offer Actions
After rendering, offer next steps:
AskUserQuestion(
questions=[{
"question": "What next?",
"header": "Actions",
"options": [
{"label": "Write to designs/", "description": "Save as designs/{branch}.md for PR review", "markdown": "```\nSave to File\n────────────\ndesigns/\n └── feat-billing-redesign.md\n ├── Header + metadata\n ├── All rendered sections\n └── Ready for PR description\n```"},
{"label": "Generate GitHub issues", "description": "Create issues from execution phases with labels and milestones", "markdown": "```\nGitHub Issues\n─────────────\n#101 [billing] Phase 1: Schema migration\n labels: component:billing, risk:medium\n#102 [billing] Phase 2: API endpoints\n labels: component:billing, risk:low\n blocked-by: #101\n```"},
{"label": "Drill deeper", "description": "Expand blast radius, cross-layer check, or migration checklist", "markdown": "```\nDeep Dive Options\n─────────────────\n[6] Blast Radius\n direct → transitive → test impact\n[7] Cross-Layer Consistency\n Frontend ↔ Backend endpoint gaps\n[8] Migration Checklist\n Ordered runbook with time estimates\n```"},
{"label": "Done", "description": "Plan visualization complete"}
],
"multiSelect": false
}]
)
Write to file: Save full report to designs/{branch-name}.md using assets/plan-report.md template.
Generate issues: For each execution phase, create a GitHub issue with title [{component}] {phase_description}, labels (component + risk:{level}), milestone, body from plan sections, and blocked-by references.
Deep Dives (Tier 3, on request)
Available when user selects "Drill deeper". Load Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/deep-dives.md") for cross-layer and migration patterns.
| Section | What It Shows | Reference |
|---|---|---|
| [6] Blast Radius | Concentric rings of impact (direct -> transitive -> tests) | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/blast-radius-patterns.md) |
| [7] Cross-Layer Consistency | Frontend/backend endpoint alignment with gap detection | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/deep-dives.md) |
| [8] Migration Checklist | Ordered runbook with sequential/parallel blocks and time estimates | (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/deep-dives.md) |
Key Principles
| Principle | Application |
|---|---|
| Progressive disclosure | Tier 1 header always, sections on request |
| Judgment over decoration | Every section answers a reviewer question |
| Precise over estimated | Use scripts for file/line counts |
| Honest uncertainty | Confidence levels, pre-mortems, tradeoff costs |
| Actionable output | Write to file, generate issues, drill deeper |
| Anti-slop | No generic transitions, no fake precision, no unused sections |
Rules Quick Reference
| Rule | Impact | What It Covers |
|---|---|---|
section-rendering (load ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/rules/section-rendering.md) | HIGH | Rendering conventions for all 5 core sections |
| ASCII diagrams | MEDIUM | Via ascii-visualizer skill (box-drawing, file trees, workflows) |
References
Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/<file>"):
| File | Content |
|---|---|
visualization-tiers.md | Progressive disclosure tiers and header field computation |
change-manifest-patterns.md | Change manifest ASCII patterns |
execution-swimlane-patterns.md | Execution swimlane ASCII patterns |
risk-dashboard-patterns.md | Risk dashboard ASCII patterns |
decision-log-patterns.md | Decision log ASCII patterns |
blast-radius-patterns.md | Blast radius ASCII patterns |
deep-dives.md | Cross-layer consistency and migration checklist |
Assets
Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/assets/<file>"):
| File | Content |
|---|---|
plan-report.md | Full mustache-style report template |
impact-dashboard.md | Impact table template |
tier1-header.md | 5-line summary template |
Related Skills
ork:implement- Execute planned changesork:explore- Understand current architectureork:assess- Evaluate complexity and risks
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/yonatangross/orchestkit/plan-viz">View plan-viz on skillZs</a>