moilanik 172bfa78e9 docs: fix outdated references to old implementation

Remove QUICK-REFERENCE.md from .ai/ — it contained kube-log project-specific
content (hardcoded paths, OpenShift/ArgoCD config) that was leaking into all
projects via the symlink.

Update docs to match the actual apply.sh implementation:
- apply.md: rewrite to reflect curl-only invocation, bootstrap/local phases,
  factory-reset marker behaviour; remove .ai-instructions.conf and interactive
  checklist references
- architecture.md: remove scripts/ subdirectory and .ai-instructions.conf that
  were never implemented
- apply-usecases.md: remove INSTALL subgraph (rm -rf + cp -r was never done),
  fix symlink targets to SCRIPT_DIR/.ai
- apply-requirements.md: NFR-1 corrected (TTY-gated prompt exists), NFR-4
  updated to <150 lines, .ai-instructions.conf removed from out-of-scope list

2026-03-03 12:55:24 +02:00

3.2 KiB

Raw Blame History

apply.sh — how it works

How apply.sh sets up and maintains AI instructions across all projects. See README.md for context and docs/architecture.md for design decisions.

Design constraints

.ai/ is a symlink in every project, pointing back to ai-superpower/.ai/. No files are copied. There are no manually maintained project lists. The script discovers projects automatically by scanning for .git directories. Every run is a full scan — idempotent and stateless.

How apply.sh works

apply.sh must be run via curl | bash from the dev root. Direct invocation is blocked:

curl -fsSL https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/apply.sh | bash

Bootstrap phase — when piped through bash, BASH_SOURCE[0] is empty. The script uses this to detect the bootstrap context, then clones (or pulls) the repo and re-execs the local apply.sh --bootstrapped DEV_ROOT.

Local phase — runs with --bootstrapped flag. Scans dev root recursively for .git directories and runs per-project setup for each one found.

Project detection

The script scans dev root recursively (-maxdepth 4) for directories containing .git. Any project with a .ai-superpower marker file in its root is excluded — this identifies the ai-superpower repo itself regardless of what the directory is named.

Per-project actions

For each discovered project:

Creates project/.ai → ai-superpower/.ai/ symlink if missing or broken
Appends .ai to project/.gitignore if not already present (creates the file if needed)
If docs/ is missing and stdin is a TTY: asks [y/N] before creating it
Creates docs/ai-context.md from template if missing; refreshes if factory-reset marker is still on line 1
Creates docs/architecture.md from template if missing; refreshes if factory-reset marker is still on line 1

Keeping instructions up to date

When instructions in this repo change, just pull:

cd ~/koodi/ai-superpower
git pull

Because .ai/ is a symlink, all projects see the updated instructions immediately — no re-run of apply.sh needed. Run apply.sh only when adding new projects or repairing broken symlinks.

apply.sh is idempotent — safe to run as many times as needed. Customised docs/ files (factory-reset marker absent) are never overwritten.

Adding a new project

The project must be a git repository — git init must have been run first. Without a .git folder, apply.sh will not detect it.

Once initialised, re-run via curl | bash from the dev root — it detects the new project automatically. No other configuration needed.

Project context (ai-context.md)

docs/ai-context.md is the AI's window into the project. The script creates a blank template if the file is missing, but the content must reflect the actual project.

Use the AI to create or update it. Open the project in your editor and prompt:

Read the codebase and create docs/ai-context.md. Cover: what this project does, the technology stack, architecture overview, key decisions, and anything the AI needs to know to work here effectively.

For updates after significant changes:

Review docs/ai-context.md against the current codebase. What is outdated or missing?

3.2 KiB Raw Blame History