Repo Bootstrap

Repo Bootstrap

Goal: create the minimum complete source-of-truth package that lets an AI agent or developer start implementation without guessing. Do not force every repo into an app/backend/SaaS shape. Classify the repository first, then select the right lanes.

Core Rule

Bootstrap is decision work before coding. It must make the next implementation agent's choices explicit:

• what the repo is
• what it must and must not do
• which technologies are approved
• where boundaries are
• how to run, test, package, release, and verify it
• which decisions are still blocked

If a decision affects code, dependencies, public API, data shape, runtime behavior, deployment, or QA, do not leave it implicit.

Workflow

Run these phases in order.

[0] Repository Type Classification
[1] Project Context
[2] Architecture / Repo Blueprint
[3] Toolchain & Dependency Policy
[4] Conditional Domain Specs
[5] Technical Standards
[6] Environment, Packaging, Release
[7] Test & QA Strategy
[8] Handoff Checklist

Do not skip phase 0. The old fixed sequence of Database -> API -> DevOps is valid for many app repos, but wrong for many libraries, CLIs, docs repos, infrastructure repos, MCP servers, firmware, games, and data/ML repos.

Phase 0 - Repository Type Classification

Classify the repo before writing detailed specs.

Record:

## Repository Classification

- Repository type:
- Primary users:
- Runtime target:
- Main deliverable:
- Interface surface:
- Data persistence:
- Deployment/distribution:
- Required conditional lanes:
- Explicitly not applicable lanes:

Use this guide:

For detailed conditional outputs, read references/repo-type-lanes.md. For desktop apps, also read references/desktop-app.md. For SaaS multi-tenant systems, also read references/saas-patterns.md. For complex UI systems, also read references/design-system.md. For technical standards details, read references/technical-standards.md.

Phase 1 - Project Context

Define the project boundary. Every later decision should point back here.

Output:

## Project Context

- Project/repo name:
- One-sentence description:
- Target users:
- Primary use cases:
- MVP scope:
- Out of scope:
- Non-functional requirements:
- Main language/runtime:
- Team size and roles:
- Milestones/deadline:
- Success criteria:

Phase 2 - Architecture / Repo Blueprint

Describe the repository shape and system boundaries at the right abstraction level for the repo type.

Output:

## Architecture / Repo Blueprint

### Overview
[Text diagram, Mermaid, or clear component/module map.]

### Module / Package Breakdown
| Module / package | Responsibility | Boundary / not responsible for |
| --- | --- | --- |

### Interface Surface
[HTTP routes, CLI commands, library public API, MCP tools, extension messages,
mobile screens, jobs, events, hardware IO, or docs publishing surface.]

### Data / State Flow
[Where data/state enters, transforms, persists, exits, or renders.]

### Integration Points
- Internal:
- External:

### Scalability / Reliability / Safety Notes

For monorepos, include workspace/package graph and ownership boundaries.

Phase 3 - Toolchain & Dependency Policy

This is a binding decision section. Coders must not invent dependencies after bootstrap unless the user approves the change.

Output:

## Toolchain & Dependency Policy

### Runtime & Language
- Language:
- Runtime:
- Package manager:
- Build tool:

### Core Frameworks / Libraries
| Area | Approved choice | Version | Reason |
| --- | --- | --- | --- |

### Dependency Rules
- Approved dependencies:
- Banned dependencies:
- Version pinning policy:
- License constraints:
- Security scanning:
- Rule for adding new dependency:

### Dev Tooling
- Formatter:
- Linter:
- Type checker:
- Git hooks:
- Local commands:

Rule for AI agents: do not import a library outside this list without explicit approval. If a new dependency is needed, stop and ask.

Phase 4 - Conditional Domain Specs

Write only the sections that match the classified repo type. Mark non-applicable sections as N/A only when that avoids ambiguity.

Common conditional specs:

Read references/repo-type-lanes.md for detailed templates.

Phase 5 - Technical Standards

Define how the repo is maintained. Use references/technical-standards.md for full patterns when needed.

Output:

## Technical Standards

- Git workflow:
- Commit convention:
- Branch / PR rules:
- Error handling:
- Logging / tracing:
- Configuration:
- Secrets:
- Caching / invalidation, if applicable:
- Background jobs, if applicable:
- Concurrency / conflict resolution:
- Security baseline:
- Code organization:
- Generated code policy:
- Documentation policy:

Sign-off rule: if multiple roles are involved, architecture, backend, frontend, DevOps, QA, and product owners should review the standards before coding starts.

Phase 6 - Environment, Packaging, Release

Every repo needs a way to run or consume its deliverable. This is not always deployment; for libraries it may be publishing, for docs it may be static-site generation, for firmware it may be flashing.

Output:

## Environment, Packaging, Release

### Environments / Targets
| Target | Purpose | Build/source | Notes |
| --- | --- | --- | --- |

### Configuration
- Environment variables:
- Config files:
- Secret handling:

### Local Setup
[Commands that work from clone to first successful run/build.]

### Build / Package / Publish
- Build command:
- Package artifact:
- Release channel:
- Versioning:

### CI/CD or Automation
- Trigger:
- Steps:
- Required checks:
- Rollback / restore:

Phase 7 - Test & QA Strategy

Tests are verification. They do not replace correct behavior, runtime review, or QA evidence.

Output:

## Test & QA Strategy

- Test levels:
- Critical behavior to cover:
- Fixtures / data strategy:
- Integration or contract tests:
- E2E or runtime validation:
- Performance / capacity checks:
- Security checks:
- Accessibility / visual checks, if UI exists:
- CI gates:
- Manual QA requirements:

For UI/runtime projects, include visible user-flow QA requirements. If the repo will use the Anvien QA skill, state which QA lanes are expected.

Phase 8 - Handoff Checklist

Before coding starts, verify that all code-shaping decisions are either resolved or explicitly blocked.

## Handoff Checklist

- [ ] Repository classification completed.
- [ ] Project context and scope completed.
- [ ] Architecture / repo blueprint completed.
- [ ] Toolchain and dependency policy completed.
- [ ] Required conditional domain specs completed.
- [ ] Non-applicable lanes explicitly marked when needed.
- [ ] Technical standards completed.
- [ ] Environment/package/release path completed.
- [ ] Test and QA strategy completed.
- [ ] No code-shaping decision remains implicit.
- [ ] All blocking TBD items are listed with owner.

Handoff: <architect|supervisor|coder> - <reason>

Handoff roles:

• architect: unresolved architecture, source-of-truth, system-flow, or rule decisions.
• supervisor: needs priority, scope, acceptance, or coordination decision.
• coder: enough decisions are made to begin implementation.

How To Work With The User

• Interview before writing. Do not fill code-shaping decisions from guesses.
• Ask for the smallest number of high-impact missing decisions at a time.
• If the user has not chosen a repository type, classify it with evidence from the request.
• If a lane is not applicable, say why.
• If a required decision is unknown, mark it as blocked instead of inventing it.
• Keep output as Markdown source-of-truth docs, usually SPEC.md or files under docs/.

Red Flags

Stop and ask or mark blocked when:

• repository type is unknown and affects the workflow
• the skill is about to force DB/API/frontend sections onto a repo that does not need them
• dependencies are unapproved or version is "latest"
• public API/CLI/tool surface is unspecified
• data persistence exists but schema/migration policy is missing
• release/distribution target is missing
• tests are defined before expected behavior is clear
• the handoff would still require the coder to guess architecture or contracts