Skip to content
BranchesTags
 
 

Repository files navigation

GSD — Get Shit Done for GitHub Copilot CLI

Development stopped on this project for now, i made this instead https://gist.github.com/japperJ/cdeaa98b5d7dd612d525d73bdc456e28

A spec-driven development workflow with native Copilot CLI integration

Based on gsd-opencode by TÂCHES & rokicool.

License

What's New in v0.4.0

Project lifecycle management

  • gsd add-feature — Add features to existing projects with lightweight questioning, appends requirements + phases
  • gsd add-phase / gsd insert-phase — Append or insert phases (decimal numbering for urgent work)
  • gsd new-milestone — Start new milestone cycle with full questioning → requirements → roadmap flow
  • gsd complete-milestone — Archive milestones to .planning/milestones/, git tag, collapse completed phases
  • Milestone-scoped requirements — REQUIREMENTS.md is per-milestone; archived on completion
  • Continuous phase numbering — Phase numbers never reset across milestones

Previous Versions

  • v0.3.0 — Constitution, scientific debugging, pause/resume, 3-level verification, planner-checker loop, deviation rules, auto-test loop, pro install tier

Quick Start

# From your project directory, clone and install
cd your-project
git clone https://github.com/japperJ/gsd-opencode
node gsd-opencode/gsd-copilot-cli/bin/install.js --minimal

# Start Copilot CLI
copilot

# Say GSD commands conversationally:
> gsd new-project
> gsd plan-phase 1
> gsd execute-phase 1

Recommended model: Claude Sonnet 4.5 or higher. Smaller models may hallucinate shell commands instead of using proper file tools. Use /model to check/switch models.

Future: Once published to npm, you'll be able to run npx gsd-copilot-cli.

How It Works

GSD uses the AGENTS.md standard — the cross-tool format recognized by Copilot CLI, Claude Code, and others.

your-project/
├── AGENTS.md                          # Primary GSD instructions
└── .github/                           # (Full install only)
    ├── instructions/
    │   └── gsd-planning.instructions.md  # Path-specific for .planning/**
    └── hooks/
        └── gsd-hooks.json             # Workflow automation

Instruction Discovery Order

Copilot CLI reads instructions in this order:

  1. ~/.copilot/copilot-instructions.md — Global (all sessions)
  2. .github/copilot-instructions.md — Repository-wide
  3. .github/instructions/**/*.instructions.md — Path-specific
  4. AGENTS.md (Git root or cwd) — ← GSD uses this
  5. CLAUDE.md, GEMINI.md, CODEX.md — Also supported

Available Commands

Say this... What happens Native feature used
gsd new-project Questioning → research → requirements → roadmap Custom workflow
gsd add-feature [desc] Add feature to existing project (lightweight questioning) Custom workflow
gsd add-phase [desc] Append phase to end of current roadmap Custom workflow
gsd insert-phase [after] [desc] Insert urgent phase with decimal numbering (e.g., 3.1) Custom workflow
gsd new-milestone [name] Start new milestone cycle (continues phase numbering) Custom workflow
gsd complete-milestone [ver] Archive milestone, git tag, prepare for next Custom workflow
gsd plan-phase 1 Research phase, then create structured plan /plan
gsd execute-phase 1 Execute tasks with atomic commits + auto-test File editing
gsd verify-work 1 3-level artifact verification + code review /review
gsd constitution Set project principles and coding standards Custom workflow
gsd debug [issue] Scientific debugging with persistent state Custom workflow
gsd pause / resume Save/restore work state across sessions Custom workflow
gsd delegate-task Offload work to async coding agent /delegate
gsd progress Show current status and next action File reading
gsd quick [task] Execute small ad-hoc task Direct execution
gsd help Show all commands -

Core Workflow

gsd new-project → gsd plan-phase 1 → gsd execute-phase 1 → gsd verify-work 1 → repeat
     ↓
  (optional: gsd constitution — can also run anytime)

Note: gsd constitution is optional. During gsd new-project you're asked if you want to set project principles. You can skip it and run gsd constitution later anytime.

Adding to Existing Projects

gsd add-feature → appends requirements + phases to existing project
gsd add-phase   → appends a single phase to the roadmap
gsd insert-phase → inserts urgent work with decimal numbering (e.g., 3.1)

Milestone Lifecycle

