Feature Management

A feature is a GitHub issue with the feature label until someone starts building it. Filing, prioritizing and scheduling a feature touch only GitHub: nothing is written to the repo and nothing is committed. Its spec in docs/features/ is written when development starts, on the feature's branch, and reaches main in the same pull request as the code, together with any impl plan or mission brief.

Usage

/feature <action> [args]

Actions

new <name>

File a new feature as an issue.

1. Ask the user to describe the feature (motivation, scope, key decisions) unless they already have.
2. Pick a priority (see Priority below). If the user didn't state one, propose one and confirm before filing. Don't file unlabeled.
3. Set a milestone only when the user names one.
4. Create the issue with labels feature and the chosen P0/P1/P2/P3:
   • Title: feat: <short description>
   • Body: Motivation, Scope, and Open questions when there are any. The issue holds the design discussion until development starts.
   • Command shape: gh issue create --label feature --label P1 --title "…" --body "…" [--milestone 0.16]
5. Report the issue URL, priority and milestone. Do not create a spec or edit any doc.

list

Show all features, sorted by priority.

1. Fetch open features with priority + metadata as JSON so they can be sorted: gh issue list --label feature --state open --limit 50 --json number,title,labels,milestone,createdAt,assignees
2. List the spec files in docs/features/ (excluding README); most features have none until development starts.
3. Sort the rows by priority (P0 first, then P1, P2, P3, then unlabeled-by-priority last). Within a priority bucket, sort by issue number ascending.
4. Present a combined view: Priority, feature name, # (issue), Milestone, spec file (if one exists), Created. Issues without a P-label show — in priority and a callout asking the user to triage them.
5. If the user asks for closed/shipped features too, repeat with --state all and add a State column.

spec <issue-number>

Write the spec when development of a feature starts.

1. Work in the feature's branch worktree (AGENTS.md, Worktrees), never in the root checkout on main. If the branch does not exist yet, create it as AGENTS.md describes once the user has asked to start the work.
2. Create docs/features/{issue}-{slug}.md, pre-populated from the issue body and its discussion: a header linking the tracking issue, then Motivation, Scope, Implementation Phases, Verification. Leave priority and milestone out; they live on the issue.
3. Add the spec's line under Active in docs/features/README.md.
4. The spec is committed on the branch and lands with the code. A crew mission folds it into its commits like the brief.

close <issue-number>

Close a feature that shipped or was dropped.

1. Close the GitHub issue: gh issue close <number>, adding --reason "not planned" when it was dropped.
2. Leave its spec where it is. The release's docs sweep archives specs (release skill, sweep).

prioritize <issue-number> <P0|P1|P2|P3>

Set or change the priority of an existing feature.

1. Remove any existing P-label on the issue, then add the new one: gh issue edit <number> --remove-label P0 --remove-label P1 --remove-label P2 --remove-label P3 --add-label <priority> (Removing all four is safe — gh ignores remove-label for labels not present.)
2. Confirm the new priority.

Labels

• feature — all feature issues use this label.
• bug — for bug reports (not managed by this skill).
• P0 / P1 / P2 / P3 — priority, exactly one per issue.

Priority

Every feature gets exactly one priority label. Rubric:

• P0 — Required for the next ship; nothing else moves until this lands. Rare for features.
• P1 — Wanted this cycle; blocks an active user workflow or has a stakeholder commitment.
• P2 — Real product win, but no urgency. Pick up when the P1 queue is clear.
• P3 — Idea / nice-to-have / "if we ever revisit X." OK to sit indefinitely; closing as wontfix later is fine.

When in doubt between two levels, pick the lower-urgency one and say why; over-labeling P0/P1 dilutes the signal.

Conventions

• A spec is named after its tracking issue, {issue}-{slug}.md, with a lowercase kebab-case slug.
• Specs, impl plans (docs/impls/) and mission briefs (docs/impls/briefs/) are written on the feature's branch and land with its code. Design files are the exception: .pen files are settled on main first (AGENTS.md, Engineering Conventions).
• Shipped specs move to docs/features/archive/ in the release's docs sweep. The implementation is the source of truth; the archived spec stays as the "what we were going for" record.

Notes

• Do not commit or push unless the user explicitly asks.
• A spec always links its GitHub issue URL.