102f593909
config.yaml: new repo-root config file with docs_folders list (docs, documentation, doc). apply.sh reads this list and picks the first existing folder per project instead of hardcoding docs/. Instructions: - core-principles: add No Vibe Coding and No Touching .ai/ sections - ai-root-instructions: add mandatory instructions block — rules stay active for the whole session, not just at start; AI must stop and announce if instructions were not loaded - project-context, docs: updated to list all docs folder alternatives and reference config.yaml as the source of truth FR-5.0 added to apply-requirements.md. README step 4 updated.
86 lines
5.3 KiB
Markdown
86 lines
5.3 KiB
Markdown
# 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.
|
|
|
|
## 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.
|