{"id":"a5724b88-865f-4288-9ee6-3dadb9b2fa61","slug":"wang-dachui986-coding-rules","kind":"skill","name":"coding-rules","summary":"Reusable Codex project-governance skill with approval gates, task cards, and durable handoffs.","owner":"Wang-dachui986","repoUrl":"https://github.com/Wang-dachui986/coding-rules","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-31T00:38:56.000Z","addedAt":"2026-10-21T23:34:56.661Z","logoUrl":"https://avatars.githubusercontent.com/u/205314616?u=543f731c328b1e7cc47c612a4995bb07e325dab4&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity"],"tags":["ai-agent","coding-rules","project-management"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T23:35:19.080Z","sample":false,"url":"https://conduits.dev/tools/wang-dachui986-coding-rules","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# coding-rules\n\n[![CI](https://github.com/Wang-dachui986/coding-rules/actions/workflows/ci.yml/badge.svg)](https://github.com/Wang-dachui986/coding-rules/actions/workflows/ci.yml)\n[![MIT License](https://img.shields.io/github/license/Wang-dachui986/coding-rules)](LICENSE)\n\n[English](#english) · [中文](#中文)\n\n## English\n\n`coding-rules` is an MIT-licensed [Codex](https://developers.openai.com/codex/skills) skill for project governance. In Codex CLI or the IDE extension you invoke it with `$coding-rules`. It writes approval rules, role handoffs, and task-card templates into a coding project, then asks requirements questions until a plan is ready for review. The skill also ships a non-destructive scaffold command, a task-card status report, and checklists for receipt, module acceptance, and release.\n\nThe skill directory is [`coding-rules/`](coding-rules/). The repository root is the maintainer-facing project around that skill. There is no sample application, no credentials, and no recorded run of a product project in this repository.\n\n### What it is\n\nOn an explicit `$coding-rules` invocation, Codex is instructed to:\n\n1. Treat the current conversation as **R0**.\n2. Classify the tree as an existing project or an empty project. Version-control metadata, editor metadata, OS metadata, caches, and generated governance files are ignored for that decision. Secret-shaped files are not read.\n3. For an empty project, copy the templates in [`coding-rules/assets/project-governance/`](coding-rules/assets/project-governance/) and replace bracketed placeholders only with verified facts. Unknown decisions stay `[待项目所有者确认]`.\n4. For an existing project, merge governance into the files that are already there. The merge never deletes, moves, renames, or overwrites project files. The order is fixed: keep one copy of an identical rule; keep a stricter project rule; add a missing non-conflicting gate; keep the project's path or role name when the meaning matches and record the mapping; stop and ask the owner when objectives or permissions conflict.\n5. Create or reuse three long-lived local threads, `<project-name> · R1`, `<project-name> · R2`, and `<project-name> · R3`. Each starts `IDLE`. Existing role threads are reused. Short-lived subagents are not substitutes. If thread tools are missing or creation fails, each missing role is marked `NOT_CREATED` and Codex must give you three prompts to send yourself. It must not claim that initialization succeeded.\n6. Offer **LIGHT** or **FULL** requirements intake and ask one question per reply until the planning gate in [`coding-rules/references/intake-model.md`](coding-rules/references/intake-model.md) is met, then present a plan in status `WAITING_REVIEW`.\n\nThat invocation authorizes only the read-only classification, the non-destructive governance write, validation of those governance files, and creation of the missing R1–R3 threads. It does not approve product edits, tests, network access, Git, deployment, server access, purchases, messages outside those initialization threads, or destructive actions.\n\nFiles an empty project receives (twelve paths):\n\n```text\nAGENTS.md\ndocs/governance/OPERATING-RULES.md\ndocs/governance/WORKSTREAMS.md\ndocs/governance/CURRENT-TASKS.md\ndocs/governance/TASK-CARD-TEMPLATE.md\ndocs/governance/CHECKLISTS.md\ndocs/governance/HANDOFF-PROTOCOL.md\ndocs/handoffs/PROJECT.md\ndocs/handoffs/R0.md\ndocs/handoffs/R1.md\ndocs/handoffs/R2.md\ndocs/handoffs/R3.md\n```\n\nAfter initialization, the operating model in [`coding-rules/references/operating-model.md`](coding-rules/references/operating-model.md) is the source for roles, statuses, task cards, preflight, receipt, and module acceptance. In short:\n\n- **R0** is the only role that plans, writes task cards, distributes them, checks integration, and reports total progress.\n- **R1, R2, and R3** execute one owner-approved card each. They verify, update their own handoff, return facts to R0, and wait. Their normal finished state is `COMPLETED_MODULE_INPUT_READY`, which is not system acceptance.\n- The template's default duty split is a starting point, not a claim about your repository. `WORKSTREAMS.md` leaves file ownership as `[待确认]` until the project sets it. The defaults written in the template are: R1 for core business, backend, data, and automated tests; R2 for platform, integration, deployment, operations, and security boundaries; R3 for frontend, interaction, documentation surfaces, and browser QA.\n- Before distribution, R0 runs one read-only dispatch-conflict preflight. Distribution is allowed only when that preflight is recorded as `READY_FOR_OWNER_APPROVAL` and you approve that exact card version. Preflight is not approval.\n- Between subtasks, R0 does a light receipt check and drafts the next card as `WAITING_APPROVAL`. Drafting does not distribute or execute it. You can say that the current task is the last one; R0 then finishes receipt and the handoff without drafting another card.\n- One systematic acceptance runs only after that module's subtasks, shared integration, and required runtime surfaces are done.\n- Discussion needs no approval. Mutations and external operations have to be inside an approved task card.\n- When a project keeps a development-progress artifact, R0 is the only editor. The template does not invent a path for it; the placeholder is `[待项目所有者确认]`. The tracker is a report, not acceptance evidence.\n- When CodeGraph is already available, the skill tells Codex to use it before code search and impact analysis. If the project is not indexed, Codex must not initialize CodeGraph silently.\n- Passwords, tokens, private keys, cookies, full server addresses, private URLs, user data, and raw access logs do not go in governance documents.\n\nThese statuses are recorded in separate fields. Approval, verification, and preflight results are not written into the task status:\n\n| Field | Values |\n| --- | --- |\n| Requirements mode | `LIGHT`, `FULL` |\n| Plan | `DISCOVERY`, `WAITING_REVIEW`, `APPROVED`, `SUPERSEDED` |\n| Task | `PLANNED`, `WAITING_APPROVAL`, `APPROVED`, `IN_PROGRESS`, `COMPLETED_MODULE_INPUT_READY`, `COMPLETED_PENDING_REVIEW`, `COMPLETED_ACCEPTED`, `BLOCKED`, `FAILED`, `SUPERSEDED` |\n| Approval | `NOT_REQUIRED`, `WAITING_APPROVAL`, `APPROVED_NOT_EXECUTED`, `COMPLETED`, `BLOCKED` |\n| Verification | `PASS`, `FAILED`, `NOT_RUN`, `LIMITED` |\n| Conversation | `IDLE`, `IN_PROGRESS`, `NOT_CREATED`, `BLOCKED` |\n| Preflight | `READY_FOR_OWNER_APPROVAL`, `REVISE_REQUIRED` |\n| Receipt | `ACCEPTED_AS_MODULE_INPUT`, `REJECTED`, `BLOCKED_SAFE_STOP_ACCEPTED_NOT_MODULE_INPUT` |\n\nA verified answer, or `NOT_APPLICABLE` that you confirm, scores coverage. The weights sum to 100:\n\n| Dimension | Weight |\n| --- | ---: |\n| Goal and observable outcome | 15 |\n| Users and core scenarios | 10 |\n| Scope and explicit exclusions | 15 |\n| Existing project state and reusable assets | 10 |\n| Functional requirements and key flows | 15 |\n| Data, interfaces, and external dependencies | 10 |\n| Security, performance, reliability, and compliance | 10 |\n| Environment, deployment, and compatibility | 5 |\n| Verification, acceptance, and definition of done | 5 |\n| Risks, approvals, and operational boundaries | 5 |\n\nIntake stops only when coverage is at least 95%, the goal, scope, definition of done, security and approval boundary, and blocking dependencies are known, and no open question would change the architecture, data model, delivery scope, or risk level. `LIGHT` may cover an irrelevant dimension with a confirmed `NOT_APPLICABLE`. `FULL` has to collect enough fact in each dimension to plan modules. Neither mode lowers the approval or evidence rules.\n\n### Who it is for\n\nUse it if you want Codex, on a repository you are willing to add governance files to, to keep an approval boundary and a written handoff across conversations.\n\nIt fits a project that will split work across one controller conversation (R0) and up to three long-lived execution conversations (R1–R3). It also fits a single conversation that should still leave task cards and handoffs on disk.\n\nIt is not a hosted tracker, a sample codebase, or a plugin marketplace listing. Installing the skill does not connect your repository to this GitHub project.\n\n### Install\n\nThe directory Codex loads is the inner `coding-rules/` folder, the one that contains `SKILL.md`.\n\nCodex's current user-skill directory is `~/.agents/skills`. A single repository can load it from `.agents/skills/` instead. Those locations are documented at <https://developers.openai.com/codex/skills>. This repository's original install path, `~/.codex/skills`, is `$CODEX_HOME/skills`. The built-in `$skill-installer` skill still installs into that directory. Copy the skill to either place. Codex notices a new skill on its own; restart it if `$coding-rules` does not appear.\n\n```bash\ngit clone https://github.com/Wang-dachui986/coding-rules.git\ncd coding-rules\n\n# Current user-skill location\nmkdir -p ~/.agents/skills\ncp -R coding-rules ~/.agents/skills/coding-rules\n\n# $CODEX_HOME/skills. $skill-installer writes here.\nmkdir -p ~/.codex/skills\ncp -R coding-rules ~/.codex/skills/coding-rules\n```\n\nFor one repository, copy that same directory to `<that-repo>/.agents/skills/coding-rules`.\n\nTo install from GitHub with Codex, invoke `$skill-installer` and ask it to install repository `Wang-dachui986/coding-rules` at path `coding-rules` (ref `main`). That path is the skill directory, not the repository root.\n\nA published release zip has the same inner directory plus `LICENSE` at the archive root. The current release is [v0.2.0](https://github.com/Wang-dachui986/coding-rules/releases/tag/v0.2.0). [CHANGELOG.md](CHANGELOG.md) describes that release and the earlier `0.1.0` snapshot.\n\n### Usage\n\nOpen Codex in the project you want to govern and send:\n\n```text\n$coding-rules\n```\n\nIf you already know the intake mode, say so in the same request (`LIGHT` or `FULL`). The skill then skips the mode question and asks the first requirements question.\n\nYou stay in the R0 conversation for requests and approvals. R0 is instructed to plan, prepare task cards, obtain approval, and distribute approved cards. You do not have to manage R1–R3 yourself unless a thread could not be created.\n\nEvery later approved task, and every resume after context compression or a \"continue\" message, starts by re-reading `AGENTS.md`, `docs/handoffs/PROJECT.md`, the active role handoff, the approved task card, and the inputs that card cites. Chat memory is not a substitute.\n\n### Scaffold, status report, and checklists\n\nFrom the installed skill directory, or from `coding-rules/` in a git checkout:\n\n```bash\n# Copy governance templates. Missing files only; nothing is overwritten.\nuv run scripts/scaffold_governance.py /path/to/project\n\n# Show the same paths without writing.\nuv run scripts/scaffold_governance.py /path/to/project --dry-run\n\n# Status report from task cards. This is a view, not acceptance.\nuv run scripts/report_status.py /path/to/project\n```\n\n`scaffold_governance.py` finds its templates next to the script, so the current directory does not matter. `mode: empty` means the project has no meaningful files besides ignored metadata and the governance templates themselves. In both modes the command creates paths that are absent and prints `skipped-existing` for paths that are already there. It does not fill `[待项目所有者确认]` placeholders and it does not merge rules into an existing `AGENTS.md`. `$coding-rules` still does that semantic merge, creates or reuses the R1–R3 threads, and runs intake. The first invocation may use the scaffold command for the file copy it is already allowed to make.\n\n`report_status.py` reads `docs/governance/tasks/*.md`, any task-card path named in `docs/governance/CURRENT-TASKS.md`, and that file's task table. A path that points at a task card uses the card and does not count the table row again. Pass `--tasks-dir` and `--current-tasks` when the project kept other paths. A card is counted as accepted only when its task status is `COMPLETED_ACCEPTED` and its `证据状态` is `PASS`. `NOT_RUN`, a missing evidence status, and any other evidence status are listed under 不能视为已验收. Placeholder rows such as `[待确认]` are not counted as tasks. Running the report is a command; initialization does not approve it. R0 may use the output as the progress view after a command is allowed. R1–R3 do not use it to edit that view.\n\n`docs/governance/CHECKLISTS.md` has three sections: R0 light receipt, the one module acceptance, and release. R0 copies the matching section into the handoff or evidence and marks each item with the existing verification vocabulary. The checklist adds no statuses. A `NOT_RUN` item is not a pass, and finishing a list does not approve the next task or the release.\n\nWithout uv, call `python3 scripts/scaffold_governance.py` and `python3 scripts/report_status.py` with the same arguments.\n\n### Worked example\n\nThis is an illustration of the rules in `SKILL.md`. It is not a transcript from a Codex session, and this repository does not contain a `notes-api` project.\n\n1. The target is an empty directory, `notes-api`. No source files, docs, or tests are in it. You install the skill, restart Codex if needed, open Codex in `notes-api`, and send `$coding-rules`.\n2. Codex classifies the tree as empty. It copies the twelve governance paths listed above, and may do that copy with `scaffold_governance.py`. Fields it cannot verify stay `[待项目所有者确认]`. It does not invent a language, framework, or feature list.\n3. It lists existing project threads, then creates any missing long-lived thread titled `notes-api · R1`, `notes-api · R2`, and `notes-api · R3`. Each role prompt tells that thread to read the rules and wait `IDLE`. No product file is edited. No test, network call, or Git command is run.\n4. If those thread tools are unavailable, the handoff records `NOT_CREATED` and you receive three prompts. Initialization is not described as successful.\n5. Codex asks you to choose `LIGHT` or `FULL`. Suppose you answer `LIGHT`.\n6. It asks one question: what observable outcome `notes-api` must produce. You answer. It records every fact in the answer, then asks the single highest-impact question that is still open. Confirmed `NOT_APPLICABLE` answers can fill dimensions that do not apply. It does not draft a task card during this questioning.\n7. Suppose the answers cover at least 95% of the weighted table, and the goal, scope, definition of done, security and approval boundary, and blocking dependencies are known. Codex posts a `WAITING_REVIEW` plan: its understanding, the coverage figure, remaining non-blocking unknowns, proposed scope, milestones, acceptance, and risks. Nothing is executed.\n8. You approve that plan. Only then may R0 draft a task card from `docs/governance/TASK-CARD-TEMPLATE.md`. The card has one owner, an id, a version, allowed files and commands, forbidden actions, validation, stop conditions, and the handoffs to read and update. R0 runs the read-only preflight against the workspace, the last accepted baseline, handoffs, dependencies, file ownership, allowed paths, validation, and stop conditions.\n9. A conflict, missing permission, or impossible check produces `REVISE_REQUIRED`. R0 revises the card and returns it for approval. It does not distribute the old text.\n10. A recorded `READY_FOR_OWNER_APPROVAL` result plus your approval of that exact version lets R0 send the card, unchanged, to the named role. That role's completion report lists what it finished, files it changed, commands it actually ran, `NOT_RUN` items, and blockers. It does not report total project progress. The usual status it can reach is `COMPLETED_MODULE_INPUT_READY`.\n11. R0 checks card identity, scope, handoff, evidence, dependencies, and high-risk stop conditions, and fills section 1 of `docs/governance/CHECKLISTS.md` in the handoff or evidence. It updates the R0 and PROJECT handoffs when those checks pass, then drafts the next card as `WAITING_APPROVAL` and waits. Your approval of the first card does not approve the next one.\n12. After the module's subtasks and shared integration are done, R0 runs one systematic acceptance and fills section 2 of the checklist. Section 3 is for a later release or deployment, which still needs its own approval. You decide the following step. A task card counts as accepted in `report_status.py` only after its task status is `COMPLETED_ACCEPTED` and its `证据状态` is `PASS`. The blank template leaves `证据状态` as `NOT_RUN`.\n\nAn existing project differs at steps 2 and 6. Codex reads the non-secret tree and the development docs first, reports verified facts, gaps, non-destructive additions, and decisions it needs, and does not ask again for facts those files already state. Stricter rules already in the project stay. Product files stay where they are.\n\n### Validation\n\nFrom a git checkout or from the installed skill directory:\n\n```bash\ncd coding-rules\nuv run scripts/validate_skill.py\nuv run scripts/test_validate_skill.py\n```\n\nPython 3.11 or newer is required. Without [uv](https://docs.astral.sh/uv/):\n\n```bash\ncd coding-rules\npython3 scripts/validate_skill.py\npython3 -m pip install \"pytest>=8,<10\"\npython3 -m pytest -q scripts/test_validate_skill.py\n```\n\n`scripts/validate_skill.py` checks the skill directory:\n\n- required files exist, including `references/operating-model.md`, `references/intake-model.md`, `docs/governance/CHECKLISTS.md`, `scripts/scaffold_governance.py`, and `scripts/report_status.py`\n- `SKILL.md` starts with the `coding-rules` frontmatter, has a description, and names the scaffold command, the status report, and `CHECKLISTS.md`\n- relative links in `SKILL.md` resolve\n- the checklist keeps its three section headings, and the task-card template keeps its required sections plus `证据状态`\n- R1, R2, and R3 handoffs do not contain the R0-only headings `## 项目总进度` or `## 下一步顺序及审批状态`\n- `._*` and `.DS_Store` files are absent\n- Markdown and YAML files are valid UTF-8 and do not match the script's secret-shaped patterns\n\nIt does not launch Codex, and it does not test the project you apply the skill to. An optional argument is a skill root: `uv run scripts/validate_skill.py /path/to/skill`.\n\nCI runs those two commands on Python 3.11 and 3.12 for every push and pull request, then builds the skill zip with `python3 scripts/package_skill.py`. The workflow is [`.github/workflows/ci.yml`](.github/workflows/ci.yml). The badge above reads that workflow's status on the default branch. It stays neutral until the workflow file is on `main`.\n\nPushing a tag such as `v0.2.0` runs [`.github/workflows/release.yml`](.github/workflows/release.yml). The tag is what starts the workflow. The workflow validates the skill, zips it as `coding-rules-<version>.zip`, and creates the GitHub Release when one does not already exist for that tag. [v0.2.0](https://github.com/Wang-dachui986/coding-rules/releases/tag/v0.2.0) is the published release. The change list is [CHANGELOG.md](CHANGELOG.md).\n\n### Repository layout\n\n```text\n.\n├── README.md\n├── LICENSE\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── CODE_OF_CONDUCT.md\n├── SECURITY.md\n├── scripts/package_skill.py\n├── .github/workflows/ci.yml\n├── .github/workflows/release.yml\n└── coding-rules/\n    ├── SKILL.md\n    ├── agents/openai.yaml\n    ├── references/intake-model.md\n    ├── references/operating-model.md\n    ├── scripts/validate_skill.py\n    ├── scripts/test_validate_skill.py\n    ├── scripts/scaffold_governance.py\n    ├── scripts/report_status.py\n    └── assets/project-governance/\n```\n\n`agents/openai.yaml` is the skill's display metadata: the name shown in Codex, a short Chinese description, and the default prompt.\n\n### FAQ\n\n**Does `$coding-rules` modify my application?**\nNo. The invocation may add or merge governance files only. It does not edit product code.\n\n**Will it run tests, Git, or the network because I invoked it?**\nNo. Those actions need to be listed in a later task card that you approve. A returned \"done\" from R1–R3 is not acceptance and does not approve the next card.\n\n**What is the difference between an empty project and an existing one?**\nAn empty project gets the templates copied in. An existing project gets a non-destructive merge. The skill must not invent a stack for an empty project, and it must not re-ask a question the existing docs already answer.\n\n**What is the difference between LIGHT and FULL?**\n`LIGHT` asks less, for a small or well-bounded effort. `FULL` goes through users, flows, functions, data, interfaces, non-functional needs, environments, delivery, risks, and acceptance in more detail. The approval, evidence, and 95% gate still apply. You can switch mode later; answers already confirmed are kept.\n\n**Can a mature project skip intake?**\nThe skill does not define that waiver. After initialization it offers `LIGHT` and `FULL`. An existing project still gets a non-secret scan first, and questions those files already answer are not asked again.\n\n**What if Codex cannot create the R1–R3 threads?**\nThose roles are marked `NOT_CREATED`. You get three prompts to send yourself. The skill must not report that thread setup succeeded.\n\n**Who is allowed to state total progress and the next step?**\nOnly R0. R1–R3 report their own card, evidence, limits, and that the result went back to R0.\n\n**Can I copy the governance files without a Codex conversation?**\nYes. From the skill directory, `uv run scripts/scaffold_governance.py /path/to/project` creates every missing template and leaves existing files untouched. It does not fill placeholders, merge an existing `AGENTS.md`, create threads, or approve product work. `$coding-rules` still does the semantic merge, the R1–R3 threads, and intake.\n\n**When does the status report count a task as accepted?**\nOnly when the task status is `COMPLETED_ACCEPTED` and `证据状态` is `PASS`. `NOT_RUN` stays in the 不能视为已验收 section. The report is a view R0 can paste into the progress artifact after a command is approved. It is not acceptance evidence.\n\n**Why are the templates in Chinese?**\nThe skill text, role prompts, and templates in this repository are written in Chinese. The validator checks structure, not translation.\n\n**Does a green validator run mean Codex followed the skill?**\nNo. It means this skill directory passed the file checks listed above.\n\n**Where are the community docs?**\n[CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md). Bugs and feature ideas use the issue templates. Please do not put secrets in an issue.\n\n### Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Behavior changes belong in the skill and the templates, and the README should be updated only to match those files.\n\n### License\n\nMIT License. Copyright (c) 2026 Wang-dachui986. See [LICENSE](LICENSE).\n\n## 中文\n\n一个面向 Codex 编程项目的通用治理 Skill。它会为新项目或现有项目建立：\n\n- `AGENTS.md` 执行与审批规则；\n- R0–R3 角色分工和任务卡；\n- 多对话任务分发规范；\n- 上下文压缩、中断恢复和交接文档；\n- R1–R3 定向验证、R0 轻量接收和模块末单次系统验收；\n- 完成汇报、项目总进度、下一步顺序和逐项审批状态；\n- R0 唯一维护开发进度制品，并在每次任务闭环后同步功能、审批和更新日志；\n- 首次调用时检查已有项目或空项目，非破坏性部署规则并创建或复用 R1–R3\n  长期执行对话；\n- `LIGHT` 轻量问答与 `FULL` 全量问答两种需求收集模式；\n- 每次只询问一个最高优先级问题，需求覆盖率达到 95% 后才提交计划审阅；\n- 现有项目先扫描非秘密文件和开发文档，再给出已验证现状、缺口和非破坏性\n  调整建议；\n- 空项目直接进行需求发现，不臆造技术栈或业务需求；\n- 计划先进入 `WAITING_REVIEW`，获得批准后才允许执行；\n- 独立的需求、计划、任务、审批、验证、对话、预检和接收状态命名空间；\n- 确定性治理合并规则与可直接运行的 Skill 验证器；\n- 证据真实性、CodeGraph 和验收闭环规则；\n- 非破坏性脚手架：只补齐缺失的治理文件，不覆盖已有文件；\n- 从任务卡生成状态报告，证据状态不是 `PASS` 时不计入已验收；\n- 轻量接收、模块验收和发布三份检查清单。\n\n本仓库只包含通用项目开发治理规则和空白模板，不包含任何具体项目源码、凭据或运行证据。\n\n### 安装\n\n```bash\ngit clone https://github.com/Wang-dachui986/coding-rules.git\nmkdir -p ~/.codex/skills\ncp -R coding-rules/coding-rules ~/.codex/skills/coding-rules\n```\n\n若技能没有出现在列表里，重新打开 Codex。\n\n当前文档中的用户技能目录是 `~/.agents/skills`。上面的 `~/.codex/skills` 是本仓库原来的安装路径，也是 `$CODEX_HOME/skills`；内置的 `$skill-installer` 仍安装到那里。同一份内层 `coding-rules` 目录（含 `SKILL.md` 的那一层）放到任一位置即可。\n\n```bash\nmkdir -p ~/.agents/skills\ncp -R coding-rules/coding-rules ~/.agents/skills/coding-rules\n```\n\n只想在某一个仓库里使用时，把同一目录放到该仓库的 `.agents/skills/coding-rules`。\n\n### 调用\n\n在目标项目的 Codex 对话中输入：\n\n```text\n$coding-rules\n```\n\nSkill 会先判断项目是否已有有效文件。已有项目只安全合并规则，不删除、移动、\n重命名或覆盖项目文件；空项目直接生成治理和交接模板。首次调用还会复用已有\nR1–R3 对话并补建缺失角色，三个角色保持 `IDLE` 等待 R0 分发获批任务卡。\n它不会因调用而自动修改产品代码、运行测试、联网、执行 Git 操作、部署或\n访问服务器。\n\n初始化完成后可以选择：\n\n- `LIGHT`：适合小项目或边界清晰的需求，问题更少、更直接；\n- `FULL`：适合大型项目，详细覆盖用户、流程、功能、数据、接口、非功能需求、\n  环境、交付、风险和验收。\n\n无论选择哪种模式，Skill 每次只问一个问题。只有加权需求覆盖率至少达到\n95%、阻塞维度已经明确且不存在重大歧义时，才会生成状态为\n`WAITING_REVIEW` 的计划供用户审阅。计划获批后，R0 才会编制任务卡并把获批\n任务分发给 R1–R3；用户无需分别管理三个执行对话。\n\n初始化之后一定会提供 `LIGHT` 和 `FULL`。Skill 和模板里没有“成熟项目可在\n`AGENTS.md` 里免除这轮问答”的规则。已有项目会先读非秘密文档，文件里已经\n写明的问题不会再问。\n\n### 合并与验证\n\n现有项目采用确定性、非破坏性合并顺序：相同规则去重，项目中更严格的规则\n保留，缺失且不冲突的治理门槛补入；路径或角色名称不同但语义一致时保留项目\n现有命名；目标或权限发生冲突时停止写入并交由用户决定。\n\n安装后可以运行内置检查：\n\n```bash\ncd ~/.codex/skills/coding-rules\nuv run scripts/validate_skill.py\nuv run scripts/test_validate_skill.py\n```\n\n在本仓库中，把目录换成检出的 `coding-rules/` 即可。校验器只检查 Skill 目录，\n不会启动 Codex，也不会测试你之后套用规则的产品项目。校验还会确认检查清单的\n三个章节都在、任务卡模板含有 `证据状态`，并且 `SKILL.md` 提到下面两条命令。\n\n### 脚手架、状态报告与检查清单\n\n在已安装的 Skill 目录或本仓库的 `coding-rules/` 中运行：\n\n```bash\n# 只创建缺失的治理模板，不覆盖已有文件\nuv run scripts/scaffold_governance.py /path/to/project\n\n# 只打印将创建和将跳过的路径\nuv run scripts/scaffold_governance.py /path/to/project --dry-run\n\n# 从任务卡生成状态报告。这是报告视图，不是验收证据\nuv run scripts/report_status.py /path/to/project\n```\n\n没有 uv 时，把命令换成 `python3 scripts/scaffold_governance.py` 和\n`python3 scripts/report_status.py`，参数相同。\n\n`scaffold_governance.py` 按脚本所在位置寻找模板，不依赖当前目录。\n`mode: empty` 表示除被忽略的元数据和治理模板之外，没有有效项目文件。\n空项目和已有项目都只补缺失文件，已存在的路径打印 `skipped-existing`。\n脚本不填写 `[待项目所有者确认]`，也不把规则合并进已有的 `AGENTS.md`。\n语义合并、R1–R3 对话和需求问答仍由 `$coding-rules` 完成。首次调用可以用\n脚手架完成它本来就获准的那次非破坏性复制。\n\n`report_status.py` 读取 `docs/governance/tasks/*.md`、`CURRENT-TASKS.md`\n表格里写明的任务卡路径，以及这张表本身。路径指向任务卡时以任务卡为准，\n不把同一路径再计一次。项目如果保留了别的路径，用\n`--tasks-dir` 和 `--current-tasks` 传入。只有任务状态为 `COMPLETED_ACCEPTED`\n且 `证据状态` 为 `PASS` 的卡计入已验收。`NOT_RUN`、缺失或其它证据状态列入\n「不能视为已验收」。`[待确认]` 这类占位行不计入任务。空白任务卡的证据状态\n默认是 `NOT_RUN`。运行报告是一条命令，初始化并不批准它。R0 可以在命令获批后\n把标准输出当作进度视图；R1–R3 不用它修改进度制品。\n\n`docs/governance/CHECKLISTS.md` 有三节：R0 轻量接收、一次模块系统性验收、\n发布检查。R0 把对应章节抄入交接或证据，并用现有验证状态填写。清单不新增\n状态词。`NOT_RUN` 不是通过，填完清单也不批准下一张任务卡或本次发布。\n\n### 仓库结构\n\n```text\n.\n├── README.md\n├── LICENSE\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── CODE_OF_CONDUCT.md\n├── SECURITY.md\n├── scripts/package_skill.py\n└── coding-rules/\n    ├── SKILL.md\n    ├── agents/openai.yaml\n    ├── scripts/validate_skill.py\n    ├── scripts/test_validate_skill.py\n    ├── scripts/scaffold_governance.py\n    ├── scripts/report_status.py\n    ├── references/intake-model.md\n    ├── references/operating-model.md\n    └── assets/project-governance/\n```\n\n贡献、行为准则和安全报告见 [CONTRIBUTING.md](CONTRIBUTING.md)、[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) 和 [SECURITY.md](SECURITY.md)。版本说明见 [CHANGELOG.md](CHANGELOG.md)。\n\n### 许可证\n\nMIT License。见 [LICENSE](LICENSE)。\n"}