Contributing to GSD-2

Contributing to GSD-2

We're glad you're here. GSD-2 is an open project and contributions are welcome across the entire codebase. We hold a high bar for what gets merged — not to be gatekeepers, but because every change ships to real users and stability matters.

Read [VISION.md](VISION.md) before contributing. It defines what GSD-2 is, what it isn't, and what we won't accept.

Before you start

1. Check existing issues. Someone may already be working on it.
2. Claim the issue. Comment on the issue to get it assigned to you before writing code. This prevents duplicate work and wasted effort.
3. No issue? Create one first for new features. Bug fixes for obvious problems can skip this step.
4. Architectural changes require an RFC. If your change touches core systems (auto-mode, agent-core, orchestration), open an issue describing your approach and get approval before writing code. We use Architecture Decision Records (ADRs) for significant decisions.

Branching and commits

Always work on a dedicated branch. Never push directly to `main`.

**Branch naming:** `/`

Type	When to use
feat/	New functionality
fix/	Bug or defect correction
refactor/	Code restructuring, no behavior change
test/	Adding or updating tests
docs/	Documentation only
chore/	Dependencies, tooling, housekeeping
ci/	CI/CD configuration

**Commit messages** must follow [Conventional Commits](https://www.conventionalcommits.org/). The commit-msg hook enforces this locally; CI enforces it on push.

(): 

Valid types: `feat` `fix` `docs` `chore` `refactor` `test` `infra` `ci` `perf` `build` `revert`

feat(pi-agent-core): add streaming output for long-running tasks
fix(pi-ai): resolve null pointer on empty provider response
chore(deps): bump typescript from 5.3.0 to 5.4.2

Keep branches current by rebasing onto `main` — do not merge `main` into your feature branch:

git fetch origin
git rebase origin/main

Working with GSD (team workflow)

GSD uses worktree-based isolation for multi-developer work. If you're contributing with GSD running, enable team mode in your project preferences:

# .gsd/PREFERENCES.md
---
version: 1
mode: team
---

This enables unique milestone IDs, branch pushing, and pre-merge checks — preventing milestone ID collisions when multiple contributors run auto-mode simultaneously. Each developer gets their own isolated worktree; squash merges to `main` happen independently.

For full details see [docs/working-in-teams.md](docs/working-in-teams.md) and [docs/git-strategy.md](docs/git-strategy.md).

Opening a pull request

PR description format

Every PR needs a **TL;DR** and a **detailed explanation**. Use this structure:

## TL;DR

**What:** One sentence — what does this change?
**Why:** One sentence — why is it needed?
**How:** One sentence — what's the ap