Contributing to DinoStack

How the repo is structured and how to make changes safely

What you can contribute

Rules & references
Bug fixes, clarifications, or new protocols. Make existing rules more precise or add new reference docs.
Agents & commands
New named agents, new slash commands, or improvements to existing ones.
Adapters
New tool support or improvements to existing adapters. 11 ship today: Claude Code, Codex, Cursor, Gemini, Hermes, Kimi, omp, OpenClaw, OpenCode, Pi, VS Code Copilot.

The golden rule: edit in content/

The content/ directory is the single source of truth. Adapter files (.claude/, .cursor/, etc.) are generated outputs - never edit them directly.

content/
  rules/        3 rule files (module-manifest, code-standards, conventions)
  references/   41 reference docs (agent-team, base-branch-sync, skeptic-protocol,
                    qa-gate, capability-preflight, events-log, planning-artifacts, ...)
  commands/     27 command files (ds-implement-ticket, ds-init-project, ds-wrap, ds-brief, ...)
  agents/       18 agent definitions (architect, engineer, skeptic, qa-engineer, ...)
  fragments/    shared wording kernels transcluded into multiple agents/*.md files

Build scripts regenerate adapter files from content/. The pre-commit hook stamps shared agent-check fragments (scripts/stamp-agent-fragments.sh), then runs all 11 adapter builds automatically when content/ files are staged. Slide .md sources have a separate slides-sync CI gate: after editing, run bash scripts/build-slides.sh and commit the regenerated .html.

Never edit generated files directly - the pre-commit hook or CI will overwrite them. Always edit the source in content/ (adapter files), docs/slides/ (slide sources), or content/fragments/ (never the interior of a <!-- shared:id --> span in an agent file).

How the build pipeline works

11 adapters ship build scripts: .claude/, .codex/, .copilot/, .cursor/, .gemini/, .hermes/, .kimi/, .omp/, .openclaw/, .opencode/, .pi/. Each build.sh transforms content/ into the tool's native format.

  • .claude/build.sh - prepends the /dinostack prerequisite to commands; symlinks rules, references, agents directly into content/
  • .cursor/build.sh - combines YAML frontmatter sidecars with rule content to produce .mdc files; copies references and commands
  • Other adapters - each converts content into their tool's format per that tool's conventions

The pre-commit hook stamps shared agent-check fragments, then runs ALL 11 builds when content/ files are staged - a single missed build fails the adapter-sync CI gate, and a missed stamp fails the agent-fragment-sync CI gate. Run bash scripts/build-slides.sh separately for slide changes (enforced by the slides-sync CI gate).

The build is idempotent. Running install.sh re-runs all builds automatically. You must run ALL 11 builds before committing content/ changes or CI will fail.

PR workflow

  1. Pull before you change anything - git fetch origin && git pull --rebase origin main
  2. Create a feature branch from main
  3. Edit in content/ - the pre-commit hook stamps shared fragments and rebuilds all 11 adapter files on commit
  4. If you edited a slide .md, run bash scripts/build-slides.sh and commit the .html too
  5. Test locally: re-run install.sh, open a session, verify the change works
  6. Sign off every commit - git commit -s (DCO, enforced by .github/workflows/dco.yml)
  7. Protocol changes go through a protocol-change RFC first - open an issue before the PR
  8. Open a PR - one concern per PR, describe the why in the body
  9. PR is merged by the lead maintainer after review
Pull-before-edit is especially important here. This repo sees active refactors - file renames, symlink restructures, directory reshapes. A stale local branch turns clean edits into hand-merges.

Creating a new adapter

  1. Create .<toolname>/ matching the tool's config directory convention
  2. Convert the 3 rules into the tool's native rule format (from content/rules/)
  3. Copy or symlink the 41 reference docs (from content/references/)
  4. Convert the 27 commands into the tool's command format (from content/commands/)
  5. Wire up lifecycle hooks - risk reminder (before prompt) and context save (on stop)
  6. Write .<toolname>/README.md with setup instructions
  7. Update root README.md with the new adapter
Adapters translate format, not substance. If a rule doesn't apply to your tool, keep the rule but note the limitation in the adapter's README.

Edit content. Build adapters. Test locally.

One source of truth, many delivery formats.

github.com/Space-Dinosaurs/DinoStack