@jakkrichm/create-nexus-devflow 2.1.0 → 2.2.1

package/template/.claude/skills/implement/SKILL.md

@@ -1,64 +1,207 @@
 ---
 name: implement
-description: "[Devflow] Fast-Track Implement stage in DevFlow (Blueprint Mode) - execute checklist tasks incrementally with TDD and update current-feature.md in context."
-argument-hint: "{running-id or workspace path}"
+description: "[devflow][F] Build the feature, fix, or rollback spec'd in devflow/context/current-feature.md, one small reviewable step at a time. Creates the matching branch, implements each step, shows the diff and explains it in plain English, tests, and iterates until it works. Type: Rollback specs use a guarded reverse patch that preserves Blueprint history. After each approved step it offers an optional commit checkpoint on the branch; the work-level commit, merge, and logging are /complete's job. Use when the user runs /implement, or asks to build, implement, or start the current feature, fix, or rollback once its spec is ready."
 ---
 
-# Fast-Track: Implement (Blueprint Mode)
+# implement - build the current spec, one reviewed step at a time
 
-$ARGUMENTS
+Where this sits in the workflow:
 
-Incremental code execution stage in Fast-Track. Reads the Single Living Spec (`devflow/context/current-feature.md`), executes checklist tasks, implements tests (TDD), and updates the implementation record.
+    /feature, /fix, or /rollback  ->  [implement]  ->  /complete  ->  next
+    (the spec)                         (build it,       (commit +
+                                        reviewed)        merge + log)
 
-## Invocations & Aliases
+`/feature`, `/fix`, or `/rollback` wrote the spec to
+`devflow/context/current-feature.md` and stopped.
+This skill turns that spec into code, following the build loop in
+`devflow/context/ai-interaction.md`, without vibe coding: small steps, a visible diff plus
+a plain-English explanation for each, testing, and iteration until it works, all
+behind your approval. It builds on a branch and offers an optional commit
+checkpoint after each step; the work-level commit, merging, and logging are
+`/complete`'s job.
 
-- `/implement`: Run implementation on current active run
-- `/implement {id}`: Run implementation on specified ID
-- `$implement`: Codex CLI invocation
+## Before you start
 
-## Fast-Track Mainline Workflow
+Read `devflow/context/current-feature.md`. If it has no real spec (still the stub, or its
+status is already complete), stop and tell the user to run `/feature` (for a
+planned feature), `/fix` (for an ad-hoc bug or change), or `/rollback` (for a
+completed feature reversal) first. Pull the
+conventions from `devflow/context/coding-standards.md` and the data model from
+`devflow/context/project-overview.md` so the code matches them.
 
-```text
-/feature (หรือ /fix) ──▶ /implement ──▶ /check ──▶ /complete
-```
+If the spec's Design reference points at `prototypes/*.html`, those mockups are
+the visual target - build components to match them, and treat `prototypes/theme.css`
+as the token source (the spec's first step ports it into the app's global
+stylesheet before the components are built).
 
-## Behavior & Contract
+**Resuming?** If the spec already has some build steps checked off (`- [x]`), this
+feature was started earlier and interrupted (often a cleared context). The spec and
+its ticked steps are files, so pick up where it left off: read which steps are done,
+check the git branch and `git status`/log to see what is committed and what is still
+in the working tree, then continue from the **first unchecked step** instead of
+starting over. No separate save/load is needed - the project instructions load
+`current-feature.md` every session.
 
-When invoked:
+## Step 1 - branch
 
-### 1. Load Active Context
-1. Identify active Running ID from `devflow/context/current-stage.md` or `devflow/context/current-feature.md`.
-2. Read `devflow/context/current-feature.md`.
-3. Locate `## 2. Plan & Test Strategy` and `## 3. Implementation Checklist`.
+Create and check out a branch named from the spec: `feature/<name>` for a feature,
+`fix/<name>` for a fix, or `rollback/<name>` for a Type: Rollback spec. If the
+project isn't a git repo yet, say so and ask the user to run `git init` first;
+the loop needs branches. On resume, the branch already exists - check it out
+instead of creating a new one.
 
