Defines the Vendix planning protocol before development. Trigger: When creating implementation plans, analyzing non-trivial changes, decomposing work, or preparing multi-agent development.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Defines the Vendix planning protocol before development. Trigger: When creating implementation plans, analyzing non-trivial changes, decomposing work, or preparing multi-agent development.
license
MIT
metadata
{"author":"rzyfront","version":"2.4","scope":["root"],"auto_invoke":["Creating implementation plans or decomposing non-trivial work","Planning structural changes, multi-file changes, broad refactors, or new features","Discovering reusable assets before proposing new code","Verifying plan completeness before approval","Choosing between viable architectural approaches","Declaring MCP servers, CLI commands, or web research alongside skills in a plan","Running the Plan Validation Checklist before requesting approval","Selecting the correct skills for each plan step using the Skill Selection Matrix","Picking concrete verification mechanisms (curl, build, audit, log inspection) per step","Choosing Playwright MCP for frontend E2E verification in a plan step"]}
How To Plan
Purpose
Define the planning protocol every Vendix agent must follow before writing code. A valid plan explains why the change exists, what general and specific outcomes it must achieve, which skills govern each step, which business decisions apply, which files are affected, which existing assets are reused, and how the result is verified end-to-end.
This skill specifies both the format of the plan and the operational workflow to produce it (5 explicit phases mirroring the Claude Code Plan Mode).
Core Rules
Always plan before non-trivial development. Trivial = single-line fix, typo, or isolated config change under 10 lines (see global rule 2.3).
Every Step block must contain ALL SIX mandatory fields, in this order: Skills, Resources, Business decision, Why, Output, Verification. Missing any field invalidates the entire plan — it is not approvable until fixed.
Every plan step must reference the skills that govern it, or be explicitly marked Knowledge gap when no skill exists. Never list how-to-plan as a step skill — it governs planning, not execution.
Every plan step must declare the Business decision it enforces (rule, product behavior, or technical policy). This field is non-negotiable.
Every plan step must declare its Resources — external tooling beyond skills: MCP servers (pencil, github, etc.), build / test / migration commands, web searches consulted for official docs, third-party APIs, dashboards, or any non-skill input. Vague resources are forbidden: write the exact command (npm run test -w apps/backend -- --runInBand path/to/spec.ts), not "backend tests".
Every plan step must declare its per-step Verification (the check that proves this step done). E2E verification at plan level does not replace per-step verification.
Every plan must split outcomes into General Objective + Specific Objectives. Specific objectives must be individually verifiable.
Compare viable approaches and record the chosen one with rationale.
Actively search for reusable functions, components, services, and patterns before proposing new code. Document them under Reusable Assets.
Critical Files must list concrete paths (controller, service, DTO, component). Wildcards (domain/x/*) are forbidden — the developer must not have to re-discover scope.
The plan must contain only the sections defined in Required Plan Format. Adding ad-hoc sections (e.g. Assumptions, Notes, TODO) is forbidden: fold their content into Context, the matching Step's Business decision, or Knowledge Gaps.
Use subagents through agent-teams. Maximum 3 in parallel per phase. Default = 1.
Never ask "is this plan ok?" — request approval through the formal mechanism (see User Interaction Boundary).
Never replan during execution unless the human explicitly requests it (global rule 1.3).
Before adding the ## Approval Request block, the planner must run the Plan Validation Checklist (see below) and only proceed if every box is checked.
Plan Workflow Phases
Every non-trivial plan flows through five phases. Phases are sequential, not optional.
Phase
Goal
Tools
Output
Max Agents
1. Understanding
Map the request, codebase areas affected, and existing assets to reuse
Explore subagent type, Read, grep, skill lookup
Inventory of files, symbols, skills, and reusable assets
3
2. Design
Generate one or more implementation approaches and compare them
Plan subagent type, web search if needed
Candidate approach(es) with trade-offs
3
3. Review
Read the critical files surfaced in Phase 1, validate the chosen approach against reality, clarify ambiguities
Read, AskUserQuestion
Refined approach + unresolved questions answered
1
4. Final Plan
Write the plan file using the Required Plan Format
Write / Edit on the plan file only
Complete plan file ready for human review
0
5. Approval
Present the plan and request explicit human confirmation. Do not execute until approved.
Formal approval request (see User Interaction Boundary)
"ejecuta" / "apruebo" / "procede" from the human
0
Phase-specific rules
Phase 1 uses Explore (read-only search). Use it for "where is X defined", "find references to Y", "list components matching Z". Do not use Explore for design.
Phase 2 uses Plan (architectural design). Brief it with concrete filenames, code path traces, and constraints discovered in Phase 1. A vague Phase 2 prompt produces a vague plan.
Phase 3 is the only phase where AskUserQuestion is appropriate, and only to (a) choose between viable approaches or (b) resolve a requirement ambiguity that grep cannot answer.
Phase 4 edits only the plan file. No source code changes.
Phase 5 uses the formal approval block in the plan, never an AskUserQuestion.
Agent Strategy
Default delegation strategy when invoking agent-teams.
Task Type
Agent Count
Notes
Isolated change in known files
1 Explore
Same files the user named or that grep finds immediately
Each agent argues a different trade-off: simplicity / performance / maintainability
Cross-cutting refactor
2 Explore + 1 Plan
Sequential: discover, then design
Parallelization rules
Independent agents → single message with multiple tool calls.
Dependent agents → sequential; pass each output to the next.
Hard ceiling: 3 in parallel per phase. Going wider duplicates searches and pollutes context.
Subagent prompt requirements
Every prompt to a subagent must include:
The user's original goal in one sentence.
The phase (Understanding / Design) and what the agent owns within it.
Concrete filenames, symbols, or code path traces already known.
Explicit constraints (skills the work must respect, anti-patterns to avoid).
The expected output shape (list of files, comparison table, decision matrix).
Whether the agent should investigate (read-only) or write code — never assume.
A vague prompt ("look at the codebase and tell me what to do") wastes the agent slot.
Resources Beyond Skills
Skills capture repeatable Vendix patterns, but a plan rarely succeeds with skills alone. Each step must also declare the external resources it depends on. A plan that only lists skills is incomplete.
Always pair skills with resources in each step. Skills: vendix-prisma-migrations + Resources: npx prisma migrate dev --name <slug> is complete; just the skill is not.
Web research is part of planning, not improvisation. If the step needs vendor docs, link them upfront in Resources, not mid-execution.
If the plan reveals that a skill is outdated relative to a fresh web source, mark a Knowledge Gap to update the skill via skill-creator.
Resources are descriptive, not authorizations. Destructive actions (migrations on prod, deletions, force pushes) still require explicit human confirmation regardless of being listed.
Reuse Discovery (mandatory Phase 1 checklist)
Before any step proposes new code, the planner must complete this checklist:
Grep for related symbols, types, services (grep -rn "ConceptName" apps/).
Read the SKILL.md of every domain affected (use the Auto-invoke tables in AGENTS.md / CLAUDE.md as a map).
If mobile (apps/mobile) work is identified, load mobile-dev and restrict all edits to apps/mobile/ only.
List the assets found under Reusable Assets in the plan, with their paths. If nothing is reusable, state so explicitly.
Skipping this checklist causes duplication (a second CurrencyFormatService, a parallel modal wrapper, a redundant guard). Duplication is a planning failure, not a coding failure.
Required Plan Format
Every plan file must use this exact structure. Sections are ordered, all are mandatory, none may be omitted, renamed, or supplemented with extras.
## Context <!-- [MANDATORY] 2-5 sentences. Why this change exists. -->
[Problem it solves, what triggered it, expected outcome.]
## General Objective <!-- [MANDATORY] one sentence, human-facing outcome. -->
[Single sentence.]
## Specific Objectives <!-- [MANDATORY] N items, each individually verifiable. -->1. [Measurable sub-result 1]
2. [Measurable sub-result 2]
3. [...]
## Approach Chosen <!-- [MANDATORY] selected approach + why it beats alternatives. -->
[Selected approach and why it beats the alternatives.]
## Alternatives Considered <!-- [MANDATORY] at least 1 rejected alternative with reason. -->- [Alternative]: [why it was not chosen]
## Critical Files <!-- [MANDATORY] concrete paths only. Wildcards forbidden. -->-`apps/backend/src/domains/x/y.controller.ts` — [role in the change]
-`apps/frontend/src/app/.../z.component.ts` — [role in the change]
## Reusable Assets <!-- [MANDATORY] from Reuse Discovery. State "none — rationale" if empty. -->-`path/to/asset.ts` — [what it provides, why it fits]
## Steps <!-- [MANDATORY] each step has ALL SIX FIELDS below. -->1. [Step name]
Skills: [skill-1], [skill-2] <!-- [MANDATORY] never `how-to-plan` itself -->
Resources: [exact CLI command | MCP tool | doc URL | `none`] <!-- [MANDATORY] no vague phrases -->
Business decision: [rule, product behavior, or technical policy being applied] <!-- [MANDATORY] -->
Why: [reason this step exists AND why in this position relative to others] <!-- [MANDATORY] -->
Output: [concrete artifact or behavior produced] <!-- [MANDATORY] -->
Verification: [exact check for THIS step — command, file diff, UI assertion] <!-- [MANDATORY] -->
## End-to-End Verification <!-- [MANDATORY] integration-level, with concrete tools. -->1. [Integration check covering multiple steps + tool used: curl, UI flow, build command, etc.]
2. [User-facing or contract-level check + how it is observed]
3. [Build / typecheck / test command — exact invocation]
## Knowledge Gaps <!-- [MANDATORY] write "None." if there are none. -->- [Gap]: [missing skill or skill update proposed, with rationale]
## Approval Request <!-- [MANDATORY] verbatim block below. -->
This plan is ready for human review. Reply **"ejecuta"**, **"apruebo"**, or **"procede"** to start execution under `how-to-dev`. Reply with corrections to revise the plan in place.
Field-by-Field Rigor
Each row defines what counts as acceptable vs rejected. If a field falls in the rejected column, the plan is not approvable.
User-facing flow: login, navigation, form submit, render — against the real vhost
browser_navigate({url:'https://vendix.com'}) then browser_snapshot() (see how-to-test; the Playwright MCP server must be launched with --ignore-https-errors — a single context-level flag that covers page + subresources on the local self-signed vhost)
agent-browser (E2E fallback)
Only when Playwright MCP cannot: wait on a CSS selector, manual scroll, or read page markdown
agent-browser support MCP — see how-to-test § Fallback
Backend unit test
Service logic
npm run test -w apps/backend -- --runInBand src/domains/organization/invoicing/invoicing.service.spec.ts
Frontend build
Type safety after refactor
npm run build:prod -w apps/frontend
Zoneless audit
Signal-based components
npm run zoneless:audit
Migration verification
DB schema change
npx prisma migrate status + targeted SQL SELECT
Permission verification
RBAC change
curl with a token whose role lacks the permission must return 403
Manual UI check
Behavior not covered by build
Document the exact route + steps + expected state
Log inspection
Async flow / queue
`docker logs --tail 200 vendix-backend
curl is the primary mechanism for verifying API contracts and auth boundaries. Agents must
NOT run Bruno (.bru) tests as plan verification. For authenticated endpoints in dev, get a
token by logging in with a seed owner account (owner@techsolutions.co or
owner@fashionretail.com, password 1125634q — see apps/backend/prisma/seeds/users.seed.ts)
or by asking the user for the slug, email, and password of an authorized dev test
account. Bruno remains an opt-in template (vendix-bruno-test) only when a developer explicitly
requests writing a .bru test.
For frontend flows, Playwright MCP is the primary E2E verification mechanism — drive the real
vhost (https://vendix.com and its subdomains), never localhost:4200, because the app resolves
its app_type by hostname. The Playwright MCP server must be launched with --ignore-https-errors
— a single context-level flag that makes Chromium trust the local self-signed vhost for both
the page and every subresource fetch (including the app_type resolve call). Playwright MCP runs
headed by default. agent-browser stays as a scoped fallback MCP for the few things Playwright
MCP cannot do (arbitrary CSS-selector wait, manual scroll, page-markdown read). The full
methodology (install, vhost setup, credentials, recipes, fallback matrix) lives in how-to-test.
Plan Validation Checklist
Before adding the ## Approval Request block, the planner must mentally (or literally) check every item below. Any unchecked item blocks approval and must be fixed in place.
Structural
All 11 mandatory top-level sections exist in this exact order: Context, General Objective, Specific Objectives, Approach Chosen, Alternatives Considered, Critical Files, Reusable Assets, Steps, End-to-End Verification, Knowledge Gaps, Approval Request.
No ad-hoc sections were added (Assumptions, Notes, TODO, Risks, etc.). If such content matters, it was folded into Context or a Step's Business decision.
Specific Objectives has at least 1 entry; each is independently verifiable (no "Improve X").
Alternatives Considered lists at least 1 rejected alternative with reason.
Per-Step (apply to every step in Steps)
Skills: listed, none is how-to-plan, no obvious skill is missing (run Skill Selection Matrix below).
Resources: is an exact command / URL / MCP tool / or the literal word none. No vague phrases ("run tests").
Business decision: present, names a concrete rule, product behavior, or technical policy (not a wish like "must work well").
Why: present, explains why the step exists and why it sits at this position in the sequence.
Output: describes a concrete artifact, endpoint shape, file, or behavior — not a hand-wave.
Verification: is an exact check picked from the Verification Mechanisms Catalog, scoped to this step (not the whole plan).
Files & assets
Critical Files lists concrete paths only — zero wildcards, zero "folder X".
Every step's expected file edits map to entries in Critical Files (or are added there).
Reusable Assets was populated from a real Reuse Discovery pass; if empty, the rationale is stated.
Verification
End-to-End Verification covers integration paths, not single-step checks (those live in each Step).
Every E2E item names a concrete tool / command (curl, build command, log inspection).
Knowledge Gaps is present and explicit — None. is allowed; absence is not.
Skill Selection Matrix (use to catch missed skills before approving)
Run this matrix against every step. If the trigger applies, the skill must appear in that step's Skills.
When Phase 2 uses multiple Plan agents, assign each a distinct perspective so their outputs do not collapse into the same proposal.
Perspective
Owns
Domain analysis
Business rules, permissions, tenant scope, data ownership
Implementation analysis
Files, dependencies, ordering, risk
Verification analysis
Logs, tests, build checks, edge cases
UX / API analysis
User-facing behavior, contracts, states, errors
For broad work, route through agent-teams. If agent tooling is unavailable, document the limitation and run separate named analysis passes — never pretend multi-agent review happened.
Knowledge Gaps
A knowledge gap exists when a planned step requires a repeatable pattern that no existing skill covers.
When a gap appears:
Mark the step as Knowledge gap instead of inventing rules.
Describe the missing pattern and why it matters.
Propose the new skill name (or the existing skill to update).
Ask the human whether to create or update the skill via skill-creator.
Relationship With Development
After the ## Approval Request is satisfied, execution moves to how-to-dev. The developer agent must:
Load every skill listed under Skills: in each step before touching that step.
Preserve every recorded Business decision. Deviating from one requires returning to planning, not silent override.
Treat Critical Files and Reusable Assets as the starting map — extend it only with discoveries, never replace it.
Run the End-to-End Verification block before reporting completion.
Never replan unless the human explicitly requests it.
Mandatory gates before any plan is "done":
Before declaring the work complete, the developer must also satisfy the git-workflow skill (RULES 5–8):
The branch is up to date with origin/dev (RULE 5).
The latest Engram memories have been pulled at the start of work (RULE 6).
A new Engram memory has been saved for any non-trivial decision, gotcha, or pattern introduced by this plan (RULE 7).
The resulting PR has been reviewed by the pr-code-review skill and passed the 80% threshold (RULE 8).
If any of these gates is not met, the work is not done — return to the gate before claiming completion.
Related Skills
how-to-dev — Development execution after planning.
git-workflow — Required for branches, commits, pushes, PR review, and the Engram memory lifecycle (RULES 5-8 are post-plan gates).
vendix-engram — Persistent shared memory used to satisfy RULES 6-7 of git-workflow.
pr-code-review — The 80% pass gate that closes the loop on RULE 8.
agent-teams — Subagent orchestration for Phase 1 and Phase 2.
skill-creator — Resolving knowledge gaps by creating or updating skills.
skill-sync — Synchronizing skill metadata to AGENTS.md / CLAUDE.md after changes.
vendix-core — Map of skills by domain for Reuse Discovery.
buildcheck-dev — Verification of build / runtime after execution.
how-to-test — Runtime verification methodology: curl for API/auth, Playwright MCP for frontend E2E against the vhost (agent-browser as fallback).
Changelog
v2.4 — Switched the frontend E2E verification mechanism from agent-browser to Playwright MCP (@playwright/mcp) as primary, with agent-browser demoted to a documented fallback. Updated the Verification Mechanisms Catalog (Playwright MCP row + agent-browser fallback row), the frontend verification note (single --ignore-https-errors context-level flag for the local self-signed vhost), and the auto_invoke trigger. Full methodology remains in how-to-test.
v2.3 — Added agent-browser to the Verification Mechanisms Catalog as the frontend E2E mechanism (drive the real vhost, not localhost:4200). Linked the new how-to-test skill (full curl + agent-browser methodology) from the verification note and Related Skills. Synced frontmatter version (was stale at 2.1 while the changelog already listed 2.2).
v2.2 — Removed Bruno from the Verification Mechanisms Catalog and all examples. curl is now the primary mechanism for API-contract and auth-boundary checks; agents must not run .bru tests as plan verification. Documented dev credential sources (seed owner accounts + ask-the-user). Bruno survives only as the opt-in vendix-bruno-test template.
v2.1 — Hardening pass for 100% format compliance. Added: explicit "six mandatory fields per step" rule, Plan Validation Checklist (structural / per-step / files / verification + Skill Selection Matrix), Field-by-Field Rigor table with acceptable-vs-rejected examples, Verification Mechanisms Catalog (Bruno, curl, build, audit, log inspection). Annotated Required Plan Format template with [MANDATORY] inline markers. Anti-Patterns extended with: missing Why/Verification, wildcards in Critical Files, vague Resources, how-to-plan listed as step skill, non-spec sections (Assumptions/Notes/Risks), absent Knowledge Gaps, subscription-gate misapplied to read-only steps, missing vendix-multi-tenant-context on tenant-scoped steps.
v2.0 — Major rewrite. Added 5-phase workflow (Understanding / Design / Review / Final Plan / Approval), Agent Strategy with parallel cap of 3, Reuse Discovery checklist, Anti-Patterns table, User Interaction Boundary, Resources Beyond Skills section. Format extended with Context, General Objective + Specific Objectives (replaces singular Objective), Critical Files, Reusable Assets, End-to-End Verification, Approval Request, and Resources: field per step (MCPs, CLI commands, web research, external APIs). Preserved:Business decision per step, Skills per step, Knowledge Gaps, multi-agent perspective matrix.
v1.0 — Initial release. Defined skills-per-step + business-decision-per-step format with single Objective.
