plan-skills

Renders a completed Claude Code dynamic Workflow run (wf_<runId>.json) as a self-contained, offline HTML page with a run→phase→agent tree and a parallelism timeline. Trigger when the user asks to "visualize the workflow run", "render wf trajectory", "trace a workflow", or "show the last workflow execution".

No-Python remote drop-in for plan-validator - runs the adversarial plan review on remote models over the Interactions API (curl + ADC from caller subagents; configurable roster; Vertex fallback), with a synthesis model casting an extra vote and nominating the first domino. Symptoms - "run the interactions plan panel", "remote plan validation without Python", "validate this plan via the Interactions API", "GEAP plan validation, no local scripts", geap-plan-validator wanted but no venv/Python available.

No-Python remote drop-in for spec-validator - runs the adversarial spec review on remote models over the Interactions API (curl + ADC from caller subagents; configurable roster; Vertex fallback), with a synthesis model casting an extra vote. Symptoms - "run the interactions spec panel", "remote spec validation without Python", "validate this spec via the Interactions API", "GEAP spec validation, no local scripts", geap-spec-validator wanted but no venv/Python available.

Use when a drafted implementation plan spans territories no single agent can hold at once — the spec's intent, multiple subsystems of the real codebase, and the delivery pipeline — BEFORE plan-validator, to improve the plan by deliberation rather than attack. Dispatches delegate agents each assigned a different territory to deep-read and speak for, who deliberate over bounded rounds until they converge on a single jointly revised plan, negotiating the trade-offs (migration strategy, group boundaries, scope) that a validator can only flag, never decide. Symptoms - "deliberate on this plan", "improve this plan from multiple perspectives", "the plan touches three subsystems", "we need to pick a migration strategy", plan.md spans code no one context window can deep-read whole, resolving the unconfirmed tail of a plan-validator run.

Use when a drafted spec depends on knowledge that is siloed across stakeholders, documents, or repos — BEFORE adversarial validation — to improve the spec by deliberation rather than attack. Dispatches delegate agents with deliberately DISJOINT context bundles (product, engineering, ops/security) who deliberate over bounded rounds, relayed verbatim by the orchestrator, until they converge on a single jointly revised spec. Symptoms - "deliberate on this spec", "improve this spec from multiple perspectives", "get product/eng/security input on the spec", "the constraints live in different places", spec touches systems whose limits no single context window can hold, resolving the unconfirmed tail of a spec-validator run.

Remote drop-in alternative to plan-validator - runs the adversarial implementation-plan review on Vertex AI foundation models (3 configurable skeptics + a synthesis model) instead of local subagents, attacking the plan text for ordering defects, hidden assumptions, and missing failure handling. Symptoms - "run the remote plan panel", "GEAP plan validation", "validate this plan with cloud/Vertex models", "get a second opinion on this plan from other models", plan-validator requested with remote or Gemini/Claude-on-Vertex models.

Remote drop-in alternative to spec-validator - runs the adversarial spec review on Vertex AI foundation models (3 configurable skeptics + a synthesis model) instead of local subagents, for an independent perspective from different model families. Symptoms - "run the remote spec panel", "GEAP spec validation", "validate this spec with cloud/Vertex models", "get a second opinion on this spec from other models", spec-validator requested with remote or Gemini/Claude-on-Vertex models.

Use after code is written and before merge, to confirm the implementation actually does what it claims. Dispatches independent skeptic agents that read the diff and surrounding code with a default-to-reject posture, hunt for real defects (or refute explicit acceptance claims), and assign a corrected severity — keeping only findings confirmed by a 2-of-3 majority. Symptoms - "validate this implementation", "did this actually work", "review this diff adversarially", "verify these findings are real", after completing a feature/task, before merging to main.