-### 2. Incremental Execution with TDD
-1. Select unchecked items `- [ ]` from the checklist in order.
-2. For each task:
-   - **TDD (Red-Green-Refactor)**: When `Test Decision: Required`, create or update unit tests first.
-   - Implement the minimal, clean code change satisfying the task.
-   - Run localized verification (e.g. `npm test`, linter).
-   - Mark the item as `- [x]` in `current-feature.md`.
+### Type: Rollback safeguard
 
-### 3. Update Living Spec (`current-feature.md`)
-Append or update `## 4. Implementation Record` in `devflow/context/current-feature.md` with:
-- Summary of completed tasks and modified files
-- Key architectural observations or notes
-- Status of checklist items
+For a rollback spec, do not hand-delete the old feature and do not run a whole
+commit `git revert`. Completed feature commits also contain Blueprint history and
+plan bookkeeping, while `current-feature.md` now contains the active rollback
+spec. Reversing the whole commit would damage that state.
 
-Example:
-```markdown
-## 4. Implementation Record
-- **[Task 1.1]**: Implemented JWT auth middleware in `src/middleware/auth.ts`
-- **[Task 1.2]**: Added unit tests in `test/auth.test.ts` (All 6 tests passing)
-- **[Task 1.3]**: Registered auth route in `src/server.ts`
-```
+Before the first rollback build step:
 
-### 4. Update Workspace Status
-Update `devflow/context/current-stage.md`:
-- `Current Stage`: `implement (Fast-Track -> Checklist Completed -> Ready for /check)`
+1. Re-resolve the target archive's introducing commit and confirm it matches the
+   full Target commit SHA recorded in the approved spec.
+2. Confirm the target is an ancestor of `HEAD`, has the recorded single parent,
+   and the only dirty path before applying the patch is the approved rollback
+   spec. Stop on drift.
+3. Preview the target's product diff while excluding `.agents/**`, `.claude/**`,
+   `devflow/**`, `AGENTS.md`, `CLAUDE.md`, and
+   `prototypes/**`. Confirm the preview is non-empty and matches the Product
+   paths in the spec.
+4. Apply that product diff in reverse with three-way conflict detection and
+   stage it. Substitute the two approved full SHAs before running:
 
