agentic-mobile-kit 0.7.17 → 0.7.19
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 +3 -3
- package/bin/cli.js +1 -1
- package/lib/init.js +62 -10
- package/package.json +1 -1
- package/stacks/react-native/expo/.rulesync/permissions.jsonc +6 -0
- package/stacks/react-native/expo/AGENTS.md +7 -3
- package/stacks/react-native/expo/docs/amk/expo.md +11 -0
- package/stacks/react-native/template/.agents/skills/m-bugfix/SKILL.md +10 -11
- package/stacks/react-native/template/.agents/skills/m-continue/SKILL.md +1 -1
- package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +1 -1
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +16 -11
- package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +8 -5
- package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +5 -5
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +5 -2
- package/stacks/react-native/template/.github/pull_request_template.md +3 -1
- package/stacks/react-native/template/.github/workflows/e2e.yml +3 -0
- package/stacks/react-native/template/.rulesync/permissions.jsonc +6 -0
- package/stacks/react-native/template/.rulesync/subagents/m-design-reviewer.md +22 -0
- package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -2
- package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +1 -1
- package/stacks/react-native/template/AGENTS.md +7 -3
- package/stacks/react-native/template/docs/amk/design-system.md +15 -0
- package/stacks/react-native/template/docs/amk/glossary.md +12 -0
- package/stacks/react-native/template/docs/amk/react-native.md +11 -0
- package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
- package/stacks/react-native/template/scripts/amk/guard.js +22 -1
- package/stacks/react-native/template/scripts/amk/report.js +78 -0
- package/stacks/react-native/template/scripts/amk/rn-check.js +155 -17
- package/stacks/react-native/template/scripts/amk/verify.sh +134 -15
- package/stacks/react-native/template/specs/_templates/design.md +16 -0
- package/stacks/react-native/template/specs/_templates/flow.yaml +11 -0
- package/stacks/react-native/template/specs/_templates/questions.md +29 -0
- package/stacks/react-native/template/specs/_templates/subflow.yaml +36 -0
- package/stacks/react-native/template/specs/_templates/tasks.md +2 -2
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, O
|
|
|
18
18
|
|
|
19
19
|
2. Run it again and choose **Check this project and machine**. It lists each problem with its fix.
|
|
20
20
|
|
|
21
|
-
3. In your AI tool, run `m-onboard`. It reads the project, drafts `docs/amk/product.md`, `tech.md`, `structure.md` and `
|
|
21
|
+
3. In your AI tool, run `m-onboard`. It reads the project, drafts `docs/amk/product.md`, `tech.md`, `structure.md`, `conventions.md`, `glossary.md` and `design-system.md`, asks what the code can't show, and writes them once you approve. Then commit and open a PR.
|
|
22
22
|
|
|
23
23
|
Each choice prints the command it runs, for scripts and CI: `init` (with `--ci github`, `--ci codemagic` or `--tools claude,codex,antigravity`, and `--new bare` or `--new expo` to create the app first), `sync`, `doctor` and `uninstall`. `--help` lists every option.
|
|
24
24
|
|
|
@@ -28,12 +28,12 @@ Each choice prints the command it runs, for scripts and CI: `init` (with `--ci g
|
|
|
28
28
|
|
|
29
29
|
| You want to | Run | What happens |
|
|
30
30
|
|---|---|---|
|
|
31
|
-
| Describe the app for agents | `m-onboard` | Reads the whole project, drafts the product, tech, structure and
|
|
31
|
+
| Describe the app for agents | `m-onboard` | Reads the whole project, drafts the product, tech, structure, conventions, glossary and design-system files in `docs/amk/`, asks what the code can't show, and writes them once you approve. Run it after installing, and again after big changes. |
|
|
32
32
|
| Think a problem through | `m-explore` | The agent reads the code, explains how it works today and lays out options with trade-offs. It never edits code. |
|
|
33
33
|
| Agree on an idea before building it | `m-prototype` | Concepts as clickable HTML mocks when how it should work is still open, then real screens with mock data on a throwaway branch, with screenshots and a video for the demo. The agreed requirements go to `m-feature` |
|
|
34
34
|
| Build a feature | `m-feature` | Requirements → you approve → design and tasks → you approve → one task at a time with tests → device checks with screenshots → living spec updated → review → PR |
|
|
35
35
|
| Make a small change | `m-change` | Checks it's small, then shows the code, living-spec and docs changes for one approval, makes them together and runs the checks |
|
|
36
|
-
| Fix a bug | `m-bugfix` |
|
|
36
|
+
| Fix a bug | `m-bugfix` | Makes the bug fail on demand (a test, or a Maestro flow on the device), lists the likely causes, finds the root cause, then makes the smallest fix |
|
|
37
37
|
| Stop, or switch tool or machine | `m-pause` | Writes a handoff in the spec, commits and pushes |
|
|
38
38
|
| Carry on anywhere | `m-continue` | Reads the spec and handoff, then picks up at the next step |
|
|
39
39
|
| Review a branch | `m-review` | Checks the work against the spec (complete, correct, coherent) and covers both platforms, error states, security and native changes |
|
package/bin/cli.js
CHANGED
|
@@ -50,7 +50,7 @@ function main([cmd, ...rest]) {
|
|
|
50
50
|
printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
|
|
51
51
|
});
|
|
52
52
|
} else if (cmd === 'sync') {
|
|
53
|
-
run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
|
|
53
|
+
run('sync', () => { if (printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') }))) process.exitCode = 1; });
|
|
54
54
|
} else if (cmd === 'uninstall') {
|
|
55
55
|
run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
|
|
56
56
|
} else if (cmd === 'doctor') {
|
package/lib/init.js
CHANGED
|
@@ -15,7 +15,7 @@ const MARKERS = /<!-- KIT:START[\s\S]*?<!-- KIT:END[^>]*-->\n?/;
|
|
|
15
15
|
// files with {{PLACEHOLDERS}} filled in from the project (the last three say what the CI chosen does, or that none does)
|
|
16
16
|
const FILLED = ['AGENTS.md', 'codemagic.yaml', 'scripts/amk/set-version.sh', 'docs/amk/team-process.md', '.githooks/pre-commit'];
|
|
17
17
|
// docs each team rewrites for its app: sync replaces them only while they're untouched, and never merges into them
|
|
18
|
-
const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions'].map(n => `docs/amk/${n}.md`);
|
|
18
|
+
const PROJECT_DOCS = ['product', 'tech', 'structure', 'conventions', 'glossary', 'design-system'].map(n => `docs/amk/${n}.md`);
|
|
19
19
|
const HOOKS_CMD = 'git config core.hooksPath .githooks || true';
|
|
20
20
|
// the app's own ESLint skips the kit's scripts: they follow the kit's style, not each app's rules
|
|
21
21
|
const ESLINT_IGNORE = 'scripts/amk/';
|
|
@@ -470,6 +470,34 @@ function merge3(current, base, kitNew, from) {
|
|
|
470
470
|
return { text: r.stdout, conflicts: r.status };
|
|
471
471
|
}
|
|
472
472
|
|
|
473
|
+
// AGENTS.md's kit section as the team left it, merged with the kit's new one: a team's edit inside it (the screens it
|
|
474
|
+
// builds for, say) stays. A line the kit fills in with what it finds (the versions, the package manager, the app's
|
|
475
|
+
// checks) is the kit's, whatever it says now: there the old version's line, filled in today, stands in for the team's.
|
|
476
|
+
// The screens are a team's decision, so a line with them counts as an edit. The marker lines are the kit's
|
|
477
|
+
function mergeSection(mine, rawOld, kitOld, kitNew, from) {
|
|
478
|
+
const lines = s => s.replace(/\n$/, '').split('\n');
|
|
479
|
+
const [raw, base, theirs] = [rawOld, kitOld, kitNew].map(lines);
|
|
480
|
+
const found = raw.length !== base.length ? [] : raw.map((l, i) => /\{\{\w+\}\}/.test(l) && !l.includes('{{SCREENS}}')
|
|
481
|
+
&& [new RegExp(`^${l.split(/\{\{\w+\}\}/).map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`), base[i]]).filter(Boolean);
|
|
482
|
+
const ours = lines(mine).map(l => (base.includes(l) ? l : (found.find(([re]) => re.test(l)) || [null, l])[1]));
|
|
483
|
+
const inner = a => `${a.slice(1, -1).join('\n')}\n`;
|
|
484
|
+
const { text, conflicts } = merge3(inner(ours), inner(base), inner(theirs), from);
|
|
485
|
+
return { text: !conflicts && text === inner(theirs) ? kitNew : `${theirs[0]}\n${text}${theirs[theirs.length - 1]}\n`, conflicts };
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
// whether a merged script still parses (two edits can merge cleanly into one that doesn't): sh -n for shell scripts
|
|
489
|
+
// and git hooks, node --check for JavaScript. Without sh on the PATH (Windows without Git's), shell isn't checked
|
|
490
|
+
function parses(rel, text) {
|
|
491
|
+
const shell = rel.endsWith('.sh') || rel.startsWith('.githooks/');
|
|
492
|
+
if (!shell && !/\.[cm]?js$/.test(rel)) return true;
|
|
493
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-parse-'));
|
|
494
|
+
const file = path.join(dir, path.basename(rel));
|
|
495
|
+
fs.writeFileSync(file, text);
|
|
496
|
+
const r = spawnSync(shell ? 'sh' : process.execPath, [shell ? '-n' : '--check', file], { encoding: 'utf8' });
|
|
497
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
498
|
+
return Boolean(r.error) || r.status === 0;
|
|
499
|
+
}
|
|
500
|
+
|
|
473
501
|
// Git hook managers a project may already use. The kit's hooks then run from theirs and core.hooksPath stays theirs:
|
|
474
502
|
// two tools setting it undo each other on every install (husky's prepare script runs after the kit's postinstall).
|
|
475
503
|
const KIT_HOOKS = ['pre-commit', 'pre-push'];
|
|
@@ -489,7 +517,10 @@ const forwarder = h => `#!/bin/sh\n${FORWARD} .git/hooks/${h}, which core.hooksP
|
|
|
489
517
|
const localHooksPath = cwd => {
|
|
490
518
|
let v = '';
|
|
491
519
|
try { v = git(cwd, 'config', '--local', 'core.hooksPath'); } catch {}
|
|
492
|
-
|
|
520
|
+
v = v && path.posix.normalize(v.replace(/\\/g, '/')).replace(/\/+$/, '');
|
|
521
|
+
// the project's own .githooks as a full path (git config core.hooksPath "$PWD/.githooks") is the kit's folder too
|
|
522
|
+
const real = p => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
|
|
523
|
+
return v && path.isAbsolute(v) && real(v) === real(path.join(cwd, '.githooks')) ? '.githooks' : v;
|
|
493
524
|
};
|
|
494
525
|
|
|
495
526
|
function hookManager(cwd, pkg) {
|
|
@@ -662,10 +693,11 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
|
|
|
662
693
|
const gi = path.join(cwd, '.gitignore');
|
|
663
694
|
const giText = readIf(gi) || '';
|
|
664
695
|
// Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
|
|
665
|
-
|
|
696
|
+
// .maestro/.amk-*: the copies of flows with view-tree steps that verify.sh runs on Android, there only while they run
|
|
697
|
+
const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', '.maestro/.amk-*', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
|
|
666
698
|
const missing = ignored.filter(l => !giText.split('\n').includes(l));
|
|
667
699
|
if (missing.length) {
|
|
668
|
-
fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs)${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
|
|
700
|
+
fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs), .maestro/.amk-* the flows verify.sh is running${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
|
|
669
701
|
done.merged.push('.gitignore');
|
|
670
702
|
}
|
|
671
703
|
|
|
@@ -834,7 +866,7 @@ function sync(cwd, opts = {}) {
|
|
|
834
866
|
const oldValues = { ...values, ...ciTexts(hadCi) };
|
|
835
867
|
const tools = installedTools(cwd);
|
|
836
868
|
const targets = tools.flatMap(t => TOOLS[t]);
|
|
837
|
-
const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
|
|
869
|
+
const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], byHand: [], removed: [], kept: [] };
|
|
838
870
|
const newFiles = stackFiles(opts.template || TEMPLATE, stack, deps);
|
|
839
871
|
// an install from before 0.7.0: the kit's files move to the new folders first, so the team's edits come along.
|
|
840
872
|
// Other files in the old folders may be the app's own, so they stay where they are.
|
|
@@ -862,8 +894,14 @@ function sync(cwd, opts = {}) {
|
|
|
862
894
|
const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldFiles.get(rel), rel, oldValues, targets) : null;
|
|
863
895
|
const current = projectText(cwd, rel, targets);
|
|
864
896
|
if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
|
|
865
|
-
|
|
866
|
-
|
|
897
|
+
// the team's edits inside the kit's section stay, merged like any file's
|
|
898
|
+
const mine = rel === 'AGENTS.md' && exact && kitOld !== null && current !== null && (current.match(MARKERS) || [])[0];
|
|
899
|
+
const { text: section, conflicts } = mine ? mergeSection(mine, fs.readFileSync(oldFiles.get(rel), 'utf8'), kitOld, kitNew, from) : { text: kitNew, conflicts: 0 };
|
|
900
|
+
const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, section) : mergeClaude(current);
|
|
901
|
+
if (next === current) continue;
|
|
902
|
+
fs.writeFileSync(path.join(cwd, rel), next);
|
|
903
|
+
if (section === kitNew) report.updated.push(rel);
|
|
904
|
+
else (conflicts ? report.conflicts : report.merged).push(`${rel} (your edits inside the kit's section)`);
|
|
867
905
|
continue;
|
|
868
906
|
}
|
|
869
907
|
if (current === null) {
|
|
@@ -879,6 +917,14 @@ function sync(cwd, opts = {}) {
|
|
|
879
917
|
if (kitOld === kitNew || PROJECT_DOCS.includes(rel)) continue;
|
|
880
918
|
// without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
|
|
881
919
|
const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
|
|
920
|
+
// markers, or a merge that no longer parses, would stop a script, a hook, a workflow or a config from working (and
|
|
921
|
+
// every check with it): those get the kit's version, and the team's goes beside it to bring its changes back
|
|
922
|
+
if (!rel.endsWith('.md') && (conflicts || !parses(rel, text))) {
|
|
923
|
+
fs.copyFileSync(path.join(cwd, rel), path.join(cwd, `${rel}.mine`));
|
|
924
|
+
writeKitFile(cwd, rel, kitNew);
|
|
925
|
+
report.byHand.push(rel);
|
|
926
|
+
continue;
|
|
927
|
+
}
|
|
882
928
|
writeKitFile(cwd, rel, text);
|
|
883
929
|
(conflicts ? report.conflicts : report.merged).push(rel);
|
|
884
930
|
}
|
|
@@ -1000,7 +1046,7 @@ function printSummary({ report, warnings = [], values, tools, ci, generated, gen
|
|
|
1000
1046
|
for (const w of warnings) log(` ! ${w}`);
|
|
1001
1047
|
if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
|
|
1002
1048
|
log('\nNext steps:');
|
|
1003
|
-
log(' 1. In your AI tool, run m-onboard (/m-onboard, or $m-onboard in Codex). It drafts docs/amk/product.md, tech.md,\n structure.md and
|
|
1049
|
+
log(' 1. In your AI tool, run m-onboard (/m-onboard, or $m-onboard in Codex). It drafts docs/amk/product.md, tech.md,\n structure.md, conventions.md, glossary.md and design-system.md from the code, asks what the code can\'t show, and writes them once you approve.');
|
|
1004
1050
|
log(' 2. Commit on a branch and open a PR. Add the "large-pr" label (the vendored skills are large).');
|
|
1005
1051
|
const more = [
|
|
1006
1052
|
ci.includes('github') && 'Turn on branch protection for main: see docs/branch-protection.md in the kit repo.',
|
|
@@ -1014,13 +1060,19 @@ function printSync({ report, warnings = [], from, to, changed, generated, genera
|
|
|
1014
1060
|
log(from === to ? `agentic-mobile-kit is already ${to}.` : `agentic-mobile-kit updated from ${from} to ${to}.`);
|
|
1015
1061
|
const lines = [
|
|
1016
1062
|
['moved to the new folders', report.moved || []], ['updated', report.updated], ['added', report.added], ['removed', report.removed],
|
|
1017
|
-
['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts],
|
|
1063
|
+
['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts],
|
|
1064
|
+
['CONFLICTS where markers would stop the file from working, so the kit\'s version is in place: bring your changes back from <file>.mine, then delete it', report.byHand || []],
|
|
1065
|
+
['left alone', report.kept],
|
|
1018
1066
|
];
|
|
1019
1067
|
for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
|
|
1020
1068
|
if (!changed) log(' Nothing changed.');
|
|
1021
1069
|
for (const w of warnings) log(` ! ${w}`);
|
|
1022
1070
|
if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
|
|
1023
|
-
|
|
1071
|
+
// a conflict left is an update not finished: said last, and the command fails
|
|
1072
|
+
const open = report.conflicts.length + (report.byHand || []).length;
|
|
1073
|
+
if (open) log(`\nsync isn't finished: ${open === 1 ? 'a conflict' : `${open} conflicts`} to resolve (above). Then run the checks, and commit.`);
|
|
1074
|
+
else if (changed) log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
|
|
1075
|
+
return open;
|
|
1024
1076
|
}
|
|
1025
1077
|
|
|
1026
1078
|
function printUninstall({ report }, log = console.log) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-mobile-kit",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.19",
|
|
4
4
|
"description": "One setup for AI-assisted development of React Native apps, bare or Expo: shared rules and workflows for Claude Code, Codex and Antigravity, git hooks, device checks with screenshots, and release tooling for the App Store and Google Play.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "prakashpro1",
|
|
@@ -9,6 +9,12 @@
|
|
|
9
9
|
"git push --force*": "deny",
|
|
10
10
|
"git push -f*": "deny",
|
|
11
11
|
"git clean -f*": "deny",
|
|
12
|
+
"git checkout .": "deny",
|
|
13
|
+
"git checkout -- .": "deny",
|
|
14
|
+
"git restore .": "deny",
|
|
15
|
+
"git stash drop*": "deny",
|
|
16
|
+
"git stash clear*": "deny",
|
|
17
|
+
"git branch -D*": "deny",
|
|
12
18
|
"git commit --no-verify*": "deny",
|
|
13
19
|
"xcrun simctl erase*": "deny",
|
|
14
20
|
"npm install *": "ask",
|
|
@@ -11,6 +11,8 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
11
11
|
- `ios/` and `android/` are generated by `npx expo prebuild` and aren't in git (Continuous Native Generation). The kit's scripts generate them when they need them.
|
|
12
12
|
- Screens: {{SCREENS}}. Build every screen for each of them (`docs/amk/expo.md`, Tablets and landscape); `verify.sh` checks each one.
|
|
13
13
|
- What the app does: `docs/amk/product.md`, and requirement by requirement, as it works now: `specs/current/`. Stack and services: `docs/amk/tech.md`. Folders and layers: `docs/amk/structure.md`. Code style: `docs/amk/conventions.md`.
|
|
14
|
+
- The app's own words, to use in names, specs and messages: `docs/amk/glossary.md`.
|
|
15
|
+
- How the app looks, which new screens follow (colours, type, spacing, controls): `docs/amk/design-system.md`.
|
|
14
16
|
|
|
15
17
|
## Commands
|
|
16
18
|
|
|
@@ -20,9 +22,9 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
20
22
|
| Add a library (ask first) | `npx expo install <package>`: the version that matches the SDK |
|
|
21
23
|
| Lint, typecheck, test (each skips what the app doesn't have yet) | `sh scripts/amk/pm-run.sh lint`, `sh scripts/amk/pm-run.sh typecheck`, `sh scripts/amk/pm-run.sh test` |
|
|
22
24
|
| Check dependency versions and the app config | `npx expo install --check`, `npx expo-doctor` |
|
|
23
|
-
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
25
|
+
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); only the flows tagged smoke: `--tags smoke`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
24
26
|
| Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` says how many this machine's memory fits, and prints the commands: one per device (in rounds when they don't all fit; a device's flows in parts when there's room), each for an `m-device-checker` subagent |
|
|
25
|
-
| React Native mistakes in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
27
|
+
| React Native mistakes and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
26
28
|
| Specs: progress, format check, fold a finished feature into the living spec | `node scripts/amk/specs.js status`, `node scripts/amk/specs.js check`, `node scripts/amk/specs.js merge <id>` |
|
|
27
29
|
| Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
|
|
28
30
|
| Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android`, `sh scripts/amk/release-build.sh ios` |
|
|
@@ -40,11 +42,13 @@ Never say a check passed unless you ran it in this session.
|
|
|
40
42
|
## Rules
|
|
41
43
|
|
|
42
44
|
- Stay inside the task. Ask before touching unrelated files.
|
|
45
|
+
- Ask the user in rounds: every question you can ask now (its answer doesn't wait on another open question), numbered, each with the answer you recommend and worded so "yes" takes it. A "yes" answers that round and nothing more: an approval is asked for on its own. The answers can open the next round. Look facts up in the code yourself; ask only for decisions. A question only someone else can answer (the client, a designer, the backend team) goes into `specs/<id>/questions-<who>.md`, from `specs/_templates/questions.md`, for the user to send; go on with the rest.
|
|
46
|
+
- Before designing a feature's screens, ask the user which UI/UX level they want: Simple (the default), Mixed or Premium (`specs/_templates/design.md` describes each). Build them to it.
|
|
43
47
|
- Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `app.json`, `app.config.*`, `eas.json` or `.github/workflows/`.
|
|
44
48
|
- Never edit `ios/` or `android/`: the next prebuild overwrites them. Native settings go in `app.json` or `app.config.*`, through config plugins; native code goes in an Expo module (`expo-module` skill). Ask before adding a config plugin.
|
|
45
49
|
- Never run `eas build`, `eas submit` or `eas update`: they build, ship or publish with the team's accounts, so a person runs them.
|
|
46
50
|
- Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
|
|
47
|
-
- Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf
|
|
51
|
+
- Never use `git commit --no-verify`, `git push --force`, `git reset --hard` or `rm -rf`, and never throw away work that can't be brought back (uncommitted changes with `git checkout .` or `git restore .`, stashes with `git stash drop` or `clear`, unmerged commits with `git branch -D`): ask first. To undo your own edit to a file, `git checkout -- <that file>`.
|
|
48
52
|
- When `rn-check` (in `verify.sh quick`) reports a problem (✗), show it to the user and let them choose, for each one: fix it, or keep the line with `// amk-ok <today's date>: <their reason>`. Never add an `amk-ok` on your own. One kept over two weeks ago comes back when its file changes again: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
|
|
49
53
|
- After 2 failed attempts at the same fix, stop and report what you found.
|
|
50
54
|
- Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
|
|
@@ -28,6 +28,11 @@ Rules for things AI agents commonly get wrong in Expo apps. Each one comes from
|
|
|
28
28
|
- Android draws edge to edge (Android 15 and later), so handle top and bottom insets on every screen.
|
|
29
29
|
- For apps targeting Android 16 (API 36), `onBackPressed` is no longer called. Handle back with `BackHandler` in JS.
|
|
30
30
|
- With the keyboard open, the field being typed in and the button that submits the form stay visible and tappable, on both platforms.
|
|
31
|
+
- New screens use the app's design system (`docs/amk/design-system.md`): its colours, type sizes, spacing, radius and shared controls. Something it doesn't have (a colour, a component) goes into it and the theme first, not into one screen.
|
|
32
|
+
- Every field has a visible label; a placeholder only shows the format (`DD/MM/YYYY`), never the label, which disappears once the user types.
|
|
33
|
+
- The keyboard and autofill fit the field: `keyboardType` (`email-address`, `number-pad`, `phone-pad`), `autoComplete` (`email`, `password`, `one-time-code`, `postal-code`, …) and on iOS `textContentType`, `autoCapitalize="none"` for emails and codes, `secureTextEntry` for passwords, and `returnKeyType` with `onSubmitEditing` going to the next field.
|
|
34
|
+
- A field is checked when the user leaves it, then as they type; its error shows under it and says what to do. The submit button is disabled only while the request runs.
|
|
35
|
+
- A button that starts a request shows it's working without changing size, ignores a second tap until the request ends, then shows the result or the error: never a success message when nothing was saved. A destructive action asks first, or can be undone.
|
|
31
36
|
- Lists that grow with the user's data scroll (`FlatList`, or the list component the app already uses), and so does any screen taller than a small phone.
|
|
32
37
|
- At the largest system text size, text wraps instead of being cut off: no fixed heights on views that hold text. Don't turn off font scaling (`allowFontScaling={false}`) to make a layout fit.
|
|
33
38
|
- Messages that appear after an action, such as a form error, are read out by screen readers. On Android, show the message in a view with `accessibilityLiveRegion="polite"`: Android 16 deprecated announcements. On iOS, announce it with `AccessibilityInfo.announceForAccessibility`.
|
|
@@ -71,6 +76,10 @@ These changed after most AI training data was written: check them instead of wri
|
|
|
71
76
|
- List keys come from the item's ID, not its index: index keys mix up rows when items are added, removed or reordered.
|
|
72
77
|
- Images go in asset files, never in code as base64 strings: they bloat the bundle, and all of it loads with the JavaScript.
|
|
73
78
|
- Component tests use React Native Testing Library (`@testing-library/react-native`) and find elements as users and screen readers do, by role, label or text (`getByRole('button', { name: 'Save' })`), rather than relying on snapshots.
|
|
79
|
+
- A test checks what a user or a caller sees, through the public interface (rendered text and roles, a hook's result, a function's return), so a refactor that keeps the behavior keeps the test passing.
|
|
80
|
+
- Mock only what the app doesn't own: the network, storage, native modules, time and randomness. Not the app's own components, hooks or modules: a test of mocks passes whatever the code does.
|
|
81
|
+
- Expected values come from the spec or a worked example (`expect(total([10, 5])).toBe(15)`), never computed the way the code computes them, or the test can't fail.
|
|
82
|
+
- A bug fix comes with a test that failed before the fix.
|
|
74
83
|
|
|
75
84
|
## Platform guidelines and accessibility
|
|
76
85
|
|
|
@@ -86,6 +95,8 @@ From Apple's Human Interface Guidelines, Android's design and app quality guidel
|
|
|
86
95
|
- Use the native controls (`@react-native-community/datetimepicker`, `Alert.alert` with verb buttons and `style: 'destructive'` and `'cancel'`, `Switch`); a custom one gets the same role, state and size.
|
|
87
96
|
- Dark mode: `userInterfaceStyle: "automatic"` in `app.json` (Android also needs `expo-system-ui`), and colors from the theme's light and dark values (`useColorScheme()`), not hex values in components; don't lock the app to light.
|
|
88
97
|
- Data screens have loading, empty (why, and what to do next), error (what failed, with Retry) and content states. A message the user has to read doesn't vanish on a timer, and screen readers announce it.
|
|
98
|
+
- Nothing on a screen is invented: texts, numbers, ratings, reviews, user counts and images come from the spec, the app's data or the client. Where one is missing, a placeholder the PR lists (and `specs/<id>/questions-<who>.md` asks for), never a made-up figure, quote or rating. Brand colours, fonts and logos come from the project or the client, never from memory. A prototype's mock data stays in its mock-data file.
|
|
99
|
+
- Texts say what things do, in the app's words (`docs/amk/glossary.md`), not marketing filler (seamless, effortless, unlock your potential); icons come from the app's icon set, not emoji.
|
|
89
100
|
- Reduce Motion: with it on, nothing loops or moves for decoration. Don't pass `ReduceMotion.Never` to Reanimated for decoration; with `Animated` or Lottie, read `AccessibilityInfo.isReduceMotionEnabled()` and the `reduceMotionChanged` event, and fade or stop instead.
|
|
90
101
|
- iOS 26: use native headers and tab bars (Expo Router's `Stack` and native tabs), which iOS draws in its current style; don't draw imitation glass behind content, or opt out with `UIDesignRequiresCompatibility` (builds with the iOS 27 SDK ignore it). Nothing the user needs sits under a floating tab bar, button or footer: scroll content gets bottom padding for it.
|
|
91
102
|
- Haptics only for success, error or a selection, never as the only feedback, with `expo-haptics`; not `Vibration.vibrate`.
|
|
@@ -11,15 +11,14 @@ The user chose this workflow: follow its steps for this task, even where other w
|
|
|
11
11
|
Input: $ARGUMENTS (what's wrong, steps to reproduce, error text, screenshots, task link).
|
|
12
12
|
|
|
13
13
|
1. **Check `docs/amk/known-issues.md`** for a matching error. If there is one, apply its fix and verify.
|
|
14
|
-
2. **
|
|
15
|
-
3. **
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
- Form one hypothesis, test it, and confirm or reject it. One at a time.
|
|
14
|
+
2. **Make it fail on demand.** Before looking for the cause, build one check that shows the bug and that you can run again: a failing Jest test where the logic can be tested; for a bug that shows on the device, a Maestro flow in `.maestro/` (from `specs/_templates/flow.yaml`) that goes where the user did and asserts what should be there, run with `sh scripts/amk/verify.sh ios --flow <path>` or `android`. Run it and show that it fails the way the user described, not with some other error. If you can't make it fail, say what you tried and ask for what would help (the exact steps, a screen recording, logs, the device and OS version). Don't guess.
|
|
15
|
+
3. **Find the root cause before changing code.**
|
|
16
|
+
- Read the full error and stack trace, and trace the data back to where it goes wrong.
|
|
17
|
+
- List three to five possible causes, most likely first, each with what it predicts ("if X is the cause, then changing Y fixes it"). Show the list to the user, who may know which one it is.
|
|
18
|
+
- Test them in that order, one change at a time. Tag every log you add while debugging with `[amk-debug]`, and remove them all before committing: `git grep amk-debug` finds them.
|
|
20
19
|
- Fix the cause, not the symptom: no try/catch that hides the error, no special case for the failing input.
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
20
|
+
4. **Make the smallest fix.** Don't refactor or touch unrelated code.
|
|
21
|
+
5. **Verify.** The check from step 2 passes now, and stays in the project so the bug can't come back unnoticed. Lint, typecheck and all tests pass too. Paste the output. For UI or native bugs, run `sh scripts/amk/verify.sh ios` and/or `android` and look at the screenshots; `--screens` limits it to the screens the bug is on (for example `--screens tablet-landscape`).
|
|
22
|
+
6. **Two attempts at most.** If two fixes didn't work, stop. Report what you tried, what you learned and what you suspect next.
|
|
23
|
+
7. **Record it.** If this kind of error could come back, add an entry to `docs/amk/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/amk/specs.js check`.
|
|
24
|
+
8. **Commit** with a message that names the cause you confirmed, so the next person debugging learns from it. Ask the user before pushing, then open a PR with the evidence.
|
|
@@ -21,4 +21,4 @@ Input: $ARGUMENTS (a spec ID, or empty).
|
|
|
21
21
|
3. the exact next step.
|
|
22
22
|
|
|
23
23
|
Use only what the files and git say. If something isn't recorded, say it's unknown. Never fill gaps with guesses.
|
|
24
|
-
5. **Wait for the user to confirm**, then continue with the next unchecked task, following step 4 of `m-feature` (one task at a time, real check output, commit, update `progress.md`).
|
|
24
|
+
5. **Wait for the user to confirm**, then continue with the next unchecked task (one with `after:` only once those tasks are ticked; one without, in list order), following step 4 of `m-feature` (one task at a time, real check output, commit, update `progress.md`).
|
|
@@ -14,5 +14,5 @@ Input: $ARGUMENTS (a problem, a question about how something works, or an idea t
|
|
|
14
14
|
2. **Explain what's there today:** the screens, state, API calls and native parts involved, and where iOS and Android differ.
|
|
15
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
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/amk/decisions.md`.
|
|
17
|
-
5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document. Then offer to commit those files on their own, so the next feature's branch starts from them instead of carrying them along uncommitted.
|
|
17
|
+
5. **Confirm what's final, and write it down in one place.** When the exploration settled or changed what the app must do, ask the user whether these requirements are now final; don't assume it. Once they say yes, write them where the next workflow reads them, and tell the user the path: for the whole app, every feature with its rules in `docs/amk/product.md`, each marked planned until `m-feature` ships it; for one feature, a draft in `specs/<id>/requirements.md`. A word the exploration settled (what the app calls a thing) goes into `docs/amk/glossary.md`. `decisions.md` logs choices and their reasons; it isn't the requirements document. Then offer to commit those files on their own, so the next feature's branch starts from them instead of carrying them along uncommitted.
|
|
18
18
|
6. **Hand off when it's clear.** Suggest the next step: `m-feature <one-line summary>`, `m-change <one-line summary>` for a small change, `m-prototype <one-line summary>` when it needs a demo or a design before it's built, 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.
|
|
@@ -23,33 +23,36 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
|
|
|
23
23
|
|
|
24
24
|
## 2. Requirements (then stop for approval)
|
|
25
25
|
|
|
26
|
-
1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `specs/_templates/` to `specs/<id>/`. If `specs/<id>/` already has a draft from `m-explore` or `m-prototype`, keep it and copy only the missing files.
|
|
26
|
+
1. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Copy `requirements.md`, `design.md`, `tasks.md` and `progress.md` from `specs/_templates/` to `specs/<id>/`. If `specs/<id>/` already has a draft from `m-explore` or `m-prototype`, keep it and copy only the missing files.
|
|
27
27
|
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.
|
|
28
28
|
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.
|
|
29
|
-
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/amk/specs.js check specs/<id>/requirements.md`.
|
|
30
|
-
5. If something is unclear, ask the user
|
|
31
|
-
6. Show the requirements and **stop until the user approves them**. Give the user these questions to check them against:
|
|
29
|
+
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. Use the app's words from `docs/amk/glossary.md`; a new word, or one used two ways, gets settled with the user and added there. Then run `node scripts/amk/specs.js check specs/<id>/requirements.md`.
|
|
30
|
+
5. If something is unclear, ask the user in rounds (`AGENTS.md`): every question you can ask now, numbered, each with the answer you recommend. Don't fill gaps with guesses.
|
|
31
|
+
6. Show the requirements, with the answers worked in, and **stop until the user approves them**. Answers to a round aren't that approval: ask for it on its own. Give the user these questions to check them against:
|
|
32
32
|
- Is this the problem you asked me to solve, with nothing extra in scope?
|
|
33
33
|
- Could someone test each requirement without reading the code?
|
|
34
34
|
- Does a scenario cover the case you care about most?
|
|
35
35
|
|
|
36
36
|
## 3. Design and tasks (then stop for approval)
|
|
37
37
|
|
|
38
|
-
1. **
|
|
39
|
-
2.
|
|
40
|
-
3. Fill `
|
|
41
|
-
4.
|
|
38
|
+
1. **Ask for the UI/UX level first, when the feature has screens**, in one round with any other open design question: which level its screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends; it takes longer). `specs/_templates/design.md` describes each. Offer as the default the level a prototype settled (under `## Decisions` in `requirements.md`), otherwise the one the app's other screens have (an earlier spec's `design.md`), otherwise Simple. Don't design until the user has answered. Write the answer and the date under "UI/UX level" in `design.md` (n/a for a feature without screens).
|
|
39
|
+
2. **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/amk/structure.md` and `docs/amk/conventions.md`.
|
|
40
|
+
3. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
|
|
41
|
+
4. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each), each a thin slice through every layer it needs (screen, state, API call, test) that works and can be checked on its own, rather than one layer at a time. Changes that make the feature easy to add (moving or renaming code that's there) come first, as their own task. Each task names the requirement it serves, the tasks it waits on (`after:`) 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 a `# Scenario <n>: <name>` comment above each scenario's steps, an assertion for its THEN and a screenshot, tapping elements by `testID` and scrolling to the ones further down a screen first (`scrollUntilVisible`): turned screens are short. A screen that loads data gets a scenario and a screenshot for its empty and error states too, where a flow can reach them (cleared data, or an account without any, for empty; `setAirplaneMode: enabled` for no network). When the feature adds screens, the task for its main screen comes first among them and ends with a look check: the start of `.maestro/<id>.yaml` opens that screen and takes its screenshot, run with `sh scripts/amk/verify.sh ios --flow .maestro/<id>.yaml --screens phone` (or `android`).
|
|
42
|
+
5. 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.
|
|
42
43
|
|
|
43
44
|
From here the plan lives in files, so the building can also run in a fresh session or another tool with `m-continue <id>`.
|
|
44
45
|
|
|
45
46
|
## 4. Build, one task at a time
|
|
46
47
|
|
|
47
|
-
For each task:
|
|
48
|
-
1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
|
|
48
|
+
For each task, in order (a task with `after:` once those tasks are ticked; one without, as listed):
|
|
49
|
+
1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the UI/UX level in `design.md`, from the colours, type, spacing and controls in `docs/amk/design-system.md`, and to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
|
|
49
50
|
2. Run `lint`, `typecheck` and `test` (see AGENTS.md). Paste the real output. If something fails, fix it; after 2 failed attempts, stop and report.
|
|
50
51
|
3. Commit with a clear message ending in `Spec: specs/<id>`.
|
|
51
52
|
4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
|
|
52
53
|
|
|
54
|
+
After the main screen's task, show the user its screenshot and **stop until they OK the look**: a wrong look then costs one screen, not five.
|
|
55
|
+
|
|
53
56
|
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.
|
|
54
57
|
|
|
55
58
|
## 5. Check against the spec
|
|
@@ -59,6 +62,8 @@ When all tasks are done:
|
|
|
59
62
|
- **One command** (`verify.sh all --spec <id>`): run it. Then **open the screenshots** in `.amk/evidence/<id>/` and check each one against its scenario, in every screen's folder (phone, landscape, tablet).
|
|
60
63
|
- **A plan, and your tool has subagents:** run its `quick` and `build` commands as printed (nothing added: the plain commands are the ones people allow), then, round by round, start one `m-device-checker` subagent per device command of the round, all at once, and wait for their reports before the next round; each runs its device (or its part of the flows), checks its screenshots and hands back a report. When all are back, check them yourself: every flow passed, every screen has screenshots in its folder, or in each `part-k/` folder when its flows ran in parts (list them), and open every screenshot a report flags plus at least one per screen. A report alone isn't evidence. Without subagents, run `verify.sh all --spec <id>` instead.
|
|
61
64
|
|
|
65
|
+
Then **the design review**: give the screenshot folders to the `m-design-reviewer` subagent, which sees only them, `docs/amk/design-system.md` and the UI/UX level in `design.md` (without subagents, check the same yourself). Fix what it finds, or tell the user why one stays.
|
|
66
|
+
|
|
62
67
|
Off a Mac it checks Android only: record in `progress.md` that iOS still needs `verify.sh ios --spec <id>` on a Mac, and say so in the PR. A turned screen's screenshots are landscape; a portrait one means the app didn't turn. Maestro can report a tap as passed when nothing happened, so the screenshots are the evidence, not the log.
|
|
63
68
|
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.
|
|
64
69
|
|
|
@@ -71,6 +76,6 @@ Then update the `docs/amk/` files the feature made untrue: a new key journey in
|
|
|
71
76
|
## 7. Review and pull request
|
|
72
77
|
|
|
73
78
|
1. Run `m-review` (or ask the `m-reviewer` subagent, if your tool has subagents). Fix real problems only; skip style nits.
|
|
74
|
-
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.
|
|
79
|
+
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. Then the risk: whether it can be undone once a store build ships (native changes, data saved in a new format, and API changes that installed versions still rely on can't be; JavaScript can be fixed in the next release), and what else it could break. Use `.github/pull_request_template.md` if the repo has one.
|
|
75
80
|
|
|
76
81
|
Never claim a check passed without running it in this session.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: m-onboard
|
|
3
|
-
description: Describe the app for AI agents - read the whole project, draft docs/amk/product.md, tech.md, structure.md and
|
|
3
|
+
description: Describe the app for AI agents - read the whole project, draft docs/amk/product.md, tech.md, structure.md, conventions.md, glossary.md and design-system.md, ask only what the code can't show, and write them once the user approves. Run it after installing the kit, and again after big changes. Run only when the user explicitly invokes m-onboard.
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -8,13 +8,13 @@ disable-model-invocation: true
|
|
|
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
|
-
Input: $ARGUMENTS (optional: which files to work on, for example `tech structure`; all
|
|
11
|
+
Input: $ARGUMENTS (optional: which files to work on, for example `tech structure`; all six by default).
|
|
12
12
|
|
|
13
|
-
Every agent reads these
|
|
13
|
+
Every agent reads these six files before it works on this app, so they must be true, short and specific: facts with the files they come from, not advice. Write only what you found in the project or what the user told you.
|
|
14
14
|
|
|
15
15
|
## 1. See what's there
|
|
16
16
|
|
|
17
|
-
Read `AGENTS.md` and the
|
|
17
|
+
Read `AGENTS.md` and the six files in `docs/amk/` (`product.md`, `tech.md`, `structure.md`, `conventions.md`, `glossary.md`, `design-system.md`). A file that holds only its heading and the `<!-- … -->` outline is empty: you'll draft it. A file with content is the team's: you'll suggest changes to it, never rewrite it.
|
|
18
18
|
|
|
19
19
|
## 2. Read the project
|
|
20
20
|
|
|
@@ -24,6 +24,7 @@ Change nothing in this step. List the project's files with `git ls-files` (it le
|
|
|
24
24
|
- **Screens and journeys:** the entry point (`index.js`, `App.tsx`, or the `app/` folder with Expo Router), the navigation setup and the list of screens. The key user journeys come from these: sign-in, the main flows, payments, settings.
|
|
25
25
|
- **Tech:** for each dependency that matters, what the app uses it for and where it's set up: state, navigation, the API client, storage, forms, i18n, analytics, push, crash reporting, payments, maps. Also the backend APIs and where their contracts live, and the environments: config files, `.env.example`, build flavors and schemes. Never open `.env` files, keystores or signing files.
|
|
26
26
|
- **Structure:** the folder map, two or three levels into the app's code; where shared components, the theme and helpers live; custom native code under `ios/` and `android/` (native modules, extensions, widgets), or config plugins and local modules in Expo apps.
|
|
27
|
+
- **Look:** the theme (colours, fonts, spacing, radius, dark mode), the shared components that draw buttons, fields and rows, the icon library, and what the texts on screen sound like.
|
|
27
28
|
- **Conventions:** a few files from each layer (a screen, a component, a hook, an API call, a test) and what they have in common: naming, file layout, styling, error, loading and empty states, how tests mock the API. Also the lint and formatter configs, and `git log --oneline -30` for the style of commit messages and branch names. A convention is a pattern you saw in several files; a single file is an example, not a rule.
|
|
28
29
|
|
|
29
30
|
In a large app, sample: a few files per layer are enough. Keep a note of the files each finding comes from.
|
|
@@ -36,6 +37,8 @@ Draft each file you're working on from its outline, and keep it short.
|
|
|
36
37
|
- `tech.md`: what the app uses today, 1-2 lines each with the library and where it's set up; the backend APIs and their contracts; the environments and how the app switches between them; third-party services. Describe what's there; don't recommend new tools.
|
|
37
38
|
- `structure.md`: the folder map, 1-2 lines per folder; where shared UI, the theme and helpers live, so agents reuse them instead of writing new ones; custom native code.
|
|
38
39
|
- `conventions.md`: the patterns you found, each with a file that shows it.
|
|
40
|
+
- `glossary.md`: the app's own words, from its screens, data types, API and store texts (an Order, a Visit), one or two lines each, with the other words used for the same thing listed as not to use (leave that line out when you found none).
|
|
41
|
+
- `design-system.md`: how the app looks, from its theme and shared components, each with the file it comes from: colours by role, the type size and weight of each text role, spacing steps, radius, the buttons, fields and rows, the icon set, motion, and the voice of its texts. In an app without a theme, write what the screens use most, and say so.
|
|
39
42
|
|
|
40
43
|
Use the app's own names for screens, modules and services. Where the project doesn't answer something, write down a question for step 4 instead of guessing.
|
|
41
44
|
|
|
@@ -43,7 +46,7 @@ For a file that's already filled in, compare it with what you found and list wha
|
|
|
43
46
|
|
|
44
47
|
## 4. Ask what the code can't show
|
|
45
48
|
|
|
46
|
-
Ask the user in one
|
|
49
|
+
Ask the user in one round (`AGENTS.md`), usually five questions or fewer, each with the answer the code suggests, about what you couldn't find:
|
|
47
50
|
- who uses the app (customers, staff, a market or age group);
|
|
48
51
|
- what must never break (payments, data sync, sign-in, …);
|
|
49
52
|
- whether the key journeys you found are right and complete;
|
|
@@ -15,9 +15,9 @@ A prototype answers questions before the real build: what the client wants, how
|
|
|
15
15
|
## 1. Understand
|
|
16
16
|
|
|
17
17
|
1. Read the requirement, `docs/amk/product.md`, `structure.md` and `conventions.md`, the living spec for the area in `specs/current/`, and the screens around where this would live: their components, theme and navigation.
|
|
18
|
-
2. Ask who the demo is for (the client or the team)
|
|
18
|
+
2. Ask in one round (`AGENTS.md`): who the demo is for (the client or the team), what it must show, and which UI/UX level the screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends). `specs/_templates/design.md` describes each; recommend the level the app's other screens have, if an earlier spec's `design.md` records one, otherwise Simple. The concepts and the prototype are made at that level: don't start them until the user has answered.
|
|
19
19
|
3. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Create the branch `prototype/<id>` from the main branch; this workflow commits everything there.
|
|
20
|
-
4. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way.
|
|
20
|
+
4. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way, starting with the UI/UX level and the date.
|
|
21
21
|
5. Decide which case this is:
|
|
22
22
|
- **What to show is clear** (the screens and the flow are known): go to step 3.
|
|
23
23
|
- **How it should work or look is still open:** go to step 2.
|
|
@@ -25,12 +25,12 @@ A prototype answers questions before the real build: what the client wants, how
|
|
|
25
25
|
## 2. Concepts
|
|
26
26
|
|
|
27
27
|
1. Work out two or three genuinely different ways it could work: different flows or layouts, not colour variants. For each, note the user flow step by step, the key screens, and the trade-offs: effort, iOS and Android differences, native or backend work.
|
|
28
|
-
2. Make one HTML file per concept in `specs/<id>/concepts/`: the key screens as phone-sized frames side by side, with the app's colours, fonts and spacing taken from its theme, real texts where they're known, and links between the frames so it can be clicked through. Each is a single file of plain HTML and CSS, with nothing to install or build and nothing loaded from the internet, so it opens in any browser.
|
|
28
|
+
2. Make one HTML file per concept in `specs/<id>/concepts/`: the key screens as phone-sized frames side by side, with the app's colours, fonts and spacing taken from `docs/amk/design-system.md` (its theme), real texts where they're known, and links between the frames so it can be clicked through. Each is a single file of plain HTML and CSS, with nothing to install or build and nothing loaded from the internet, so it opens in any browser.
|
|
29
29
|
3. Show the concepts with your recommendation. **Stop until the user picks one or combines them.** Write the choice and why under `## Decisions`, and commit.
|
|
30
30
|
|
|
31
31
|
## 3. Build the prototype in the app
|
|
32
32
|
|
|
33
|
-
1. Build the screens with the app's own components, theme and navigation, so it looks and feels like the app. Keep the mock data in one file next to the screens.
|
|
33
|
+
1. Build the screens with the app's own components, theme and navigation, as `docs/amk/design-system.md` describes them, so it looks and feels like the app. Keep the mock data in one file next to the screens.
|
|
34
34
|
2. No API calls, no native files and no new dependencies. If one seems unavoidable, ask.
|
|
35
35
|
3. Make it easy to reach in a demo: a temporary entry where the feature would live, or the app's first screen when that's simpler.
|
|
36
36
|
4. Skip tests: the prototype is thrown away. It only has to build and run.
|
|
@@ -40,7 +40,7 @@ A prototype answers questions before the real build: what the client wants, how
|
|
|
40
40
|
|
|
41
41
|
1. Write `.maestro/<id>-prototype.yaml` from `specs/_templates/flow.yaml`: walk through the prototype the way the demo would, with a `takeScreenshot` on every screen, and `startRecording: <id>-prototype` after the launch and `stopRecording` at the end for a video.
|
|
42
42
|
2. Run `sh scripts/amk/verify.sh all --flow .maestro/<id>-prototype.yaml --label <id>-prototype`. Off a Mac it covers Android only.
|
|
43
|
-
3. Open every screenshot and check that it shows what the demo needs. Give the user the folder `.amk/evidence/<id>-prototype/`, which has the screenshots and a video per platform, and the concept files if there are any. For a live demo, run the app from this branch on a phone or simulator.
|
|
43
|
+
3. Open every screenshot and check that it shows what the demo needs. Then ask the `m-design-reviewer` subagent for a design review of them (without subagents, check the same yourself), and fix what it finds before the demo. Give the user the folder `.amk/evidence/<id>-prototype/`, which has the screenshots and a video per platform, and the concept files if there are any. For a live demo, run the app from this branch on a phone or simulator.
|
|
44
44
|
|
|
45
45
|
## 5. Take in the feedback
|
|
46
46
|
|
|
@@ -17,12 +17,15 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
|
|
|
17
17
|
- **Against the spec**, when there is one:
|
|
18
18
|
- *Complete:* every task is ticked, every requirement is implemented, and every scenario has evidence (a test or a screenshot).
|
|
19
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/amk/specs.js merge <id>`) if behavior changed.
|
|
20
|
+
- *Coherent:* the decisions in `design.md` show up in the code, its UI/UX level in the screens, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
|
|
21
21
|
- **No spec:** does the diff do what was asked, and nothing unrelated?
|
|
22
|
-
- **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
|
|
22
|
+
- **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened? Do they check behavior through the public interface, mock only what the app doesn't own, and take expected values from the spec rather than recompute them (the React Native rules file)?
|
|
23
23
|
- **TypeScript:** any new `any`, `@ts-ignore` or non-null `!` to get past a check, or a loosened `tsconfig.json`?
|
|
24
24
|
- **Both platforms:** anything iOS-only or Android-only (insets, back button, permissions, keyboard)?
|
|
25
25
|
- **Screens:** with the keyboard open, do the field and its button stay visible? Does anything sit under the status bar, home indicator or gesture bar? Do lists that grow with the user's data scroll? Does text wrap at the largest text size?
|
|
26
|
+
- **Design system:** new screens use the colours, type, spacing and controls in `docs/amk/design-system.md`; nothing new (a hex colour, a one-off button style) that it doesn't have.
|
|
27
|
+
- **Forms and buttons:** a visible label on every field, not the placeholder; the right keyboard and autofill; errors under their field; a request that can't be sent twice; no success message when nothing was saved; a destructive action that asks first.
|
|
28
|
+
- **Nothing invented:** no made-up figures, ratings, reviews or placeholder names on a screen; a missing text is a placeholder the PR lists.
|
|
26
29
|
- **Tablets and landscape** (the screens `AGENTS.md` lists): does each layout adapt to the window width (`useWindowDimensions`), rather than stretching or centering the phone layout? Do turned screens scroll, with the left and right insets handled? Are sizes done the app's existing way?
|
|
27
30
|
- **Accessibility:** does every new button or other touchable have an `accessibilityLabel` and an `accessibilityRole`, and checkboxes, switches and tabs their `accessibilityState`? Are messages that appear after an action, such as form errors, announced to screen readers? Text contrast 4.5:1 in both themes, nothing under 11 points, swipe and long-press actions reachable another way?
|
|
28
31
|
- **Platform guidelines:** tap areas of at least 44×44 pt (48×48 dp on Android); swipe back and the Android back button still work, and every `Modal` closes with back; permissions asked when the user starts the feature, with a way to Settings once blocked; native controls; dark mode from the theme; Reduce Motion respected.
|
|
@@ -10,7 +10,9 @@
|
|
|
10
10
|
|
|
11
11
|
## Risk
|
|
12
12
|
|
|
13
|
-
<!--
|
|
13
|
+
<!-- Can it be undone? JavaScript can be fixed in the next release, but a store build can't be called back:
|
|
14
|
+
native changes, data saved in a new format, and API changes that installed versions still rely on need care.
|
|
15
|
+
And what else could it break, beyond the feature? -->
|
|
14
16
|
|
|
15
17
|
## AI use
|
|
16
18
|
|
|
@@ -65,6 +65,9 @@ jobs:
|
|
|
65
65
|
disable-animations: true
|
|
66
66
|
emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
|
|
67
67
|
script: sh scripts/amk/verify.sh android --label ci
|
|
68
|
+
- name: Summary (each flow's result, from verify.sh's report)
|
|
69
|
+
if: always()
|
|
70
|
+
run: if [ -d .amk/evidence/ci ]; then node scripts/amk/report.js .amk/evidence/ci --summary >> "$GITHUB_STEP_SUMMARY"; fi
|
|
68
71
|
- name: Upload screenshots and logs
|
|
69
72
|
if: always()
|
|
70
73
|
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
@@ -8,6 +8,12 @@
|
|
|
8
8
|
"git push --force*": "deny",
|
|
9
9
|
"git push -f*": "deny",
|
|
10
10
|
"git clean -f*": "deny",
|
|
11
|
+
"git checkout .": "deny",
|
|
12
|
+
"git checkout -- .": "deny",
|
|
13
|
+
"git restore .": "deny",
|
|
14
|
+
"git stash drop*": "deny",
|
|
15
|
+
"git stash clear*": "deny",
|
|
16
|
+
"git branch -D*": "deny",
|
|
11
17
|
"git commit --no-verify*": "deny",
|
|
12
18
|
"xcrun simctl erase*": "deny",
|
|
13
19
|
"npm install *": "ask",
|