Starter Harness for Vibe Coded Projects

Help small product teams move fast with AI while keeping the repo clear enough for engineers to review, fix, and deploy.

This repository helps you choose the right starter harness for your project.

Each starter harness lives in its own repository, so you can start from the right template directly.

The goal is simple: when engineers need to take a project further, the repo is easier to understand and safer to ship.

Who This Is For

• Small product teams building new software
• Teams using AI tools to move faster in early project work
• Projects that will later need engineers to review, clean up, harden, and deploy
• Teams that want better docs and clearer handoff from day one

Why This Exists

Many small teams can build fast with AI.

The hard part comes later.

When engineers need to fix bugs, review changes, improve the code, and deploy safely, they often inherit a repo with missing context and weak structure.

This starter harness helps teams set up the basic docs and working rules early, so the project is easier to understand and easier to ship later.

Choose a Scaffold

If you are not sure, start with balanced.

• minimal Best for small repos that need the core docs and a simple working structure.
• balanced Best for most small product teams. It adds security, roadmap, risks, decisions, contribution workflow, ownership, and GitHub templates on top of the core set.
• full Best for projects that also need deeper docs for design, API, data, operations, observability, deployment, release work, and runbooks.

Scaffold Repos

• starter-harness-minimal - view the minimal template
• starter-harness-minimal/generate - start from the minimal template
• starter-harness-balanced - view the balanced template
• starter-harness-balanced/generate - start from the balanced template
• starter-harness-full - view the full template
• starter-harness-full/generate - start from the full template

How to Start

1. Pick the scaffold that fits your project.
2. Open the scaffold repo for that option.
3. Use the direct /generate link if you want to create a new GitHub repository from the template.
4. Replace the placeholder text.
5. Work through TODO.md for setup items that cannot be known before the template is copied.
6. Fill in the core docs first.
7. Keep the docs updated as the project changes.

How the Scaffolds Work

Each starter harness lives in its own repository and gives you a starting set of docs for a new software project.

In every scaffold:

• README.md is the main file for humans
• AGENTS.md is the model-neutral entry point for coding agents
• CLAUDE.md is the Claude Code-specific instruction file
• TODO.md tracks setup items that must be resolved after copying the template
• docs/INDEX.md is the file map for the docs

The scaffolds intentionally do not invent project-specific commands, CI checks, evaluation fixtures, observability standards, or deployment procedures. Those depend on the copied codebase. TODO.md exists so users and agents can replace those unknowns with real project facts instead of treating placeholders as guidance.

Human Workflow After Setup

1. Open the scaffold README.md.
2. Work through TODO.md.
3. Fill in the project name, setup, and commands.
4. Read docs/INDEX.md to see what each doc is for.
5. Update the core docs first.
6. Keep the docs aligned with the real repository structure.

LLM Workflow After Setup

For another LLM working in the copied repository:

1. Read AGENTS.md first.
2. Read README.md second for the project overview.
3. Read docs/INDEX.md third.
4. Read TODO.md before substantial work.
5. Read CLAUDE.md after that if the agent is Claude Code.
6. Use docs/INDEX.md as the file map.
7. Read the task-specific docs after that.
8. Do not create a second file index somewhere else.
9. Update docs/INDEX.md and the affected docs when structure or behavior changes.

Placeholder Tokens

The scaffold files keep a small set of placeholders:

• {{PROJECT_NAME}}
• {{PROJECT_SLUG}}
• {{PROJECT_DESCRIPTION}}
• {{OWNER_NAME}}
• {{PRIMARY_LANGUAGE}}
• {{DEFAULT_BRANCH}}
• {{CURRENT_DATE}}

These placeholders are expected in the scaffold files and should be replaced after starting from a scaffold repository.

The scaffolds also include non-token setup markers such as TODO, @org/team, and replacement security contacts where the correct value depends on the copied project. Track and resolve those items through TODO.md.

References

The research references and rationale for this structure live in REFERENCES.md.