plan-tooling

Overview

plan-tooling works with Plan Format v1 markdown files. It can parse plans to JSON, validate plan files, compute dependency batches for a sprint, scaffold new plans, and generate task-to-PR split grouping primitives in deterministic or auto strategy modes. Runtime execution metadata for orchestration is materialized by plan-issue-cli from split results plus parsed plan content.

Usage

Usage:
  plan-tooling <command> [args]

Commands:
  to-json   Parse a plan markdown file into a stable JSON schema
  validate  Lint plan markdown files
  batches   Compute dependency layers (parallel batches) for a sprint
  split-prs Build task-to-PR split records (deterministic/auto)
  scaffold  Create a new plan from template
  completion Export shell completion script
  help      Display help message

Help:
  plan-tooling help
  plan-tooling --help

Commands

to-json

to-json --file <plan.md> [--sprint <n>] [--pretty]: Parse a plan file and output JSON.

validate

validate [--file <path>]... [--format text|json]: Validate plan files. With no --file, scans tracked docs/plans/*-plan.md files.

batches

batches --file <plan.md> --sprint <n> [--format json|text]: Compute dependency batches for a sprint.

split-prs

split-prs --file <plan.md> --scope <plan|sprint> [--sprint <n>] [--pr-grouping <per-sprint|group>] [--default-pr-grouping <per-sprint|group>] [--pr-group <task-or-plan-id>=<group>]... [--strategy deterministic|auto] [--explain] [--format json|tsv]
compatibility flags accepted by the CLI parser: --owner-prefix, --branch-prefix, --worktree-prefix
value options accept both --key value and --key=value.
--owner-prefix, --branch-prefix, and --worktree-prefix are accepted for compatibility with older automation, but v2 split-prs output is grouping-only (task_id, summary, pr_group).
deterministic mode:
- --pr-grouping is required.
- --pr-grouping per-sprint: one shared pr_group per sprint (s<n>).
- --pr-grouping group: pass --pr-group for every selected task.
auto mode:
- --pr-grouping is rejected.
- sprint metadata PR grouping intent is authoritative when present.
- --default-pr-grouping fills gaps only for sprints that omit grouping intent.
- if a selected sprint has neither metadata nor --default-pr-grouping, the command fails.
- scoring inputs are Complexity, dependency topology, and Location overlap.
- for auto-resolved group sprints, --pr-group mappings are optional pins and remaining tasks are auto-grouped.
- pins targeting auto-resolved per-sprint sprints are rejected.
- when sprint metadata provides Execution Profile parallel width hints, auto grouping targets that lane count (deterministic fallback merges apply when needed).
- parser metadata gates are strict; non-canonical field names (for example PR Grouping Intent) are rejected.
- --explain includes pr_grouping_intent_source (plan-metadata, default-pr-grouping, or command-pr-grouping) for traceability.
- ordering and tie-breakers stay deterministic (Task N.M, then SxTy, then lexical summary).
- emitted grouping primitives (task_id, summary, pr_group, optional --explain) are consumed by plan-issue runtime materialization and runtime-truth validation.
deterministic examples:
- split-prs --file docs/plans/example-plan.md --scope sprint --sprint 1 --pr-grouping per-sprint --format tsv
- split-prs --file docs/plans/example-plan.md --scope sprint --sprint 2 --pr-grouping group --pr-group S2T1=isolated --pr-group S2T2=shared --pr-group S2T3=shared --format json
auto example:
- split-prs --file docs/plans/example-plan.md --scope sprint --sprint 2 --strategy auto --default-pr-grouping group --format json
rollback switchback:
- if auto rollout is unhealthy, pin orchestration calls to --strategy deterministic until follow-up fixes land.

scaffold

scaffold --slug <kebab-case> [--title <title>] [--force]: Write to docs/plans/<slug>-plan.md (or <slug>.md if the slug already ends with -plan).
scaffold --file <path> [--title <title>] [--force]: Write to a specific -plan.md path.

completion

completion <bash|zsh>: Export completion script for shell integration.

Sprint metadata hints (Plan markdown)

Supported sprint metadata fields are case-sensitive and parser-enforced:
- **PR grouping intent**: per-sprint|group
- **Execution Profile**: serial|parallel-xN
Parse flows fail fast on invalid metadata keys/values (to-json, split-prs, batches).
validate enforces metadata coherence by default:
- if one metadata field is present, both must be present.
- PR grouping intent=per-sprint cannot be combined with parallel width >1.

Quick examples

# Parse one plan to JSON
plan-tooling to-json --file docs/plans/example-plan.md --pretty

# Validate all tracked plan docs (default discovery)
plan-tooling validate

# Compute sprint batches in text mode
plan-tooling batches --file docs/plans/example-plan.md --sprint 2 --format text

# Split sprint tasks with deterministic groups
plan-tooling split-prs \
  --file docs/plans/example-plan.md \
  --scope sprint \
  --sprint 2 \
  --pr-grouping group \
  --pr-group S2T1=isolated \
  --pr-group S2T2=shared \
  --strategy deterministic \
  --format json

# Export completion
plan-tooling completion zsh > completions/zsh/_plan-tooling

nils-plan-tooling 0.6.0