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:

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.