agentic-mobile-kit 0.7.4 → 0.7.6
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 -1
- package/bin/cli.js +5 -3
- package/lib/doctor.js +9 -3
- package/lib/init.js +74 -2
- package/lib/menu.js +15 -5
- package/package.json +1 -1
- package/stacks/react-native/template/.agents/skills/m-explore/SKILL.md +2 -1
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +6 -1
- package/stacks/react-native/template/.agents/skills/m-onboard/SKILL.md +4 -4
- package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +4 -3
- package/stacks/react-native/template/docs/amk/product.md +5 -4
- package/stacks/react-native/template/docs/amk/structure.md +1 -1
- package/stacks/react-native/template/scripts/amk/verify.sh +32 -8
package/README.md
CHANGED
|
@@ -14,11 +14,13 @@ Tested with Claude Code, Codex and Antigravity. `--tools` also sets up Cursor, O
|
|
|
14
14
|
|
|
15
15
|
It asks what to do, one step at a time: install with the recommended setup (Claude Code, Codex and Antigravity, no CI), or choose the AI tools and CI. There's nothing to `npm install`: the kit copies its files into the app and isn't a dependency. If you ran `npm i agentic-mobile-kit`, commit or undo that first, because the kit needs a clean working tree.
|
|
16
16
|
|
|
17
|
+
**Starting a new app?** Run it in an empty folder. It offers to create a React Native app with the React Native CLI (with its iOS pods) or an Expo app with create-expo-app, commits it, and installs the kit in it.
|
|
18
|
+
|
|
17
19
|
2. Run it again and choose **Check this project and machine**. It lists each problem with its fix.
|
|
18
20
|
|
|
19
21
|
3. In your AI tool, run `m-onboard`. It reads the project, drafts `docs/amk/product.md`, `tech.md`, `structure.md` and `conventions.md`, asks what the code can't show, and writes them once you approve. Then commit and open a PR.
|
|
20
22
|
|
|
21
|
-
Each choice prints the command it runs, for scripts and CI: `init` (with `--ci github`, `--ci codemagic` or `--tools claude,codex,antigravity`), `sync`, `doctor` and `uninstall`. `--help` lists every option.
|
|
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.
|
|
22
24
|
|
|
23
25
|
`init` never overwrites your files, is safe to run again, and can be undone with git. The [team guide](docs/team-guide.md#setup) lists everything it changes.
|
|
24
26
|
|
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, CI } = require('../lib/init');
|
|
3
|
+
const { init, sync, uninstall, createApp, printSummary, printSync, printUninstall, InitError, TOOLS, CI } = require('../lib/init');
|
|
4
4
|
const { doctor, printDoctor } = require('../lib/doctor');
|
|
5
5
|
const { menu } = require('../lib/menu');
|
|
6
6
|
|
|
@@ -8,18 +8,19 @@ const help = `agentic-mobile-kit ${version}
|
|
|
8
8
|
|
|
9
9
|
Usage:
|
|
10
10
|
npx agentic-mobile-kit In a terminal: pick what to do in this app, step by step
|
|
11
|
-
npx agentic-mobile-kit init [--tools claude,codex,antigravity] [--ci github,codemagic] [--pm yarn|npm|pnpm|bun]
|
|
11
|
+
npx agentic-mobile-kit init [--new bare|expo] [--tools claude,codex,antigravity] [--ci github,codemagic] [--pm yarn|npm|pnpm|bun]
|
|
12
12
|
npx agentic-mobile-kit sync [--ci github,codemagic] [--from <version>]
|
|
13
13
|
npx agentic-mobile-kit uninstall [--from <version>]
|
|
14
14
|
npx agentic-mobile-kit doctor
|
|
15
15
|
|
|
16
16
|
Commands:
|
|
17
|
-
init Install the kit into a React Native or Expo app (run in the app's root).
|
|
17
|
+
init Install the kit into a React Native or Expo app (run in the app's root, or with --new in an empty folder).
|
|
18
18
|
sync Update the kit's files to this version. Your own changes to them are merged in, not lost.
|
|
19
19
|
uninstall Remove the kit's files and sections. Files you changed are kept and listed.
|
|
20
20
|
doctor Check the project and this machine, with a fix for each problem.
|
|
21
21
|
|
|
22
22
|
Options:
|
|
23
|
+
--new In an empty folder: first create the app, with the React Native CLI (bare) or create-expo-app (expo)
|
|
23
24
|
--tools AI tools your team uses: ${Object.keys(TOOLS).join(', ')} (default: claude,codex,antigravity)
|
|
24
25
|
--ci CI to set up, only if the app uses it: ${Object.keys(CI).join(', ')} (GitHub Actions checks, Codemagic signed builds; default: none)
|
|
25
26
|
--pm Package manager, if it can't be detected from the lockfile
|
|
@@ -45,6 +46,7 @@ function main([cmd, ...rest]) {
|
|
|
45
46
|
console.log(version);
|
|
46
47
|
} else if (cmd === 'init') {
|
|
47
48
|
run('init', () => {
|
|
49
|
+
if (flag('new')) createApp(process.cwd(), flag('new'));
|
|
48
50
|
printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
|
|
49
51
|
});
|
|
50
52
|
} else if (cmd === 'sync') {
|
package/lib/doctor.js
CHANGED
|
@@ -4,7 +4,7 @@ const fs = require('fs');
|
|
|
4
4
|
const os = require('os');
|
|
5
5
|
const path = require('path');
|
|
6
6
|
const { spawnSync } = require('child_process');
|
|
7
|
-
const { tool, hookManager, hooksWired } = require('./init');
|
|
7
|
+
const { tool, hookManager, hooksWired, checkProject, emptyFolder } = require('./init');
|
|
8
8
|
|
|
9
9
|
const RULESYNC = 'rulesync@27.0.0';
|
|
10
10
|
|
|
@@ -29,7 +29,10 @@ function projectChecks(cwd, opts) {
|
|
|
29
29
|
const out = [];
|
|
30
30
|
const agents = read(cwd, 'AGENTS.md');
|
|
31
31
|
if (!agents || !/<!-- KIT:START/.test(agents) || !fs.existsSync(path.join(cwd, '.agents/skills/m-feature/SKILL.md'))) {
|
|
32
|
-
|
|
32
|
+
let fix = 'run: npx agentic-mobile-kit init';
|
|
33
|
+
if (emptyFolder(cwd)) fix = 'create the app here and install the kit: npx agentic-mobile-kit init --new bare (or --new expo)';
|
|
34
|
+
else try { checkProject(cwd); } catch (e) { fix = e.message; } // what init would stop on
|
|
35
|
+
out.push(fail('Kit installed', fix));
|
|
33
36
|
return out; // the rest needs the kit
|
|
34
37
|
}
|
|
35
38
|
out.push(ok('Kit installed'));
|
|
@@ -108,7 +111,10 @@ function machineChecks(cwd) {
|
|
|
108
111
|
|
|
109
112
|
const pm = fs.existsSync(path.join(cwd, 'yarn.lock')) ? 'yarn' : fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')) ? 'pnpm' : 'npm';
|
|
110
113
|
out.push(run(pm, ['--version'], { cwd }) ? ok(`Package manager (${pm})`) : fail(`${pm} not found`, pm === 'npm' ? 'install Node' : 'run: corepack enable'));
|
|
111
|
-
|
|
114
|
+
if (fs.existsSync(path.join(cwd, 'package.json'))) {
|
|
115
|
+
out.push(fs.existsSync(path.join(cwd, 'node_modules')) ? ok('Dependencies installed')
|
|
116
|
+
: fail('Dependencies not installed', `run: ${fs.existsSync(path.join(cwd, 'scripts/amk/install-deps.sh')) ? 'sh scripts/amk/install-deps.sh' : `${pm} install`}`));
|
|
117
|
+
}
|
|
112
118
|
|
|
113
119
|
// iOS (macOS only)
|
|
114
120
|
if (process.platform === 'darwin') {
|
package/lib/init.js
CHANGED
|
@@ -91,7 +91,7 @@ function detectPm(cwd, forced) {
|
|
|
91
91
|
// the app's folder first: in the wrong folder, "run git init" would be the wrong advice
|
|
92
92
|
function checkProject(cwd) {
|
|
93
93
|
const pkgFile = path.join(cwd, 'package.json');
|
|
94
|
-
if (!fs.existsSync(pkgFile)) throw new InitError('No package.json here. Run this in the root of your React Native app.');
|
|
94
|
+
if (!fs.existsSync(pkgFile)) throw new InitError('No package.json here. Run this in the root of your React Native app, or in an empty folder to create one.');
|
|
95
95
|
const pkg = readJson(pkgFile);
|
|
96
96
|
const deps = { ...pkg.dependencies, ...pkg.devDependencies };
|
|
97
97
|
if (!deps['react-native']) throw new InitError('This is not a React Native project (no "react-native" dependency).');
|
|
@@ -108,6 +108,78 @@ function checkProject(cwd) {
|
|
|
108
108
|
return { pkg, deps, stack };
|
|
109
109
|
}
|
|
110
110
|
|
|
111
|
+
// a folder with nothing but these can get a new app: system and editor files, and the .git of an empty clone
|
|
112
|
+
const EMPTY_OK = ['.git', '.DS_Store', 'Thumbs.db', '.vscode', '.idea'];
|
|
113
|
+
const emptyFolder = cwd => fs.readdirSync(cwd).every(f => EMPTY_OK.includes(f));
|
|
114
|
+
// the React Native CLI wants an identifier: a folder "my-new-app" gives MyNewApp
|
|
115
|
+
const appName = folder => {
|
|
116
|
+
const n = (folder.match(/[A-Za-z0-9]+/g) || []).map(w => w[0].toUpperCase() + w.slice(1)).join('');
|
|
117
|
+
return /^[A-Za-z]/.test(n) ? n : `App${n}`;
|
|
118
|
+
};
|
|
119
|
+
// the CLI's pods step fetches and builds Ruby gems first, which is slow, and when that fails it reports a broken iOS
|
|
120
|
+
// setup: createApp installs the pods itself, as scripts/amk/pod-install.sh does
|
|
121
|
+
const NEW_APP = {
|
|
122
|
+
bare: { by: 'the React Native CLI', args: name => ['@react-native-community/cli@latest', 'init', appName(name), '--directory', name, '--install-pods', 'false'] },
|
|
123
|
+
expo: { by: 'create-expo-app', args: name => ['create-expo-app@latest', name, '--yes'] },
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
// `init --new bare|expo`: creates the app with the official tool, which makes a new folder, so the tool runs in an
|
|
127
|
+
// empty subfolder and the app moves up. In place, the React Native CLI offers to delete a folder that has any file
|
|
128
|
+
// (even .git), and create-expo-app refuses .vscode.
|
|
129
|
+
function createApp(cwd, kind, { run = tool, log = console.log, pods = process.platform === 'darwin' } = {}) {
|
|
130
|
+
const how = Object.hasOwn(NEW_APP, kind) && NEW_APP[kind];
|
|
131
|
+
if (!how) throw new InitError(`Unknown app type "${kind}". Choose bare (the React Native CLI) or expo (create-expo-app).`);
|
|
132
|
+
if (!emptyFolder(cwd)) throw new InitError('This folder isn\'t empty. To create a new app, run this in an empty folder.');
|
|
133
|
+
let prefix = null;
|
|
134
|
+
try { prefix = git(cwd, 'rev-parse', '--show-prefix'); } catch {}
|
|
135
|
+
if (prefix) throw new InitError(`This folder is inside another git repository (${git(cwd, 'rev-parse', '--show-toplevel')}), as in a monorepo. The kit doesn't support that yet.`);
|
|
136
|
+
const own = prefix === ''; // the folder is its own repository: keep it, with its remote
|
|
137
|
+
const name = path.basename(cwd);
|
|
138
|
+
const args = ['-y', ...how.args(name)];
|
|
139
|
+
const tmp = fs.mkdtempSync(path.join(cwd, '.amk-new-'));
|
|
140
|
+
const held = path.join(tmp, '.held-git');
|
|
141
|
+
// Ctrl-C stops the tool, which takes minutes; this process stays to put the folder back
|
|
142
|
+
const stay = () => {};
|
|
143
|
+
process.on('SIGINT', stay);
|
|
144
|
+
try {
|
|
145
|
+
if (own) fs.renameSync(path.join(cwd, '.git'), held); // otherwise the tools skip git, or ask
|
|
146
|
+
log(`Creating the app with ${how.by}: npx ${args.join(' ')}\n`);
|
|
147
|
+
const r = run('npx', args, { cwd: tmp, stdio: 'inherit', env: cleanEnv() });
|
|
148
|
+
const app = path.join(tmp, name);
|
|
149
|
+
if (r.status !== 0 || !fs.existsSync(path.join(app, 'package.json'))) throw new InitError(`${how.by} didn't create the app (${r.signal || `exit code ${r.status}`}). This folder is as it was.`);
|
|
150
|
+
// both tools finish, and commit, even when installing the packages failed: the lockfile shows it worked
|
|
151
|
+
if (!fs.readdirSync(app).some(f => /^(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?)$/.test(f))) {
|
|
152
|
+
throw new InitError(`${how.by} created the app, but installing its packages failed (see above). This folder is as it was. Check the network, then run this again.`);
|
|
153
|
+
}
|
|
154
|
+
for (const f of fs.readdirSync(app)) {
|
|
155
|
+
if (f === '.git' && own) continue;
|
|
156
|
+
if (!fs.existsSync(path.join(cwd, f))) fs.renameSync(path.join(app, f), path.join(cwd, f)); // the folder's own editor settings stay
|
|
157
|
+
}
|
|
158
|
+
} finally {
|
|
159
|
+
process.off('SIGINT', stay);
|
|
160
|
+
if (own && fs.existsSync(held)) fs.renameSync(held, path.join(cwd, '.git'));
|
|
161
|
+
fs.rmSync(tmp, { recursive: true, force: true });
|
|
162
|
+
}
|
|
163
|
+
log(`\nThe app is in ${cwd} (the folder in the tool's instructions above was temporary).`);
|
|
164
|
+
const commit = msg => {
|
|
165
|
+
if (!git(cwd, 'status', '--porcelain')) return;
|
|
166
|
+
git(cwd, 'add', '-A');
|
|
167
|
+
git(cwd, 'commit', '-q', '-m', msg);
|
|
168
|
+
};
|
|
169
|
+
try {
|
|
170
|
+
// the tools commit only in a repository they create; init needs everything committed
|
|
171
|
+
commit(own ? 'Initial commit' : 'Add the files that were already in the folder');
|
|
172
|
+
// the first pod install changes the Xcode project and Info.plist: a commit of its own keeps that out of the first feature
|
|
173
|
+
if (kind === 'bare' && pods) {
|
|
174
|
+
log('Installing the iOS pods\n');
|
|
175
|
+
if (run('sh', [path.join(TEMPLATE, 'scripts/amk/pod-install.sh')], { cwd, stdio: 'inherit' }).status === 0) commit('Install the iOS pods');
|
|
176
|
+
else log('! The iOS pods aren\'t installed (see above). Run sh scripts/amk/pod-install.sh, and commit what it changes before the first feature.');
|
|
177
|
+
}
|
|
178
|
+
} catch (e) {
|
|
179
|
+
throw new InitError(`The app is created, but git couldn't commit it: ${String(e.stderr || e.message).trim()}\nCommit it, then run: npx agentic-mobile-kit init`);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
111
183
|
// Expo apps whose ios/ and android/ come from `expo prebuild` (Continuous Native Generation, not in git) get the
|
|
112
184
|
// Expo overlay. Expo apps that keep the native folders in git are set up like bare apps.
|
|
113
185
|
function detectStack(cwd, deps) {
|
|
@@ -759,5 +831,5 @@ function printUninstall({ report }, log = console.log) {
|
|
|
759
831
|
|
|
760
832
|
module.exports = {
|
|
761
833
|
init, sync, uninstall, printSummary, printSync, printUninstall, InitError, TOOLS, TESTED, CI, KIT_VERSION, tool, cleanEnv,
|
|
762
|
-
hookManager, hooksWired, checkProject, recorded, installedCi,
|
|
834
|
+
hookManager, hooksWired, checkProject, recorded, installedCi, emptyFolder, createApp,
|
|
763
835
|
};
|
package/lib/menu.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
const fs = require('fs');
|
|
5
5
|
const path = require('path');
|
|
6
6
|
const readline = require('readline');
|
|
7
|
-
const { checkProject, recorded, installedCi, InitError, TOOLS, TESTED, CI, KIT_VERSION, tool, cleanEnv } = require('./init');
|
|
7
|
+
const { checkProject, recorded, installedCi, emptyFolder, InitError, TOOLS, TESTED, CI, KIT_VERSION, tool, cleanEnv } = require('./init');
|
|
8
8
|
|
|
9
9
|
const NAMES = { claude: 'Claude Code', codex: 'Codex', antigravity: 'Antigravity', cursor: 'Cursor', opencode: 'OpenCode', kiro: 'Kiro' };
|
|
10
10
|
const CI_NAMES = { github: 'GitHub Actions', codemagic: 'Codemagic' };
|
|
@@ -75,10 +75,13 @@ async function menu(cwd, { input = process.stdin, output = process.stdout, lates
|
|
|
75
75
|
return null;
|
|
76
76
|
}
|
|
77
77
|
|
|
78
|
+
const empty = emptyFolder(cwd);
|
|
78
79
|
let problem = '';
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
80
|
+
if (!empty) {
|
|
81
|
+
try { checkProject(cwd); } catch (e) {
|
|
82
|
+
if (!(e instanceof InitError)) throw e;
|
|
83
|
+
problem = e.message;
|
|
84
|
+
}
|
|
82
85
|
}
|
|
83
86
|
let agents = '';
|
|
84
87
|
try { agents = fs.readFileSync(path.join(cwd, 'AGENTS.md'), 'utf8'); } catch {}
|
|
@@ -86,7 +89,14 @@ async function menu(cwd, { input = process.stdin, output = process.stdout, lates
|
|
|
86
89
|
const quit = { label: 'Quit', args: null };
|
|
87
90
|
let items;
|
|
88
91
|
let def = 0;
|
|
89
|
-
if (
|
|
92
|
+
if (empty) {
|
|
93
|
+
say('This folder is empty. The kit can create the app here with the official tool, then install itself.');
|
|
94
|
+
items = [
|
|
95
|
+
{ label: 'Create a React Native app with the React Native CLI (init --new bare)', args: ['init', '--new', 'bare'] },
|
|
96
|
+
{ label: 'Create an Expo app with create-expo-app (init --new expo)', args: ['init', '--new', 'expo'] },
|
|
97
|
+
doctor, quit,
|
|
98
|
+
];
|
|
99
|
+
} else if (!/<!-- KIT:START/.test(agents)) {
|
|
90
100
|
say('The kit isn\'t installed here.');
|
|
91
101
|
items = [
|
|
92
102
|
{ label: `Install it for ${and(TESTED.map(t => NAMES[t]))}, without CI (init)`, args: ['init'], changes: true },
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-mobile-kit",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.6",
|
|
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",
|
|
@@ -14,4 +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. **
|
|
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.
|
|
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.
|
|
@@ -10,6 +10,11 @@ The user chose this workflow: follow its steps for this task, even where other w
|
|
|
10
10
|
|
|
11
11
|
Input: $ARGUMENTS (the requirement text, a file path, or a task link plus pasted details).
|
|
12
12
|
|
|
13
|
+
With no input, don't guess what to build:
|
|
14
|
+
1. Run `node scripts/amk/specs.js status`. If a spec is in progress, say which one and where it stopped, and suggest `m-continue`. Start something new only if the user says so.
|
|
15
|
+
2. Otherwise list the features marked planned in `docs/amk/product.md` and recommend the next one: the first in the list whose dependencies are built. Wait for the user to pick.
|
|
16
|
+
3. If nothing is planned, ask what to build, or suggest `m-explore` when the requirements aren't settled yet.
|
|
17
|
+
|
|
13
18
|
## 1. Always use the full flow
|
|
14
19
|
|
|
15
20
|
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. (For a small change to behavior the app already has, suggest `m-change`. A change with nothing to record, such as fixing a typo, can just be asked for directly.)
|
|
@@ -57,7 +62,7 @@ When all tasks are done:
|
|
|
57
62
|
|
|
58
63
|
Run `node scripts/amk/specs.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.
|
|
59
64
|
|
|
60
|
-
Then update the `docs/amk/` files the feature made untrue: a new key journey in `product.md
|
|
65
|
+
Then update the `docs/amk/` files the feature made untrue: a new key journey in `product.md` or, for a planned feature there, its rules replaced by one line without the planned mark, a new library or service in `tech.md`, a new folder or shared component in `structure.md`, a new pattern in `conventions.md`. Commit them with the feature too.
|
|
61
66
|
|
|
62
67
|
## 7. Review and pull request
|
|
63
68
|
|
|
@@ -30,11 +30,11 @@ In a large app, sample: a few files per layer are enough. Keep a note of the fil
|
|
|
30
30
|
|
|
31
31
|
## 3. Draft
|
|
32
32
|
|
|
33
|
-
Draft each file you're working on from its outline, and keep it short
|
|
33
|
+
Draft each file you're working on from its outline, and keep it short.
|
|
34
34
|
|
|
35
|
-
- `product.md`: what the app does
|
|
36
|
-
- `tech.md`: what the app uses today,
|
|
37
|
-
- `structure.md`: the folder map,
|
|
35
|
+
- `product.md`: what the app does, who uses it, key journeys, and what must never break.
|
|
36
|
+
- `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
|
+
- `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
38
|
- `conventions.md`: the patterns you found, each with a file that shows it.
|
|
39
39
|
|
|
40
40
|
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.
|
|
@@ -44,11 +44,12 @@ A prototype answers questions before the real build: what the client wants, how
|
|
|
44
44
|
|
|
45
45
|
## 5. Take in the feedback
|
|
46
46
|
|
|
47
|
-
After the demo, write what was settled into `requirements.md`: answered questions become requirements and scenarios, and the choices go under `## Decisions`. If the client asked for changes, change the prototype and run step 4 again. Repeat until the user approves the requirements.
|
|
47
|
+
After the demo, write what was settled into `requirements.md`: answered questions become requirements and scenarios, and the choices go under `## Decisions`. If the client asked for changes, change the prototype and run step 4 again. Repeat until the user approves the requirements: **stop and ask for that approval**, and record it under `## Decisions` with the date. Step 6 doesn't start without it.
|
|
48
48
|
|
|
49
49
|
## 6. Hand off to m-feature
|
|
50
50
|
|
|
51
51
|
1. Create the feature branch from the main branch and bring the spec over: `git checkout prototype/<id> -- specs/<id>`. Leave the prototype code behind.
|
|
52
52
|
2. Add the decisions from `## Decisions` to `docs/amk/decisions.md`, with the date. Run `node scripts/amk/specs.js check specs/<id>/requirements.md`, and commit.
|
|
53
|
-
3.
|
|
54
|
-
4.
|
|
53
|
+
3. If the prototype covered more than one feature, such as an app's first version, also write every feature with its rules in `docs/amk/product.md`, in the order to build them, each marked planned, and tell the user the path. `decisions.md` logs choices and their reasons; it isn't the requirements document.
|
|
54
|
+
4. Suggest `m-feature specs/<id>/requirements.md`, or one `m-feature` per feature when there are several. In `design.md` it names the `prototype/<id>` branch as the agreed flow and look, and it builds the real screens properly: real data, error, loading and empty states, and tests, on both platforms.
|
|
55
|
+
5. Delete the `prototype/<id>` branch once the feature has shipped.
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# Product
|
|
2
2
|
|
|
3
|
-
<!-- Fill in,
|
|
4
|
-
- What the app does
|
|
3
|
+
<!-- Fill in, and keep it short. Agents read this to understand what they're building.
|
|
4
|
+
- What the app does.
|
|
5
5
|
- Who uses it.
|
|
6
|
-
- The
|
|
7
|
-
- Anything that must never break (payments, data sync, …).
|
|
6
|
+
- The key user journeys (sign-up, checkout, …).
|
|
7
|
+
- Anything that must never break (payments, data sync, …).
|
|
8
|
+
- Features that are planned but not built yet, in the order to build them, each marked planned, with its rules. When `m-feature` ships one, its rules move to `specs/current/` and one line stays here. -->
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Structure
|
|
2
2
|
|
|
3
3
|
<!-- Fill in. Agents use this to put new code in the right place and to reuse what exists.
|
|
4
|
-
- Folder map (src/screens, src/components, src/api, …) with
|
|
4
|
+
- Folder map (src/screens, src/components, src/api, …) with 1-2 lines per folder.
|
|
5
5
|
- Where shared UI components and the theme/design tokens live.
|
|
6
6
|
- Where helpers live (dates, formatting, validation), so agents reuse them instead of writing new ones.
|
|
7
7
|
- Native code: anything custom under ios/ and android/. -->
|
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
# --scheme <name> iOS scheme to check (default: the one named like the workspace)
|
|
14
14
|
# (no flows found: a smoke check that launches the app and takes a screenshot)
|
|
15
15
|
# Env: AMK_ANDROID_FLAVOR, AMK_IOS_SCHEME (defaults for the two options), AMK_IOS_DEVICE (simulator name
|
|
16
|
-
# or UDID), AMK_ANDROID_DEVICE (adb serial
|
|
16
|
+
# or UDID), AMK_ANDROID_DEVICE (adb serial: the only way to check on a phone while an emulator exists),
|
|
17
|
+
# AMK_ANDROID_AVD (the emulator to use, started if it isn't running; other devices are left alone)
|
|
17
18
|
# Flows that log in read ${MAESTRO_EMAIL} and the like from a local, gitignored .maestro/.env.local (never committed).
|
|
18
19
|
set -eu
|
|
19
20
|
|
|
@@ -136,6 +137,13 @@ ios() {
|
|
|
136
137
|
run_flows ios "$device" "$app_id"
|
|
137
138
|
}
|
|
138
139
|
|
|
140
|
+
# a running emulator's adb serial, of the AVD named in $1 if one is
|
|
141
|
+
running_emulator() {
|
|
142
|
+
for d in $("$adb" devices | awk 'NR > 1 && $2 == "device" && /^emulator-/ { print $1 }'); do
|
|
143
|
+
if [ -z "$1" ] || [ "$("$adb" -s "$d" emu avd name 2> /dev/null | head -n 1 | tr -d '\r')" = "$1" ]; then echo "$d"; return; fi
|
|
144
|
+
done
|
|
145
|
+
}
|
|
146
|
+
|
|
139
147
|
android() {
|
|
140
148
|
command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
|
|
141
149
|
case $(uname -s) in # where Android Studio puts the SDK by default
|
|
@@ -162,15 +170,31 @@ android() {
|
|
|
162
170
|
[ -z "$flavor" ] || echo "android: checking the \"$flavor\" flavor (the app has: $(echo $flavors)); --flavor <name> checks another"
|
|
163
171
|
fi
|
|
164
172
|
variant=$(printf %s "$flavor" | awk '{ print toupper(substr($0, 1, 1)) substr($0, 2) }')
|
|
165
|
-
# the device first: the build only needs its CPU type, and an emulator boots while Gradle builds
|
|
166
|
-
|
|
173
|
+
# the device first: the build only needs its CPU type, and an emulator boots while Gradle builds.
|
|
174
|
+
# The flows clear the app's data, so an emulator comes before a phone plugged in over USB: a phone is used
|
|
175
|
+
# only when AMK_ANDROID_DEVICE names it, or when there's no emulator at all
|
|
176
|
+
device=${AMK_ANDROID_DEVICE:-$(running_emulator "${AMK_ANDROID_AVD:-}")}
|
|
167
177
|
if [ -z "$device" ]; then
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
178
|
+
avds=$("$sdk/emulator/emulator" -list-avds 2> /dev/null || true)
|
|
179
|
+
avd=${AMK_ANDROID_AVD:-$(echo "$avds" | head -n 1)}
|
|
180
|
+
if [ -n "$avd" ]; then
|
|
181
|
+
echo "$avds" | grep -qxF "$avd" || { echo "android: there's no emulator named $avd (see: emulator -list-avds)"; status=1; return; }
|
|
182
|
+
nohup "$sdk/emulator/emulator" -avd "$avd" -no-snapshot-save -no-boot-anim > /dev/null 2>&1 &
|
|
183
|
+
tries=0
|
|
184
|
+
until device=$(running_emulator "$avd") && [ -n "$device" ]; do
|
|
185
|
+
tries=$((tries + 1))
|
|
186
|
+
[ "$tries" -le 150 ] || { echo "android: emulator $avd didn't start"; status=1; return; }
|
|
187
|
+
sleep 2
|
|
188
|
+
done
|
|
189
|
+
else
|
|
190
|
+
device=$("$adb" devices | awk 'NR > 1 && $2 == "device" { print $1; exit }')
|
|
191
|
+
[ -n "$device" ] || { echo "android: no emulator found (create one in Android Studio)"; status=1; return; }
|
|
192
|
+
fi
|
|
173
193
|
fi
|
|
194
|
+
case $device in
|
|
195
|
+
emulator-*) echo "android: checking on $device" ;;
|
|
196
|
+
*) echo "android: checking on the phone $device; the flows clear the app's data on it" ;;
|
|
197
|
+
esac
|
|
174
198
|
abi=$("$adb" -s "$device" shell getprop ro.product.cpu.abi 2> /dev/null | tr -d '\r')
|
|
175
199
|
[ -n "$abi" ] || { echo "android: device $device isn't connected (see: adb devices)"; status=1; return; }
|
|
176
200
|
# native code for that CPU type only, as run-android --active-arch-only does: much faster than all four
|