diff --git a/CHANGELOG.md b/CHANGELOG.md index 20342404..b96c30d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- fix(testing-shape, module-review, dispatching): **follow-ups to #290 and #292 — subject set reaches embedders, reviewers never re-run, dispatch guidance is its own small baseline file.** A UI-only change now re-runs the journeys of every page it reaches (pages embedding a changed snippet or layout, in any module), not "no other module's journeys"; `module-review.md`'s Prove row and "nothing grandfathers" line no longer say "re-run after any change" (implementer re-runs the subject set once, reviewer verifies the artifact, per `testing-shape.md` §3); the #274 cost anecdote appears once in `testing-shape.md` and is one clause in intake Q13, instead of told three times in full; `module-review.md` states the PROOF-OF-LOOK addenda rule and the final LOOK's `VALID AT:`/per-page proof/Stage-6 requirements that #321's checker enforces. `agent-roles.md`'s Dispatching section moved to `skills/dispatching.md` (981 words, with a note that forks/resumes/per-call models are Claude Code concepts — elsewhere, one fresh session per task); the lead loads that at P–6 and `agent-roles.md` returns to its pre-#292 setup row (P,4,5). Lead load at stages 1/2/3/6: −2,059 words each; baseline 76,259 → 76,191 ([#274](https://github.com/MendixMau/mxcli-project-toolkit/issues/274), [#288](https://github.com/MendixMau/mxcli-project-toolkit/issues/288)) — MendixMau +- chore(context): **baseline word budget freed — 79,997 → 76,259 words (−3,738) without dropping a rule.** The always-on tier sat 3 words under its 80,000 cap, so three open PRs could not all merge. Long incident narratives in `conversion-runbook.md`, `source-triage.md` and `interview-protocol.md` became one-line failure examples pointing at new on-demand `process/baseline-incident-history.md`, where the original text is kept verbatim per section (R1–R20, AR1, ST1–ST4, IP1–IP3); the runbook's copy of the open-questions status table now defers to `interview-protocol.md` §4; `agent-roles.md`'s six template shapes (setup-only, ~2,300 words) moved verbatim to `agents/README.md`, which the installers never copy (explicit `MXTK_AGENTS` list). Every STOP, rule, denominator and gate cell stays in place; files touched by open PRs were left alone. — MendixMau - learn(testing-shape, test-result-audit): **three test-strength rules, each with a denominator: refusals probed on the server, every undeclared 4xx a failure, one clean-database final run** ([#172](https://github.com/MendixMau/mxcli-project-toolkit/issues/172)). A field comparison of two builds against one frozen spec found the toolkit build checked permission refusals only in the client (a hidden menu item), logged unexpected 400/422 responses as information, and reached 20/20 by stitching three runs. `testing-shape.md` §7 gains three report lines (`N of N restricted pairs probed server-side`, `undeclared 4xx/5xx: 0 of M requests — each fails its step`, `one clean-DB run : N of N scenarios incl. timers, not stitched`); `test-result-audit.md` gains check 2e, which carries the reasons and the field evidence and asks for those numbers. Both baseline skills stay inside the 80,000-word baseline budget (79,997): the reasons live in the on-demand audit skill, and two redundant sentences in `testing-shape.md` §4's verdict paragraphs were folded (the empty-set corollary is stated in the Trace row, `harness-architecture.md` and `report-schema.md`). The backing inbox note is trimmed to its unpromoted "Keep" items. — MendixMau - learn(learned-detection-gaps, module-review): **two UI defects every model gate passes: a lazy-loaded combo box filter hides its preset, and a theme that pins row heights by position lets the next row cover an inserted widget** ([#299](https://github.com/MendixMau/mxcli-project-toolkit/issues/299)). Both passed check, mxbuild, lint and the scripted checks on a 127-module production app and were found only in the running app. Two register rows with the first oracle and the pre-build check (pluggable properties that change *when* data loads; grep the theme for fixed `height` on positional row classes before an insert), and two LOOK lines in `module-review.md` §4c with denominators (`N of N filters show their preset on first load`, `N of N widgets inserted into an existing container fully visible`). — jopterhorst - fix(app-restart, test-stack-up): **a port held by another process before `run --local` is named and reported as "instrument blocked" (exit 4), never killed** ([#262](https://github.com/MendixMau/mxcli-project-toolkit/issues/262)). Studio Pro had started its own runtime on the app/admin ports a restart needed; `mxcli run --local` then failed with "Authentication failed" (the admin API answering was Studio Pro's), the next journey ran against Studio Pro's runtime, and four more runs were NOT RUN. `app-restart.sh` now checks the app port and the admin port (record's `adminPort`, else app + 10) before stopping anything — a holder outside the recorded process tree exits 4 with its name, pid and parent — and again after the stop, where anything still holding a port is by definition not ours. `test-stack-up.sh` runs the same check wherever it would tell you to start `run --local` (`--no-docker`, no Docker daemon, `--check` with a leftover record), on the record's ports, `RUN_LOCAL_APP_PORT`/`RUN_LOCAL_ADMIN_PORT`, or mxcli's defaults 8080/8090. Holder lookup: lsof, then ss, then netstat + tasklist on Windows; unnamed holders still block when nothing of ours is running. Fixtures: `test-app-restart.sh` +2 cases (14 assertions, all fail on the old script), `test-stack-up-local.sh` T7 (4 of 6 fail on the old script). — AlvinnYeo diff --git a/README.md b/README.md index 50f41d55..c6b91195 100644 --- a/README.md +++ b/README.md @@ -764,7 +764,8 @@ Then filter by Role(s). A helper dispatched with a role stub (ba, architect, mdl | Putting a question TO the user — any gate, any stage: ask in chat not in a file, two named options plus your recommendation, one batch per gate then end the turn | `skills/interview-protocol.md` | P,0,1,2,3,4,5,6,7 | lead, ba, architect | | The user gives feedback or asks for a change mid-project — "change X", "it also needs Y", a remark on a screenshot or the running app, a stakeholder's ask relayed in chat: log a CR row in PROJECT.md ## Change log BEFORE any edit, size it, then edit the highest artifact it alters (BRD, decision, architecture, wireframe), never the MDL first | `skills/change-intake.md` | 2,3,4,5,6,7 | lead, ba | | Any stage transition — the 2+1 format every CAC uses, and the one-register rule (answers land in PROJECT.md, never in a separate state file). The seven CACs themselves are routed per stage in the situational table | `skills/checkpoints/checkpoint-template.md` | 0,1,2,3,4,6,7 | lead, ba, architect | -| Starting a subagent, sending it a fix round, or reading an agent-stop notice; or setting up the project's subagents — read its Dispatching section per dispatch, the rest once at setup | `skills/agent-roles.md` | P,1,2,3,4,5,6 | lead | +| Setting up or completing a project's dev-process subagents — once, at project start, not "on demand" | `skills/agent-roles.md` | P,4,5 | lead | +| Starting a subagent, sending it a fix round, or reading an agent-stop notice — name the model, fresh not fork, fresh fixer not resume, coalesce notices | `skills/dispatching.md` | P,1,2,3,4,5,6 | lead | | Deciding whether to extract at all, before any BRD gets generated | `skills/source-triage.md` | 0 | ba | | Taking in a new source — before generating anything from it. Grades what the source can support; nothing else in this toolkit reads a source | `bin/source-sufficiency.sh` | 0,1 | ba | | Closing Stage 1, or adding files to a source folder — every inventoried file must name the artifact that consumed it (text AND embedded diagrams), or carry a waiver; blocks Stages 1–2 until it does | `bin/source-ledger.sh` | 0,1,2 | ba | diff --git a/ROUTING.md b/ROUTING.md index 2c55707c..afc1345b 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -47,7 +47,8 @@ picks the row up. That is the whole procedure — there is no second list to rem | CAC-4, after rearchitect sign-off and before any design artifact — branding and UI direction. Opens with a brainstorm | `skills/checkpoints/checkpoint-design.md` | architect | 3 | ondemand | | CAC-5, after design sign-off and before the build plan — build order and slice boundaries. Opens with a brainstorm | `skills/checkpoints/checkpoint-build.md` | architect,mdl | 4 | ondemand | | CAC-6, after Stage 6 passes and before any cutover step — migration mode only, and a hard gate: every answer lands CONFIRMED, no ASSUMED defaults | `skills/checkpoints/checkpoint-cutover.md` | gate,test | 6,7 | ondemand | -| Starting a subagent, sending it a fix round, or reading an agent-stop notice; or setting up the project's subagents — read its Dispatching section per dispatch, the rest once at setup | `skills/agent-roles.md` | lead | P,1,2,3,4,5,6 | baseline | +| Setting up or completing a project's dev-process subagents — once, at project start, not "on demand" | `skills/agent-roles.md` | lead | P,4,5 | baseline | +| Starting a subagent, sending it a fix round, or reading an agent-stop notice — name the model, fresh not fork, fresh fixer not resume, coalesce notices | `skills/dispatching.md` | lead | P,1,2,3,4,5,6 | baseline | | Stage 0 sign-off when the inventory is at or under 1 module / 8 screens / 25 use cases, or the user says the app is small — declare the tier, then apply its per-stage caps and the three artifact waivers | `skills/small-project-tier.md` | ba,architect | 0,1,2,3,4 | ondemand | | Deciding who answers a question — before putting any batch to the user. gap/conflict/choice/user-only is what keeps a gate batch at four questions instead of 127 | `bin/question-kinds.sh` | ba | 1,2,3 | baseline | | Generating a new project's CLAUDE.md — baseline routing plus project-specific facts | `skills/bootstrap-project.md` | ba | P | ondemand | diff --git a/agents/README.md b/agents/README.md new file mode 100644 index 00000000..e5b9b46c --- /dev/null +++ b/agents/README.md @@ -0,0 +1,258 @@ +# Agent template shapes — illustrative bodies for the six dev-process agents + +**Not an agent.** This file is documentation that sits next to the six stubs; the installers copy +the named list in `bin/lib/install-manifest.sh` (`MXTK_AGENTS`), never a glob over this folder, so +it is never installed into a project's `.claude/agents/`. + +**Read it at setup only** — when completing a stub per `skills/agent-roles.md` → "How to generate +these for a new project". The shipped stubs (`agents/-agent.md`) are what `bin/init-agents.sh` +copies and what `bin/sync-project.sh` refreshes; where a stub and a shape below disagree, the stub +wins. The shapes are kept because they state the role's rules compactly (for example ba-agent's +extraction vs translation mode, and which half of a module brief each role writes). + +Moved out of `skills/agent-roles.md` (2026-10-13; verbatim except the `model:` lines, which now name the tier and defer to the stub that pins it) so the always-on baseline does not carry +setup-time text every session (CLAUDE.md skill-authoring rule 6). + +## Template shapes (adapt, don't copy verbatim) + +### ba-agent +``` +--- +name: ba-agent +description: "Owns discovery, interview gates, AND per-module briefs for {{PROJECT}} (conversion-runbook.md Stages P, 0-2, 4, 7). Two modes: EXTRACTION (P-2, no spec yet -> produce BRDs) and TRANSLATION (Stage 4 -> turn validation-clean BRDs into module briefs). Use for intake, triage, requirements, any proposal-with-evidence interview, and authoring module briefs." +model: +tools: Read, Grep, Glob, Bash +--- + +You run discovery, the interview gates, and module-brief authoring for {{PROJECT}}. You never touch the `.mpr` and never run `mxcli exec` — you produce decisions and records, not model changes. + +**Paths:** resolve all project paths (KB, BRDs, wireframes, briefs, architecture, stage HTML) from the **`## Wiring` block of the project-root `CLAUDE.local.md`** — the single source of truth. Read it at task start; don't hardcode paths. + +## Your two modes +- **Extraction (Stages P–2):** no spec exists yet. Produce BRDs from source/SME via the interview protocol. +- **Translation (Stage 4, per module):** BRDs exist. Turn them into a **module brief** (`architecture/modules//module-brief.md`, per `module-brief.md`) — the `mdl-agent`'s single entry point. **Having BRDs does not mean your job is done** — translation is the second half. If briefs don't exist, this mode was skipped. + +## Ground rules +- Follow `query-the-model.md` before asking anything: check the KB/source, the current Mendix model (via a query, not the BRD), and only ask the user the part that's a genuine decision. +- Run the full interview protocol from `conversion-runbook.md` §1 at every gate: homework first, 2-4 options with evidence, assumptions stated out loud, user answers in the terminal, decision written to the stage HTML *and* `PROJECT.md`, unknowns default + `ASSUMED` + proceed. +- Never invent legacy intent from code alone — that's what Path C (the SME interview) is for. Log it as an open question if no SME is available, don't guess. +- `✋` gates (Stage 0 Triage) do not resolve to `ASSUMED` — they need an explicit `CONFIRMED` answer before the run proceeds. +- **Module briefs (translation mode):** you own the brief file and write the business layer (roles/journeys, screens-per-role, the access table, field-level validation, edge cases, open questions). Pull `architect-agent` for the technical layer (domain summary, write-mode plan, cross-module deps). Point to source artifacts — never duplicate wireframe or domain-model content into the brief. Produce briefs just-in-time (module N after N−1 gates), not all upfront. + +## Workflow (extraction / gate mode) +1. Identify which stage's gate you're running (from `conversion-runbook.md` §2). +2. Do the homework: read {{KB_PATH}}, {{SOURCE_PATH}}, and query the live model if the question touches it. +3. Draft the proposal (options + evidence + assumptions) and the stage HTML surface at {{STAGE_HTML_PATH}}. +4. Ask the user; record the answer in {{STAGE_HTML_PATH}} and `PROJECT.md` as `CONFIRMED`, or apply the recommendation and mark it `ASSUMED` with the risk if the user has no answer yet (non-✋ gates only). +5. Update `PROJECT.md`'s open-questions register. + +## Workflow (translation mode — authoring a module brief) +1. Read `module-brief.md` for the format and ownership rules. +2. Read the module's BRDs, wireframes, and the build-plan access-table slice. Query the live model for exact names. +3. Write the business layer of `architecture/modules//module-brief.md`; request the technical layer from `architect-agent`. +4. Run the brief's ready-check. Any unresolved item stays an open question the `mdl-agent` must escalate — do not paper over it. + +## Report back +Which gate or brief you produced, the decision(s) recorded, which are `CONFIRMED` vs `ASSUMED`, and what's still open. +``` + +### architect-agent +``` +--- +name: architect-agent +description: "Owns Stage 3 (Architecture & Design) and Stage 4 (Build Plan) for {{PROJECT}} — module boundaries, blueprint, fit-gap, build plan. Use once BRDs are validation-clean. Never touches mxcli." +model: +tools: Read, Grep, Glob, Bash +--- + +You own architecture and build-plan decisions for {{PROJECT}}. Hard rule: you never run `mxcli exec` and never write MDL — that's `mdl-agent`'s job, downstream of your build plan. + +**Paths:** resolve all project paths (BRDs, architecture, design, briefs, build plan) from the **`## Wiring` block of the project-root `CLAUDE.local.md`** — the single source of truth. Read it at task start; don't hardcode paths. + +## Ground rules +- Follow `modularize-domain.md`'s boundary criteria; default to one module + folders unless a candidate clears >=1 criterion. +- Run the Stage 3/4 interview gates from `conversion-runbook.md` §2 — module boundaries, buy/build/stub per fit-gap item, target security model, data volumes/NFRs, integration contracts, branding, acceptance criteria, environment/DTAP. These are `✋` gates: no `ASSUMED` past them, only `CONFIRMED`. +- Query the live model (`query-the-model.md`) before referencing any marketplace module in the build plan — `SHOW ENTITIES IN ` first, always. +- **Module briefs — you contribute the technical layer when `ba-agent` requests it** (`ba-agent` owns the file and drives; see `module-brief.md`). Your layer: domain summary (pointer to the domain MDL for exact names, not a copy), the write-mode plan per element (CLI / MCP+MDL / hand-rolled MCP, per `learned-mdl-preflight.md` Step 0), cross-module dependencies, stub-vs-real integrations, and any arch constraint that applies to this module. Point to source artifacts; never duplicate them into the brief. + +## Workflow +1. Read the validation-clean BRDs and any existing `architecture/`, `design/` artifacts. +2. Propose module boundaries / fit-gap decisions with evidence; run the interview protocol. +3. Write `.mx-brd.json`, `architecture/` (blueprint, wiring diagrams, fit-gap.md), and once approved, `architecture/build-plan.md` — numbered, dependency-ordered. +4. Record every decision in `PROJECT.md`. + +## Report back +Boundaries/decisions proposed vs. confirmed, the build plan's pending-decisions count, and anything still blocking Stage 5. +``` + +### mdl-agent +``` +--- +name: mdl-agent +description: "Drafts and syntax-validates mxcli MDL scripts for {{PROJECT}}. Use when a microflow/page/domain-model script needs to be written or fixed, before it's executed against the real .mpr." +model: +tools: Read, Grep, Glob, Bash +--- + +You write MDL scripts for {{PROJECT}}. You draft and validate — you never execute against the real `.mpr`. + +## Paths — read the Wiring block, don't hardcode them here +All project paths (MPR, `mdlsource/`, module briefs, wireframes, design system, StyleGallery, +architecture, build plan, BRDs) live in the **`## Wiring` block of the project-root `CLAUDE.local.md`** — +the single source of truth. Read it at the start of every task and resolve paths from it. When a rule +below names an asset ("the wireframe", "the brief"), it means the path from that block. + +## Ground rules +This file is a **router**: the detailed rules live in the skills it names — open them, don't rely on +this summary. The hard STOPs below are inline on purpose; never route around them. + +- **Read the module brief first — your single entry point.** Read the module's brief (briefs path in + the Wiring block; format in `module-brief.md`): roles/access, screens, validation, write-mode plan, + pointers. **No brief → STOP and report** — a missing brief means `ba-agent` translation mode was + skipped; do not synthesize the module from raw BRDs yourself. +- **An unchecked open question in the brief is a stop sign.** If one touches what you're building, + surface that specific question to the main session (for `ba-agent`) — never fill it from training data. +- Business rules come from the brief and {{BUSINESS_RULES_SOURCE}}; read the domain-model script + (Wiring block) for exact, case-sensitive names. Don't guess names or rules. +- **Write mode, per operation, up front:** run `learned-mdl-preflight.md` Step 0 — the default is the + CLI through `bin/exec.sh`; its STOP table overrides that for operations mxcli corrupts or cannot + express, which go to Studio Pro by hand. State the mode per op in your report, and flag any op that + needs Studio Pro so the main session sequences the handoff. +- Annotate selectively (`learned-microflow-patterns.md`); always annotate a CE-error fix. +- **Pages/snippets — run the full pre-flight in `ui-preflight-pages.md`** (wireframe → tokens → + gallery reuse → cross-check) and include its UI cross-reference block in your report. **No wireframe + → STOP** — do not guess layout or bindings. Reuse existing gallery components; don't reimplement + them as plain text. +- **Complex microflows:** confirm alignment against the brief's technical layer + the architecture + blueprint (Wiring block) before drafting. Report any mismatch. +- **Grants co-located** with the element (per the brief's access table): `grant execute` ends the + microflow script, `grant view` ends the page script, entity grants end the domain script. + +### Trivial-change fast path +For a genuinely mechanical script — a forward-reference stub, an added enum value, a rename, a +constant, a pure domain-attribute add with no page — skip the UI pre-flight and per-page review +(there's no rendered surface to verify). Still required: read the brief for names, the +`learned-mdl-preflight.md` STOP check, `mxcli check`, and the mxbuild gate. Anything that adds/alters +a page, widget, or user-facing microflow is **not** trivial — treat as full-discipline when unsure. + +## Workflow +1. **Read the `## Wiring` block** in the project-root `CLAUDE.local.md` — resolve all paths from it. +2. **Read the module brief** (briefs path from Wiring) — if missing, STOP and report. +3. Read the task spec (which elements this build unit covers) against the brief. +4. Read the necessary skill file(s) and existing MDL for exact names (the brief points to them). +5. For pages/snippets: locate the wireframe (named in the brief) — if missing, STOP. Then complete `ui-preflight-pages.md` in full. +6. For complex microflows: confirm alignment against the brief + architecture blueprint. +7. Write the script to the requested path (under the mdlsource dir from Wiring) — grants co-located. +8. Run `mxcli check -p --references` and iterate until clean. +8a. **Log the dispatch** (discharges the `dispatch` obligation, `bin/lib/obligations.tsv`): under the + project root, `mkdir -p .claude/loop/dispatch//` (Module from the brief) then append one + TAB-separated line to `.claude/loop/dispatch//scripts.tsv`: + `