gsd new-project → ... → gsd complete-milestone → gsd new-milestone → ...
  • gsd complete-milestone archives the current milestone (roadmap + requirements) to .planning/milestones/, creates a git tag, and collapses the roadmap entry.
  • gsd new-milestone starts a fresh cycle (questioning → research → requirements → roadmap) with phase numbering continuing from where it left off.

1. Initialize Project (gsd new-project)

  1. Deep questioning until the project is understood
  2. Research the domain (optional)
  3. Extract requirements (v1 vs v2 vs out of scope)
  4. Create roadmap with phases

Creates: .planning/PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md

2. Plan Phase (gsd plan-phase 1)

Uses Copilot CLI''s native /plan command:

  1. Reads phase requirements from ROADMAP.md
  2. Researches implementation approach
  3. Executes /plan to create structured plan with checkboxes
  4. Saves to .planning/phases/01-name/01-01-PLAN.md

3. Execute Phase (gsd execute-phase 1)

  1. Reads each plan file
  2. Executes tasks sequentially
  3. Commits atomically after each task
  4. Creates summary in SUMMARY.md
  5. Updates STATE.md

4. Verify Work (gsd verify-work 1)

Uses Copilot CLI''s native /review command with GSD-specific criteria.

Native CLI Features You Should Know

Feature What it does When to use
/plan Creates implementation plan with checkboxes Complex features
/review Analyzes code changes Before merging
/delegate Offloads to cloud coding agent Async/parallel work
/context Shows token usage Monitor context
/compact Summarizes conversation Long sessions
/session plan View current plan Check progress
Shift+Tab Toggle plan mode Complex work
@filename Include file in context Reference code

File Structure

After gsd new-project:

your-project/
├── AGENTS.md                  # GSD workflow instructions
└── .planning/
    ├── CONSTITUTION.md       # Project principles & standards
    ├── PROJECT.md            # Project vision
    ├── REQUIREMENTS.md       # Scoped requirements (current milestone)
    ├── ROADMAP.md            # Phases (completed milestones collapsed)
    ├── STATE.md              # Project memory (update frequently!)
    ├── debug/                # Debug sessions (gsd debug)
    ├── milestones/           # Archived milestone artifacts
    │   ├── v1.0-ROADMAP.md
    │   └── v1.0-REQUIREMENTS.md
    └── phases/
        ├── 01-foundation/
        │   ├── 01-RESEARCH.md
        │   ├── 01-01-PLAN.md
        │   ├── 01-01-SUMMARY.md
        │   └── 01-VERIFICATION.md
        └── 02-features/
            └── ...

Installation Options

Note: Package not yet published to npm. Use the local install method below.

# From your project directory:
git clone https://github.com/japperJ/gsd-opencode

# Interactive (prompts for choice)
node gsd-opencode/gsd-copilot-cli/bin/install.js

# Minimal — AGENTS.md only (recommended)
node gsd-opencode/gsd-copilot-cli/bin/install.js --minimal

# Pro — AGENTS.md + advanced instruction files (verification, execution, debugging)
node gsd-opencode/gsd-copilot-cli/bin/install.js --pro

# Full — Pro + hooks (experimental)
node gsd-opencode/gsd-copilot-cli/bin/install.js --full

# Legacy — copilot-instructions.md (v0.1 compatibility)
node gsd-opencode/gsd-copilot-cli/bin/install.js --legacy

# Add --yolo to auto-approve all tool execution (optional)
node gsd-opencode/gsd-copilot-cli/bin/install.js --minimal --yolo

Future: Once published to npm, you'll be able to use npx gsd-copilot-cli.

Installation Tiers Explained

Minimal — Single-file setup

  • Copies only AGENTS.md with the entire GSD workflow
  • Copilot CLI reads this one file to understand all commands
  • Lightest weight, works everywhere Copilot CLI is installed
  • Recommended for getting started

Pro — Modular instructions (recommended for sustained work)

  • Copies AGENTS.md (same as Minimal)
  • PLUS 4 modular instruction files in .github/instructions/
  • Each file handles one area: planning, verification, execution, debugging
  • Copilot CLI auto-loads these files based on path patterns (no manual intervention)
  • Benefit: Keeps AGENTS.md lean (486 lines instead of bloated) while providing full feature set
  • Best balance of features and efficiency

