Vibe Codebase Structure

Purpose

Help vibe coders start production projects with a repository that is:

• understandable by humans and coding agents;
• reproducible across machines;
• testable with one clear verification command;
• secure by default;
• deployable and observable;
• recoverable after failures;
• governed by explicit specifications and architectural rules.

This skill focuses on project structure, repository files, agent guidance, testing, security, CI/CD, operations, and production readiness. It is stack-agnostic unless the user provides a specific technology stack.

When to use this skill

Use this skill when the user asks to:

• create a production-grade project structure;
• review whether a repository is ready for production;
• define must-have and good-to-have files or directories;
• make a project safer for vibe coding or agent-driven development;
• create AGENTS.md, architecture docs, specifications, runbooks, or CI structure;
• organize a monorepo or single-application repository;
• add missing testing, security, infrastructure, observability, or deployment folders;
• prepare a codebase for Cursor, Codex, Claude Code, Copilot, or other coding agents;
• create a reusable repository starter template.

Do not use this skill only to generate application features, UI screens, or business logic unless repository structure is also part of the request.

Core principle

A production-grade repository is not defined by the number of folders.

It is production-grade when a new developer or coding agent can answer:

1. What does the system do?
2. How is the repository organized?
3. How do I set it up?
4. How do I run it?
5. How do I verify a change?
6. Which architectural boundaries must not be crossed?
7. How are database changes performed safely?
8. Where are secrets stored?
9. How is the application deployed?
10. How is it monitored?
11. How is it restored after failure?
12. What evidence is required before declaring work complete?

Classification system

Classify recommended files and directories using:

• Must have — required for most production projects.
• Conditional — required when the related capability exists.
• Good to have — valuable but not always necessary.
• Agent-critical — especially important for AI-assisted development.

Avoid labeling everything as mandatory. Adapt the structure to project size, risk, deployment model, team size, and regulatory requirements.

Required discovery

Before designing the repository, determine as much of the following as possible from the conversation or existing files:

• application type: web, API, mobile, desktop, CLI, data, AI, or mixed;
• single repository or monorepo;
• primary stack and package manager;
• database and migration tool;
• deployment target;
• CI/CD provider;
• whether containers are used;
• whether agents will modify the repository;
• security or compliance sensitivity;
• team size;
• whether the project is greenfield or existing;
• whether public APIs, queues, workers, cron jobs, or third-party integrations exist.

When details are missing, make conservative assumptions and clearly identify conditional sections. Do not force enterprise complexity onto a small project.

Workflow

Step 1: Identify the project profile

Classify the project into one of these profiles:

Small production application

Typical characteristics:

• one application;
• one database;
• one deployment target;
• small team;
• limited infrastructure.

Use a compact structure with strong basics.

Multi-application or monorepo

Typical characteristics:

• frontend, backend, admin, workers, or shared packages;
• multiple deployment units;
• shared libraries;
• separate ownership boundaries.

Use apps/, packages/, nested documentation, and scoped agent instructions.

High-assurance or enterprise system

Typical characteristics:

• regulated data;
• strict uptime or audit requirements;
• complex infrastructure;
• multiple teams;
• security review;
• formal releases.

Add threat modeling, SBOM, provenance, service-level objectives, incident runbooks, environment protections, and stricter ownership rules.

Step 2: Produce a recommended repository tree

Start with the smallest credible structure. Expand only when justified.

Minimum production structure

project/
├── README.md
├── AGENTS.md
├── SECURITY.md
├── .gitignore
├── .editorconfig
├── .env.example
├── package-manifest
├── dependency-lockfile
├── Makefile
├── src/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── specs/
├── docs/
│   ├── architecture/
│   ├── adr/
│   ├── deployment/
│   └── runbooks/
├── scripts/
│   ├── setup
│   ├── dev
│   ├── verify
│   ├── migrate
│   └── smoke-test
├── database/
│   └── migrations/
├── security/
│   ├── threat-model.md
│   └── secrets-policy.md
└── .github/
    ├── CODEOWNERS
    ├── dependabot.yml
    ├── PULL_REQUEST_TEMPLATE.md
    └── workflows/
        ├── ci.yml
        └── deploy.yml

