96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
# 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.
|