Contributing

​

Quick Links

​

Development Setup

​

Prerequisites

• Node.js 16+ (LTS recommended)
• Git
• Claude Code, OpenCode, Gemini CLI, or Codex installed
• Basic familiarity with shell scripting and JavaScript

​

Clone and Install

# Clone the repository
git clone https://github.com/glittercowboy/get-shit-done.git
cd get-shit-done

# Install dependencies (if any)
npm install

​

Local Testing

# Test Claude Code local install
node bin/install.js --claude --local

# Test OpenCode global install
node bin/install.js --opencode --global

# Test all runtimes
node bin/install.js --all --local

​

Verify Installation

# Claude Code
cd /path/to/test/project
claude
/gsd:help

# OpenCode
opencode
/gsd-help

# Codex
codex
$gsd-help

​

Project Structure

get-shit-done/
├── bin/
│   └── install.js              # Main installer script
├── commands/
│   └── gsd/                    # Command implementations
│       ├── new-project.md
│       ├── plan-phase.md
│       ├── execute-phase.md
│       └── ...
├── agents/
│   ├── gsd-executor/          # Execution agent
│   ├── gsd-planner/           # Planning agent
│   ├── gsd-verifier/          # Verification agent
│   └── ...
├── workflows/
│   ├── new-project.md         # Workflow orchestration
│   ├── plan-phase.md
│   └── ...
├── templates/
│   ├── PROJECT.md             # Document templates
│   ├── PLAN.md
│   └── ...
├── references/
│   ├── debugging.md           # Reference documentation
│   ├── checkpoints.md
│   └── ...
├── hooks/
│   ├── gsd-statusline.js      # Runtime hooks
│   ├── gsd-context-monitor.js
│   └── ...
├── lib/
│   └── gsd-tools.cjs          # Utility CLI
├── test/
│   └── *.test.cjs             # Test suite
├── CHANGELOG.md               # Release history
├── README.md                  # Main documentation
└── package.json

​

Key Components

​

Testing

​

Run Test Suite

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
node test/phase.test.cjs

​

Test Coverage

• Core utilities (config, state, roadmap parsing)
• Command dispatch and routing
• Frontmatter parsing and validation
• Phase/milestone management
• Windows/Unix path handling

npm run test:coverage
# Opens coverage/index.html

​

Manual Testing

1. Create a test project:
   Copy

   Ask AI

   mkdir test-project
   cd test-project
   git init
   
2. Install your local GSD:
   Copy

   Ask AI

   node /path/to/get-shit-done/bin/install.js --claude --local
   
3. Run a full workflow:
   Copy

   Ask AI

   claude --dangerously-skip-permissions
   /gsd:new-project
   # Answer questions
   /gsd:plan-phase 1
   /gsd:execute-phase 1
   
4. Verify outputs:
   • Check .planning/ files
   • Review git commits
   • Test generated code

​

Contribution Guidelines

​

Reporting Issues

• Search existing issues to avoid duplicates
• Verify you’re on the latest version: npx get-shit-done-cc@latest

• GSD version (check VERSION file in .claude/commands/gsd/ or similar)
• Runtime (Claude Code, OpenCode, Gemini CLI, Codex)
• Operating system (Mac, Linux, Windows, WSL)
• Command that failed (e.g., /gsd:execute-phase 1)
• Error messages or unexpected behavior
• Steps to reproduce

• Bug Report
• Feature Request

​

Submitting Pull Requests

1. Fork and clone:
   Copy

   Ask AI

   git clone https://github.com/YOUR_USERNAME/get-shit-done.git
   cd get-shit-done
   git checkout -b feature/your-feature-name
   
2. Make your changes:
   • Follow existing code style
   • Add tests for new functionality
   • Update documentation if needed
3. Test thoroughly:
   Copy

   Ask AI

   npm test
   npm run test:coverage
   
