# ai-superpower

AI instructions scatter across a large number of projects. Maintaining them inside each project individually is not practical — a single change requires manual updates everywhere.
This repo solves that: instructions live in one place and are distributed to all projects from here.

AI requires strong guidance to support human workflows rather than override them. Treat its outputs as zero-trust: the human reviews everything and must be willing to put their name on what the AI produced.

Good instructions are what make that possible — they allow AI to produce output that is high in quality and volume, in a way that feels natural and pleasant to work with, while keeping the human in control of the workflow.

## Principles

- **Generic vs. project-specific** — `.ai/` instructions know nothing about individual projects. Project knowledge lives in each project's own `docs/ai-context.md`.
- **Sync writes only to `.ai/`** — never touches project code or `docs/`.
- **Modular loading** — AI loads only the relevant instruction files per task, not everything at once.
- **One change, all projects** — edit here, run sync, done.
- **Version controlled** — instructions are managed in git. Changes are tracked, history is preserved, and rolling back is straightforward.

## Usage

Clone this repo directly into your dev root — the folder where all your projects live. The dev root can be anything (`~/koodi`, `~/projects`, `C:\dev`), but `ai-superpower` must be an immediate child of it. The script uses its own location to determine where to look for projects.

```
dev_root/          ← can be anywhere
├── ai-superpower/    ← must be here, at this level
├── project-a/
├── project-b/
└── some-folder/
    └── project-c/    ← nested projects are found automatically
```

```bash
cd ~/koodi
git clone https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower.git
```

From there, run the appropriate script depending on how you use your editor:

- **One project per editor window** — run `apply.sh`. It copies `.ai/` into each project and sets up context files.
- **Dev root as single workspace** — run `apply.sh`. Skips `.ai/` distribution (not needed), only sets up per-project context files.

See [apply.md](apply.md) for the full mechanism and [docs/architecture.md](docs/architecture.md) for the design.

The AI must be instructed to always read `.ai/ai-root-instructions.md` at the start of every session. In your AI assistant's system prompt or custom instructions, add:

> Always read `.ai/ai-root-instructions.md` at the start of every conversation and confirm with `✅ ai-root-instructions.md READ`.

Verify that every AI response begins with this confirmation. If it does not, the instructions have not been loaded.

## Repository structure

`ai-root-instructions.md` is the entry point — the first file the AI reads in any project. It routes to the relevant instruction files based on the task at hand.

```
ai-superpower/
└── .ai/                      ← synced to all projects
    ├── ai-root-instructions.md  ← entry point, read first
    └── instructions/
        ├── behavior/         ← how AI approaches its work
        ├── skills/           ← task-specific guides (git, docs, diagrams)
        └── constraints/      ← what AI must not do

project-x/
├── .ai/                      ← written by sync
└── docs/
    └── ai-context.md         ← project-specific, never synced
```

Clear architecture documentation — written following the instructions in this project — matters for both human and AI work. There must be a plan before building. The AI will consistently push for this, because without context it cannot work well. The vision always comes from the human; the AI helps carry it out under human supervision.