-### 5. Output Summary & Next Step
-Report to the user:
-- Completed checklist items and modified files
-- Local verification results
-- **Next Command**: `/check` (or `/check {ID}`)
+       git diff --binary <target-parent> <target-commit> -- . \
+         ':(exclude).agents/**' \
+         ':(exclude).claude/**' ':(exclude)devflow/**' \
+         ':(exclude)AGENTS.md' ':(exclude)CLAUDE.md' \
+         ':(exclude)prototypes/**' |
+         git apply --reverse --3way --index
+
+   Never omit the protected pathspec exclusions for convenience.
+5. Show both `git diff --cached` and `git status`. Confirm no protected path is
+   staged or modified before presenting the step for review.
+
+If the reverse patch conflicts, stop and report the exact paths and later commit
+that appears involved. Do not auto-resolve, discard, stash, reset, or switch to a
+broad checkout. Ask whether to resolve only the conflict allowed by the approved
+spec or abandon the attempt. A cascade into another completed feature needs a
+new rollback plan.
+
+## Step 2 - build one step, review, iterate, checkpoint
+
+Work through the spec's build steps in order, one at a time. For each step:
+
+1. Implement just that step: the smallest change that satisfies its "done when."
+2. Show the **diff**, not whole files.
+3. **Explain it, and prove it.** Give a short summary: what the step delivered,
+   one line per changed file on what it does and why, then confirm the step's
+   "done when" is met with evidence (build output, a screenshot, a passing
+   assertion). This summary is the comprehension gate, so keep it concrete, not
+   ceremonial. Include a short **How to try it** note when the step has a manual
+   path: the command, URL, click, endpoint, or output the user can check.
+4. **Verify the step.** If `AGENTS.md` declares a `Verify` command, run that exact
+   command as the automated gate. It is only an umbrella for checks the project
+   actually has, so do not invent tests or other checks to satisfy it. If no
+   `Verify` command exists, run the documented build command and the test command
+   when the project declares one. A step that adds logic must ship a passing test
+   in the same diff when the test gate is on, and the suite must be green before
+   the step is approved (see the Testing gate in `coding-standards.md`). UI and
+   integration-only steps ride on screenshot plus build evidence. Run a focused
+   test separately when it gives faster feedback, then use `Verify` as the final
+   automated gate. For UI or integration done-whens, prefer Playwright when it is
+   already installed or declared in `AGENTS.md`; do not add it silently for an
+   unrelated feature. Create focused test files next to the source they cover,
+   per `coding-standards.md`. Never install a runner mid-step unless the current
+   spec is explicitly the unit-testing setup itself (for example `/fix "add unit
+   testing"`). If a step surfaces non-trivial logic the spec did not foresee, add
+   a focused test then, or note why not. When a step's done-when is behavioral (a
+   click, a download, or a flow across screens), run `/check` to prove it against
+   the running app rather than eyeballing it.
+5. **Iterate until it works.** If it fails or the user wants changes, revise the
+   step (re-prompt or hand-edit the code), show the updated diff, and re-test.
+   Repeat until it works and the user approves. Nothing is committed until the
+   user is happy with the step.
+6. **Mark it done, then prompt to move on.** Once the step is approved, check that
+   step off (`- [x]`) in `devflow/context/current-feature.md` so progress survives a context
+   clear. If the step repaired a finding tracked in
+   `devflow/context/findings.md`, set that finding's status to `fixed` now too
+   and note the repair in its **Resolution** line. Never set `closed`: a repair
+   is re-reviewed by `/audit` before it clears, because a fix can introduce a
+   worse defect than the one it removed. Then offer a short choice, noting that checkpoints are optional since
+   `/complete` makes the real feature-level commit. Use the current tool's short
+   user-input prompt when available; when you've just produced a long block to
+   read (a deep explanation, a big
+   walk-through), ask in plain text instead, so the prompt doesn't cover what the
+   user is still reading:
+   - **Continue** (default) - roll into the next step without committing.
+   - **Commit checkpoint** - commit just this step on the branch with a
+     conventional message (a cheap rollback point).
+   - **Walk me through it** - give a deeper, line-level explanation of the new or
+     changed code (why this approach, what each part does, any gotchas), then
+     re-ask this checkpoint prompt. A loop-back, not a terminal choice.
+   - **Stop here** - pause the loop so the user can review or come back later.
+
+   On **Continue** or after **Commit checkpoint**, go to the next step. On **Walk
+   me through it**, explain in depth and then re-ask this prompt in plain text (the
+   explanation is long, so a modal would cover it). On **Stop here**, stop and say
+   where things stand: the branch is intact; run `/implement` again to resume, or
+   `/complete` to wrap up what's built so far.
+
+Never batch the whole thing into one diff. If a step's diff is too big to read,
+split it. The documented `Verify` command, or the fallback build and tests, must
+pass before any commit.
+
+## Step 3 - hand off to /complete
+
+Before handing off, check `devflow/context/findings.md`. A P0 or P1 finding
+still `open` or `fixed` there means `/complete` will refuse the merge, so close
+the loop now:
+
+- Repair each `open` P0 or P1 as an extra reviewed step. First append it to the
+  spec's build steps in `current-feature.md` (`- [ ] Repair F-03 - <title>`) so
+  the repair is on the record and survives a context clear, then run the same
+  loop as Step 2: smallest change, diff, plain-English explanation, evidence.
+  Check the step off and mark the finding `fixed` together.
+- Then run `/audit` so the repairs are re-reviewed and can move to `closed`.
+  A repair this skill made never closes itself.
+- If the user decides a finding should not be fixed, only they can set
+  `accepted` (reason recorded). A finding that looks wrong goes back to
+  `/audit` to invalidate with recorded evidence; this skill never sets
+  `accepted` or `invalid`.
+
+When every step is built and `Verify`, or the fallback build and tests, passes
+(committed as checkpoints or not), stop with a compact review packet:
+
+- branch name
+- what changed, grouped by file or area
+- checks run, with the exact command or proof used
+- how to try it manually, or a pointer to `/try`
+- ledger state: any findings still `open` or `fixed`, by ID
+- known risks, skipped checks, or follow-up notes
+- next action, usually `/complete`
+
+Then tell the user `/complete` makes the one work-level commit, logs it (archive,
+update the build plan for a feature or rollback, reset), and merges with
+approval. This skill does not touch main.
+
+## Rules
+
+- One small step per diff; the user reviews and approves each before any commit.
+- Explain every change in plain English. Understanding the code is the point.
+- Iterate on the branch until each step works; never commit code the user hasn't
+  approved.
+- Follow `devflow/context/coding-standards.md` (server vs client, scope user-owned queries
+  by the authenticated user id, validate inputs, and so on).
+- Build only what the spec says. If the spec is wrong or thin, stop and fix the
+  spec first, do not improvise.
+- Per-step commits are optional checkpoints. The work-level commit, the merge,
+  and any push are `/complete`'s job.
+- For Type: Rollback, reverse only the approved product diff and preserve all
+  protected Blueprint paths.
+
+## Formatting
+
+Format the output to match the project's conventions in
+`devflow/context/ai-interaction.md`: concise, scannable markdown, with lists for
+enumerations and tables for matrices rather than dense paragraphs.

