feat: /onboarding — tour guiado do brownfield (/absorb → /stack → /kit) terminando em /idea ou /feature

DOCS.md

@@ -912,6 +912,7 @@ Planning, specs and scope:
 | `/quick "small change"` | Triage: SIMPLE only when blast radius ≤ ~3 files, one obvious shape, and none of: schema/migrations, auth/permissions, payments, new dependency, new route/page, new UI component, destructive data op. SIMPLE ships in one sitting with the guardrails on + one `## Q-NNN` audit line in `ai-docs/todos/quick-log.md`; anything else routes to `/feature`/`/bug` with the reason. Never touches the roadmap. |
 | `/note "idea"` | Appends `- [ ] YYYY-MM-DD — <idea>` to `ai-docs/inbox.md` and stops — zero questions. Later `/feature`/`/quick`/`/spec` tick items with `→ spec NNNN` / `→ Q-NNN` / `→ task NN`. |
 | `/absorb [focus?]` | Onboards an EXISTING system: surveys the code, writes `map.yaml`, the as-built PRD (never overwriting a human PRD — `PRD-as-built.md` instead), `stack.md` from what was observed, `conventions.md`, the as-built component registry and a distilled project skill; short interview for what code can't reveal. Changes no code, creates no tasks; recommends `/kit` when the registry comes out empty/duplicated. |
