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.
• Single install, real folder — apply.sh copies .ai/ into your dev root. Every project symlinks there. One source of truth, zero drift.
• Modular loading — AI loads only the relevant instruction files per task, not everything at once.
• One change, all projects — re-run apply.sh, done. .ai/ is refreshed and all symlinks already point to it.
• 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:

curl -fsSL https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/apply.sh | bash

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. Copies .ai/ into your dev root as a real folder
3. Scans for all projects (up to 4 levels deep) and creates a .ai symlink in each
4. Adds .ai to each project's .gitignore
5. Creates docs/ai-context.md and docs/architecture.md templates in projects that have a docs/ folder but no such files yet
6. Writes a .ai-superpower.version file to your dev root with the run timestamp and commit hash

dev_root/             ← run curl from here
├── .ai/              ← installed here as a real folder (refreshed on every run)
├── ai-superpower/    ← cloned here automatically
├── project-a/
│   └── .ai → dev_root/.ai/   ← symlink
├── project-b/
│   └── .ai → dev_root/.ai/   ← symlink
└── some-folder/
    └── project-c/             ← nested projects found automatically (maxdepth 4)
        └── .ai → dev_root/.ai/

See docs/apply-requirements.md for the full requirements and 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.

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, copied to dev_root/.ai/ on every run
    ├── 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/
├── .ai/                         ← real folder (copy of above)
└── project-x/
    ├── .ai → dev_root/.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.