99d13e6e4a
- apply.sh: direct-run guard (only curl | bash allowed) - apply.sh: DEV_ROOT passed as explicit arg from bootstrap - apply.sh: .ai/ copied to dev root as real folder; projects symlink there - apply.sh: counters + detailed summary (version prev→new, templated, refreshed, no-docs) - apply.sh: find errors silenced, no crash on empty dev root - .ai-superpower: added warning comment about deletion side effects - .gitignore: .ai-instructions.conf → .ai-superpower.version - scripts/: removed (hello.sh, scan-projects-with-git.sh, verify-docs-folder.sh, add-ai-context-to-docs-folder.sh) - templates: monorepo sections split into AI instructions + developer instructions - README.md: rewritten to match current architecture and behaviour - docs/apply-requirements.md: FR-2.4, FR-3, FR-5, FR-6, FR-7, FR-8 updated - docs/apply-usecases.md: full detailed Mermaid flowchart replacing placeholder
82 lines
4.7 KiB
Markdown
82 lines
4.7 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`.
|
|
- **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:
|
|
|
|
```bash
|
|
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](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, 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.
|