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

undefined

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