feat(aidd-context): rebuild onboard as a token-lean guided tutorial#425
Merged
Conversation
Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com>
Remove the aidd-ui package from release-please-config.json. Its release-as: 0.1.0-alpha.0 pin forced the same version on every run, so any change touching aidd-ui made release-please retry the existing aidd-ui-v0.1.0-alpha.0 tag and fail (Validation Failed: already_exists). Dropping it from the config freezes aidd-ui at its current alpha while it is still a scaffold; re-add it with proper prerelease handling when it is ready to version. Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Restore the aidd-ui package block in release-please-config.json so it matches the other seven plugins (package-name + extra-files), but without the release-as: 0.1.0-alpha.0 pin. The pin forced the same version every run, retrying the existing aidd-ui-v0.1.0-alpha.0 tag and failing (already_exists). Supersedes the block removal in #394: aidd-ui stays release-managed like its siblings; the next change bumps it to a fresh version instead of colliding. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt
Reshape the onboard report from a status dashboard into a noob-first guide: one plain state sentence, one recommended action with its key, the rest on demand behind [?]. Emoji-anchored state kept, glyphs cut to ✅/⚠️ /❌, tiers phrased as plain clauses, labels made explicit (tech stack, project knowledge saved, knowledge loaded by the AI). Restore three behaviors the earlier linter rebuild dropped: - session ledger (kills the re-nag for off-disk completions) - plan-status hedge driving the build-to-ship pin - capability map documented as the fixed catalogue (light tradeoff) Fix the dev-flow pin to read only the current branch's PR, never a repo-wide open PR or review queue. Rework the idle menu into three plain umbrellas (start new work / improve the project / customize the AI) plus explore. Add a recap reply, a return-to-onboard affordance on GUIDED handoff, and a framing line so the interactive nature is announced. Conform to the skill-authoring contract (R1-R13). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
5-phase plan for reworking onboard into a token-optimized guided tutorial: granular conditional-load file tree, 4-action chain (scan → assess → present → run), state-aware foundations, leaner router format, updated skill-authoring contract. Colleague-approved mockup gallery included. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…uthoring Phase 1 of the onboard rebuild. Relax R3 to allow nested reference sub-folders with a load-locality rule; reconcile R13 (import vs pointer, nested paths); add R14 (telegraphic notation, mermaid only for branching); specify the router format (tiny title, arrow/pick-one chaining schema, verb-led Does, no intro/Input column, official frontmatter keys only). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 2. Split the state catalogue into tiny conditional-load refs: state/zones.md (foundations, dev flow, health), state/detection.md (AI-tool roots + per-tool wiring), state/done-rule.md (session ledger), state/hedge.md (plan-status pin). Rewrite 01-scan to load them per step and detect AI tools + wiring. checks.md kept until phase 3 extracts order/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 3. Add 02-assess (snapshot => decision: state class, ranked next,
chosen screen) over order/{ranking, idle-menu, screen-map(mermaid)}.
Rename 03-run => 04-run over run/{replies, tiers, return}. Rename
02-report => 03-present (body rewritten in phase 4). Delete run-tiers.md
(content moved to run/). Four actions: scan → assess → present → run.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… flow + banner) Phase 4. Rewrite 03-present to render the screen 02-assess chose, injecting banner.txt on entry screens and loading flow.md on flow/walk screens. New flow.md (8-step curriculum, two state-aware foundation paths, vertical + map layouts). New banner.txt (AIDD ASCII). Rewrite report.md into the screen shapes (state block with warning-carries-a-fix, foundations step, where-you-are, [?] detail). Delete checks.md, now fully split into state/ and order/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 5. Rewrite SKILL.md in the new router format (tiny title, 'scan → assess → present → run ↺' schema, verb-led Does, no intro or Input column): 567 → 296 tok. Reframe README as a guided tutorial. Token budget (tiktoken cl100k, proxy): always-on description 66 tok; model-loaded corpus 5672 tok (-249 vs the noob-first checkpoint). The real win is conditional loading — each action pays its own layer (scan ~1280, assess ~620, run ~620) instead of the old checks.md (2068) + run-tiers (1033) co-loaded monolith. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
All five phases done, link check green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Single-home the glyph semantics (state refs describe status in words; display legend stays in report.md), split disk-detectable dev-flow pins from inferred ones in zones.md, and point report.md's tier clause to run/tiers.md instead of restating it. review.md verdict now approve. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Cut flow.md duplication (the step table was repeated as a vertical code block; present renders the table now): 562 → 324 tok. Telegraph the prose notes and drop the duplicated flow map in zones.md (769 → 649), and tighten idle-menu, detection, tiers. No condition lost. References corpus 3211 → 2678; model-loaded total 5921 → 5255 (-11% vs the noob-first checkpoint). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add the mandatory ## Output section to 04-run (R8 action anatomy; the other three actions had it). Stop the README from restating the glyph legend that report.md single-homes (describe status in words). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Lead with 'Guide a project through AIDD' instead of the awkward 'onboard onto an AIDD project'; drop near-duplicate triggers. 66 -> 49 always-on tokens. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Describe the journey (first setup to shipping a feature) rather than restating the scan/assess mechanism the actions already own. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…mbiguous ↺ The 'scan → assess → present → run ↺' glyph is ambiguous about where the loop returns. Show the cycle as a mermaid flowchart so the LLM reads the run → scan edge unambiguously. Update the contract: a pipeline schema is arrows for a straight run or a mermaid when the flow loops (a cycle is not linear, so R14 permits it). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Verb + object per action (read the project / decide the next step / show the screen / act on the reply); the action files carry the detail. Includes the reviewed transversal rules. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Trim each action to essentials: a rule-free title line, a one-line Output, one-line Process steps (detail lives in the refs, cases as sub-bullets), and challenged one-sentence Test points. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Drop the cross-skill import of 02-project-memory's memory-block.md. Memory-wiring drift is judged in the Zones step against a self-contained rule in zones.md (the standard aidd_project_memory block that imports the memory files), so onboard no longer reaches into another skill's files. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… semicolons Output names the produced artifact (snapshot / decision / screen) instead of enumerating its contents with a colon. Drop 03-present's Warn step — report.md already owns the warning-and-fix rules that Shape applies. Split every semicolon run-on into sub-bullets or separate lines. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The router mermaid owns the scan → assess → present → run chain, so each action's Input/Output/handoff no longer restates its neighbour. Inputs and outputs name the artifact (snapshot, decision, screen), not the producer or consumer. Drop the reply enumeration from 04-run input (replies.md owns it) and 02-assess's pure-handoff step. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Trim the legend comment (glyph single-home + inline pointers to replies.md/tiers.md), shorten placeholder hints, and replace the notes that restated flow.md/replies.md with pointers. Five screen shapes kept, mapping the screen-map state classes. 776 -> 590 tok. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…esent An asset holds the shape to fill, not rules and not action names. Strip report.md to the five screen templates. Move the render rules (framing first-only, glyph meanings, warning-carries-fix, ids/tier under [?]) into 03-present, where the renderer owns them. report.md 590 -> 351 tok. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Drop the 'action reads/does this' opener from every reference — the action already declares which ref it reads, so naming the consumer back is duplication. Remove the read/write and when-a-plan-exists conditions that the actions own, fix a stale glyph-legend pointer, and clear the remaining semicolons. References are the looked-up data now, nothing more. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Restore the explain-project reply (dropped, not relocated) with its memory-filled guard. Drop the render instruction from detection.md (03-present owns rendering). Align 04-run Output with its Process by exempting umbrella picks from the re-scan too. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
detection: detect a tool by its own dir only (.claude/.codex/.cursor/ .opencode) — AGENTS.md is a shared wiring target many tools read, not a codex signal. hedge: cover all five plan statuses (pending, in-progress, implemented, reviewed, blocked) plus open-PR. idle-menu: new work is sdlc or brainstorm, not spec. screen-map: one class/when/screen table, drop the redundant mermaid. zones: keep detectable pins in the table, inferred stages in a note; trim noise. return + done-rule: slimmed, purpose-first. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The 'AGENTS.md is the shared target... CLAUDE.md is claude's' prose just restated a column. One table now carries detection dir + wiring file per tool; the shared AGENTS.md is self-evident from the rows. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
flow + ranking + replies + screen-map: drop openers that only echo the H1. ranking: drop the state-aware parenthetical zones.md owns. replies: [n] just runs a step or opens an umbrella, idle-menu owns the umbrella mechanic. tiers: fold the clause into a table column, drop the What column and the OK-walk bullet that restated it. flow: drop the render hint. Includes the banner flag. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
'unreadable or absent' read as 'no plan', but hedge only applies when a plan exists — with no plan, zones.md places the pin. The row is about a missing or unreadable status field. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… pin A missing or unreadable status: means the plan itself is broken. Surface it like blocked does, rather than inventing an Implement-then-Review pin. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Explore becomes idle-menu slot 4, so [?] is no longer overloaded between 'expand detail' and 'explore' on the idle screen. Delete the two replies.md bullets that restated 04-run's loop decision (five lenses agreed). Drop 04-run's verbatim echo of tiers.md and its lone sibling-action reference. Drop flow.md's consumer-naming line. Strip trailing whitespace. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The index still carried the pre-rework description. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A real headless run improvised three things the asset never specified: the foundations screen previewed the remaining steps, the option line carried OK-walks-all and the flow map, and a zero-tool project crossed its AI-tools row. Pin all three: the remaining steps are part of the foundations shape, the option line names the walk and the map, and an undetected tool set reads 'none yet' uncrossed since the memory row already carries the gap. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The live greenfield run stacked the entry screen's action line on top of the foundations step's, repeating the same options twice. A screen that carries a foundations step uses that step's line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A drift screen printed [1] twice: the warning's fix line and the arrow line both claimed the same action. Generalise the rule — a warning's fix or a foundations step already is the action line, so the arrow line renders only when neither does. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A live run trailed improvised prose past the options line, guessing what comes after the fix. Lines stay short, nothing follows the options line, and lookahead lives under [?]. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Split the compound render bullets in 03-present and its Inject step, and cut 04-run's Output back to the artifact it names — the ledger write and the re-scan are Process steps, not Output prose. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Four lines still stacked two ideas. Each case becomes a sub-bullet, each assertion its own Test point. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Codex triggered the skill, read SKILL.md, and stopped. The 'read the action file before running it' rule had been moved into the authoring contract, which no executing host ever reads, so it reached nobody at runtime. The router carries it again and the contract now says why. CLAUDE.md without a .claude/ dir left claude undetected, so memory-wiring drift was never judged and a broken block reported as healthy. A tool-exclusive file is a valid signal; only the shared AGENTS.md is not. A used-but-unwired tool rendered as missing, and a warning screen still stacked two action lines. The shapes now name three mutually exclusive action blocks, so a screen cannot carry two. Captured runs for both hosts land beside the plan. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The contract changes this rework leaned on (nested references, router format, the runtime read-the-action rule) ship in their own pair on the next milestone. This branch touches onboard only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The orphaned runtime rule was the only blocker. With the router carrying it, Codex reads the actions and renders the same greenfield screen Claude does. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A live run on a broken-plan repo obeyed the one-action rule, then trailed a detail block, a state snapshot, and a next hint past the options line. The rule now names exactly what must not follow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Left unshaped, a live idle screen grew a four-row list with descriptions. Slot 1 is the action line, the rest join the options line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
next removed the per-skill README mirrors (#396), so onboard's README goes with them. The reworked SKILL.md, actions, references and assets are kept as this branch wrote them. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
blafourcade
added a commit
that referenced
this pull request
Jul 10, 2026
…425) * chore: release main (#405) Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com> * ci(framework): stop release-please re-tagging aidd-ui (#394) Remove the aidd-ui package from release-please-config.json. Its release-as: 0.1.0-alpha.0 pin forced the same version on every run, so any change touching aidd-ui made release-please retry the existing aidd-ui-v0.1.0-alpha.0 tag and fail (Validation Failed: already_exists). Dropping it from the config freezes aidd-ui at its current alpha while it is still a scaffold; re-add it with proper prerelease handling when it is ready to version. Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * ci(framework): drop the aidd-ui release-as pin, keep it consistent Restore the aidd-ui package block in release-please-config.json so it matches the other seven plugins (package-name + extra-files), but without the release-as: 0.1.0-alpha.0 pin. The pin forced the same version every run, retrying the existing aidd-ui-v0.1.0-alpha.0 tag and failing (already_exists). Supersedes the block removal in #394: aidd-ui stays release-managed like its siblings; the next change bumps it to a fresh version instead of colliding. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt * feat(aidd-context): rework onboard into a noob-first guide Reshape the onboard report from a status dashboard into a noob-first guide: one plain state sentence, one recommended action with its key, the rest on demand behind [?]. Emoji-anchored state kept, glyphs cut to ✅/⚠️ /❌, tiers phrased as plain clauses, labels made explicit (tech stack, project knowledge saved, knowledge loaded by the AI). Restore three behaviors the earlier linter rebuild dropped: - session ledger (kills the re-nag for off-disk completions) - plan-status hedge driving the build-to-ship pin - capability map documented as the fixed catalogue (light tradeoff) Fix the dev-flow pin to read only the current branch's PR, never a repo-wide open PR or review queue. Rework the idle menu into three plain umbrellas (start new work / improve the project / customize the AI) plus explore. Add a recap reply, a return-to-onboard affordance on GUIDED handoff, and a framing line so the interactive nature is announced. Conform to the skill-authoring contract (R1-R13). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): plan the onboard tutorial rebuild 5-phase plan for reworking onboard into a token-optimized guided tutorial: granular conditional-load file tree, 4-action chain (scan → assess → present → run), state-aware foundations, leaner router format, updated skill-authoring contract. Colleague-approved mockup gallery included. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): nested refs + leaner router format in skill-authoring Phase 1 of the onboard rebuild. Relax R3 to allow nested reference sub-folders with a load-locality rule; reconcile R13 (import vs pointer, nested paths); add R14 (telegraphic notation, mermaid only for branching); specify the router format (tiny title, arrow/pick-one chaining schema, verb-led Does, no intro/Input column, official frontmatter keys only). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(aidd-context): onboard state layer (scan + state refs) Phase 2. Split the state catalogue into tiny conditional-load refs: state/zones.md (foundations, dev flow, health), state/detection.md (AI-tool roots + per-tool wiring), state/done-rule.md (session ledger), state/hedge.md (plan-status pin). Rewrite 01-scan to load them per step and detect AI tools + wiring. checks.md kept until phase 3 extracts order/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(aidd-context): onboard assess + run actions with order/ + run/ refs Phase 3. Add 02-assess (snapshot => decision: state class, ranked next, chosen screen) over order/{ranking, idle-menu, screen-map(mermaid)}. Rename 03-run => 04-run over run/{replies, tiers, return}. Rename 02-report => 03-present (body rewritten in phase 4). Delete run-tiers.md (content moved to run/). Four actions: scan → assess → present → run. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(aidd-context): onboard tutorial presentation (present + report + flow + banner) Phase 4. Rewrite 03-present to render the screen 02-assess chose, injecting banner.txt on entry screens and loading flow.md on flow/walk screens. New flow.md (8-step curriculum, two state-aware foundation paths, vertical + map layouts). New banner.txt (AIDD ASCII). Rewrite report.md into the screen shapes (state block with warning-carries-a-fix, foundations step, where-you-are, [?] detail). Delete checks.md, now fully split into state/ and order/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(aidd-context): lean onboard router + tutorial README Phase 5. Rewrite SKILL.md in the new router format (tiny title, 'scan → assess → present → run ↺' schema, verb-led Does, no intro or Input column): 567 → 296 tok. Reframe README as a guided tutorial. Token budget (tiktoken cl100k, proxy): always-on description 66 tok; model-loaded corpus 5672 tok (-249 vs the noob-first checkpoint). The real win is conditional loading — each action pays its own layer (scan ~1280, assess ~620, run ~620) instead of the old checks.md (2068) + run-tiers (1033) co-loaded monolith. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(aidd-context): mark onboard tutorial rebuild implemented All five phases done, link check green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): resolve onboard review findings Single-home the glyph semantics (state refs describe status in words; display legend stays in report.md), split disk-detectable dev-flow pins from inferred ones in zones.md, and point report.md's tier clause to run/tiers.md instead of restating it. review.md verdict now approve. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): compress onboard references Cut flow.md duplication (the step table was repeated as a vertical code block; present renders the table now): 562 → 324 tok. Telegraph the prose notes and drop the duplicated flow map in zones.md (769 → 649), and tighten idle-menu, detection, tiers. No condition lost. References corpus 3211 → 2678; model-loaded total 5921 → 5255 (-11% vs the noob-first checkpoint). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): resolve checker findings on onboard Add the mandatory ## Output section to 04-run (R8 action anatomy; the other three actions had it). Stop the README from restating the glyph legend that report.md single-homes (describe status in words). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): tighter onboard description Lead with 'Guide a project through AIDD' instead of the awkward 'onboard onto an AIDD project'; drop near-duplicate triggers. 66 -> 49 always-on tokens. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): onboard description frames the journey Describe the journey (first setup to shipping a feature) rather than restating the scan/assess mechanism the actions already own. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): router loop as an explicit mermaid, not the ambiguous ↺ The 'scan → assess → present → run ↺' glyph is ambiguous about where the loop returns. Show the cycle as a mermaid flowchart so the LLM reads the run → scan edge unambiguously. Update the contract: a pipeline schema is arrows for a straight run or a mermaid when the flow loops (a cycle is not linear, so R14 permits it). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): terser onboard action table Verb + object per action (read the project / decide the next step / show the screen / act on the reply); the action files carry the detail. Includes the reviewed transversal rules. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): lean onboard action files Trim each action to essentials: a rule-free title line, a one-line Output, one-line Process steps (detail lives in the refs, cases as sub-bullets), and challenged one-sentence Test points. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): make onboard standalone Drop the cross-skill import of 02-project-memory's memory-block.md. Memory-wiring drift is judged in the Zones step against a self-contained rule in zones.md (the standard aidd_project_memory block that imports the memory files), so onboard no longer reaches into another skill's files. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): name action outputs, drop restated step, kill semicolons Output names the produced artifact (snapshot / decision / screen) instead of enumerating its contents with a colon. Drop 03-present's Warn step — report.md already owns the warning-and-fix rules that Shape applies. Split every semicolon run-on into sub-bullets or separate lines. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): actions stop naming sibling actions The router mermaid owns the scan → assess → present → run chain, so each action's Input/Output/handoff no longer restates its neighbour. Inputs and outputs name the artifact (snapshot, decision, screen), not the producer or consumer. Drop the reply enumeration from 04-run input (replies.md owns it) and 02-assess's pure-handoff step. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): slim the report.md screen asset Trim the legend comment (glyph single-home + inline pointers to replies.md/tiers.md), shorten placeholder hints, and replace the notes that restated flow.md/replies.md with pointers. Five screen shapes kept, mapping the screen-map state classes. 776 -> 590 tok. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): report.md is pure shapes, rules move to 03-present An asset holds the shape to fill, not rules and not action names. Strip report.md to the five screen templates. Move the render rules (framing first-only, glyph meanings, warning-carries-fix, ids/tier under [?]) into 03-present, where the renderer owns them. report.md 590 -> 351 tok. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): references hold data, not action coupling Drop the 'action reads/does this' opener from every reference — the action already declares which ref it reads, so naming the consumer back is duplication. Remove the read/write and when-a-plan-exists conditions that the actions own, fix a stale glyph-legend pointer, and clear the remaining semicolons. References are the looked-up data now, nothing more. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): resolve checker findings on the onboard slim pass Restore the explain-project reply (dropped, not relocated) with its memory-filled guard. Drop the render instruction from detection.md (03-present owns rendering). Align 04-run Output with its Process by exempting umbrella picks from the re-scan too. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): correct + slim onboard references from review detection: detect a tool by its own dir only (.claude/.codex/.cursor/ .opencode) — AGENTS.md is a shared wiring target many tools read, not a codex signal. hedge: cover all five plan statuses (pending, in-progress, implemented, reviewed, blocked) plus open-PR. idle-menu: new work is sdlc or brainstorm, not spec. screen-map: one class/when/screen table, drop the redundant mermaid. zones: keep detectable pins in the table, inferred stages in a note; trim noise. return + done-rule: slimmed, purpose-first. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): fold detection wiring prose into the table The 'AGENTS.md is the shared target... CLAUDE.md is claude's' prose just restated a column. One table now carries detection dir + wiring file per tool; the shared AGENTS.md is self-evident from the rows. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): drop prose that a table or another file carries flow + ranking + replies + screen-map: drop openers that only echo the H1. ranking: drop the state-aware parenthetical zones.md owns. replies: [n] just runs a step or opens an umbrella, idle-menu owns the umbrella mechanic. tiers: fold the clause into a table column, drop the What column and the OK-walk bullet that restated it. flow: drop the render hint. Includes the banner flag. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): hedge fallback names the status field, not the plan 'unreadable or absent' read as 'no plan', but hedge only applies when a plan exists — with no plan, zones.md places the pin. The row is about a missing or unreadable status field. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): a broken plan status surfaces, it does not guess a pin A missing or unreadable status: means the plan itself is broken. Surface it like blocked does, rather than inventing an Implement-then-Review pin. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): resolve the ten-lens audit findings on onboard Explore becomes idle-menu slot 4, so [?] is no longer overloaded between 'expand detail' and 'explore' on the idle screen. Delete the two replies.md bullets that restated 04-run's loop decision (five lenses agreed). Drop 04-run's verbatim echo of tiers.md and its lone sibling-action reference. Drop flow.md's consumer-naming line. Strip trailing whitespace. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): refresh the stale onboard row in the plugin index The index still carried the pre-rework description. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): specify what the live greenfield run left to chance A real headless run improvised three things the asset never specified: the foundations screen previewed the remaining steps, the option line carried OK-walks-all and the flow map, and a zero-tool project crossed its AI-tools row. Pin all three: the remaining steps are part of the foundations shape, the option line names the walk and the map, and an undetected tool set reads 'none yet' uncrossed since the memory row already carries the gap. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): one action line per screen The live greenfield run stacked the entry screen's action line on top of the foundations step's, repeating the same options twice. A screen that carries a foundations step uses that step's line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): the action line renders once, whoever carries it A drift screen printed [1] twice: the warning's fix line and the arrow line both claimed the same action. Generalise the rule — a warning's fix or a foundations step already is the action line, so the arrow line renders only when neither does. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): the screen ends at the options line A live run trailed improvised prose past the options line, guessing what comes after the fix. Lines stay short, nothing follows the options line, and lookahead lives under [?]. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): one idea per line in the actions Split the compound render bullets in 03-present and its Inject step, and cut 04-run's Output back to the artifact it names — the ledger write and the re-scan are Process steps, not Output prose. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * refactor(aidd-context): split the last compound action lines Four lines still stacked two ideas. Each case becomes a sub-bullet, each assertion its own Test point. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): three defects an eight-state headless sweep exposed Codex triggered the skill, read SKILL.md, and stopped. The 'read the action file before running it' rule had been moved into the authoring contract, which no executing host ever reads, so it reached nobody at runtime. The router carries it again and the contract now says why. CLAUDE.md without a .claude/ dir left claude undetected, so memory-wiring drift was never judged and a broken block reported as healthy. A tool-exclusive file is a valid signal; only the shared AGENTS.md is not. A used-but-unwired tool rendered as missing, and a warning screen still stacked two action lines. The shapes now name three mutually exclusive action blocks, so a screen cannot carry two. Captured runs for both hosts land beside the plan. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * revert(aidd-context): keep skill-authoring out of this branch The contract changes this rework leaned on (nested references, router format, the runtime read-the-action rule) ship in their own pair on the next milestone. This branch touches onboard only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(aidd-context): codex portability, proven before and after The orphaned runtime rule was the only blocker. With the router carrying it, Codex reads the actions and renders the same greenfield screen Claude does. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): the options line is the last line, named plainly A live run on a broken-plan repo obeyed the one-action rule, then trailed a detail block, a state snapshot, and a next hint past the options line. The rule now names exactly what must not follow. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(aidd-context): the idle menu is an action block, not a list Left unshaped, a live idle screen grew a four-row list with descriptions. Slot 1 is the action line, the rest join the options line. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rebuilds
aidd-context:00-onboardfrom a status dashboard into a guided tutorial, and cuts what the model loads by a third.What changed
Your AIDD setupblock (AI tools · plugins · memory), then one clear next action with its key. Nothing runs until the user replies.scan → assess → present → run ↺, overreferences/{state,order,run}/plus a flow curriculum. Each action loads only its own layer.⚠️never stands alone: plain cause, keyed remedy, one action line per screen.status:surfaces as broken rather than being pinned somewhere on the flow.Token budget
Model-loaded corpus
5921 → ~3900tokens (-34%), always-on description66 → 43. No behaviour was dropped: the cuts came from duplication, prose that restated a table, and rules that had two homes.How it was verified
aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/.read an action's file before running itrule had been moved intoskill-authoring.md, a contract no executing host ever reads. Codex readSKILL.mdand stopped. The router carries the line again. Proof incodex-portability.md.Static audits found the duplication. Only running it found the specification holes. Only a second host found the rule that had no reader.
Known gaps, deliberately shipped
1, the GUIDED handoff and its return line, theOKwalk,[m],[?],back,recap, and the idle-menu umbrellas have never been executed once.@citations (R13). The contract pair follows on the next milestone, with a rule forbidding a runtime instruction from living only in the contract.no testshealth signal fired in one fixture and not in another with the same state. Model variance, unresolved.🤖 Generated with Claude Code