4. Commit with clear messages:
   Copy

   Ask AI

   git add .
   git commit -m "feat: add new feature X"
   
   Commit message format:
   • feat: New feature
   • fix: Bug fix
   • docs: Documentation changes
   • test: Test additions/changes
   • refactor: Code refactoring
   • chore: Maintenance tasks
5. Push and create PR:
   Copy

   Ask AI

   git push origin feature/your-feature-name
   
   Open a pull request on GitHub with:
   • Clear description of changes
   • Link to related issues
   • Screenshots/examples if applicable

​

Code Style

• Markdown commands/workflows: Use consistent heading levels, clear step numbering
• JavaScript/Node.js: Follow existing patterns in lib/gsd-tools.cjs and hooks
• XML prompts: Follow existing agent patterns with clear tags and structure
• Comments: Explain why, not what

​

Testing New Agents

1. Create agent directory:
   Copy

   Ask AI

   mkdir -p agents/gsd-newagent
   
2. Add agent file:
   • Include frontmatter (name, role, allowed-tools, skills)
   • Follow thin orchestrator pattern
   • Add comprehensive methodology section
3. Add tests:
   Copy

   Ask AI

   # Test frontmatter parsing
   node test/frontmatter.test.cjs
   
4. Test spawn:
   • Create a workflow that spawns your agent
   • Verify context loading and output format

​

Architecture Guidelines

​

Thin Orchestrator Pattern

• Parse arguments
• Load necessary context
• Spawn specialized agents
• Collect results
• Update state files
• Route to next step

• Complete methodology
• Domain expertise
• No external dependencies
• Fresh context per spawn

<!-- commands/gsd/example.md -->
# /gsd:example

**Parse args and load context:**
1. Extract phase number
2. Load PROJECT.md, STATE.md

**Spawn agent:**
```json
{
  "type": "task",
  "agent": "gsd-example-agent",
  "context": {
    "phase": "03",
    "project": "..."
  }
}

1. Validate output
2. Update STATE.md
3. Commit if needed

• If X, suggest /gsd:next-command

### Context Engineering

When designing features:

- **Size limits:** Keep files under limits where Claude's quality degrades
- **Frontmatter:** Use YAML frontmatter for machine-readable metadata
- **XML prompts:** Structure plans/tasks with clear XML tags
- **Dependency graphs:** Track what depends on what (frontmatter)
- **Fresh contexts:** Each agent gets clean 200K window

### State Management

Always update state through deterministic tools:

```bash
# Good: Use gsd-tools CLI
node ~/.claude/commands/gsd/lib/gsd-tools.cjs state update-progress 3 2

# Bad: Let agent edit STATE.md manually
# (Prone to parsing errors, corruption)

​

Documentation

• README.md: Update if it affects core workflow
• CHANGELOG.md: Add entry following Keep a Changelog format
• USER-GUIDE.md: Add to command reference and examples
• Inline docs: Update command help text

• Core docs: README.md, docs/USER-GUIDE.md
• Reference: references/ (debugging, checkpoints, etc.)
• Templates: templates/ (document templates)

​

Release Process

1. Update CHANGELOG.md:
   • Add version and date
   • List changes by category (Added, Changed, Fixed, Removed)
2. Bump version in package.json:
   Copy

   Ask AI

   npm version patch|minor|major
   
3. Tag release:
   Copy

   Ask AI

   git tag v1.X.Y
   git push origin v1.X.Y
   
4. Publish to npm:
   Copy

   Ask AI

   npm publish
   
5. Create GitHub release:
   • Copy changelog section
   • Attach any relevant files

​

Community Ports

• Runtime must support slash commands or equivalent
• Ability to spawn subagents with fresh context
• File system access (Read, Write, Edit)
• Git integration
• Bash/shell command execution

• gsd-opencode (now officially supported)
• gsd-gemini (archived, now officially supported)

• Open a GitHub Discussion
• Join Discord

​

License

​

Recognition

• GitHub Contributors
• Release notes for significant contributions
• CHANGELOG.md for bug fixes and features

​

Questions?