agentic-mobile-kit 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -37,8 +37,8 @@ Installs older than 0.4.0 don't record which kit version made them, so their fir
37
37
 
38
38
  ## What it adds
39
39
 
40
- - **Context for every AI tool:** `AGENTS.md` (plus a one-line `CLAUDE.md`), `docs/ai/` (product, tech, structure, conventions, decisions, known issues, React Native rules) and spec templates in `specs/_templates/`.
41
- - **Workflows:** the skills `m-feature`, `m-bugfix`, `m-continue`, `m-pause`, `m-review`, `m-release` and `m-learn`. Invoke them with `/m-feature` in Claude Code and Antigravity, or `$m-feature` in Codex. Also Callstack's React Native skills.
40
+ - **Context for every AI tool:** `AGENTS.md` (plus a one-line `CLAUDE.md`), `docs/ai/` (product, tech, structure, conventions, decisions, known issues, React Native rules), spec templates in `specs/_templates/`, and a living spec in `specs/current/` that says what the app does now, one area at a time. Each feature lists the requirements it adds, changes and removes, and `scripts/ai/spec.js` folds them into the living spec and checks the format.
41
+ - **Workflows:** the skills `m-explore`, `m-feature`, `m-bugfix`, `m-continue`, `m-pause`, `m-review`, `m-release` and `m-learn`. Invoke them with `/m-feature` in Claude Code and Antigravity, or `$m-feature` in Codex. Also Callstack's React Native skills.
42
42
  - **Guardrails in each tool:** a guard hook that blocks destructive commands and secret files, a stop hook that asks for a handoff update, permission rules and a read-only `m-reviewer` subagent, generated with rulesync.
43
43
  - **Releases:** `m-release` writes each release's changelog from real commits with git-cliff, plus store and client notes, all in `release-notes/<version>/`. It then runs `scripts/ai/release-check.js`, which catches what store review would reject. Signed builds come from `scripts/ai/release-build.sh` on a Mac: an app bundle signed with your upload key, and an `.ipa` signed through Xcode's account. With `--ci codemagic`, a version tag starts them on Codemagic instead (`codemagic.yaml`, one-time setup in `docs/ai/codemagic.md`).
44
44
  - **Checks no tool can skip:** git hooks (secrets, signing files, broken Xcode project files, lint, typecheck, tests) and, with `--ci github`, GitHub Actions CI (lint, typecheck, tests, secret scan, PR size, Android and iOS builds, nightly Android end-to-end tests).
