# 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` and exit the bootstrap process

### 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** 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.2** Add `.ai` to `DEV_ROOT/.gitignore` (create file if needed)
- **FR-3.3** For each discovered project: create `project/.ai` as a symlink pointing to `DEV_ROOT/.ai/` (absolute path)
- **FR-3.4** If symlink is already correct: skip silently
- **FR-3.5** If symlink is missing or broken: create it

### 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: print a warning and skip context setup for this project
- **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 No interaction (v1)

v1 runs fully automatically. No prompts, no questions, no `read` calls. Compatible with `curl | bash`.

**Future:** the docs/ setup steps (FR-5, FR-6) are the most likely candidates for interactivity in a later version — e.g. asking the developer to describe the project before generating `ai-context.md`, or offering to scaffold `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 100 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)
- Per-developer configuration file (`.ai-instructions.conf`)
- Harnesses (CLAUDE.md, AGENTS.md, .cursor/rules/)
- Copy mode — symlinks only
- Windows native (WSL required)