> ## Documentation Index
>
> Fetch the complete documentation index at: https://superpowers.frontis.nl/llms.txt
> Use this file to discover all available pages before exploring further.

---

title: Repository bootstrap
summary: How to initialize a Frontis repository for agentic development using local .frontis conventions, AGENTS.md, GitHub Copilot instructions, Superpowers workflow, and Caveman token-saving mode.
order: 10

---

# Repository bootstrap

Use this guide when initializing or updating a Frontis repository for agentic development.

This bootstrap creates the local files that coding agents need to work safely and consistently in Frontis projects.

The goal is:

- give agents a stable local source of truth;
- keep project identity and naming conventions inside the repository;
- link agents to the current Frontis online documentation;
- support Superpowers-style workflows for non-trivial work;
- support Caveman lite for concise progress updates;
- keep CI and developers aligned on the same conventions.

## Required local files

A bootstrapped Frontis repository should contain:

```text
.frontis/
  project.json
  project-context.yaml
  naming-convention.yaml
  azure-conventions.yaml

AGENTS.md

.github/
  copilot-instructions.md
  instructions/
    frontis-conventions.instructions.md
    azure-pipelines.instructions.md
    dotnet.instructions.md
    nuxt.instructions.md
    caveman.instructions.md
  prompts/
    start-frontis-task.prompt.md
```

These files may be installed by:

- the Frontis `.NET` template;
- a coding agent following this guide;
- a repository template;
- a manual copy from another approved Frontis repository.

## Source of truth

Local repository files are canonical for the specific project.

Online documentation explains the current workflow, but it must not override local project identity or user instructions.

Priority order:

1. explicit user instruction;
2. local repository files;
3. Frontis online agent documentation;
4. general agent knowledge.

Project identity must come from:

```text
.frontis/project.json
```

Naming, directory and pipeline rules must come from:

```text
.frontis/naming-convention.yaml
```

Azure hosting, resource and environment rules must come from:

```text
.frontis/azure-conventions.yaml
```

Additional project context must come from:

```text
.frontis/project-context.yaml
```

Never invent Frontis naming conventions from memory.

## Required project values

When bootstrapping a repository, collect these values:

```text
company
product
component
hosting
environments
grippNumber
team
```

Allowed `hosting` values should follow the local convention file.

Typical examples:

```text
shared
dedicated
```

Typical `environments` examples:

```text
test
acceptance
production
prod
```

Use the environment names required by the specific project.

If required values are missing, ask the user before creating final project files.

## Example project.json

Create or update:

```text
.frontis/project.json
```

Example:

```json
{
  "schemaVersion": "1.0.0",
  "company": "AALP",
  "product": "CompositePIM",
  "component": "Api",
  "hosting": "dedicated",
  "environments": ["test", "prod"],
  "grippNumber": 2600173,
  "team": "Everest"
}
```

Rules:

- keep JSON valid;
- use exact casing from the project;
- do not add comments;
- do not add secrets;
- do not add Azure subscription IDs;
- do not add customer credentials.

## Bootstrap workflow for agents

When asked to initialize a repository:

1. Inspect the repository.
2. Check whether `.frontis/`, `AGENTS.md`, `.github/copilot-instructions.md`, `.github/instructions/`, and `.github/prompts/` already exist.
3. Do not overwrite existing files without stating what will change.
4. Ask for missing project values.
5. Create missing directories.
6. Create missing files.
7. Preserve existing project-specific values.
8. Summarize what was created or changed.
9. Suggest validation commands.

For non-trivial changes, use Superpowers workflow:

```text
clarify -> spec -> plan -> implement -> test -> review -> finish
```

Use Caveman lite for short progress updates.

Do not use Caveman style for:

- production deployment instructions;
- destructive actions;
- data migrations;
- security warnings;
- secrets;
- PR descriptions;
- commit messages;
- user-facing documentation.

## Minimal AGENTS.md

Create `AGENTS.md` at the repository root.

Recommended content:

