Claude-Code-Game-Studios/CONTRIBUTING.md

# Contributing to Claude Code Game Studios

CCGS is a coordination framework for indie game development using Claude Code.
Contributions are welcome — bug fixes, new skills that fill a real gap, agent
improvements, and hook fixes. PRs that don't fit the framework's direction will
be closed without lengthy explanation.

## What Makes a Good PR

- **Bug fixes** — something is broken, here's the fix
- **New skills** that address a workflow gap not already covered
- **Improvements** to existing agents, skills, or hooks
- **Documentation corrections** — wrong info, broken references, outdated steps

Feature requests submitted as PRs will be closed. Open an issue instead.

**What this repo isn't:**
CCGS is the system that helps you build games, not a place to store the games
you build with it. GDDs, ADRs, PRDs, game concepts, level designs, narrative
docs, or any other output generated by CCGS for your own project won't be
merged here — keep those in your own repo.

## The Non-Negotiable Technical Rules

These are the things that will get your PR rejected if you miss them.

**Skill files**
- Skills live in `.claude/skills/<name>/SKILL.md` — the subdirectory format is
  required. Flat `.md` files are silently ignored by Claude Code.
- SKILL.md must include YAML frontmatter: `name`, `description`,
  `argument-hint`, `allowed-tools`, and `model`
- Model tier: `haiku` for read-only status checks, `opus` for multi-document
  synthesis and phase gates, `sonnet` for everything else

**Hooks**
- Use `grep -E` — never `grep -P` (Perl regex breaks on Windows Git Bash)
- Include fallbacks for systems without `jq` or `python` installed
- Hooks run on every session start — they must exit quickly and gracefully
  (`exit 0`) when not applicable

**Agents**
- New agents must include a **Collaboration Protocol** section that describes
  how the agent asks questions and defers decisions to the user
- Agents must not modify files outside their documented domain without explicit
  user delegation

**Reference docs**
- If your PR adds or changes a skill, agent, or hook, update the matching
  reference doc (agent-roster, skills-reference, hooks-reference, or
  rules-reference). PRs that add things without updating the index will be
  sent back.

## The Collaborative Principle

CCGS is not an autonomous system. Every workflow follows:
**Question → Options → Decision → Draft → Approval → Write**

Skills and agents must ask before acting. Nothing writes to files without
explicit user confirmation. If your contribution has an agent making decisions
or writing files unilaterally, it won't be merged.

## Testing Your Changes

Run it in a Claude Code session and confirm it works end-to-end. For skills,
invoke the skill and verify the output matches what the skill claims to do.
For hooks, trigger the relevant event and confirm the hook fires correctly
and exits cleanly.

Include a brief note in your PR description describing what you tested and
what the output looked like.

## Commit Format

Use [Conventional Commits](https://www.conventionalcommits.org/):

```
feat: add /retrospective skill for end-of-sprint reviews
fix: correct grep -P usage in session-start hook
docs: update skills-reference with new /qa-plan entry
```

Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`

## PR Process

- Your PR will be auto-assigned to the maintainer via CODEOWNERS
- Reviews happen when they happen — this is a solo-maintained project
- If your PR sits open without feedback for a few weeks, a nudge comment is fine
- Merged contributors are credited in release notes

## Platform Compatibility

CCGS must work on Windows (Git Bash), macOS, and Linux. If your hook or
script uses anything platform-specific, it will be rejected. When in doubt,
test on Windows.