Your First PR to Colibri

New here? This guide walks you through making your first contribution to Colibri in under 30 minutes.

What Colibri is (in 30 seconds)

Colibri is a documentation-first TypeScript MCP orchestration runtime. As of R75 Wave I (April 2026), Phase 0 is 100% on non-deferred tasks (28 of 28 shipped) — P0.5.1/P0.5.2 shipped as δ library-only stubs per ADR-005 §Decision — with a live 14-tool stdio MCP server and 1084 passing tests. Most newcomer-friendly contributions are still documentation, diagrams, or spec refinements — those require no local build. For code contributions, see CLAUDE.md §5 for the build && lint && test gate.

First PR = docs. No build environment needed.

Pick a starter task (5 minutes)

Choose one of these no-prerequisite contributions:

1. Fix a typo — Find and fix a typo in any doc under docs/. Easy win.
2. Add a missing term to the glossary — Read docs/reference/glossary.md and add a term you think is missing.
3. Add a Mermaid diagram — Pick a concept doc (under docs/3-world/ or docs/2-plugin/) without a diagram and add one.
4. Cross-link two docs — Find two related docs that should reference each other and add wikilinks.
5. Expand a tool reference — Add a request/response example to one tool in docs/reference/mcp-tools-phase-0.md.
6. Add an FAQ — Pick a doc with no FAQ section and add one with 3 questions you would have asked yourself reading it.

Set up your fork (5 minutes)

gh repo fork LastEld/AMS --clone
cd AMS
git checkout -b docs/your-contribution-name

Or with git:

git clone https://github.com/YOUR-USERNAME/AMS.git
cd AMS
git remote add upstream https://github.com/LastEld/AMS.git
git checkout -b docs/your-contribution-name

Make your change (10 minutes)

1. Open the file in your editor
2. Make the change
3. Make sure any wikilinks resolve (no broken [[link]])
4. Save

Verify locally (5 minutes)

If you have Ruby installed:

cd docs
bundle install
bundle exec jekyll serve

Otherwise, GitHub will build and preview for you.

Submit the PR (5 minutes)

git add -A
git commit -m "docs: <your one-line summary>"
git push origin docs/your-contribution-name

Then open a PR via the GitHub UI. Use the PR template — fill in the task field as docs/first-pr if you’re not working from a tracked task.

What happens next

• CI will run docs-integrity checks (links, frontmatter, wikilinks)
• A maintainer will review within 48 hours
• Small docs PRs are usually merged same-day

Common first-PR pitfalls

• Broken wikilinks — [[broken-link]] will fail CI. Always verify the target exists.
• Missing frontmatter — New files need YAML frontmatter with at least tags: and created:.
• Editing main checkout — Don’t! Use a feature branch. Claude sessions must go further: always work inside .worktrees/claude/<task-slug>, never on main. See CLAUDE.md §3.
• Adding files outside docs/ — Most first PRs should only touch docs/ and possibly README.md.
• Citing stale donor facts — The repo’s history includes the donor AMS runtime (pre-R53), which had a 78-table schema, 11-middleware chain, src/server.js entry point, and ~480-tool surface. None of those describe Phase 0. Phase 0 ships 14 tools, a 5-stage α middleware chain inlined in src/server.ts, and data/colibri.db (created at runtime in WAL mode). If you are asserting a number, cross-check it against colibri-system.md or CLAUDE.md §9 first.

Getting help

• Open a GitHub Discussion if you’re stuck
• Look at recently merged PRs for examples (gh pr list --state merged)
• Read CONTRIBUTING.md for the full contribution model

Next steps after your first PR

• Pick a more substantial contribution from the Phase 0 task breakdown
• Read the Architecture Overview
• Start writing or reviewing skill specifications in .agents/skills/

---

Welcome to Colibri. Documentation contributions matter — they keep the spec, the skills, and the code in lockstep.