gsd-auto

Automated GSD milestone development loop using GitHub Copilot CLI.

Install into any GSD project and run the full autonomous cycle repeatedly:

discuss → plan → execute → verify → ship

until the current milestone is complete.

Quick Start

# In any GSD project directory:
npx gsd-auto install

# Run the automation loop:
npx gsd-auto run

# Or directly:
./.scripts/gsd-auto/copilot/gsd-loop.sh

What It Does

The loop continuously:

1. Inspects .planning/ROADMAP.md and current phase state
2. Opens a new Copilot CLI session for each step/action
3. Executes phase workflow in order:
   • /gsd-discuss-phase N --auto
   • /gsd-plan-phase N --auto
   • /gsd-execute-phase N --no-transition
   • /gsd-verify-work N
   • /gsd-ship N --draft (default)
4. Moves to the next incomplete phase and repeats
5. Optionally runs milestone lifecycle when phases are done:
   • /gsd-audit-milestone
   • /gsd-complete-milestone

Defaults use GPT-5.3-Codex with xhigh reasoning effort.

Prerequisites

1. GitHub Copilot CLI installed and authenticated (copilot + login)
2. GSD installed in your target project (includes .planning/ and .github/get-shit-done/)
3. Node.js 20+

Commands

install

npx gsd-auto install
npx gsd-auto install /path/to/project
npx gsd-auto install --force

Installs automation assets to:

.scripts/gsd-auto/copilot/

run

npx gsd-auto run
npx gsd-auto run --max 120
npx gsd-auto run --model gpt-5.3-codex --reasoning-effort xhigh
npx gsd-auto run --step-timeout-minutes 0
npx gsd-auto run --verbose
npx gsd-auto run --dry

Useful flags:

• --skip-lifecycle
• --skip-discuss
• --skip-plan
• --skip-execute
• --skip-verify
• --skip-ship
• --retry-partial-verify (re-run verify repeatedly even if UAT is partial/manual)

status

npx gsd-auto status

Checks:

• Copilot CLI availability
• .planning existence
• gsd-tools availability
• Current next phase and progress counters

uninstall

npx gsd-auto uninstall

Removes .scripts/gsd-auto/copilot/ and managed .gitignore entries.

Direct Script Usage

After installation:

macOS / Linux

./.scripts/gsd-auto/copilot/gsd-loop.sh
./.scripts/gsd-auto/copilot/gsd-loop.sh 100 --verbose
./.scripts/gsd-auto/copilot/gsd-loop.sh 100 --dry

Windows PowerShell

.\.scripts\gsd-auto\copilot\gsd-loop.ps1
.\.scripts\gsd-auto\copilot\gsd-loop.ps1 -MaxIterations 100 -Verbose
.\.scripts\gsd-auto\copilot\gsd-loop.ps1 -Dry

Configuration

install creates:

.scripts/gsd-auto/copilot/gsd-auto-config.yaml

with project-specific defaults.

Environment Variables

| Variable | Default | Description | |---|---|---| | COPILOT_CLI | copilot | Copilot CLI command name | | COPILOT_MODEL | gpt-5.3-codex | Model for all Copilot sessions | | COPILOT_REASONING_EFFORT | xhigh | Reasoning effort for sessions | | ITERATION_DELAY | 8 | Delay (seconds) between loop iterations | | STEP_TIMEOUT_MINUTES | 0 | Timeout per Copilot step before fail/continue (0 disables timeout) | | MAX_STEP_TIMEOUT_MINUTES | 90 | Upper cap used by automatic timeout backoff | | STEP_TIMEOUT_BACKOFF_MULTIPLIER | 1.5 | Multiplier applied after timeout before retry | | FATAL_RETRY_LIMIT | 3 | Max retries for fatal steps before run aborts | | RETRY_PARTIAL_VERIFY | false | If true, keep re-running verify on partial/manual UAT |

Installed Files

.scripts/gsd-auto/copilot/
├── gsd-loop.sh
├── gsd-loop.ps1
├── gsd-auto-config.yaml
├── gsd-progress.log
├── gsd-run-state.json
└── prompts/
    ├── discuss.md
    ├── plan.md
    ├── execute.md
    ├── verify.md
    ├── ship.md
    ├── audit.md
    └── complete.md

Safety Features

• Max iterations cap (default 250)
• One fresh Copilot session per action
• Persistent execution log (gsd-progress.log)
• Dry-run mode (--dry)
• Non-fatal handling for verify/ship lifecycle steps when configured

Troubleshooting

If output appears stuck at a step (for example → discuss), use:

npx gsd-auto run --verbose

• --verbose streams Copilot output so you can see progress live.

By default, step timeout is disabled and runs can continue as long as needed.

If a phase UAT remains partial due to manual-only checks, gsd-auto now stops with a clear message (instead of looping verify forever). To force repeated unattended verify attempts anyway, use --retry-partial-verify.

If you want no timeout for long planning phases:

npx gsd-auto run --step-timeout-minutes 0 --verbose

gsd-auto now also auto-backs off timeout after a timeout event and stops after a retry limit to avoid endless timeout loops.

License

MIT