docs: add VISION.md, CONTRIBUTING.md, and update PR template (#1506)

Establishes contributor guidelines based on maintainer team discussion.
VISION.md defines project identity, principles, and explicit rejection
criteria. CONTRIBUTING.md covers assign-then-PR workflow, RFC process
for architectural changes, AI disclosure policy, and testing standards.
PR template restructured around TL;DR + What/Why/How format.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,15 +1,23 @@
-## Summary
-<!-- What does this PR do? 1-3 bullet points. -->
+## TL;DR
 
--
+**What:** <!-- One sentence — what does this change? -->
+**Why:** <!-- One sentence — why is it needed? -->
+**How:** <!-- One sentence — what's the approach? -->
 
-## Motivation
-<!-- Why is this change needed? Link issues if applicable. -->
+## What
 
-Closes #
+<!-- Detailed description of the change. What files, modules, or systems are affected? -->
+
+## Why
+
+<!-- The motivation. What problem does this solve? Link issues: Closes #123 -->
+
+## How
+
+<!-- The approach. How does the implementation work? Key decisions and alternatives considered? -->
 
 ## Change type
-<!-- Check one: -->
+
 - [ ] `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
-<!-- Which packages/areas does this touch? Check all that apply. -->
+
 - [ ] `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
-<!-- Does this change any public API, CLI behavior, config format, or file structure? -->
+
 - [ ] No breaking changes
-- [ ] Yes — describe below:
+- [ ] Yes — described above
 
 ## Test plan
-<!-- How was this tested? Check all that apply. -->
-- [ ] 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
-<!-- If this causes issues in production, how do we revert safely? -->
-- [ ] 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
-<!-- What branch does this PR target? -->
-- **Target**: <!-- e.g., milestone/2.15.x or main -->
+## AI disclosure
+
+- [ ] This PR includes AI-assisted code <!-- If so, note the tool and what was tested -->

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.

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.