Use after an implementation plan is written and BEFORE executing it, to catch ordering bugs and false assumptions while they are still cheap. Dispatches independent skeptic agents that assume the plan WILL fail, read the codebase to check its assumptions, and find the first domino that topples the rest — keeping only findings confirmed by a 2-of-3 majority. Symptoms - "validate this plan", "will this plan work", "review the plan before we start", a freshly written plans/*.md from writing-plans, about to run executing-plans or subagent-driven-development.

Use after a spec or design doc is drafted and BEFORE writing an implementation plan, to find defects while they are still cheap to fix. Dispatches independent skeptic agents that attack the spec for ambiguity, missing or contradictory requirements, and untestable acceptance criteria, then keeps only findings confirmed by a 2-of-3 majority. Symptoms - "validate this spec", "poke holes in this design", "is this spec ready to plan against", finishing brainstorming before writing-plans, a freshly written specs/*.md.

Automatically scans the .agents/ directory, parses agent briefing and handoff records, and compiles a stunning interactive HTML visualization timeline written directly under .agents/trajectory.html.

The Implementation Recap renderer. After the engineer has implemented plan.md and the auditor has produced a green audit, render everything the milestone changed as a single self-contained, browsable HTML document for the human commit-gate review. Use when a reviewer needs to grasp the shape of a change — outcome + metrics, tasks completed, changed-files tree with diffstat, annotated diffs, architecture/API/schema changes, before/after UI, and the audit verdict — instead of reading prose plus a raw git diff. Triggers: "recap the changes", "show me what was built", "visualize this milestone's diff", "render the implementation recap". Additive companion to the swarm — it NEVER replaces the auditor; it runs after a green audit and produces visual-recap.html.

The Visual Software Architect. Does the architect's planning work, then renders the plan as a self-contained, browsable HTML document for human review. Use when a plan deserves a human-optimized visual review surface — architecture diagrams, file maps, annotated code, API specs, schema maps, wireframes/prototype, and open questions — instead of a wall of prose. Drop-in alternative to `architect`: still produces the machine-readable `plan.md` the swarm consumes, plus a `visual-plan.html` companion.

The Visual Product Owner. Does the product-owner's work — runs the interactive "Grill Loop" and writes a rigorous, Gherkin-based spec.md — then renders that spec as a self-contained, browsable HTML document for human review. Use when a spec deserves a human-optimized review surface — overview, user-story cards, color-coded Given/When/Then acceptance criteria, user-flow diagrams, edge-cases/constraints, wireframes/prototype, and open questions — instead of a wall of prose. Drop-in alternative to `product-owner`: still produces the machine-readable `spec.md` the swarm consumes, plus a `visual-spec.html` companion.

Use when a spec and plan are approved and the plan still has unchecked tasks — to implement each execution group with TDD, refine it, audit it, adversarially attack the diff, and commit per group behind human approval. Symptoms - "start building", "implement the plan", "execute group N", supervisor Phase 3, an approved plan.md with [ ] tasks remaining.

Use when a context report exists for a request but no validated spec yet — to turn the idea into a rigorous, testable spec and pass it through an adversarial spec gate before any planning begins. Symptoms - "write the spec", "we have research, what's next", supervisor Phase 1, a spec.md that has not yet passed spec-validation.

Use when a validated spec exists but no validated plan yet — to translate the spec into a micro-stepped, parallel-grouped implementation plan and pass it through an adversarial plan gate before any code is written. Symptoms - "write the plan", "how do we build this", supervisor Phase 2, a plan.md that has not yet passed plan-validation.

Use when every milestone under the active release in 00-ROADMAP.md is completed and committed — to finalize, tag, and ship the release behind explicit human approval. Symptoms - "ship it", "cut the release", "tag the version", supervisor Phase 4, all milestones in the active release marked COMPLETED.

Use when a new feature, bug, or refactor request arrives and no context report yet exists for it in plans/research/ — before any spec is written, to map the affected codebase domain, existing patterns, dependencies, and constraints. Symptoms - "investigate before we plan", "scope this out", starting a brand-new milestone, supervisor Phase 0.

Use when driving a feature, bug fix, or refactor through a disciplined spec-driven lifecycle end to end — coordinating multiple specialist skills, enforcing spec/plan/implementation validation gates, and gating git commits behind human approval. Symptoms - "run the swarm", "orchestrate this end to end", "be the supervisor", "drive this from idea to commit", or resuming a milestone partway through plans/active_milestones/.

The Chief Software Architect. Manages the roadmap, prioritizes tasks, and creates detailed implementation plans.

The Quality & Consistency Gatekeeper. Verifies tests, checks for regression, and ensures the active Plan matches the Codebase reality.

The Expert Builder. Implements changes using TDD, Strangler Fig, and Gather-Calculate-Scatter patterns.

The Product Owner. Translates human ideas into rigorous specifications through interactive "grilling" and manages the Master Roadmap.

Expertise in simplifying and refining code for clarity, consistency, and maintainability while preserving all functionality. Use when the user asks to "simplify code", "refactor for clarity", or "clean up this file".

Use when you need to act as the Project Manager orchestrating the agent swarm (Architect, Engineer, Auditor, Product Owner) to drive a feature, bug fix, or refactor through the full spec→plan→execute lifecycle. Load this role before running any operation. Triggers - "be the supervisor", "set the supervisor role", "orchestrate this end to end", "run the swarm", "drive this from idea to commit", or resuming a milestone in plans/active_milestones/.