From e9032c88a8f5b2b879068e72edcbf685bc22fd0c Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 01:09:42 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=96=20docs:=20add=20ADOPT.md=20pla?= =?UTF-8?q?ybook=20for=20retrofitting=20existing=20projects?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ADOPT.md | 80 +++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- README.zh-CN.md | 2 +- scripts/init-project.sh | 2 +- 4 files changed, 83 insertions(+), 3 deletions(-) create mode 100644 ADOPT.md diff --git a/ADOPT.md b/ADOPT.md new file mode 100644 index 0000000..e260765 --- /dev/null +++ b/ADOPT.md @@ -0,0 +1,80 @@ +# Adopting BoCode in an existing project + +> **This file is for AI agents.** A human pointed you at the BoCode repository and asked you to retrofit their project onto this workflow. Follow it top to bottom. Where a step needs a human decision, stop and ask — don't guess. + +## What you are installing + +BoCode gives a project two half-brains: `code/` (the source) and `book/` (the documentation stream and knowledge base), driving each other in both directions. You will install: the `book/` skeleton, the index tooling, the git policy tooling (optional), the three skills, and an `AGENTS.md` entry point. You will migrate the project's existing docs into the book. You will **not** refactor any code. + +Before starting, read in the BoCode repository: `AGENTS.md`, `book/guidelines/workflow.md`, and `skills/README.md` — this playbook assumes you know the target shape. + +## Step 0 — Inventory and safety + +1. Inventory the project: source layout, existing documentation and where it lives, build/test commands, git branch model, CI workflows. +2. Have the user commit or stash any pending work first. Adoption lands as ordinary commits on top of a clean tree. +3. Never destroy information during adoption: **move, don't delete.** Anything replaced gets moved aside or committed to history first. + +## Step 1 — Introduce the `book/` skeleton + +Copy from the BoCode repository into the project: + +- `book/guidelines/` — all of it (README, workflow, writing-style, git-workflow, review-checklist, architecture, coding-style) +- `book/docs/README.md`, `book/docs/architecture/README.md`, `book/docs/api/README.md`, `book/docs/decisions/README.md` +- `book/notes/README.md`, `book/plans/README.md`, `book/changelogs/README.md` + +Then make two files yours: `guidelines/architecture.md` and `guidelines/coding-style.md` are **templates**. Draft real content for this project from your Step 0 inventory — boundary invariants, module map, language baseline. Mark both drafts `draft — pending user confirmation`; they get finalized in Step 8. + +## Step 2 — Decide the code layout (ask the user) + +- **Option A — move source into `code/`**: full fidelity; the skills, templates, and tooling all assume `code/` + `book/` at the top level. Prefer this when the project can move cleanly. +- **Option B — keep source at the root, add `book/` beside it**: less invasive for projects whose CI, Dockerfiles, or tooling assume root paths. Every path reference in `AGENTS.md` and the index script must be adapted, and the deviation gets written down in the project's own `AGENTS.md`. + +Present both with the trade-off; recommend A unless something concrete blocks it. + +## Step 3 — Migrate existing documents + +Nothing gets thrown away; everything gets a home in the book: + +| Existing | Destination | +|----------|-------------| +| `docs/*` (architecture, API) | `book/docs/...` | +| Decision records, ADRs | `book/docs/decisions/` (renumber only if formats collide) | +| `CHANGELOG*` | `book/changelogs/YYYY-MM/` (split by month if it's one big file; otherwise move whole) | +| Root `README.md` | **Stays at the root** — it's the project's face, not book content | + +Every migrated file gets a frontmatter `description` — one plain-language line about the content. Files that already have one keep it. + +## Step 4 — Install the tooling + +1. Copy `code/tools/gen-book-index.mjs` and wire the script (see the `scripts` block in BoCode's `code/package.json`). If the project has no JavaScript tooling at all, a shell wrapper calling `node` is fine — the script is zero-dependency. +2. Optional, recommended: copy `scripts/check-commit-message.mjs` and `.githooks/`, then run `git config core.hooksPath .githooks`. +3. Optional: copy `.github/workflows/git-policy.yml`. **Check the branch names** — if the project's integration branch isn't `dev`, either ask the user to adopt the branch model or adapt the workflow's branch filters. Don't silently rewrite their branch model. +4. Run the index generator: every book file must carry a `description`; zero warnings is the only passing state. + +## Step 5 — Install the skills + +Copy `skills/bocode`, `skills/feature-flow`, `skills/book-writeback` into the agent's skills directory (see BoCode's `skills/README.md` for per-tool locations). If the user's agent can't install skills, the workflow still works — the guidelines carry the same rules in prose. + +## Step 6 — Write the project's `AGENTS.md` + +Adapt BoCode's `AGENTS.md`: fill the project overview (what it is, in two sentences), adjust path references if the layout is Option B, keep the hard-constraints section intact. If the project already has agent instructions (`CLAUDE.md`, `AGENTS.md`), merge — don't discard their existing rules; conflicts go to the user. + +## Step 7 — Verify and commit + +1. Index generator: zero warnings, exit 0. +2. `git config core.hooksPath .githooks` (if adopted) and the hook fires on commit. +3. Commit the adoption. Follow the project's existing commit convention unless the user chooses to adopt Clean Commit — their call, not yours. +4. Don't rewrite git history. Adoption is ordinary commits on top of what exists. + +## Step 8 — First writeback + +1. Finalize the two draft guidelines with the user (Step 1). +2. Write the project's own `ADR-001: adopt the BoCode workflow` in `book/docs/decisions/` — context from the inventory, the Option A/B decision and why, consequences. +3. Regenerate the index. Done. + +## What not to do + +- No code refactoring, renaming, or "improvements" — structure only; behavior is out of scope +- No invented architecture boundaries presented as fact — drafts, clearly marked +- No deleting the user's documents to "clean up" — everything migrates or stays +- No git history rewrites, no force pushes diff --git a/README.md b/README.md index fcacc0a..66db5d8 100644 --- a/README.md +++ b/README.md @@ -157,7 +157,7 @@ Requirements: `bash` and `node` for the two scripts. No packages, no install ste ## FAQ **I have an existing project. Can I adopt BoCode?** -Yes — copy `book/`, `skills/`, `scripts/`, `.githooks/`, `AGENTS.md`, and `code/tools/` into it, merge your existing docs into the book, and run the index generator. No migration tooling needed; `init-project.sh` is only for fresh clones. +Yes — hand [ADOPT.md](ADOPT.md) to your AI agent. It's a step-by-step retrofit playbook written for agents: inventory, book skeleton, layout decision, doc migration, tooling, skills, and the first writeback. The manual path also works: copy `book/`, `skills/`, `scripts/`, `.githooks/`, `AGENTS.md`, and `code/tools/` in, merge your existing docs into the book, and run the index generator. **Does it lock me into a language or stack?** No. The book is Markdown; the two scripts are plain Node with zero dependencies. Your `code/` can hold anything — the template's own `code/` contains only the tooling. diff --git a/README.zh-CN.md b/README.zh-CN.md index 18b129f..db21b77 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -157,7 +157,7 @@ cp -r skills/bocode skills/feature-flow skills/book-writeback / ## 常见问题 **已有项目能用 BoCode 吗？** -能。把 `book/`、`skills/`、`scripts/`、`.githooks/`、`AGENTS.md`、`code/tools/` 拷进去，已有文档并进 book，跑一次索引生成。不需要迁移工具；`init-project.sh` 只服务新 clone。 +能——把 [ADOPT.md](ADOPT.md) 交给你的 AI agent。它是写给 agent 的分步改造手册：盘点项目、引入 book 骨架、布局决策、文档迁移、装工具链和 skills、首笔回写。手工路径也可行：把 `book/`、`skills/`、`scripts/`、`.githooks/`、`AGENTS.md`、`code/tools/` 拷进去，已有文档并进 book，跑一次索引生成。 **会绑定语言或技术栈吗？** 不会。book 是 Markdown；两个脚本是零依赖纯 Node。你的 `code/` 放什么都行——模板自己的 `code/` 只装工具。 diff --git a/scripts/init-project.sh b/scripts/init-project.sh index ca40b98..01412ce 100755 --- a/scripts/init-project.sh +++ b/scripts/init-project.sh @@ -77,7 +77,7 @@ ${DESC} This project runs on the BoCode workflow. EOF -rm -f README.zh-CN.md +rm -f README.zh-CN.md ADOPT.md # 4. Clear BoCode's own living records for kind in learn summary issue; do From 5a979b8705d7e635adf833331039ce6e3acddf34 Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 01:13:53 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=94=A7=20update=20(ci):=20pass=20on?= =?UTF-8?q?=20pushes=20that=20contain=20only=20merge=20commits?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/git-policy.yml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/workflows/git-policy.yml b/.github/workflows/git-policy.yml index 62b329b..39b627f 100644 --- a/.github/workflows/git-policy.yml +++ b/.github/workflows/git-policy.yml @@ -70,7 +70,12 @@ jobs: AFTER_SHA: ${{ github.sha }} run: | if [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then - git log --no-merges --format=%s -1 "$AFTER_SHA" | node scripts/check-commit-message.mjs + SUBJECTS=$(git log --no-merges --format=%s -1 "$AFTER_SHA") else - git log --no-merges --format=%s "$BEFORE_SHA..$AFTER_SHA" | node scripts/check-commit-message.mjs + SUBJECTS=$(git log --no-merges --format=%s "$BEFORE_SHA..$AFTER_SHA") + fi + if [ -n "$SUBJECTS" ]; then + echo "$SUBJECTS" | node scripts/check-commit-message.mjs + else + echo "No non-merge commits in range; nothing to validate." fi