Add /syskit-approve command and redesign /syskit-refine as feedback-b…

templates/claude/CLAUDE_SYSKIT.md

@@ -14,10 +14,11 @@ This project uses **syskit** for specification-driven development. Specification
 For non-trivial changes affecting system behavior, use the syskit workflow:
 
 1. `/syskit-impact <change>` — Analyze what specifications are affected
-2. `/syskit-propose` — Propose all specification updates at once
-   **OR** `/syskit-refine --scope <type>` — Propose changes incrementally by document type (requirements, interfaces, design)
-3. `/syskit-plan` — Break into implementation tasks
-4. `/syskit-implement` — Execute with traceability
+2. `/syskit-propose` — Propose specification updates
+3. `/syskit-refine --feedback "<issues>"` — Iterate on proposed changes based on review feedback (optional, repeatable)
+4. `/syskit-approve` — Approve changes (works across sessions, enables overnight review)
+5. `/syskit-plan` — Break into implementation tasks
+6. `/syskit-implement` — Execute with traceability
 
 New to syskit? Run `/syskit-guide` for an interactive walkthrough.
 

templates/claude/commands/syskit-approve.md

@@ -0,0 +1,93 @@
+---
+description: Approve or reject proposed specification changes (works across sessions)
+arguments:
+  - name: analysis
+    description: Name of the analysis folder (optional, uses most recent if not specified)
+    required: false
+---
+
+# Approve Specification Changes
+
+You are reviewing and approving (or rejecting) proposed specification changes from a previous `/syskit-propose` or `/syskit-refine` session.
+
+## Instructions
+
+### Step 0: Context Check
+
+If this conversation already contains output from a previous syskit command (look for IMPACT_SUMMARY, PROPOSE_SUMMARY, CHUNK_SUMMARY, PLAN_SUMMARY, IMPLEMENT_SUMMARY, or REFINE_SUMMARY markers, or previous `/syskit-*` command invocations), STOP and tell the user:
+
+"This conversation already has syskit command history in context. Start a fresh conversation to run `/syskit-approve` — all progress is saved to disk and will be picked up automatically."
+
+If the user explicitly included `--continue` in their command, skip this check and proceed.
+
+### Step 1: Find Pending Changes
+
+If `$ARGUMENTS.analysis` is provided:
+
+- Find the analysis folder: `.syskit/analysis/$ARGUMENTS.analysis/`
+
+Otherwise:
+
+- Find the most recent folder in `.syskit/analysis/`
+
+Check that `proposed_changes.md` exists in the folder. If not, tell the user:
+
+"No proposed changes found. Run `/syskit-propose` first to generate specification changes."
+
+Read the first ~10 lines of `proposed_changes.md` to get the change name and status.
+
+If `Status:` is already "Approved", tell the user:
+
+"These changes have already been approved. Run `/syskit-plan` to create an implementation task breakdown."
+
+If `Status:` is not "Pending Approval", tell the user the current status and suggest running `/syskit-propose`.
+
+### Step 2: Check for Uncommitted Changes
+
+Run `git status -- doc/` to verify there are uncommitted changes in the doc directory.
+
+If there are **no** uncommitted changes in `doc/`:
+
+Tell the user: "No uncommitted changes found in `doc/`. The proposed changes may have already been committed or reverted. Check `git log -- doc/` for recent commits, or re-run `/syskit-propose` to regenerate changes."
+
+### Step 3: Show Change Summary
+
+Read the change summary table from `proposed_changes.md` (the `## Change Summary` section, typically a markdown table).
+
+Run `git diff --stat -- doc/` to get a compact summary of what files changed.
+
+Present to the user:
+
+"**Pending approval:** <change name>
+**Analysis folder:** `.syskit/analysis/<folder>/`
+
+**Change summary:**
+<paste the change summary table from proposed_changes.md>
+
+**Files changed:**
+<paste git diff --stat output>
+
+Review the full diff with `git diff doc/` or your editor's source control panel.
+
+Reply with:
+- **'approve'** to accept all changes and proceed to planning
+- **'approve \<filename\>'** to keep changes to specific file(s) and revert others
+- **'reject'** to revert all changes (`git checkout -- doc/`)
+- **'refine'** to describe issues and run `/syskit-refine` instead"
+
+### Step 4: Handle Response
+
+- **approve:** Update `Status: Pending Approval` to `Status: Approved` in `.syskit/analysis/<folder>/proposed_changes.md`. Proceed to Step 5.
+- **approve \<filename\>:** Revert all other changed doc files with `git checkout -- doc/<other files>`, keeping only the specified file(s). Update `Status: Pending Approval` to `Status: Approved` in `proposed_changes.md`. Proceed to Step 5.
+- **reject:** Run `git checkout -- doc/` to revert all changes. Tell the user the proposal has been discarded.
+- **refine:** Tell the user to start a new conversation and run `/syskit-refine --feedback "<their feedback>"` to iterate on the changes.
+
+### Step 5: Next Steps
+
+Tell the user:
+
+"Changes approved. Status updated in `.syskit/analysis/<folder>/proposed_changes.md`.
+
+Next step: run `/syskit-plan` to create an implementation task breakdown.
+
+Tip: Start a new conversation before running the next command to free up context."

