| name | feature-state |
| description | Change a feature's state (active/paused/replaced/abandoned). Use when a feature needs to be paused while waiting on something, marked obsolete because another feature replaces it, or abandoned because it won't be pursued. Requires companion fields for non-active states. |
| user-invocable | true |
| allowed-tools | Read, Edit, Bash |
Change Feature State
You are executing the CHANGE STATE workflow — flipping the state: field in a feature's idea.md frontmatter and validating the required companion fields.
Arguments
$ARGUMENTS: <feature-id> <state> [--reason "..."] [--replaced-by <id>]
Examples:
/feature-state user-roles paused --reason "Waiting on auth team"/feature-state old-feature replaced --replaced-by new-feature/feature-state nice-to-have abandoned --reason "Out of scope"/feature-state stuck-feature active (resume from paused/tombstone)
Step 1: Parse Arguments
Extract:
<feature-id> — required<state> — one of active, paused, replaced, abandoned--reason "..." — used for paused (writes pausedReason) or abandoned (writes abandonedReason)--replaced-by <id> — used for replaced (writes replacedBy)
If arguments are missing or malformed, show usage and stop.
Step 2: Load Feature
Read docs/features/<feature-id>/idea.md. If it doesn't exist, error:
"No feature <feature-id>. Check docs/features/ or run /feature-search."
If shipped.md exists AND the requested new state is replaced or abandoned, refuse:
"<feature-id> is already shipped — tombstoning it makes no sense. If it needs to be reverted, revert the PR and remove shipped.md first."
Step 3: Validate Required Companions
| Target state | Required argument |
|---|
paused | --reason "..." |
replaced | --replaced-by <id> |
abandoned | --reason "..." |
active | none |
If the required companion is missing, ask the user for it via AskUserQuestion before proceeding.
For replaced: also check that the referenced ID has an idea.md on disk. If not, warn but allow (forward reference).
Step 4: Update Frontmatter
Use the Edit tool to update docs/features/<feature-id>/idea.md:
- Set
state: — replace any existing state: line, or insert one after id:.
- Set companion field — same insertion pattern.
- Clean up obsolete companions when state changes:
- Resuming to
active from paused: remove pausedReason:
- Resuming to
active from replaced: remove replacedBy:
- Resuming to
active from abandoned: remove abandonedReason:
Do NOT touch any other frontmatter or content.
Step 5: Confirm + Regen Dashboard
The PostToolUse hook will regenerate DASHBOARD.md automatically when you edit idea.md.
Print a one-line confirmation:
"✓ <feature-id> is now <state>. "
Step 6: Suggest Follow-Up
| New state | Suggest |
|---|
| paused | "When the blocker clears, run /feature-state <id> active to resume." |
| replaced | "If <replaced-by-id> doesn't exist yet, run /feature-capture to create it." |
| abandoned | (none — terminal state for now) |
| active (from paused) | "Resume with /feature-implement <id> or /feature-autopilot <id>." |
Notes
- This is the only correct way to tombstone a feature. Do NOT delete the directory — the history is the whole point.
- The dashboard hook regenerates on edit; no manual regen needed.
- State changes are reversible. Going
paused → active → paused is fine.