+| `/onboarding [focus?]` | The first command on an EXISTING system: chains `/absorb` → `/stack` → `/kit` in one guided pass (each command's own file stays the law — interviews, decision logs and approvals included), then hands over explaining `/idea` (module-sized discovery, in Pi) vs `/feature` (one-sentence delta). |
 
 Design system and references:
 
@@ -1678,7 +1679,7 @@ not exist"). Deep procedures live in 15 cookbooks
 run_fda, create_fda, observability, decision-log, stack, specs, components,
 theme, design, examples, launch, update_roster.
 
-### 12.1 The 23 commands (`.pi/prompts/`)
+### 12.1 The 24 commands (`.pi/prompts/`)
 
 | Command | Arguments | What it does |
 |---|---|---|
@@ -1702,6 +1703,7 @@ theme, design, examples, launch, update_roster.
 | `/design` | `images + scope` | Layout redesign from references — structure from the image, identity from OUR system. |
 | `/example` | `URL [notes] \| list` | Register an external reference on the shelf (license researched, `What NOT to take` mandatory). |
 | `/agents` | — | Opens the viewer's Agents tab (`npm run agents -- --detach`) to edit engines/models/fallbacks; Pi is forbidden from editing `imp/fia.config.yaml` itself. |
+| `/onboarding` | `[focus?]` | First command on an EXISTING system: chains `/absorb` → `/stack` → `/kit` in one guided pass (each stage's own prompt is the law; stages whose artifacts already exist can be kept and skipped), then hands over explaining the split — `/idea` for a MODULE-sized addition vs `/feature` for a one-sentence delta. |
 | `/absorb` | `[focus?]` | Brownfield onboarding (as-built PRD/map/conventions/registry + project skill in `.pi/skills/project/` AND `.claude/skills/project/`); recommends `/kit` when the registry comes out empty/duplicated. |
 | `/kit` | `[focus?] [--report-only]` | Brownfield design-system audit → gap report → approved design-only tasks. |
 | `/status` | — | Read-only progress: tasks, milestones (status as declared), specs, inbox, latest runs and failed phases. |
@@ -2082,8 +2084,9 @@ CREATE_IAI_TOKEN=<token> npx impactus my-saas --yes --preset saas --payments asa
 cd my-app
 npx impactus --dir .         # detects the project → harness + FIA only; nothing overwritten
 imp
-/absorb                      # as-built PRD + map + conventions + stack manifest + registry
-/kit                         # (recommended when the registry came out empty) DS audit → tasks
+/onboarding                  # guided pass: /absorb (as-built PRD + map + conventions +
+                             #   stack manifest + registry) → /stack (docs + tooling)
+                             #   → /kit (design-system audit → approved tasks)
 /feature "CSV export on the reports page"   # delta spec + tasks, approved before running
 /bug "login loops after logout"             # proven RED, then the fix
 /quick "rename the Save button"             # small change, one audit line

README.md

@@ -134,6 +134,7 @@ imp handoff                    # continue the newest Pi conversation in `claude`
 | `/bug "the symptom"` | Records the defect, proves a valid failing test first (RED), then fixes it. |
 | `/quick "small change"` | Triage: a genuinely small change ships in one sitting; anything bigger routes to `/feature` or `/bug`. |
 | `/spec [capability]` | Durable spec — requirements + BDD scenarios + traceability gates. |
+| `/onboarding [focus?]` | Existing project, first run: chains `/absorb` → `/stack` → `/kit` in one guided pass — ends ready for `/idea` or `/feature`. |
 | `/absorb [focus]` | Existing project → as-built PRD, map, conventions, stack manifest and component registry. |
 | `/kit` | Design-system audit of existing code: as-built registry, gap report, design-only tasks. |
 | `/component`, `/theme`, `/design`, `/example` | Design system: add a component, change colors/fonts, redesign from references, register an external reference. |
@@ -154,7 +155,7 @@ imp handoff                    # continue the newest Pi conversation in `claude`
 | `/test-ui [flow?]` | Tests the UI in a real browser, with automated sign-in and issue detection. |
 | `/team [task]` | Multi-agent orchestration: parallel specialist agents on one task. |
 | `/restore` | Rolls code + database back to a previous save (destructive — confirms first). |
-| `/grill`, `/stack`, `/absorb`, `/quick`, `/spec`, `/feature`, `/bug`, `/component`, `/theme`, `/design`, `/example`, `/kit`, `/launch`, `/note` | The same planning, spec and design-system commands also live here. |
+| `/grill`, `/stack`, `/absorb`, `/onboarding`, `/quick`, `/spec`, `/feature`, `/bug`, `/component`, `/theme`, `/design`, `/example`, `/kit`, `/launch`, `/note` | The same planning, spec and design-system commands also live here. |
 
 ### Dashboards & utilities (npm scripts stamped into the project)
 
@@ -224,7 +225,8 @@ cd my-app
 npx impactus --dir .      # detects the existing project → harness + FIA only,
                           # nothing in your code is overwritten
 imp
-/absorb                   # as-built PRD + map + conventions + stack manifest
+/onboarding               # guided pass: /absorb → /stack → /kit (as-built PRD,
+                          # map, stack docs, design-system audit)
 /feature "CSV export on the reports page"   # new feature → delta spec + tasks
 /bug "login loops after logout"             # defect → proven RED, then the fix
 /quick "rename the Save button"             # small change, no ceremony

pi-templates/.pi/prompts/onboarding.md

@@ -0,0 +1,44 @@
+---
+description: First command on an EXISTING system — /absorb → /stack → /kit in one guided pass, ending ready for /idea or /feature
+argument-hint: "[optional focus, e.g. only the sales module]"
+---
+Read `.pi/skills/fia/SKILL.md`. This is the ONE command to run right after
+installing on an EXISTING system: it chains the three brownfield onboarding
+commands in order and ends with the project ready for new work. You orchestrate
+the sequence — each stage's own prompt is the law: follow it to the letter
+(interviews, decision logs, approvals included). NEVER change product code
+here (the only exception is /kit's `/ui-components` page, per its own prompt).
+
+Focus (optional, passed to the /absorb stage): $@
+
+0. **Guard + announce** — run `node imp/scripts/project-mode.mjs --json` and
+   trust it. Not `brownfield` → stop: there is nothing to absorb; route in one
+   line — no PRD yet → /idea (discover the product), PRD exists but nothing
+   built → /grill then /map. Brownfield → announce the tour: three stages,
+   what each produces, roughly what I will be asked.
+1. **Absorb** — follow `.pi/prompts/absorb.md`: as-built PRD, `ai-docs/map.yaml`,
+   conventions, stack manifest, component registry and the project skill. If
+   `ai-docs/map.yaml` AND the as-built PRD already exist, show what is there
+   and ask ONE question: re-run or keep them and skip ahead.
+2. **Stack** — follow `.pi/prompts/stack.md` (full pass): decide any layer
+   still "decide later", run the mandatory research, write
+   `ai-docs/apis/<tech>.md` for each technology in use and equip the project
+   (skills, CLIs, MCPs).
+3. **Kit** — follow `.pi/prompts/kit.md`: as-built registry + `/ui-components`
+   page, gap report vs the core kit, and ONLY engineer-approved design-only
+   tasks — "nothing approved" is a valid outcome; approved tasks run later via
+   /task or /goal.
+4. **Wrap-up** (mandatory) — recap the three stages in one line each (artifact
+   paths), then hand over — the system now behaves like a project "with a
+   PRD". Explain the split:
+   - `/idea "<module>"` — something MODULE-sized: a new area of the product
+     (new actor, new data domain, several screens). Deep interview → a
+     `## Module: <name>` chapter appended to the PRD; /feature then turns it
+     into specs + tasks.
+   - `/feature "what you want"` — a delta on the existing system you can
+     describe in one sentence. Delta interview → delta spec → only the NEW
+     tasks, shown for my approval before anything runs.
+   Rule of thumb: can't describe it in one sentence → /idea; otherwise
+   /feature. (Defect → /bug; tiny change → /quick.)
+   A stage was skipped or /kit tasks were approved → say what is pending and
+   the command that resumes it.

pi-templates/.pi/skills/fia/SKILL.md

@@ -46,6 +46,7 @@ Short commands (prompt templates in `.pi/prompts/`) are the student entry points
 | `/design [images]` | layout redesign from references, inside the design system | design |
 | `/example [URL or slug]` | register an external reference (repo, code, docs, design) on the examples shelf | examples |
 | `/agents` | visual roster editor — engines, models, fallbacks (viewer "Agents" tab) | update_roster |
+| `/onboarding [focus?]` | first command on an existing system — chains /absorb → /stack → /kit in one guided pass, ends ready for /idea or /feature | — |
 | `/absorb [focus]` | existing project → as-built PRD + map + conventions + stack manifest + component registry | — |
 | `/kit` | existing code → design-system audit: as-built registry + `/ui-components`, gap report vs the core kit, approved design-only tasks (`Kind: kit`) | components |
 | `/status` | progress + latest runs | observability |

src/steps/fia.js

@@ -172,6 +172,7 @@ export async function setupFia(ctx) {
       '  /example    put an external reference (repo, code, docs, screen) on the shelf: read, licensed, indexed',
       '',
       'Existing code',
+      '  /onboarding EXISTING project, first run → /absorb + /stack + /kit in one guided pass, then /idea or /feature',
       '  /absorb     EXISTING project → as-built PRD + map + stack manifest',
       '  /kit        EXISTING code → design-system audit: as-built registry, /ui-components, gaps vs the core kit, approved design-only tasks',
       '',

src/steps/finish.js

@@ -289,8 +289,8 @@ export async function finish(ctx) {
               'EXISTING project — the path is having the system understand your code before touching it:',
               '',
               ctx.fiaInstalled
-                ? `1. Run \`${agentCmd(ctx)}\`${fiaNeedsLogin ? ', run /login openai-codex (only that one — Anthropic stays on the `claude` CLI)' : ''} and type /absorb — it generates the as-built PRD, the map, the conventions and the stack manifest (ai-docs/stack.md) of your system.`
-                : '1. Open Claude Code in this folder and run /absorb — it generates the as-built PRD, the map, the conventions and the stack manifest (ai-docs/stack.md) of your system.',
+                ? `1. Run \`${agentCmd(ctx)}\`${fiaNeedsLogin ? ', run /login openai-codex (only that one — Anthropic stays on the `claude` CLI)' : ''} and type /onboarding — one guided pass through /absorb (as-built PRD, map, conventions, stack manifest), /stack (per-tech docs + tooling) and /kit (design-system audit).`
+                : '1. Open Claude Code in this folder and run /onboarding — one guided pass through /absorb (as-built PRD, map, conventions, stack manifest), /stack (per-tech docs + tooling) and /kit (design-system audit).',
               '2. New feature: /feature "what you want". Defect: /bug "the symptom".',
               // /task and /goal are Pi prompts (not Claude Code commands) —
               // say WHERE they run, or people type them in the wrong tool.

src/steps/mode.js

@@ -122,9 +122,10 @@ export async function selectInstallMode(ctx) {
       [
         'I detected an EXISTING project in this folder (package.json/git).',
         'The recommended path is to install just the harness + FIA on top — none',
-        'of your files are overwritten — and then run /absorb in `pi` so the',
-        'system understands the project (generates the as-built PRD, map,',
-        'conventions and the stack manifest in ai-docs/stack.md).',
+        'of your files are overwritten — and then run /onboarding in `pi`: one',
+        'guided pass (/absorb → /stack → /kit) that maps the system (as-built',
+        'PRD, map, conventions, stack manifest, design-system audit) and leaves',
+        'it ready for /idea or /feature.',
       ].join('\n'),
       'Existing project',
     );