templates/claude/commands/syskit-guide.md

@@ -127,12 +127,14 @@ Explain:
 - The manifest (`.syskit/manifest.md`) stores SHA256 hashes of every spec document
 - This enables **freshness checking** — syskit detects when specs have changed between workflow steps, preventing work based on stale analysis
 
-Then explain the four-command change workflow for future changes:
+Then explain the change workflow for future changes:
 
 1. **`/syskit-impact`** — Describe a change; syskit analyzes which specs are affected
-2. **`/syskit-propose`** — Review and approve proposed modifications to affected specs
-3. **`/syskit-plan`** — Break approved spec changes into implementation tasks
-4. **`/syskit-implement`** — Execute tasks one by one with verification
+2. **`/syskit-propose`** — Draft proposed modifications to affected specs
+3. **`/syskit-refine`** — (Optional, repeatable) Fix issues in proposed changes based on your review feedback
+4. **`/syskit-approve`** — Approve changes when ready (works across sessions — review overnight if needed)
+5. **`/syskit-plan`** — Break approved spec changes into implementation tasks
+6. **`/syskit-implement`** — Execute tasks one by one with verification
 
 Tell the user: "You're set up. When you want to make a change, start with `/syskit-impact` and describe what you want to change."
 
@@ -165,9 +167,11 @@ Explain the conventions this project uses:
 Walk through how to make changes in this project:
 
 1. **`/syskit-impact <description>`** — Start here. Describe what you want to change. Syskit analyzes which specs are affected and creates an impact report.
-2. **`/syskit-propose`** — Proposes specific edits to affected specs. You review and approve before any specs are modified.
-3. **`/syskit-plan`** — Creates an implementation task breakdown from approved spec changes.
-4. **`/syskit-implement`** — Executes tasks one by one with verification.
+2. **`/syskit-propose`** — Drafts specific edits to affected specs. You review using `git diff`.
+3. **`/syskit-refine --feedback "<issues>"`** — (Optional) Fix issues in the proposal based on your review. Repeatable.
+4. **`/syskit-approve`** — Approve changes when satisfied. Works across sessions — review overnight if needed.
+5. **`/syskit-plan`** — Creates an implementation task breakdown from approved spec changes.
+6. **`/syskit-implement`** — Executes tasks one by one with verification.
 
 Also mention helper scripts for creating new documents:
 - `.syskit/scripts/new-req.sh <name>` — Create a new requirement (use `--parent REQ-NNN` for child)

templates/claude/commands/syskit-impact.md

