Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (82 loc) · 7.14 KB

CONTRIBUTING.md

File metadata and controls

123 lines (82 loc) · 7.14 KB

Contributing to Colibri

Colibri is a documentation-first project. The active canon is docs/. No Node.js source code exists yet — Phase 0 bootstrap has not started.

Colibri is maintained for correctness, traceability, and safe docs updates. The only long-lived integration branch is main; executor work should stay on short-lived feature branches and feature worktrees.

New here? Start with these PRs

First time contributing to Colibri? Pick one of these no-build-environment PRs — they take 20-30 minutes and need nothing but a text editor:

  1. Fix a typo in the docs — Find a typo in any file under docs/ and fix it. Start in docs/index.md if you need suggestions. Read: any Greek-letter concept page reachable from docs/world-schema.md.

  2. Add a missing term to the glossary — Browse docs/reference/glossary.md and add a term you think is missing from Colibri's vocabulary. Read: docs/reference/glossary.md.

  3. Add a Mermaid diagram to a concept — Pick a concept page reachable from docs/world-schema.md that lacks a diagram and sketch one. (If the concept needs a system flow, architecture box, or timeline, you just found a good starter contribution.) Read: the concept doc you're diagramming.

  4. Cross-link two related docs — Find two concept or reference docs that should cite each other and add wikilinks. For example, if concept A mentions a tool that's explained in reference doc B, add a [[link]]. Read: docs/index.md to map the landscape.

  5. Expand a tool reference with examples — Pick one tool in docs/reference/mcp-tools-phase-0.md and add a before/after request–response example. Read: the tool reference.

  6. Add framework comparison entries — If you know another MCP framework or orchestration system, note how Colibri's 19-tool stdio surface compares in a short note under docs/reference/mcp-tools-phase-0.md. Read: the Phase 0 tool reference.

  7. Write an FAQ for a concept — Pick a concept doc without an FAQ section and add 3–5 questions + answers that you would ask yourself reading it. Read: the concept doc.

  8. Document a Phase 0 task in more detail — Pick an unfinished task from docs/guides/implementation/task-breakdown.md and expand its description with acceptance criteria or architecture notes. Read: the task breakdown and the relevant concept docs.

No prior experience with Colibri required. Just follow Your First PR after picking your task above.

Documentation-only contributions are welcome

Heads up: Colibri is in the spec phase. Phase 0 (the first code release) hasn't started yet. That means:

  • ✅ All current PRs are documentation, diagrams, glossary, or spec refinements — no TypeScript code to build or test.
  • ✅ No build environment needed — just a text editor and git.
  • ✅ Low barrier to entry — perfect for learning how Colibri works while improving the project at the same time.
  • ❌ No feature code PRs yet — if you want to build src/, wait for Phase 0 bootstrap (task P0.1 and P0.2).

So if you're reading this and thinking "I want to contribute but I'm not sure I'm ready," you're actually the perfect person to help right now. Newcomers catch unclear explanations and missing examples that maintainers have gotten used to.

Before You Change Anything

  1. Read README.md for the current repo surface.
  2. Read the relevant page in docs/ before editing public documentation or release/distribution guidance.
  3. Read docs/guides/deploy.md before changing release wording or packaging guidance.
  4. Run the repository's actual validation lane, not a custom one.

Local Validation

The CI workflow checks docs integrity — no npm or package.json is present. Run the docs-integrity checks as defined in .github/workflows/ci.yml.

Branch and Commit Style

  • Branch names: feature/..., bugfix/..., docs/..., refactor/...
  • Treat main as the single relevant integration branch; do not use it as a direct executor workspace.
  • Work in a feature worktree for non-trivial changes, especially public docs or release surfaces.
  • Commit style: conventional commits such as feat:, fix:, docs:, refactor:, test:, build:

Documentation Rules

  • Keep the root small and visitor-friendly.
  • Put canonical user-facing documentation under docs/.
  • Put historical or report-style material under docs/archive/.
  • Put planning artifacts under docs/internal/ only when they still help future maintainers.
  • Do not reintroduce stale projects/unified-mcp/..., projects/ckamal/, or projects/peer-to-peer/ paths into public docs — those directories have been deleted.
  • Do not hardcode absolute paths. Use $COLIBRI_ROOT or <COLIBRI_ROOT> placeholders instead.
  • No src/ directory exists. Do not reference src/server.js as an entrypoint in public docs until Phase 0 bootstrap is complete.

Discipline Requirements

Colibri contributions follow a strict discipline model:

  • Every tool use must be justified.
  • Every change must be tracked in AMS.
  • Every public-facing change must have AMS proof.
  • No path hardcoding.
  • Use the full AMS capability surface: audit, memory, context, and proof primitives.

Execution Standards

Phase Required Action
Init unified_init, unified_vitals, unified_help, unified_set_project
Plan thought_plan with clear goals and constraints
Execute task_update to in_progress, work with traceability
Verify audit_verify_chain to confirm integrity
Close audit_verify_chain, merkle_finalize, merkle_root, task_update to done, thought_record summary, memory_pack

Colibri Roadmap

Colibri development is guided by the colibri roadmap:

  • Scope and discipline
  • Tool chain registry
  • Integration patterns
  • Verification and proof

See roadmap_list and roadmap_get with roadmap_id: "colibri" for current state.

Pull Request Checklist

  • Public docs point at the correct root paths.
  • Tests pass locally or the gap is explicitly explained.
  • Repo-facing changes keep GitHub Pages, releases, and metadata coherent.
  • PRs that touch public release surfaces must target main, include the AMS task or intake id, and note the audit session used for verification.
  • No hardcoded absolute paths are introduced in documentation.
  • AMS task references are included in commit messages where applicable.
  • The PR template fields for task, audit, branch, worktree, and proof update are complete.
  • Docs integrity CI passes (no broken extraction references, no missing frontmatter).

Reporting Issues

When reporting a bug, include:

  • what you ran
  • what you expected
  • what happened instead
  • relevant logs or command output
  • OS and client details if the issue involves MCP setup
  • related AMS task or intake id if one exists

Code of Conduct

Please follow CODE_OF_CONDUCT.md.