agentic-mobile-kit 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -36,6 +36,7 @@ Each choice prints the command it runs, for scripts and CI: `init` (with `--ci g
36
36
  | Build the planned features overnight | `node scripts/amk/autopilot.js` | First the review comments nobody answered on its pull requests, and the bugs labelled `amk-fix`, each to a pull request. Then a fresh session of the AI tool for each feature, with only the build's commands allowed and only the variables a build needs. A stalled session starts again from its handoff; a full disk, an expired sign-in or a usage limit ends the build with the command to go on. Notes and a stop file steer it, and you're notified of each block |
37
37
  | 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 |
38
38
  | Fix a bug | `m-bugfix` | From a description, an issue or a Sentry or Crashlytics report: 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 |
39
+ | See what the AI is doing, and how far a check is | Claude Code: under the prompt; any tool: `node scripts/amk/status.js --watch` | Whether it works, waits for something it started (and goes on by itself) or waits for you, the feature's tasks done, and the checks as they run: a device check's flow k of n, the quick check's stage, CI's checks, an unattended build's feature |
39
40
  | Stop, or switch tool or machine | `m-pause` | Writes a handoff in the spec, commits and pushes |
40
41
  | Carry on anywhere | `m-continue` | Reads the spec and handoff, then picks up at the next step |
41
42
  | Test a change or a release | `m-test` | Runs the checks and the device flows of the change and the areas it touches; a read-only tester gives each scenario a status, and the report says Ready or Not ready |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentic-mobile-kit",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
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",
@@ -1,9 +1,9 @@
1
1
  <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} stack={{KIT_STACK}} (edit outside these markers; the kit updates what's inside) -->
2
2
  # {{APP_NAME}}: instructions for AI agents
3
3
 
4
- Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity; details live in `docs/amk/`.
4
+ Read by every AI tool here (Claude Code through CLAUDE.md); details live in `docs/amk/`.
5
5
 
6
- This project may also use other AI workflow frameworks (for example Superpowers, BMAD or proAgents). They keep working for everything else. When the user starts a task with an `m-` skill (`/m-feature`, `$m-feature`, …), follow that skill's steps for the whole task; where another framework's instructions differ, the `m-` skill wins.
6
+ Other AI workflow frameworks in this project (Superpowers, BMAD, proAgents, …) keep working for everything else. When the user starts a task with an `m-` skill (`/m-feature`, `$m-feature`, …), follow that skill's steps for the whole task; where another framework's instructions differ, the `m-` skill wins.
7
7
 
8
8
  ## Project
9
9
 
@@ -26,7 +26,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
26
26
  | Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` prints a command per device, each for an `m-device-checker` subagent |
27
27
  | After each task: lint, typecheck and the tests of the changed files | `sh scripts/amk/verify.sh quick --related` |
28
28
  | React Native mistakes, flow problems and oversized files or functions in this branch's changes (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
29
- | Specs and the plan: progress, checks, the tests of the areas a spec touches, flows, the living spec, planning | `node scripts/amk/specs.js status` (or `check`, `tests <id>`, `flow <id>`, `merge <id>`, `check --plan`, `plan-folder`, `import <file>`, `start [<id>]`) |
29
+ | Specs and the plan: progress, checks, a spec's tests and flows, the living spec, planning | `node scripts/amk/specs.js status` (or `check`, `tests <id>`, `flow <id>`, `merge <id>`, `check --plan`, `plan-folder`, `import <file>`, `start [<id>]`) |
30
30
  | Unattended (a person starts it; never skipping permission prompts): its PRs' review fixes, `amk-fix` bugs, then approved features | `node scripts/amk/autopilot.js [--reviews \| --bugs \| --features]`; first `node scripts/amk/autopilot.js check` |
31
31
  | A feature's PR: checks (with a failure's log), review comments, auto-merge, main merged into stacked branches | `node scripts/amk/pr.js checks` (or `comments`, `automerge`, `forward`) |
32
32
  | Check a release before tagging it (versions, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
@@ -53,9 +53,10 @@ Never say a check passed unless you ran it in this session.
53
53
  - Never run `eas build`, `eas submit` or `eas update`: they use the team's accounts, so a person runs them.
54
54
  - Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
55
55
  - 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>`.
56
- - 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`, or a cap in `.amk-size-caps`, on your own. One kept over two weeks ago comes back when its file changes: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
56
+ - 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`, or a cap in `.amk-size-caps`, on your own. Fix the warnings (!) in code the task changed, or tell the user why one stays.
57
57
  - Run shell commands one at a time, as the skills write them, not joined with `&&` or `;`: a tool asks about a joined line, or refuses it, as a whole. When one is refused, run its parts on their own before deciding anything is blocked.
58
58
  - After 2 failed attempts at the same fix, stop and report what you found.
59
+ - Ending your turn while something you started still runs (a background command, a subagent, CI)? Say what you wait for, and whether you go on by yourself.
59
60
  - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
60
61
  - Follow `docs/amk/expo.md`. Before fixing a build error, check `docs/amk/known-issues.md`.
61
62
 
@@ -1,9 +1,9 @@
1
1
  <!-- KIT:START agentic-mobile-kit {{KIT_VERSION}} ci={{KIT_CI}} stack={{KIT_STACK}} (edit outside these markers; the kit updates what's inside) -->
2
2
  # {{APP_NAME}}: instructions for AI agents
3
3
 
4
- Read by Claude Code (through CLAUDE.md), Codex, Cursor, OpenCode, Kiro and Antigravity; details live in `docs/amk/`.
4
+ Read by every AI tool here (Claude Code through CLAUDE.md); details live in `docs/amk/`.
5
5
 
6
- This project may also use other AI workflow frameworks (for example Superpowers, BMAD or proAgents). They keep working for everything else. When the user starts a task with an `m-` skill (`/m-feature`, `$m-feature`, …), follow that skill's steps for the whole task; where another framework's instructions differ, the `m-` skill wins.
6
+ Other AI workflow frameworks in this project (Superpowers, BMAD, proAgents, …) keep working for everything else. When the user starts a task with an `m-` skill (`/m-feature`, `$m-feature`, …), follow that skill's steps for the whole task; where another framework's instructions differ, the `m-` skill wins.
7
7
 
8
8
  ## Project
9
9
 
@@ -26,7 +26,7 @@ This project may also use other AI workflow frameworks (for example Superpowers,
26
26
  | Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` prints a command per device, each for an `m-device-checker` subagent |
27
27
  | After each task: lint, typecheck and the tests of the changed files | `sh scripts/amk/verify.sh quick --related` |
28
28
  | React Native mistakes, flow problems and oversized files or functions in this branch's changes (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
29
- | Specs and the plan: progress, checks, the tests of the areas a spec touches, flows, the living spec, planning | `node scripts/amk/specs.js status` (or `check`, `tests <id>`, `flow <id>`, `merge <id>`, `check --plan`, `plan-folder`, `import <file>`, `start [<id>]`) |
29
+ | Specs and the plan: progress, checks, a spec's tests and flows, the living spec, planning | `node scripts/amk/specs.js status` (or `check`, `tests <id>`, `flow <id>`, `merge <id>`, `check --plan`, `plan-folder`, `import <file>`, `start [<id>]`) |
30
30
  | Unattended (a person starts it; never skipping permission prompts): its PRs' review fixes, `amk-fix` bugs, then approved features | `node scripts/amk/autopilot.js [--reviews \| --bugs \| --features]`; first `node scripts/amk/autopilot.js check` |
31
31
  | A feature's PR: checks (with a failure's log), review comments, auto-merge, main merged into stacked branches | `node scripts/amk/pr.js checks` (or `comments`, `automerge`, `forward`) |
