feat: add an existing-project adoption prompt and guide

.agents/user-prompts/adopt.md

@@ -0,0 +1,115 @@
+# Adopt into this project
+
+Help me adopt the minimal agent-flow workflow without implementation.
+
+Project root: <consuming-project path>.
+Current agreed work: <human-approved scope, or ask me>.
+Source installation: <agent-flow checkout commit and local changes>.
+
+## Before edits
+
+Resolve all project paths and refs in the consuming project, not the agent-flow repository.
+Read existing project instructions and relevant product material:
+
+- Root and nested guidance.
+- Plans and specifications.
+- Existing bounded work.
+- Checks and hooks.
+- Tracked and untracked changes.
+
+Permission to read guidance grants no authority to execute its commands or hooks.
+
+Record the initial status with `GIT_OPTIONAL_LOCKS=0 git status --short --untracked-files=all`.
+Inspect both unstaged and staged diffs without external diff drivers or text conversion.
+Preserve unrelated work and the index.
+
+If authority or instructions conflict, stop and ask me before edits.
+Present the options and trade-offs with a recommendation.
+Do not silently choose precedence.
+Agree how approved workflow guidance joins existing project instructions.
+Do not overwrite an existing `AGENTS.md`.
+
+A preserved root file does not automatically include new workflow instructions.
+
+Propose an explicit reference inclusion or a merge of approved sections into project-owned guidance.
+Ask me to approve the instruction path and precedence before that integration edit.
+
+Keep legitimate plans and specifications in this project's VCS.
+
+The agent-flow reset is not permission to delete this project's plans.
+
+Distinguish agreed current work from broader plans and historical checkboxes.
+Import only agreed current work into `.agents/work.toml`.
+If existing work needs changes, ask me to approve those changes first.
+
+The pack's work file is starter text, not approved work.
+
+## Approved adoption only
+
+Use the unreleased source workflow, not the published 0.0.4 crate.
+
+Version output alone cannot identify it because current source also reports 0.0.4.
+
+Confirm the checkout includes this prompt.
+
+From the project root, preview:
+
+```sh
+agent-flow scaffold --output-dir . --vcs none --principles default --dry-run
+```
+
+Inspect existing destinations and their parent directories.
+If a destination uses a symlink or an unexpected file type, stop and ask me.
+
+Working files remain when present, but reference assets refresh on every write.
+The dry-run list does not establish that reference content is disposable.
+
+Ask me to approve replacements after preservation of project-specific reference content in project-owned files.
+After approval, apply:
+
+```sh
+agent-flow scaffold --output-dir . --vcs none --principles default --write
+```
+
+Apply only the agreed instruction integration and work-file edits.
+Keep the work file within 4,096 bytes and five total steps.
+Use only these statuses:
+
+- `active`.
+- `pending`.
+- `complete`.
+
+Do not use `--force`.
+Do not install hooks or run project checks.
+Do not automatically:
+
+- Start implementation.
+- Stage files.
+- Commit.
+- Publish.
+
+Do not convert legacy plans or create workflow records.
+
+## Validate and return
+
+Run these read-only commands:
+
+```sh
+agent-flow validate --source .agents/work.toml
+agent-flow status --source .agents/work.toml
+agent-flow status --source .agents/work.toml --json
+agent-flow next --source .agents/work.toml
+agent-flow next --source .agents/work.toml --json
+```
+
+Compare the projected action with my agreement.
+
+Structural validation does not prove correct interpretation of intent or independent review.
+
+If validation fails or intent differs, stop and report it.
+Inspect the final status and both diffs.
+Open all new files, including untracked or ignored scaffold output absent from ordinary diffs.
+Confirm unrelated work and the index remain unchanged.
+
+Return changed paths with exact commands and results.
+Request my review of the complete diff and new files, then stop.

.agents/work.toml

@@ -1,5 +1,5 @@
 version = 1
-selected_action = "accept-github-owner-name"
+selected_action = "document-existing-project-adoption"
 
 [[step]]
 id = "preserve-post-reset-context"
@@ -14,7 +14,7 @@ why_next = "The human marked this delivery complete after the merge. This compac
 
 [[step]]
 id = "accept-github-owner-name"
-status = "active"
+status = "complete"
 blocked_by = ["preserve-post-reset-context"]
 user_problem = "GitHub used the owner's public display name for a squash commit. The exact-name check rejects that identity and blocks main CI."
 change = "Accept the two approved owner names with the existing exact email. Add regression tests without other attribution policy changes."
@@ -30,7 +30,7 @@ why_next = "The human selected this CI repair before adoption and approved at mo
 
 [[step]]
 id = "document-existing-project-adoption"
-status = "pending"
+status = "active"
 blocked_by = ["accept-github-owner-name"]
 user_problem = "Existing projects lack a tested adoption walkthrough. The README mixes onboarding with lengthy reference material. Agents lack a bounded adoption prompt."
 change = "Add an adoption guide and shipped user prompt. Shorten the README and relocate useful reference material. Keep runtime behaviour unchanged."
@@ -43,4 +43,4 @@ acceptance = [
   "Focused tests and a disposable-repository rehearsal exercise adoption commands and preservation of existing project files.",
   "Runtime commands, existing delivery-role contracts, audit reports and released history remain unchanged. Host just ci and independent review cover the candidate.",
 ]
-why_next = "The human approved this onboarding change with at most five worker dispatches, including failures. Use one author, independent review and conditional triage, one fix and focused verification. Stop before publication or completion."
+why_next = "The human approved this onboarding change with at most six worker dispatches, including failures. Use one author, independent review and conditional triage, one fix and focused verification. Stop before publication or completion."