Expanded production structure

project/
│
├── README.md
├── AGENTS.md
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
│
├── .gitignore
├── .gitattributes
├── .editorconfig
├── .env.example
├── .dockerignore
├── .nvmrc / .python-version
├── mise.toml / .tool-versions
│
├── package.json / pyproject.toml /
│   composer.json / go.mod / Cargo.toml
├── dependency-lockfile
│
├── Makefile / Taskfile.yml / justfile
├── Dockerfile
├── compose.yaml
│
├── apps/
│   ├── web/
│   ├── api/
│   ├── admin/
│   └── worker/
│
├── packages/
│   ├── ui/
│   ├── shared/
│   ├── database/
│   └── config/
│
├── src/
│   ├── domain/
│   ├── application/
│   ├── infrastructure/
│   ├── interfaces/
│   ├── config/
│   └── main.*
│
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── contract/
│   ├── e2e/
│   ├── security/
│   ├── performance/
│   ├── smoke/
│   ├── fixtures/
│   ├── factories/
│   └── helpers/
│
├── specs/
│   ├── product/
│   ├── features/
│   ├── acceptance/
│   ├── api/
│   ├── data/
│   └── templates/
│
├── docs/
│   ├── architecture/
│   ├── adr/
│   ├── api/
│   ├── database/
│   ├── development/
│   ├── deployment/
│   ├── operations/
│   ├── runbooks/
│   ├── troubleshooting/
│   └── glossary.md
│
├── agents/
│   ├── README.md
│   ├── roles/
│   ├── workflows/
│   ├── prompts/
│   ├── policies/
│   ├── checklists/
│   ├── context/
│   └── skills/
│
├── evals/
│   ├── code-generation/
│   ├── regression/
│   ├── security/
│   ├── golden-cases/
│   ├── rubrics/
│   ├── datasets/
│   └── results/
│
├── tasks/
│   ├── templates/
│   ├── proposed/
│   ├── active/
│   ├── blocked/
│   └── completed/
│
├── scripts/
│   ├── setup
│   ├── dev
│   ├── verify
│   ├── lint
│   ├── test
│   ├── typecheck
│   ├── build
│   ├── migrate
│   ├── seed
│   ├── release
│   ├── backup
│   ├── restore
│   └── smoke-test
│
├── config/
│   ├── development/
│   ├── testing/
│   ├── staging/
│   ├── production/
│   ├── feature-flags/
│   └── schemas/
│
├── database/
│   ├── migrations/
│   ├── seeders/
│   ├── factories/
│   ├── fixtures/
│   ├── schema/
│   ├── views/
│   └── README.md
│
├── api/
│   ├── openapi.yaml
│   ├── asyncapi.yaml
│   ├── schemas/
│   └── examples/
│
├── infra/
│   ├── terraform/
│   ├── kubernetes/
│   ├── helm/
│   ├── docker/
│   ├── cloud/
│   ├── environments/
│   └── README.md
│
├── deploy/
│   ├── staging/
│   ├── production/
│   ├── migrations/
│   ├── rollback/
│   └── smoke-tests/
│
├── observability/
│   ├── dashboards/
│   ├── alerts/
│   ├── logging/
│   ├── metrics/
│   ├── tracing/
│   ├── synthetic-checks/
│   └── service-level-objectives/
│
├── security/
│   ├── threat-model.md
│   ├── data-classification.md
│   ├── secrets-policy.md
│   ├── access-control.md
│   ├── dependency-policy.md
│   ├── secure-coding.md
│   ├── incident-response.md
│   ├── vulnerability-management.md
│   └── sbom/
│
├── .github/
│   ├── CODEOWNERS
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── ISSUE_TEMPLATE/
│   ├── workflows/
│   └── dependabot.yml
│
├── .devcontainer/
│   ├── devcontainer.json
│   └── Dockerfile
│
├── .cursor/
│   ├── rules/
│   └── cli.json
│
├── CLAUDE.md
├── .github/copilot-instructions.md
├── mcp.json / .mcp.json
│
├── public/
├── assets/
├── templates/
├── examples/
├── benchmarks/
└── fixtures/