32
32
  | Check a release before tagging it (versions, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
@@ -52,9 +52,10 @@ Never say a check passed unless you ran it in this session.
52
52
  - Don't hand-edit `ios/*.xcodeproj/project.pbxproj`. If a native file must be added to the Xcode project, stop and ask.
53
53
  - Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
54
54
  - 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>`.
55
- - 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`, or a cap in `.amk-size-caps`, on your own. One kept over two weeks ago comes back when its file changes: ask again. Fix the warnings (!) in code the task changed, or tell the user why one stays.
55
+ - 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`, or a cap in `.amk-size-caps`, on your own. Fix the warnings (!) in code the task changed, or tell the user why one stays.
56
56
  - Run shell commands one at a time, as the skills write them, not joined with `&&` or `;`: a tool asks about a joined line, or refuses it, as a whole. When one is refused, run its parts on their own before deciding anything is blocked.
57
57
  - After 2 failed attempts at the same fix, stop and report what you found.
58
+ - Ending your turn while something you started still runs (a background command, a subagent, CI)? Say what you wait for, and whether you go on by yourself.
58
59
  - Chat is not memory: write decisions into the spec or `docs/amk/decisions.md` straight away.
59
60
  - Follow `docs/amk/react-native.md`. Before fixing a build error, check `docs/amk/known-issues.md`.
60
61
 
@@ -33,6 +33,7 @@ const path = require('path');
33
33
  const { spawn, spawnSync } = require('child_process');
34
34
  const { redact, untrusted } = require('./redact.js');
35
35
  const specs = require('./specs.js');
36
+ const progress = require('./progress.js');
36
37
 
37
38
  const ROOT = fs.realpathSync(path.join(__dirname, '..', '..'));
38
39
  const BUILD = path.join(ROOT, '.amk', 'build');
@@ -513,6 +514,15 @@ function reviewQueue(ids = new Set(), ghx = gh) {
513
514
  }
514
515
  // the plan's features, by id
515
516
  const planIds = () => { const ref = specs.planRef(); const plan = ref && specs.show(ref, 'specs/plan.md'); return new Set(plan ? specs.planFeatures(plan).rows.map(r => r.id) : []); };
517
+ // the plan's features, and how many of them are built: on main, or done on their branch
518
+ function planCount() {
519
+ try {
520
+ const ids = [...planIds()];
521
+ const main = specs.mainRef();
522
+ const built = main ? specs.builtOn(main) : new Set();
523
+ return { total: ids.length, done: ids.filter(id => built.has(id) || isDone(git('show', `feature/${id}:specs/${id}/progress.md`))).length };
524
+ } catch { return {}; }
525
+ }
516
526
  // open issues labelled amk-fix, oldest first: labelled by someone who can label them, or by Sentry's integration with
517
527
  // "Sentry adds amk-fix: on"; without amk-needs-info, and without an open pull request from fix/<n> yet
518
528
  function bugQueue(cfg, ghx = gh) {
@@ -572,7 +582,9 @@ async function build(o, d = {}) {
572
582
  // main merged into the build's stacked branches whose parent has merged (pr.js forward), at the start of each round
573
583
  forward: log => { const pr = require('./pr.js'); return pr.forward(specs.mainRef(), {}, pr.settings(), { ...pr.IO, log }); },
574
584
  reviews: () => reviewQueue(planIds()), bugs: () => bugQueue(cfg), prFor, needsInfo: (n, t) => needsInfo(n, t),
575
- unanswered: n => { const me = (gh(['api', 'user']) || {}).login; const repo = repoName(); return Boolean(me && repo) && unanswered(repo, n, me); }, ...d };
585
+ unanswered: n => { const me = (gh(['api', 'user']) || {}).login; const repo = repoName(); return Boolean(me && repo) && unanswered(repo, n, me); },
586
+ // where the build stands, for the status line and status.js --watch: null when it ends
587
+ progress: at => (at ? progress.set('autopilot', { title: 'Unattended build', pid: process.pid, ...at }) : progress.end('autopilot')), ...d };
576
588
  const cfg = settings();
577
589
  const env = cleanEnv(process.env, cfg);
578
590
  const built = [];
@@ -627,14 +639,18 @@ async function build(o, d = {}) {
627
639
  await io.notify('Build: stopped on one', `${id}: ${reason}`);
628
640
  return null;
629
641
  };
630
- for (const p of kinds.includes('reviews') ? io.reviews() : []) {
642
+ const reviews = kinds.includes('reviews') ? io.reviews() : [];
643
+ for (const [i, p] of reviews.entries()) {
644
+ io.progress({ stage: 'review comments', done: i, total: reviews.length, label: `#${p.number}` });
631
645
  end = await other({ id: `review-${p.number}`, branch: () => toBranch(p.headRefName), prompt: `m-review the review comments on pull request #${p.number}`,
632
646
  note: x => unattendedReview(p.number, p.headRefName, x), what: `review comments on pull request #${p.number}`,
633
647
  after: () => (io.unanswered(p.number) ? null : `review-${p.number}: answered`) });
634
648
  if (end) break;
635
649
  }
