agentleFS
Vinix24Vinix24/vnx-orchestration/.claude/skills/featureplan-kickoff/SKILL.md

featureplan-kickoff

Skill63 starsChanged 4 days agoMITView on GitHub

VNX feature-execution kickoff preflight. USE THIS when starting or resuming a feature or track from its plan: checking worktree/queue/staging health, finding the first promoteable dispatch, and handing off to @t0-orchestrator. Reads the feature's track + plan doc from Horizon's tracks DB (`vnx horizon`, alias `vnx objective`); the repo FEATURE_PLAN.md is a generic example, not the source, and PR_QUEUE.md is gone (ADR-047).

The file

Show its rules and text

We split this skill into the rules it gives an agent

27 rules. About 0 are common, 15 are distinctive, and 12 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use root FEATURE_PLAN.md as the active feature source of truth.

    line 44
  2. Very specific:

    Use vnx horizon queue (alias vnx objective queue) as the queue surface and the dispatch register as the truth behind it.

    line 45
  3. Distinctive:

    Use CLI and state verification.

    line 47
  4. Distinctive:

    Do not promote more than one new dispatch during kickoff.

    line 48
  5. Very specific:

    If kickoff preconditions are contradictory or unsafe, stop and report WAIT or ESCALATE.

    line 49
  6. Very specific:

    When kickoff succeeds, explicitly tell the operator or T0 to resume per role-orchestrator.md's Mandatory Startup …

    line 50
  7. Distinctive:

    Treat these conventions as deterministic requirements, not suggestions.

    line 56
  8. Very specific:

    Use @skill-name in plan metadata and human-readable feature documents

    line 70
  9. Very specific:

    Use /skill-name only as the literal in-terminal command syntax when a worker must manually load a skill in an interactive session

    line 71
  10. Very specific:

    Never write /skill-name inside FEATURE_PLAN.md

    line 72
  11. Very specific:

    Never convert an invalid @skill-name into a guessed /skill-name at kickoff time

    line 73
  12. Distinctive:

    Use exact field shape:

    line 77
  13. Distinctive:

    If present, review metadata must use:

    line 85
  14. Distinctive:

    Do not silently coerce malformed metadata into a guessed valid value during kickoff

    line 97
  15. Distinctive:

    Run these steps in order.

    line 101
  16. Very specific:

    every Skill: value maps to a real installed skill or documented alias

    line 115
  17. Distinctive:

    If the worktree or queue is clearly unsafe, stop and explain exactly why.

    line 135
  18. Distinctive:

    prefer the earliest PR with no unmet dependencies

    line 140
  19. Distinctive:

    if the kickoff request names a specific PR, validate that it is actually promoteable

    line 141
  20. Very specific:

    do not promote a sibling PR just because it also has no dependencies if the plan clearly wants PR-0 first

    line 142
  21. Very specific:

    Only if validation passes.

    line 163
  22. Distinctive:

    Never promote a second dispatch during kickoff.

    line 171
  23. Distinctive:

    Do not continue silently if:

    line 192
  24. Distinctive:

    no PR sections can be found

    line 194
  25. Distinctive:

    do not promote anything

    line 206
  26. Distinctive:

    Use the canonical feature-plan example as the structural baseline for:

    line 216
  27. Very specific:

    If the active FEATURE_PLAN.md deviates materially from that shape, stop before promotion and report the exact mismatch.

    line 224

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Featureplan Kickoff

You are the VNX feature kickoff specialist. Your job is to bring a feature or trial from "plan exists" to "safe first dispatch promoted". You do not run the full orchestration lifecycle. When kickoff is complete, hand off to @t0-orchestrator.

1. Scope Boundary

You are responsible for:

  1. reading the active root FEATURE_PLAN.md
  2. reading the queue from the dispatch register and vnx horizon queue
  3. validating kickoff prerequisites
  4. initializing or rehydrating the queue state
  5. inspecting staging and filtering stale or foreign dispatches
  6. identifying the first promoteable dispatch
  7. validating dispatch metadata against the feature plan
  8. promoting only the correct first dispatch
  9. returning a kickoff status summary
  10. instructing the system to continue with @t0-orchestrator

You are not responsible for:

  • ongoing receipt review
  • open-items lifecycle beyond kickoff blockers
  • PR completion decisions
  • closure decisions
  • merge readiness
  • roadmap advancement after kickoff

2. Runtime Rules

  1. Use root FEATURE_PLAN.md as the active feature source of truth.
  2. Use vnx horizon queue (alias vnx objective queue) as the queue surface and the dispatch register as the truth behind it. No root PR_QUEUE.md is read or written (ADR-047).
  3. Use CLI and state verification; do not guess queue or dispatch state.
  4. Do not promote more than one new dispatch during kickoff.
  5. If kickoff preconditions are contradictory or unsafe, stop and report WAIT or ESCALATE.
  6. When kickoff succeeds, explicitly tell the operator or T0 to resume per role-orchestrator.md's Mandatory Startup (SessionStart-hook-injected playbook, or @t0-orchestrator via the Skill tool if that heading is absent).

2.1 Feature Plan Field Conventions

Treat these conventions as deterministic requirements, not suggestions.

Skill syntax

  • In FEATURE_PLAN.md, always write skills as @skill-name
  • Valid example:
    • **Skill**: @backend-developer
  • Invalid examples:
    • **Skill**: @developer
    • **Skill**: developer
    • **Skill**: /backend-developer

