Agentic AI changed how we build software.

Keep the flow, and the Engineering.

Work naturally with your agentic AI. AGENTIC_BOOTSTRAP continuously turns the architecture, decisions, trade-offs, and future ideas created along the way into lasting project knowledge—without interrupting your flow.

Get AGENTIC-BOOTSTRAP.md View on GitHub

Project-agnostic Re-runnable No dependencies One file

Works with

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

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

                
                ~/my-new-project
              
$ claude # or cursor · codex ·
                  cn · …
› follow AGENTIC_BOOTSTRAP.md and
                  let's build this together▍

                ▸ Project name? "orbital"

                ▸ Agents used? Claude, Cursor, Codex

                ▸ 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.

Before you run · two requirements

Capable model. Claude Sonnet / Opus, GPT-4 class, Gemini 1.5 / 2.x, full DeepSeek-V3, Qwen 2.5 Coder 32B+. Smaller distilled reasoners may skip steps in this multi-step playbook.

~80k context window that fits. Verify your model + runtime + tool can carry it. Watch for GGUF caps at 32k (most Qwen 2.5, Codestral, Phi-4), runtime defaults (Ollama, vLLM, llama.cpp), and agents that re-send the file every turn.

Can't meet both? A hosted API for the one-shot is rounding error against a single dev day.

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

Tell the agent

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

› follow AGENTIC-BOOTSTRAP.md
and let's build this together

Re-run is safe — it's idempotent.

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)

That's the setup. From here, it's you and your agent doing what you already do — with a repository that remembers.

Nudge it if it stalls

Less-capable models sometimes acknowledge the file but won't start.

Paste this to get them moving:

› Begin with Step 0 — detect run mode,
then ask me Q1.

Nudge it toward rich prompts

Some hosts have interactive prompt UI (pickers, multi-select) but default to plain text on the first read.

Paste this to get the pickers:

› use your interactive prompts
(pickers, multi-select) —
one call per question

Origin

Built from real engineering

AGENTIC_BOOTSTRAP wasn't born from trying to build a product. It was born from trying not to repeat myself.

It started while building a project where I gradually developed a better way of collaborating with agentic AI. As the project evolved, so did the engineering: architectural decisions, TODOs, conventions, prompt history, ADRs, and the operating model itself.

Then I started another project.

Almost immediately I found myself thinking:

“I wish this project had everything I built into the last one.”

Instead, I was rebuilding the same engineering practices from scratch. Repeating conversations with the AI. Rediscovering conventions. Losing valuable ideas because they lived only inside the chat. Avoiding clearing the context because I didn't want to lose the reasoning that got us there.

By the third project, it was obvious.

This shouldn't be something I rebuilt every time.

It should be something I bootstrap once and evolve forever.

That's why AGENTIC_BOOTSTRAP exists.

It gives every new project the engineering maturity of the previous one from day one.

Start with the bootstrap.

Keep what works.

Remove what doesn't.

Add your own skills, workflows, standards, and conventions.

Evolve it with your project.

AGENTIC_BOOTSTRAP gives you the first version of your operating model. What it becomes is yours.

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 (plus generic fallback for C# · Java · Ruby · PHP · Kotlin · Swift · anything else), 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.

Runtime footprint

Runs once. Then steps out of the way.

The bootstrap is heavyweight at scaffold time and lightweight forever after. A template index lets capable agents skip what doesn't apply to your answers, cutting scaffold cost further. The playbook's cost is paid at bootstrap. Regular sessions stay lightweight.

Scaffold · smart agent

~25k tokens

Claude Code, Cursor, Codex CLI — agents whose Read tool supports offset + limit. Reads the operator playbook, interview, and decision matrix, then jumps straight to only the ~15 templates your answers require. Skips the other ~65.

Scaffold · naive fallback

~80k tokens

Agents without offset reads, or hosts that ignore the index instruction, fall through to top-to-bottom reading. No functionality lost; the bootstrap still works — you just pay the full playbook cost. Backward-compatible safety net.

Every session after

~5–15k tokens

Agents usually auto-load only the thin spine — AGENTS.md plus the relevant rule files under .agents/rules/. The footprint depends on the gates you enabled and the assistant's loading strategy, but it stays far smaller than the original bootstrap playbook.

The bootstrap pays its token cost at scaffold time. Your team works at the runtime cost forever after.

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; Codex gets .codex/config.toml; Continue.dev gets a tools-autonomy block in .continue/config.json; Windsurf gets .windsurf/settings.json; Aider gets the matching keys in .aider.conf.yml. 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 ↑

Cautious

POSTURE=CAUTIOUS

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

Read-only autonomy

POSTURE=READONLY

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

Trusted dev

POSTURE=TRUSTED_DEV

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

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

MIT licensed · re-runnable · failure-safe refinement · CI-linted · 8 tool adapters

Keep the flow, and the Engineering.

Three steps. One file. One commit.

Drop the file

Tell the agent

Get the scaffold

Built from real engineering

A repo that knows its own rules.

Process, encoded.

Interview-driven

One request, one commit

ADRs with the right diagram

Tests ship with the code

Security, built in

Polyglot & stack-aware

Runs once. Then steps out of the way.

Pick a shape. Get the rules.

4-Layer DDD

Hexagonal · Clean · Onion

Classical 3-Tier

SPA Frontend

Flat

Monorepo

Serverless

Microservice

Vertical Slice

Trust on your terms.

Cautious

Read-only autonomy

Trusted dev

Full bypass

The discipline shows up in git log.

See it. Run it. Audit it.

See the output

60 seconds, three steps

Audit without writing

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

Ship the discipline. Not the boilerplate.