nils-plan-tooling 0.5.5

CLI crate for nils-plan-tooling in the nils-cli workspace.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# 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> [--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 per-sprint`: one shared `pr_group` per sprint (`s<n>`).
  - `--pr-grouping group`: pass `--pr-group` for every selected task.
- auto mode:
  - scoring inputs are `Complexity`, dependency topology, and `Location` overlap.
  - in `pr-grouping=group`, `--pr-group` mappings are optional pins; remaining tasks are auto-grouped.
  - when sprint metadata provides `Execution Profile` parallel width hints, auto grouping targets that lane count (deterministic fallback merges apply when needed).
  - `pr-grouping=per-sprint` keeps one shared group per sprint (`s<n>`).
  - 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 --pr-grouping group --strategy auto --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.

## 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)
- [Migration runbook](docs/runbooks/split-prs-migration.md)