package/template/.claude/skills/onboard/SKILL.md

@@ -1,129 +1,260 @@
 ---
 name: onboard
-description: "[Devflow] Set up Nexus-DevFlow after overlaying it onto a freshly scaffolded or early-stage project."
+description: "[devflow][B] Set up the Blueprint after overlaying it onto a freshly scaffolded or early project. Detects the stack, tunes project files and adapters, documents real commands and existing checks, points to the optional standalone CI setup, and tells the user what to fill in before /overview or $overview. Use when the user runs /onboard, invokes $onboard, just copied the Blueprint into a new project, or asks what to do after overlaying the Blueprint. For an existing app with meaningful shipped features, use adopt instead."
 ---
 
-# onboard - Finish the Nexus-DevFlow Setup for Fresh Projects
+# onboard - finish the Blueprint overlay setup
 
 Where this sits in the workflow:
 
-```text
-scaffold app  ->  overlay DevFlow  ->  [onboard]  ->  00-explore or 10-define  ->  Mainline Loop
-(user/tool)       (create-nexus)       (tune setup)   (discovery / run scoping)      (20-spec -> 70-deliver)
-```
+    scaffold app  ->  overlay Blueprint  ->  [onboard]  ->  project-plan + build-plan  ->  /overview
+    (user/tool)       (copied files)          (tune setup)   (user-owned inputs)       (generated context)
 
-`onboard` is the fresh-project on-ramp for Nexus-DevFlow. It assumes the application was scaffolded first (e.g. via `create-next-app`, `create-vite`, `cargo new`, etc.) and DevFlow was overlaid after.
+`/onboard` is the fresh-project on-ramp. It assumes the app was scaffolded first
+and the Blueprint files were overlaid after. Run it before filling in plans or
+running `/overview`. Its job is to make the Blueprint fit the real project before
+planning starts: commands, project title, conventions, ignore rules, and tool
+adapters. It also asks whether the Blueprint workflow files should be committed
+with the repo or kept local-only through `.gitignore`.
 
-Run `onboard` before starting discovery or delivery runs. Its job is to make DevFlow fit the real project from day one: detecting commands, project name, coding conventions, ignore rules, and tool adapters.
+Use `/adopt` instead when the app is brownfield: real routes, shipped features,
+and project behavior already exist and need to be reflected into the plans.
 
-Use `adopt` instead when the app already has substantial shipped code, working routes, and existing business logic.
+## Input
 
----
+No argument is required. If the user provides context about the stack, hosting,
+database, auth, or preferred tool, use it as a hint and verify against files.
 
-## Input
+## Step 0 - confirm this is onboarding, not adoption
 
-No argument is required. If the user provides context about the stack, database, authentication, or preferred tooling, use it as a hint and verify against files.
+Inspect the repository and the two planning docs:
 
----
+- If `devflow/project-plan.md` and `devflow/build-plan.md` are mostly empty or
+  worksheet-like, proceed.
+- If the app already has substantial shipped features, stop and recommend
+  `/adopt` instead.
+- If the plans already contain real user-owned content, do not overwrite them.
+  Continue only with setup files such as `AGENTS.md`, `coding-standards.md`,
+  `.gitignore`, and optional notes.
 
