diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..f54b9a409 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,36 @@ +# CODEOWNERS +# Defines required reviewers per path. GitHub enforces these on PRs. +# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +# +# Format: <@user or @org/team> +# Last matching rule wins. + +# Default: maintainers review everything not explicitly matched below +* @gsd-build/maintainers + +# Core agent orchestration — RFC required, senior review only +packages/pi-agent-core/ @gsd-build/maintainers +src/resources/extensions/gsd/ @gsd-build/maintainers + +# AI/LLM provider integrations +packages/pi-ai/ @gsd-build/maintainers + +# Terminal UI +packages/pi-tui/ @gsd-build/maintainers + +# Native bindings — platform-specific, needs careful review +native/ @gsd-build/maintainers + +# CI/CD and release pipeline — high blast radius +.github/ @gsd-build/maintainers +scripts/ @gsd-build/maintainers +Dockerfile @gsd-build/maintainers + +# Security-sensitive files — always require maintainer sign-off +.secretscanignore @gsd-build/maintainers +scripts/secret-scan.sh @gsd-build/maintainers +scripts/install-hooks.sh @gsd-build/maintainers + +# Contributor-facing docs — keep accurate, maintainers approve +CONTRIBUTING.md @gsd-build/maintainers +VISION.md @gsd-build/maintainers diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index acf637fc2..46690bec6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,59 @@ Read [VISION.md](VISION.md) before contributing. It defines what GSD-2 is, what 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: + +```bash +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: + +```yaml +# .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 @@ -65,10 +118,12 @@ If your PR changes any public API, CLI behavior, config format, or file structur 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. +- **Disclose it.** Note that the PR is AI-assisted in your description. Do not credit the AI tool as an author or co-author in the commit or PR. - **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 agents opening PRs must follow the same workflow as human contributors: clean working tree, new branch per task, CI passing before requesting review. Multi-phase work should start as a Draft PR and only move to Ready when complete. + AI PRs go through the same review process as any other PR. No special treatment in either direction. ## Architecture guidelines @@ -109,6 +164,9 @@ PRs go through automated review first, then human review. To help us review effi # Install dependencies npm ci +# Install git hooks (secret scanning + commit message validation) +npm run secret-scan:install-hook + # Build npm run build @@ -119,6 +177,10 @@ npm test npx tsc --noEmit ``` +Run `npm run secret-scan:install-hook` once after cloning. It installs two hooks: +- **pre-commit** — blocks commits containing hardcoded secrets or credentials +- **commit-msg** — validates Conventional Commits format before the commit lands + CI must pass before your PR will be reviewed. Run these locally to save time. ## Security diff --git a/scripts/install-hooks.sh b/scripts/install-hooks.sh deleted file mode 100755 index 30bfd629e..000000000 --- a/scripts/install-hooks.sh +++ /dev/null @@ -1,34 +0,0 @@ -#!/usr/bin/env bash -# Installs the git pre-commit hook for secret scanning. -# Safe to run multiple times — only installs if not already present. - -set -euo pipefail - -HOOK_DIR="$(git rev-parse --git-dir)/hooks" -HOOK_FILE="$HOOK_DIR/pre-commit" -MARKER="# gsd-secret-scan" - -mkdir -p "$HOOK_DIR" - -# Check if our hook is already installed -if [[ -f "$HOOK_FILE" ]] && grep -q "$MARKER" "$HOOK_FILE" 2>/dev/null; then - echo "secret-scan pre-commit hook already installed." - exit 0 -fi - -# If a pre-commit hook already exists, append; otherwise create -if [[ -f "$HOOK_FILE" ]]; then - echo "" >> "$HOOK_FILE" - echo "$MARKER" >> "$HOOK_FILE" - echo 'bash "$(git rev-parse --show-toplevel)/scripts/secret-scan.sh"' >> "$HOOK_FILE" - echo "secret-scan appended to existing pre-commit hook." -else - cat > "$HOOK_FILE" << 'EOF' -#!/usr/bin/env bash -# gsd-secret-scan -# Pre-commit hook: scan staged files for hardcoded secrets -bash "$(git rev-parse --show-toplevel)/scripts/secret-scan.sh" -EOF - chmod +x "$HOOK_FILE" - echo "secret-scan pre-commit hook installed." -fi