99d13e6e4a
- apply.sh: direct-run guard (only curl | bash allowed) - apply.sh: DEV_ROOT passed as explicit arg from bootstrap - apply.sh: .ai/ copied to dev root as real folder; projects symlink there - apply.sh: counters + detailed summary (version prev→new, templated, refreshed, no-docs) - apply.sh: find errors silenced, no crash on empty dev root - .ai-superpower: added warning comment about deletion side effects - .gitignore: .ai-instructions.conf → .ai-superpower.version - scripts/: removed (hello.sh, scan-projects-with-git.sh, verify-docs-folder.sh, add-ai-context-to-docs-folder.sh) - templates: monorepo sections split into AI instructions + developer instructions - README.md: rewritten to match current architecture and behaviour - docs/apply-requirements.md: FR-2.4, FR-3, FR-5, FR-6, FR-7, FR-8 updated - docs/apply-usecases.md: full detailed Mermaid flowchart replacing placeholder
117 lines
5.3 KiB
Markdown
117 lines
5.3 KiB
Markdown
# 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)
|