-## Step 0 - Confirm Onboarding vs Adoption
+Never run a framework scaffolder. The Blueprint is already overlaid.
 
-Inspect the repository and context files:
+## Step 1 - survey the project facts
 
-- If the project is freshly scaffolded with minimal boilerplate, proceed.
-- If `devflow/context/project-overview.md` and `devflow/context/coding-standards.md` already contain rich, user-customized content, do not overwrite them without explicit confirmation.
-- If the repository already has substantial existing routes, controllers, or database models, stop and recommend `adopt` instead.
+Read only enough to identify the setup:
 
-Never run a framework scaffolder. DevFlow is already overlaid.
+- package manager and lockfile (`pnpm-lock.yaml`, `package-lock.json`,
+  `yarn.lock`, `bun.lockb`, etc.)
+- manifest scripts (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, and
+  similar)
+- framework and runtime config (`astro.config.*`, `next.config.*`, `vite.config.*`,
+  `tailwind.config.*`, database config, test config)
+- source layout, route layout, and app/package directories
+- existing `.gitignore`
+- whether `.agents/` and `.claude/` are both needed
+- whether Blueprint workflow paths are already tracked by git
+- existing verification commands and `.github/workflows/`
+- project name, from `package.json`, the folder name, existing docs, or the user
 
----
+Do not infer more than the files support. Mark uncertain items as `> TODO` in the
+summary rather than inventing a convention.
 
-## Step 1 - Survey the Project Facts
+## Step 2 - update project entry files
 
-Read only enough to identify the setup:
+If the root `README.md` is a copied Blueprint workflow document, replace that
+obsolete overlay content in the product README slot:
 
-- **Package Manager & Lockfile**: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`, `Cargo.lock`, `poetry.lock`, `go.sum`, etc.
-- **Manifest Scripts**: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.
-- **Framework & Configs**: `tsconfig.json`, `next.config.*`, `vite.config.*`, `astro.config.*`, `tailwind.config.*`, database configs, test configs.
-- **Source Layout**: `src/`, `app/`, `pages/`, `components/`, `lib/`, etc.
-- **Existing Git & Ignore Rules**: `.gitignore`, git branches.
-- **Project Name**: Extracted from manifest, root directory, or user.
+- Detect it conservatively: the first heading is `# AI Coding Blueprint`, or the
+  opening section clearly describes the Blueprint workflow rather than this app.
+- Create a small root `README.md` stub for the actual project using the detected
+  project name, one-line purpose when known, and the Commands from `AGENTS.md`.
+  Keep it minimal if the project plan is not filled yet.
+- Do not move or copy the workflow document into `devflow/`. Agents use the
+  local skills, plans, and context files directly.
+- Remove any `AGENTS.md` claim that a project README explains the Blueprint
+  workflow.
 
----
+If the root `README.md` already looks like a real project README, leave it alone.
+Never replace a project README with Blueprint documentation.
 
-## Step 2 - Update Entry Files (AGENTS.md & CLAUDE.md)
+Update the Commands section of `AGENTS.md` to match real scripts and commands.
+Include only commands that exist or are intentionally available:
 
-1. **Update `AGENTS.md` Commands**:
-   - Fill in the actual commands found in the project:
-     - `Dev`: dev server command (e.g. `npm run dev`)
-     - `Build`: production build command (e.g. `npm run build`)
-     - `Test`: test runner command (e.g. `npm test`, `vitest`, `pytest`)
-     - `Lint / Typecheck`: linting and typechecking commands
-     - `Verify`: combined verification command if present (e.g. `npm run check` or `npm run typecheck && npm test && npm run build`)
-   - If no test command exists, state explicitly that testing is opt-in and not yet configured.
+- dev server
+- build
+- preview or start
+- lint, format, typecheck, and test, if configured
+- verify, when a real combined verification command already exists
+- useful app-specific commands, if obvious
 
-2. **Update `CLAUDE.md`**:
-   - Replace any `# Project Name` placeholder with the real detected project name.
-   - Keep `@AGENTS.md` and `@devflow/context/...` imports intact.
+If no test command exists, say so explicitly. Do not claim tests are a gate until
+a real test command is configured.
 
