From 9153506fba066a4d426b21c11887db219dc866e8 Mon Sep 17 00:00:00 2001 From: Jeremy McSpadden Date: Tue, 24 Mar 2026 08:35:40 -0500 Subject: [PATCH] chore(contrib): add CODEOWNERS and team workflow docs (#2286) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore(contrib): add commit-msg hook, CODEOWNERS, team workflow docs - Extend install-hooks.sh with commit-msg hook that enforces Conventional Commits format on every commit - Add .github/CODEOWNERS mapping packages, CI, scripts, and security-sensitive files to @gsd-build/maintainers - CONTRIBUTING.md: add Branching and commits section with naming convention, commit format, and rebase guidance - CONTRIBUTING.md: add Working with GSD section covering mode: team, unique milestone IDs, and worktree isolation for multi-dev workflows - CONTRIBUTING.md: surface npm run secret-scan:install-hook in Local development with explanation of both hooks it installs - CONTRIBUTING.md: align AI disclosure section — no AI tool authorship in commits, Draft PR requirement for multi-phase agent work * chore: remove install-hooks.sh — local git hook installation is too intrusive for a contributor PR --- .github/CODEOWNERS | 36 ++++++++++++++++++++++ CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++- scripts/install-hooks.sh | 34 --------------------- 3 files changed, 99 insertions(+), 35 deletions(-) create mode 100644 .github/CODEOWNERS delete mode 100755 scripts/install-hooks.sh 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