Step 3: Explain the purpose of each major area

Root governance files

README.md — Must have

The README should answer:

• what the system does;
• who it is for;
• current maturity;
• architecture summary;
• required runtime versions;
• local setup;
• environment variables;
• development command;
• test command;
• build command;
• deployment overview;
• known limitations;
• ownership or support.

Keep it navigational. Put deep details in dedicated documents.

AGENTS.md — Must have for agent-driven projects

Use AGENTS.md as the canonical repository instruction file.

It should contain:

# Project purpose

# Repository map

# Supported commands
- Setup:
- Development:
- Lint:
- Typecheck:
- Unit tests:
- Integration tests:
- Full verification:
- Build:

# Architecture rules

# Security rules

# Database and migration rules

# Testing expectations

# Files agents must not modify

# Generated files

# Required documentation updates

# Pull-request expectations

# Definition of done

Recommended rules:

• Do not invent database fields.
• Do not modify production data.
• Do not change public APIs without updating their specifications.
• Do not disable tests merely to make CI pass.
• Do not add dependencies without justification.
• Do not place secrets in source code.
• Run the full verification command before reporting completion.
• Include migrations and recovery plans for schema changes.
• Add regression tests for fixed bugs.
• Update relevant documentation and ADRs.

Use nested AGENTS.md files in subdirectories when different areas require different rules.

SECURITY.md — Must have

Document:

• supported versions;
• vulnerability reporting process;
• private security contact;
• disclosure expectations;
• response process;
• scope exclusions.

Dependency manifest and lockfile — Must have

Always keep both:

• the dependency manifest;
• the resolved lockfile.

Examples:

package.json
pnpm-lock.yaml

pyproject.toml
uv.lock

The lockfile must not be casually deleted or regenerated without review.

.env.example — Must have

Include variable names, harmless examples, comments, required versus optional status, and value format.

Never commit real secrets.

.editorconfig — Must have

Use it to keep encoding, indentation, line endings, and whitespace consistent across humans and agents.

Makefile, Taskfile.yml, or justfile — Must have

Expose stable commands such as:

make setup
make dev
make lint
make typecheck
make test
make test-integration
make build
make verify
make migrate
make seed
make smoke

The most important command is a single complete verification command:

make verify

It should perform all required checks before work is considered complete.

Step 4: Define application boundaries

Single application

A clean layered layout may use:

src/
├── domain/
├── application/
├── infrastructure/
├── interfaces/
└── config/

For a smaller application:

src/
├── components/
├── services/
├── repositories/
├── models/
├── routes/
├── middleware/
├── validation/
├── utilities/
└── config/

The names matter less than documented dependency direction.

Example rules:

• Domain code must not import infrastructure code.
• Controllers call application services rather than querying the database directly.
• UI components do not call third-party APIs directly.
• Shared packages do not depend on application-specific modules.

Monorepo

Use:

apps/
├── web/
├── api/
├── admin/
└── worker/

packages/
├── ui/
├── database/
├── shared/
├── validation/
├── observability/
└── config/

Each major application or package should have its own:

• README;
• scoped AGENTS.md;
• tests;
• manifest;
• configuration;
• ownership boundaries.

Step 5: Add specifications

Use specs/ to convert vague ideas into testable contracts.

specs/
├── product/
├── features/
├── acceptance/
├── api/
├── data/
└── templates/

Feature specification template

# Feature name

## Problem

## User outcome

## In scope

## Out of scope

## User roles

## Functional requirements

## Business rules

## Validation rules

## Permissions

## Error cases

## Data changes

## API changes

## UI states

## Accessibility requirements

## Observability requirements

## Acceptance criteria

## Rollback considerations

Rewrite vague requests into concrete behavior.

Weak:

Add customer management.

Strong:

Administrators can create, edit, archive, and restore customers.

Customer email must be unique within a company.

Archived customers remain visible in historical invoices but cannot be selected
for new invoices.

Every create, update, archive, and restore action is written to the audit log.