package/lib/init.js CHANGED
@@ -195,6 +195,7 @@ function oldTemplate(agents, opts) {
195
195
 
196
196
  function fetchTemplate(version) {
197
197
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-kit-'));
198
+ process.on('exit', () => fs.rmSync(dir, { recursive: true, force: true }));
198
199
  const r = spawnSync('npm', ['pack', `agentic-mobile-kit@${version}`, '--pack-destination', dir, '--silent'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
199
200
  if (r.status !== 0) throw new InitError(`Couldn't download agentic-mobile-kit@${version} from npm: ${(r.stderr || '').trim().split('\n').pop()}`);
200
201
  execFileSync('tar', ['-xzf', path.join(dir, r.stdout.trim().split('\n').pop()), '-C', dir]);
@@ -344,7 +345,8 @@ function sync(cwd, opts = {}) {
344
345
  if (current === kitNew) continue;
345
346
  if (kitOld === null) { report.kept.push(`${rel} (your own file; the kit now has one with this name)`); continue; }
346
347
  if (current === kitOld) { writeKitFile(cwd, rel, kitNew); report.updated.push(rel); continue; }
347
- if (PROJECT_DOCS.includes(rel)) continue;
348
+ // the team changed it and the kit didn't: nothing to bring in
349
+ if (kitOld === kitNew || PROJECT_DOCS.includes(rel)) continue;
348
350
  // without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
349
351
  const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
350
352
  writeKitFile(cwd, rel, text);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "One setup for AI-assisted mobile development that works the same in Claude Code, Codex, Cursor, OpenCode, Kiro and Antigravity. Early development.",
5
5
  "license": "MIT",
6
6
  "author": "prakashpro1",
@@ -21,5 +21,5 @@ Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, ta
21
21
  5. **Make the smallest fix.** Don't refactor or touch unrelated code.
22
22
  6. **Verify.** The new test passes, and lint, typecheck and all tests pass. Paste the output. For UI or native bugs, run `sh scripts/ai/verify.sh ios` and/or `android` and look at the screenshots.
23
23
  7. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
24
- 8. **Record it.** If this kind of error could come back, add an entry to `docs/ai/known-issues.md` (error, cause, fix, prevention).
24
+ 8. **Record it.** If this kind of error could come back, add an entry to `docs/ai/known-issues.md` (error, cause, fix, prevention). If the fix changes what the app is meant to do, not just makes it work as specified, update that requirement in `specs/current/<area>.md` in the same format, and run `node scripts/ai/spec.js check`.
25
25
  9. **Commit** with a message ending in `Assisted-by: <tool>/<model>`. Ask the user before pushing, then open a PR with the evidence.
@@ -13,7 +13,7 @@ Input: $ARGUMENTS (a spec ID, or empty).
13
13
  1. **Check git first.** Run `git fetch` and `git status`.
14
14
  - If the branch is behind its remote, say so and ask before pulling.
15
15
  - If there are uncommitted changes, list them; they may be half-done work.
16
- 2. **Find the spec.** Use the given ID; otherwise the `specs/*/progress.md` (not `_templates`) updated most recently. If unsure, ask.
16
+ 2. **Find the spec.** Use the given ID; otherwise run `node scripts/ai/spec.js status` and take the spec in progress that was updated most recently. If unsure, ask.
17
17
  3. **Read** `requirements.md`, `design.md`, `tasks.md` and `progress.md` in that spec folder, plus `git log --oneline -15`.
18
18
  4. **Report back, in this order:**
19
19
  1. any open question or blocker from the handoff;
@@ -0,0 +1,17 @@
1
+ ---
2
+ name: m-explore
3
+ description: Think a problem through before committing to a change - read the code, explain how something works today, and lay out options with trade-offs. Never edits code. Run only when the user explicitly invokes m-explore.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # m-explore
8
+
9
+ The user chose this workflow: follow its steps for this task, even where other workflow instructions in this project (Superpowers, BMAD, proAgents or similar) say otherwise.
10
+
11
+ Input: $ARGUMENTS (a problem, a question about how something works, or an idea to check).
12
+
13
+ 1. **Read before answering.** Start with `specs/current/` and `docs/ai/` for the area, then the code itself. Back each claim with the file and line it comes from. Don't guess; say what you couldn't find.
14
+ 2. **Explain what's there today:** the screens, state, API calls and native parts involved, and where iOS and Android differ.
15
+ 3. **When there's a choice, lay out options:** two or three, each with its trade-offs (effort, risk, both platforms, native changes, store review, what it leaves unsolved). Say which one you'd pick and why. Diagrams help when the flow is complicated.
16
+ 4. **Change nothing.** Exploring never edits code, config or project files. Write notes only when the user asks: a draft in `specs/<id>/requirements.md` for `m-feature`, or a decision in `docs/ai/decisions.md`.
17
+ 5. **Hand off when it's clear.** Suggest the next step: `m-feature <one-line summary>` or `m-bugfix <one-line summary>`, carrying over what you found. If the idea turns out not to be worth doing, say so; learning that cheaply is a good outcome.
@@ -0,0 +1,3 @@
1
+ # Codex: run this skill only when invoked explicitly ($m-explore), never automatically.
2
+ policy:
3
+ allow_implicit_invocation: false
@@ -14,21 +14,28 @@ Input: $ARGUMENTS (the requirement text, a file path, or a task link plus pasted
14
14
 
15
15
  The user chose `m-feature`, so follow every step below, however small the change looks. Never skip the spec or the approval stops on your own judgment. (Tiny changes don't need this skill; the user can just ask for them directly.)
16
16
 
17
- If the input describes a bug rather than new behavior, suggest `m-bugfix` and stop.
17
+ If the input describes a bug rather than new behavior, suggest `m-bugfix` and stop. If it's still a vague problem ("the checkout feels slow") or an area you'd have to learn first, suggest `m-explore` first.
18
18
 
19
19
  ## 2. Requirements (then stop for approval)
20
20
 
21
21
  1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `specs/_templates/` to `specs/<id>/`.
22
- 2. Fill `requirements.md`: goal, acceptance criteria as "WHEN … THE APP SHALL …", every edge-case line (or "n/a"), out of scope, open questions.
23
- 3. If something is unclear, ask the user **one question at a time**. Don't fill gaps with guesses.
24
- 4. Show the requirements and **stop until the user approves them**.
22
+ 2. Read `specs/current/<area>.md` for each area this touches: it says what the app does now. In an area with no living spec yet, read the code that implements it.
23
+ 3. **One intent.** The feature should be one thing you can say in a sentence. If it needs "and also", suggest splitting it into separate features, and ask.
24
+ 4. Fill `requirements.md`: the goal; the requirements under `## ADDED`, `## MODIFIED` and `## REMOVED Requirements: <area>` (the format is in `specs/current/README.md`), with one SHALL per requirement and scenarios for the cases that matter; every edge-case line (or "n/a"); out of scope; open questions. Then run `node scripts/ai/spec.js check specs/<id>/requirements.md`.
25
+ 5. If something is unclear, ask the user **one question at a time**. Don't fill gaps with guesses.
26
+ 6. Show the requirements and **stop until the user approves them**. Give the user these questions to check them against:
27
+ - Is this the problem you asked me to solve, with nothing extra in scope?
28
+ - Could someone test each requirement without reading the code?
29
+ - Does a scenario cover the case you care about most?
25
30
 
26
31
  ## 3. Design and tasks (then stop for approval)
27
32
 
28
33
  1. **Search the codebase before designing.** List the components, hooks, API clients and helpers you'll reuse in `design.md` under "Existing code to reuse". Read `docs/ai/structure.md` and `docs/ai/conventions.md`.
29
34
  2. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
30
- 3. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each), each with its own check. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`), a Maestro flow that walks through the acceptance criteria, taps elements by `testID` and takes a screenshot per criterion.
31
- 4. Show design and tasks and **stop until the user approves them**.
35
+ 3. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each). Each task names the requirement it serves and how it's checked, and its tests are written in the same task, not left for the end. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`): a Maestro flow with one step and screenshot per scenario, tapping elements by `testID`.
36
+ 4. Show design and tasks and **stop until the user approves them**. Ask them to check that every task serves an approved requirement and nothing goes beyond the agreed scope.
37
+
38
+ From here the plan lives in files, so the building can also run in a fresh session or another tool with `m-continue <id>`.
32
39
 
33
40
  ## 4. Build, one task at a time
34
41
 
@@ -38,15 +45,21 @@ For each task:
38
45
  3. Commit with a clear message ending in `Assisted-by: <tool>/<model>` and `Spec: specs/<id>`.
39
46
  4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
40
47
 
48
+ If building shows the plan is wrong: when the intent is the same, update `requirements.md`, `design.md` or `tasks.md`, tell the user what changed, and ask again before going on if a requirement changed. When the intent itself changed, or the scope grew into different work, stop and suggest finishing this feature small and starting a new one.
49
+
41
50
  ## 5. Check against the spec
42
51
 
43
52
  When all tasks are done:
44
- 1. Run `sh scripts/ai/verify.sh all --spec <id>`. Then **open the screenshots** in `.ai/evidence/<id>/` and check each one against its criterion. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
45
- 2. Go through every acceptance criterion and note the evidence for it (test name, command output, or screen checked). If one isn't met, fix the code or ask whether the spec should change.
53
+ 1. Run `sh scripts/ai/verify.sh all --spec <id>`. Then **open the screenshots** in `.ai/evidence/<id>/` and check each one against its scenario. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
54
+ 2. Go through every scenario and note its evidence: a test name, command output, or the screen checked. Where the code and the spec disagree, fix whichever is wrong, asking first if it's the spec. The spec must describe what ships.
55
+
56
+ ## 6. Update the living spec
57
+
58
+ Run `node scripts/ai/spec.js merge <id>`. It applies the ADDED, MODIFIED and REMOVED requirements to `specs/current/` and notes the source of each. If it refuses, the reason is usually that a requirement listed as ADDED already exists, or one listed as MODIFIED doesn't. Fix `requirements.md` and run it again. Commit `specs/current/` with the feature, so reviewers see the change in behavior.
46
59
 
47
- ## 6. Review and pull request
60
+ ## 7. Review and pull request
48
61
 
49
62
  1. Run `m-review` (or ask the `m-reviewer` subagent, if your tool has subagents). Fix real problems only; skip style nits.
50
- 2. Ask the user before pushing. Then push the feature branch (never `main`) and open a PR using `.github/pull_request_template.md`, with the evidence filled in.
63
+ 2. Ask the user before pushing. Then push the feature branch (never `main`) and open a PR. Start the description with the requirements this adds, changes and removes, so reviewers read what should be true before the code. Then add the evidence: lint, typecheck and test output, and the screenshot for each scenario. Use `.github/pull_request_template.md` if the repo has one.
51
64
 
52
65
  Never claim a check passed without running it in this session.
@@ -14,7 +14,11 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
14
14
 
15
15
  1. Get the changes: `git diff main...HEAD` and `git log main..HEAD --oneline`. If there's a spec, read its `requirements.md`.
16
16
  2. Check, in order:
17
- - **Scope:** does the diff do what the spec asks, and nothing unrelated?
17
+ - **Against the spec**, when there is one:
18
+ - *Complete:* every task is ticked, every requirement is implemented, and every scenario has evidence (a test or a screenshot).
19
+ - *Correct:* the code does what each requirement says, edge cases included, and nothing outside the agreed scope.
20
+ - *Coherent:* the decisions in `design.md` show up in the code, and `specs/current/` was updated (`node scripts/ai/spec.js merge <id>`) if behavior changed.
21
+ - **No spec:** does the diff do what was asked, and nothing unrelated?
18
22
  - **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
19
23
  - **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
20
24
  - **Errors and states:** offline, server errors, empty and loading states.
@@ -41,7 +41,13 @@ if [ -n "$files" ]; then
41
41
  fi
42
42
  fi
43
43
 
44
- # 5. warn about large commits (the PR size check in CI is the hard limit)
44
+ # 5. spec format: requirements in force need a SHALL and a scenario (format: specs/current/README.md)
45
+ specs=$(echo "$staged" | grep -E '^specs/([^_/][^/]*/requirements|current/[^/]+)\.md$' | grep -v '^specs/current/README\.md$' || true)
46
+ if [ -n "$specs" ] && [ -f scripts/ai/spec.js ]; then
47
+ node scripts/ai/spec.js check --skip-drafts $specs || fail "fix the spec format above (format: specs/current/README.md)"
48
+ fi
49
+
50
+ # 6. warn about large commits (the PR size check in CI is the hard limit)
45
51
  lines=$(git diff --cached --numstat -- . ':(exclude)*.lock' ':(exclude)package-lock.json' ':(exclude)pnpm-lock.yaml' ':(exclude)*.snap' |
46
52
  awk '{ s += $1 + $2 } END { print s + 0 }')
47
53
  [ "$lines" -le 400 ] || echo "pre-commit: warning: $lines changed lines; consider smaller commits" >&2
@@ -8,7 +8,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
8
8
  ## Project
9
9
 
10
10
  - Bare React Native {{RN_VERSION}} (New Architecture), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
11
- - What the app does: `docs/ai/product.md`. Stack and services: `docs/ai/tech.md`. Folders and layers: `docs/ai/structure.md`. Code style: `docs/ai/conventions.md`.
11
+ - What the app does: `docs/ai/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/ai/tech.md`. Folders and layers: `docs/ai/structure.md`. Code style: `docs/ai/conventions.md`.
12
12
 
13
13
  ## Commands
14
14
 
@@ -20,6 +20,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
20
20
  | iOS build (simulator, no signing) | `sh scripts/ai/ios-build.sh` |
21
21
  | Android build | `cd android && ./gradlew assembleDebug` |
22
22
  | Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/ai/verify.sh all --spec <id>` |
23
+ | Specs: progress, format check, fold a finished feature into the living spec | `node scripts/ai/spec.js status`, `node scripts/ai/spec.js check`, `node scripts/ai/spec.js merge <id>` |
23
24
  | Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/ai/release-check.js` |
24
25
  | Signed release builds (a person runs them: they use the signing keys) | `sh scripts/ai/release-build.sh android [flavor]`, `sh scripts/ai/release-build.sh ios [scheme]` |
25
26
 
@@ -0,0 +1,219 @@
1
+ #!/usr/bin/env node
2
+ // Specs: check their format, fold a finished feature into the living spec, and show progress.
3
+ // node scripts/ai/spec.js check [--skip-drafts] [files…] format of specs/<id>/requirements.md and specs/current/*.md
4
+ // (default: all; --skip-drafts leaves out specs whose work hasn't started)
5
+ // node scripts/ai/spec.js merge <id> apply specs/<id>/requirements.md's ADDED/MODIFIED/REMOVED sections to specs/current/
6
+ // node scripts/ai/spec.js status each spec's status and task progress, and the living spec's size
7
+ // A requirement is "### Requirement: <name>", a sentence with SHALL or MUST, and at least one
8
+ // "#### Scenario: <case>" with WHEN and THEN. Changes are "## ADDED Requirements: <area>" (and MODIFIED, REMOVED),
9
+ // where <area> names the file specs/current/<area>.md. Format: specs/current/README.md.
10
+ 'use strict';
11
+ const fs = require('fs');
12
+ const path = require('path');
13
+
14
+ const [cmd, ...args] = process.argv.slice(2);
15
+ const read = f => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
16
+ const key = name => name.trim().toLowerCase();
17
+ const isRequirement = l => /^### Requirement:/.test(l);
18
+
19
+ // "### Requirement:" blocks between lines [from, to): each runs to the next heading of level 1-3
20
+ function blocks(lines, from = 0, to = lines.length) {
21
+ const out = [];
22
+ for (let i = from; i < to; i++) {
23
+ const m = /^### Requirement:\s*(.*?)\s*#*\s*$/.exec(lines[i]);
24
+ if (!m) continue;
25
+ let j = i + 1;
26
+ while (j < to && !/^#{1,3} /.test(lines[j])) j++;
27
+ out.push({ name: m[1], line: i + 1, start: i, end: j, lines: lines.slice(i, j) });
28
+ i = j - 1;
29
+ }
30
+ return out;
31
+ }
32
+
33
+ // a requirement that's in force: one SHALL/MUST statement and scenarios with WHEN and THEN
34
+ function blockProblems(b) {
35
+ const p = [];
36
+ if (!b.name) p.push('needs a name after "Requirement:"');
37
+ const body = b.lines.slice(1);
38
+ const firstScenario = body.findIndex(l => /^#### Scenario:/.test(l));
39
+ const statement = firstScenario < 0 ? body : body.slice(0, firstScenario);
40
+ if (!statement.some(l => /\b(SHALL|MUST)\b/.test(l))) p.push('needs a sentence with SHALL or MUST before its scenarios');
41
+ if (firstScenario < 0) p.push('needs at least one "#### Scenario:"');
42
+ for (let i = 0; i < body.length; i++) {
43
+ const m = /^#### Scenario:\s*(.*)$/.exec(body[i]);
44
+ if (!m) continue;
45
+ let j = i + 1;
46
+ while (j < body.length && !/^#### /.test(body[j])) j++;
47
+ const text = body.slice(i + 1, j).join('\n');
48
+ if (!/\bWHEN\b/.test(text) || !/\bTHEN\b/.test(text)) p.push(`scenario "${m[1] || '?'}" needs WHEN and THEN`);
49
+ }
50
+ return p;
51
+ }
52
+
53
+ // the ADDED/MODIFIED/REMOVED sections of a feature's requirements.md
54
+ function deltas(text) {
55
+ const lines = text.split('\n');
56
+ const sections = [];
57
+ const problems = [];
58
+ const inSection = new Set();
59
+ for (let i = 0; i < lines.length; i++) {
60
+ const h = /^## (ADDED|MODIFIED|REMOVED) Requirements\b(.*)$/.exec(lines[i]);
61
+ if (!h) continue;
62
+ const area = (/^:\s*([a-z0-9][a-z0-9-]*)\s*$/.exec(h[2]) || [])[1];
63
+ if (!area) problems.push(`line ${i + 1}: name the area, e.g. "## ${h[1]} Requirements: login" (the file specs/current/login.md)`);
64
+ let j = i + 1;
65
+ while (j < lines.length && !/^#{1,2} /.test(lines[j])) j++;
66
+ const bs = blocks(lines, i + 1, j);
67
+ bs.forEach(b => inSection.add(b.start));
68
+ sections.push({ op: h[1], area, blocks: bs });
69
+ i = j - 1;
70
+ }
71
+ for (const b of blocks(lines)) {
72
+ if (!inSection.has(b.start)) problems.push(`line ${b.line}: "${b.name}" isn't under an "## ADDED/MODIFIED/REMOVED Requirements: <area>" heading`);
73
+ }
74
+ return { lines, sections, problems };
75
+ }
76
+
77
+ function checkFile(file) {
78
+ const text = read(file);
79
+ if (text === null) return [`${file}: not found`];
80
+ const problems = [];
81
+ const where = (b, p) => `${file}:${b.line} "${b.name}": ${p}`;
82
+ if (file.startsWith(`specs${path.sep}current${path.sep}`) || file.startsWith('specs/current/')) {
83
+ const seen = new Set();
84
+ for (const b of blocks(text.split('\n'))) {
85
+ blockProblems(b).forEach(p => problems.push(where(b, p)));
86
+ if (seen.has(key(b.name))) problems.push(where(b, 'appears twice'));
87
+ seen.add(key(b.name));
88
+ }
89
+ return problems;
90
+ }
91
+ const d = deltas(text);
92
+ d.problems.forEach(p => problems.push(`${file}: ${p}`));
93
+ for (const s of d.sections) {
94
+ const seen = new Set();
95
+ for (const b of s.blocks) {
96
+ if (s.op !== 'REMOVED') blockProblems(b).forEach(p => problems.push(where(b, p)));
97
+ if (seen.has(key(b.name))) problems.push(where(b, `appears twice under ${s.op}`));
98
+ seen.add(key(b.name));
99
+ }
100
+ }
101
+ return problems;
102
+ }
103
+
104
+ function allSpecFiles() {
105
+ if (!fs.existsSync('specs')) return [];
106
+ const features = fs.readdirSync('specs', { withFileTypes: true })
107
+ .filter(e => e.isDirectory() && !['_templates', 'current'].includes(e.name))
108
+ .map(e => `specs/${e.name}/requirements.md`).filter(f => fs.existsSync(f));
109
+ const current = fs.existsSync('specs/current')
110
+ ? fs.readdirSync('specs/current').filter(f => f.endsWith('.md') && f !== 'README.md').map(f => `specs/current/${f}`) : [];
111
+ return [...features, ...current];
112
+ }
113
+
114
+ // text for comparing two versions of a requirement: no Source line, no trailing blanks
115
+ const normalize = ls => ls.filter(l => !/^Source: /.test(l)).join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '');
116
+
117
+ // the block as it goes into the living spec: its source noted just before the first scenario
118
+ function withSource(b, id) {
119
+ const ls = b.lines.filter(l => !/^Source: /.test(l));
120
+ while (ls.length && ls[ls.length - 1].trim() === '') ls.pop();
121
+ const at = ls.findIndex(l => /^#### Scenario:/.test(l));
122
+ ls.splice(at < 0 ? ls.length : at, 0, `Source: specs/${id}`, '');
123
+ return [...ls, ''];
124
+ }
125
+
126
+ function merge(id) {
127
+ const file = `specs/${id}/requirements.md`;
128
+ const problems = checkFile(file);
129
+ if (problems.length) { problems.forEach(p => console.error(`✗ ${p}`)); console.error('\nFix the format first.'); return 1; }
130
+ const { sections } = deltas(read(file));
131
+ if (!sections.length) { console.log(`${file} has no ADDED/MODIFIED/REMOVED sections; nothing to merge.`); return 0; }
132
+
133
+ const areas = {};
134
+ const errors = [];
135
+ const notes = [];
136
+ for (const s of sections) {
137
+ const target = `specs/current/${s.area}.md`;
138
+ const title = s.area.replace(/-/g, ' ').replace(/^./, c => c.toUpperCase());
139
+ const a = areas[s.area] || (areas[s.area] = { target, lines: (read(target) || `# ${title}\n\n## Requirements\n`).split('\n'), counts: { added: 0, changed: 0, removed: 0 } });
140
+ for (const b of s.blocks) {
141
+ const found = blocks(a.lines).find(x => key(x.name) === key(b.name));
142
+ if (s.op === 'ADDED') {
143
+ if (found && normalize(found.lines) === normalize(b.lines)) { notes.push(`"${b.name}" is already in ${target}`); continue; }
144
+ if (found) { errors.push(`"${b.name}" already exists in ${target}: list it under MODIFIED instead`); continue; }
145
+ while (a.lines.length && a.lines[a.lines.length - 1].trim() === '') a.lines.pop();
146
+ a.lines.push('', ...withSource(b, id));
147
+ a.counts.added++;
148
+ } else if (s.op === 'MODIFIED') {
149
+ if (!found) { errors.push(`no requirement "${b.name}" in ${target} to modify: list it under ADDED instead`); continue; }
150
+ if (normalize(found.lines) === normalize(b.lines)) continue;
151
+ a.lines.splice(found.start, found.end - found.start, ...withSource(b, id));
152
+ a.counts.changed++;
153
+ } else if (!found) {
154
+ notes.push(`"${b.name}" isn't in ${target} (already removed, or a typo in its name)`);
155
+ } else {
156
+ a.lines.splice(found.start, found.end - found.start);
157
+ a.counts.removed++;
158
+ }
159
+ }
160
+ }
161
+ if (errors.length) { errors.forEach(e => console.error(`✗ ${e}`)); console.error('\nNothing was changed.'); return 1; }
162
+
163
+ fs.mkdirSync('specs/current', { recursive: true });
164
+ for (const a of Object.values(areas)) {
165
+ const c = a.counts;
166
+ if (!c.added && !c.changed && !c.removed) continue;
167
+ if (!blocks(a.lines).length) {
168
+ fs.rmSync(a.target, { force: true });
169
+ console.log(`${a.target}: its last requirement was removed, so the file was deleted`);
170
+ continue;
171
+ }
172
+ fs.writeFileSync(a.target, `${a.lines.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '')}\n`);
173
+ console.log(`${a.target}: ${c.added} added, ${c.changed} changed, ${c.removed} removed`);
174
+ }
175
+ notes.forEach(n => console.log(` note: ${n}`));
176
+ return 0;
177
+ }
178
+
179
+ function status() {
180
+ const dirs = fs.existsSync('specs') ? fs.readdirSync('specs', { withFileTypes: true })
181
+ .filter(e => e.isDirectory() && !['_templates', 'current'].includes(e.name)).map(e => e.name) : [];
182
+ const rows = dirs.map(name => {
183
+ const dir = `specs/${name}`;
184
+ const state = ((read(`${dir}/progress.md`) || '').match(/^Status:\s*(.*?)\s*$/m) || [])[1] || 'no progress.md';
185
+ const tasks = read(`${dir}/tasks.md`) || '';
186
+ const done = (tasks.match(/^\s*- \[[xX]\]/gm) || []).length;
187
+ const total = done + (tasks.match(/^\s*- \[ \]/gm) || []).length;
188
+ const updated = Math.max(0, ...fs.readdirSync(dir).map(f => fs.statSync(path.join(dir, f)).mtimeMs));
189
+ return { name, state, tasks: total ? `tasks ${done}/${total}` : 'no tasks yet', updated };
190
+ }).sort((a, b) => b.updated - a.updated);
191
+ if (!rows.length) console.log('No specs yet.');
192
+ const w = Math.max(0, ...rows.map(r => r.name.length));
193
+ for (const r of rows) console.log(`${r.name.padEnd(w)} ${r.state.padEnd(32)} ${r.tasks} (updated ${new Date(r.updated).toISOString().slice(0, 10)})`);
194
+ const current = allSpecFiles().filter(f => f.startsWith('specs/current/'));
195
+ const count = current.reduce((n, f) => n + blocks(read(f).split('\n')).length, 0);
196
+ console.log(`\nLiving spec: ${current.length} area(s), ${count} requirement(s) in specs/current/`);
197
+ return 0;
198
+ }
199
+
200
+ // a feature spec still being drafted: its work hasn't started (progress.md says "not started")
201
+ const isDraft = f => /^specs\/[^/]+\/requirements\.md$/.test(f) && !f.startsWith('specs/current/')
202
+ && !/^Status:\s*(in progress|done)/im.test(read(f.replace(/requirements\.md$/, 'progress.md')) || '');
203
+
204
+ if (cmd === 'check') {
205
+ const skipDrafts = args.includes('--skip-drafts');
206
+ const named = args.filter(a => a !== '--skip-drafts');
207
+ const files = (named.length ? named : allSpecFiles()).filter(f => !(skipDrafts && isDraft(f)));
208
+ const problems = files.flatMap(checkFile);
209
+ problems.forEach(p => console.error(`✗ ${p}`));
210
+ if (!problems.length) console.log(`✓ ${files.length} spec file(s) checked`);
211
+ process.exitCode = problems.length ? 1 : 0;
212
+ } else if (cmd === 'merge' && args[0]) {
213
+ process.exitCode = merge(args[0]);
214
+ } else if (cmd === 'status') {
215
+ process.exitCode = status();
216
+ } else {
217
+ console.log(fs.readFileSync(__filename, 'utf8').split('\n').slice(1, 10).map(l => l.replace(/^\/\/ ?/, '')).join('\n'));
218
+ process.exitCode = 1;
219
+ }
@@ -4,11 +4,11 @@ appId: ${APP_ID} # set by verify.sh
4
4
  ---
5
5
  - launchApp:
6
6
  clearState: true
7
- # Criterion 1: <WHEN … THE APP SHALL …>
7
+ # Scenario 1: <scenario name from requirements.md>
8
8
  - assertVisible:
9
9
  id: "<testID of the element>"
10
10
  - takeScreenshot: <id>-1-<short-name>
11
- # Criterion 2: …
11
+ # Scenario 2: …
12
12
  - tapOn:
13
13
  id: "<testID>"
14
14
  - takeScreenshot: <id>-2-<short-name>
@@ -4,15 +4,37 @@ Source: <link to the task in Excel, Trello or the task platform>
4
4
 
5
5
  ## Goal
6
6
 
7
- <!-- One or two sentences: what the user can do after this change, and why. -->
7
+ <!-- One or two sentences: what the user can do after this change, and why.
8
+ One intent you can say in a sentence: if it needs "and also", it's two features. -->
8
9
 
9
- ## Acceptance criteria
10
+ ## ADDED Requirements: <area>
10
11
 
11
- <!-- One line each, testable: "WHEN <trigger> THE APP SHALL <response>". -->
12
- 1. WHEN … THE APP SHALL …
12
+ <!-- <area> names the living spec file specs/current/<area>.md (for example login or tasks); read it first.
13
+ Each requirement is one behavior, with SHALL (or MUST), that someone who can't see the code could check.
14
+ Scenarios are concrete cases that prove it, edge and error cases included; name the case in the title.
15
+ Format and examples: specs/current/README.md. -->
16
+
17
+ ### Requirement: <name>
18
+ The app SHALL <behavior>.
19
+
20
+ #### Scenario: <the case, for example "Rejects an expired code">
21
+ - GIVEN <starting state>
22
+ - WHEN <action or event>
23
+ - THEN <what the user sees or what happens>
24
+
25
+ ## MODIFIED Requirements: <area>
26
+
27
+ <!-- Requirements already in specs/current/<area>.md that this changes: copy each one, keep its name, edit it.
28
+ Delete this section if nothing existing changes. -->
29
+
30
+ ## REMOVED Requirements: <area>
31
+
32
+ <!-- Requirements in specs/current/<area>.md that go away: "### Requirement: <name>" and a line on why.
33
+ Delete this section if nothing is removed. -->
13
34
 
14
35
  ## Edge cases (answer each, or write "n/a")
15
36
 
37
+ <!-- Each case that matters gets a scenario above. -->
16
38
  - Offline or slow network:
17
39
  - Server error, timeout:
18
40
  - Empty, loading and long-content states:
@@ -1,6 +1,6 @@
1
1
  # <ID>: tasks
2
2
 
3
- Each task: about an hour of work, under ~300 changed lines, with its own check. One commit per task.
3
+ Each task: about an hour of work, under ~300 changed lines, one commit. Each one names the requirement it serves and how it's checked. Its tests are written in the same task, not in a catch-up task at the end.
4
4
 
5
- - [ ] 1. <task> — files: <paths> — check: <command or manual step>
5
+ - [ ] 1. <task> — for: <requirement name> — files: <paths> — check: <test, command or screen>
6
6
  - [ ] 2.
@@ -0,0 +1,40 @@
1
+ # What the app does now
2
+
3
+ One file per area of the app (for example `login.md` or `tasks.md`) that describes how the app behaves today, requirement by requirement. AI tools read it before they change an area, so they don't have to work out the current behavior from the code.
4
+
5
+ It starts empty and grows one change at a time; there's no need to describe the whole app up front. Each feature's `specs/<id>/requirements.md` lists what it adds, changes and removes, and when the feature is done, `node scripts/ai/spec.js merge <id>` applies those changes here. People can edit these files too.
6
+
7
+ ## Format
8
+
9
+ # Login
10
+
11
+ ## Requirements
12
+
13
+ ### Requirement: Sign in with a one-time code
14
+ The app SHALL sign the user in after they enter the 6-digit code sent to their email.
15
+
16
+ Source: specs/LOGIN-12
17
+
18
+ #### Scenario: Correct code
19
+ - GIVEN a user who requested a code
20
+ - WHEN they enter it within 10 minutes
21
+ - THEN they land on the home screen
22
+
23
+ #### Scenario: Rejects an expired code
24
+ - GIVEN a code older than 10 minutes
25
+ - WHEN the user enters it
26
+ - THEN the app shows "This code has expired" and offers to send a new one
27
+
28
+ - **A requirement** is one behavior, stated with SHALL (or MUST) so that someone who can't see the code could check it. How it's built belongs in `design.md`, not here.
29
+ - **A scenario** is a concrete case that proves the requirement, with GIVEN, WHEN and THEN. Cover the cases where bugs live (empty input, errors, offline, a second tap), and name the case in the title. Each scenario becomes a step and a screenshot in the feature's Maestro flow, or a test.
30
+ - **Only what's true now:** no plans and no history. The `Source:` line points to the feature that last changed the requirement, whose folder keeps the history.
31
+
32
+ ## How a feature changes it
33
+
34
+ A feature's `requirements.md` groups its requirements under these headings, where `<area>` is the file name here:
35
+
36
+ - `## ADDED Requirements: <area>`: new behavior. Merging appends it. The name must not exist yet.
37
+ - `## MODIFIED Requirements: <area>`: behavior that changes. Copy the current requirement, keep its name, and edit it. Merging replaces the old one.
38
+ - `## REMOVED Requirements: <area>`: behavior that goes away, with a line on why. Merging deletes it, and deletes the file when its last requirement goes.
39
+
40
+ `node scripts/ai/spec.js check` checks the format; the git pre-commit hook runs it on staged specs once their work has started. `node scripts/ai/spec.js status` lists every feature's state and task progress.