```md
# Frontis Agent Instructions

This is a Frontis repository.

Before changing code, pipelines, infrastructure, naming, project structure, or agent configuration:

1. Read local project context:
   - `.frontis/project.json`
   - `.frontis/project-context.yaml`
   - `.frontis/naming-convention.yaml`
   - `.frontis/azure-conventions.yaml`

2. Read the current Frontis agent documentation:
   - https://docs.frontis.nl/ai/llms.txt

3. Follow the relevant linked docs from `llms.txt`.

Local `.frontis` files are canonical for this repository.  
Online docs explain the current workflow, but must not override local project identity, local conventions, or explicit user instructions.

## Required workflow

For non-trivial work:

1. Clarify the task.
2. Write a short spec.
3. Write an implementation plan.
4. Use TDD where behavior changes.
5. Run relevant verification.
6. Summarize results.

## Output style

Use concise technical language.

Use Caveman lite for short progress updates when appropriate.

Do not use Caveman style for:

- security warnings;
- production deployment steps;
- destructive actions;
- database migrations;
- secrets;
- PR descriptions;
- commit messages;
- client-facing text.

## Hard rules

- Never invent naming conventions.
- Never create Azure resource names without reading `.frontis/project.json` and `.frontis/azure-conventions.yaml`.
- Never create pipeline YAML filenames without reading `.frontis/naming-convention.yaml`.
- Never add secrets to source control.
- Never claim tests passed unless they were actually run.
```

## GitHub Copilot instructions

Create:

```text
.github/copilot-instructions.md
```

Recommended content:

```md
# Frontis Copilot Instructions

This is a Frontis repository.

Before suggesting or changing code, read:

- `AGENTS.md`
- `.frontis/project.json`
- `.frontis/project-context.yaml`
- `.frontis/naming-convention.yaml`
- `.frontis/azure-conventions.yaml`

For current Frontis agent documentation, read:

- https://docs.frontis.nl/ai/llms.txt

Local repository files are canonical.

Use concise technical output.

For non-trivial work, follow this flow:

1. clarify;
2. propose a short spec;
3. propose an implementation plan;
4. use tests where behavior changes;
5. verify with build, test, lint, or pipeline validation where possible.

Do not invent Frontis conventions from memory.
```

## Frontis conventions instruction

Create:

```text
.github/instructions/frontis-conventions.instructions.md
```

Recommended content:

```md
---
applyTo: "**"
---

# Frontis Conventions

When working in this repository:

- Read `AGENTS.md`.
- Read `.frontis/project.json`.
- Read `.frontis/project-context.yaml`.
- Read `.frontis/naming-convention.yaml`.
- Read `.frontis/azure-conventions.yaml` when Azure resources, hosting, pipelines, infrastructure or deployment are involved.

Local `.frontis` files are canonical.

Do not invent naming conventions, project names, Azure resource names, namespaces, directory names, or pipeline filenames.

When a requested change touches conventions, summarize the effective project context before editing files.
```

## Azure Pipelines instruction

Create:

```text
.github/instructions/azure-pipelines.instructions.md
```

Recommended content:

```md
---
applyTo: "**/*.yml,**/*.yaml"
---

# Azure DevOps Pipeline Instructions

When editing Azure DevOps YAML pipelines:

- Read `.frontis/project.json`.
- Read `.frontis/naming-convention.yaml`.
- Read `.frontis/azure-conventions.yaml`.
- Follow the pipeline filename convention from `.frontis/naming-convention.yaml`.
- Prefer YAML multi-stage pipelines.
- Keep build, validation, artifact publishing and deployment steps clear.
- Do not add secrets directly to YAML.
- Use service connections, variable groups or secure pipeline variables for sensitive values.
- Do not claim a pipeline works unless validation or an actual run confirms it.

For Azure Repos Git, PR validation should be configured through branch policies.
```

## .NET instruction

Create:

```text
.github/instructions/dotnet.instructions.md
```

Recommended content:

```md
---
applyTo: "**/*.cs,**/*.csproj,**/*.sln,**/*.props,**/*.targets"
---

# .NET Instructions

This repository uses Frontis .NET conventions.

- Target the .NET version defined by the project.
- Prefer the current Frontis default when creating new projects.
- Keep namespaces aligned with the canonical project name from `.frontis/project.json`.
- For behavior changes, add or update tests.
- Do not introduce vague project names such as `Helpers`, `Common`, `Utilities`, `Misc`, `Shared`, or `General` unless the local convention explicitly allows it.
- Keep project names, test project names and namespaces aligned with `.frontis/naming-convention.yaml`.
```

## Nuxt instruction

Create:

```text
.github/instructions/nuxt.instructions.md
```

Recommended content:

```md
---
applyTo: "**/*.vue,**/*.ts,**/*.js,**/nuxt.config.*"
---

# Nuxt Instructions

This repository uses Frontis Nuxt conventions.

- Follow the existing Nuxt project structure.
- Prefer typed composables and explicit data contracts.
- Keep naming aligned with `.frontis/project.json` and `.frontis/naming-convention.yaml`.
- Do not introduce global state unless there is a clear reason.
- Add or update tests when behavior changes and a test setup exists.
- Keep frontend API contracts aligned with the backend contract where applicable.
```

