/spectra-commit

Commit files related to a specific Spectra change.

This is a utility skill (not a workflow step). It reads source file tracking data and artifact changes to stage and commit only the files belonging to one change — useful when multiple changes are in progress simultaneously.

Input: Optionally specify a change name after /spectra:commit (e.g., /spectra:commit add-auth). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Prerequisites: This skill requires git. Run git --version. If git is not available (command not found or similar error), inform the user to install git and STOP.

Steps

1. Select the change

   If a name is provided, use it. Otherwise:

   • Infer from conversation context if the user mentioned a change
   • Auto-select if only one active change exists
   • If ambiguous, run spectra list --json to get available changes. Use the AskUserQuestion tool to let the user select

   Always announce: "Committing for change: "

2. Read tracking file

   Check for .spectra/touched/<change-name>.json. If it exists, parse it to get source files grouped by task.

   Expected format:

   {
     "change": "<change-name>",
     "touched": [
       {
         "task_id": "1",
         "task_desc": "Task description",
         "files": ["src/file1.ts", "src/file2.ts"]
       }
     ]
   }
   

   If the file does not exist, proceed without source file data — only artifact files will be included.

3. Collect artifact files

   Run git status --porcelain and filter the output to files under openspec/changes/<name>/. These are the change's artifact files (proposal, design, tasks, specs, etc.).

4. Identify unrelated dirty files

   From the full git status --porcelain output, any dirty files NOT in the artifact set and NOT in the tracking file are "unrelated changes."

5. Display commit plan

   Show the file list grouped into sections:

   ## Commit Plan: <change-name>
   
   ### Change Artifacts
   - M  openspec/changes/<name>/proposal.md
   - M  openspec/changes/<name>/tasks.md
   
   ### Source Files
   **Task 1: <task description>**
   - M  src/lib/components/search.svelte
   - A  src/lib/stores/search.ts
   
   **Task 3: <task description>**
   - M  src/routes/+page.svelte
   
   ### Unrelated Changes (not included)
   - M  src/lib/utils/format.ts
   - ??  tmp/scratch.js
   

   If no tracking file was found, show a warning instead of the Source Files section:

   ### Source Files
   ⚠ No source file tracking data found.
   Only artifact files will be committed. Use `spectra task done` during apply to enable source file tracking.
   

   If there are no artifact files AND no tracked source files, inform the user that there is nothing to commit and STOP.

6. User confirmation

   Use the AskUserQuestion tool to ask the user how to proceed.

   Options:

   • Commit as shown: Proceed with the displayed artifact + source files
   • Include all dirty files: Add all unrelated files to the commit as well
   • Customize: Let the user add or remove specific files from the commit set
   • Archive first, then commit together: Run archive before committing — archive file moves will be included in this commit

   If the user selects "Customize":

   • Show a numbered list of all dirty files (included and excluded)
   • Ask which files to add or remove
   • Re-display the updated commit plan for confirmation

   If the user selects "Archive first, then commit together":

   • Proceed to step 6a (Archive sub-flow) before continuing to step 7

6a. Archive sub-flow (only when the user selected "Archive first, then commit together")

This sub-flow executes three checks in sequence before returning to the main commit flow.

**6a-i. Incomplete task handling**

Read the tasks file at `openspec/changes/<name>/tasks.md`. Count `- [x]` (complete) and `- [ ]` (incomplete) checkboxes.