636
- for (const i of !end && kinds.includes('bugs') ? io.bugs() : []) {
650
+ const bugs = !end && kinds.includes('bugs') ? io.bugs() : [];
651
+ for (const [k, i] of bugs.entries()) {
637
652
  const n = i.number;
653
+ io.progress({ stage: 'bugs', done: k, total: bugs.length, label: `#${n}` });
638
654
  end = await other({ id: `bug-${n}`, branch: () => toBranch(`fix/${n}`, true), prompt: `m-bugfix #${n}`, note: x => unattendedBug(n, x), what: `issue #${n}`,
639
655
  after: () => {
640
656
  const url = io.prFor(`fix/${n}`);
@@ -678,6 +694,7 @@ async function build(o, d = {}) {
678
694
  fs.mkdirSync(path.dirname(log), { recursive: true });
679
695
  fs.appendFileSync(log, `\n=== ${stamp()}: session ${t.sessions} of ${id} (${o.tool}${notes ? ', with notes.md' : ''})\n`);
680
696
  io.log(`${stamp()} ${id}: session ${t.sessions} (${o.tool}), logged in .amk/build/${id}/build.log`);
697
+ io.progress({ stage: 'features', ...planCount(), label: `${id}${t.sessions > 1 ? ` (session ${t.sessions})` : ''}` });
681
698
  const { cmd, args } = TOOLS[o.tool](`m-continue ${id}`, unattended(id, notes), o);
682
699
  const s = await io.session({ id, cmd, args, env, log, stallMs: o.stall * 60e3 });
683
700
  commitHandoff(id);
@@ -718,6 +735,7 @@ async function build(o, d = {}) {
718
735
  fs.mkdirSync(BUILD, { recursive: true });
719
736
  fs.writeFileSync(path.join(BUILD, 'report.md'), `# Build of ${stamp()}\n\n${redact(report)}\n`);
720
737
  io.log(`\n${report}`);
738
+ io.progress(null);
721
739
  await io.notify('Build ended', `${end.reason}. Built: ${built.length}${done.length ? `, reviews and bugs: ${done.length}` : ''}, blocked: ${blocked.length}`);
722
740
  return { end, built, blocked, done };
723
741
  }
@@ -43,8 +43,13 @@ if (payload.hook_event_name === 'SessionStart') {
43
43
  process.exit(0);
44
44
  }
45
45
 
46
- // the turn really ends here (nothing below asks to go on): tell the developer, who may be in another window
47
- const ends = () => { try { require('./notify.js').notify({ ...payload, hook_event_name: 'Stop' }); } catch {} process.exit(0); };
46
+ // the turn really ends here (nothing below asks to go on): the status line hears of it, and the developer, who may be in
47
+ // another window, is told
48
+ const ends = () => {
49
+ try { require('./status.js').mark(payload, { ended: Date.now() }); } catch {}
50
+ try { require('./notify.js').notify({ ...payload, hook_event_name: 'Stop' }); } catch {}
51
+ process.exit(0);
52
+ };
48
53
 
49
54
  if (payload.stop_hook_active && !unattended) ends(); // already reminded once; don't loop
50
55
 
@@ -4,8 +4,10 @@
4
4
  // Google Chat, Discord). Hooks of the AI tool start it:
5
5
  // Notification (Claude Code) a permission prompt, or a reply it has waited a minute for
6
6
  // PermissionRequest (Codex) an approval (Claude Code says those through Notification)
7
- // Stop (every tool) every finished turn, from handoff-check.js once the turn really ends: what it asks
7
+ // Stop (every tool) every finished turn, from handoff-check.js once the turn really ends: what it asks, or
8
+ // (Claude Code) what it waits for, when it ends the turn while something it started runs
8
9
  // AMK_NOTIFY=off turns it off; AMK_NOTIFY=ask keeps the approvals, the waiting and the turns that end with a question.
10
+ // The hook also tells the status line (status.js) that the agent waits for you, whether or not it notifies.
9
11
  // An unattended build (autopilot.js) notifies by itself, so nothing comes from here then.
10
12
  'use strict';
11
13
  const fs = require('fs');
@@ -30,6 +32,7 @@ function lastWords(p) {
30
32
  } catch {}
31
33
  return '';
32
34
  }
35
+ const waiting = (p, words) => { try { const a = require('./status.js').stateOf(p, words); return a && a.state === 'waiting' ? a : null; } catch { return null; } };
33
36
  const toolOf = (p, env) => (/[\\/]\.claude[\\/]/.test(p.transcript_path || '') || env.CLAUDECODE ? 'Claude Code'
34
37
  : /[\\/]\.codex[\\/]/.test(p.transcript_path || '') ? 'Codex' : 'The AI');
35
38
 
@@ -47,7 +50,12 @@ function message(p, env = process.env) {
47
50
  return { title: `${project}: ${tool} needs your approval`, text: String(input.command || input.file_path || p.tool_name || 'a command') };
48
51
  }
49
52
  if (event !== 'Stop') return null;
50
- const lines = lastWords(p).split('\n').map(l => l.replace(/[*_`#>]/g, '').trim()).filter(Boolean);
53
+ const words = lastWords(p);
54
+ // a turn that ends while what it started still runs (a command in the background, a subagent): Claude Code goes on
55
+ // by itself when that ends, as its log says
56
+ const a = tool === 'Claude Code' ? waiting(p, words) : null;
57
+ if (a) return mode === 'ask' ? null : { title: `${project}: ${tool} is waiting for ${a.pending[0].what}`, text: 'It goes on by itself when that ends: nothing is needed from you now.' };
58
+ const lines = words.split('\n').map(l => l.replace(/[*_`#>]/g, '').trim()).filter(Boolean);
51
59
  const question = lines.filter(l => /\?$/.test(l)).pop() || lines.find(l => /\bapprov/i.test(l));
52
60
  if (mode === 'ask' && !question) return null;
53
61
  return { title: `${project}: ${tool} ${question ? 'asks you' : 'finished'}`, text: question || lines[0] || 'Its turn is over.' };
@@ -75,10 +83,15 @@ function send(n, env = process.env) {
75
83
  }
76
84
 
77
85
  const notify = (p, env = process.env) => { const n = message(p, env); if (n) send(n, env); return n; };
78
- // a hook's own start: its payload on stdin
86
+ // a hook's own start: its payload on stdin. The status line hears of it too: a reply Claude Code has waited a minute
87
+ // for means the turn is over; anything else (a permission prompt, Codex's approvals) waits for you until the next step
79
88
  function hook() {
80
89
  let p = {};
81
90
  try { p = JSON.parse(fs.readFileSync(0, 'utf8')); } catch {}
91
+ try {
92
+ const idle = p.notification_type === 'idle_prompt' || /waiting for your input/i.test(p.message || '');
93
+ require('./status.js').mark(p, idle ? { ended: Date.now() } : { attention: { at: Date.now(), text: String(p.message || (p.tool_input || {}).command || 'your approval').slice(0, 200) } });
94
+ } catch {}
82
95
  notify(p);
83
96
  }
84
97
 
@@ -20,6 +20,7 @@ const path = require('path');
20
20
  const { spawnSync } = require('child_process');
21
21
  const { untrusted } = require('./redact.js');
22
22
  const specs = require('./specs.js');
23
+ const progress = require('./progress.js');
23
24
 
24
25
  const ROOT = path.join(__dirname, '..', '..');
25
26
  const read = f => { try { return fs.readFileSync(f, 'utf8').replace(/\r\n/g, '\n'); } catch { return null; } };
@@ -36,8 +37,12 @@ const IO = {
36
37
  ghText: args => { const r = sh('gh', args, { timeout: 120000 }); return r.status === 0 ? r.stdout : null; },
37
38
  ghRun: args => sh('gh', args, { timeout: 120000 }),
38
39
  sleep: ms => new Promise(r => setTimeout(r, ms)),
39
- // where a wait stands, under .amk/: autopilot.js's stall watchdog counts a change there as activity
40
- note: t => { try { fs.mkdirSync(path.join(ROOT, '.amk'), { recursive: true }); fs.writeFileSync(path.join(ROOT, '.amk/pr-checks.txt'), `${new Date().toISOString()} ${t}\n`); } catch {} },
40
+ // where a wait stands, under .amk/: autopilot.js's stall watchdog counts a change there as activity, and the status
41
+ // line shows how many checks are done (progress.js)
42
+ note: (t, at) => {
43
+ try { fs.mkdirSync(path.join(ROOT, '.amk'), { recursive: true }); fs.writeFileSync(path.join(ROOT, '.amk/pr-checks.txt'), `${new Date().toISOString()} ${t}\n`); } catch {}
44
+ if (at) progress.set('pr-checks', { title: 'CI', pid: process.pid, ...at });
45
+ },
41
46
  now: Date.now,
42
47
  log: t => console.log(t),
43
48
  };
@@ -77,7 +82,8 @@ async function checks(branch, { waitMs = 30 * 60e3, pollMs = 30e3, firstMs = 3 *
77
82
  for (;;) {
78
83
  list = checkList(pr, io);
79
84
  const pending = list.filter(c => c.bucket === 'pending');
80
- io.note(`${pr.url}: ${list.length ? `waiting for ${pending.map(c => c.name).join(', ')}` : 'no checks reported yet'}`);
85
+ io.note(`${pr.url}: ${list.length ? `waiting for ${pending.map(c => c.name).join(', ')}` : 'no checks reported yet'}`,
86
+ { stage: `PR #${pr.number}`, done: list.length - pending.length, total: list.length, label: pending.length ? `waiting for ${pending[0].name}${pending.length > 1 ? ` and ${pending.length - 1} more` : ''}` : 'no checks reported yet' });
81
87
  if (list.length && !pending.length) break;
82
88
  // a repository without CI never reports any: after a few minutes, there's nothing to wait for
83
89
  if (!list.length && io.now() - start >= firstMs) { io.log(`No checks reported on ${pr.url}: nothing to wait for.`); return 0; }
@@ -233,7 +239,7 @@ if (require.main === module) {
233
239
  const branch = named || branchNow();
234
240
  const main = specs.mainRef();
235
241
  const done = c => { process.exitCode = c; };
236
- if (cmd === 'checks') checks(branch, { waitMs: (parseFloat(opt('--wait')) || 30) * 60e3 }).then(done);
242
+ if (cmd === 'checks') checks(branch, { waitMs: (parseFloat(opt('--wait')) || 30) * 60e3 }).then(c => { progress.end('pr-checks', c === 0 ? 'passed' : ''); done(c); });
237
243
  else if (cmd === 'automerge') done(automerge(branch, main));
238
244
  else if (cmd === 'comments') done(comments(branch));
239
245
  else if (cmd === 'forward') done(forward(main));
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env node
2
+ // Where the kit's long runs stand, for the status line and `node scripts/amk/status.js --watch`: a small JSON file per
3
+ // run in .amk/progress/ (what it is, its stage, how far: done of total, what it's on, since when), written as it goes,
4
+ // and the length of the last run of each kind that passed, as a guide to how long the next one takes.
5
+ // node scripts/amk/progress.js set <key> --pid <pid> --title <title> [--kind <k>] [--stage <s>] [--done <n>] [--total <n>] [--label <l>]
6
+ // node scripts/amk/progress.js end <key> [--result passed|failed] or, for every run of a process, end-pid <pid>
7
+ // A run whose process is gone (killed, crashed) is left out when it's read, and its file removed.
8
+ 'use strict';
9
+ const fs = require('fs');
10
+ const path = require('path');
11
+
12
+ const DIR = path.join(__dirname, '..', '..', '.amk', 'progress');
13
+ const HISTORY = path.join(DIR, 'history.json');
14
+ const file = key => path.join(DIR, `${String(key).replace(/[^A-Za-z0-9._-]/g, '_')}.json`);
15
+ const readJson = f => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
16
+ // written whole: a reader never sees half a file
17
+ function writeJson(f, value) {
18
+ fs.mkdirSync(path.dirname(f), { recursive: true });
19
+ const tmp = `${f}.${process.pid}.tmp`;
20
+ fs.writeFileSync(tmp, `${JSON.stringify(value)}\n`);
21
+ fs.renameSync(tmp, f);
22
+ }
23
+ const alive = pid => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
24
+
25
+ // a run's record: kept from the last call, so a stage can change without repeating the title
26
+ function set(key, fields, now = Date.now()) {
27
+ const was = readJson(file(key)) || {};
28
+ // a new stage starts its own count
29
+ const fresh = fields.stage !== undefined && fields.stage !== was.stage;
30
+ const kept = fresh ? (({ done, total, label, ...rest }) => rest)(was) : was;
31
+ const next = { ...kept, ...fields, key, started: was.started || now, updated: now };
32
+ if (fresh) next.stageStarted = now;
33
+ if (!next.pid) next.pid = process.pid;
34
+ try { writeJson(file(key), next); } catch {}
35
+ return next;
36
+ }
37
+ // done: the record goes, and how long it took, when it passed, stays as the guide for its kind (one that failed or
38
+ // stopped part of the way says little about the next)
39
+ function end(key, result, now = Date.now()) {
40
+ const r = readJson(file(key));
41
+ try { fs.rmSync(file(key), { force: true }); } catch {}
42
+ if (!r || result !== 'passed') return r;
43
+ const history = readJson(HISTORY) || {};
44
+ history[r.kind || r.title] = { ms: now - r.started, at: now };
45
+ try { writeJson(HISTORY, history); } catch {}
46
+ return r;
47
+ }
48
+ const endPid = pid => runs({ all: true }).filter(r => String(r.pid) === String(pid)).map(r => end(r.key));
49
+
50
+ // the runs going on now, oldest first, each with its kind's last length; those whose process is gone are cleared away
51
+ function runs({ all = false } = {}) {
52
+ let names = [];
53
+ try { names = fs.readdirSync(DIR).filter(f => f.endsWith('.json') && f !== 'history.json'); } catch { return []; }
54
+ const history = readJson(HISTORY) || {};
55
+ return names.map(f => readJson(path.join(DIR, f))).filter(Boolean).filter(r => {
56
+ if (all || alive(r.pid)) return true;
57
+ try { fs.rmSync(file(r.key), { force: true }); } catch {}
58
+ return false;
59
+ }).map(r => ({ ...r, last: history[r.kind || r.title] || null })).sort((a, b) => a.started - b.started);
60
+ }
61
+
62
+ module.exports = { set, end, endPid, runs, writeJson, DIR };
63
+
64
+ if (require.main === module) {
65
+ const [cmd, key, ...rest] = process.argv.slice(2);
66
+ const opt = n => (rest.includes(`--${n}`) ? rest[rest.indexOf(`--${n}`) + 1] : undefined);
67
+ const num = n => (opt(n) === undefined ? undefined : Number(opt(n)));
68
+ if (cmd === 'set' && key) {
69
+ const fields = { title: opt('title'), kind: opt('kind'), stage: opt('stage'), label: opt('label'), done: num('done'), total: num('total'), pid: num('pid') };
70
+ set(key, Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined && !Number.isNaN(v))));
71
+ } else if (cmd === 'end' && key) end(key, opt('result'));
72
+ else if (cmd === 'end-pid' && key) endPid(key);
73
+ else { console.error('usage: progress.js set <key> --pid <pid> --title <title> [--kind k] [--stage s] [--done n] [--total n] [--label l] | end <key> [--result passed] | end-pid <pid>'); process.exitCode = 2; }
74
+ }
@@ -0,0 +1,240 @@
1
+ #!/usr/bin/env node
2
+ // What's going on in this project, at a glance: whether the AI agent is working, is waiting for something it started
3
+ // (a command in the background, a subagent: it goes on by itself when that ends), or is waiting for you; the feature's
4
+ // tasks (specs/<id>/tasks.md); and where the kit's long runs stand (scripts/amk/progress.js: device and quick checks, CI,
5
+ // an unattended build), with how long the last one of each took.
6
+ // Claude Code's status line runs it (statusLine in .claude/settings.json, every 2 seconds): a developer's own status
7
+ // line first, when they have one, then the kit's lines. AMK_STATUS=off leaves the kit's lines out.
8
+ // node scripts/amk/status.js the status, once
9
+ // node scripts/amk/status.js --watch every 2 seconds, in a terminal of its own: with any AI tool
10
+ // The agent's state comes from Claude Code's session log (for --watch, the newest of this project) and its hooks: other
11
+ // tools show the tasks and the runs.
12
+ 'use strict';
13
+ const fs = require('fs');
14
+ const os = require('os');
15
+ const path = require('path');
16
+ const { Buffer } = require('buffer');
17
+ const { execFileSync, spawnSync } = require('child_process');
18
+ const progress = require('./progress.js');
19
+
20
+ const root = path.join(__dirname, '..', '..');
21
+ const project = path.basename(root);
22
+ const STATE = path.join(root, '.amk', 'state');
23
+ const TAIL = 4 * 2 ** 20; // a session's first look reads at most this much of its end
24
+ const STALE = 6 * 3600e3; // something in the background not heard of for this long is taken as gone
25
+ const readJson = f => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
26
+ const save = (f, v) => { try { progress.writeJson(f, v); } catch {} };
27
+ const git = (...a) => { try { return execFileSync('git', a, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
28
+ const off = (env = process.env) => ['off', '0', 'no', 'false'].includes(String(env.AMK_STATUS || '').toLowerCase());
29
+ const idOf = (transcript, id) => String(id || path.basename(String(transcript || ''), '.jsonl')).replace(/[^A-Za-z0-9_-]/g, '_');
30
+
31
+ // ---------- the agent, from Claude Code's session log ----------
32
+ // the question a message ends with (its last line asking something), or an approval it asks for
33
+ function asks(text) {
34
+ const lines = String(text || '').split('\n').map(l => l.replace(/[*_`#>]/g, '').trim()).filter(Boolean);
35
+ return lines.filter(l => /\?$/.test(l)).pop() || lines.find(l => /\bapprov/i.test(l)) || '';
36
+ }
37
+ const what = p => { const i = p.input || {}; return String(i.description || i.command || i.prompt || p.name).split('\n')[0].slice(0, 80); };
38
+ // one record of the log: what the agent did last, and what it started in the background and hasn't heard back from
39
+ function take(s, line) {
40
+ let e;
41
+ try { e = JSON.parse(line); } catch { return; }
42
+ if (e.isSidechain) return; // a subagent's own records
43
+ const at = Date.parse(e.timestamp) || null;
44
+ const content = e.message && e.message.content;
45
+ // a background job's news: as a prompt of its own, or added to a turn under way. Its end has a status (completed,
46
+ // failed, stopped); a watcher's (Monitor's) events have none, and it goes on
47
+ const note = e.type === 'user' && typeof content === 'string' ? content
48
+ : e.type === 'attachment' && e.attachment && typeof e.attachment.prompt === 'string' ? e.attachment.prompt : '';
49
+ if (/^\s*<task-notification>/.test(note)) {
50
+ const id = (/<task-id>([^<]+)<\/task-id>/.exec(note) || [])[1];
51
+ if (id && /<status>(?!running)\w+<\/status>/.test(note)) delete s.pending[id];
52
+ }
53
+ if (e.type === 'assistant' && Array.isArray(content)) {
54
+ for (const p of content) {
55
+ if (p.type === 'tool_use') {
56
+ s.uses[p.id] = what(p);
57
+ const q = p.name === 'AskUserQuestion' && (((p.input || {}).questions || [])[0] || {}).question;
58
+ s.last = { kind: 'tool', name: p.name, at, ...(q ? { ask: String(q).slice(0, 200) } : {}) };
59
+ } else if (p.type === 'text' && String(p.text).trim()) s.last = { kind: 'text', text: String(p.text).slice(-2000), at };
60
+ }
61
+ } else if (e.type === 'user' && typeof content === 'string') s.last = { kind: 'prompt', at };
62
+ else if (e.type === 'user' && Array.isArray(content)) {
63
+ for (const p of content) {
64
+ if (p.type === 'tool_result') {
65
+ const r = e.toolUseResult || {};
66
+ const job = r.backgroundTaskId || (r.status === 'async_launched' && r.agentId) || r.taskId;
67
+ if (job) s.pending[job] = { what: String(r.description || s.uses[p.tool_use_id] || 'a command').slice(0, 80), at };
68
+ delete s.uses[p.tool_use_id];
69
+ s.last = { kind: 'result', at };
70
+ } else if (p.type === 'text') s.last = { kind: /^\[Request interrupted by user/.test(p.text || '') ? 'stopped' : 'prompt', at };
71
+ }
72
+ }
73
+ }
74
+ // the session as its log says now: read on from where the last look stopped (kept in .amk/state/), whole lines only
75
+ function session(transcript, id) {
76
+ let size;
77
+ try { size = fs.statSync(transcript).size; } catch { return null; }
78
+ const cache = path.join(STATE, `session-${idOf(transcript, id)}.json`);
79
+ let s = readJson(cache);
80
+ if (!s || s.path !== transcript || s.offset > size) s = { path: transcript, offset: Math.max(0, size - TAIL), pending: {}, uses: {}, last: null, cut: true };
81
+ if (size > s.offset) {
82
+ const buf = Buffer.alloc(size - s.offset);
83
+ const fd = fs.openSync(transcript, 'r');
84
+ try { fs.readSync(fd, buf, 0, buf.length, s.offset); } finally { fs.closeSync(fd); }
85
+ const end = buf.lastIndexOf(10);
86
+ if (end >= 0) {
87
+ let lines = buf.subarray(0, end + 1).toString('utf8').split('\n');
88
+ if (s.cut && s.offset > 0) lines = lines.slice(1); // the first look starts inside a line
89
+ for (const l of lines) if (l) take(s, l);
90
+ s.offset += end + 1;
91
+ s.cut = false;
92
+ const uses = Object.entries(s.uses);
93
+ if (uses.length > 50) s.uses = Object.fromEntries(uses.slice(-50));
94
+ save(cache, s);
95
+ }
96
+ }
97
+ return s;
98
+ }
99
+ // what the hooks saw that the log doesn't say: the turn ended (Stop), or Claude Code asks for a permission
100
+ const marksFile = (transcript, id) => path.join(STATE, `marks-${idOf(transcript, id)}.json`);
101
+ const marks = (transcript, id) => readJson(marksFile(transcript, id)) || {};
102
+ function mark(p, fields) {
103
+ if (!p.transcript_path && !p.session_id) return;
104
+ save(marksFile(p.transcript_path, p.session_id), { ...marks(p.transcript_path, p.session_id), ...fields });
105
+ }
106
+ // working, waiting (for what it started: it goes on by itself), asks (you), stopped (you stopped it), or done
107
+ function agentState(s, m = {}, now = Date.now(), lastWords = null) {
108
+ if (!s || !s.last) return null;
109
+ const pending = Object.values(s.pending || {}).filter(p => !p.at || now - p.at < STALE).sort((a, b) => (a.at || 0) - (b.at || 0));
110
+ const l = s.last;
111
+ const at = l.at || 0;
112
+ if (l.kind === 'tool' && l.name === 'AskUserQuestion') return { state: 'asks', text: l.ask || 'a question', pending, at };
113
+ if (m.attention && m.attention.at >= at) return { state: 'asks', text: m.attention.text, pending, at: m.attention.at };
114
+ const over = l.kind === 'stopped' || (m.ended && m.ended >= at) || lastWords !== null;
115
+ if (!over) return { state: 'working', pending, at };
116
+ if (pending.length) return { state: 'waiting', pending, at };
117
+ if (l.kind === 'stopped') return { state: 'stopped', pending, at };
118
+ const q = asks(lastWords !== null ? lastWords : l.kind === 'text' ? l.text : '');
119
+ return q ? { state: 'asks', text: q, pending, at } : { state: 'done', pending, at };
120
+ }
121
+ const stateOf = (p, lastWords = null) => agentState(session(p.transcript_path, p.session_id), marks(p.transcript_path, p.session_id), Date.now(), lastWords);
122
+ // the newest Claude Code session log of this project (Claude Code names its folder after the project's path)
123
+ function newestTranscript(dir = root, home = os.homedir()) {
124
+ try {
125
+ const base = path.join(process.env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'projects', fs.realpathSync(dir).replace(/[^a-zA-Z0-9]/g, '-'));
126
+ return fs.readdirSync(base).filter(f => f.endsWith('.jsonl')).map(f => path.join(base, f))
127
+ .map(f => [f, fs.statSync(f).mtimeMs]).sort((a, b) => b[1] - a[1]).map(x => x[0])[0] || null;
128
+ } catch { return null; }
129
+ }
130
+
131
+ // ---------- the feature's tasks ----------
132
+ function readText(f) { try { return fs.readFileSync(f, 'utf8'); } catch { return ''; } }
133
+ // the feature of this branch (feature/<id>, fix/<id>), else the spec in progress updated last
134
+ function tasks() {
135
+ const specs = path.join(root, 'specs');
136
+ const id0 = (/^(?:feature|fix)\/(.+)$/.exec(git('symbolic-ref', '--quiet', '--short', 'HEAD')) || [])[1];
137
+ let id = id0 && fs.existsSync(path.join(specs, id0, 'tasks.md')) ? id0 : null;
138
+ if (!id) {
139
+ let dirs = [];
140
+ try { dirs = fs.readdirSync(specs).filter(d => d !== '_templates' && d !== 'current'); } catch {}
141
+ id = dirs.map(d => path.join(specs, d, 'progress.md')).filter(f => /^Status:\s*in progress/im.test(readText(f)))
142
+ .map(f => [f, fs.statSync(f).mtimeMs]).sort((a, b) => b[1] - a[1]).map(([f]) => path.basename(path.dirname(f)))[0] || null;
143
+ }
144
+ if (!id) return null;
145
+ const items = [...readText(path.join(specs, id, 'tasks.md')).matchAll(/^\s*- \[([ xX])\]\s*(.*)$/gm)]
146
+ .map(m => ({ done: m[1] !== ' ', title: m[2].replace(/^\d+[.)]\s*/, '').split(/\s+—\s+/)[0].trim() }));
147
+ if (!items.length) return null;
148
+ const done = items.filter(t => t.done).length;
149
+ return { id, done, total: items.length, current: (items.find(t => !t.done) || {}).title || '', items };
150
+ }
151
+
152
+ // ---------- the view ----------
153
+ const C = { dim: s => `\x1b[2m${s}\x1b[22m`, yellow: s => `\x1b[33m${s}\x1b[39m`, magenta: s => `\x1b[35m${s}\x1b[39m`, green: s => `\x1b[32m${s}\x1b[39m`, cyan: s => `\x1b[36m${s}\x1b[39m` };
154
+ const plain = s => s.replace(/\x1b\[[0-9;]*m/g, '');
155
+ // a line cut to the width, its colours kept
156
+ function fit(s, width) {
157
+ if (!width || [...plain(s)].length <= width) return s;
158
+ let out = '';
159
+ let n = 0;
160
+ for (const part of s.split(/(\x1b\[[0-9;]*m)/)) {
161
+ if (/^\x1b\[/.test(part)) { out += part; continue; }
162
+ const chars = [...part].slice(0, Math.max(0, width - 1 - n));
163
+ out += chars.join('');
164
+ n += chars.length;
165
+ }
166
+ return `${out}…\x1b[0m`;
167
+ }
168
+ const ago = (from, now = Date.now()) => {
169
+ const s = Math.max(0, Math.round((now - from) / 1000));
170
+ return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s` : `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}m`;
171
+ };
172
+ const bar = (done, total, w = 5) => { const n = Math.round((done / total) * w); return `${'▰'.repeat(n)}${'▱'.repeat(w - n)}`; };
173
+ // the agent's line; plain work isn't one under Claude Code's prompt, where its spinner says so
174
+ function agentLine(a, now = Date.now(), always = false) {
175
+ if (!a) return '';
176
+ const first = a.pending[0];
177
+ const more = a.pending.length > 1 ? ` and ${a.pending.length - 1} more` : '';
178
+ if (a.state === 'waiting') return `${C.yellow('⏳ Waiting')} for ${first.what}${first.at ? ` (${ago(first.at, now)})` : ''}${more} ${C.dim('· goes on by itself when that ends')}`;
179
+ if (a.state === 'asks') return `${C.magenta('❓ Needs you:')} ${a.text}`;
180
+ if (a.state === 'stopped') return `${C.cyan('⏸ Stopped')} ${C.dim('· your turn')}`;
181
+ if (a.state === 'done') return `${C.green('✓ Done')} ${C.dim('· your turn')}`;
182
+ if (first) return `${C.cyan('▶ Working')} ${C.dim(`· ${first.what} running in the background${more}`)}`;
183
+ return always ? C.cyan('▶ Working') : '';
184
+ }
185
+ const runLine = (r, now = Date.now()) => `${r.title}${r.stage ? `: ${r.stage}` : ''}${r.total ? ` ${r.done || 0}/${r.total}` : ''}${r.label ? ` ${r.label}` : ''} ${C.dim(`${ago(r.started, now)}${r.last ? ` (last ${ago(0, r.last.ms)})` : ''}`)}`;
186
+ const taskLine = t => `${t.id} ${bar(t.done, t.total)} ${t.done}/${t.total} tasks${t.current ? ` ${C.dim(`· ${t.current}`)}` : ''}`;
187
+
188
+ // the kit's lines under the prompt: the agent, then the feature's tasks and the runs
189
+ function lines({ transcript = null, sessionId = null, now = Date.now(), width = 0 } = {}) {
190
+ const a = transcript ? agentState(session(transcript, sessionId), marks(transcript, sessionId), now) : null;
191
+ const t = tasks();
192
+ const work = [t && taskLine(t), ...progress.runs().map(r => runLine(r, now))].filter(Boolean);
193
+ return [agentLine(a, now), work.join(C.dim(' · '))].filter(Boolean).map(l => fit(l, width));
194
+ }
195
+
196
+ // Claude Code's status line: the developer's own first (the project's setting replaces theirs), then the kit's
197
+ function ownStatusLine(input, env = process.env) {
198
+ const own = (readJson(path.join(env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude'), 'settings.json')) || {}).statusLine;
199
+ if (!own || own.type !== 'command' || !own.command || /scripts\/amk\/status\.js/.test(own.command)) return '';
200
+ // ponytail: through the system shell; a Windows status line written for Git Bash doesn't run here
201
+ const r = spawnSync(own.command, { shell: true, input, encoding: 'utf8', timeout: 1500, env });
202
+ return (r.stdout || '').replace(/\r\n/g, '\n').replace(/\n+$/, ''); // a Windows command's lines end in \r\n
203
+ }
204
+ function statusLine() {
205
+ let input = '';
206
+ try { input = fs.readFileSync(0, 'utf8'); } catch {}
207
+ let p = {};
208
+ try { p = JSON.parse(input); } catch {}
209
+ const out = [ownStatusLine(input)];
210
+ if (!off()) out.push(...lines({ transcript: p.transcript_path, sessionId: p.session_id, width: Number(process.env.COLUMNS) || 0 }));
211
+ process.stdout.write(`${out.filter(Boolean).join('\n')}\n`);
212
+ }
213
+
214
+ // once, or every 2 seconds in a terminal of its own, with any AI tool
215
+ function full({ now = Date.now(), transcript = newestTranscript() } = {}) {
216
+ const a = transcript ? agentState(session(transcript), marks(transcript), now) : null;
217
+ const t = tasks();
218
+ const out = [`${project} ${C.dim(`· ${new Date(now).toLocaleTimeString()}`)}`, ''];
219
+ out.push(a ? `${agentLine(a, now, true)}${a.at ? C.dim(` · ${ago(a.at, now)} ago`) : ''}` : C.dim('The agent: shown for Claude Code sessions. Other tools: the tasks and the checks below.'));
220
+ if (a && a.pending.length > 1) for (const p of a.pending) out.push(C.dim(` ⏳ ${p.what}${p.at ? ` (${ago(p.at, now)})` : ''}`));
221
+ if (t) {
222
+ out.push('', `${t.id}: ${t.done} of ${t.total} tasks done ${bar(t.done, t.total, 10)}`);
223
+ const next = t.items.findIndex(x => !x.done);
224
+ t.items.forEach((x, i) => out.push(` ${x.done ? C.green('✓') : i === next ? C.cyan('▶') : C.dim('○')} ${x.done ? C.dim(x.title) : x.title}`));
225
+ }
226
+ const runs = progress.runs();
227
+ if (runs.length) out.push('', ...runs.map(r => `${runLine(r, now)}${r.total ? ` ${bar(r.done || 0, r.total, 10)}` : ''}`));
228
+ if (!t && !runs.length && !a) out.push(C.dim('Nothing in progress.'));
229
+ return out.join('\n');
230
+ }
231
+
232
+ module.exports = { asks, take, session, marks, mark, agentState, stateOf, newestTranscript, tasks, lines, statusLine, ownStatusLine, full, fit, ago };
233
+
234
+ if (require.main === module) {
235
+ if (process.argv.includes('--watch')) {
236
+ const draw = () => process.stdout.write(`\x1b[H\x1b[2J${full()}\n${C.dim('\nEvery 2 seconds. Ctrl+C to stop.')}\n`);
237
+ draw();
238
+ setInterval(draw, 2000);
239
+ } else console.log(full());
240
+ }
@@ -5,6 +5,10 @@
5
5
  // Antigravity rejects, dropping the whole hook set, the guard included
6
6
  // - Codex asks with options to pick from (request_user_input) in every mode, not only in plan mode: rulesync writes no
7
7
  // [features] table, and Codex reads it from the project's config once the folder is trusted
8
+ // - Codex shows its plan as a checklist while it works (update_plan, off since Codex 0.152), in step with the spec's tasks
9
+ // - Claude Code shows what's going on under the prompt (scripts/amk/status.js, every 2 seconds), the spec's tasks
10
+ // included. rulesync has no statusLine, and keeps it once it's there. A team's own status line in the project's
11
+ // settings stays
8
12
  // Usage: node scripts/amk/tool-configs.js (in the project's folder)
9
13
  'use strict';
10
14
  const fs = require('fs');
@@ -34,8 +38,27 @@ function codexQuestions(dir) {
34
38
  : `${text.replace(/\n*$/, '\n')}\n# agentic-mobile-kit: questions as options to pick from, in every mode\n[features]\n${on}\n`);
35
39
  }
36
40
 
37
- const afterGenerate = dir => { flattenAntigravityStop(dir); codexQuestions(dir); };
41
+ function codexPlan(dir) {
42
+ const file = path.join(dir, '.codex/config.toml');
43
+ const text = read(file);
44
+ if (text === null || /^[^#\n]*\bupdate_plan\b/m.test(text)) return;
45
+ fs.writeFileSync(file, `${text.replace(/\n*$/, '\n')}\n# agentic-mobile-kit: the plan as a checklist while it works, in step with the spec's tasks\n[tools.update_plan]\nenabled = true\n`);
46
+ }
47
+
48
+ // found from wherever Claude Code runs it, as the hooks are (.rulesync/hooks.jsonc)
49
+ const STATUS_LINE = { type: 'command', command: "node -e \"require(require('child_process').execSync('git rev-parse --show-toplevel').toString().trim() + '/scripts/amk/status.js').statusLine()\"", refreshInterval: 2 };
50
+ function claudeStatus(dir) {
51
+ const file = path.join(dir, '.claude/settings.json');
52
+ let settings;
53
+ try { settings = JSON.parse(read(file)); } catch { return; }
54
+ if (!settings || typeof settings !== 'object') return;
55
+ const before = JSON.stringify(settings);
56
+ if (!settings.statusLine || /scripts\/amk\/status\.js/.test(settings.statusLine.command || '')) settings.statusLine = STATUS_LINE;
57
+ if (JSON.stringify(settings) !== before) fs.writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
58
+ }
59
+
60
+ const afterGenerate = dir => { flattenAntigravityStop(dir); codexQuestions(dir); codexPlan(dir); claudeStatus(dir); };
38
61
 
39
- module.exports = { afterGenerate, flattenAntigravityStop, codexQuestions };
62
+ module.exports = { afterGenerate, flattenAntigravityStop, codexQuestions, codexPlan, claudeStatus, STATUS_LINE };
40
63
 
41
64
  if (require.main === module) afterGenerate(process.cwd());
@@ -246,7 +246,28 @@ unclaim() { l=$(lock_path "$1"); rm -f "$l/owner"; rmdir "$l" 2> /dev/null || tr
246
246
  release() { for l in $held; do rm -f "$l/owner"; rmdir "$l" 2> /dev/null || true; done; held=""; }
247
247
  temps="" # the temporary devices this run made for a part of the flows (--part), deleted at its end
248
248
  tree_flow="" # the copy of a flow with view-tree steps (Android), next to it while it runs
249
- trap 'release; drop_temps; [ -z "$tree_flow" ] || rm -f "$tree_flow"' EXIT
249
+ # where this run stands, for the status line and node scripts/amk/status.js --watch: a record per check in
250
+ # .amk/progress/ (scripts/amk/progress.js), gone when the check ends. Git Bash's $$ isn't the process ID node sees
251
+ me=$$
252
+ [ ! -r "/proc/$$/winpid" ] || me=$(cat "/proc/$$/winpid")
253
+ step() { # quick, ios or android; its stage; for the flows: how many ran, of how many, and the one running
254
+ step_title="Quick check" step_kind=quick-$related
255
+ case $1 in
256
+ ios | android)
257
+ step_title=iOS
258
+ [ "$1" = ios ] || step_title=Android
259
+ if [ "$build_only" = 1 ]; then step_title="$step_title build"; else step_title="$step_title check${part:+ part $part}"; fi
260
+ step_kind=$1-$build_only$no_build${part:+-part} ;;
261
+ esac
262
+ if [ -n "${3:-}" ]; then
263
+ node "$root/scripts/amk/progress.js" set "verify-$1-$me" --pid "$me" --title "$step_title" --kind "$step_kind" --stage "$2" --done "$3" --total "$4" --label "$5"
264
+ else
265
+ node "$root/scripts/amk/progress.js" set "verify-$1-$me" --pid "$me" --title "$step_title" --kind "$step_kind" --stage "$2"
266
+ fi > /dev/null 2>&1 || true
267
+ }
268
+ # its length is kept as a guide for the next of its kind when it passed
269
+ finish() { node "$root/scripts/amk/progress.js" end "verify-$1-$me" --result "$([ "$status" = 0 ] && echo passed || echo failed)" > /dev/null 2>&1 || true; }
270
+ trap 'release; drop_temps; [ -z "$tree_flow" ] || rm -f "$tree_flow"; node "$root/scripts/amk/progress.js" end-pid "$me" > /dev/null 2>&1 || true' EXIT
250
271
  trap 'exit 130' INT TERM
251
272
  holder() {
252
273
  l=$(lock_path "$1")
@@ -435,9 +456,13 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
435
456
  passed=0
436
457
  total=0
437
458
  flakies=0
459
+ count=$(echo $files | wc -w | tr -d ' ')
460
+ view=${1#"${1%%-*}"}
461
+ case $view in '') view=phone ;; -landscape) view="phone landscape" ;; *) view=$(echo "${view#-}" | tr - ' ') ;; esac
438
462
  for f in $files; do
439
463
  total=$((total + 1))
440
464
  name=$(basename "$f" .yaml)
465
+ step "${1%%-*}" "$view" $((total - 1)) "$count" "$name"
441
466
  ok=0 why="" shot="" first=""
442
467
  # an earlier run's first try, when the flow was flaky then
443
468
  [ ! -d "$evidence/maestro-logs/$1-$name-first-try" ] || rm -r "$evidence/maestro-logs/$1-$name-first-try"
@@ -601,9 +626,9 @@ check_screens() { # platform phone tablet app_id screens…
601
626
 
602
627
  quick() {
603
628
  # each one passes when the app's script passes, or when all its failures were already on the base branch
604
- if node scripts/amk/baseline.js lint > "$evidence/lint.log" 2>&1 &&
605
- node scripts/amk/baseline.js typecheck > "$evidence/typecheck.log" 2>&1 &&
606
- node scripts/amk/baseline.js test $([ "$related" = 0 ] || echo --related) > "$evidence/test.log" 2>&1; then
629
+ if step quick lint && node scripts/amk/baseline.js lint > "$evidence/lint.log" 2>&1 &&
630
+ step quick typecheck && node scripts/amk/baseline.js typecheck > "$evidence/typecheck.log" 2>&1 &&
631
+ step quick tests && node scripts/amk/baseline.js test $([ "$related" = 0 ] || echo --related) > "$evidence/test.log" 2>&1; then
607
632
  if [ "$related" = 0 ]; then echo "quick: lint, typecheck and tests passed"; else echo "quick: lint, typecheck and the tests related to this branch's changes passed"; fi
608
633
  # what didn't run (no such script, or an Expo app without ESLint yet), and failures the base branch already had
609
634
  cat "$evidence/lint.log" "$evidence/typecheck.log" "$evidence/test.log" |
@@ -615,6 +640,7 @@ quick() {
615
640
  fi
616
641
  # React Native mistakes in the lines this branch changed (the app's rules list them): its problems fail quick, its
617
642
  # warnings don't
643
+ step quick "React Native check"
618
644
  node scripts/amk/rn-check.js > "$evidence/rn-check.log" 2>&1 || status=1
619
645
  head -n 40 "$evidence/rn-check.log"
620
646
  [ "$(wc -l < "$evidence/rn-check.log")" -le 40 ] || echo " … all of it in ${evidence#"$root"/}/rn-check.log"
@@ -629,6 +655,7 @@ ios() {
629
655
  fi
630
656
  [ "$build_only" = 1 ] || command -v maestro > /dev/null || { echo "ios: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
631
657
  same_api ios || { status=1; return; }
658
+ step ios "$([ "$no_build" = 1 ] && echo devices || echo build)"
632
659
  if [ "$no_build" = 0 ]; then
633
660
  # Expo apps without native folders in git: generate ios/ first
634
661
  if ! sh scripts/amk/prebuild.sh ios > "$evidence/prebuild-ios.log" 2>&1; then
@@ -704,6 +731,7 @@ ios() {
704
731
  echo "ios: there's no build to check yet: run sh scripts/amk/verify.sh build first"; status=1; return
705
732
  fi
706
733
  app_id=$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$a/Info.plist")
734
+ step ios installing
707
735
  for d in $device $tablet; do
708
736
  if is_real "$d"; then
709
737
  launch_check "$d" || { status=1; return; }
@@ -982,6 +1010,7 @@ android_ready() {
982
1010
  android() {
983
1011
  [ "$build_only" = 1 ] || command -v maestro > /dev/null || { echo "android: Maestro isn't installed (https://maestro.dev)"; status=1; return; }
984
1012
  same_api android || { status=1; return; }
1013
+ step android "$([ "$no_build" = 1 ] && echo devices || echo build)"
985
1014
  case $(uname -s) in # where Android Studio puts the SDK by default
986
1015
  Darwin) default_sdk=$HOME/Library/Android/sdk ;;
987
1016
  MINGW* | MSYS* | CYGWIN*) default_sdk=${LOCALAPPDATA:-$HOME/AppData/Local}/Android/Sdk ;;
@@ -1092,6 +1121,7 @@ android() {
1092
1121
  aapt2="$(ls -d "$sdk"/build-tools/*/ 2> /dev/null | sort -V | tail -n 1)aapt2"
1093
1122
  app_id=$("$aapt2" dump badging "$apk" 2> /dev/null | sed -n "s/^package: name='\([^']*\)'.*/\1/p")
1094
1123
  [ -n "$app_id" ] || app_id=$(sed -n 's/.*applicationId *=\{0,1\} *"\([^"]*\)".*/\1/p' android/app/build.gradle* | head -n 1)
1124
+ step android installing
1095
1125
  if [ -n "$device" ]; then
1096
1126
  android_ready "$device" || { echo "android: $device didn't finish starting (see: adb devices)"; status=1; return; }
1097
1127
  "$adb" -s "$device" install -r "$apk" > /dev/null
@@ -1116,10 +1146,10 @@ build() {
1116
1146
  build_only=1
1117
1147
  ios_pid=""
1118
1148
  if [ "$(uname -s)" = Darwin ]; then
1119
- (trap release EXIT; ios; exit $status) > "$evidence/build-ios.out" 2>&1 &
1149
+ (trap release EXIT; ios; finish ios; exit $status) > "$evidence/build-ios.out" 2>&1 &
1120
1150
  ios_pid=$!
1121
1151
  fi
1122
- (trap release EXIT; android; exit $status) > "$evidence/build-android.out" 2>&1 &
1152
+ (trap release EXIT; android; finish android; exit $status) > "$evidence/build-android.out" 2>&1 &
1123
1153
  android_pid=$!
1124
1154
  [ -z "$ios_pid" ] || wait "$ios_pid" || status=1
1125
1155
  wait "$android_pid" || status=1
@@ -1242,10 +1272,10 @@ case $mode in ios | android | all | build)
1242
1272
  esac
1243
1273
 
1244
1274
  case $mode in
1245
- quick) quick ;;
1246
- ios) ios ;;
1247
- android) android ;;
1248
- all) quick; ios; android ;;
1275
+ quick) quick; finish quick ;;
1276
+ ios) ios; finish ios ;;
1277
+ android) android; finish android ;;
1278
+ all) quick; finish quick; ios; finish ios; android; finish android ;;
1249
1279
  build) build ;;
1250
1280
  plan) plan; exit 0 ;;
1251
1281
  approve) node scripts/amk/shots.js approve "$evidence"; exit $? ;;
@@ -1,6 +1,6 @@
1
1
  # <ID>: tasks
2
2
 
3
- Each task: about an hour of work, under ~300 changed lines, one commit. Each is a thin slice through every layer it needs (screen, state, API call, test) that works and can be checked on its own, not one layer at a time; moving or renaming code that's there, to make the feature easy to add, comes first. Each names the requirement it serves, the tasks it waits on, and how it's checked. Its tests are written in the same task, not in a catch-up task at the end.
3
+ Each task: about an hour of work, under ~300 changed lines, one commit. Each is a thin slice through every layer it needs (screen, state, API call, test) that works and can be checked on its own, not one layer at a time; moving or renaming code that's there, to make the feature easy to add, comes first. Each names the requirement it serves, the tasks it waits on, and how it's checked. Its tests are written in the same task, not in a catch-up task at the end. While building, your AI tool's task list, if it has one (Codex's plan), follows this one: the task you're on in progress, each done when it's ticked here.
4
4
 
5
5
  - [ ] 1. <task> — for: <requirement name> — after: <task numbers, or none> — files: <paths> — check: <test, command or screen>
6
6
  - [ ] 2.