agentic-mobile-kit 0.4.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 +5 -4
- package/bin/cli.js +7 -6
- package/lib/init.js +84 -25
- package/package.json +1 -1
- package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +3 -1
- package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +3 -1
- package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +17 -0
- package/stacks/react-native/template/.agents/skills/m-explore/agents/openai.yaml +3 -0
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +25 -10
- package/stacks/react-native/template/.agents/skills/m-learn/SKILL.md +2 -0
- package/stacks/react-native/template/.agents/skills/m-pause/SKILL.md +2 -0
- package/stacks/react-native/template/.agents/skills/m-release/SKILL.md +16 -8
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +7 -1
- package/stacks/react-native/template/.githooks/pre-commit +7 -1
- package/stacks/react-native/template/AGENTS.md +6 -2
- package/stacks/react-native/template/scripts/ai/release-build.sh +87 -0
- package/stacks/react-native/template/scripts/ai/release-check.js +10 -5
- package/stacks/react-native/template/scripts/ai/spec.js +219 -0
- package/stacks/react-native/template/specs/_templates/flow.yaml +2 -2
- package/stacks/react-native/template/specs/_templates/requirements.md +26 -4
- package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
- package/stacks/react-native/template/specs/current/README.md +40 -0
package/README.md
CHANGED
|
@@ -11,6 +11,7 @@ Run in the app's root, on a clean git working tree:
|
|
|
11
11
|
```sh
|
|
12
12
|
npx agentic-mobile-kit init
|
|
13
13
|
npx agentic-mobile-kit init --tools claude,codex,antigravity # choose your AI tools
|
|
14
|
+
npx agentic-mobile-kit init --ci github,codemagic # only if the app uses that CI
|
|
14
15
|
```
|
|
15
16
|
|
|
16
17
|
Then check the project and your machine, with a fix for each problem:
|
|
@@ -36,11 +37,11 @@ Installs older than 0.4.0 don't record which kit version made them, so their fir
|
|
|
36
37
|
|
|
37
38
|
## What it adds
|
|
38
39
|
|
|
39
|
-
- **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)
|
|
40
|
-
- **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.
|
|
41
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.
|
|
42
|
-
- **Releases:** `m-release` writes
|
|
43
|
-
- **Checks no tool can skip:** git hooks (secrets, signing files, broken Xcode project files, lint, typecheck, tests) and GitHub Actions CI (lint, typecheck, tests, secret scan, PR size, Android and iOS builds).
|
|
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
|
+
- **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).
|
|
44
45
|
|
|
45
46
|
Work continues across tools and machines through `specs/<id>/progress.md`: run `m-pause` in one tool, then `m-continue` in another.
|
|
46
47
|
|
package/bin/cli.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
const { version } = require('../package.json');
|
|
3
|
-
const { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS } = require('../lib/init');
|
|
3
|
+
const { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI } = require('../lib/init');
|
|
4
4
|
const { doctor, printDoctor } = require('../lib/doctor');
|
|
5
5
|
|
|
6
6
|
const [cmd, ...rest] = process.argv.slice(2);
|
|
@@ -8,12 +8,13 @@ const flag = name => {
|
|
|
8
8
|
const i = rest.indexOf(`--${name}`);
|
|
9
9
|
return i >= 0 ? rest[i + 1] : undefined;
|
|
10
10
|
};
|
|
11
|
+
const list = name => (flag(name) ? flag(name).split(',').map(s => s.trim()).filter(Boolean) : undefined);
|
|
11
12
|
|
|
12
13
|
const help = `agentic-mobile-kit ${version}
|
|
13
14
|
|
|
14
15
|
Usage:
|
|
15
|
-
npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--pm yarn|npm|pnpm|bun]
|
|
16
|
-
npx agentic-mobile-kit sync [--from <version>]
|
|
16
|
+
npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--ci github,codemagic] [--pm yarn|npm|pnpm|bun]
|
|
17
|
+
npx agentic-mobile-kit sync [--ci github,codemagic] [--from <version>]
|
|
17
18
|
npx agentic-mobile-kit uninstall [--from <version>]
|
|
18
19
|
npx agentic-mobile-kit doctor
|
|
19
20
|
|
|
@@ -25,6 +26,7 @@ Commands:
|
|
|
25
26
|
|
|
26
27
|
Options:
|
|
27
28
|
--tools AI tools your team uses: ${Object.keys(TOOLS).join(', ')} (default: claude,codex,antigravity)
|
|
29
|
+
--ci CI to set up, only if the app uses it: ${Object.keys(CI).join(', ')} (GitHub Actions checks, Codemagic signed builds; default: none)
|
|
28
30
|
--pm Package manager, if it can't be detected from the lockfile
|
|
29
31
|
--from The kit version that installed the project; needed only for installs made before 0.4.0`;
|
|
30
32
|
|
|
@@ -41,11 +43,10 @@ if (cmd === '--version' || cmd === '-v') {
|
|
|
41
43
|
console.log(version);
|
|
42
44
|
} else if (cmd === 'init') {
|
|
43
45
|
run('init', () => {
|
|
44
|
-
|
|
45
|
-
printSummary(init(process.cwd(), { tools, pm: flag('pm') }));
|
|
46
|
+
printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
|
|
46
47
|
});
|
|
47
48
|
} else if (cmd === 'sync') {
|
|
48
|
-
run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), pm: flag('pm') })));
|
|
49
|
+
run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
|
|
49
50
|
} else if (cmd === 'uninstall') {
|
|
50
51
|
run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
|
|
51
52
|
} else if (cmd === 'doctor') {
|
package/lib/init.js
CHANGED
|
@@ -16,6 +16,12 @@ const FILLED = ['AGENTS.md', 'codemagic.yaml'];
|
|
|
16
16
|
// docs each team rewrites for its app: sync replaces them only while they're untouched, and never merges into them
|
|
17
17
|
const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/ai/${n}.md`);
|
|
18
18
|
const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
|
|
19
|
+
// optional parts, installed only when a project chooses them with --ci: not every app uses CI
|
|
20
|
+
const CI = {
|
|
21
|
+
github: rel => rel.startsWith(`.github${path.sep}`),
|
|
22
|
+
codemagic: rel => rel === 'codemagic.yaml' || rel === path.join('docs', 'ai', 'codemagic.md'),
|
|
23
|
+
};
|
|
24
|
+
const ciGroup = rel => Object.keys(CI).find(g => CI[g](rel));
|
|
19
25
|
|
|
20
26
|
// tool name -> rulesync targets
|
|
21
27
|
const TOOLS = {
|
|
@@ -103,9 +109,10 @@ function fillPlaceholders(text, values) {
|
|
|
103
109
|
return text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in values ? values[k] : m));
|
|
104
110
|
}
|
|
105
111
|
|
|
106
|
-
function projectValues(cwd, pkg, deps, pm) {
|
|
112
|
+
function projectValues(cwd, pkg, deps, pm, ci) {
|
|
107
113
|
return {
|
|
108
114
|
KIT_VERSION,
|
|
115
|
+
KIT_CI: ci.join(',') || 'none',
|
|
109
116
|
APP_NAME: pkg.name || path.basename(cwd),
|
|
110
117
|
RN_VERSION: installedVersion(cwd, 'react-native', deps['react-native']),
|
|
111
118
|
REACT_VERSION: installedVersion(cwd, 'react', deps.react),
|
|
@@ -153,11 +160,29 @@ function installedTools(cwd) {
|
|
|
153
160
|
return tools.length ? tools : TESTED;
|
|
154
161
|
}
|
|
155
162
|
|
|
163
|
+
// what the kit marker in AGENTS.md records: the kit version since 0.4.0, the CI choice since 0.5.0
|
|
164
|
+
function recorded(agents) {
|
|
165
|
+
const m = (agents || '').match(/KIT:START agentic-mobile-kit (\d[^\s>]*)(?: ci=([\w,]+))?/);
|
|
166
|
+
return { version: m ? m[1] : null, ci: m && m[2] ? m[2].split(',').filter(g => CI[g]) : null };
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// the CI parts a project has: as recorded, or (installs before 0.5.0 got them by default) recognized by the kit's own files
|
|
170
|
+
function installedCi(cwd, agents) {
|
|
171
|
+
return recorded(agents).ci || Object.keys(CI).filter(g => (g === 'github'
|
|
172
|
+
? /agentic-mobile-kit/.test(readIf(path.join(cwd, '.github', 'workflows', 'ci.yml')) || '')
|
|
173
|
+
: fs.existsSync(path.join(cwd, 'docs', 'ai', 'codemagic.md'))));
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
function chooseCi(cwd, agents, wanted = []) {
|
|
177
|
+
for (const g of wanted) if (!CI[g]) throw new InitError(`Unknown CI "${g}". Choose from: ${Object.keys(CI).join(', ')}.`);
|
|
178
|
+
return Object.keys(CI).filter(g => wanted.includes(g) || installedCi(cwd, agents).includes(g));
|
|
179
|
+
}
|
|
180
|
+
|
|
156
181
|
// the kit version that installed the project: recorded in AGENTS.md since 0.4.0, or given with --from.
|
|
157
182
|
// A --from version is a guess (installs may predate it), so it isn't trusted as a merge base.
|
|
158
183
|
function oldTemplate(agents, opts) {
|
|
159
184
|
if (opts.fromDir) return { from: opts.from || 'old', dir: opts.fromDir, exact: !opts.from };
|
|
160
|
-
const from = opts.from || (agents.
|
|
185
|
+
const from = opts.from || recorded(agents).version;
|
|
161
186
|
if (!from) {
|
|
162
187
|
throw new InitError('This project doesn\'t record which kit version installed it (versions before 0.4.0 didn\'t). '
|
|
163
188
|
+ 'Pass it with --from, for example --from 0.3.0; the commit that added or last updated the kit usually says.');
|
|
@@ -170,6 +195,7 @@ function oldTemplate(agents, opts) {
|
|
|
170
195
|
|
|
171
196
|
function fetchTemplate(version) {
|
|
172
197
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-kit-'));
|
|
198
|
+
process.on('exit', () => fs.rmSync(dir, { recursive: true, force: true }));
|
|
173
199
|
const r = spawnSync('npm', ['pack', `agentic-mobile-kit@${version}`, '--pack-destination', dir, '--silent'], { cwd: dir, env: cleanEnv(), encoding: 'utf8' });
|
|
174
200
|
if (r.status !== 0) throw new InitError(`Couldn't download agentic-mobile-kit@${version} from npm: ${(r.stderr || '').trim().split('\n').pop()}`);
|
|
175
201
|
execFileSync('tar', ['-xzf', path.join(dir, r.stdout.trim().split('\n').pop()), '-C', dir]);
|
|
@@ -186,18 +212,33 @@ function merge3(current, base, kitNew, from) {
|
|
|
186
212
|
return { text: r.stdout, conflicts: r.status };
|
|
187
213
|
}
|
|
188
214
|
|
|
215
|
+
const SKILL_LINKS = [['.claude/skills', 'claude'], ['.kiro/skills', 'kiro']];
|
|
216
|
+
const kitSkills = template => fs.readdirSync(path.join(template, '.agents', 'skills'), { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
|
|
217
|
+
|
|
189
218
|
// steps 2–6, shared by init and sync
|
|
190
|
-
function finish(cwd, { pkg, deps, tools, skipGenerate }) {
|
|
219
|
+
function finish(cwd, { pkg, deps, tools, template, skipGenerate }) {
|
|
191
220
|
const done = { created: [], merged: [], skipped: [] };
|
|
192
221
|
|
|
193
|
-
// 2. skills
|
|
194
|
-
for (const [link, tool] of
|
|
222
|
+
// 2. skills links for tools that don't read .agents/skills
|
|
223
|
+
for (const [link, tool] of SKILL_LINKS) {
|
|
195
224
|
if (!tools.includes(tool)) continue;
|
|
196
225
|
const dest = path.join(cwd, link);
|
|
197
|
-
if (fs.existsSync(dest)
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
226
|
+
if (!fs.existsSync(dest) && !isLink(dest)) {
|
|
227
|
+
fs.mkdirSync(path.dirname(dest), { recursive: true });
|
|
228
|
+
fs.symlinkSync('../.agents/skills', dest);
|
|
229
|
+
done.created.push(`${link} -> .agents/skills`);
|
|
230
|
+
continue;
|
|
231
|
+
}
|
|
232
|
+
if (isLink(dest) || !fs.statSync(dest).isDirectory()) { done.skipped.push(link); continue; }
|
|
233
|
+
// the folder already holds another framework's skills: link each kit skill into it
|
|
234
|
+
for (const name of kitSkills(template)) {
|
|
235
|
+
const p = path.join(dest, name);
|
|
236
|
+
const target = `../../.agents/skills/${name}`;
|
|
237
|
+
if (isLink(p) && fs.readlinkSync(p) === target) continue;
|
|
238
|
+
if (fs.existsSync(p) || isLink(p)) { done.skipped.push(`${link}/${name} (another skill has this name)`); continue; }
|
|
239
|
+
fs.symlinkSync(target, p);
|
|
240
|
+
done.created.push(`${link}/${name} -> .agents/skills/${name}`);
|
|
241
|
+
}
|
|
201
242
|
}
|
|
202
243
|
|
|
203
244
|
// 3. .gitignore: keep secrets out of git
|
|
@@ -244,12 +285,14 @@ function init(cwd, opts = {}) {
|
|
|
244
285
|
const tools = opts.tools || TESTED;
|
|
245
286
|
for (const t of tools) if (!TOOLS[t]) throw new InitError(`Unknown tool "${t}". Choose from: ${Object.keys(TOOLS).join(', ')}.`);
|
|
246
287
|
const template = opts.template || TEMPLATE;
|
|
247
|
-
const
|
|
288
|
+
const ci = chooseCi(cwd, readIf(path.join(cwd, 'AGENTS.md')), opts.ci);
|
|
289
|
+
const values = projectValues(cwd, pkg, deps, pm, ci);
|
|
248
290
|
const targets = tools.flatMap(t => TOOLS[t]);
|
|
249
291
|
const report = { created: [], merged: [], skipped: [] };
|
|
250
292
|
|
|
251
293
|
// 1. template files (never overwrite)
|
|
252
294
|
for (const rel of templateFiles(template)) {
|
|
295
|
+
if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
|
|
253
296
|
const dest = path.join(cwd, rel);
|
|
254
297
|
const text = kitText(template, rel, values, targets);
|
|
255
298
|
const current = readIf(dest);
|
|
@@ -263,9 +306,9 @@ function init(cwd, opts = {}) {
|
|
|
263
306
|
report.created.push(rel);
|
|
264
307
|
}
|
|
265
308
|
|
|
266
|
-
const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, skipGenerate: opts.skipGenerate });
|
|
309
|
+
const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
|
|
267
310
|
for (const k of Object.keys(report)) report[k].push(...done[k]);
|
|
268
|
-
return { report, values, tools, generated, generateError };
|
|
311
|
+
return { report, values, tools, ci, generated, generateError };
|
|
269
312
|
}
|
|
270
313
|
|
|
271
314
|
function sync(cwd, opts = {}) {
|
|
@@ -274,7 +317,11 @@ function sync(cwd, opts = {}) {
|
|
|
274
317
|
if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section). Run init instead.');
|
|
275
318
|
const { from, dir: oldDir, exact } = oldTemplate(agents, opts);
|
|
276
319
|
const template = opts.template || TEMPLATE;
|
|
277
|
-
const
|
|
320
|
+
const ci = chooseCi(cwd, agents, opts.ci);
|
|
321
|
+
// a CI part chosen just now was never installed, so its files are new rather than deleted by the team
|
|
322
|
+
const hadCi = installedCi(cwd, agents);
|
|
323
|
+
const wasInstalled = rel => !ciGroup(rel) || hadCi.includes(ciGroup(rel));
|
|
324
|
+
const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), ci);
|
|
278
325
|
const tools = installedTools(cwd);
|
|
279
326
|
const targets = tools.flatMap(t => TOOLS[t]);
|
|
280
327
|
const report = { updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
|
|
@@ -282,8 +329,9 @@ function sync(cwd, opts = {}) {
|
|
|
282
329
|
const oldFiles = new Set(templateFiles(oldDir));
|
|
283
330
|
|
|
284
331
|
for (const rel of newFiles) {
|
|
332
|
+
if (ciGroup(rel) && !ci.includes(ciGroup(rel))) continue;
|
|
285
333
|
const kitNew = kitText(template, rel, values, targets);
|
|
286
|
-
const kitOld = oldFiles.has(rel) ? kitText(oldDir, rel, values, targets) : null;
|
|
334
|
+
const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldDir, rel, values, targets) : null;
|
|
287
335
|
const current = projectText(cwd, rel, targets);
|
|
288
336
|
if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
|
|
289
337
|
const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, kitNew) : mergeClaude(current);
|
|
@@ -297,7 +345,8 @@ function sync(cwd, opts = {}) {
|
|
|
297
345
|
if (current === kitNew) continue;
|
|
298
346
|
if (kitOld === null) { report.kept.push(`${rel} (your own file; the kit now has one with this name)`); continue; }
|
|
299
347
|
if (current === kitOld) { writeKitFile(cwd, rel, kitNew); report.updated.push(rel); continue; }
|
|
300
|
-
|
|
348
|
+
// the team changed it and the kit didn't: nothing to bring in
|
|
349
|
+
if (kitOld === kitNew || PROJECT_DOCS.includes(rel)) continue;
|
|
301
350
|
// without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
|
|
302
351
|
const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
|
|
303
352
|
writeKitFile(cwd, rel, text);
|
|
@@ -305,13 +354,13 @@ function sync(cwd, opts = {}) {
|
|
|
305
354
|
}
|
|
306
355
|
// files the kit no longer ships
|
|
307
356
|
for (const rel of oldFiles) {
|
|
308
|
-
if (newFiles.includes(rel)) continue;
|
|
357
|
+
if (newFiles.includes(rel) || !wasInstalled(rel)) continue;
|
|
309
358
|
const current = projectText(cwd, rel, targets);
|
|
310
359
|
if (current === null) continue;
|
|
311
360
|
if (current === kitText(oldDir, rel, values, targets)) { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); } else report.kept.push(`${rel} (the kit dropped it; you changed it)`);
|
|
312
361
|
}
|
|
313
362
|
|
|
314
|
-
const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, skipGenerate: opts.skipGenerate });
|
|
363
|
+
const { done, generated, generateError } = finish(cwd, { pkg, deps, tools, template, skipGenerate: opts.skipGenerate });
|
|
315
364
|
report.added.push(...done.created);
|
|
316
365
|
report.updated.push(...done.merged);
|
|
317
366
|
return { report, from, to: KIT_VERSION, tools, generated, generateError };
|
|
@@ -335,7 +384,7 @@ function uninstall(cwd, opts = {}) {
|
|
|
335
384
|
const agents = readIf(path.join(cwd, 'AGENTS.md'));
|
|
336
385
|
if (!agents || !MARKERS.test(agents)) throw new InitError('The kit isn\'t installed here (AGENTS.md has no KIT section).');
|
|
337
386
|
const { from, dir: template } = oldTemplate(agents, opts);
|
|
338
|
-
const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm));
|
|
387
|
+
const values = projectValues(cwd, pkg, deps, detectPm(cwd, opts.pm), installedCi(cwd, agents));
|
|
339
388
|
const targets = installedTools(cwd).flatMap(t => TOOLS[t]);
|
|
340
389
|
const report = { removed: [], kept: [], left: [] };
|
|
341
390
|
const remove = rel => { fs.unlinkSync(path.join(cwd, rel)); report.removed.push(rel); };
|
|
@@ -358,9 +407,15 @@ function uninstall(cwd, opts = {}) {
|
|
|
358
407
|
if (current === null) continue;
|
|
359
408
|
if (current === text) remove(rel); else report.kept.push(`${rel} (also has your own settings; remove the kit's entries by hand)`);
|
|
360
409
|
}
|
|
361
|
-
for (const link of
|
|
410
|
+
for (const [link] of SKILL_LINKS) {
|
|
362
411
|
const p = path.join(cwd, link);
|
|
363
|
-
if (isLink(p) && fs.readlinkSync(p) === '../.agents/skills') { fs.unlinkSync(p); report.removed.push(link); }
|
|
412
|
+
if (isLink(p) && fs.readlinkSync(p) === '../.agents/skills') { fs.unlinkSync(p); report.removed.push(link); continue; }
|
|
413
|
+
// per-skill links inside another framework's skills folder
|
|
414
|
+
if (!fs.existsSync(p) || isLink(p)) continue;
|
|
415
|
+
for (const name of fs.readdirSync(p)) {
|
|
416
|
+
const q = path.join(p, name);
|
|
417
|
+
if (isLink(q) && fs.readlinkSync(q) === `../../.agents/skills/${name}`) { fs.unlinkSync(q); report.removed.push(path.join(link, name)); }
|
|
418
|
+
}
|
|
364
419
|
}
|
|
365
420
|
// folders left empty (rmdir refuses non-empty ones)
|
|
366
421
|
const dirs = [...new Set(report.removed.map(r => path.dirname(r.split(' (')[0])))].sort((a, b) => b.length - a.length);
|
|
@@ -383,9 +438,10 @@ function uninstall(cwd, opts = {}) {
|
|
|
383
438
|
return { report, from };
|
|
384
439
|
}
|
|
385
440
|
|
|
386
|
-
function printSummary({ report, values, tools, generated, generateError }, log = console.log) {
|
|
441
|
+
function printSummary({ report, values, tools, ci, generated, generateError }, log = console.log) {
|
|
387
442
|
log(`agentic-mobile-kit installed for ${values.APP_NAME} (React Native ${values.RN_VERSION}, ${values.PM}).`);
|
|
388
443
|
log(`Tools: ${tools.join(', ')}${tools.some(t => !TESTED.includes(t)) ? ' (cursor, opencode and kiro are not tested yet)' : ''}`);
|
|
444
|
+
log(`CI: ${ci.length ? ci.join(', ') : 'none (add it any time with --ci github,codemagic)'}`);
|
|
389
445
|
log(` created: ${report.created.length} files`);
|
|
390
446
|
if (report.merged.length) log(` merged: ${report.merged.join(', ')}`);
|
|
391
447
|
if (report.skipped.length) log(` kept as they were (already existed): ${report.skipped.join(', ')}`);
|
|
@@ -393,9 +449,12 @@ function printSummary({ report, values, tools, generated, generateError }, log =
|
|
|
393
449
|
log('\nNext steps:');
|
|
394
450
|
log(' 1. Fill in docs/ai/product.md, tech.md, structure.md and conventions.md for this app.');
|
|
395
451
|
log(' 2. Commit on a branch and open a PR. Add the "large-pr" label (the vendored skills are large).');
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
452
|
+
const more = [
|
|
453
|
+
ci.includes('github') && 'Turn on branch protection for main: see docs/branch-protection.md in the kit repo.',
|
|
454
|
+
ci.includes('codemagic') && 'Signed store builds on Codemagic: one-time setup in docs/ai/codemagic.md.',
|
|
455
|
+
tools.includes('codex') && 'Codex users: open the project in Codex once and approve its hooks (they stay off until approved).',
|
|
456
|
+
].filter(Boolean);
|
|
457
|
+
more.forEach((m, i) => log(` ${i + 3}. ${m}`));
|
|
399
458
|
}
|
|
400
459
|
|
|
401
460
|
function printSync({ report, from, to, generated, generateError }, log = console.log) {
|
|
@@ -417,4 +476,4 @@ function printUninstall({ report }, log = console.log) {
|
|
|
417
476
|
log('\nReview it with "git status" and "git diff", then commit. Undo it with git if you change your mind.');
|
|
418
477
|
}
|
|
419
478
|
|
|
420
|
-
module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, KIT_VERSION };
|
|
479
|
+
module.exports = { init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, CI, KIT_VERSION };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-mobile-kit",
|
|
3
|
-
"version": "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",
|
|
@@ -6,6 +6,8 @@ disable-model-invocation: true
|
|
|
6
6
|
|
|
7
7
|
# m-bugfix
|
|
8
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
|
+
|
|
9
11
|
Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, task link).
|
|
10
12
|
|
|
11
13
|
1. **Check `docs/ai/known-issues.md`** for a matching error. If there is one, apply its fix and verify.
|
|
@@ -19,5 +21,5 @@ Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, ta
|
|
|
19
21
|
5. **Make the smallest fix.** Don't refactor or touch unrelated code.
|
|
20
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.
|
|
21
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.
|
|
22
|
-
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`.
|
|
23
25
|
9. **Commit** with a message ending in `Assisted-by: <tool>/<model>`. Ask the user before pushing, then open a PR with the evidence.
|
|
@@ -6,12 +6,14 @@ disable-model-invocation: true
|
|
|
6
6
|
|
|
7
7
|
# m-continue
|
|
8
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
|
+
|
|
9
11
|
Input: $ARGUMENTS (a spec ID, or empty).
|
|
10
12
|
|
|
11
13
|
1. **Check git first.** Run `git fetch` and `git status`.
|
|
12
14
|
- If the branch is behind its remote, say so and ask before pulling.
|
|
13
15
|
- If there are uncommitted changes, list them; they may be half-done work.
|
|
14
|
-
2. **Find the spec.** Use the given ID; otherwise
|
|
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.
|
|
15
17
|
3. **Read** `requirements.md`, `design.md`, `tasks.md` and `progress.md` in that spec folder, plus `git log --oneline -15`.
|
|
16
18
|
4. **Report back, in this order:**
|
|
17
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.
|
|
@@ -6,27 +6,36 @@ disable-model-invocation: true
|
|
|
6
6
|
|
|
7
7
|
# m-feature
|
|
8
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
|
+
|
|
9
11
|
Input: $ARGUMENTS (the requirement text, a file path, or a task link plus pasted details).
|
|
10
12
|
|
|
11
13
|
## 1. Always use the full flow
|
|
12
14
|
|
|
13
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.)
|
|
14
16
|
|
|
15
|
-
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.
|
|
16
18
|
|
|
17
19
|
## 2. Requirements (then stop for approval)
|
|
18
20
|
|
|
19
21
|
1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `specs/_templates/` to `specs/<id>/`.
|
|
20
|
-
2.
|
|
21
|
-
3.
|
|
22
|
-
4.
|
|
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?
|
|
23
30
|
|
|
24
31
|
## 3. Design and tasks (then stop for approval)
|
|
25
32
|
|
|
26
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`.
|
|
27
34
|
2. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
|
|
28
|
-
3. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each),
|
|
29
|
-
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>`.
|
|
30
39
|
|
|
31
40
|
## 4. Build, one task at a time
|
|
32
41
|
|
|
@@ -36,15 +45,21 @@ For each task:
|
|
|
36
45
|
3. Commit with a clear message ending in `Assisted-by: <tool>/<model>` and `Spec: specs/<id>`.
|
|
37
46
|
4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
|
|
38
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
|
+
|
|
39
50
|
## 5. Check against the spec
|
|
40
51
|
|
|
41
52
|
When all tasks are done:
|
|
42
|
-
1. Run `sh scripts/ai/verify.sh all --spec <id>`. Then **open the screenshots** in `.ai/evidence/<id>/` and check each one against its
|
|
43
|
-
2. Go through every
|
|
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.
|
|
44
59
|
|
|
45
|
-
##
|
|
60
|
+
## 7. Review and pull request
|
|
46
61
|
|
|
47
62
|
1. Run `m-review` (or ask the `m-reviewer` subagent, if your tool has subagents). Fix real problems only; skip style nits.
|
|
48
|
-
2. Ask the user before pushing. Then push the feature branch (never `main`) and open a PR
|
|
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.
|
|
49
64
|
|
|
50
65
|
Never claim a check passed without running it in this session.
|
|
@@ -6,6 +6,8 @@ disable-model-invocation: true
|
|
|
6
6
|
|
|
7
7
|
# m-learn
|
|
8
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
|
+
|
|
9
11
|
Input: $ARGUMENTS (what went wrong or what the user had to correct; the error text, PR comment or session transcript if there is one).
|
|
10
12
|
|
|
11
13
|
1. **State the lesson in one sentence:** what happened, what should have happened, and why. The usual causes are missing context, an ignored rule, the wrong command, or a gap in the rules. Quote the evidence, and don't guess what an earlier session did. If the cause isn't clear, ask.
|
|
@@ -6,6 +6,8 @@ disable-model-invocation: true
|
|
|
6
6
|
|
|
7
7
|
# m-pause
|
|
8
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
|
+
|
|
9
11
|
1. **Update the handoff block** at the top of `specs/<id>/progress.md`: date and time, tool and model, branch, status (start the line with `not started`, `in progress — task N of M` or `done`, exactly), done, in progress (with file paths and what's half-done), the exact next step, decisions, open question, last check results, blockers, notes. Add a line to the log.
|
|
10
12
|
2. **Move decisions out of the chat.** Anything decided in this conversation goes into `requirements.md`, `design.md` or `docs/ai/decisions.md` now. Chat history doesn't travel to other tools.
|
|
11
13
|
3. **Commit the work in progress** on the feature branch (never `main`): message `wip: <id> <short summary>`, ending with `Assisted-by: <tool>/<model>` and `Spec: specs/<id>`.
|
|
@@ -1,23 +1,31 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: m-release
|
|
3
|
-
description: Prepare a store release - version, changelog and store notes from real commits, release check, release PR, then the tag
|
|
3
|
+
description: Prepare a store release - version, changelog and store notes from real commits, release check, release PR, then the tag and the signed builds. Run only when the user explicitly invokes m-release.
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# m-release
|
|
8
8
|
|
|
9
|
-
|
|
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
10
|
|
|
11
|
-
|
|
11
|
+
Input: $ARGUMENTS (the new version such as 1.4.0, or patch, minor or major; which app, if the project ships several; anything the client should hear about).
|
|
12
|
+
|
|
13
|
+
1. **Start clean:** `main`, pulled, with a clean working tree. Find the last release with `git describe --tags --abbrev=0 --match 'v*'`.
|
|
14
|
+
- No tag, but the app is already in the stores: ask the user which commit was the last store release (or its date and version), and tag it locally as `v<that version>`. The changelog then starts there instead of at the first commit.
|
|
15
|
+
- No tag and never released: this is the first release.
|
|
12
16
|
2. **Choose the version.** Show the commits since the last release (`git log --oneline <last tag>..HEAD`). Suggest minor if there's anything new for users, patch for fixes only, and major only if the user asks. Get the user's confirmation, then create the branch `release/v<version>`.
|
|
13
|
-
3. **Changelog from real commits:** `npx -y git-cliff@2.14.2 --unreleased --tag v<version>
|
|
14
|
-
4. **Store and client notes** go in `release-notes/<version
|
|
17
|
+
3. **Changelog from real commits:** `npx -y git-cliff@2.14.2 --unreleased --tag v<version> -o release-notes/<version>/CHANGELOG.md`. If the repo tracks a root `CHANGELOG.md` (`git ls-files CHANGELOG.md`), also add the section there with `--prepend CHANGELOG.md`. Leave the root file alone if `.gitignore` ignores it, because another tool may own it. Don't add, merge or reword entries by hand. A misleading commit message gets fixed in the notes below, not in the changelog.
|
|
18
|
+
4. **Store and client notes** go in `release-notes/<version>/` too. Write them only from that changelog, so every line traces back to an entry. Leave out internal changes (refactors, CI, dependency bumps) unless users notice them.
|
|
15
19
|
- `play-store.txt`: plain text for users, at most 500 characters.
|
|
16
20
|
- `app-store.txt`: plain text for users, at most 4000 characters, with no `<` or `>`.
|
|
17
21
|
- `client.md`: for the client or product owner. Cover what's new, what's fixed, what they should test or do, and known issues.
|
|
18
22
|
|
|
19
23
|
Show all three files to the user and wait for their approval.
|
|
20
|
-
5. **Version
|
|
24
|
+
5. **Version and build numbers:** `sh scripts/ai/set-version.sh <version>` sets the iOS and Android version names. If the script stops because the project ships several apps, ask the user which version each app gets, and set them after they confirm.
|
|
25
|
+
- When `codemagic.yaml` sets build numbers, leave them alone.
|
|
26
|
+
- Otherwise every store upload needs a higher build number. Ask before changing native files. Then raise Android's `versionCode` in `android/app/build.gradle`, and set iOS with `cd ios && agvtool new-version -all <number>`. Never edit `project.pbxproj` by hand. iOS may keep its build number when the version name changes, if that's how the team works.
|
|
21
27
|
6. **Release check:** `node scripts/ai/release-check.js`. Show the output. Fix each ✗, asking first when the fix touches native config. List each ! for the user to decide.
|
|
22
|
-
7. **Release PR:** commit as `
|
|
23
|
-
8. **Tag after the merge.** Once the PR is merged, ask the user before tagging. Then run `git switch main && git pull && git tag v<version> && git push origin v<version>`.
|
|
28
|
+
7. **Release PR:** commit as `chore(release): <version>` (so the next changelog leaves it out), with `Assisted-by: <tool>/<model>`. Ask before pushing. Open a PR titled `Release <version>` with the changelog and the release-check output.
|
|
29
|
+
8. **Tag and build, after the merge.** Once the PR is merged, ask the user before tagging. Then run `git switch main && git pull && git tag v<version> && git push origin v<version>`.
|
|
30
|
+
- With Codemagic (`codemagic.yaml`; see `docs/ai/codemagic.md`), the tag starts the signed builds.
|
|
31
|
+
- Without CI, the user builds signed apps on their Mac, because signing keys stay with people. Tell them to run `sh scripts/ai/release-build.sh android [flavor]` and `sh scripts/ai/release-build.sh ios [scheme]`, and to upload the results from `.ai/release/` (Play Console, and Xcode's Organizer or Transporter). Never run these yourself or ask for the keys.
|
|
@@ -6,13 +6,19 @@ disable-model-invocation: true
|
|
|
6
6
|
|
|
7
7
|
# m-review
|
|
8
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
|
+
|
|
9
11
|
If your tool has subagents, hand the review to the `m-reviewer` subagent, so it looks at the code with fresh eyes. Otherwise review it yourself, read-only.
|
|
10
12
|
|
|
11
13
|
## Reviewing
|
|
12
14
|
|
|
13
15
|
1. Get the changes: `git diff main...HEAD` and `git log main..HEAD --oneline`. If there's a spec, read its `requirements.md`.
|
|
14
16
|
2. Check, in order:
|
|
15
|
-
- **
|
|
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?
|
|
16
22
|
- **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
|
|
17
23
|
- **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
|
|
18
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.
|
|
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
|
|
@@ -1,12 +1,14 @@
|
|
|
1
|
-
<!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} (edit outside these markers; the kit updates what's inside) -->
|
|
1
|
+
<!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} (edit outside these markers; the kit updates what's inside) -->
|
|
2
2
|
# {{APP_NAME}}: instructions for AI agents
|
|
3
3
|
|
|
4
4
|
Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity. Keep it short; details live in `docs/ai/`.
|
|
5
5
|
|
|
6
|
+
This project may also use other AI workflow frameworks (for example Superpowers, BMAD or proAgents). They keep working for everything else. When the user starts a task with an `m-` skill (`/m-feature`, `$m-feature`, …), follow that skill's steps for the whole task; where another framework's instructions differ, the `m-` skill wins.
|
|
7
|
+
|
|
6
8
|
## Project
|
|
7
9
|
|
|
8
10
|
- Bare React Native {{RN_VERSION}} (New Architecture), React {{REACT_VERSION}}, TypeScript {{TS_VERSION}}, Node {{NODE_VERSION}}. Package manager: {{PM}}.
|
|
9
|
-
- What the app does: `docs/ai/product.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`.
|
|
10
12
|
|
|
11
13
|
## Commands
|
|
12
14
|
|
|
@@ -18,7 +20,9 @@ Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antig
|
|
|
18
20
|
| iOS build (simulator, no signing) | `sh scripts/ai/ios-build.sh` |
|
|
19
21
|
| Android build | `cd android && ./gradlew assembleDebug` |
|
|
20
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>` |
|
|
21
24
|
| Check a release before tagging it (versions, permission texts, debug leftovers) | `node scripts/ai/release-check.js` |
|
|
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]` |
|
|
22
26
|
|
|
23
27
|
## Definition of done
|
|
24
28
|
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# Builds signed release apps on this Mac: for apps without CI, or to check a release by hand.
|
|
3
|
+
# A person runs it, because it uses the signing keys, which agents must never handle.
|
|
4
|
+
#
|
|
5
|
+
# sh scripts/ai/release-build.sh android [flavor] signed app bundle (.aab) for Google Play
|
|
6
|
+
# sh scripts/ai/release-build.sh ios [scheme] signed .ipa for App Store Connect (TestFlight)
|
|
7
|
+
#
|
|
8
|
+
# Android signs with your upload key. Set its path in your shell, never in the repo:
|
|
9
|
+
# export AMK_UPLOAD_KEYSTORE=~/keys/myapp-upload.jks AMK_UPLOAD_KEY_ALIAS=upload
|
|
10
|
+
# The passwords are asked for, unless AMK_UPLOAD_STORE_PASSWORD and AMK_UPLOAD_KEY_PASSWORD are set.
|
|
11
|
+
# Without AMK_UPLOAD_KEYSTORE it uses the app's own signing setup, and stops if that's the debug key.
|
|
12
|
+
# iOS signs with the Apple account in Xcode (Settings > Accounts) and automatic signing; Xcode may
|
|
13
|
+
# create a distribution certificate or profile in that team if one is missing.
|
|
14
|
+
# Version and build numbers come from the repo, so set them first (the m-release skill does).
|
|
15
|
+
# Output: .ai/release/
|
|
16
|
+
set -eu
|
|
17
|
+
platform=${1:-}
|
|
18
|
+
target=${2:-}
|
|
19
|
+
out=.ai/release
|
|
20
|
+
mkdir -p "$out"
|
|
21
|
+
|
|
22
|
+
# secret VAR "question": read it without echo, unless it's already set
|
|
23
|
+
secret() {
|
|
24
|
+
eval "[ -n \"\${$1:-}\" ]" && return 0
|
|
25
|
+
[ -t 0 ] || { echo "Set $1 in your shell, or run this in a terminal to be asked." >&2; exit 1; }
|
|
26
|
+
printf '%s: ' "$2" >&2; stty -echo; read -r value; stty echo; echo >&2
|
|
27
|
+
eval "$1=\$value"
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
case "$platform" in
|
|
31
|
+
android)
|
|
32
|
+
flavor=$(printf %s "$target" | awk '{ print toupper(substr($0, 1, 1)) substr($0, 2) }')
|
|
33
|
+
if [ -n "${AMK_UPLOAD_KEYSTORE:-}" ]; then
|
|
34
|
+
secret AMK_UPLOAD_STORE_PASSWORD 'Keystore password'
|
|
35
|
+
secret AMK_UPLOAD_KEY_PASSWORD 'Key password'
|
|
36
|
+
# injected signing (as Android Studio's "Generate Signed Bundle" does): build.gradle stays as it is
|
|
37
|
+
set -- -Pandroid.injected.signing.store.file="$AMK_UPLOAD_KEYSTORE" \
|
|
38
|
+
-Pandroid.injected.signing.store.password="$AMK_UPLOAD_STORE_PASSWORD" \
|
|
39
|
+
-Pandroid.injected.signing.key.alias="${AMK_UPLOAD_KEY_ALIAS:-upload}" \
|
|
40
|
+
-Pandroid.injected.signing.key.password="$AMK_UPLOAD_KEY_PASSWORD"
|
|
41
|
+
else
|
|
42
|
+
set --
|
|
43
|
+
fi
|
|
44
|
+
(cd android && ./gradlew "bundle${flavor}Release" "$@")
|
|
45
|
+
dir=android/app/build/outputs/bundle/${target:-release}${target:+Release}
|
|
46
|
+
for aab in "$dir"/*.aab; do
|
|
47
|
+
signer=$(keytool -printcert -jarfile "$aab" | sed -n 's/^Owner: //p' | head -n 1)
|
|
48
|
+
case "$signer" in
|
|
49
|
+
''|*'Android Debug'*) echo "$aab is signed with the debug key. Set AMK_UPLOAD_KEYSTORE (see the top of this script)." >&2; exit 1 ;;
|
|
50
|
+
esac
|
|
51
|
+
cp "$aab" "$out/"
|
|
52
|
+
echo "Signed by: $signer"
|
|
53
|
+
echo "$out/$(basename "$aab")"
|
|
54
|
+
done
|
|
55
|
+
;;
|
|
56
|
+
ios)
|
|
57
|
+
workspace=$(ls -d ios/*.xcworkspace | head -n 1)
|
|
58
|
+
scheme=${target:-$(basename "$workspace" .xcworkspace)}
|
|
59
|
+
[ -d ios/Pods ] || (cd ios && pod install)
|
|
60
|
+
log="$out/$scheme-ios.log"
|
|
61
|
+
echo "Archiving $scheme (several minutes; log: $log)"
|
|
62
|
+
xcodebuild -workspace "$workspace" -scheme "$scheme" -configuration Release -destination 'generic/platform=iOS' \
|
|
63
|
+
-archivePath "$out/$scheme.xcarchive" -allowProvisioningUpdates archive > "$log" 2>&1 \
|
|
64
|
+
|| { grep -E 'error:|BUILD FAILED|ARCHIVE FAILED' "$log" | head -n 20; exit 1; }
|
|
65
|
+
cat > "$out/ExportOptions.plist" <<'PLIST'
|
|
66
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
67
|
+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
68
|
+
<plist version="1.0"><dict>
|
|
69
|
+
<key>method</key><string>app-store-connect</string>
|
|
70
|
+
<key>destination</key><string>export</string>
|
|
71
|
+
<key>signingStyle</key><string>automatic</string>
|
|
72
|
+
</dict></plist>
|
|
73
|
+
PLIST
|
|
74
|
+
xcodebuild -exportArchive -archivePath "$out/$scheme.xcarchive" -exportPath "$out/$scheme" \
|
|
75
|
+
-exportOptionsPlist "$out/ExportOptions.plist" -allowProvisioningUpdates >> "$log" 2>&1 \
|
|
76
|
+
|| { grep -E 'error:|EXPORT FAILED' "$log" | head -n 20; exit 1; }
|
|
77
|
+
ipa=$(ls "$out/$scheme"/*.ipa | head -n 1)
|
|
78
|
+
# the export re-signs for distribution, so check the app inside the .ipa, not the archive
|
|
79
|
+
unzip -oq "$ipa" -d "$out/$scheme/unzipped"
|
|
80
|
+
echo "Signed by: $(codesign -dvv "$out/$scheme/unzipped"/Payload/*.app 2>&1 | sed -n 's/^Authority=//p' | head -n 1)"
|
|
81
|
+
echo "$ipa"
|
|
82
|
+
;;
|
|
83
|
+
*)
|
|
84
|
+
sed -n '2,16p' "$0"
|
|
85
|
+
exit 1
|
|
86
|
+
;;
|
|
87
|
+
esac
|
|
@@ -49,7 +49,7 @@ const iosBuilds = t => all(/CURRENT_PROJECT_VERSION = ([^;]+);/g, t);
|
|
|
49
49
|
const androidVersions = t => all(/versionName\s*=?\s*"([^"]+)"/g, stripComments(t));
|
|
50
50
|
const androidBuilds = t => all(/versionCode\s*=?\s*(\d+)/g, stripComments(t));
|
|
51
51
|
|
|
52
|
-
function compare(platform, now, before, kind) {
|
|
52
|
+
function compare(platform, now, before, kind, versionChanged) {
|
|
53
53
|
if (kind === 'build number' && ciBuildNumber[platform]) { info(`${platform} build number: set by Codemagic at build time`); return; }
|
|
54
54
|
if (!now.length) { warn(`${platform} ${kind}: couldn't read it`, 'check it by hand before you ship'); return; }
|
|
55
55
|
if (!before) { info(`${platform} ${kind}: ${now.join(', ')}`); return; }
|
|
@@ -57,6 +57,9 @@ function compare(platform, now, before, kind) {
|
|
|
57
57
|
if (kind === 'build number' && before.length && maxNum(now) < maxNum(before)) {
|
|
58
58
|
fail(`${platform} build number went down (${before.join(', ')} → ${now.join(', ')})`, 'stores reject a build number lower than the last upload');
|
|
59
59
|
} else ok(`${platform} ${kind}`, `${before.join(', ') || '?'} → ${now.join(', ')}`);
|
|
60
|
+
} else if (kind === 'build number' && platform === 'iOS' && versionChanged) {
|
|
61
|
+
// the App Store needs a new build number only within a version, so 1 again for a new version is fine
|
|
62
|
+
ok(`${platform} build number (${now.join(', ')} again, for a new version)`);
|
|
60
63
|
} else if (kind === 'build number') {
|
|
61
64
|
warn(`${platform} build number unchanged since ${since} (${now.join(', ')})`, 'bump it, unless your CI sets it (for example Codemagic); stores reject a repeated build number');
|
|
62
65
|
} else {
|
|
@@ -66,8 +69,9 @@ function compare(platform, now, before, kind) {
|
|
|
66
69
|
|
|
67
70
|
if (!since) info('No previous release found (no git tag)', 'tag each release, e.g. v1.4.0, or pass --since <ref>, so the next check can compare');
|
|
68
71
|
if (pbx) {
|
|
69
|
-
|
|
70
|
-
compare('iOS',
|
|
72
|
+
const [now, before] = [iosVersions(pbx), since && iosVersions(readAt(since, pbxPath))];
|
|
73
|
+
compare('iOS', now, before, 'version');
|
|
74
|
+
compare('iOS', iosBuilds(pbx), since && iosBuilds(readAt(since, pbxPath)), 'build number', before && now.join() !== before.join());
|
|
71
75
|
}
|
|
72
76
|
if (gradle) {
|
|
73
77
|
compare('Android', androidVersions(gradle), since && androidVersions(readAt(since, gradlePath)), 'version');
|
|
@@ -76,7 +80,7 @@ if (gradle) {
|
|
|
76
80
|
if (pbx && gradle) {
|
|
77
81
|
const a = iosVersions(pbx), b = androidVersions(gradle);
|
|
78
82
|
if (a.length && b.length && !a.some(v => b.includes(v))) {
|
|
79
|
-
|
|
83
|
+
info(`iOS shows version ${a.join(', ')}, Android shows ${b.join(', ')}`, 'users and support see different numbers; fine if your team numbers the platforms separately');
|
|
80
84
|
}
|
|
81
85
|
}
|
|
82
86
|
|
|
@@ -168,7 +172,8 @@ const releaseBlock = block(block(gradle, 'buildTypes'), 'release');
|
|
|
168
172
|
if (/debuggable\s*=?\s*true/.test(releaseBlock)) fail('Android release build is debuggable', 'remove "debuggable true" from buildTypes.release; Play rejects debuggable apps');
|
|
169
173
|
if (/android\.injected\.signing/.test(codemagic)) ok('Android release signing', 'Codemagic signs with the upload key');
|
|
170
174
|
else if (/signingConfig\s*=?\s*signingConfigs\.debug/.test(releaseBlock)) {
|
|
171
|
-
|
|
175
|
+
// the kit's release-build.sh (and Codemagic) sign with the upload key, and Play rejects debug-signed uploads anyway
|
|
176
|
+
info('build.gradle signs release builds with the debug key', 'build store releases with sh scripts/ai/release-build.sh android, which signs with your upload key');
|
|
172
177
|
}
|
|
173
178
|
if (/android:usesCleartextTraffic="true"/.test(readNow(manifestPath) || '')) {
|
|
174
179
|
warn('Android allows cleartext (HTTP) traffic', 'allow only the domains that need it (network security config)');
|
|
@@ -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
|
-
#
|
|
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
|
-
#
|
|
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
|
-
##
|
|
10
|
+
## ADDED Requirements: <area>
|
|
10
11
|
|
|
11
|
-
<!--
|
|
12
|
-
|
|
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,
|
|
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
|
|
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.
|