Skip to content

refactor(aidd-context): rebuild 00-onboard as a plain-language guide#284

Merged
blafourcade merged 1 commit into
mainfrom
refactor/aidd-context-onboard
Jun 17, 2026
Merged

refactor(aidd-context): rebuild 00-onboard as a plain-language guide#284
blafourcade merged 1 commit into
mainfrom
refactor/aidd-context-onboard

Conversation

@blafourcade

Copy link
Copy Markdown
Contributor

Stacked on #279 (project-memory). Base is refactor/aidd-context-project-init; merge that first. onboard's read-project references the capability-folder memory templates from the project-memory rework.

🎯 What & why

Rework aidd-context:00-onboard from 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

  • Three actions (SKILL.md): 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.
  • Canonical flow (references/journey.md) taken 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 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.
  • Memory-led: it reads and leads with the project's own memory (brief, architecture), and a menu choice explains the project from its memory bank.
  • Gap-honest: suggest by function, resolve to an installed skill, name a gap by function, never invent a skill or plugin id.
  • journey.md lives in references/ (read, not copied). aidd_docs is 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=x then diff against the committed CATALOG.md.
  • In a project with aidd-context enabled, 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.
  • Validated via headless 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).

⚠️ Heads-up

  • Generic next-step phrasings ("where do I start") may be answered directly rather than invoking the skill. Explicit invocation and "onboard me" / "how does AIDD work" trigger it reliably; headless claude -p under-triggers skills versus a real session, so the natural-trigger behavior is best confirmed interactively.

✅ I certify

  • I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

Base automatically changed from refactor/aidd-context-project-init to main June 17, 2026 06:58
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>
@blafourcade blafourcade force-pushed the refactor/aidd-context-onboard branch from 7ec0885 to 5507685 Compare June 17, 2026 07:00
@blafourcade blafourcade merged commit 5d7351a into main Jun 17, 2026
4 checks passed
@blafourcade blafourcade deleted the refactor/aidd-context-onboard branch June 17, 2026 07:00
@aidd-bot aidd-bot Bot mentioned this pull request Jun 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant