ai-superpower/docs/apply-requirements.md

apply.sh — requirements

Goal

A single bash script that gives any developer AI superpowers across all their projects in one command. Run once to set up, run again to repair. No configuration, no questions.

---

Functional requirements

FR-1 Bootstrap via curl

• FR-1.1 When run via curl | bash, the script detects it has no filesystem location (BASH_SOURCE[0] is empty)
• FR-1.2 If ai-superpower/ does not exist in $PWD: clone the repo there
• FR-1.3 If ai-superpower/ already exists: run git pull to update it
• FR-1.4 After clone/pull: re-exec the local copy of apply.sh with --bootstrapped DEV_ROOT and stdin reopened from /dev/tty so interactive prompts work even when piped through curl

FR-2 Project discovery

• FR-2.1 Scan dev root recursively for directories containing .git
• FR-2.2 Dev root is the parent directory of the script's own location
• FR-2.3 Exclude any project containing a .ai-superpower marker file in its root — this identifies the ai-superpower repo itself regardless of what the directory is named
• FR-2.4 Maximum scan depth: 4 levels below dev root (-maxdepth 4 from dev root)

FR-3 Symlink

• 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 If symlink is already correct: skip silently
• FR-3.3 If symlink is missing or broken: create it
• 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-4 .gitignore

• FR-4.1 Check if .ai is present in project/.gitignore
• FR-4.2 If missing: append .ai to the file (create file if it does not exist)
• FR-4.3 If already present: skip silently

FR-5 ai-context.md

• FR-5.1 If project/docs/ does not exist and stdin is a TTY: ask the developer [y/N] whether to create it; create it on y, skip on anything else
• FR-5.1b If project/docs/ does not exist and stdin is not a TTY (non-interactive environment): print a warning and skip
• FR-5.2 If project/docs/ai-context.md does not exist: create it from a template
• FR-5.3 The template contains section headings and inline instructions explaining what each section should contain and how to fill it in (manually or by asking the AI)
• FR-5.4 If file already exists and the first line is the factory-reset marker (<!-- ai-superpower:template): overwrite with the current template — the file has not yet been customised
• FR-5.5 If file already exists and marker is absent: skip silently — the developer owns this file
• FR-5.6 (future) Interactive mode: before creating the template, ask the developer for a one-line project description and pre-fill it into the template

FR-6 architecture.md

• FR-6.1 If project/docs/architecture.md does not exist: create it from a template
• FR-6.2 The template contains section headings and inline instructions explaining what each section should contain and how to fill it in (manually or by asking the AI)
• FR-6.3 If file already exists and the first line is the factory-reset marker: overwrite with the current template — the file has not yet been customised
• FR-6.4 If file already exists and marker is absent: skip silently — the developer owns this file
• FR-6.5 (future) Interactive mode: offer to scaffold a richer architecture.md based on a brief description from the developer

FR-7 Idempotency

• FR-7.1 Running apply.sh multiple times produces the same result
• FR-7.2 Files that have been customised by the developer (factory-reset marker absent) are never overwritten
• FR-7.3 No duplicate lines added to .gitignore

FR-8 Version file

• FR-8.1 After each run, write $DEV_ROOT/.ai-superpower.version with the current UTC timestamp and the short git commit hash of the ai-superpower repo
• FR-8.2 The file is overwritten on every run (always reflects the last run)
• FR-8.3 $DEV_ROOT/.ai-superpower.version is listed in this repo's .gitignore

---

Non-functional requirements

NFR-1 Minimal interaction

The script is designed to run non-interactively. One exception: when project/docs/ does not exist and stdin is a TTY, the script asks [y/N] before creating the folder. This is gated on TTY detection — in non-interactive environments (piped through curl, CI) it falls back to a printed warning and skip. All other steps run without prompts.

Future: FR-5.6 and FR-6.5 describe potential interactive scaffolding for ai-context.md and architecture.md. The code structure must allow this to be added per-project without redesigning the main loop.

NFR-2 Output

Each project prints a short status line per action taken. Silent for skipped steps.

▸ project-name
  ✓  .ai symlinked
  ✓  .ai added to .gitignore
  ✓  created docs/ai-context.md
  ⚠  no docs/architecture.md

NFR-3 Error handling

• set -euo pipefail — fail fast on errors
• Failed git clone or git pull: print clear error message and exit
• Failed write to .gitignore or docs files: script exits immediately (inherits pipefail behaviour)

NFR-4 Size

Target: under 150 lines. Single file, no external scripts.

NFR-5 Compatibility

• macOS (zsh + bash)
• Linux (bash)
• Windows via WSL
• No dependencies beyond git, bash, find

---

Out of scope (v1)

• Interactive project selection checklist
• Interactive docs/ scaffolding (deferred to future version — see FR-5.6, FR-6.5)
• Harnesses (CLAUDE.md, AGENTS.md, .cursor/rules/)
• Copy mode — symlinks only
• Windows native (WSL required)