Step 6: Build the testing structure

Recommended layout:

tests/
├── unit/
├── integration/
├── contract/
├── e2e/
├── security/
├── performance/
├── smoke/
├── fixtures/
├── factories/
└── helpers/

Minimum layers:

• unit tests for business logic;
• integration tests for database, queue, cache, and service behavior;
• end-to-end tests for critical user journeys;
• smoke tests for deployed environments;
• regression tests for important bugs.

Use contract tests when the project has:

• separate frontend and backend systems;
• external APIs;
• webhooks;
• multiple services;
• events;
• public APIs.

Use golden or snapshot cases for:

• PDFs;
• emails;
• reports;
• structured AI output;
• complex calculations;
• serialized responses.

Do not rely only on snapshots. Add meaningful assertions.

Step 7: Add agent-driven development support

agents/

Use when the project has repeated agent workflows or multiple agent roles.

agents/
├── README.md
├── roles/
├── workflows/
├── policies/
├── prompts/
├── checklists/
├── context/
└── skills/

Roles

Define responsibilities rather than fictional personalities.

Example reviewer role:

# Responsibility

Review proposed changes without modifying source files.

# Check

- Correctness
- Security
- Data integrity
- Backward compatibility
- Tests
- Error handling
- Logging
- Documentation
- Migration safety

# Required output

- Blocking findings
- Non-blocking findings
- Missing evidence
- Recommended verification commands

Workflows

Useful workflow files:

implement-feature.md
fix-bug.md
review-pull-request.md
database-migration.md
security-review.md
release-check.md
incident-investigation.md

Each workflow should define:

1. inputs;
2. preconditions;
3. allowed tools;
4. planning requirements;
5. implementation steps;
6. verification commands;
7. required evidence;
8. approval boundaries;
9. output format.

Policies

Recommended agent policies:

filesystem-policy.md
command-execution-policy.md
dependency-policy.md
database-policy.md
network-policy.md
secrets-policy.md
production-access-policy.md

Skills

Each specialized skill should use:

skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Only add scripts, references, or assets when they materially improve the skill.

evals/

Use evals to test coding-agent behavior.

evals/
├── code-generation/
├── regression/
├── security/
├── golden-cases/
├── rubrics/
├── datasets/
└── results/

Evaluate whether the agent:

• follows architecture rules;
• adds correct tests;
• preserves compatibility;
• avoids insecure dependencies;
• protects secrets;
• handles ambiguity honestly;
• creates safe migrations;
• runs required verification;
• reports failed checks accurately.

Do not store uncontrolled model transcripts containing sensitive data. Prefer compact inputs, rubrics, expected outputs, scores, and failure evidence.

tasks/

Repository-managed tasks improve traceability.

tasks/
├── templates/
├── proposed/
├── active/
├── blocked/
└── completed/

Task template:

id: FEAT-0142
title: Add customer archival
status: active
owner: platform
risk: medium

scope:
  include:
    - apps/api/src/customers
    - apps/web/src/features/customers
  exclude:
    - billing

acceptance_criteria:
  - Archived customers cannot be selected for new invoices.
  - Existing invoices continue displaying archived customers.
  - Restore is available to administrators.
  - Actions are included in the audit log.

required_checks:
  - unit
  - integration
  - e2e
  - migration-check

approval_required:
  - database-schema
  - permissions

Step 8: Add tool-specific instruction adapters

Use AGENTS.md as the canonical instruction source.

Add tool-specific files only when needed:

.cursor/rules/
CLAUDE.md
.github/copilot-instructions.md
mcp.json

Avoid duplicating the full rule set in every tool file.

Preferred pattern:

AGENTS.md                         Canonical repository rules
docs/architecture/               Detailed architecture
security/                        Detailed security policies
.cursor/rules/frontend.mdc       Cursor-specific routing
CLAUDE.md                        Small adapter to canonical docs

Never commit credentials inside MCP or agent-tool configuration.

Step 9: Document architecture and decisions

docs/architecture/

Recommended files:

overview.md
system-context.md
component-map.md
dependency-rules.md
data-flow.md
authentication.md
authorization.md
tenancy.md
integration-map.md
failure-modes.md

