Bootstrap Guide

Bootstrap Guide

colony bootstrap scaffolds a brand-new Colony-managed repository from a stack template in a single command. Use it when starting a greenfield project — it handles the framework skeleton, Colony conventions, .gitignore patches, and GitHub pipeline labels.

If you already have an existing repository, use colony init to register it and colony colonize to generate conventions. colony bootstrap is for repos that do not exist yet.

Context: Bootstrap exists primarily to enable the canary suite — a set of nine epic-scale prompts that Colony should complete without human intervention. Every canary entry assumes a bootstrapped starting state. Bootstrap is the command that produces it.

---

Scaffold a new repo

colony bootstrap <stack> <name>

Creates a new directory ./<name>/ containing:

• Framework skeleton for the chosen stack (conventions, directory layout)
• .colony/colony.yaml discovery marker (managed_by: local)
• .colony/conventions.md with stack-specific patterns for Colony’s agents
• .gitignore entries for .colony/workspaces, .env, and .env.local
• GitHub pipeline labels created on the configured repository

Arguments:

Argument	Description
<stack>	Stack template to use. One of: nextjs, rails, cloudflare-workers, django, go-cli
<name>	Directory name for the new project

Flags:

Flag	Description
-c, --config <path>	Path to colony.config.yaml (default: auto-discovered)
--cloud	Not yet available — see Cloud mode

Stack templates

Stack	Ecosystem	Canary entries
nextjs	Next.js (TypeScript)	S2 mark, M4 relay, L1 ledger
rails	Ruby on Rails	M2 tomato, L2 flightplan
cloudflare-workers	Cloudflare Workers (TypeScript)	S1 shrtnr, M3 lighthouse
django	Django (Python)	M1 inkwell
go-cli	Go CLI (Cobra)	S3 tt

Each template maps to one or more canary suite entries. See docs/canary-suite/README.md for the full entry list and grading criteria.

Example

colony bootstrap nextjs my-app

Output:

Bootstrapping nextjs project "my-app"...
  ✓ Wrote .colony/colony.yaml
  ✓ Added .colony/workspaces to .gitignore
  ✓ Added .env to .gitignore
  ✓ Added .env.local to .gitignore
  ✓ Generated .colony/conventions.md
  ✓ 42 pipeline labels created/verified

Done! Project "my-app" bootstrapped.
  Review .colony/conventions.md before starting Colony on this repo.

After bootstrap, open .colony/conventions.md and review it for accuracy before starting Colony on the new repo. The conventions file teaches Colony’s agents the project’s style, test framework, and directory structure.

---

Apply conventions to an existing repo

colony bootstrap configure

Runs inside an already-initialised repo (or after a manual scaffold). It:

1. Auto-detects the stack from existing framework files
2. Rewrites .colony/conventions.md with detected stack patterns
3. Patches tool-specific ignore configs (.eslintignore, .prettierignore, etc.) to exclude Colony’s working directories

Flags:

Flag	Description
-c, --config <path>	Path to colony.config.yaml (default: auto-discovered)
--dry-run	Print what would be written without making any changes

Credential collection

If .env.example is present in the repo, bootstrap configure prompts interactively for any env vars not already set in .env.local. Variable names ending in _SECRET, _KEY, or _TOKEN are masked at the prompt. Known service credentials — Stripe, Resend, Postmark, Cloudflare R2, and Postgres — are validated live against their APIs as each value is entered.

If a credential was collected from a previous run and cached, the command offers to reuse the cached value instead of re-prompting.

After writing .env.local, the command asks:

Cache credentials to ~/.config/colony/secrets.yaml for reuse? (y/N)

Accepting caches the values for future runs on other repos. Caching is opt-in and defaults to No.

Example

colony bootstrap configure --dry-run

Output:

Configuring Colony conventions for /path/to/my-app...
  [dry-run] Would write: /path/to/my-app/.colony/conventions.md
  [dry-run] Detected stack: nextjs
  [dry-run] Credentials that would be prompted:
    STRIPE_SECRET_KEY — Stripe secret key
    DATABASE_URL — Postgres connection string

The [dry-run] Credentials that would be prompted: block only appears when .env.example is present in the repo.

Remove --dry-run to apply the changes.

---

Cloud mode

--cloud is not yet available. Passing it exits immediately with a pointer to the tracking issue at https://github.com/RunColony/colony. Cloud mode will enable colony bootstrap to register the repo with a Colony Cloud deployment instead of a local one; it depends on colony login and a Cloud-side handshake, both of which are tracked separately.

---

What bootstrap produces

After a successful colony bootstrap <stack> <name> run, the new directory contains:

<name>/
  .colony/
    colony.yaml        # managed_by: local discovery marker
    conventions.md     # stack-specific patterns for Colony agents
  .gitignore           # .colony/workspaces, .env, .env.local entries added

The colony.yaml marker tells Colony tooling that this repo is managed locally. Future Cloud-aware tooling will read this file to determine routing — the schema is forward-compatible (managed_by: cloud is accepted but unused in local mode).

---

Next steps

After bootstrap:

1. cd <name> into the new directory
2. Review .colony/conventions.md and tune it for the project
3. Add your colony.config.yaml pointing at the repo
4. Run colony check to validate setup
5. File an issue and watch Colony go

For a full walkthrough of the Colony pipeline from first issue to merged PR, see Getting Started.