# 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)