feat(autonomous): add --to N flag to stop after specific phase (#1646)

Allows users to run autonomous mode up to a specific phase number.
After the target phase completes, execution halts instead of advancing.

Closes #1644

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

commands/gsd/autonomous.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:autonomous
 description: Run all remaining phases autonomously — discuss→plan→execute per phase
-argument-hint: "[--from N] [--only N] [--interactive]"
+argument-hint: "[--from N] [--to N] [--only N] [--interactive]"
 allowed-tools:
   - Read
   - Write
@@ -32,6 +32,7 @@ Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase comm
 <context>
 Optional flags:
 - `--from N` — start from phase N instead of the first incomplete phase.
+- `--to N` — stop after phase N completes (halt instead of advancing to next phase).
 - `--only N` — execute only phase N (single-phase mode).
 - `--interactive` — run discuss inline with questions (not auto-answered), then dispatch plan→execute as background agents. Keeps the main context lean while preserving user input on decisions.
 

get-shit-done/workflows/autonomous.md

@@ -1,6 +1,6 @@
 <purpose>
 
-Drive milestone phases autonomously — all remaining phases, or a single phase via `--only N`. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
+Drive milestone phases autonomously — all remaining phases, a range via `--from N`/`--to N`, or a single phase via `--only N`. For each incomplete phase: discuss → plan → execute using Skill() flat invocations. Pauses only for explicit user decisions (grey area acceptance, blockers, validation requests). Re-reads ROADMAP.md after each phase to catch dynamically inserted phases.
 
 </purpose>
 
@@ -16,7 +16,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 ## 1. Initialize
 
-Parse `$ARGUMENTS` for `--from N`, `--only N`, and `--interactive` flags:
+Parse `$ARGUMENTS` for `--from N`, `--to N`, `--only N`, and `--interactive` flags:
 
 ```bash
 FROM_PHASE=""
@@ -24,6 +24,11 @@ if echo "$ARGUMENTS" | grep -qE '\-\-from\s+[0-9]'; then
   FROM_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-from\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
 fi
 
+TO_PHASE=""
+if echo "$ARGUMENTS" | grep -qE '\-\-to\s+[0-9]'; then
+  TO_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-to\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
+fi
+
 ONLY_PHASE=""
 if echo "$ARGUMENTS" | grep -qE '\-\-only\s+[0-9]'; then
   ONLY_PHASE=$(echo "$ARGUMENTS" | grep -oE '\-\-only\s+[0-9]+\.?[0-9]*' | awk '{print $2}')
@@ -65,6 +70,7 @@ Display startup banner:
 
 If `ONLY_PHASE` is set, display: `Single phase mode: Phase ${ONLY_PHASE}`
 Else if `FROM_PHASE` is set, display: `Starting from phase ${FROM_PHASE}`
+If `TO_PHASE` is set, display: `Stopping after phase ${TO_PHASE}`
 If `INTERACTIVE` is set, display: `Mode: Interactive (discuss inline, plan+execute in background)`
 
 </step>
@@ -85,8 +91,18 @@ Parse the JSON `phases` array.
 
 **Apply `--from N` filter:** If `FROM_PHASE` was provided, additionally filter out phases where `number < FROM_PHASE` (use numeric comparison — handles decimal phases like "5.1").
 
+**Apply `--to N` filter:** If `TO_PHASE` was provided, additionally filter out phases where `number > TO_PHASE` (use numeric comparison). This limits execution to phases up through the target phase.
+
 **Apply `--only N` filter:** If `ONLY_PHASE` was provided, additionally filter OUT phases where `number != ONLY_PHASE`. This means the phase list will contain exactly one phase (or zero if already complete).
 
+**If `TO_PHASE` is set and no phases remain** (all phases up to N are already completed):
+
+```
+All phases through ${TO_PHASE} are already completed. Nothing to do.
+```
+
+Exit cleanly.
+
 **If `ONLY_PHASE` is set and no phases remain** (phase already complete):
 
 ```
@@ -758,6 +774,21 @@ Decisions captured: {count} across {area_count} areas
 
 **If `ONLY_PHASE` is set:** Do not iterate. Proceed directly to lifecycle step (which exits cleanly per single-phase mode).
 
+**If `TO_PHASE` is set and current phase number >= `TO_PHASE`:** The target phase has been reached. Do not iterate further. Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► AUTONOMOUS ▸ --to ${TO_PHASE} REACHED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Completed through phase ${TO_PHASE} as requested.
+ Remaining phases were not executed.
+
+ Resume with: /gsd:autonomous --from ${next_incomplete_phase}
+```
+
+Proceed directly to lifecycle step (which handles partial completion — skips audit/complete/cleanup since not all phases are done). Exit cleanly.
+
 **Otherwise:** After each phase completes, re-read ROADMAP.md to catch phases inserted mid-execution (decimal phases like 5.1):
 
 ```bash
@@ -767,6 +798,7 @@ ROADMAP=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap analyze)
 Re-filter incomplete phases using the same logic as discover_phases:
 - Keep phases where `disk_status !== "complete"` OR `roadmap_complete === false`
 - Apply `--from N` filter if originally provided
