Starting a New Project with Colony

Starting a New Project with Colony

A guide for setting up a repository so Colony can build it out incrementally through GitHub issues.

---

Prerequisites

Before starting, you need:

• Colony running — installed, configured with a GitHub token, agents operational
• A GitHub repository — public or private, with Colony’s token granted access
• The project scaffolded and passing — framework installed, builds cleanly, pushed to main
• Deployment configured — hosting platform (Cloudflare Pages, Netlify, Vercel) connected to the repo and deploying on push to main

This guide doesn’t cover installing Colony or setting up hosting accounts. It picks up at: “I have a working repo and Colony — now what?”

How Colony Works (the 30-second version)

Colony watches your GitHub repo for issues. When you file one, its agents pick it up: analyze the requirements, implement the code in a branch, validate the build, open a PR, review it, address feedback, and merge. You interact with Colony primarily by writing issues. The better the issue, the better the result.

---

1. Repository Setup

Colony works on your repo through the normal GitHub flow — branches, PRs, merges. The repo must build and pass checks before Colony touches it, because Colony validates its own work against those same checks.

Scaffold the Project

Use whatever framework fits your project. For a content-heavy personal site, we recommend Astro + Tailwind CSS:

npm create astro@latest my-site
cd my-site
npx astro add tailwind

For other frameworks, see the Appendix.

Verify the Build Pipeline

Before Colony can work on your project, every check you plan to configure must pass on main:

npm run build        # Site builds successfully
npx astro check      # No type errors (Astro)
npx prettier --check . # Formatting is clean

This is the #1 gotcha for new projects. If you configure a check that doesn’t pass on main, every Colony issue will fail self-validation and get blocked.

Push and Deploy

git add -A && git commit -m "Initial scaffold"
git push origin main

Confirm your hosting platform picks up the push and deploys successfully. Colony merges to main, which triggers deploys — the pipeline needs to be working end-to-end before you start filing issues.

---

2. Colony Configuration

Add your repository to colony.config.yaml:

repos:
  - owner: your-github-username
    repo: your-site
    workspace:
      repo_dir: /path/to/your-site
      base_dir: /path/to/your-site/.colony/workspaces
      setup_command: 'npm install'
    review:
      checks:
        build: 'npm run build'
        check: 'npx astro check'
        format: 'npx prettier --check .'
      timeout_per_check: 120

Key points

repo_dir must point to a local clone of the GitHub repo with origin set to the GitHub remote. Colony creates worktrees from this directory.

setup_command runs in every worktree Colony creates. Keep it fast — npm install is fine. For non-Node projects: bundle install, pip install -r requirements.txt, etc.

review.checks are the commands Colony runs to validate its own work before opening a PR, and again during review. Rules:

• Only list checks that currently pass on main. Don’t add test: 'npm test' if you have no tests yet.
• Add new checks as the project grows. Once you have tests, add the test check.
• Each check must exit 0 on success, non-zero on failure. Standard CLI behavior.

timeout_per_check — 120 seconds is fine for most projects. Increase for slow test suites.

---

3. Teaching Colony Your Project

Create a file at .colony/conventions.md in your repository. This is the single most impactful thing you can do. Colony includes this file in every prompt it sends to Claude Code, so it shapes every line of code Colony writes.

What to include

Project purpose — one paragraph. Colony uses this to make contextual decisions about tone, styling, and content structure.

Directory structure — where things live. Colony needs to know where to put new files.

Content patterns — frontmatter schemas, file naming, image handling.

Styling rules — be specific. “Use Tailwind” is good. “Use Tailwind with the Inter font, lots of whitespace, neutral color palette” is better.

Design sensibility — unusual for a conventions file, but critical for visual projects. If you want a specific aesthetic, describe it.

Constraints — what Colony should not do. This prevents overengineering.

Example: Photography / Personal Brand Site

# Site Conventions

## About This Site
Personal website for Jane — photographer, visual designer, creative professional.
Clean, modern aesthetic with emphasis on large imagery and whitespace.

## Tech Stack
- Astro 5.x with Tailwind CSS
- Content in Markdown (src/content/)
- Static output, deployed to Cloudflare Pages

## Directory Structure
src/
├── content/
│   ├── blog/        # Blog posts (Markdown with frontmatter)
│   └── gallery/     # Photo gallery entries
├── pages/           # Route pages (.astro files)
├── components/      # Reusable UI components (.astro files)
├── layouts/         # Page layouts (BaseLayout.astro, BlogLayout.astro)
└── assets/          # Images and fonts