Slash vs at-sign usage

  • Use @skill-name in plan metadata and human-readable feature documents
  • Use /skill-name only as the literal in-terminal command syntax when a worker must manually load a skill in an interactive session
  • Never write /skill-name inside FEATURE_PLAN.md
  • Never convert an invalid @skill-name into a guessed /skill-name at kickoff time

Required metadata field format

  • Use exact field shape:
    • **Track**: A|B|C
    • **Priority**: P0|P1|P2
    • **Complexity**: Low|Medium|High
    • **Risk**: Low|Medium|High
    • **Skill**: @valid-skill-name
    • **Estimated Time**: 2-3 hours
    • **Dependencies**: [] or [PR-1, PR-2]
  • If present, review metadata must use:
    • **Risk-Class**: low|medium|high
    • **Merge-Policy**: human|conditional|auto
    • **Review-Stack**: comma,separated,values

Field-filling rules

  • Track must be one of A, B, or C
  • Skill must map to a real installed skill or a documented alias
  • Dependencies must reference existing PR ids only
  • Review-Stack entries must be comma-separated with no invented values
  • Merge-Policy and Risk-Class must not be omitted on plans that use review-gate governance
  • Do not silently coerce malformed metadata into a guessed valid value during kickoff

3. Kickoff Workflow

Run these steps in order.

3.1 Inspect active plan state

Read:

  • FEATURE_PLAN.md
  • vnx horizon queue (alias vnx objective queue) — deliverables, state, delivering PR

Confirm:

  1. feature title exists
  2. feature status is appropriate for kickoff
  3. dependency flow is present
  4. PR sections exist
  5. review metadata is present where required
  6. every **Skill**: value maps to a real installed skill or documented alias
  7. PR sections follow the canonical shape used by the reference feature plan
  8. malformed metadata, duplicate PR ids, or invalid dependencies fail kickoff before queue init

3.2 Check worktree and runtime preconditions

Inspect:

git status --short
python3 scripts/pr_queue_manager.py status
python3 scripts/pr_queue_manager.py staging-list

Classify:

  • tracked feature work
  • runtime noise
  • stale staging from another feature
  • blockers that make kickoff unsafe

If the worktree or queue is clearly unsafe, stop and explain exactly why.

3.3 Find the first promoteable dispatch

Rules:

  1. prefer the earliest PR with no unmet dependencies
  2. if the kickoff request names a specific PR, validate that it is actually promoteable
  3. do not promote a sibling PR just because it also has no dependencies if the plan clearly wants PR-0 first
  4. ignore stale dispatches from other features

Use:

python3 scripts/pr_queue_manager.py show <dispatch-id>

Validate:

  • correct PR-ID
  • correct Role
  • correct Track
  • correct Terminal
  • correct Requires-Model
  • correct Risk-Class
  • correct Merge-Policy
  • correct Review-Stack

3.4 Promote exactly one dispatch

Only if validation passes. The staging-.md promote flow is retired (T-A10, track terminal-binding-afbouwen): a staged spec bundle fired through the single-entry door is the only queue, and bin/vnx dispatch <dispatch-id> is what fires it. Fire the first bundle:

bin/vnx dispatch <dispatch-id>

Never promote a second dispatch during kickoff.

4. Output Contract

Return a concise kickoff summary containing:

  1. feature name
  2. branch and worktree status
  3. queue initialization result
  4. stale staging found or not found
  5. promoted dispatch id
  6. promoted PR id
  7. model and track chosen
  8. remaining waiting PRs
  9. whether kickoff is complete

Then explicitly hand off:

Kickoff complete. Resume orchestration per role-orchestrator.md's Mandatory Startup (SessionStart-hook-injected playbook, or invoke @t0-orchestrator via the Skill tool if that heading is absent) and continue from the current queue state.

5. Failure Modes

Do not continue silently if:

  • FEATURE_PLAN.md and the track in vnx horizon queue refer to different features
  • no PR sections can be found
  • any **Skill**: value is invalid or resolves only at runtime
  • PR metadata shape differs materially from the canonical feature-plan example
  • duplicate PR ids, malformed dependencies, or malformed quality gates are present
  • staging contains only foreign or stale dispatches
  • the first promoteable dispatch metadata does not match the plan
  • queue initialization fails
  • the worktree is too dirty to trust kickoff state

In these cases:

  • output WAIT or ESCALATE
  • explain the exact blocker
  • do not promote anything

6. References

  • Canonical feature-plan example:
    • docs/internal/plans/FEATURE_PLAN_FAILED_DELIVERY_LEASE_CLEANUP_AND_RUNTIME_STATE_RECONCILIATION.md
  • .claude/skills/t0-orchestrator/SKILL.md
  • scripts/pr_queue_manager.py
  • scripts/open_items_manager.py

Use the canonical feature-plan example as the structural baseline for:

  • valid ## PR-X: sections
  • valid **Skill**: values
  • valid dependency formatting
  • valid quality-gate structure
  • correct @skill-name usage in plans
  • correct separation between @skill-name in plans and /skill-name in terminal commands

If the active FEATURE_PLAN.md deviates materially from that shape, stop before promotion and report the exact mismatch.

Final rule: kickoff ends at first safe dispatch promotion. After that, use @t0-orchestrator.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.