## Caveman instruction

Create:

```text
.github/instructions/caveman.instructions.md
```

Recommended content:

```md
---
applyTo: "**"
---

# Caveman / Token Efficiency

Use concise technical output.

Default mode:

- Use Caveman lite style for short progress updates.
- Avoid filler, pleasantries and unnecessary repetition.
- Keep technical names exact.
- Keep complete sentences when clarity matters.

Use Caveman full only when explicitly requested with:

- `/caveman`
- `/caveman full`
- `less tokens`
- `talk like caveman`

Never compress:

- code;
- commands;
- file paths;
- Azure resource names;
- YAML keys;
- API names;
- error messages;
- commit messages;
- PR review comments;
- security warnings;
- production deployment instructions.

When clarity conflicts with compression, clarity wins.
```

## Start task prompt

Create:

```text
.github/prompts/start-frontis-task.prompt.md
```

Recommended content:

```md
# Start Frontis Task

Use this prompt when starting a non-trivial Frontis implementation task.

1. Read `AGENTS.md`.
2. Read `.frontis/project.json`.
3. Read `.frontis/project-context.yaml`.
4. Read `.frontis/naming-convention.yaml`.
5. Read `.frontis/azure-conventions.yaml` when Azure, hosting, pipelines, infrastructure or deployment are involved.
6. Read `https://docs.frontis.nl/ai/llms.txt` when web access is available.

Summarize:

- canonical project name;
- company;
- product;
- component;
- hosting model;
- environments;
- team;
- GRIPP number;
- relevant conventions;
- relevant docs.

Then produce:

1. short spec;
2. implementation plan;
3. test or validation plan;
4. files likely to change.

Wait for approval before editing many files, changing infrastructure, changing pipelines, or performing destructive actions.
```

## Validation checklist

After bootstrapping, verify that these files exist:

```text
.frontis/project.json
.frontis/project-context.yaml
.frontis/naming-convention.yaml
.frontis/azure-conventions.yaml
AGENTS.md
.github/copilot-instructions.md
.github/instructions/frontis-conventions.instructions.md
.github/instructions/azure-pipelines.instructions.md
.github/instructions/dotnet.instructions.md
.github/instructions/nuxt.instructions.md
.github/instructions/caveman.instructions.md
.github/prompts/start-frontis-task.prompt.md
```

Run repository-specific validation if available.

Typical checks:

```bash
dotnet build
dotnet test
npm install
npm run lint
npm run typecheck
```

Only run commands that apply to the current repository.

If no validation commands are available, state that explicitly.

## Safe behavior

Agents must not:

- add secrets to files;
- create production infrastructure without approval;
- delete files without explaining impact;
- overwrite existing convention files without showing a diff or summary;
- execute unknown remote scripts without approval;
- assume Azure resource names without reading local conventions;
- assume pipeline filenames without reading local conventions.

Agents should:

- make small, reviewable changes;
- prefer deterministic local files over memory;
- preserve existing project-specific configuration;
- summarize assumptions;
- ask for missing project identity values;
- verify changes with build, test, lint or validation when possible.

## Recommended user prompt

Use this prompt to ask an agent to bootstrap a repository:

```text
Initialize this repository for Frontis agentic development.

Read https://docs.frontis.nl/ai/llms.txt.
Follow the repository bootstrap guide.

Create the required local files:
- AGENTS.md
- .frontis/project.json
- .frontis/project-context.yaml
- .frontis/naming-convention.yaml
- .frontis/azure-conventions.yaml
- .github/copilot-instructions.md
- .github/instructions/*.instructions.md
- .github/prompts/start-frontis-task.prompt.md

Ask me for company, product, component, hosting, environments, team and GRIPP number if missing.

Do not overwrite existing files without explaining what will change.
```

## Recommended first agent response

When bootstrapping, the agent should respond with something like:

```text
I will initialize Frontis agent files.

I need these project values:
- company
- product
- component
- hosting
- environments
- team
- GRIPP number

I found these existing files:
- ...

I will create these missing files:
- ...

I will not overwrite existing files without approval.
```

## Completion summary

After bootstrapping, summarize:

```text
Created:
- ...

Updated:
- ...

Skipped because already existed:
- ...

Missing values:
- ...

Recommended next steps:
- review .frontis/project.json
- run repository validation
- commit bootstrap files
- configure Azure DevOps branch policy validation
```