## Content Schemas

### Blog Posts (src/content/blog/*.md)
---
title: string (required)
date: YYYY-MM-DD (required)
description: string (required, used for meta tags and previews)
coverImage: path to image in src/assets/ (optional)
tags: list of strings (optional)
---

### Gallery Items (src/content/gallery/*.md)
---
title: string (required)
date: YYYY-MM-DD (required)
image: path to image in src/assets/ (required)
category: one of [Landscape, Portrait, Street] (required)
---

## Styling
- Tailwind CSS utility classes only — no custom CSS files
- Font: Inter for headings, system serif for body text
- Colors: neutral palette (slate/gray/white), accent color stone-800
- Full-width images for hero sections, max-w-4xl for text content
- Generous whitespace — when in doubt, add more padding

## Design Principles
- Photography-first: images should be large and high-quality
- Minimal UI chrome — let the content breathe
- Mobile-first responsive design
- Fast page loads — use Astro Image component for all images

## Constraints
- Do not add client-side JavaScript unless the issue specifically requires interactivity
- Do not install new npm packages unless the issue asks for it
- Do not create custom CSS files — use Tailwind
- Do not write placeholder/lorem-ipsum content — use only the text provided in the issue
- Keep all pages accessible (semantic HTML, alt text on images, sufficient contrast)

Keep it updated

The conventions file is a living document. As the site evolves and you establish patterns, update it. If Colony keeps making a recurring mistake — wrong styling, putting files in the wrong place, using the wrong component — the fix is usually adding a line to conventions.

Commit the conventions file to main:

git add .colony/conventions.md
git commit -m "Add Colony conventions"
git push origin main

---

4. Writing Good Issues

Colony’s output quality is directly proportional to issue quality. A well-written issue with clear deliverables gets a clean PR. A vague issue gets vague results.

The formula

Every issue should have:

1. What — a concrete deliverable, not a vague goal
2. Where — which pages or files are affected (if known)
3. Acceptance criteria — how to know it’s done
4. Reference — a link, screenshot, or description of the visual/behavioral target

Good examples

Adding a page

Title: Add About page

Create an About page at /about with:

• Hero section with a full-width photo (use src/assets/about-hero.jpg)
• Bio paragraph (text below)
• Grid of 3 “what I do” cards: Photography, Design, Consulting
• Link to the contact page in the footer

Bio text: “Jane is a photographer and visual designer based in Portland, Oregon. She specializes in landscape photography and brand design for small businesses.”

Style: clean, centered layout consistent with the homepage. Generous whitespace.

Adding content

Title: Add blog post: Weekend at the Coast

Create a new blog post at src/content/blog/2026-03-09-weekend-at-the-coast.md

Frontmatter:

• title: “Weekend at the Coast”
• date: 2026-03-09
• description: “A rainy Saturday exploring tide pools and sea stacks along the Oregon coast.”
• coverImage: src/assets/blog/coast-cover.jpg
• tags: [photography, travel, oregon]

Body text: [paste the actual post content here]

Adding a feature

Title: Add photo gallery page with category filtering

Create a /gallery page that displays photos in a responsive grid.

• Source images from the gallery content collection
• Clicking a photo opens it larger (lightbox or modal)
• Category filter tabs at the top: All, Landscape, Portrait, Street
• 3 columns on desktop, 2 on tablet, 1 on mobile
• Use the masonry layout pattern (variable height rows)

Modifying existing pages

Title: Add navigation link for gallery

Update src/components/Nav.astro to add a “Gallery” link between “Blog” and “Contact” in the main navigation.

Anti-patterns

Issue	Problem
”Make the site look better”	No concrete deliverable. Colony can’t evaluate “better."
"Redesign the homepage”	Too broad. Split into separate issues for each section.
”Add SEO”	Vague scope. Try: “Add meta descriptions and Open Graph tags to all pages."
"Fix the styling”	Which styling? Where? What should it look like instead?
”Build a contact form”	Needs specifics: which form service? What fields? Where does it submit?
”Add lots of cool animations”	Subjective, unbounded. Pick one specific animation for one specific element.

Rules of thumb

