@@ -43,12 +43,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 | Group | File | Description |
 |-------|------|---|
-| `actions` | [01-detect-state.md](skills/00-onboard/actions/01-detect-state.md) | - |
-| `actions` | [02-recommend-next.md](skills/00-onboard/actions/02-recommend-next.md) | - |
-| `actions` | [03-execute-or-handoff.md](skills/00-onboard/actions/03-execute-or-handoff.md) | - |
-| `assets` | [state-matrix.md](skills/00-onboard/assets/state-matrix.md) | - |
+| `actions` | [01-read-project.md](skills/00-onboard/actions/01-read-project.md) | - |
+| `actions` | [02-orient.md](skills/00-onboard/actions/02-orient.md) | - |
+| `actions` | [03-act.md](skills/00-onboard/actions/03-act.md) | - |
 | `-` | [README.md](skills/00-onboard/README.md) | - |
-| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Detect the current project's state and open a hub of project actions - understand the project, set up or refresh the memory bank, or continue the AIDD development journey. Silently inspects the project, the AIDD setup, and which AIDD plugins are installed, then adapts the menu to that context. Use when the user says "where do I start", "onboard me", "onboard me to this project", "what should I run next", "what should I work on next", "what's the state of this project", "guide me through aidd", "guide me through aidd-context", or invokes `aidd-context:00-onboard`. Do NOT use to enumerate every installed surface from raw user intent (the discovery skill in this plugin handles that).` |
+| `references` | [journey.md](skills/00-onboard/references/journey.md) | - |
+| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Guide the user through the AIDD framework on the current project. Explain the flow in plain language and suggest the next logical step, adapted to what is already set up and which AIDD plugins are installed. Use when the user asks where to start, what to do next, how AIDD works, or to be onboarded. Not for listing every installed surface (the discovery skill does that) or running a skill the user already knows they need (invoke it directly).` |
 
 #### `skills/01-bootstrap`
 
 
@@ -1,79 +1,35 @@
-← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md)
+← [framework](../../../../README.md) / [aidd-context](../../README.md)
 
 # 00 - Onboard
 
-State-aware onboarding **hub** for the current project. Silently probes the
-project, its AIDD setup, and which AIDD plugins are installed, then opens a
-short briefing and a menu of project actions. Loops back to detection after
-each action so the briefing always reflects the latest state.
+A plain-language guide to the AIDD framework for the current project. It reads the project lightly, explains where the project sits in the AIDD flow, and suggests the next logical step, using only the plugins that are installed. It teaches as it goes and never assumes you already know the framework.
 
 ## When to use
 
 - "Where do I start?" / "Onboard me to this project."
-- "What should I run next?" / "What should I work on next?"
-- "What's the current state of this project?"
-- After a partial setup, to figure out what to do next.
+- "What should I do next?"
+- "How does AIDD work?"
+- After a partial setup, to figure out the next move.
 
-## When NOT to use
+## When not to use
 
-- To enumerate every installed surface from raw intent -> use the discovery
-  skill in this plugin.
-- To run a specific AIDD skill you already know you need -> invoke it directly.
+- To list every installed surface. Use the discovery skill in this plugin.
+- To run a specific skill you already know you need. Invoke it directly.
 
-## How to invoke
+## Flow
 
-```
-Use skill aidd-context:00-onboard
-```
+Three actions, in a loop:
 
-The skill walks 3 atomic actions in a loop:
+1. `read-project`: **silently** read a few plain facts about the project and the installed skills. Prints nothing.
+2. `orient`: explain where the project sits in the AIDD flow and suggest the next step, in plain language, then offer choices.
+3. `act`: run the suggestion, explain it, walk the whole flow, switch to a different step, hand off, or stop. Then loop back to `01`.
 
-1. `detect-state` - **silently** probe the filesystem, the project context,
-   and the installed AIDD surface. Prints nothing.
-2. `recommend-next` - render the briefing header and the hub menu, route the
-   user's pick to one concrete action.
-3. `execute-or-handoff` - carry out the choice (briefing, run, explain,
-   handoff, swap, stop), then loop back to `01`.
+It suggests by **function**, then resolves that to whatever skill is actually installed. A step with no installed skill is named as a gap, never an invented recommendation. The suggested step is always a hint, never a forced choice.
 
-## The hub menu
+## Requires
 
-Every pass opens with a three-line briefing (project, AIDD setup, standing),
-then this menu:
+Only the `aidd-context` plugin installed and enabled, and a working directory rooted in the target project. The `aidd_docs/` memory bank is **not** required: on a project without it, onboard's first suggestion is to set it up (the Context step). Onboard is the entry point, so it works before anything else exists.
 
-1. **Understand this project** - a full briefing on state, stack, AIDD setup,
-   and where the project stands.
-2. **Memory bank** - set it up if absent, refresh it if present.
-3. **Continue the SDLC** - open the journey sub-menu and pick a development leg.
-4. **List every installed surface** - open the discovery skill.
-5. **Stop**.
+## Details
 
-## The AIDD journey
-
-`bootstrap -> context-setup -> refine -> specify -> plan -> implement -> review -> ship`
-
-The first two legs (`bootstrap`, `context-setup`) are reached through hub
-option 2 (Memory bank); the remaining six (`refine` through `ship`) through the
-SDLC sub-menu under hub option 3.
-
-Onboard recommends by **category** (a function), then resolves the category to
-whatever installed skill fits. A leg with no installed skill is reported as a
-gap, never as an invented recommendation. The detected SDLC phase is shown only
-as a hint - onboard never forces a leg or assumes a phase is finished.
-
-## Outputs
-
-- A clean three-line project briefing (no raw snapshot, no `Analysis:` noise).
-- A hub menu of project actions, with one option marked as the suggested start.
-- Numbered sub-menus for the SDLC journey and for a resolved skill.
-- Updated detection after each action.
-
-## Prerequisites
-
-- Plugin `aidd-context` installed and enabled in the AI tool.
-- A working directory rooted in the target project.
-
-## Technical details
-
-See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for
-each of the 3 atomic actions, and `assets/state-matrix.md` for the hub menu,
-the SDLC sub-menu, the journey backbone, and the category resolution rules.
+See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for the three actions, and [`references/journey.md`](references/journey.md) for the AIDD flow stages and how each resolves to an installed skill.
@@ -1,43 +1,32 @@
 ---
 name: 00-onboard
-description: Detect the current project's state and open a hub of project actions - understand the project, set up or refresh the memory bank, or continue the AIDD development journey. Silently inspects the project, the AIDD setup, and which AIDD plugins are installed, then adapts the menu to that context. Use when the user says "where do I start", "onboard me", "onboard me to this project", "what should I run next", "what should I work on next", "what's the state of this project", "guide me through aidd", "guide me through aidd-context", or invokes `aidd-context:00-onboard`. Do NOT use to enumerate every installed surface from raw user intent (the discovery skill in this plugin handles that).
-model: opus
+description: Guide the user through the AIDD framework on the current project. Explain the flow in plain language and suggest the next logical step, adapted to what is already set up and which AIDD plugins are installed. Use when the user asks where to start, what to do next, how AIDD works, or to be onboarded. Not for listing every installed surface (the discovery skill does that) or running a skill the user already knows they need (invoke it directly).
 ---
 
 # Onboard
 
-State-aware onboarding hub for the current project. Silently inspects the project, the AIDD setup, and the installed AIDD plugins, then opens a briefing and a menu: understand the project, set up or refresh the memory bank, or continue the AIDD development journey. Loops until the user stops.
+A plain-language guide to the AIDD framework for the current project. It reads the project lightly, explains where the project sits in the AIDD flow, and suggests the next logical step using only the plugins that are installed. It loops until the user stops.
 
-## Available actions
+## Actions
 
-| #   | Action               | Role                                                                       | Input                  |
-| --- | -------------------- | -------------------------------------------------------------------------- | ---------------------- |
-| 01  | `detect-state`       | Silently probe the project, the AIDD setup, and the installed AIDD surface  | project root           |
-| 02  | `recommend-next`     | Render the briefing and the hub menu, route the pick to one concrete action | internal state from 01 |
-| 03  | `execute-or-handoff` | Carry out the choice: briefing, run, explain, handoff, swap, or stop        | choice from 02         |
+| #   | Action         | Role                                                              | Input             |
+| --- | -------------- | ---------------------------------------------------------------- | ----------------- |
+| 01  | `read-project` | Lightly and silently read the project and the installed skills    | project root      |
+| 02  | `orient`       | Explain where the project sits and suggest the next step, in plain language | the read from 01  |
+| 03  | `act`          | Run the suggestion, explain it, teach the flow, switch step, or stop | the user's choice |
 
-## Default flow
-
-`01 -> 02 -> 03 -> back to 01` after each action, until the user picks Stop. Run each action's `## Test` before moving to the next.
+Run `01 → 02 → 03`, then loop back to `01` after each step until the user stops. Run each action's `## Test` before the next.
 
 ## Transversal rules
 