----
+If `CLAUDE.md` exists and still has the placeholder `# Project Name`, replace it
+with the detected project name. Keep the `@AGENTS.md` and `@devflow/...`
+imports intact. Do not move detailed app context into `CLAUDE.md`; that belongs
+in `AGENTS.md` and the generated project overview.
 
-## Step 3 - Tune Coding Standards
+## Step 3 - tune coding standards
 
-Update `devflow/context/coding-standards.md` to match the detected stack:
+Update `devflow/context/coding-standards.md` so it matches the detected stack.
+Keep stable, tool-agnostic sections such as writing style, comments, scope, and
+testing philosophy. Replace stack-specific defaults that do not apply.
 
-- Framework, rendering model, and component architecture
-- Package manager and runtime
-- Project directory conventions
-- Styling approach (Tailwind CSS, Vanilla CSS, CSS Modules)
-- Data fetching, state management, and API boundaries
-- Validation and error handling expectations
-- Testing expectations
+Cover the practical conventions the build loop needs:
 
-Keep core general rules (functional style, small focused functions, clear naming) and replace template placeholders with real patterns.
+- framework and rendering model
+- package manager
+- project structure
+- styling approach
+- data access and API boundaries, if known
+- validation and error handling expectations
+- test gate status
+- build and verification commands, via `AGENTS.md`
 
----
+If the project is too new to reveal a convention, leave a concise `> TODO` rather
+than pretending a pattern exists.
 
-## Step 4 - Check AI Interaction Rules
+## Step 4 - check AI interaction rules
 
-Review `devflow/context/ai-interaction.md` and adjust if needed:
-- Language preferences (`artifact_language: "th"` or `"en"`)
-- Branching conventions
-- Review checkpoint expectations
+Read `devflow/context/ai-interaction.md` and update only obvious mismatches.
+Usually the default review loop should stay intact. Flag preferences for the user
+instead of guessing, such as:
 
----
+- whether commits should be offered after every step
+- whether branches should use a different naming pattern
+- whether `/check` should require browser evidence for UI work
 
-## Step 5 - Check Ignore Files, Visibility & Tool Adapters
+If no changes are needed, say so.
 
-1. **Update `.gitignore`**: Ensure common build artifacts, dependencies, and environment files are ignored.
-2. **DevFlow Visibility**:
-   - By default, keep DevFlow files tracked in git for team collaboration.
-   - If local-only mode is requested, add `devflow/`, `.agents/`, `.claude/`, `CLAUDE.md` to `.gitignore` while keeping `AGENTS.md` public.
-3. **Tool Adapters**:
-   - Codex & Antigravity use `.agents/skills/`.
-   - Claude Code uses `.claude/skills/`.
-   - Both can coexist cleanly.
+## Step 5 - point to optional CI setup
 
----
+Do not create or change Verify commands or GitHub workflows during onboarding.
+Report any verification command or CI already present. When equivalent automatic
+pull-request checks are absent, mention the optional standalone setup:
+
+```text
+Run /ci or $ci when you want automatic GitHub checks.
+```
 
-## Step 6 - Initialize Project Overview
+Explain that CI is not required to continue with planning or the Blueprint build
+loop. The `/ci` skill owns project-specific Verify and GitHub workflow setup.
 
-Populate `devflow/context/project-overview.md` with baseline information:
-- Project Name and One-line Summary
-- Tech Stack & Tooling Architecture
-- Initial Repository Structure
-- Available Verified Commands
+## Step 6 - check ignore files, visibility, and adapters
 
----
+Update `.gitignore` for common generated files from the detected stack while
+preserving existing entries. Typical examples include dependencies, build output,
+framework caches, logs, environment files, test output, temporary files, and OS or
+editor files.
+
+Ask how DevFlow workflow files should be handled in git, unless the user
+already gave a preference:
 
-## Step 7 - Handoff to Planning
+```text
+DevFlow visibility?
+
+1. Commit DevFlow workflow files
+   Portable. Best for teams and working across machines.
+
+2. Keep DevFlow workflow files local
+   Adds .agents/, .claude/, devflow/, and CLAUDE.md to .gitignore.
+   Keeps AGENTS.md public as the lightweight project agent guide.
+```
 