• One page or one component per issue. Not “build the whole site.”
• Provide the actual content. Don’t make Colony write your bio — paste the text into the issue.
• Reference what exists. “Style it like the About page” works if the About page already exists.
• Name specific files when you know them. “Update src/components/Nav.astro” is clearer than “update the navigation.”
• Images must exist in the repo first. Colony can reference images but can’t create photographs. Push images to main before filing the issue that uses them.
• Start small, build up. Your first few issues should be simple — a page with text and an image. Build confidence in the patterns before attempting complex interactive features.

---

5. The Daily Workflow

Getting started: seed the backlog

File 3-5 well-scoped issues for the initial structure of your site. For a personal site, a good starting batch:

1. Homepage (hero image, tagline, navigation)
2. About page (bio, photo, services)
3. Blog index page (list of posts)
4. First blog post (actual content)
5. Contact page (info, links, maybe a form)

Colony works through issues in priority order. It processes one issue at a time per repo (analyzing, implementing, reviewing, merging) before moving to the next.

Reviewing Colony’s work

Colony opens PRs on GitHub. You have two options:

Let Colony handle it. The reviewer agent runs your configured checks and does an LLM code review. If everything passes, the merger agent merges the PR. If the reviewer requests changes, the developer agent fixes them automatically. This loop typically resolves in 1-3 cycles.

Review it yourself. Colony labels PRs colony:human-review-ready when its own review passes. You can review the PR on GitHub, request changes via comments, and Colony will address your feedback too.

For a personal site, letting Colony handle the full loop is fine for most issues. Review the first few PRs yourself to calibrate — if the conventions file is doing its job, results should match your expectations.

Adding content

Two paths:

Via Colony (structural content): File an issue with the content pasted in. Good for blog posts that need custom layouts or new pages.

Push directly (simple content): Create a Markdown file in the right directory, commit, and push to main. No issue needed. Good for routine blog posts once the templates are established.

Adding images

Always push images to the repo before (or separately from) filing the issue that references them:

cp ~/Photos/coast-cover.jpg src/assets/blog/
git add src/assets/blog/coast-cover.jpg
git commit -m "Add coast cover photo"
git push origin main

Then file the issue referencing src/assets/blog/coast-cover.jpg.

When to use the local repo

• Uploading images and assets — git push directly
• Writing blog posts — create the Markdown file and push
• Quick fixes — faster to edit and push than to file an issue
• Experimenting — exploring design ideas you’re not sure about yet
• Updating conventions — edit .colony/conventions.md when you want to change Colony’s behavior

When to file an issue

• New pages — homepage, about, gallery, any new route
• New features — lightbox, filtering, search, contact form
• Design changes — layout updates, component redesigns, responsive fixes
• Structural changes — navigation updates, footer changes, new content types
• Integrations — CMS setup, analytics, third-party services

---

6. Growing the Site

A typical evolution:

Phase 1: Static foundation

Markdown content, Astro pages, Tailwind styling. All changes through Colony issues. Simple, fast, reliable.

Phase 2: Add a CMS

Once filing issues for every blog post gets tedious, add a git-backed CMS. File one issue:

Title: Integrate Decap CMS for blog and gallery management

Add Decap CMS (formerly Netlify CMS) so blog posts and gallery items can be created/edited through a web interface at /admin.

• Configure collections for blog and gallery matching the existing content schemas
• Authentication via Cloudflare Access (or GitHub OAuth)
• Media uploads stored in src/assets/
• Preview templates matching the site’s actual styling

After this, content goes through the CMS web UI. Structural and design changes stay as Colony issues.

Phase 3: Add interactivity

File targeted issues for interactive features:

• Photo lightbox (clicking gallery images opens full-screen viewer)
• Contact form (via Formspree, Cloudflare Workers, or similar)
• Dark mode toggle
• Animated page transitions

Astro’s island architecture means Colony adds a React or Svelte component for interactivity without rebuilding the rest of the site.

Phase 4: New content types

Each new content type is a natural Colony issue:

• Portfolio/case studies
• Testimonials
• Events calendar
• Newsletter signup

One issue per content type: define the schema, create the listing page, create the detail page.

---

Appendix: Framework Quick-Start Configs

Astro (recommended for content sites)

npm create astro@latest my-site && cd my-site
npx astro add tailwind

colony.config.yaml

workspace:
  setup_command: 'npm install'
review:
  checks:
    build: 'npm run build'
    check: 'npx astro check'
    format: 'npx prettier --check .'

# .colony/conventions.md skeleton
## Tech Stack
Astro 5.x, Tailwind CSS, static output

