From aaa3b3b6c91b776da4fdcb61defe498a73f98664 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86gir=20M=C3=A1ni=20Hauksson?= <54936225+sourcehawk@users.noreply.github.com> Date: Fri, 29 May 2026 16:26:20 +0200 Subject: [PATCH] refactor(skills): move state files to docs/superpowers/states/ The orchestration state file lived inside docs/superpowers/plans/, co-located with the plan. Give it its own docs/superpowers/states/ directory so state is a distinct namespace from the plan it tracks. Lifecycle is unchanged: state stays scratch, deleted in the orchestrator's last commit when the feature ships. Only the path and the "beside the plan" wording change. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 3 ++- skills/developing-a-feature/SKILL.md | 2 +- skills/fanning-out-with-worktrees/SKILL.md | 2 +- skills/planning-a-feature/SKILL.md | 2 +- skills/reviewing-feature-progress/SKILL.md | 2 +- templates/project-CLAUDE.md | 2 +- 6 files changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 34460b0..25c3295 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,8 @@ This plugin depends on the [superpowers](https://github.com/obra/superpowers) pl skills directly: `superpowers:brainstorming`, `superpowers:writing-plans`, `superpowers:test-driven-development`, `superpowers:verification-before-completion`, and `superpowers:dispatching-parallel-agents`. It also uses superpowers' `docs/superpowers/{specs,plans}/` -path convention. Install superpowers first. +path convention, adding a sibling `docs/superpowers/states/` directory for orchestration state files. +Install superpowers first. The skills also assume the [`gh`](https://cli.github.com/) CLI is installed and authenticated. diff --git a/skills/developing-a-feature/SKILL.md b/skills/developing-a-feature/SKILL.md index 6a9b7d0..f8115b9 100644 --- a/skills/developing-a-feature/SKILL.md +++ b/skills/developing-a-feature/SKILL.md @@ -17,7 +17,7 @@ ad-hoc fixes — those go directly through `superpowers:test-driven-development` ### 1. Read the state file first, then plan + spec -The orchestration state file (`docs/superpowers/plans/--state.md`, created by `feature-dev-workflow:planning-a-feature` Step 8) +The orchestration state file (`docs/superpowers/states/--state.md`, created by `feature-dev-workflow:planning-a-feature` Step 8) is the entry point — it points at the plan, the spec, the tracking issue, the open PRs, the worktrees, and any bubble-up concerns logged so far. Read it in full before anything else; follow the file's "Resume checklist" section to verify reality against the recorded state. diff --git a/skills/fanning-out-with-worktrees/SKILL.md b/skills/fanning-out-with-worktrees/SKILL.md index a5ca1bf..4983476 100644 --- a/skills/fanning-out-with-worktrees/SKILL.md +++ b/skills/fanning-out-with-worktrees/SKILL.md @@ -16,7 +16,7 @@ When you're the orchestrator for multi-PR feature work and these prerequisites a invoking this skill). - The plan (`docs/superpowers/plans/--plan.md`) has a `## Contracts` section with a Realization strategy per row. -- The state file (`docs/superpowers/plans/--state.md`) has rows for each sub-issue. +- The state file (`docs/superpowers/states/--state.md`) has rows for each sub-issue. Skip for single-PR features — there's no fan-out, just one branch off main. diff --git a/skills/planning-a-feature/SKILL.md b/skills/planning-a-feature/SKILL.md index c1c6e14..106617a 100644 --- a/skills/planning-a-feature/SKILL.md +++ b/skills/planning-a-feature/SKILL.md @@ -159,7 +159,7 @@ single "yes to all": a wall of bodies gets rubber-stamped instead of read. ### 8. Initialize the orchestration state file -Before handing off, create `docs/superpowers/plans/YYYY-MM-DD--state.md` from +Before handing off, create `docs/superpowers/states/YYYY-MM-DD--state.md` from `${CLAUDE_PLUGIN_ROOT}/skills/planning-a-feature/templates/feature-state.md`. This is the **orchestration state** — phases, PRs, worktrees, contract realization, bubble-up log. It's what a future Claude session reads first to resume the work without a massive user prompt. diff --git a/skills/reviewing-feature-progress/SKILL.md b/skills/reviewing-feature-progress/SKILL.md index dac9091..9e3cf55 100644 --- a/skills/reviewing-feature-progress/SKILL.md +++ b/skills/reviewing-feature-progress/SKILL.md @@ -34,7 +34,7 @@ accumulates silently across waves; this skill catches it at the boundary. Open these in order: -- The state file (`docs/superpowers/plans/--state.md`). +- The state file (`docs/superpowers/states/--state.md`). - The plan (`docs/superpowers/plans/--plan.md`), with focus on the `## Contracts` section and the PR-by-PR breakdown. - The spec (`docs/superpowers/specs/--design.md`), with focus on goals + non-goals. diff --git a/templates/project-CLAUDE.md b/templates/project-CLAUDE.md index 1369e02..9520a14 100644 --- a/templates/project-CLAUDE.md +++ b/templates/project-CLAUDE.md @@ -73,4 +73,4 @@ so sessions don't have to guess: - **Never `--no-verify`, never `git add -A` / `git add .`.** Stage by name; pre-commit hooks exist for a reason. - **No GitHub mutation without a fresh confirmation against the specific body about to land.** Paste the body inline, name the target, wait for an explicit yes. - **PR titles outlive lifecycle state.** No `wip` / `draft` / `plan` suffixes; GitHub's chip carries lifecycle. -- **Specs in `docs/superpowers/specs/` are durable; plans in `docs/superpowers/plans/` are scratch** (deleted once the plan ships). State files live beside the plan. +- **Specs in `docs/superpowers/specs/` are durable; plans in `docs/superpowers/plans/` are scratch** (deleted once the plan ships). State files live in `docs/superpowers/states/` and share the plan's scratch lifecycle.