Workflow discipline · for AI coding · tool-agnostic

The day-one discipline. In any Agent. In one prompt.

One markdown file. Any agentic coding assistant. One prompt. Your repo grows the discipline a Senior Engineer would have set up on day one — workflow rules, ADR culture, the testing pyramid, telemetry, security rubric, TODO discipline — then bundles every change into one focused git commit. Tool-agnostic. Cross-stack. Idempotent.

Get AGENTIC-BOOTSTRAP.md View on GitHub
Project-agnostic Re-runnable No dependencies One file

Works with

Claude Code · Cursor · Aider · OpenAI Codex CLI · OpenCode · Continue.dev · Windsurf · GitHub Copilot

One tool-agnostic spine — AGENTS.md + .agents/rules/ — plus a thin adapter file per assistant you pick.

~/my-new-project
$ claude # or cursor · aider · codex · …
› follow AGENTIC-BOOTSTRAP.md to bootstrap this repo
▸ Project name? "orbital"
▸ Agents used? Claude, Cursor, Aider
▸ Language? Python
▸ Architecture? 4-Layer DDD
… 11 more questions, one commit later …
# Scaffold written:
AGENTS.md · .agents/rules/ · .docs/{adrs,prompts,todos}/
CLAUDE.md · .cursor/rules/ · .aider.conf.yml # adapters
+ first commit recording the bootstrap itself

60-second demo

Three steps. One file. One commit.

No dependencies. No SDK. The discipline lives in a single markdown file you can read end-to-end.

01

Drop the file

Save AGENTIC-BOOTSTRAP.md at the root of any repo — fresh or existing.

$ curl -O https://raw.githubusercontent.com/
  sciensoft/agentic-bootstrap/develop/AGENTIC-BOOTSTRAP.md
02

Tell the agent

Hand it to your assistant of choice — Claude Code, Cursor, Aider, Codex, Continue.dev, Windsurf, Copilot — with one prompt.

› follow AGENTIC-BOOTSTRAP.md
  to bootstrap this repo
03

Get the scaffold

17 questions, smart defaults, then the agent writes the rules, ADR index, prompt log, per-tool adapters, the test scaffold — and bundles it all into one disciplined commit.

# 28 files written · tests/ scaffolded
# [main] chore: bootstrap project (1 commit)

What you get

A repo that knows its own rules.

Every artifact has a reason. AGENTS.md is the primary cross-tool brief. .agents/rules/ holds the durable workflow rules. .docs/ grows with the project — ADRs, timestamped prompts, deferred TODOs, security audits. Per-tool adapters (CLAUDE.md, .cursor/rules/, .aider.conf.yml, …) are thin pointers.

  • › Prompt log — every artifact-producing request gets a timestamped file under .docs/prompts/. Read it back like git log with intent.
  • › ADR culture — slim Nygard format. New module / pattern / dependency → new ADR. Index auto-maintained.
  • › Do-later, captured — deferred ideas land as one-file-per-entry under .docs/todos/. No buried promises.
  • › Security rubric — OWASP-aligned methodology plus LLM-specific sub-rubric. Dated audits on cadence.
  • › Tests ship with the code — pyramid-shaped, mocks at boundaries only, bug fixes start with a failing regression test. Tests bundled into the same commit as the behaviour they prove.
  • › One commit per request — prompt + ADR + tests + telemetry + code, staged explicitly by path. git log is the project's story; no git add -A ever.
your-repo/
├── AGENTS.md                       # primary cross-tool brief — title, purpose, run, architecture
├── README.md · LICENSE · SECURITY.md
│
├── .agents/                        # tool-agnostic spine
│   ├── rules/
│   │   ├── workflow.md             # prompt → ADR → telemetry → commit → push
│   │   ├── workflow-todos.md       # how do-later ideas are captured
│   │   ├── workflow-security.md    # per-request security checks
│   │   ├── best-practices.md       # code-style + idioms
│   │   └── layered-architecture.md # 4-Layer / 3-Tier / SPA / Monorepo / Serverless
│   └── bootstrap.json              # interview answers — re-runnable
│
│   # Per-tool adapters — only the ones you picked get written:
├── CLAUDE.md                       # Claude Code adapter (@-includes the brief)
├── .claude/settings.json          # Claude permission posture (cautious → bypass)
├── .cursor/rules/agents.mdc      # Cursor adapter (alwaysApply: true)
├── .aider.conf.yml                 # Aider read: list
├── .continue/config.json         # Continue.dev rules entry
├── .windsurfrules                  # Windsurf adapter
├── .github/copilot-instructions.md # Copilot adapter (rules inlined)
│
└── .docs/
    ├── prompts/                    # timestamped, one per request
    ├── adrs/                       # slim Nygard format, indexed
    ├── todos/                      # one file per deferred idea
    └── security/
        └── methodology.md           # OWASP + LLM-specific rubric

