ai-superpower/README.md

# 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: a central `.ai/` folder is installed in your dev root, and every project gets a symlink to it. A `git pull` + re-run of `apply.sh` updates all projects instantly.

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`.
- **Symlink, never copy** — every project's `.ai/` symlinks directly to the `ai-superpower` repo. Edits land in git immediately — no sync step, no drift.
- **Modular loading** — AI loads only the relevant instruction files per task, not everything at once.
- **One change, all projects** — edit any instruction file from any project, commit to `ai-superpower`, and all projects pick it up on next `git pull` or `curl | bash`.
- **Version controlled** — instructions are managed in git. Changes are tracked, history is preserved, and rolling back is straightforward.

## Install

Run this from your dev root — the folder where all your projects live:

```bash
# Full setup: clone/pull + scan all projects + create/refresh docs templates
curl -fsSL https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/apply.sh | bash

# Update instructions only: pull latest .ai/ files, skip all project setup
curl -fsSL https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/apply.sh | bash -s -- --update
```

This script **must be run via `curl | bash`** from your dev root. Running it directly will fail with instructions to use the curl command.

What it does:
1. Clones (or updates) this repo into `dev_root/ai-superpower/`
2. Scans for all projects (up to 4 levels deep) and creates a `.ai` symlink in each pointing to `ai-superpower/.ai/`
3. Adds `.ai` to each project's `.gitignore`
4. Creates `ai-context.md` and `architecture.md` templates in the project's docs folder (`docs/`, `documentation/`, `doc/` — whichever exists) if the files are missing; asks first if no docs folder exists. The list of folder names is configured in `config.yaml`.
5. Writes a `.ai-superpower.version` file to your dev root with the run timestamp and commit hash

```
dev_root/             ← run curl from here
├── ai-superpower/    ← cloned here automatically
│   └── .ai/         ← instruction source (git tracked)
├── project-a/
│   └── .ai → dev_root/ai-superpower/.ai/   ← symlink
├── project-b/
│   └── .ai → dev_root/ai-superpower/.ai/   ← symlink
└── some-folder/
    └── project-c/             ← nested projects found automatically (maxdepth 4)
        └── .ai → dev_root/ai-superpower/.ai/
```

Any edits made to `.ai/` instruction files from within any project land directly in the `ai-superpower/` git working tree — visible with `git diff` and committable without a sync step.

See [docs/apply-requirements.md](docs/apply-requirements.md) for the full requirements and [docs/apply-usecases.md](docs/apply-usecases.md) for a detailed flow diagram.

## AI setup

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.

### `-root` command

Type `-root` at the start of any message to force the AI to re-read `ai-root-instructions.md` immediately:

```
-root
```

The AI will respond with `✅ ai-root-instructions.md READ — rules active` and then continue with the rest of your message.

Use it:
- At the start of every new session
- When the AI seems to have forgotten the rules (e.g. attempts a `git commit` unprompted)
- When switching context or returning to a project after a break

This command works in any AI tool — VS Code Copilot, Cursor, Claude.ai, or any other assistant. It requires no configuration and no tool-specific features.

## 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/                         ← source + symlink target (git tracked)
    ├── 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

dev_root/
└── project-x/
    ├── .ai → dev_root/ai-superpower/.ai/   ← symlink
    └── docs/
        ├── ai-context.md        ← project-specific context, never overwritten once customised
        └── architecture.md      ← project architecture, never overwritten once customised
```

Templates for `ai-context.md` and `architecture.md` are deployed automatically to any project that has a `docs/` folder. They contain a factory-reset marker on line 1 — as long as that marker is present, `apply.sh` will refresh the file on every run. Once you (or the AI) edits the file and removes the marker, the file is yours and will never be touched again.