## Structure
- Pages: src/pages/ (file-based routing)
- Content: src/content/ (Markdown collections)
- Components: src/components/ (.astro files)
- Layouts: src/layouts/

## Styling
Tailwind utility classes. No custom CSS.

## Images
Use Astro's Image component. Store in src/assets/.

Next.js

npx create-next-app@latest my-site && cd my-site

workspace:
  setup_command: 'npm install'
review:
  checks:
    build: 'npm run build'
    lint: 'npm run lint'
    format: 'npx prettier --check .'

# .colony/conventions.md skeleton
## Tech Stack
Next.js 15 (App Router), Tailwind CSS, React Server Components

## Structure
- Routes: app/ (file-based routing, page.tsx per route)
- Components: components/ (React .tsx files)
- Content: content/ (Markdown/MDX if using contentlayer)
- API: app/api/ (route handlers)

## Styling
Tailwind utility classes. Use cn() utility for conditional classes.

## Constraints
- Prefer Server Components by default, add 'use client' only when needed
- Use next/image for all images
- Use next/link for all internal links

SvelteKit

npx sv create my-site && cd my-site

workspace:
  setup_command: 'npm install'
review:
  checks:
    build: 'npm run build'
    check: 'npm run check'
    lint: 'npm run lint'
    format: 'npx prettier --check .'

# .colony/conventions.md skeleton
## Tech Stack
SvelteKit 2.x, Tailwind CSS

## Structure
- Routes: src/routes/ (+page.svelte per route, +layout.svelte for layouts)
- Components: src/lib/components/ (.svelte files)
- Content: src/content/ (Markdown with mdsvex)

## Styling
Tailwind utility classes. Scoped styles in <style> blocks when needed.

Eleventy (11ty)

mkdir my-site && cd my-site && npm init -y
npm install @11ty/eleventy

workspace:
  setup_command: 'npm install'
review:
  checks:
    build: 'npx eleventy'
    format: 'npx prettier --check .'

# .colony/conventions.md skeleton
## Tech Stack
Eleventy 3.x, Nunjucks templates

## Structure
- Pages: src/ (Markdown and .njk files)
- Layouts: src/_includes/layouts/
- Partials: src/_includes/
- Data: src/_data/ (global data files)
- Output: _site/

## Content
Markdown with YAML frontmatter. Layouts specified via `layout` frontmatter key.

## Styling
Vanilla CSS in src/css/. No build step for styles.

Ruby on Rails

rails new my-app && cd my-app

workspace:
  setup_command: 'bundle install'
review:
  checks:
    test: 'bundle exec rake test'
    lint: 'bundle exec rubocop'

See docs/conventions-rails-example.md for a full conventions template.

Generic (HTML/CSS/JS, no framework)

workspace:
  setup_command: 'npm install'  # or omit if no dependencies
review:
  checks:
    format: 'npx prettier --check .'

# .colony/conventions.md skeleton
## Tech Stack
Static HTML, CSS, vanilla JavaScript. No framework.

## Structure
- Pages: *.html in project root
- Styles: css/
- Scripts: js/
- Images: images/

## Styling
Vanilla CSS. One stylesheet per page or a shared styles.css.

## Constraints
- No frameworks or build tools
- Keep it simple — semantic HTML, minimal JavaScript

---

Troubleshooting

Every issue gets blocked

Check that all review.checks pass on main. Run each command manually in a fresh clone. The most common cause is configuring a check that doesn’t exist or doesn’t pass.

Colony’s code doesn’t match the site’s style

Update .colony/conventions.md with more specific instructions. If Colony keeps using the wrong font, wrong colors, or wrong layout patterns, add explicit rules. The conventions file is your primary lever for quality.

Colony installs packages you didn’t ask for

Add to conventions: “Do not install new npm packages unless the issue specifically requests it.”

PRs have merge conflicts

This happens when multiple issues touch the same files. Colony handles rebasing automatically in most cases. If it can’t resolve the conflict, the issue gets blocked — resolve it manually, push, and relabel the issue to colony:changes-requested.

Issues are too big and produce bad results

Break them down. If an issue touches more than 3-4 files or requires more than ~300 lines of changes, it’s probably too big. Split it into sequential issues where each one builds on the last.

Images aren’t showing up

Colony can’t create image files. Push images to main first, then file the issue that references them. Use exact paths in the issue: “Use src/assets/hero.jpg” not “add a hero image.”