Features

Process, encoded.

AI agents are powerful but undisciplined. Without a process, decisions vanish, TODOs pile up, and changes lose their why. The bootstrap turns the discipline into files.

Interview-driven

17 targeted questions. Smart defaults. Re-runnable — adding a new question only asks existing projects that one.

One request, one commit

Every request bundles prompt file + ADR (when it matters) + tests + telemetry + code into a single focused commit. Deferred ideas land as one-file-per-entry under .docs/todos/ — context, deferred-because, revisit-when. No drive-by changes. No buried promises. git log reads as the project's story.

ADRs with the right diagram

Slim Nygard format, indexed by README. The agent picks the Mermaid type that fits — flowchart, sequenceDiagram, stateDiagram, erDiagram, C4Context, gitGraph, gantt, and any other Mermaid type the situation calls for — guided by a picker table that maps decision-shape to diagram-type, plus readability conventions that keep diagrams legible.

Tests ship with the code

Pyramid-shaped: unit-heavy, integration-light, e2e-thin. Mock at boundaries, never at internals. Bug fixes start with a failing regression test that becomes the bug's tombstone. TDD encouraged but not mandated — the hard rule is tests + code land in the same commit, always. Coverage tracked, never gated by a percentage.

Security, built in

OWASP Top 10 rubric plus optional LLM sub-rubric (prompt injection, tool agency, supply chain). Dated audits as siblings.

Polyglot & stack-aware

Python · TypeScript · Go · Rust scaffolds, paired with 9 architecture shapes (4-Layer DDD · Hexagonal · Microservice · Vertical Slice · 3-Tier · SPA · Flat · Monorepo · Serverless). And when your agent has web search, best-practices.md gets refined live from current sources for your exact stack, with inline citations — falling back to a sensible generic baseline when search isn't available.

Architectures supported

Pick a shape. Get the rules.

The interview detects the difference between system topology ("microservices") and internal code organisation — and routes you to the right scaffold for each.

4-Layer DDD

ARCH=4_LAYER_DDD

Presentation → application → domain ← infrastructure + shared. Non-trivial backends with multiple I/O surfaces.

presentation/ · application/ · domain/ · infrastructure/ · shared/

Hexagonal · Clean · Onion

ARCH=HEXAGONAL

Pure domain/ with ports/ + symmetric adapters/primary & /secondary. Covers the Ports-and-Adapters / Clean / Onion family in one template.

domain/{model,ports/{primary,secondary},service}/ · adapters/{primary,secondary}/ · shared/

Classical 3-Tier

ARCH=3_TIER

Presentation / business / data. Simpler CRUD apps — Rails/Django/.NET-style.

presentation/ · business/ · data/ · shared/

SPA Frontend

ARCH=SPA

Pages → components → hooks → services. React / Vue / Svelte conventions.

pages/ · components/ · hooks/ · services/ · stores/

Flat

ARCH=FLAT

No layering — modules organised by topic. CLIs, libraries, small scripts.

no layered-architecture.md written

Monorepo

ARCH=MONOREPO

Apps + services + packages. Each sub-project picks its own internal architecture.

apps/ · services/ · packages/ · tools/

Serverless

ARCH=SERVERLESS

Handler-per-trigger + thin lib/ core. AWS Lambda / Cloud Functions / Workers / Vercel.

handlers/{http,events,scheduled}/ · lib/ · shared/

Microservice

ARCH=MICROSERVICE

One service in a larger ecosystem. 4-Layer DDD internals plus health / readiness, retries + circuit breakers, distributed tracing, consumer-driven contracts.

presentation/{http,health,messaging}/ · application/ · domain/ · infrastructure/{clients,telemetry}/ · contracts/

Vertical Slice

ARCH=VERTICAL_SLICE

Organise by feature, not by layer. Each slice owns its handler / service / model / repository / tests. Features may only import from shared/ — never from each other.

features/<feature>/{handler,service,model,repository,tests}/ · shared/{domain,infrastructure,…}/

Permission postures

Trust on your terms.

Pick how much autonomy your agent gets — from "ask for everything" to "no prompts ever" — and the bootstrap fans that one intent out across every tool you picked. Claude gets a .claude/settings.json; Cursor gets .cursor/settings.json; Aider gets the matching keys in .aider.conf.yml; Codex gets .codex/config.toml; Continue.dev gets a tools-autonomy block in .continue/config.json; Windsurf gets .windsurf/settings.json. OpenCode and Copilot don't have file-based permission models — their adapters carry a posture-intent note you apply in the IDE.

