a6eb4da214
- .ai/ instruction set (root, behavior, skills, constraints) - apply.sh workflow documentation (apply.md) - architecture documentation (docs/architecture.md) - .github/copilot-instructions.md for VS Code auto-load - .gitignore (tmp/, .ai-instructions.conf)"
71 lines
3.8 KiB
Markdown
71 lines
3.8 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: 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
|
|
```
|
|
|
|
```bash
|
|
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](apply.md) for the full mechanism and [docs/architecture.md](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.
|
|
|
|
|