+- Apply `--to N` filter if originally provided
 - Sort by number ascending
 
 Read STATE.md fresh:
@@ -947,7 +979,7 @@ When any phase operation fails or a blocker is detected, present 3 options via A
  Skipped: {list of skipped phases}
  Remaining: {list of remaining phases}
 
- Resume with: /gsd-autonomous ${ONLY_PHASE ? "--only " + ONLY_PHASE : "--from " + next_phase}
+ Resume with: /gsd-autonomous ${ONLY_PHASE ? "--only " + ONLY_PHASE : "--from " + next_phase}${TO_PHASE ? " --to " + TO_PHASE : ""}
 ```
 
 </step>
@@ -988,10 +1020,17 @@ When any phase operation fails or a blocker is detected, present 3 options via A
 - [ ] `--only N` exits cleanly after single phase completes
 - [ ] `--only N` on already-complete phase exits with message
 - [ ] `--only N` handle_blocker resume message uses --only flag
+- [ ] `--to N` stops execution after phase N completes (halts at iterate step)
+- [ ] `--to N` filters out phases with number > N during discovery
+- [ ] `--to N` displays "Stopping after phase N" in startup banner
+- [ ] `--to N` on already completed target exits with "already completed" message
+- [ ] `--to N` compatible with `--from N` (run phases from M to N)
+- [ ] `--to N` handle_blocker resume message preserves --to flag
+- [ ] `--to N` skips lifecycle when not all milestone phases complete
 - [ ] `--interactive` runs discuss inline via gsd:discuss-phase (asks questions, waits for user)
 - [ ] `--interactive` dispatches plan and execute as background agents (context isolation)
 - [ ] `--interactive` enables pipeline parallelism: discuss Phase N+1 while Phase N builds
 - [ ] `--interactive` main context only accumulates discuss conversations (lean)
 - [ ] `--interactive` waits for background agents before post-execution routing
-- [ ] `--interactive` compatible with `--only` and `--from` flags
+- [ ] `--interactive` compatible with `--only`, `--from`, and `--to` flags
 </success_criteria>

tests/autonomous-to-flag.test.cjs

@@ -0,0 +1,160 @@
+/**
+ * GSD Tools Tests - autonomous --to N flag
+ *
+ * Validates that the autonomous workflow and command definition
+ * correctly document and support the --to N flag to stop after
+ * a specific phase completes.
+ *
+ * Closes: #1644
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+describe('autonomous --to N flag (#1644)', () => {
+  const workflowPath = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'autonomous.md');
+  const commandPath = path.join(__dirname, '..', 'commands', 'gsd', 'autonomous.md');
+
+  // --- Command definition tests ---
+
+  test('command definition includes --to N in argument-hint', () => {
+    const content = fs.readFileSync(commandPath, 'utf8');
+    assert.ok(content.includes('--to N') || content.includes('--to'),
+      'command argument-hint should include --to flag');
+    // Verify it's in the argument-hint frontmatter line specifically
+    const hintMatch = content.match(/argument-hint:.*--to/);
+    assert.ok(hintMatch, 'argument-hint frontmatter should contain --to');
+  });
+
+  test('command definition describes --to N behavior in context', () => {
+    const content = fs.readFileSync(commandPath, 'utf8');
+    assert.ok(content.includes('--to N') || content.includes('--to'),
+      'command should document --to flag');
+    assert.ok(content.includes('stop') || content.includes('halt'),
+      'command should describe stopping behavior');
+  });
+
+  // --- Workflow parsing tests ---
+
+  test('workflow parses --to N flag into TO_PHASE variable', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    assert.ok(content.includes('--to') && content.includes('TO_PHASE'),
+      'workflow should parse --to into TO_PHASE variable');
+  });
+
+  test('workflow parsing handles --to with numeric argument', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // Should have grep pattern that extracts the number after --to
+    // The workflow uses escaped dashes in grep: \-\-to\s+[0-9]
+    assert.ok(
+      content.includes('--to') && content.includes('TO_PHASE') && content.includes('[0-9]'),
+      'workflow should extract numeric value after --to flag');
+  });
+
+  // --- --to N stops after phase N completes ---
+
+  test('workflow iterate step checks TO_PHASE to halt after target phase', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // The iterate step should check if current phase >= TO_PHASE
+    assert.ok(content.includes('TO_PHASE'),
+      'iterate step should reference TO_PHASE');
+    // Should have logic to stop/halt when target phase is reached
+    const iterateSection = content.substring(content.indexOf('<step name="iterate">'));
+    assert.ok(iterateSection.includes('TO_PHASE'),
+      'iterate step section should check TO_PHASE to decide whether to continue');
+  });
+
+  // --- --to without a number shows error ---
+
+  test('workflow validates --to requires a numeric argument', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // The grep pattern requires a digit after --to, so --to without a number won't match
+    // and TO_PHASE stays empty (no error needed — it simply doesn't activate)
+    assert.ok(content.includes('TO_PHASE=""'),
+      'TO_PHASE defaults to empty when --to has no number (grep requires digit)');
+    // Verify the grep requires a numeric character after --to
+    assert.ok(content.includes('\\-\\-to\\s+[0-9]') || content.includes("--to\\s+[0-9]") || content.includes("--to") && content.includes('[0-9]'),
+      'workflow grep pattern should require a digit after --to');
+  });
+
+  // --- No --to flag runs all phases (existing behavior preserved) ---
+
+  test('workflow defaults TO_PHASE to empty when --to not provided', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    assert.ok(content.includes('TO_PHASE=""'),
+      'TO_PHASE should default to empty string when --to is not provided');
+  });
+
+  test('workflow only halts at iterate when TO_PHASE is set', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // The halt logic should be conditional on TO_PHASE being set
+    const iterateSection = content.substring(content.indexOf('<step name="iterate">'));
+    assert.ok(
+      iterateSection.includes('TO_PHASE') &&
+      (iterateSection.includes('If `TO_PHASE`') || iterateSection.includes('TO_PHASE" is set') || iterateSection.includes('TO_PHASE` is set')),
+      'iterate step should only halt when TO_PHASE is set (preserving default run-all behavior)'
+    );
+  });
+
+  // --- --to N where N < current phase shows message ---
+
+  test('workflow handles --to N where target is already passed', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // Should detect when TO_PHASE is less than the first incomplete phase
+    assert.ok(
+      content.includes('TO_PHASE') &&
+      (content.includes('already past') || content.includes('already beyond') || content.includes('already completed')),
+      'workflow should handle case where --to N target is already completed/passed'
+    );
+  });
+
+  // --- Display / UX ---
+
+  test('workflow displays --to target in startup banner', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // Similar to how --from and --only display in the banner
+    assert.ok(
+      content.includes('TO_PHASE') && (content.includes('Stopping after') || content.includes('stop') || content.includes('through phase')),
+      'startup banner should display --to target phase'
+    );
+  });
+
+  test('workflow displays completion message when --to target reached', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    const iterateSection = content.substring(content.indexOf('<step name="iterate">'));
+    assert.ok(
+      iterateSection.includes('--to') || iterateSection.includes('TO_PHASE'),
+      'iterate section should have --to completion messaging'
+    );
+  });
+
+  // --- Success criteria ---
+
+  test('success criteria include --to N requirements', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    const criteriaMatch = content.match(/<success_criteria>([\s\S]*?)<\/success_criteria>/);
+    const criteria = criteriaMatch ? criteriaMatch[1] : '';
+    assert.ok(criteria.includes('--to'),
+      'success criteria should include --to requirements');
+  });
+
+  // --- Compatibility ---
+
+  test('--to is compatible with --from (documented or implied)', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // --to and --from should be usable together (run phases from N to M)
+    assert.ok(
+      content.includes('--to') && content.includes('--from'),
+      'workflow should support both --to and --from flags'
+    );
+  });
+
+  test('--to flag does not interfere with --only flag parsing', () => {
+    const content = fs.readFileSync(workflowPath, 'utf8');
+    // --only should still work independently; --to parsing should not capture --only values
+    const onlyParsing = content.match(/ONLY_PHASE[\s\S]{0,200}--only/);
+    assert.ok(onlyParsing, '--only parsing should still be present and independent');
+  });
+});

tests/copilot-install.test.cjs

@@ -659,7 +659,7 @@ describe('copyCommandsAsCopilotSkills', () => {
     assert.ok(skillContent.includes('description: Run all remaining phases autonomously'),
       'description preserved');
     // argument-hint present and double-quoted
-    assert.ok(skillContent.includes('argument-hint: "[--from N] [--only N] [--interactive]"'), 'argument-hint present and quoted');
+    assert.ok(skillContent.includes('argument-hint: "[--from N] [--to N] [--only N] [--interactive]"'), 'argument-hint present and quoted');
     // allowed-tools comma-separated
     assert.ok(skillContent.includes('allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task'),
       'allowed-tools is comma-separated');