feature-resolve
Internal helper invoked only by other skills in this plugin (feature-storm, feature-design, feature-plan, feature-implement) as their resolution step. Determines the correct features/feature-vN-<descr
Файлы1
Открыть в GitHubSKILL.mdskills/feature-resolve/SKILL.md
GitHubfeature-resolve
Invoked as the resolution step of another feature-* skill in this plugin. Computes which features/feature-v<N>-<description>/ folder the caller should write into, ensures the folder and tracker file exist, and returns the resolution as a structured block for the caller to parse.
You are running inline, inside the calling skill's own turn. The Skill tool loads these instructions into the caller's context — it does not delegate to a subagent. There is no second agent on the other side of this: the model reading this text is the same model that will carry on with the caller's remaining steps once the resolution block is out. Read every "the caller" below as "you, a few steps from now".
The point of externalising this is that all four feature skills need identical answers to "what folder, what version, what stage file?". Putting the procedure here means the four skills stay perfectly aligned and a rule change lands in exactly one place.
Input
The caller passes a comma-separated argument string with these slots:
stage=<storm|design|plan|implement>— required. The calling skill's stage slug.version=<N>— optional. An explicit feature version the user named (e.g. via$ARGUMENTS).description=<phrase>— optional. A new feature's description. Only consulted when creating a new feature folder; ignored (with a warning) when continuing into an existing folder.
Examples:
stage=design
stage=plan, version=3
stage=design, description=Add Reminders
stage=storm, version=4, description=Payments checkout
If stage= is missing or names a slug other than the four allowed values, stop with a one-line error and ask the caller to retry. Do not guess from context.
Step 1 — Locate or create features/ in the project root
Run test -d features in the current working directory.
- If it does not exist, run
mkdir -p featuresto create it. - Never write
features/anywhere other than the project root (cwd). Do not migrate or copy fromdocs/—docs/is legacy reference material; new artifacts always live underfeatures/starting at v1.
Step 2 — Scan for existing feature folders
Glob features/ for directories matching feature-v<N>-*:
find features -maxdepth 1 -type d -iname 'feature-v[0-9]*-*'
For each match, parse:
N— the integer version (numeric compare, not lexicographic —v10>v9).description— everything afterfeature-v<N>-, preserved verbatim (this is the authoritative description for the feature).present_stages— set of stages whose file exists in the folder. A stage file is namedfeature-<stage>-v<N>-<description>.md. Check for each ofstorm,design,plan,implement.
Build the map {N → (folder_path, description, present_stages)}. Identify N_max (the highest existing version) and latest (the entry for N_max). If the map is empty, treat N_max as 0 and latest as absent.
Step 3 — Resolve mode, target version, and target folder
Apply the rules in this priority order. The first matching rule wins.
Rule A — Explicit version=<N> argument. The user named a specific feature.
- If
features/feature-v<N>-*does not exist:- For
stage=stormorstage=design: this is a forward reference. IfN≠N_max + 1, stop with an error — versions must be contiguous, no gaps. IfN=N_max + 1, treat as create-new at versionN(description is required, validate per Step 4). - For
stage=planorstage=implement: stop with an error — these stages cannot create a new feature folder; they need an existing folder with the prerequisite stage file. Tell the caller to specify an existing version or run the earlier stage first.
- For
- If
features/feature-v<N>-<desc>/exists:- If the stage file already exists in that folder: ask the user via
AskUserQuestionwhether to overwrite (revisions are explicitly disabled in this plugin's design — overwriting is the only path) or cancel. If they cancel, stop. If they overwrite, proceed with mode = continue-existing. - If the stage file does not exist in that folder: for
plan/implement, confirm the prerequisite stage file is present (design for plan; plan for implement). If the prerequisite is missing, stop with an error naming the missing prerequisite. Otherwise proceed with mode = continue-existing. - If a
description=argument was also provided and it conflicts with the folder's description, ignore the user's value and warn in the outputnotesfield that the folder name is authoritative.
- If the stage file already exists in that folder: ask the user via
Rule B — No version= argument, and no existing feature folders. This is the first ever feature in this repo.
- Allowed only for
stage=stormorstage=design—planandimplementneed a prerequisite and there is none. For plan/implement, stop with an error: "No feature folders exist underfeatures/. Run /feature-design (and optionally /feature-storm) first." - Mode = create-new, version =
1. Description is required; validate per Step 4. Ifdescription=was not provided, stop with a one-line error asking the caller to re-invoke with a description.
Rule C — No version= argument, the latest folder LACKS this stage's file. The latest feature is still in progress on this stage.
Guard — a missing stage file may mean the stage was skipped, not left pending. Check what else the latest folder holds before treating it as in-progress. For stage=storm and stage=design only (plan and implement cannot create a new feature, so the guard does not apply to them), fall straight through to Rule D — create-new at N_max + 1, without asking — when either of these holds:
- The latest folder contains a later stage's file —
design,planorimplementwhenstage=storm;planorimplementwhenstage=design. That feature started cold at a later stage, so its earlier stage was skipped rather than left pending, and continuing this stage into it is never the right answer. Expect this after any feature that began at/feature-design. - The latest folder contains no stage file at all and no
feature-v<N>-tracker.html, and adescription=differing from the folder's was provided. A folder this resolver created always carries a seeded tracker, so one with neither is out-of-band — a stray or hand-made directory, not a feature awaiting its first stage.
In both cases there is exactly one sensible outcome, so the AskUserQuestion below would cost a round-trip and buy nothing. Record what happened in notes (e.g. latest v<N_max> skipped <stage> — created new feature instead) so the caller can surface the reasoning. Everything below applies only when the guard did not fire.
- For
plan/implement: also confirm the prerequisite stage file exists inlatest. If not, stop with an error naming the missing prerequisite. - If
description=was provided and matcheslatest.description, proceed with mode = continue-existing, version =N_max, folder =latest.folder_path. - If
description=was provided and differs fromlatest.description: ask viaAskUserQuestion— "Continue intofeature-v<N_max>-<latest.description>/(folder name wins) or start a new featurefeature-v<N_max+1>-<new-desc>/?" Honor the choice. - If
description=was not provided, proceed with mode = continue-existing, version =N_max, folder =latest.folder_path, description =latest.description.
Rule D — No version= argument, the latest folder ALREADY HAS this stage's file.
- For
stage=stormorstage=design: mode = create-new, version =N_max + 1. Description is required; validate per Step 4. Ifdescription=was not provided, stop with a one-line error asking the caller to re-invoke with a description. - For
stage=planorstage=implement: ambiguous (the stage is "done" in the latest folder, and these stages can't make a new feature). Ask the user viaAskUserQuestionwhether to overwrite the existing stage file inlatestor specify an older version viaversion=. Do not pick for them.
Record the resolved mode, version, folder_path, and description.
Step 4 — Validate description (create-new only)
For mode = continue-existing, skip this step — the description came from the folder name and is already valid.
For mode = create-new, the description must meet:
- Word count ≤ 10. Count whitespace-separated tokens of the user-provided phrase. If more than 10, stop with an error: "Description must be 10 words or fewer; got <N>: <phrase>". Do not truncate silently.
- Filename-safe. Strip leading/trailing whitespace, collapse internal whitespace runs to single spaces, then replace each space with
-. Preserve the user's case (so "Add Reminders" → "Add-Reminders", consistent with the examplefeature-plan-v2-Reminders). Reject if the result contains characters outside[A-Za-z0-9._-]after the transformation — stop and tell the caller to simplify the description. - Non-empty. A whitespace-only or zero-length description is rejected.
The validated, hyphenated description becomes the canonical description for this feature and goes into the folder name.
Step 5 — Create the feature folder if needed
If mode = create-new, run mkdir -p features/feature-v<N>-<description> (relative to cwd). Record the absolute folder path for the output block (resolve via pwd if helpful).
If mode = continue-existing, the folder already exists from Step 2 — no creation needed.
Step 6 — Seed the tracker if missing
The tracker file path is <folder_path>/feature-v<N>-tracker.html.
If it already exists, do nothing — the caller (or a previous stage) populated it.
If it does not exist, copy the plugin's template into place. Locate the template by searching the plugin install location:
find ~ -path "*dev-skills*/templates/feature-tracker.html" 2>/dev/null- First, try the running plugin's own copy — no search needed. This skill's base directory was announced when it was invoked (
…/dev-skills/<version>/skills/feature-resolve), so the template sits two levels up at<base>/../../templates/feature-tracker.html. If that file exists, use it: it is by definition the template matching the running plugin version. - Otherwise run the
findabove. The*dev-skills*form is deliberate — an installed plugin lives at…/plugins/cache/<marketplace>/dev-skills/<version>/templates/, and the narrower*/dev-skills/templates/…pattern silently misses it, matching only a working clone. - If exactly one match:
cp <match> <folder_path>/feature-v<N>-tracker.html. - If multiple matches: prefer one under a
plugins/cache/path (an installed plugin) at the highest version over a working clone. Do not key this on~/.claude/— a profile directory can live elsewhere (e.g. synced under~/Library/Mobile Documents/), and several versions are normally cached side by side. Ask the user viaAskUserQuestiononly if a genuine tie remains. - If zero matches: do not fail the whole resolution — emit a note in the output (
tracker_seed: skipped — template not found) and let the caller decide whether to populate the tracker from scratch.
- First, try the running plugin's own copy — no search needed. This skill's base directory was announced when it was invoked (
Do not substitute any tokens ({{FEATURE_VERSION}}, etc.) — token replacement is the calling skill's responsibility. Tracker file lives as a raw template until each stage fills in its own section.
Step 7 — Output the resolution block
Echo a single block to chat. Use exactly this shape so the caller can parse it line-by-line:
feature-resolve result
---
mode: <create-new | continue-existing>
version: <N>
description: <hyphenated description, exactly as it appears in the folder name>
feature_folder: <absolute path>
stage_file: <absolute path to features/feature-vN-<desc>/feature-<stage>-vN-<desc>.md>
tracker_file: <absolute path to features/feature-vN-<desc>/feature-vN-tracker.html>
prereq_file: <absolute path to the prerequisite stage file, or "n/a" if none>
notes: <single line — overwrites authorised, description conflicts ignored, tracker seeded/skipped, etc.; or "none">
The stage_file is the path the caller will write to. The file itself must not exist yet for mode = create-new and may or may not exist for continue-existing (it exists only when the user authorised an overwrite in Step 3). Either way, this skill does not touch it.
prereq_file is set when the caller is plan or implement — it points at the design (for plan) or plan (for implement) file the caller should read. For storm and design, set prereq_file: n/a.
Do not end your turn here. Nothing is waiting to pick this block up — you were loaded inline, so emitting the block is not a hand-off and there is no "return" to make. Emit it, then continue immediately, in the same turn, with the calling skill's next step: feature-storm Step 3, feature-design Step 3, feature-plan Step 2, feature-implement Step 2. The block stays in context as the record every later step reads its paths from.
The only paths that do end the turn are the explicit failure exits above: a missing or invalid stage=, a non-contiguous version=, a missing prerequisite stage file, an invalid description, or a user cancelling the overwrite prompt in Step 3. A successful resolution never ends the turn.
Constraints (non-negotiable)
- Never create or edit a stage
.mdfile. Only the caller writes those. This skill creates the folder and (optionally) seeds the tracker html. - Never delete anything. No
rm, no overwriting existing folders, no removing tracker files. If an overwrite is authorised in Step 3 for an existing stage file, this skill still does not touch it — it just reports the path and lets the caller overwrite. - Folder name is authoritative for description. When continuing into an existing folder, the folder's description wins; any
description=argument that disagrees is reported innotesand discarded. - Versions are contiguous. No gaps allowed when creating new —
Nmust equalN_max + 1. No minor versioning (v1.0,v1.1) under any circumstances. - No symlinks. When copying the tracker template, always copy — never
ln -s. - Stop and ask, don't invent. Any ambiguity (overwrite vs. new feature, multiple template matches, description mismatch on continue) goes through
AskUserQuestion. Never silently pick a path the caller didn't authorise. - Output format is the contract. The block in Step 7 is read back verbatim by the caller's later steps — which are your own later steps, since you run inline; do not add prose, headers, or extra fields. The exact keys and order matter.
- A successful resolution never ends the turn. Emitting the Step 7 block is a checkpoint, not a stopping point. Carry straight on into the calling skill's next step in the same turn. Only the explicit failure exits (bad
stage=, version gap, missing prerequisite, invalid description, user cancel) stop the run.