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

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 for the full mechanism and 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.