Build and Maintain Repository Conventions

.colony/conventions.md records repository facts that an agent cannot safely infer from one issue and one checkout. It complements executable configuration: conventions explain intent and boundaries; setup and review commands prove the checkout actually works.

Write only durable guidance

Include information that changes how work should be implemented or reviewed:

• supported language, runtime, and package-manager versions;
• the architecture’s important module or service boundaries;
• the canonical setup, build, test, lint, typecheck, and generated-code commands;
• files that are generated, vendored, migration-controlled, or owned elsewhere;
• patterns that are required or intentionally forbidden;
• compatibility and public-API expectations;
• how to test database, service, or integration changes;
• security-sensitive areas that require a human or a separate process.

Do not turn the file into a project history, issue template, style-guide copy, or list of facts the repository already enforces mechanically.

Create the first version

Generate from a clone

In a current local clone, run:

colony colonize

Review the generated .colony/conventions.md as a draft. The command can detect stack signals and create a starting structure, but a maintainer must correct architectural and policy claims before committing it.

Write manually

Create .colony/conventions.md with short sections such as Runtime, Architecture, Commands, Testing, Generated files, and Change boundaries. Prefer an exact command or directory over a general adjective.

Example:

# Repository conventions

## Runtime
- Use Node.js 22 and npm. Do not replace `package-lock.json`.

## Architecture
- HTTP handlers live in `packages/api/src/routes` and may call services, not database clients directly.
- Shared request/response types live in `packages/shared`; do not duplicate them in the dashboard.

## Verification
- Install from a clean checkout with `npm ci`.
- Run `npm run typecheck`, `npm test`, and `npm run build` before handoff.

## Change boundaries
- Files under `packages/api/src/openapi/generated` are generated; update the schema and run `npm run openapi:generate`.
- Database changes require a forward migration and a rollback note in the PR.

Align executable configuration

Put shell behavior in Colony configuration rather than relying on prose alone:

workspace:
  setup_command: npm ci
  prebuild_command: npm run generate
review:
  checks:
    typecheck: npm run typecheck
    test: npm test
    build: npm run build

Test these commands in a clean Worker-like checkout with no preinstalled dependencies, untracked generated files, or developer credentials. See Onboard a Non-TypeScript Repository for other stacks.

Caution

Do not put tokens, internal credentials, private endpoints, or instructions to read secret files in conventions. Use secret management and forbidden_paths for sensitive material.

Validate the guidance

1. Ask a maintainer who did not write the file to follow its setup and verification commands in a clean clone.
2. Use Colony Cloud Issue Intake Studio’s convention validation, or file a small test issue that depends on one documented boundary.
3. Inspect the plan and diff for evidence that the relevant convention was followed.
4. Remove redundant prose when a linter, type system, test, or generator can enforce the rule instead.
5. Commit the conventions with the repository so pull requests review changes to the instructions alongside code.

Keep conventions current

Review the file when any of these change:

• runtime or package manager;
• repository layout or service ownership;
• setup, build, test, lint, or generation commands;
• CI-required checks;
• public API or compatibility policy;
• migration or deployment workflow;
• repeated Colony failures reveal a missing durable fact.

Do not add a rule because one implementation made a poor local choice. Add it when the rule represents an enduring repository constraint; otherwise improve the issue or the relevant automated check.

Resolve conflicting instructions

When an issue, convention, and executable check disagree, stop and fix the source of truth. Do not ask Colony to guess which contradiction to ignore. A good resolution usually follows this order:

1. correct the issue if its requested outcome is wrong;
2. update conventions if repository policy changed;
3. update configuration if the executable command is stale;
4. rerun the work only after all three describe the same expected result.

What next

• Writing for Colony
• Onboard a Non-TypeScript Repository
• Configure Issue Intake and Workflow Routing