diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ae3a26a05..e8dbfe9c0 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,23 @@ -## Summary - +## TL;DR -- +**What:** +**Why:** +**How:** -## Motivation - +## What -Closes # + + +## Why + + + +## How + + ## Change type - + - [ ] `feat` — New feature or capability - [ ] `fix` — Bug fix - [ ] `refactor` — Code restructuring (no behavior change) @@ -18,32 +26,27 @@ Closes # - [ ] `chore` — Build, CI, or tooling changes ## Scope - + - [ ] `pi-tui` — Terminal UI - [ ] `pi-ai` — AI/LLM layer - [ ] `pi-agent-core` — Agent orchestration - [ ] `pi-coding-agent` — Coding agent -- [ ] `gsd extension` — GSD workflow (`src/resources/extensions/gsd/`) +- [ ] `gsd extension` — GSD workflow - [ ] `native` — Native bindings - [ ] `ci/build` — Workflows, scripts, config ## Breaking changes - + - [ ] No breaking changes -- [ ] Yes — describe below: +- [ ] Yes — described above ## Test plan - -- [ ] Unit tests added/updated (`npm run test:unit`) -- [ ] Integration tests added/updated (`npm run test:integration`) -- [ ] Manual testing — describe steps: -- [ ] No tests needed — explain why: -## Rollback plan - -- [ ] Safe to revert (no migrations, no state changes) -- [ ] Requires steps — describe: +- [ ] CI passes +- [ ] New/updated tests included +- [ ] Manual testing — steps described above +- [ ] No tests needed — explained above -## Release context - -- **Target**: +## AI disclosure + +- [ ] This PR includes AI-assisted code diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..59eaefba8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# 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. + +## 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 approach? + +## What + +Detailed description of the change. What files, modules, or systems are affected? + +## Why + +The motivation. What problem does this solve? What was broken, missing, or suboptimal? +Link issues where applicable: `Closes #123` + +## How + +The approach. How does the implementation work? What were the key decisions? +If this is a non-trivial change, explain the design and any alternatives you considered. +``` + +### Requirements + +- **CI must pass.** If your PR breaks tests, fix them before requesting review. +- **One concern per PR.** A bug fix is a bug fix. A feature is a feature. Don't bundle unrelated changes. +- **No drive-by formatting.** Don't reformat code you didn't change. Don't reorder imports in files you're not modifying. +- **Link issues when relevant.** Not mandatory for every PR, but if an issue exists, reference it. + +### Change type checklist + +Include in your PR: + +- [ ] `feat` — New feature or capability +- [ ] `fix` — Bug fix +- [ ] `refactor` — Code restructuring (no behavior change) +- [ ] `test` — Adding or updating tests +- [ ] `docs` — Documentation only +- [ ] `chore` — Build, CI, or tooling changes + +### Breaking changes + +If your PR changes any public API, CLI behavior, config format, or file structure, say so explicitly. Breaking changes need extra scrutiny and may need migration guidance. + +## AI-assisted contributions + +AI-generated PRs are first-class citizens here. We welcome them. We just ask for transparency: + +- **Disclose it.** Note that the PR is AI-assisted in your description. +- **Test it.** AI-generated code must be tested to the same standard as human-written code. "The AI said it works" is not a test plan. +- **Understand it.** You should be able to explain what the code does and why. If a reviewer asks a question, "I'll ask the AI" is not an answer. + +AI PRs go through the same review process as any other PR. No special treatment in either direction. + +## Architecture guidelines + +Before writing code, understand these principles: + +- **Extension-first.** Can this be an extension instead of a core change? If yes, build it as an extension. +- **Simplicity wins.** Don't add abstractions, helpers, or utilities for one-time operations. Don't design for hypothetical future requirements. +- **Tests are the contract.** Changed behavior? The test suite tells you what you broke. + +See [VISION.md](VISION.md) for the full list of what we won't accept. + +## Scope areas + +The codebase is organized into these areas. All are open to contributions: + +| Area | Path | Notes | +|------|------|-------| +| Terminal UI | `pi-tui` | Components, themes, rendering | +| AI/LLM layer | `pi-ai` | Provider integrations, model handling | +| Agent core | `pi-agent-core` | Agent orchestration — RFC required for changes | +| Coding agent | `pi-coding-agent` | The main coding agent | +| GSD extension | `src/resources/extensions/gsd/` | GSD workflow — RFC required for auto-mode | +| Native bindings | `native/` | Platform-specific native code | +| CI/Build | `.github/`, `scripts/` | Workflows, build scripts | + +## Review process + +PRs go through automated review first, then human review. To help us review efficiently: + +- Keep PRs focused and reasonably sized. Massive PRs take longer to review and are more likely to be sent back. +- Respond to review comments. If you disagree, explain why — discussion is welcome. +- If your PR has been open for a while without review, ping in Discord. We're a small team and things slip. + +## Local development + +```bash +# Install dependencies +npm ci + +# Build +npm run build + +# Run tests +npm test + +# Type check +npx tsc --noEmit +``` + +CI must pass before your PR will be reviewed. Run these locally to save time. + +## Security + +If you find a security vulnerability, **do not open a public issue.** Email the maintainers directly or use GitHub's private vulnerability reporting. See the supply chain attack on GSD-1 (PR #1232) for why this matters. + +## Questions? + +Open a discussion on GitHub or ask in the Discord `#maintainers` channel. diff --git a/VISION.md b/VISION.md new file mode 100644 index 000000000..da201bb17 --- /dev/null +++ b/VISION.md @@ -0,0 +1,37 @@ +# Vision + +GSD-2 is the orchestration layer between you and AI coding agents. It handles planning, execution, verification, and shipping so you can focus on what to build, not how to wrangle the tools. + +## Who it's for + +Anyone who codes with AI agents — solo developers shipping faster, open-source maintainers handling scale, vibe coders who think in outcomes. GSD adapts to skill level and workflow. + +## Principles + +**Extension-first.** If it can be an extension, it should be. Core stays lean. New capabilities belong in extensions, skills, and plugins unless they fundamentally require core integration. + +**Simplicity over abstraction.** The codebase was aggressively cleaned up. Every line earns its place. Don't add helpers, utilities, or abstractions unless they eliminate real duplication or solve a real problem. Three similar lines of code is better than a premature abstraction. + +**Tests are the contract.** If you change behavior, the tests tell you what you broke. Write tests for new behavior. Trust the test suite. + +**Ship fast, fix fast.** Get it out, iterate quickly, don't let perfect be the enemy of good. Every release should work, but we'd rather ship and patch than delay and accumulate. + +**Provider-agnostic.** GSD works with any LLM provider. No architectural decisions should privilege one provider over another. + +## What we won't accept + +These save everyone time. Don't open PRs for: + +- **Enterprise patterns.** Dependency injection containers, abstract factories, strategy-pattern-for-the-sake-of-it, over-engineered config systems. This is a CLI tool, not a Spring application. + +- **Framework swaps.** Rewriting working code in a different library or framework without a clear, measurable improvement in performance or maintainability. "I prefer X" is not sufficient motivation. + +- **Cosmetic refactors.** Renaming variables to your preferred style, reordering imports, reformatting code that works. This is pure churn that creates merge conflicts and review burden for zero user value. + +- **Complexity without user value.** If a change adds abstraction, indirection, or configuration but doesn't improve something a user can see or feel, it doesn't belong here. + +- **Heavy orchestration layers.** Don't duplicate what the agent infrastructure already provides. Build on top of it, don't wrap it. + +## Relationship to GSD-1 + +GSD-2 is the future. GSD-1 continues to serve its community but GSD-2 is where active development, new features, and architectural investment happen. The goal is to eventually migrate GSD-1 users to GSD-2.