SDA Bootstrap Kit

This repository contains a reusable bootstrap kit for introducing Self Driven Architecture (SDA) into a software project.

SDA is a software engineering methodology designed to help an AI model maintain an operational awareness of a project and assist its evolution under human supervision.

SDA does not mean fully autonomous development.

It means a project becomes:

• explicit enough to be understood by an AI;
• structured enough to be safely evolved;
• tested enough to detect regressions;
• documented enough to preserve decisions;
• observable enough to assess risks, drift and roadmap progress.

Quick Start (CLI)

Install SDA into any existing project with one command — no global install required:

npx sda-kit init --profile=core+tests

This copies the kit into docs/sda/, generates the project-owned files (STATE.md plus the logs for your profile), and wires your AI tool (AGENTS.md, or .cursor/rules/ if a .cursor/ directory is present) to point at docs/sda/INDEX.md. It never touches runtime code.

Then ask your AI coding assistant:

Start at `docs/sda/INDEX.md`.

Do not modify code yet.

Analyze this project and prepare a Self Driven Architecture integration plan according to the bootstrap instructions.

INDEX.md is the single entry point. The AI loads the kernel, then pulls only what the current task needs — it should not read every file. The first output is an analysis and proposal, not code changes.

CLI commands

| Command | Purpose | |---|---| | sda init [--profile=<p>] [--dir=<path>] | Install SDA + scaffold the chosen profile | | sda status | Show profile, capabilities and STATE.md freshness | | sda add <cap> | Add a capability (roadmap, todo, tests, decisions, risk) | | sda remove <cap> | Remove a capability (its log is archived, not deleted) | | sda update | Refresh kernel + practices; never touches project logs | | sda doctor | Validate the installation | | sda uninstall [--all] | Remove SDA (reversible; runtime code untouched) |

The CLI maps directly onto the kit's layer model: static files (kernel rules + practices) are copied and refreshed by init/update, while logs (STATE.md, roadmap.md, …) are project-owned and never overwritten. A small .sda.json manifest in docs/sda/ records the active profile and kit version.

Useful flags: --profile=core+roadmap+todo+tests, --with-claude / --with-cursor / --with-agents / --no-wire (tool pointer), --yes (skip confirmations), --force (reinstall).

Manual usage (no CLI)

You can still copy this kit into docs/sda/ by hand. The generated instance files (STATE.md, roadmap.md, …) live in that same docs/sda/ directory, and you run the same initialization prompt above.

The 3-Layer Model

SDA files are organized by how they behave (see sda-architecture.md):

• Kernel (always loaded): sda-operating-rules.md + STATE.md.
• Logs (per-project state, loaded when relevant): roadmap.md, todo.md, decisions.md.
• Practices (knowledge, on demand): testing, blind-spots, git, rollback, roadmap, profiles.

Core Documents

| File | Layer | Purpose | |---|---|---| | INDEX.md | Kernel | Single entry point + task→file map | | sda-operating-rules.md | Kernel | AI behavior and the four validation gates | | sda-state.md | Kernel | Spec for STATE.md, the operational-awareness snapshot | | sda-philosophy.md | Meta | Principles and scope (the why) | | sda-architecture.md | Meta | The 3-layer model and file mapping | | sda-profiles.md | Practice | Composable capability/profile system | | sda-failure-modes.md | Meta | How SDA can harm a project + safeguards | | sda-initialization-prompt.md | Meta | Entry ritual + initialization-report template | | sda-project-analysis.md | Practice | Initial project audit | | sda-roadmap.md | Practice | Roadmap strategy → produces roadmap.md | | sda-todo.md | Practice | Tactical TODO strategy → produces todo.md | | sda-decisions.md | Practice | Decision history → produces decisions.md | | sda-testing.md | Practice | Regression and test strategy | | sda-blind-spots.md | Practice | Technical/product/legal/economic/human risks | | sda-git.md | Practice | Commit discipline | | sda-branching.md | Practice | Branch strategy + Git operations requiring human approval | | sda-rollback.md | Practice | Soft disable and hard rollback |

Files consolidated during the redesign are kept in archive/ (see archive/README.md).

Recommended First Step

For an existing project, start with:

1. project analysis;
2. SDA readiness assessment;
3. proposed minimal SDA structure;
4. no code modification;
5. human validation.

Important

SDA must remain:

• adaptive;
• lightweight;
• reversible;
• proportional to project complexity;
• non-invasive for runtime code.