-- Hub, not a track. Onboard shows a briefing and a menu of project actions; it never forces a single next step.
-- Silent detection. `01-detect-state` prints nothing - no `state:` snapshot, no signal dump, no `Analysis:` label ever reaches the user. The first visible output is the briefing header.
-- Briefing first. Every pass opens with a clean three-line briefing header: project, AIDD setup, standing.
-- Categories, never hard-coded foreign skills. Onboard recommends by category - a function such as "technical planning" or "shipping" - and resolves it at runtime against the skills actually installed. It never names a skill or plugin id that is not installed.
-- Honest gaps. A category that resolves to no installed skill is reported as a gap, described by function. Onboard never invents a skill to fill it.
-- `sdlc_phase` is a hint, never a verdict. Onboard shows where the project seems to stand but always lets the user pick the SDLC leg. It never assumes a phase is finished or unfinished.
-- Numbered choices only. The user replies with a digit. Free-text replies re-render the same menu with a one-line digit reminder.
-- Never assume the user will run a skill in this conversation. For a resolved skill always offer: run-in-session, explain, hand off to a new session, swap, stop.
-- Always loop back to `01-detect-state` after an action runs or is handed off. The project state changes; re-detect before re-rendering.
-- Anti-sycophancy. If the user picks an option that conflicts with the detected state, challenge once before complying.
-- Wait for an explicit user response between every menu. Do not auto-advance.
-
-## Assets
-
-- `@assets/state-matrix.md` - the hub menu, the SDLC sub-menu, the AIDD journey backbone, and the category resolution rules
+- Teach, do not assume. The user may be new to AIDD. Explain a term the first time it appears (the memory bank is the project memory the AI loads each session), never assume framework literacy.
+- Suggest, never force. Show where the project seems to stand and the next logical step, and always let the user choose another.
+- Plain language only. No internal state names, no raw phase labels, no signal dump reaches the user. The user reads guidance, not a state machine.
+- Adapt to what is installed. Suggest by function and resolve it to a skill that is actually installed. If none is installed, name the missing capability by function, never invent a skill.
+- Silent read. `01-read-project` prints nothing. The first visible output is the plain briefing from `02-orient`.
+- Re-read after each step. The project changes, so read again before suggesting again.
+- Wait for an explicit reply between prompts. Never auto-advance.
 
 ## References
 