Full — Pro + workflow automation (experimental)

  • Same as Pro
  • PLUS gsd-hooks.json for automatic triggers
  • Hooks can run commands on Copilot CLI events (e.g., "when user says X, run Y first")
  • Marked experimental because hook behavior varies across Copilot CLI versions
  • Only use if you want to experiment with automation

Legacy — v0.1 compatibility

  • Single file copilot-instructions.md in repo root
  • Old instruction format that Copilot CLI still recognizes
  • Provided for backwards compatibility with older setups

What Each Option Creates

Minimal (recommended):

└── AGENTS.md

Pro:

├── AGENTS.md
└── .github/instructions/
    ├── gsd-planning.instructions.md       # Path-specific for .planning/**
    ├── gsd-verification.instructions.md   # 3-level artifact verification
    ├── gsd-execution.instructions.md      # Deviation rules + auto-test
    └── gsd-debugging.instructions.md      # Scientific debugging

Full: Experimental — hooks may behave inconsistently

├── (everything in Pro)
└── .github/hooks/
    └── gsd-hooks.json                     # Session start/post-tool hooks

Legacy:

└── copilot-instructions.md

Comparison: GSD Implementations

Feature Claude Code OpenCode Copilot CLI
Commands /gsd-* slash /gsd-* slash Conversational
Multi-agent ✓ Task tool ✓ Task tool ✗ Single context
Native planning ✗ ✗ ✓ /plan built-in
Native review ✗ ✗ ✓ /review built-in
Delegation ✗ ✗ ✓ /delegate built-in
Path-specific ✗ ✗ ✓ .instructions.md files
Hooks ✗ ✗ ✓ .github/hooks/

When to Use Which

Use Case Recommended
Complex multi-agent orchestration Claude Code or OpenCode
Native planning + review + delegation Copilot CLI
Path-specific instructions Copilot CLI
Workflow hooks/automation Copilot CLI
Already using Copilot CLI Copilot CLI

Repository Structure

gsd-opencode/
├── gsd-copilot-cli/          # The npm package
│   ├── templates/
│   │   ├── AGENTS.md                              # Core GSD workflow
│   │   └── .github/
│   │       ├── instructions/
│   │       │   ├── gsd-planning.instructions.md   # Path-specific
│   │       │   ├── gsd-verification.instructions.md # 3-level verification
│   │       │   ├── gsd-execution.instructions.md  # Deviation rules
│   │       │   └── gsd-debugging.instructions.md  # Scientific debugger
│   │       └── hooks/
│   │           └── gsd-hooks.json                 # Automation
│   ├── copilot-instructions.md                    # Legacy format
│   ├── bin/install.js
│   └── package.json
├── gsd-opencode/             # Original OpenCode version (submodule)
├── original/                  # Original TÂCHES version (submodule)
├── CLAUDE.md                 # Project instructions
└── README.md                 # This file

Development

Cloning with Submodules

git clone https://github.com/japperJ/gsd-opencode
cd gsd-opencode
git submodule update --init --recursive

Testing Locally

cd gsd-copilot-cli
node bin/install.js --minimal

Troubleshooting

"Copilot doesn''t recognize GSD commands"

  • Ensure AGENTS.md exists in project root
  • Try /init to reload instructions
  • Rephrase: "run the gsd new-project workflow"

"Context getting too long"

  • Use /compact to summarize
  • Use /context to check usage
  • Start fresh with /clear

"Native /plan doesn''t match GSD format"

  • GSD plan-phase uses /plan internally but saves to .planning/ format
  • The workflow adapts native output to GSD structure

"Hooks not running"

  • Hooks must be in .github/hooks/ directory
  • Check JSON syntax: cat .github/hooks/gsd-hooks.json | jq .
  • Hooks only run with --full installation

Credits

  • TÂCHES — Original Get Shit Done for Claude Code
  • rokicool — gsd-opencode adaptation for OpenCode
  • GitHub — Copilot CLI native features (/plan, /review, /delegate)

v0.3.0 inspired by:

  • SpecKit — Constitution concept, spec-driven philosophy
  • oh-my-opencode — Persistence patterns, session management
  • Aider — Auto-test loop, repo-map awareness
  • PIV-SpecKit — Adaptive learning, auto-prime context

License

MIT License. See LICENSE for details.

Further Reading

GSD for GitHub Copilot CLI — native integration, spec-driven development

About

Get-Shit-Done by TACHES for OpenCode with some addons and for copilot-cli

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages