diff --git a/DOCS.md b/DOCS.md index 53694e0..4e318ac 100644 --- a/DOCS.md +++ b/DOCS.md @@ -912,7 +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). | +| `/onboarding [focus?] [--report-only]` | 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), resumable via its `onboarding` decision-log rail, then hands over explaining `/idea` (module-sized discovery, in Pi) vs `/feature` (one-sentence delta). `--report-only` defers the `/kit` decisions to a later run. | Design system and references: @@ -1483,6 +1483,12 @@ Shared conventions between the harness (Claude Code/Cursor) and Pi, all under history. Commands read the recent logs before interviewing and never re-ask a decided question. The log preserves the interview; the artifact (PRD/spec/manifest) stays the source of truth for WHAT was decided. + `/onboarding` uses the same script as a **resume rail** rather than an + interview log: `open onboarding` when the tour starts, one + `note --text "stage : …"` per completed stage, `close` at the + wrap-up — `latest onboarding --json` finding an `open` log is how an + interrupted tour resumes from its last stage note (never `open` again + mid-tour: that would supersede the trail). - **Stack research** — `ai-docs/research/.md`: before `/stack` documents or equips a technology, it must research FOUR dimensions — docs (+ `llms.txt`), agent skills (skills.sh registry), official CLI, official @@ -1703,7 +1709,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. | +| `/onboarding` | `[focus?] [--report-only]` | 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. The tour keeps a **resume rail** in the decision log (`open onboarding` → one stage note each → `close`): an interrupted session resumes from its last stage note instead of restarting. `--report-only` is the express path — the `/kit` stage presents its gap report and defers the design decisions to a later `/kit` run. | | `/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. | diff --git a/README.md b/README.md index 1e7f2b5..5480444 100644 --- a/README.md +++ b/README.md @@ -134,7 +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`. | +| `/onboarding [focus?] [--report-only]` | Existing project, first run: chains `/absorb` → `/stack` → `/kit` in one guided pass — ends ready for `/idea` or `/feature`. Interrupted tours resume where they stopped; `--report-only` defers the design-system decisions. | | `/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. | diff --git a/pi-templates/.pi/prompts/onboarding.md b/pi-templates/.pi/prompts/onboarding.md index 8adeb9e..e64ca82 100644 --- a/pi-templates/.pi/prompts/onboarding.md +++ b/pi-templates/.pi/prompts/onboarding.md @@ -1,6 +1,6 @@ --- 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]" +argument-hint: "[optional focus] [--report-only]" --- 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 @@ -9,13 +9,25 @@ 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): $@ +Focus/flags (optional; the focus goes 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. +0. **Guard + resume rail + 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 → the tour keeps a resume rail in the decision log + (cookbook `.pi/skills/fia/cookbooks/decision-log.md`): + - `node imp/scripts/decision-log.mjs latest onboarding --json` FIRST. An + `open` log = an interrupted tour: read its stage notes, confirm the + resume point with me in ONE question and KEEP that log id — a new + `open` would supersede the trail. No open log → + `open onboarding --topic "brownfield onboarding tour"`. + - After EACH stage lands: `note --text "stage : + done|skipped|report-only ()"` — that note trail is exactly + what a resumed tour reads. + Then announce the tour: three stages, what each produces, roughly what I + will be asked — and, on a large codebase, that this is a long session + (`--report-only` is the express path: the /kit decisions are deferred). 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 @@ -24,13 +36,18 @@ Focus (optional, passed to the /absorb stage): $@ 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: +3. **Kit** — follow `.pi/prompts/kit.md`, passing `--report-only` through + when I gave it (express mode: the gap report is presented and the design + decisions are deferred — running /kit later picks them up). Full mode: + 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 close the rail: + `close --outcome "" + --artifact ai-docs/PRD.md --artifact ai-docs/stack.md` and commit the + docs per the cookbook. 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 @@ -40,5 +57,5 @@ Focus (optional, passed to the /absorb stage): $@ 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. + A stage was skipped, /kit ran report-only 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 c3ccade..47b2e47 100644 --- a/pi-templates/.pi/skills/fia/SKILL.md +++ b/pi-templates/.pi/skills/fia/SKILL.md @@ -46,7 +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 | — | +| `/onboarding [focus?] [--report-only]` | first command on an existing system — chains /absorb → /stack → /kit in one guided pass (resumable via its decision-log rail; `--report-only` defers the kit decisions), ends ready for /idea or /feature | decision-log | | `/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/pi-templates/.pi/skills/fia/cookbooks/decision-log.md b/pi-templates/.pi/skills/fia/cookbooks/decision-log.md index d4dd6e9..fc1eca1 100644 --- a/pi-templates/.pi/skills/fia/cookbooks/decision-log.md +++ b/pi-templates/.pi/skills/fia/cookbooks/decision-log.md @@ -56,6 +56,13 @@ The log NEVER replaces the artifact — the PRD/spec/manifest remains the source of truth for WHAT was decided; the log preserves the interview itself (question, recommendation, answer) for audit and reuse. +`/onboarding` uses the same script as a **resume rail** rather than an +interview log: `open onboarding` when the tour starts, one `note --text +"stage : done|skipped|report-only (…)"` after each stage, `close` at the +wrap-up. `latest onboarding --json` is how an interrupted tour finds where it +stopped — an `open` log means resume from its last stage note; never `open` +again mid-tour (that would supersede the trail). + ## Reading it back - `latest [--json]` — most recent run of a command.