-- The AI tool's native plugin and skill discovery - the runtime source of truth for which categories onboard can resolve to a real skill
+- `references/journey.md`: the AIDD flow stages, what each unblocks, and how a step resolves to an installed skill.
@@ -0,0 +1,35 @@
+# 01 - Read project
+
+Read the project lightly and **silently**. No questions, no writes, no visible output. The few facts gathered are working notes the next action uses to orient the user.
+
+## Input
+
+The project root, the current working directory.
+
+## Output
+
+Internal working notes only, **never printed**. Onboard must not show a snapshot or a list of checks. The first thing the user sees is the briefing from `02-orient`.
+
+The notes answer a handful of plain questions:
+
+- Is the project memory set up? Does `aidd_docs/memory/` exist, and does any file hold real content rather than a bare template?
+- When the memory is filled, what does it say the project is? Read the project brief and the architecture for the project's purpose, stack, and shape. This is the project's own context, and it leads the briefing.
+- Does the AI context file carry the `<aidd_project_memory>` block?
+- Is there code yet, and what stack? A manifest like `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, or the stack named in the memory when there is no manifest.
+- Is there a spec or a plan under `aidd_docs/`?
+- Is there an open pull request on the current branch?
+- Is the repo empty, nothing built yet?
+- Which AIDD plugins and skills are installed, with each skill's description?
+
+## Process
+
+1. **Check the setup.** `test -d aidd_docs/memory`, list its `*.md`, and judge whether any file is filled rather than an untouched template. When a file is filled, read the project brief and the architecture so the briefing speaks from the project's own context, not a guess. `grep -l '<aidd_project_memory>' CLAUDE.md AGENTS.md .github/copilot-instructions.md` for the context block.
+2. **Check the work.** Look for source files outside `aidd_docs/`, a stack manifest, a spec or plan under `aidd_docs/`, and an open pull request on the branch. If nothing is built at all, note the repo as empty.
+3. **List what is installed.** Use the AI tool's native plugin and skill discovery to gather the enabled AIDD plugins and the skills they expose, each with its description. This is how onboard adapts to what the user actually has.
+4. **Hold, do not print.** Keep the notes in context. Hand directly to `02-orient`.
+
+## Test
+
+- The action produces zero user-visible output. No snapshot, no check list, no labels appear.
+- The setup facts, the work facts, and the installed-skill list are all available to `02-orient`.
+- No skill id is named in the conversation by this action.