Autonomy axis

Cautious
all prompts
Read-only
reads pass
Trusted dev
daily dev flows
Bypass
no prompts
Friction ↓ Autonomy ↑
01

Cautious

POSTURE=CAUTIOUS

Every action prompts. Safest for shared / team / open-source projects.

02

Read-only autonomy

POSTURE=READONLY

Pre-allows safe reads (ls, cat, grep, git status/log/diff). Writes still prompt.

03

Trusted dev

POSTURE=TRUSTED_DEV

Reads + safe git + language-specific build/test (uv:* · npm:* · go:* · cargo:*). Force-push / hard-reset still gated.

04

Full bypass

POSTURE=BYPASS

No prompts, ever. Only safe in dedicated dev VMs / containers / trusted personal workspaces.

Two weeks later

The discipline shows up in git log.

Day 1 is one focused commit. By the second week, every change carries its prompt file, its ADR when it matters, its tests, its security checks. Reading the history reconstructs the why, not just the what.

~/orbital — git log --oneline --decorate
* a3f2b1c (HEAD -> main) feat(orders): cancellation flow with refund pathway * d8e4c92 docs(adrs): 0007-saga-for-cross-service-orders + sequenceDiagram * b1a7f5e refactor(payments): swap Stripe wrapper for a tested adapter * 9c3d2a8 fix(auth): close session-fixation gap surfaced by 2026-06-22 audit * 7e1b4d6 chore(deps): pin pgx 5.6.0; weekly security review 2026-06-22 * 5a8c1f3 feat(metrics): order-fulfilment golden signals; cardinality verified * 3b9e7a2 docs(prompts): 1750000000.tune-retry-budgets — captured before tuning * 0d5e9a1 test(orders): regression for inventory race; bug 2026-06-15 * 1c2f8d4 Bootstrap project with agentic workflow conventions
Every commit above ships with at least one prompt file under .docs/prompts/. Architecturally significant changes — the saga ADR, the metrics surface, the Stripe-wrapper swap — carry their own ADR. The audit-driven fix cites the dated security review. The bug fix begins with a failing regression test. The bootstrap commit sets up all of that on day one.

Adoption

See it. Run it. Audit it.

Three example projects show what the bootstrap actually produces. A 60-second quickstart walks the steps. A doctor mode audits an existing repo against the rules without writing anything.

Examples

See the output

Three fully-bootstrapped sample projects — python-4layer-ddd, typescript-vertical-slice, go-microservice. Browse what lands before you run it.

Browse examples/ →

Quickstart

60 seconds, three steps

Drop the file, prompt the agent, get the scaffold + first commit. Includes the question-by-question reference and a side-by-side comparison vs Cookiecutter / copier / a hand-typed agent brief.

Read QUICKSTART.md →

Doctor mode

Audit without writing

Already bootstrapped? Ask "run bootstrap-doctor against this repo" for a structured drift report — missing rule files, stale answer cache, security audits overdue, stub best-practices, ADR-index drift. No writes; pure read.

See doctor-mode spec →

Why this, not …

Not a template engine. Not a CLI. Not a hand-typed brief.

  This bootstrap Cookiecutter / copier Hand-typed agent brief
Output Disciplined repo + first commit A working repo A markdown file
Tools supported 8 agentic assistants N/A — templating tool One
Discipline encoded Workflow + ADRs + tests + security + TODOs Whatever the template author wrote Whatever you typed
Architectures 9, with diagram picker Whatever the template author wrote None
Live best-practices Refined from current sources for your stack Frozen at template-author time Frozen at typing time
Onboarding cost One file. One prompt. 60 seconds. Install + find + verify a template Hours of typing
Re-runnable Yes — idempotent; picks up new conventions Usually no No
Audit mode Yes — doctor mode reports drift No No
Star on GitHub v2026-06-10 Changelog Contribute lint-bootstrap status CI
MIT licensed · re-runnable · failure-safe refinement · CI-linted · 8 tool adapters

Found a bug, got an idea, or built something you'd like to ship?

Open an issue Start a discussion Open a PR

Ship the discipline. Not the boilerplate.

One file. One prompt. One commit. Drop it into a fresh repo, an existing repo, or re-run it later — the bootstrap reuses your prior answers and only asks about what's new.

Download AGENTIC-BOOTSTRAP.md Read it on GitHub

› follow AGENTIC-BOOTSTRAP.md to bootstrap this repo