Repository navigation
docs: rewrite README as project intro with review/rebase/knowledge quick starts - #100
Conversation
Restructure the README from a Direct-skill catalog into a project introduction plus quick starts for the three core workflows: - Review: Direct (imreview) and Strict CLI side by side, with the snapshot-freeze flow and the post/ALLOW_POST double gate. - Rebase: previously absent from the README entirely — PR rebase via the CLI (conflict escalation, push double gate, with-lease only) and the locked repo-rebase nightly playbook. - Knowledge update: imupdate release audit, manual contributions via CONTRIBUTING plus the two validators, and the profile/skills candidate channels. The Direct-vs-Strict table, safety defaults, doc map, and the MCP tool reference (kept in compact form — doc/guide/mcp.md only covers installation) survive; imdesign/imcifix move to a short "other capabilities" list. The repo-neutrality claim is stated as enforced by the guardrail test with a shrink-only leak cap, not as an absolute. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EFomsSerZ41AX1kajBK13g
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7e1c8ea2be
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Strict 需要在 `.env` 里填一种模型 Key（`ANTHROPIC_API_KEY` 或 | ||
| `OPENAI_API_KEY`，各自支持可选 `*_BASE_URL`）和 `REPO_PATHS`。完整配置、 |
There was a problem hiding this comment.
Do not state that Strict always requires an Anthropic or OpenAI API key: when STRICT_BACKEND is cursor, claude-code, or codex, the shipped configuration deliberately uses the vendor CLI's subscription authentication, and doctor._check_env accepts an empty API key in that case (src/infermatrix_copilot/cli/doctor.py:29-36). As written, subscription-only users are incorrectly instructed to acquire and configure an unnecessary key, contradicting the Direct/Strict table above and the supported backend guide.
Useful? React with 👍 / 👎.
| ```bash | ||
| ./infermatrix-copilot -p "review pr 5172" | ||
| ./infermatrix-copilot -p "review pr 5172" --plan-only # 只看计划不执行 | ||
| ./infermatrix-copilot -p "review pr 5172" --performance # 用高能力模型档 |
There was a problem hiding this comment.
Document the prerequisite for this command, because the generated .env leaves PERFORMANCE_MODEL empty and Settings.tier_target rejects every --performance run in that state with TierNotConfiguredError (src/infermatrix_copilot/config.py:510-516). Although the CLI --help describes the flag as selecting the high-performance tier, the preceding minimal setup only asks for a shared key and REPO_PATHS, so a user following this quick start reaches an immediate failure unless the example says to configure PERFORMANCE_MODEL and any independent backend fields first.
Useful? React with 👍 / 👎.
| 退出码 3），绝不留下半成品树。push 同样双闸：PushPolicy 允许**且** | ||
| `ALLOW_PUSH=1`，否则是一次 dry-run，准确显示"本来会做什么"；force 只有 | ||
| `--force-with-lease`，且只针对 PR 的 head 分支。 |
There was a problem hiding this comment.
Do not say every unmet half of the push gate becomes a dry run: ci.push first calls guard_push, and a denied PushPolicy or protected target returns FORBIDDEN, blocks the run, and produces exit code 3; only an authorized policy combined with ALLOW_PUSH=0 returns a successful dry-run command (src/infermatrix_copilot/engine/steps/pr/publish.py:44-49). This matters for a PR whose head branch is protected, where the documented rebase command escalates instead of completing as the stated dry run.
Useful? React with 👍 / 👎.
Maintainer feedback on the previous commit: the introduction read worse than the original — it opened with abstract architecture language instead of what the tool does for the reader. Revision by Codex (gpt-5.6-sol), reviewed before commit: - Intro restored to the original's concrete form: what it does for your coding agent, then the four skills each tied to the problem it solves; the Direct-vs-Strict table follows immediately. - Quick starts tightened; arrow-chain process notation replaced with prose; install section split per platform. - MCP completion-gate description now carries the exact contract (none must carry no subtraction evidence, triggered needs a subtraction item or minimality proof, exactly one final comment). - Dirty-worktree row added to the safety defaults table. - The absolute repo-neutrality claim is dropped entirely; new-repo onboarding states adapters/ + knowledge/repos/ with no src/ changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EFomsSerZ41AX1kajBK13g
The intro framed the copilot as a vLLM-Omni-specific tool. Verified against code and docs, it is repo-invariant: playbooks match any repo by capability (repo-profile declares `repos: []`), per-repo knowledge lives in adapters/<repo>/ and knowledge/repos/<repo>/, and a second adapter (afd-plugin, active, human-reviewed) already exists alongside adapter zero. - Intro now says "目标仓库的项目知识" and adds a short paragraph: onboarding a new repo needs no core-code change; vLLM-Omni is adapter zero and the example repo throughout; afd-plugin is the second onboarded repo. - MCP section notes that the `repo` parameter defaults to adapter zero (matching the actual signature defaults in thin_mcp_server.py) and accepts any onboarded repo's short name, alias, or owner/name. - Remaining vllm-omni mentions are examples or real code defaults, left as is. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EFomsSerZ41AX1kajBK13g
The section still presented `repo-rebase` (the locked playbook that delegates to the external 5-phase orchestrator) as THE full-repo rebase, and named a `repo-rebase-native` candidate that does not exist under that name. Since the rebase-merge completion unit landed, the actual pipeline is `repo-rebase-v3` — rebase_engine end to end inside the playbook (wheel pin, per-module waves, local test loop, push gate, remote-CI monitoring), proven on the live vLLM v0.28.0 rebases. Now documented: the two invocations (report_only probe and the end-to-end full mode with last_rebase_commit), the four rebase_mode tiers, the push double gate, remote CI's schedule-build adoption plus the adapter-gated direct build creation on schedule-only pipelines (rebase.ci.ignore_branch_filters), and the real three-playbook status: repo-rebase-v3 / repo-rebase-native-v1 as planner-invisible candidates, repo-rebase still locked until the §8 gate promotes v3. Docs-only; no code touched. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CD4ifoCtkdQXxEyfCPyzLV
Tracks the 2026-08-25 cutover (main 012e900): repo-rebase-v3 is now locked and planner-recalled, the delegating v2 and native-v1 are deleted, so the "three playbooks coexist" paragraph is gone. The quick start now documents where every input comes from: the target repo (--repo / DEFAULT_REPO via the REPO_PATHS mapping and its adapters/<repo>/ requirement), the target branch (adapter manifest upstream.target_branch, resolved to the branch tip with the wheel probe), the upstream-checkout/venv path variables, the full --task-param table (rebase_mode tiers, last_rebase_commit, upstream_commit, force_upstream_commit, main_ci_idx, the halt/push strictness knobs) and the .env gates (ALLOW_PUSH double gate, GITHUB_TOKEN, BUILDKITE_API_TOKEN, REBASE_CI_TIMEOUT_SEC). Docs-only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CD4ifoCtkdQXxEyfCPyzLV
…example Owner feedback, three additions: 1. New "配置 .env" section between install and the quick starts: the three-layer minimal config (Direct needs only the repo mapping; Strict/CLI adds the model backend; rebase remote CI adds the tokens), a filled example block covering REPO_PATHS/DEFAULT_REPO/ REPO_FULL_NAMES, the vllm-omni path variables incl. VLLM_OMNI_VENV, the ALLOW_PUSH/ALLOW_POST gates, GITHUB_TOKEN/BUILDKITE_API_TOKEN/ REBASE_CI_TIMEOUT_SEC, and the doctor / doctor --probe verification step. Never-commit rule stated up front. 2. imcifix promoted from an "other capabilities" bullet to quick start 4 with Direct examples (issue URL / number / natural language) and the Strict debug/answer/triage commands moved in; imdesign keeps an invocation example in the remaining list. 3. The repo-rebase quick start now carries the real v0.28.0 campaign commands: full mode from baseline 1af5a386cd43 chasing releases/v0.28.0 (tag v0.28.0 = 2cf0a691, resolved by the pipeline from the manifest's target_branch), plus the remote_ci variant with the exact upstream_commit sha. Docs-only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CD4ifoCtkdQXxEyfCPyzLV
What
Rewrites
README.mdas a project introduction with quick starts for the three core workflows: review, rebase, and knowledge-base update.Why
The previous README was a Direct-skill catalog: it documented
imreview/imdesign/imcifix/imupdatewell, but had no project-level introduction (two products, safety model) and no rebase coverage at all, and the knowledge/CLI sides were only reachable through deeper docs.Structure of the new README
install-mcp.shfor Direct hosts,install.sh+doctorfor the CLI), linkingQUICKSTART.mdfor full CLI config.imreviewflow (snapshot freeze → knowledge routes → completion gate) and Strict CLI commands, with the post/ALLOW_POSTdouble gate.repo-rebase-v3(locked since the 2026-08-25 cutover, main 012e900; the delegating v2 and native-v1 are deleted), with a full input/parameter guide: target repo (--repo / REPO_PATHS), target branch (adapter manifest upstream.target_branch), the --task-param table (rebase_mode tiers, baselines, halt/push knobs) and the .env gates (ALLOW_PUSH double gate, tokens, CI budget).imupdaterelease audit flow, manual contributions viadoc/knowledge/CONTRIBUTING.md+ the two tree validators, and the profile/skills candidate channels.doc/guide/mcp.mdonly covers installation, so the signatures stay in the README), safety-defaults table, host ≠ backend note, doc map.imdesign/imcifixmove to a short "other capabilities" list.Content is sourced from
doc/GUIDE.md,QUICKSTART.md, and the previous README; all relative links verified against this branch. Docs-only change — no code touched.🤖 Generated with Claude Code
https://claude.ai/code/session_01EFomsSerZ41AX1kajBK13g