-Present a concise onboarding summary report:
+Recommend option 1 by default. If the user chooses option 2:
+
+- Add this block to `.gitignore`, preserving existing entries:
+
+  ```gitignore
+  # DevFlow local workflow files
+  .agents/
+  .claude/
+  devflow/
+  CLAUDE.md
+  ```
+
+- Keep `AGENTS.md` tracked. It remains the lightweight public project guide for
+  commands and conventions.
+- Make `AGENTS.md` public-safe: keep project description, commands, testing gate,
+  and coding conventions, but remove or avoid DevFlow workflow explanations,
+  hidden adapter paths, workflow-document pointers, and core skill lists that
+  would expose the local-only workflow.
+- Explain that local-only mode hides the workflow contents from the repo, but the
+  `.gitignore` names still reveal the ignored paths.
+- Explain that DevFlow state, specs, findings, and history will not travel
+  with the repo; another machine needs DevFlow reinstalled or restored
+  locally.
+- If any of `.agents/`, `.claude/`, `devflow/`, or
+  `CLAUDE.md` are already tracked, say `.gitignore` will not hide tracked files.
+  Ask before running
+  `git rm --cached -r .agents .claude devflow CLAUDE.md`, and
+  only run it if the user explicitly approves. Never delete the local files.
+
+Then report which adapter folders are needed:
+
+- Codex, Antigravity, and GitHub Copilot: keep `AGENTS.md`, `.agents/`, and `devflow/`; `CLAUDE.md` and
+  `.claude/` can be deleted.
+- Claude Code only: keep `AGENTS.md`, `CLAUDE.md`, `.claude/`, and `devflow/`;
+  `.agents/` can be deleted.
+- OpenCode: shares either `.agents/` or `.claude/` compatible skill tree without duplicate folders.
+- Mixed tools: keep both `.agents/` and `.claude/` adapters.
+
+Do not delete adapters unless the user explicitly asks.
+
+## Step 7 - hand off to planning
+
+Stop with a concise onboarding report:
+
+- stack and package manager detected
+- project name used for entry files
+- README handling, especially if the copied Blueprint README was moved
+- Blueprint visibility choice
+- tracked-file warning if local-only mode was chosen after files were already tracked
+- files changed
+- commands now available
+- testing gate status
+- verification command and GitHub checks status
+- adapter recommendation
+- TODOs or uncertainties
+- exact next files for the user to fill in:
+  - `devflow/project-plan.md`
+  - `devflow/build-plan.md`
+
+Make the direct path clear: the user can write or develop those files through
+any conversation, then run `/overview`. Also mention `/discovery` or `$discovery`
+as an optional deep planning conversation for users who want guided help. Do not
+start it, make it a prerequisite, or imply that directly written plans are less
+complete.
+
+End with the next command:
+
+```text
+/overview
+```
+
+For Codex, also mention:
+
+```text
+$overview
+```
 
-- Stack, framework, and package manager detected
-- Commands configured in `AGENTS.md`
-- Files tuned during onboarding
-- Adapter status (`.agents/`, `.claude/`)
-- Recommended next step:
-  - Run `00-explore` (or `00-explore`, `$00-explore`) to explore the first feature or product direction
-  - Run `10-define` (or `10-define`, `$10-define`) if the initial delivery slice is already clear and ready for execution
+## Rules
+
+- Setup files are fair game; planning docs are user-owned.
+- `/discovery` is optional and never runs as part of onboarding. The direct
+  plan-writing path must remain fully supported.
+- Never overwrite real `project-plan.md` or `build-plan.md` content.
+- Never run scaffolders or install dependencies unless the user explicitly asks.
+- Reflect the stack that exists, not the stack the default Blueprint mentions.
+- Be honest about tests. No `test` command means no required test gate yet.
+- Keep `AGENTS.md` public in local-only mode unless the user explicitly asks for
+  a more advanced setup.
+- Do not untrack Blueprint files with `git rm --cached` without a separate
+  explicit approval.
+- Keep changes small and explain what changed.
+
+## Formatting
+
+Format the output to match the project's conventions in
+`devflow/context/ai-interaction.md`: concise, scannable markdown, with lists for
+enumerations and tables for matrices rather than dense paragraphs.