refactor(aidd-context): rebuild 00-onboard as a plain-language guide#284
Merged
Conversation
Rework onboard from a state-machine hub into a guide that teaches the AIDD flow and suggests the next logical step, adapted to the project and the installed plugins. - three actions (read-project, orient, act) with the Input/Output/Process/ Test anatomy; the router carries plain transversal rules, no internal state taxonomy. - references/journey.md holds the canonical flow from the course (courses/05_ai_coding/0501_flow.md): Context, then Clarify, Track, Plan, Build, Review, Ship. It is the spine only; every skill is discovered at runtime by description and grouped by step, so a new skill surfaces on its own with no edit here. - read and lead with the project's own memory (brief, architecture); a choice explains the project from its memory bank. - suggest by function and resolve to an installed skill, name a gap by function, never invent a skill or plugin id. - move the flow model from assets/ to references/ (it is read, not copied). - aidd_docs is not required: a project without it is suggested the Context step first. Validated via headless claude -p: canonical flow, memory context, the six-choice menu, Ship distinct from Review, full skill discovery, and gap-honesty against a single-plugin marketplace. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
7ec0885 to
5507685
Compare
Merged
This was referenced Jun 17, 2026
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
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.
🎯 What & why
Rework
aidd-context:00-onboardfrom a state-machine hub into a plain-language guide. The old skill leaked implementation state (sdlc_phase,memory_state, Group A/B/C signals, a 130-line state-matrix) and assumed framework literacy in its menus, the opposite of what an onboarding skill should do. The new one teaches the AIDD flow and suggests the next logical step, adapted to the project and the installed plugins.🛠️ How it works
read-project(silent light read),orient(place the project, suggest a step, offer choices),act(run, explain, teach, switch, hand off, stop). Plain transversal rules, no state taxonomy.courses/05_ai_coding/0501_flow.md): Context, then Clarify, Track, Plan, Build, Review, Ship. It is the spine only. Every skill is discovered at runtime by its description and grouped by step, so a skill added to any plugin later surfaces on its own with no edit to this file. Support tools (debug, refactor, audit, test) appear by discovery, not a hardcoded list.journey.mdlives inreferences/(read, not copied).aidd_docsis not required: a project without it is suggested the Context step first.Why this shape: the spine is the framework's stable conceptual model, worth curating; the skills that fill it change, so they are discovered. That keeps onboard self-updating.
🧪 How to verify
node scripts/summarize-markdown.js plugins/aidd-context/ /tmp/cat.md --depth=4 --fields=description,argument-hint --title=x --tagline=xthen diff against the committedCATALOG.md.aidd-contextenabled, invoke onboard: it reads silently, gives a plain briefing led by the memory, suggests the earliest unmet step resolved to an installed skill, and offers a stable six-choice menu.claude -p: canonical flow (Clarify through Ship, Ship distinct from Review), memory context used, the explain-the-project choice, full skill discovery grouped by step, and gap-honesty against a single-plugin marketplace (no non-installed skill named).claude -punder-triggers skills versus a real session, so the natural-trigger behavior is best confirmed interactively.✅ I certify