niko/ai-superpower
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: symlinks point directly to ai-superpower/.ai/ (revert copy approach)

Browse Source 
- remove DEV_ROOT/.ai/ copy step — AI_TARGET = SCRIPT_DIR/.ai (repo)
- remove /dev/tty deleted copy folder from filesystem
- edits to .ai/ from any project land directly in git working tree
- docs/apply-requirements.md: FR-3 rewritten
- README.md: principles, install steps, directory structure updated
This commit is contained in:
moilanik 2026-03-03 11:49:35 +02:00
parent 6c0a40f186
commit cd6f8b5c81
3 changed files with 19 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@ -10,9 +10,9 @@ Good instructions are what make that possible — they allow AI to produce outpu
## Principles ## Principles
- **Generic vs. project-specific** — `.ai/` instructions know nothing about individual projects. Project knowledge lives in each project's own `docs/ai-context.md`. - **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. - **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. - **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. - **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. - **Version controlled** — instructions are managed in git. Changes are tracked, history is preserved, and rolling back is straightforward.
## Install ## Install
@ -27,25 +27,26 @@ This script **must be run via `curl | bash`** from your dev root. Running it dir
What it does: What it does:
1. Clones (or updates) this repo into `dev_root/ai-superpower/` 1. Clones (or updates) this repo into `dev_root/ai-superpower/`
2. Copies `.ai/` into your dev root as a real folder 2. Scans for all projects (up to 4 levels deep) and creates a `.ai` symlink in each pointing to `ai-superpower/.ai/`
3. Scans for all projects (up to 4 levels deep) and creates a `.ai` symlink in each 3. Adds `.ai` to each project's `.gitignore`
4. Adds `.ai` to each project's `.gitignore` 4. Creates `docs/ai-context.md` and `docs/architecture.md` templates in projects that have a `docs/` folder but no such files yet — asks first if the folder doesn't exist
5. Creates `docs/ai-context.md` and `docs/architecture.md` templates in projects that have a `docs/` folder but no such files yet 5. Writes a `.ai-superpower.version` file to your dev root with the run timestamp and commit hash
6. Writes a `.ai-superpower.version` file to your dev root with the run timestamp and commit hash
``` ```
dev_root/ ← run curl from here dev_root/ ← run curl from here
├── .ai/ ← installed here as a real folder (refreshed on every run)
├── ai-superpower/ ← cloned here automatically ├── ai-superpower/ ← cloned here automatically
│ └── .ai/ ← instruction source (git tracked)
├── project-a/ ├── project-a/
│ └── .ai → dev_root/.ai/ ← symlink │ └── .ai → dev_root/ai-superpower/.ai/ ← symlink
├── project-b/ ├── project-b/
│ └── .ai → dev_root/.ai/ ← symlink │ └── .ai → dev_root/ai-superpower/.ai/ ← symlink
└── some-folder/ └── some-folder/
└── project-c/ ← nested projects found automatically (maxdepth 4) └── project-c/ ← nested projects found automatically (maxdepth 4)
└── .ai → dev_root/.ai/ └── .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. 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 ## AI setup
@ -62,7 +63,7 @@ Verify that every AI response begins with this confirmation. If it does not, the
``` ```
ai-superpower/ ai-superpower/
└── .ai/ ← source, copied to dev_root/.ai/ on every run └── .ai/ ← source + symlink target (git tracked)
├── ai-root-instructions.md ← entry point, read first ├── ai-root-instructions.md ← entry point, read first
└── instructions/ └── instructions/
├── behavior/ ← how AI approaches its work ├── behavior/ ← how AI approaches its work
@ -70,9 +71,8 @@ ai-superpower/
└── constraints/ ← what AI must not do └── constraints/ ← what AI must not do
dev_root/ dev_root/
├── .ai/ ← real folder (copy of above)
└── project-x/ └── project-x/
├── .ai → dev_root/.ai/ ← symlink ├── .ai → dev_root/ai-superpower/.ai/ ← symlink
└── docs/ └── docs/
├── ai-context.md ← project-specific context, never overwritten once customised ├── ai-context.md ← project-specific context, never overwritten once customised
└── architecture.md ← project architecture, never overwritten once customised └── architecture.md ← project architecture, never overwritten once customised

10
apply.sh
View File

@ -34,7 +34,7 @@ fi
# ── Local mode ──────────────────────────────────────────────────────────────── # ── Local mode ────────────────────────────────────────────────────────────────
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DEV_ROOT="${2:?DEV_ROOT not passed — re-run via curl}" DEV_ROOT="${2:?DEV_ROOT not passed — re-run via curl}"
AI_TARGET="$DEV_ROOT/.ai" AI_TARGET="$SCRIPT_DIR/.ai"
TEMPLATE_MARKER="<!-- ai-superpower:template" TEMPLATE_MARKER="<!-- ai-superpower:template"
# Counters # Counters
@ -43,14 +43,6 @@ cnt_no_docs=0
cnt_templated=0 cnt_templated=0
cnt_refreshed=0 cnt_refreshed=0
# ── Install .ai/ into dev root (real folder, refreshed on every run) ─────────
echo "→ installing .ai/ into $DEV_ROOT ..."
rm -rf "$AI_TARGET"
cp -r "$SCRIPT_DIR/.ai" "$AI_TARGET"
if ! grep -qxF '.ai' "$DEV_ROOT/.gitignore" 2>/dev/null; then
echo '.ai' >> "$DEV_ROOT/.gitignore"
fi
setup_project() { setup_project() {
local project="$1" local project="$1"
local name local name

9
docs/apply-requirements.md
View File

@ -24,11 +24,10 @@ A single bash script that gives any developer AI superpowers across all their pr
### FR-3 Symlink ### FR-3 Symlink
- **FR-3.1** Copy `ai-superpower/.ai/` to `DEV_ROOT/.ai/` as a real folder on every run — this keeps the instructions up to date when the repo is pulled - **FR-3.1** For each discovered project: create `project/.ai` as a symlink pointing directly to `ai-superpower/.ai/` in the repo (absolute path)
- **FR-3.2** Add `.ai` to `DEV_ROOT/.gitignore` (create file if needed) - **FR-3.2** If symlink is already correct: skip silently
- **FR-3.3** For each discovered project: create `project/.ai` as a symlink pointing to `DEV_ROOT/.ai/` (absolute path) - **FR-3.3** If symlink is missing or broken: create it
- **FR-3.4** If symlink is already correct: skip silently - **FR-3.4** This means changes made to `.ai/` instruction files from any project are immediately reflected in the git working tree of `ai-superpower/` — no sync step needed
- **FR-3.5** If symlink is missing or broken: create it
### FR-4 .gitignore ### FR-4 .gitignore