Architecture documentation should state boundaries explicitly.

docs/adr/

Use Architecture Decision Records to prevent repeated reversal of prior decisions.

0001-use-postgresql.md
0002-use-session-authentication.md
0003-adopt-modular-monolith.md
0004-use-database-backed-jobs.md

ADR template:

# Decision title

Status: Accepted
Date: YYYY-MM-DD

## Context

## Decision

## Alternatives considered

## Consequences

## Reversal conditions

docs/runbooks/

Recommended runbooks:

database-restore.md
failed-deployment.md
queue-backlog.md
high-error-rate.md
credential-rotation.md
storage-outage.md
third-party-api-outage.md
security-incident.md

A production system is incomplete when recovery knowledge exists only in one person’s head.

Step 10: Control database changes

Recommended layout:

database/
├── migrations/
├── seeders/
├── factories/
├── fixtures/
├── schema/
├── views/
└── README.md

Rules:

• Every schema change uses a migration.
• Released migrations are immutable.
• Destructive operations require explicit review.
• Large data migrations are separated from schema migrations.
• Rollback or forward-fix strategy is documented.
• Production data is never stored in the repository.
• Seed data is clearly labeled as test or development data.
• Tests use isolated databases.
• Backup restoration is tested.

Step 11: Add CI/CD governance

For GitHub:

.github/
├── workflows/
│   ├── ci.yml
│   ├── security.yml
│   ├── release.yml
│   ├── deploy-staging.yml
│   └── deploy-production.yml
├── CODEOWNERS
├── dependabot.yml
├── PULL_REQUEST_TEMPLATE.md
└── ISSUE_TEMPLATE/

CI should normally perform:

Install from lockfile
Validate formatting
Lint
Typecheck
Unit tests
Integration tests
Contract tests
Build
Migration validation
Dependency vulnerability scan
Secret scan
Static security analysis
Artifact generation
Smoke test

Deployment should include:

• protected environments;
• production approval when appropriate;
• immutable build artifacts;
• deployment records;
• migration handling;
• post-deployment smoke tests;
• rollback procedures.

Promote the same tested artifact to production. Do not rebuild different code during production deployment.

Step 12: Separate infrastructure, deployment, configuration, and secrets

Use:

infra/
├── terraform/
├── kubernetes/
├── helm/
├── cloud/
├── environments/
└── README.md

deploy/
├── staging/
├── production/
├── migrations/
├── rollback/
└── smoke-tests/

Keep these concepts distinct:

• Infrastructure — networks, databases, storage, identity, clusters.
• Deployment — placing a release into an environment.
• Configuration — runtime behavior and non-secret settings.
• Secrets — protected values stored outside version control.

Step 13: Make development reproducible

Recommended conditional files:

.devcontainer/
├── devcontainer.json
└── Dockerfile

Also consider:

.nvmrc
.python-version
.tool-versions
mise.toml
Dockerfile
compose.yaml

The goal is to prevent:

• runtime version drift;
• missing system dependencies;
• inconsistent test results;
• agents using unapproved tools;
• “works on my machine” failures.

Step 14: Add security structure

Recommended:

security/
├── threat-model.md
├── data-classification.md
├── secrets-policy.md
├── access-control.md
├── dependency-policy.md
├── secure-coding.md
├── vulnerability-management.md
├── incident-response.md
└── sbom/

Threat model

Document:

• sensitive assets;
• trust boundaries;
• roles;
• entry points;
• abuse cases;
• external integrations;
• authentication threats;
• authorization threats;
• data leakage risks;
• availability risks;
• mitigations;
• residual risks.

SBOM

Generate a Software Bill of Materials for higher-assurance systems.

Possible outputs:

security/sbom/application.spdx.json
security/sbom/application.cdx.json

Prefer generated SBOMs attached to build artifacts or releases over manually maintained inventories.

Build provenance

Add provenance for regulated, enterprise, public-package, containerized, or critical systems.

Step 15: Add observability and operational ownership

Recommended:

observability/
├── dashboards/
├── alerts/
├── logging/
├── metrics/
├── tracing/
├── synthetic-checks/
└── service-level-objectives/

Cover:

• request volume;
• error rate;
• latency;
• queue depth;
• job failures;
• database connection usage;
• cache behavior;
• integration failures;
• authentication failures;
• business-critical operations.

Every important alert should define:

• owner;
• severity;
• notification path;
• linked runbook;
• recovery condition.

Step 16: Validate configuration

Recommended:

config/
├── development/
├── testing/
├── staging/
├── production/
├── schemas/
└── feature-flags/

Rules:

• Validate configuration at startup.
• Fail fast when required values are missing.
• Never silently use development defaults in production.
• Keep secrets outside the repository.
• Document environment differences.
• Avoid scattered environment-name conditionals.
• Add a configuration schema when practical.

Step 17: Add conditional support files

API specifications

For HTTP APIs, events, or webhooks:

api/
├── openapi.yaml
├── asyncapi.yaml
├── schemas/
└── examples/

CHANGELOG.md

Use when releases affect customers or other systems.

Suggested sections:

Added
Changed
Deprecated
Removed
Fixed
Security
Migration required

CONTRIBUTING.md

Include:

• branch strategy;
• commit expectations;
• pull-request size;
• testing requirements;
• migration rules;
• documentation requirements;
• review process;
• release process;
• agent-use expectations.

CODEOWNERS

Example:

*                         @platform-team
/apps/web/                @frontend-team
/apps/api/                @backend-team
/database/migrations/     @database-team
/infra/                   @platform-team
/security/                @security-team

benchmarks/

Use when performance is a formal requirement.

benchmarks/
├── api/
├── database/
├── frontend/
├── memory/
└── baselines/

Store definitions and acceptable thresholds, not only screenshots.

Generated and ignored files

Usually ignore:

node_modules/
vendor/
.venv/
dist/
build/
coverage/
.cache/
.next/
.nuxt/
target/
__pycache__/
logs/
tmp/
.env
.env.*
*.log
*.sqlite
*.db

Generated files may be committed only when deliberately required.

When generated files are versioned, document:

• their source;
• regeneration command;
• whether manual edits are forbidden;
• how CI checks freshness.

Never commit

Never commit:

• API keys;
• passwords;
• private keys;
• access tokens;
• cloud credentials;
• production .env files;
• real customer databases;
• production database dumps;
• personal data;
• authentication cookies;
• browser profiles;
• unredacted logs;
• private certificates;
• agent transcripts containing secrets;
• MCP credentials;
• sensitive local paths.

Do not allow agents to create uncontrolled scratch directories inside the repository.

Priority order for vibe coders

When the user cannot implement everything at once, prioritize in this order:

Priority 1: Immediate foundations

1. README.md
2. AGENTS.md
3. dependency manifest and lockfile
4. .gitignore
5. .editorconfig
6. .env.example
7. one stable task runner
8. scripts/verify
9. basic tests
10. CI workflow

Priority 2: Intent and architecture

1. specs/templates/feature.md
2. docs/architecture/overview.md
3. docs/architecture/dependency-rules.md
4. docs/adr/
5. database migration rules

Priority 3: Production safety

1. SECURITY.md
2. security/secrets-policy.md
3. security/threat-model.md
4. backup and restore scripts
5. deployment smoke tests
6. runbooks
7. observability

Priority 4: Agent maturity

1. scoped AGENTS.md files;
2. agent workflows;
3. task templates;
4. evals;
5. tool-specific adapters;
6. reusable skills.

Recommended starter files

For a new agent-driven production project, create these first:

AGENTS.md
README.md
.env.example
.editorconfig
.gitignore
Makefile
scripts/verify
specs/templates/feature.md
docs/architecture/overview.md
docs/architecture/dependency-rules.md
security/secrets-policy.md
security/threat-model.md
tests/
.github/workflows/ci.yml

The five highest-value files for agent behavior are:

AGENTS.md
specs/templates/feature.md
scripts/verify
docs/architecture/overview.md
security/secrets-policy.md

They provide:

• context;
• a task contract;
• a verification mechanism;
• architectural boundaries;
• security limits.

Production-readiness audit

When auditing an existing codebase, check each domain.

Repository clarity

• Is the project purpose documented?
• Is the repository map accurate?
• Are setup, run, test, build, and deploy commands documented?
• Are generated and protected files identified?
• Can a new agent navigate without guessing?

Reproducibility

• Are runtime versions pinned?
• Is the dependency lockfile committed?
• Is setup automated?
• Is configuration validated?
• Can the environment be recreated?

Specifications

• Are features documented before implementation?
• Are business rules explicit?
• Are permissions and error cases documented?
• Are acceptance criteria testable?
• Are API and data changes described?

Testing

• Are business rules covered by unit tests?
• Are database and integration paths tested?
• Are critical journeys covered by end-to-end tests?
• Are deployment smoke tests present?
• Do fixed bugs receive regression tests?

Architecture

• Are dependency boundaries documented?
• Are major decisions recorded?
• Are shared packages controlled?
• Are circular dependencies prevented?
• Are public interfaces versioned?

Database safety

• Are schema changes migration-based?
• Are destructive changes reviewed?
• Are backups and restores tested?
• Is production data absent from the repository?
• Is rollback or forward-fix documented?

Security

• Are secrets externalized?
• Is vulnerability reporting documented?
• Is there a threat model?
• Are dependencies scanned?
• Are authorization boundaries tested?
• Are logs protected from sensitive data leakage?

CI/CD

• Does CI run from the lockfile?
• Does one command perform full local verification?
• Are production environments protected?
• Is the deployed artifact identical to the tested artifact?
• Are migration and rollback steps automated or documented?

Observability

• Are logs structured?
• Are metrics and traces available where needed?
• Are critical alerts configured?
• Does each alert have an owner and runbook?
• Are business-critical operations observable?

Recovery

• Are backup procedures documented?
• Has restore been tested?
• Are failed deployment and incident runbooks available?
• Are credential rotation steps documented?
• Can the team recover without the original author?

Agent safety

• Are agent permissions explicit?
• Are prohibited files and commands documented?
• Must agents run verification?
• Must they disclose failed checks?
• Are database, network, and dependency operations constrained?
• Are agent outputs reviewable and traceable?

Definition of done for repository setup

A repository-structure task is complete only when:

• the proposed structure matches the actual project profile;
• every recommended item is classified as must-have, conditional, good-to-have, or agent-critical;
• the root files have clear responsibilities;
• one full verification command is defined;
• specifications and acceptance criteria have a home;
• architecture boundaries are documented;
• database changes have a safe workflow;
• secrets are excluded from version control;
• CI validates code quality and tests;
• deployment and recovery paths are documented;
• agent permissions and completion rules are explicit;
• unnecessary enterprise complexity has been avoided.

Common anti-patterns

Avoid:

• creating dozens of empty folders with no owner or purpose;
• placing all documentation in one giant README;
• using chat history as the only specification;
• maintaining conflicting instruction files for different agents;
• allowing agents to invent architecture while implementing;
• deleting failing tests to pass CI;
• allowing direct production database changes;
• committing real .env files;
• rebuilding different code during production deployment;
• creating alerts without owners or runbooks;
• writing backup instructions without testing restoration;
• treating generated code as automatically trustworthy;
• claiming production readiness without evidence.

Output format

When helping a user, provide:

1. Project profile
2. Recommended repository tree
3. Must-have files
4. Conditional files
5. Good-to-have additions
6. Agent-specific structure
7. Implementation priority
8. Production-readiness gaps
9. Definition of done

For an existing repository, distinguish:

• already present;
• missing;
• incomplete;
• unnecessary;
• high-risk.

Prefer a practical phased plan over an enormous undifferentiated checklist.

Final quality standard

The structure should allow a competent developer or coding agent to:

• understand the system;
• find the right code;
• make a scoped change;
• follow architecture and security rules;
• test the change;
• explain the evidence;
• deploy safely;
• diagnose failures;
• restore service.

If any of those actions still depends on undocumented tribal knowledge, the repository is not yet production-grade.