Consolidate 36 per-change specs into 4 feature-level specs and align workflow
Replace granular change-level specs (001–036) with living feature specs: - 001-combatant-management (CRUD, persistence, clear, confirm buttons) - 002-turn-tracking (rounds, turn order, advance/retreat, top bar) - 003-combatant-state (HP, AC, conditions, concentration, initiative) - 004-bestiary (search, stat blocks, source management, panel UX) Workflow changes: - Add /integrate-issue command (replaces /issue-to-spec) for routing issues to existing specs or handing off to /speckit.specify - Update /sync-issue to list specs instead of requiring feature branch - Update /write-issue to reference /integrate-issue - Add RPI skills (research, plan, implement) to .claude/skills/ - Create docs/agents/ for RPI artifacts (research reports, plans) - Remove update-agent-context.sh call from /speckit.plan - Update CLAUDE.md with proportional scope-based workflow table - Bump constitution to 3.0.0 (specs describe features, not changes) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Lukas
143
.claude/commands/integrate-issue.md
Normal file
143
.claude/commands/integrate-issue.md
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
description: Fetch a Gitea issue, identify the affected feature spec(s), and integrate the issue's requirements into the spec. For new features, hands off to /speckit.specify.
|
||||
---
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** provide an issue number as the argument (e.g. `/integrate-issue 6`). 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>/comments"
|
||||
```
|
||||
|
||||
If comments exist, include them as additional context (they may contain clarifications or requirements discussed after the issue was created).
|
||||
|
||||
### Step 3 — Route: new feature or existing feature?
|
||||
|
||||
List the existing feature specs by reading the `specs/` directory:
|
||||
|
||||
```bash
|
||||
ls -d specs/*/
|
||||
```
|
||||
|
||||
Present the issue summary and existing specs to the user. Ask:
|
||||
|
||||
**"Does this issue belong to an existing feature, or is it a new feature?"**
|
||||
|
||||
Present options:
|
||||
- Each existing spec as a numbered option (show spec name and one-line description from CLAUDE.md or the spec's overview)
|
||||
- A "New feature" option
|
||||
|
||||
If the user selects **New feature**, compose the feature description from the issue content (title + body + comments) and hand off to `/speckit.specify`. Stop here.
|
||||
|
||||
If the user selects an **existing spec**, continue to Step 4.
|
||||
|
||||
### Step 4 — Read the affected spec
|
||||
|
||||
Load the selected spec file. Identify the sections that the issue's requirements affect:
|
||||
- Which user stories need updating?
|
||||
- Which requirements (FR-NNN) need adding or modifying?
|
||||
- Which acceptance scenarios change?
|
||||
- Are new edge cases introduced?
|
||||
|
||||
Present your analysis to the user:
|
||||
- **Stories affected**: list the story IDs/titles that need changes
|
||||
- **New stories needed**: if the issue introduces behavior not covered by any existing story
|
||||
- **Requirements to add/modify**: list specific FR numbers or new ones needed
|
||||
|
||||
Ask the user to confirm or adjust the scope.
|
||||
|
||||
### Step 5 — Draft spec changes
|
||||
|
||||
For each affected section, draft the specific changes:
|
||||
|
||||
- **Modified stories**: show the before/after for acceptance scenarios
|
||||
- **New stories**: write them in the spec's format (matching the existing story naming convention — e.g., `**Story HP-7**` for combatant-state, `**Story A4**` for combatant-management)
|
||||
- **New/modified requirements**: write them with the next available FR number
|
||||
- **New edge cases**: add to the relevant edge cases section
|
||||
|
||||
For per-topic specs (003-combatant-state, 004-bestiary), place changes in the correct topic section.
|
||||
|
||||
### Step 6 — Preview and confirm
|
||||
|
||||
Show the user a complete preview of all changes:
|
||||
- Which file(s) will be modified
|
||||
- The exact additions/modifications (as diffs or before/after blocks)
|
||||
|
||||
Ask for confirmation before writing.
|
||||
|
||||
### Step 7 — Write changes
|
||||
|
||||
On confirmation:
|
||||
- Write the updated spec file(s)
|
||||
- Report what was changed (sections touched, stories added/modified, requirements added)
|
||||
|
||||
### Step 8 — Suggest next steps
|
||||
|
||||
Report completion and suggest next steps based on scope:
|
||||
|
||||
- **Straightforward change** (1-2 stories, clear acceptance scenarios): "Implement the changes and commit"
|
||||
- **Larger change** (multiple stories, cross-cutting concerns): "Use `rpi-research` to investigate the affected code, then `rpi-plan` to create a phased implementation plan, then `rpi-implement` to execute it"
|
||||
- **Complex or ambiguous change**: "Run `/speckit.clarify` to resolve remaining ambiguities before implementing"
|
||||
- Always: "Run `/sync-issue <number>` to update the Gitea issue with the new acceptance criteria"
|
||||
|
||||
## Behavior Rules
|
||||
|
||||
- Never modify the issue on Gitea — this is a read-only operation on the issue side.
|
||||
- Always preview before writing spec changes — never write without user confirmation.
|
||||
- Include comment authors in the context so requirements can be attributed.
|
||||
- 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.
|
||||
- Match the existing spec's naming conventions for stories, requirements, and structure.
|
||||
- When adding to per-topic specs (003, 004), place content in the correct topic section — do not create new top-level sections unless the change introduces an entirely new topic area.
|
||||
- Increment FR/SC numbers from the highest existing number in the spec.
|
||||
@@ -1,101 +0,0 @@
|
||||
---
|
||||
description: Fetch a Gitea issue and feed it into /speckit.specify as the feature description.
|
||||
handoffs:
|
||||
- label: Start speccing from this issue
|
||||
agent: speckit.specify
|
||||
prompt: "Create a spec from this issue"
|
||||
send: true
|
||||
---
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
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.
|
||||
@@ -75,14 +75,7 @@ You **MUST** consider the user input before proceeding (if not empty).
|
||||
- Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
|
||||
- Skip if project is purely internal (build scripts, one-off tools, etc.)
|
||||
|
||||
3. **Agent context update**:
|
||||
- Run `.specify/scripts/bash/update-agent-context.sh claude`
|
||||
- These scripts detect which AI agent is in use
|
||||
- Update the appropriate agent-specific context file
|
||||
- Add only new technology from current plan
|
||||
- Preserve manual additions between markers
|
||||
|
||||
**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
|
||||
**Output**: data-model.md, /contracts/*, quickstart.md
|
||||
|
||||
## Key rules
|
||||
|
||||
|
||||
@@ -38,23 +38,31 @@ Extract:
|
||||
- `REPO` — the repo name (strip `.git` suffix)
|
||||
- `API_BASE` — `https://<GITEA_HOST>/api/v1`
|
||||
|
||||
3. Locate the spec file. Run:
|
||||
3. Locate the spec file. List the available feature specs:
|
||||
|
||||
```bash
|
||||
.specify/scripts/bash/check-prerequisites.sh --json --paths-only
|
||||
ls specs/*/spec.md
|
||||
```
|
||||
|
||||
Parse `FEATURE_SPEC` from the output. If it fails, ask the user to ensure they're on a feature branch with a spec. For single quotes in args, use escape syntax: e.g `'I'\''m Groot'` (or double-quote if possible: `"I'm Groot"`).
|
||||
Present the specs to the user and ask which one contains the acceptance criteria for this issue. If only one spec exists, use it automatically.
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 1 — Read the spec
|
||||
|
||||
Load the spec file at `FEATURE_SPEC`. Parse the **User Scenarios & Testing** section, specifically:
|
||||
Load the spec file at `FEATURE_SPEC`. Extract user stories and acceptance scenarios using these patterns:
|
||||
|
||||
- Each `### User Story N - [Title]` block
|
||||
**Flat specs** (001-combatant-management, 002-turn-tracking):
|
||||
- Look for the `## User Scenarios & Testing` section
|
||||
- Each `### ... Story ...` or `**Story ...** ` block
|
||||
- The **Acceptance Scenarios** numbered list within each story (Given/When/Then format)
|
||||
- The **Edge Cases** section
|
||||
- The **Edge Cases** section(s)
|
||||
|
||||
**Per-topic specs** (003-combatant-state, 004-bestiary):
|
||||
- Stories are nested inside topic sections (e.g., `## Hit Points` > `### User Stories` > `**Story HP-1 — ...**`)
|
||||
- Scan ALL `##` sections for `**Story ...` or `**US-...` patterns
|
||||
- Extract acceptance scenarios from each story regardless of nesting depth
|
||||
- Collect edge cases from each topic section's `### Edge Cases` subsection
|
||||
|
||||
### Step 2 — Condense into business-level acceptance criteria
|
||||
|
||||
|
||||
@@ -150,7 +150,7 @@ PAYLOAD
|
||||
|
||||
Parse the response and report:
|
||||
- Issue number and URL (`https://<GITEA_HOST>/<OWNER>/<REPO>/issues/<number>`)
|
||||
- Suggest next step: `/issue-to-spec <number>` to start speccing
|
||||
- Suggest next step: `/integrate-issue <number>` to integrate into a feature spec
|
||||
|
||||
## Behavior Rules
|
||||
|
||||
|
||||
Reference in New Issue
Block a user