initiative/.claude/commands/issue-to-spec.md

description, handoffs

description	handoffs
Fetch a Gitea issue and feed it into /speckit.specify as the feature description.	label agent prompt send Start speccing from this issue speckit.specify Create a spec from this issue true

User Input

$ARGUMENTS

You MUST provide an issue number as the argument (e.g. /issue-to-spec 42). If $ARGUMENTS is empty or not a valid number, ask the user for the issue number.

Prerequisites

1. Verify the GITEA_TOKEN_ISSUES environment variable is set:

test -n "$GITEA_TOKEN_ISSUES" && echo "TOKEN_OK" || echo "TOKEN_MISSING"

If missing, tell the user to set it:

export GITEA_TOKEN_ISSUES="your-gitea-personal-access-token"

Then abort.

2. Parse the git remote to extract the Gitea API base URL, owner, and repo:

git config --get remote.origin.url

Expected format: ssh://git@<host>:<port>/<owner>/<repo>.git or https://<host>/<owner>/<repo>.git

Extract:

• GITEA_HOST — the hostname
• OWNER — the repo owner/org
• REPO — the repo name (strip .git suffix)
• API_BASE — https://<GITEA_HOST>/api/v1

Execution

Step 1 — Fetch the issue

curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>"

Extract from the JSON response:

• title — the issue title
• body — the issue body (markdown)
• labels — array of label names (if any)

If the API call fails or returns no issue, abort with a clear error.

Step 2 — Fetch issue comments (if any)

curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>/comments"

If comments exist, append them to the context (they may contain clarifications or additional requirements discussed after the issue was created).

Step 3 — Compose the feature description

Format the issue content into a feature description suitable for /speckit.specify:

<Issue Title>

<Issue Body>

<If comments exist:>
---
Additional context from issue comments:
<Comment 1 by @author>: <comment body>
<Comment 2 by @author>: <comment body>
...

Step 4 — Report and hand off

Display a summary:

• Issue number and title
• Number of comments included
• The composed feature description

Then hand off to /speckit.specify with the composed feature description as input. The handoff button in the UI will allow the user to proceed.

Behavior Rules

• Never modify the issue on Gitea — this is a read-only operation.
• Include comment authors in the context so /speckit.specify can attribute requirements.
• If the issue body is empty, warn the user but still proceed with just the title.
• Strip HTML tags from the body/comments if present (Gitea sometimes includes rendered HTML).
• Use curl for all API calls — do not rely on gh CLI.