create-issue

Create Issue

Create or update a well-structured GitHub issue from a verified design document. The issue serves as the implementation brief — everything a developer (or Claude) needs to build the feature without ambiguity.

Announce at start: If updating an existing issue: "Updating issue #N from the design document." Otherwise: "Creating GitHub issue from the design document."

When to Use

• After a design document has been written and verified
• When the user wants to track a feature as a GitHub issue
• When transitioning from design to implementation planning
• When an existing issue number is passed as context (update mode — syncs the issue with the design document)

Process

Step 1: Assemble design content

Design content for new issues comes from the current conversation context (brainstorming output, inline arguments, or previously gathered decisions) — not from docs/plans/.

Context sources (in priority order):

1. If issue is already set in lifecycle context (the user passed an existing issue number): load the existing issue body via gh issue view <issue_number> --json body,title --jq '{title, body}'. This is update mode — skip draft assembly and go directly to Step 5.
2. From brainstorming output in the conversation: extract scope, approach, decisions, and acceptance criteria.
3. From inline start: args (user description + any explicitly provided context).
4. From any design-document content already written earlier in the session (in conversation context — not from a file).

Assemble a minimal issue body from the gathered context. The body will include an empty design marker block that feature-flow:design-document will fill in on the next lifecycle step.

Design marker block (placeholder — will be replaced by design-document):

<!-- feature-flow:design:start -->
(pending design-document — will be filled in by `feature-flow:design-document`)
<!-- feature-flow:design:end -->

Step 2: Check Repository Context