# 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
```text
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
```bash
# 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
```
## Template
- Plan template: `crates/plan-tooling/plan-template.md`.
## Exit codes
- `0`: success and help output.
- `1`: validation or runtime errors.
- `2`: usage errors.
## Docs
- [Docs index](docs/README.md)
- [split-prs contract v2](docs/specs/split-prs-contract-v2.md)