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:

# 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 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 + 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.