diff --git a/DOCS.md b/DOCS.md index f8eb56d..53694e0 100644 --- a/DOCS.md +++ b/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 — ` 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= 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 diff --git a/README.md b/README.md index 809101b..1e7f2b5 100644 --- a/README.md +++ b/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 diff --git a/pi-templates/.pi/prompts/onboarding.md b/pi-templates/.pi/prompts/onboarding.md new file mode 100644 index 0000000..8adeb9e --- /dev/null +++ b/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/.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 ""` — something MODULE-sized: a new area of the product + (new actor, new data domain, several screens). Deep interview → a + `## Module: ` 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. diff --git a/pi-templates/.pi/skills/fia/SKILL.md b/pi-templates/.pi/skills/fia/SKILL.md index d21685f..c3ccade 100644 --- a/pi-templates/.pi/skills/fia/SKILL.md +++ b/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 | diff --git a/src/steps/fia.js b/src/steps/fia.js index 88618d1..a089692 100644 --- a/src/steps/fia.js +++ b/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', '', diff --git a/src/steps/finish.js b/src/steps/finish.js index 1a392c7..789e4f5 100644 --- a/src/steps/finish.js +++ b/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. diff --git a/src/steps/mode.js b/src/steps/mode.js index f62de91..d178fd3 100644 --- a/src/steps/mode.js +++ b/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', );