Skip to content

Vinix24/vnx-orchestration / .claude/skills/planner

planner

Verified

Planning specialist that breaks a VNX feature or track into small, independently-shippable PRs with dependencies and per-PR task-class routing. USE THIS when the user wants to break a feature down into PRs, sequence the work, or turn a plan into a PR queue. Delegated to by @horizon (formerly @pm — @pm still resolves via alias). Works from Horizon's tracks DB (`vnx horizon`, alias `vnx objective`); the repo FEATURE_PLAN.md is a generated generic example, not the source.

Planning Specialist

Generate structured FEATURE_PLAN.md documents with PR-based breakdown for T0 orchestration.

Core Responsibilities

  • Break features into reviewable PRs (300-450 lines each, 300 or less on a security, permission or auth path)
  • Define clear PR dependencies and execution order
  • Map skills to specific PRs
  • Validate PR size constraints
  • Ensure acyclic dependency graphs
  • Write quality gates that become trackable deliverables (see Governance Model)

Planning Process

  1. Analyze Requirements: Break down into testable requirements
  2. PR Decomposition: Split into 300-450 line PRs with clear scope; above 450 split, bundle serially dependent changes on the same files into one PR
  3. Skill Assignment: Map appropriate @skill to each PR
  4. Dependency Mapping: Define PR execution order (must be acyclic)
  5. Size Validation: Verify all PRs within the 300-450 line constraint (hard cap 450, 300 on security paths)
  6. Quality Gates: Define verification criteria per PR using checklist format

Governance Model: Quality Gates as Deliverables

Quality gate items become open items once the track is imported. Each checklist item is tracked individually with a severity level. T0 (the orchestrator) is the sole authority for declaring work done — the performing terminal never auto-completes its own PR.

Flow:

FEATURE_PLAN.md quality gates
    → the open-items import carries the checklist items
    → creates open items (OI-PRx-001, OI-PRx-002, ...)
    → terminal executes work, receipt records evidence
    → T0 reviews evidence, closes satisfied items
    → all blockers/warns closed → PR complete

This means every quality gate item you write will be individually tracked. Write them to be:

  • Specific: "All 405 tests pass" not "Tests pass"
  • Measurable: Include numbers, thresholds, or binary criteria
  • Verifiable: T0 must be able to evaluate evidence against the criterion

Quality Gate Severity Classification

Items are classified by keywords:

SeverityKeywordsExample
blocker"all tests pass", "E2E", "100%", "test suite passes"- [ ] All tests pass
warn"memory", "zombie", "regression", ">=", "shutdown", "speed"- [ ] Memory profiling: no regression
infoDefault (anything else)- [ ] Dashboard shows accurate data

Rule of thumb: If a failing item should block the PR, make sure its wording triggers blocker classification.

FEATURE_PLAN.md Format (Required)

Every FEATURE_PLAN.md MUST follow this structure:

# Feature: [Feature Name]

## PR-1: [PR Title]
**Track**: A
**Priority**: P1
**Complexity**: Medium
**Risk**: Low
**Skill**: @backend-developer
**Estimated Time**: 2-3 hours
**Dependencies**: []

### Description
[What this PR does]

### Scope
- File changes listed here

### Success Criteria
- Criterion 1
- Criterion 2

### Quality Gate
`gate_pr1_descriptive_name`:
- [ ] All tests pass
- [ ] Specific measurable criterion
- [ ] Another verifiable criterion

---

## PR-2: [Next PR Title]
**Dependencies**: [PR-1]
...

Critical Format Rules

  1. PR headers: Must be ## PR-X: Title (exactly this format)
  2. Metadata fields: Use **Field**: Value format (bold markdown)
  3. Dependencies: Use [PR-1, PR-2] array format, [] for none
  4. Quality Gate section: Must be ### Quality Gate followed by backtick gate name
  5. Checklist items: Must use - [ ] format (markdown checkboxes)
  6. PR separator: Use --- between PRs
  7. Gate name: Use backtick format `gate_prX_descriptive_name`

Examples

  • /planner Create authentication system plan
  • "Use planner skill to break down the refactoring"
  • "Generate FEATURE_PLAN for the API redesign"

PR Size Guidelines

Target Range: 300-450 changed lines per PR (tests included), hard cap 450, 300 or less on security, permission and auth paths. Serially dependent changes on the same files are one PR; independent PRs stay separate. Measured on 67 merges of 2026-11-08: 150-300 lines took 0.8 h and 1.23 review rounds, 300-450 lines 0.6 h and 1.33 rounds, above 450 lines 1.5 h and 2.89 rounds.

How to estimate:

  • Count modified/created files
  • Estimate lines per file (implementation + tests)
  • Include documentation updates
  • Add 10% buffer for edge cases

If PR exceeds 300 lines: Split into smaller, logical PRs If PR below 150 lines: Combine with related work

Skill Assignment

Available skills (use with @ prefix in FEATURE_PLAN, without @ in dispatches):

  • @backend-developer - Python/API implementation
  • @api-developer - REST API endpoints
  • @frontend-developer - UI components
  • @test-engineer - Testing infrastructure
  • @quality-engineer - Quality assurance and validation
  • @debugger - Issue investigation
  • @reviewer - Code review
  • @architect - System design
  • @security-engineer - Security hardening
  • @performance-profiler - Performance analysis
  • @python-optimizer - Code optimization
  • @supabase-expert - Database optimization
  • @data-analyst - Data analysis
  • @monitoring-specialist - Monitoring setup

Key Principles

  1. Right-sized PRs: 300-450 lines (300 on security paths), never above 450
  2. Clear Dependencies: Explicit prerequisite mapping (acyclic)
  3. Skill Alignment: Right expertise for each PR
  4. Size Validation: Estimate and verify line counts
  5. Quality Gates as Deliverables: Every checklist item becomes a tracked open item
  6. Specific & Measurable: Quality criteria must be evaluable by T0

Output Instructions

See template.md for report format and output location.

Intelligence Access

Use scripts/intelligence.sh for accessing VNX intelligence patterns and solutions.


Skill Activation Announcement

MANDATORY — first line of every response after skill load:

Skill actief: planner

No exceptions. This must appear before any other content.

planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall