From 79c291f53913bf9a5b33953846589669304a11c9 Mon Sep 17 00:00:00 2001 From: v0 Date: Mon, 13 Jul 2026 04:07:05 +0000 Subject: [PATCH 1/2] docs: establish Convergent Coding as the project's formal positioning Tagline: spec is the output, not the input. README leads with the positioning, references/CONVERGENT_CODING.md defines the idea (the explore-ratify-converge loop, what it borrows from SDD/TDD/DDD/ cybernetics, five design commitments), and the install template anchors the principle for agents. Co-authored-by: v0 --- README.md | 28 +++++--- project-template/AGENTS.md | 7 ++ references/CONVERGENT_CODING.md | 119 ++++++++++++++++++++++++++++++++ 3 files changed, 144 insertions(+), 10 deletions(-) create mode 100644 references/CONVERGENT_CODING.md diff --git a/README.md b/README.md index aab7237..62f2a4b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# CodeRail +# CodeRail — Convergent Coding ![version](https://img.shields.io/badge/version-v0.7.3-2f80ed) ![license](https://img.shields.io/badge/license-MIT-27ae60) @@ -6,9 +6,13 @@ ![agent](https://img.shields.io/badge/agent--ready-Codex%20%7C%20Claude-8e44ad) ![scope](https://img.shields.io/badge/scope-repo--local-16a085) -**Your AI coding assistant stops drifting, stops declaring victory too early, and always leaves a project state the next session can pick up.** +**Spec is the output, not the input.** -**让 AI 编码助手不再跑偏、不再过早宣布完成、并且永远留下下一个会话能接得住的项目状态。** +**Spec 是产出，不是前提。** + +Vibe coding explores; CodeRail converges. As you build, discover, and change your mind, the tool quietly turns what you learned into guardrails — so exploration compounds instead of unravelling. Your AI assistant stops drifting, stops declaring victory too early, and always leaves a state the next session can pick up. + +Vibe coding 负责发散探索，CodeRail 负责收敛。你一边做、一边发现、一边改主意，工具在背后把你学到的东西悄悄追认为护栏——让探索层层累积，而不是层层瓦解。你的 AI 助手不再跑偏、不再过早宣布完成、并且永远留下下一个会话能接得住的项目状态。 No server. No accounts. No new methodology to learn. Just three commands and a `docs/` folder that stays honest. @@ -45,15 +49,19 @@ That is the whole interface. Your AI assistant reads the installed `AGENTS.md` a **`done`** — 安全网。它验证测试通过（或你明确记录了人工检查）、确认改动没超出承诺的文件、同步文档、只提交安全的任务相关文件，然后告诉你下一步。有问题它会拒绝并明确说出要修什么——AI 助手无法用话术绕过它。 -## Why / 为什么需要它 +## Why "Convergent Coding" / 为什么叫"收敛式编码" + +Vibe coding is fast and creative — until the project grows. Then docs rot, the assistant drifts from the goal, sessions forget each other, and "done" stops meaning done. The usual fix is spec-driven development: write the spec first, then build. But that assumes you already know what you want — and vibe coders discover what they want *by building*. Spec-first is not too hard for them; it points the wrong way. + +Vibe coding 又快又自由——直到项目变大。然后文档腐烂、助手偏离目标、会话之间互相失忆、"完成"不再意味着真的完成。常规解法是 spec 驱动开发：先写规格、再动手。但它假设你早就知道自己要什么——而 vibe coder 恰恰是**做出来才知道要什么**。spec 前置对他们不是太难，是方向反了。 -Vibe coding is fast and creative — until the project grows. Then docs rot, the assistant drifts from the goal, sessions forget each other, and "done" stops meaning done. Heavyweight spec-driven processes fix this but demand expertise most vibe coders do not have. +Convergent Coding inverts the arrow. You explore freely; each time something proves true — a task verified, a decision made, a boundary learned — the tool records it as a constraint the next round of exploration must respect. The spec accumulates behind you instead of blocking the road ahead. Exploration stays free; the project stops oscillating and starts converging. When repeated fixing fails to converge, the tool says so and points one level up: rethink the design, or rethink the goal. -Vibe coding 又快又自由——直到项目变大。然后文档腐烂、助手偏离目标、会话之间互相失忆、"完成"不再意味着真的完成。重型 spec 流程能解决这些，但它要求的工程素养恰恰是 vibe coder 不具备的。 +Convergent Coding 把箭头倒过来。你自由探索；每当一件事被证实——一个任务通过验证、一个决策被做出、一条边界被踩明白——工具就把它记录为下一轮探索必须尊重的约束。spec 在你身后累积，而不是挡在你前面。探索依旧自由，项目却不再震荡、开始收敛。当反复修补无法收敛时，工具会直说，并把你的注意力抬高一层：重新想设计，或者重新想目标。 -CodeRail takes a third path: the discipline runs automatically behind three plain commands. You never write a spec; the tool quietly maintains one for you (goal, task list, decision log, change history) and refuses to let anyone — human or AI — skip verification. +In short: discipline runs automatically behind three plain commands. You never write a spec; the tool quietly maintains one for you (goal, task list, decision log, change history) and refuses to let anyone — human or AI — skip verification. -CodeRail 走第三条路：纪律在三个命令背后自动运行。你从不写 spec，工具在背后悄悄替你维护（目标、任务清单、决策记录、变更历史），并且拒绝让任何人——无论人类还是 AI——跳过验证。 +一句话：纪律在三个命令背后自动运行。你从不写 spec，工具在背后悄悄替你维护（目标、任务清单、决策记录、变更历史），并且拒绝让任何人——无论人类还是 AI——跳过验证。 ## What lives in your repo / 装进仓库的是什么 @@ -89,9 +97,9 @@ The three commands are a facade over a deeper kernel: verification gates, TDD ev python .coderail/coderail.py --help # lists advanced commands ``` -Deep documentation lives in [`references/`](references/). Install details in [`INSTALL.md`](INSTALL.md). Skills for Claude Code / Codex live in [`skills/`](skills/). +The idea behind the tool — Convergent Coding — is written up in [`references/CONVERGENT_CODING.md`](references/CONVERGENT_CODING.md). Deep documentation lives in [`references/`](references/). Install details in [`INSTALL.md`](INSTALL.md). Skills for Claude Code / Codex live in [`skills/`](skills/). -深度文档见 [`references/`](references/)，安装细节见 [`INSTALL.md`](INSTALL.md)，Claude Code / Codex 的 skills 见 [`skills/`](skills/)。 +工具背后的思想——Convergent Coding（收敛式编码）——完整阐述见 [`references/CONVERGENT_CODING.md`](references/CONVERGENT_CODING.md)。深度文档见 [`references/`](references/)，安装细节见 [`INSTALL.md`](INSTALL.md)，Claude Code / Codex 的 skills 见 [`skills/`](skills/)。 ## License diff --git a/project-template/AGENTS.md b/project-template/AGENTS.md index e0edcf2..9f4e7d5 100644 --- a/project-template/AGENTS.md +++ b/project-template/AGENTS.md @@ -3,6 +3,13 @@ This project uses CodeRail to keep AI-assisted work on track. The rules below are written in plain language. You do not need to learn any special terminology. +One principle governs everything here: **spec is the output, not the input**. +The user explores and discovers what they want by building; your job is to help +them converge — each verified task, recorded decision, and learned boundary +becomes a constraint the next round of work must respect. Never demand an +upfront specification from the user, and never violate what has already been +ratified in `docs/`. + ## The three commands There is one entry point with three everyday commands: diff --git a/references/CONVERGENT_CODING.md b/references/CONVERGENT_CODING.md new file mode 100644 index 0000000..eb73206 --- /dev/null +++ b/references/CONVERGENT_CODING.md @@ -0,0 +1,119 @@ +# Convergent Coding / 收敛式编码 + +> Spec is the output, not the input. +> Spec 是产出，不是前提。 + +This document defines the idea behind CodeRail. It is a positioning statement, +not a methodology to study — the tool applies it automatically. + +本文定义 CodeRail 背后的思想。它是一份定位陈述，不是需要学习的方法论——工具会自动应用它。 + +## The problem / 问题 + +Two camps dominate how people build software with AI: + +- **Vibe coding**: describe, generate, look, react. Fast, creative, and honest + about how amateurs actually work — but it does not converge. Docs rot, + assistants drift, sessions forget each other, and late in the project the + owner loses the ability to judge what is going on. +- **Spec-driven development**: write the specification first, then build. + It converges — but it assumes you already know what you want. Amateur + builders discover what they want *by building*. For them spec-first is not + merely difficult; the arrow points the wrong way. + +当下用 AI 造软件的两大阵营： + +- **Vibe coding**：描述、生成、看、反应。快、有创造力、忠于业余开发者的真实 + 工作方式——但它不收敛。文档腐烂、助手漂移、会话失忆，项目后期连项目 + 拥有者自己都失去了判断力。 +- **Spec 驱动开发**：先写规格再动手。它收敛——但它假设你早就知道自己要 + 什么。业余开发者恰恰是**做出来才知道要什么**。对他们来说 spec 前置不是 + 太难，是方向反了。 + +## The idea / 思想 + +Convergent Coding keeps vibe coding's direction of discovery and adds the one +thing it lacks: a mechanism that makes exploration accumulate instead of +unravel. + +The loop has three beats: + +1. **Explore** — build freely, in whatever language you think in + ("make the button do X"). No upfront modelling required. +2. **Ratify** — each time something proves true — a task verified, a decision + made, a boundary learned the hard way — the tool records it as a + constraint. The spec grows *behind* you, assembled from verified facts, + never written in advance. +3. **Converge or escalate** — feedback is compared against what was ratified. + If the work drifts, the tool says so. If repeated fixing fails to converge, + that is itself a signal (Wiener's second-order feedback): the problem lives + one level up. The tool then points there explicitly — rethink the design, + or rethink the goal. + +Convergent Coding 保留 vibe coding 的发现方向，补上它唯一缺失的东西：一个让 +探索层层累积、而非层层瓦解的机制。 + +循环有三拍： + +1. **探索**——用你自己的语言自由地做（"让这个按钮做 X"），不要求任何前置建模。 +2. **追认**——每当一件事被证实——任务通过验证、决策被做出、边界被踩明白—— + 工具就把它记录为约束。spec 在你**身后**生长，由被验证过的事实拼装而成， + 从不预先书写。 +3. **收敛或升层**——反馈与已追认的约束对照。工作跑偏，工具直说。反复修补 + 仍不收敛，这本身就是信号（维纳的二阶反馈）：问题在上一层。工具会明确 + 指过去——重新想设计，或重新想目标。 + +## What it borrows, and what it changes / 借用与改造 + +Convergent Coding is not a rejection of existing ideas. It extracts the +smallest effective ingredient from each and re-mounts them on the +explore–ratify–converge loop: + +| Source | Ingredient kept | Change made | +|---|---|---| +| Spec-driven | Explicit goal, scope, done-criteria | Shrunk to three lines per task; produced during work, not before it | +| TDD | "State the expectation verifiably before claiming success" | Enforced only where correctness matters (bugs, parsers, domain logic, APIs); waived for exploration | +| Domain-driven design | A shared reference the whole project aligns to | Reduced to one plain-language North Star; alignment triggered by non-convergence, not by ceremony | +| Cybernetics (Wiener) | Feedback against a reference signal; escalate when feedback fails to converge | Implemented as deterministic counters, never LLM judgment | + +Convergent Coding 不是对既有思想的否定。它从每一种思想中萃取最小有效成分， +重新装配在"探索—追认—收敛"循环上： + +| 来源 | 保留的成分 | 所做的改造 | +|---|---|---| +| Spec 驱动 | 显式的目标、范围、完成标准 | 缩到每任务三行；在工作中产出，而非工作前 | +| TDD | "在宣称成功前，用可验证的语言说清期望" | 只在正确性敏感处强制（bug、解析器、领域逻辑、API）；探索性工作自动豁免 | +| 领域驱动设计 | 全项目对齐的共同参照 | 退化为一段人话 North Star；由"不收敛"触发对齐，而非仪式 | +| 控制论（维纳） | 对照参考信号的反馈；反馈不收敛时升层 | 以确定性计数实现，绝不依赖 LLM 判断 | + +## Design commitments / 设计承诺 + +Any tool claiming to implement Convergent Coding should honor these: + +1. **The user never writes a spec.** The tool assembles one from verified work. +2. **Ratified facts are cheap to create and hard to violate.** Three lines to + start a task; a gate that cannot be talked past to finish one. +3. **Escalation is counted, not felt.** "You are going in circles" comes from + arithmetic on the history, never from a model's mood. +4. **Every report is decodable by the owner.** Plain language, three questions: + what changed, how it was verified, what's next. An owner who can always + decode the feedback never loses judgment. +5. **Everything lives in the repo as plain text.** Delete the folder and the + tool is gone; the ratified history remains readable. + +任何声称实现 Convergent Coding 的工具都应遵守： + +1. **用户从不写 spec。**工具从被验证的工作中拼装出 spec。 +2. **追认的事实创建成本极低、违反成本极高。**开始任务只需三行；结束任务 + 要过一道无法用话术绕过的门。 +3. **升层靠计数，不靠感觉。**"你在原地打转"来自对历史的算术，绝不来自 + 模型的情绪。 +4. **每一份汇报都是项目拥有者可解码的。**人话、三个问题：改了什么、怎么 + 验证的、下一步是什么。永远能解码反馈的人，永远不会失去判断力。 +5. **一切以纯文本存在于仓库中。**删掉目录工具即卸载，被追认的历史依然可读。 + +## One sentence / 一句话 + +Vibe coding explores; Convergent Coding makes exploration converge. + +Vibe coding 负责发散，Convergent Coding 让发散收敛。 From c8fa88a2e9a84a8c31e9a7163ee386bbe4728827 Mon Sep 17 00:00:00 2001 From: v0 Date: Mon, 13 Jul 2026 04:51:39 +0000 Subject: [PATCH 2/2] feat: blueprint gap detection in check/done plus one-command scaffolding check and done now surface missing/stale diagrams (4 layers, 11 classes) detected from real code signals. New 'coderail blueprint --scaffold' creates Mermaid stubs under docs/blueprints/ and updates the index to planned. Template AGENTS.md instructs agents to ratify diagrams from built code and mark stale rows in the same commit. Co-authored-by: v0 --- project-template/AGENTS.md | 18 ++++- scripts/coderail.py | 152 ++++++++++++++++++++++++++++++++++++- skills/blueprint/SKILL.md | 13 +++- 3 files changed, 175 insertions(+), 8 deletions(-) diff --git a/project-template/AGENTS.md b/project-template/AGENTS.md index 9f4e7d5..bf1091c 100644 --- a/project-template/AGENTS.md +++ b/project-template/AGENTS.md @@ -99,6 +99,17 @@ The pattern behind this: when repeated fixing does not converge, the bug is almost never at the level where you are fixing. It lives one level up — in the design, or in the requirement itself. +## When the tool says "Blueprints" + +`check` and `done` watch the codebase shape; when it grows a new layer they +list the diagrams now needed (4 layers / 11 classes). When you see the notice, +run `python .coderail/coderail.py blueprint --scaffold` — it creates Mermaid +stubs under `docs/blueprints/`, marked `planned` in `docs/BLUEPRINTS.md`. +Replace placeholders with the REAL structure (small enough that a newcomer +understands without guesswork), then set the row to `current`. When a change +invalidates a diagram, mark it `stale` in the same commit. Diagrams are +ratified from what was built — never drawn ahead of the code. + ## Honesty rules (non-negotiable) - Do not claim tests passed if you did not run them. @@ -114,7 +125,6 @@ status with `python .coderail/coderail.py inspect`. ## Advanced -Power users and long-running autonomous sessions can use the advanced -commands (`doctor`, `drive`, `inspect`, `trace`, `blueprint`, `finish`, ...). -Run `python .coderail/coderail.py --help` to list them. They are optional; -the three everyday commands cover normal work. +Power users and long-running autonomous sessions can use advanced commands +(`doctor`, `drive`, `inspect`, `trace`, `finish`, ...); run +`python .coderail/coderail.py --help` to list them. They are optional. diff --git a/scripts/coderail.py b/scripts/coderail.py index b1131a0..81384bd 100644 --- a/scripts/coderail.py +++ b/scripts/coderail.py @@ -23,7 +23,6 @@ # Advanced/legacy commands, kept for compatibility and power users. ADVANCED = { - "blueprint": "blueprint_check.py", "ci": "ci_gate.py", "closeout": "closeout_check.py", "coordinate": "coordinate_check.py", @@ -214,6 +213,146 @@ def print_user_report_scaffold(task_id: str, title: str, verified: str) -> None: print(" something, make it a clear either/or question.") +# ------------------------------------------------- blueprint coverage +# +# 4 layers, 11 diagram classes (defined in blueprint_check.py). The engine +# detects which diagrams THIS project needs from actual code signals; here we +# surface the gaps in everyday commands and scaffold the missing ones so the +# project stays followable, maintainable, learnable, and deliverable. +# Convergent rule applies: diagrams are ratified output, never upfront input. + +MERMAID_STUBS = { + "UJM": ("User Journey Map", "journey\n title User journey\n section Arrive\n Open the app: 3: User\n section Core action\n Do the main thing: 4: User\n section Leave satisfied\n See the result: 5: User"), + "UF": ("User Flow", "flowchart TD\n Start([User arrives]) --> A{Main choice?}\n A -->|Path 1| B[Step]\n A -->|Path 2| C[Step]\n B --> Done([Goal reached])\n C --> Done"), + "PF": ("Page Flow", "flowchart LR\n Home[Home page] --> Detail[Detail page]\n Detail --> Action[Action page]\n Action --> Home"), + "SA": ("System Architecture", "flowchart TB\n User([User]) --> FE[Frontend]\n FE --> API[Backend / API]\n API --> DB[(Database)]"), + "CD": ("Component Diagram", "flowchart TB\n subgraph App\n A[Module A] --> B[Module B]\n B --> C[Shared utils]\n end"), + "SEQ": ("Sequence Diagram", "sequenceDiagram\n participant U as User\n participant F as Frontend\n participant B as Backend\n U->>F: action\n F->>B: request\n B-->>F: response\n F-->>U: result"), + "SM": ("State Machine", "stateDiagram-v2\n [*] --> Draft\n Draft --> Active: submit\n Active --> Done: complete\n Active --> Draft: reject\n Done --> [*]"), + "ERD": ("ER Diagram", "erDiagram\n USER ||--o{ ITEM : owns\n USER {\n string id PK\n string name\n }\n ITEM {\n string id PK\n string user_id FK\n }"), + "DFD": ("Data Flow Diagram", "flowchart LR\n In[/Input/] --> P1[Transform]\n P1 --> S[(Store)]\n S --> Out[/Output/]"), + "DD": ("Deployment Diagram", "flowchart TB\n subgraph Cloud\n Web[Web service] --> DB[(Managed database)]\n end\n Dev[Developer] -->|deploy| Cloud"), + "CICD": ("CI/CD Pipeline", "flowchart LR\n Commit --> Test --> Build --> Deploy"), +} + + +def load_blueprint_module(): + try: + sys.path.insert(0, str(SCRIPTS)) + import blueprint_check + return blueprint_check + except ImportError: + return None + finally: + if str(SCRIPTS) in sys.path: + sys.path.remove(str(SCRIPTS)) + + +def blueprint_gaps(root: Path) -> dict: + """Return {'required': [...ids missing/not-current...], 'stale': [...], 'recommended': [...]}.""" + bc = load_blueprint_module() + empty = {"required": [], "stale": [], "recommended": []} + if bc is None: + return empty + try: + result = bc.check_project(root) + except Exception: + return empty + path = root / "docs" / "BLUEPRINTS.md" + rows = bc.parse_blueprints(bc.read(path)) if path.exists() else {} + gaps = {"required": [], "stale": [], "recommended": []} + for did in result.get("required", []): + status = rows.get(did, {}).get("status", "") + if status == "stale": + gaps["stale"].append(did) + elif status != "current": + gaps["required"].append(did) + for did in result.get("recommended", []): + status = rows.get(did, {}).get("status", "") + if status not in {"current", "not-applicable"}: + gaps["recommended"].append(did) + return gaps + + +def print_blueprint_notice(root: Path) -> None: + gaps = blueprint_gaps(root) + if not (gaps["required"] or gaps["stale"]): + return + bc = load_blueprint_module() + names = (lambda ids: ", ".join(f"{i} ({bc.DIAGRAM_BY_ID[i].name})" for i in ids)) if bc else (lambda ids: ", ".join(ids)) + print("\n== Blueprints ==") + if gaps["required"]: + print(f" ! The code now needs diagrams it does not have: {names(gaps['required'])}") + if gaps["stale"]: + print(f" ! These diagrams no longer match the code: {names(gaps['stale'])}") + print(" A project without current diagrams cannot be handed over, maintained,") + print(" or learned from. Create/update them with: coderail blueprint --scaffold") + print() + + +def cmd_blueprint(args) -> int: + root = Path(args.target).resolve() + bc = load_blueprint_module() + if bc is None: + print("blueprint_check.py not found next to coderail.py") + return 1 + + result = bc.check_project(root) + if not args.scaffold: + print(bc.render_report(result)) + gaps = blueprint_gaps(root) + if gaps["required"] or gaps["stale"]: + print("\nFill the gaps automatically with: coderail blueprint --scaffold") + return 1 if result["status"] == "unhealthy" else 0 + + # --scaffold: create stub diagrams for every required/stale/recommended gap. + gaps = blueprint_gaps(root) + todo_ids = gaps["required"] + gaps["stale"] + (gaps["recommended"] if args.all else []) + if not todo_ids: + print("Blueprint coverage is already complete for the detected project shape.") + return 0 + + bp_dir = root / "docs" / "blueprints" + bp_dir.mkdir(parents=True, exist_ok=True) + index_path = root / "docs" / "BLUEPRINTS.md" + today = datetime.now(timezone.utc).strftime("%Y-%m-%d") + + created = [] + for did in todo_ids: + title, mermaid = MERMAID_STUBS[did] + stub_path = bp_dir / f"{did.lower()}.md" + if not stub_path.exists(): + stub_path.write_text( + f"# {title} ({did})\n\n" + f"Status: draft scaffold - replace the placeholder shapes with this\n" + f"project's real structure, then set the index row to `current`.\n\n" + f"What this diagram answers: see docs/BLUEPRINTS.md notes for {did}.\n\n" + f"```mermaid\n{mermaid}\n```\n", + encoding="utf-8", + ) + created.append(did) + # Update the index row: status -> planned, path -> stub, updated -> today. + if index_path.exists(): + text = index_path.read_text(encoding="utf-8") + row_re = re.compile( + rf"^(\|\s*{did}\s*\|[^|]*\|)\s*[^|]*(\|)\s*[^|]*(\|[^|]*\|)\s*[^|]*(\|[^|]*\|)\s*$", + re.M, + ) + replacement = rf"\g<1> planned \g<2> docs/blueprints/{did.lower()}.md \g<3> {today} \g<4>" + text, n = row_re.subn(replacement, text, count=1) + if n: + index_path.write_text(text, encoding="utf-8") + + print(f"Scaffolded {len(created)} diagram stub(s): {', '.join(created)}") + print(f" Stubs: docs/blueprints/ (Mermaid, edit in place)") + print(f" Index: docs/BLUEPRINTS.md (rows set to 'planned')") + print() + print("Now replace each placeholder with the project's real structure,") + print("then set its index row to 'current'. Keep every diagram small:") + print("the goal is that a newcomer understands the system without guesswork.") + return 0 + + # ------------------------------------------------- spinning-in-place detection # # Second-order feedback (Wiener): when first-order feedback (edit -> verify) @@ -474,6 +613,7 @@ def cmd_check(args) -> int: print(f"Queued: {len(queued)} task(s), next would be {queued[0]['id']} {queued[0]['title']}") print_spin_report(root, active, all_tasks) + print_blueprint_notice(root) coord_rc, coord_out = run_script("coordinate_check.py", root, capture=True) tdd_rc, tdd_out = run_script("tdd_check.py", root, capture=True) @@ -537,6 +677,7 @@ def cmd_done(args) -> int: append_progress(root, task_before, title or task_before, verified, next_hint) print("Progress journal updated: docs/PROGRESS.md") + print_blueprint_notice(root) print_next_recommendation(root) if task_before: print_user_report_scaffold(task_before, title or task_before, verified) @@ -610,6 +751,13 @@ def build_parser() -> argparse.ArgumentParser: p_next.add_argument("--go", action="store_true", help="Activate the recommended task") p_next.add_argument("--target", default=".") + p_bp = sub.add_parser("blueprint", help="Check diagram coverage; --scaffold fills the gaps") + p_bp.add_argument("--scaffold", action="store_true", + help="Create Mermaid stubs for missing required/stale diagrams") + p_bp.add_argument("--all", action="store_true", + help="With --scaffold: also stub recommended diagrams") + p_bp.add_argument("--target", default=".") + p_done = sub.add_parser("done", help="Finish the current task safely") p_done.add_argument("--task", help="Task id (defaults to the active task)") p_done.add_argument("--result", default="done", @@ -643,6 +791,8 @@ def main(argv=None) -> int: return cmd_check(args) if args.command == "next": return cmd_next(args) + if args.command == "blueprint": + return cmd_blueprint(args) if args.command == "done": return cmd_done(args) diff --git a/skills/blueprint/SKILL.md b/skills/blueprint/SKILL.md index fae9e68..e267b2d 100644 --- a/skills/blueprint/SKILL.md +++ b/skills/blueprint/SKILL.md @@ -5,17 +5,24 @@ description: Keep simple architecture/data/flow diagrams up to date when the pro # Blueprint Gate -Use this skill when architecture, lifecycle, data, deployment, UI flow, or cross-layer complexity appears. +Use this skill when architecture, lifecycle, data, deployment, UI flow, or cross-layer complexity appears — or when `check`/`done` prints a `== Blueprints ==` notice. ## Action -Run: +Check coverage (the tool detects which diagrams THIS codebase needs from real code signals): ```bash python .coderail/coderail.py blueprint ``` -Then update `docs/BLUEPRINTS.md` or the linked diagrams when the gate reports missing, stale, planned, or invalid coverage. +Fill the gaps automatically — creates Mermaid stubs under `docs/blueprints/` and marks index rows `planned`: + +```bash +python .coderail/coderail.py blueprint --scaffold # required + stale gaps +python .coderail/coderail.py blueprint --scaffold --all # also recommended +``` + +Then replace each stub's placeholder shapes with the project's real structure and set its row in `docs/BLUEPRINTS.md` to `current`. ## Diagram Classes