@@ -41,16 +41,12 @@ If `$ARGUMENTS.incremental` is provided (or the user's command included `--incre
 
 2. Read the first few lines of `impact.md` in that folder to get the original proposed change description.
 
-3. Check for `refine_status.md` in the folder. If it does not exist, warn the user: "No refinement history found. Run `/syskit-refine` first, or use `/syskit-impact` without `--incremental` for a fresh analysis."
+3. Set the PROPOSED_CHANGE to the original change description from impact.md, appended with:
+   "NOTE: Specifications may have been modified since the original analysis (via `/syskit-propose` and `/syskit-refine`). The impact analysis should reflect the CURRENT state of all documents."
 
-4. Read the `refine_status.md` to note which scopes have been approved.
+4. Rename the existing `impact.md` to `impact_prev.md` (for reference).
 
-5. Set the PROPOSED_CHANGE to the original change description from impact.md, appended with:
-   "NOTE: The following refinements have already been approved and applied to the doc/ files: \<list approved scopes and their document lists from refine_status.md\>. The impact analysis should reflect the CURRENT state of these documents (post-refinement) and focus on remaining unrefined documents."
-
-6. Rename the existing `impact.md` to `impact_prev.md` (for reference).
-
-7. Note the analysis folder path — you will reuse it. Skip Step 2.
+5. Note the analysis folder path — you will reuse it. Skip Step 2.
 
 If `$ARGUMENTS.incremental` is NOT provided and `$ARGUMENTS.change` is empty, STOP and tell the user: "Please provide a change description: `/syskit-impact \"your change description\"`"
 
@@ -109,6 +105,6 @@ Tell the user:
 
 "Impact analysis complete. Results saved to `.syskit/analysis/<folder>/impact.md`.
 
-Next step: run `/syskit-refine --scope <recommended_scope>` to propose changes to the next set of documents, or `/syskit-propose` to propose all changes at once.
+Next step: run `/syskit-propose` to propose specification changes based on this analysis.
 
 Tip: Start a new conversation before running the next command to free up context."

templates/claude/commands/syskit-plan.md

@@ -30,19 +30,15 @@ Otherwise:
 
 - Find the most recent folder in `.syskit/analysis/`
 
-Check for approval status using this priority:
+Check for approval status:
 
-1. If `refine_status.md` exists in the folder:
-   - Read it. Check the top-level `Status:` field.
-   - If "Complete", proceed — all scopes have been refined and approved.
-   - If "In Progress", warn the user: "Refinement is still in progress. The following scopes are not yet approved: \<list\>. Run `/syskit-refine` to complete them, or pass `--force` to plan with partial refinement."
-   - The subagent will read all `refine_<scope>.md` files for context.
+1. Check that `proposed_changes.md` exists in the folder.
+   - If it does not exist, tell the user: "No proposed changes found. Run `/syskit-propose` first to generate specification changes."
 
-2. Else if `proposed_changes.md` exists:
-   - Read ONLY its first ~10 lines. Check the `Status:` line.
-   - If not "Approved", prompt user to run `/syskit-propose` first.
-
-3. If neither exists, prompt user to run `/syskit-propose` or `/syskit-refine` first.
+2. Read ONLY its first ~10 lines. Check the `Status:` line.
+   - If "Approved", proceed.
+   - If "Pending Approval", tell the user: "Proposed changes have not been approved yet. Run `/syskit-approve` to review and approve them, or approve inline during `/syskit-propose`."
+   - If any other status, tell the user the current status and suggest re-running `/syskit-propose`.
 
 Note the analysis folder path and the change name — you will pass these to the subagent.
 

templates/claude/commands/syskit-propose.md

@@ -139,7 +139,11 @@ Reply with:
 - **'approve'** to keep all changes and proceed to planning
 - **'approve \<filename\>'** to keep changes to a specific file and revert others
 - **'revise \<filename\>'** to discuss modifications to a specific file
-- **'reject'** to revert all changes (`git checkout -- doc/`)"
+- **'reject'** to revert all changes (`git checkout -- doc/`)
+
+Or review at your leisure and use these commands in a new session:
+- **`/syskit-refine --feedback \"<your feedback>\"`** to iterate on the proposed changes
+- **`/syskit-approve`** to approve when ready"
 
 ### Step 8: Handle Approval
 
@@ -148,11 +152,11 @@ Reply with:
 - **revise \<filename\>:** Discuss the specific file with the user, make adjustments, then re-present.
 - **reject:** Run `git checkout -- doc/` to revert all changes. Tell the user the proposal has been discarded.
 
-### Step 9: Next Step
+### Step 9: Next Steps
 
 After applying approved changes, tell the user:
 
-"Proposed changes applied. Summary saved to `.syskit/analysis/<folder>/proposed_changes.md`.
+"Changes approved. Summary saved to `.syskit/analysis/<folder>/proposed_changes.md`.
 
 Next step: run `/syskit-plan` to create an implementation task breakdown.