From 208ac9ead2a0f4daeefa2753d19a4bb9e668e82b Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Sun, 8 Mar 2026 06:03:04 +0800 Subject: [PATCH] feat(plan): align create-plan with plan-tooling workflow --- skills/workflows/plan/create-plan/SKILL.md | 53 +++++++++++++++++-- .../tests/test_workflows_plan_create_plan.py | 22 ++++++++ 2 files changed, 72 insertions(+), 3 deletions(-) diff --git a/skills/workflows/plan/create-plan/SKILL.md b/skills/workflows/plan/create-plan/SKILL.md index 19fc00f7..4ec5ce61 100644 --- a/skills/workflows/plan/create-plan/SKILL.md +++ b/skills/workflows/plan/create-plan/SKILL.md @@ -16,7 +16,8 @@ Prereqs: - User is asking for an implementation plan (not asking you to build it yet). - You can read enough repo context to plan safely (or the user provides constraints). -- `plan-tooling` available on `PATH` for linting (install via `brew install nils-cli`). +- `plan-tooling` available on `PATH` for linting/parsing/splitting (`validate`, `to-json`, `batches`, `split-prs`; install via + `brew install nils-cli`). Inputs: @@ -57,9 +58,12 @@ Failure modes: 1. Write the plan (do not implement) - Use sprints/phases that each produce a demoable/testable increment. -- Break work into atomic, independently testable tasks. +- Treat sprints as sequential integration gates; do not imply cross-sprint execution parallelism. +- Break work into atomic, independently testable tasks with explicit dependencies when execution order matters. +- Prefer within-sprint parallel lanes only when file overlap and validation scope stay manageable. - Include file paths whenever you can be specific. - Include a validation step per sprint (commands, checks, expected outcomes). +- Fill `Complexity` when it materially affects batching/splitting or when a task looks oversized. 1. Save the plan file @@ -71,9 +75,47 @@ Failure modes: - Run: `plan-tooling validate --file docs/plans/-plan.md` - If it fails: tighten tasks (missing fields, placeholders, unclear validations) until it passes. +1. Run an executability + grouping pass (mandatory) + +- Default grouping policy for this skill: + - If the user did not explicitly request grouping behavior, validate with metadata-first auto + (`--strategy auto --default-pr-grouping group`). +- For each sprint, run: + + ```bash + plan-tooling to-json --file docs/plans/-plan.md --sprint + plan-tooling batches --file docs/plans/-plan.md --sprint + plan-tooling split-prs --file docs/plans/-plan.md --scope sprint \ + --sprint --strategy auto --default-pr-grouping group --format json + ``` + +- If the user explicitly requests deterministic/manual grouping: + - Provide explicit mapping for every task: `--pr-group =` (repeatable). + - Validate with: + + ```bash + plan-tooling split-prs --file docs/plans/-plan.md --scope sprint --sprint --pr-grouping group --strategy deterministic --pr-group ... --format json + ``` + +- If the user explicitly requests one shared lane per sprint: + - Validate with: + + ```bash + plan-tooling split-prs --file docs/plans/-plan.md --scope sprint --sprint --pr-grouping per-sprint --strategy deterministic --format json + ``` + +- When you add sprint metadata for grouping/parallelism, use exact case-sensitive labels: + - `**PR grouping intent**: per-sprint|group` + - `**Execution Profile**: serial|parallel-xN` +- Keep metadata coherent: + - If `PR grouping intent` is `per-sprint`, do not declare parallel width `>1`. + - If planning multi-lane parallel execution, set `PR grouping intent` to `group`. +- After each adjustment, rerun `plan-tooling validate` and the relevant `split-prs` command until the plan is stable and executable. + 1. Review “gotchas” -- After saving, add/adjust a “Risks & gotchas” section: ambiguity, dependencies, migrations, rollout, backwards compatibility, and rollback. +- After saving, add/adjust a “Risks & gotchas” section: ambiguity, dependency bottlenecks, same-batch overlap hotspots, migrations, rollout, + backwards compatibility, and rollback. ## Plan Template @@ -81,6 +123,11 @@ Shared template (single source of truth): - `skills/workflows/plan/_shared/assets/plan-template.md` +When a plan needs explicit grouping/parallelism metadata, extend each sprint with these exact labels: + +- `**PR grouping intent**: per-sprint|group` +- `**Execution Profile**: serial|parallel-xN` + Optional scaffold helper (creates a placeholder plan; fill it before linting): - `plan-tooling scaffold --slug --title ""` diff --git a/skills/workflows/plan/create-plan/tests/test_workflows_plan_create_plan.py b/skills/workflows/plan/create-plan/tests/test_workflows_plan_create_plan.py index 03493ef2..b4518d9d 100644 --- a/skills/workflows/plan/create-plan/tests/test_workflows_plan_create_plan.py +++ b/skills/workflows/plan/create-plan/tests/test_workflows_plan_create_plan.py @@ -8,3 +8,25 @@ def test_workflows_plan_create_plan_contract() -> None: skill_root = Path(__file__).resolve().parents[1] assert_skill_contract(skill_root) + + +def _skill_md_text() -> str: + return (Path(__file__).resolve().parents[1] / "SKILL.md").read_text(encoding="utf-8") + + +def test_create_plan_requires_plan_tooling_executability_pass() -> None: + text = _skill_md_text() + assert "plan-tooling to-json --file docs/plans/-plan.md --sprint " in text + assert "plan-tooling batches --file docs/plans/-plan.md --sprint " in text + assert "--strategy auto --default-pr-grouping group --format json" in text + assert "--pr-grouping group --strategy deterministic --pr-group ... --format json" in text + assert "--pr-grouping per-sprint --strategy deterministic --format json" in text + + +def test_create_plan_documents_grouping_metadata_and_cross_sprint_policy() -> None: + text = _skill_md_text() + assert "Treat sprints as sequential integration gates" in text + assert "do not imply cross-sprint execution parallelism." in text.lower() + assert "`**PR grouping intent**: per-sprint|group`" in text + assert "`**Execution Profile**: serial|parallel-xN`" in text + assert "If `PR grouping intent` is `per-sprint`, do not declare parallel width `>1`." in text