Skip to content
Back to search

birdview

Show evidence-linked architecture, constraints and change scope, or review architecture improvement opportunities. Use for Birdview/map requests or requests to optimize architecture, review module boundaries or 优化架构. Also activate before coding when the project explicitly configures Birdview auto mode. Ordinary coding does not activate Birdview without that opt-in.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Qiuner/birdview with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Qiuner/birdview'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/qiuner--birdview/badge.svg)](/listings/qiuner--birdview)

HTML

<a href="/listings/qiuner--birdview"><img src="/api/listings/qiuner--birdview/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install it with the third-party `skills` CLI:

npx skills add Qiuner/birdview --skill birdview

Start a new agent task and invoke the skill explicitly. **By default, Birdview runs only when requested; ordinary edits trigger it only after you enable project auto mode.**

**Codex:** type `/skills` and select Birdview, or enter:

$birdview Show this project's architecture and constraints; do not edit code.

**Claude Code:** enter:

/birdview Show this project's architecture and constraints; do not edit code.

For DeepSeek Harness and other hosts, use their skill selector or explicitly ask to use Birdview; slash-command support depends on the host.

When it works, the agent delivers a browser-readable page with the architecture, reviewed constraints, source evidence and review gaps. If constraints cannot be reviewed, it should explain the missing coverage instead of inventing rules. Map-only requests end after delivery; coding requests stop and wait for you to confirm the displayed plan.

See the [installation guide](docs/installation.md) for complete setup and verification steps, and the [0.4.0 release notes](docs/release-notes-0.4.0.md) for this release's features and limitations.

Example Pages

The repository has 2 example pages. Both are offline HTML; open them directly in a browser without running anything:

| Page | Views | Data | |---|---|---| | [`examples/harness-activity.html`](examples/harness-activity.html) | Architecture and Changes (with outside-scope impact) | Simulated project and agent activity | | [`examples/review.html`](examples/review.html) | Architecture review: red-pencil marks on the current drawing, the clean redraw and source clippings | An AI-generated review of Birdview itself: two candidates on page delivery and rule validation; quotes are checked line by line against the source |

The constraint view needs a curated constraint catalog first, so there is no ready-to-open example for it yet.

To regenerate the examples from source, use Node.js 18 or newer:

npm ci
npm run validate:examples
npm test
npm run build:demo

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 75 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: birdview
  3. description: Show evidence-linked architecture, constraints and change scope, or review architecture improvement opportunities. Use for Birdview/map requests or requests to optimize architecture, review module boundaries or 优化架构. Also activate before coding when the project explicitly configures Birdview auto mode. Ordinary coding does not activate Birdview without that opt-in.
  4. ---
  5. # Birdview
  6. [中文](SKILL.zh.md)
  7. Show the system on an evidence-linked architecture map and highlight the modules AI plans to change before editing.
  8. ## Activation
  9. Project `off` disables the foundation and map workflow unless explicitly requested for the current task. Installed project foundation rules remain applicable in `on-demand` even without skill activation; their canonical managed text is [foundation.txt](references/foundation.txt). For project setup, disabling or removal of managed rules, follow [modes.md](references/modes.md); do not start mapping merely to configure rules.
  10. Birdview defaults to `on-demand`: activate when the user selects the skill, names Birdview, requests an architecture/constraint/change map, or requests architecture improvement through the review route below. Ordinary coding, small fixes and feature planning do not activate it by default. If the project host instruction file explicitly configures `auto`, activate before every code-changing task, including small edits, and planning that explicitly analyzes affected modules. Honor existing `auto` settings; `setup` preserves them. Honor `off` unless explicitly invoked for this task. Merely discussing the skill does not request a map. When active for authorized coding, reuse/update the map and declare affected modules before editing.
  11. In Codex, use `/skills` to select Birdview or mention `$birdview`. For the separate environment audit, use `$birdview-compatibility`; it does not activate mapping. Claude Code exposes these installed skills as `/birdview` and `/birdview-compatibility`. Other hosts use their skill selector or an explicit request; do not assume they implement the same slash command. Invocation applies to the current task, not all future edits.
  12. For mode changes/status, follow [modes.md](references/modes.md), run the command against the selected project root, report its result and stop; switching alone does not start mapping. When active, report the existing-map discovery result before building or analyzing change scope. These are agent instructions, not enforced write interception.
  13. On first Birdview setup in an environment, follow [skill-compatibility.md](references/skill-compatibility.md) and run the read-only `skills audit` once. Use its manifest report to decide which skill bodies need inspection; do not treat duplicate names or broad triggers as proof of a semantic conflict. Do not modify or disable another skill without explicit user direction.
  14. For requests to optimize architecture, review module boundaries or find architectural refactoring opportunities, follow [review-architecture.md](references/review-architecture.md) directly instead of the default full-project mapping workflow below; naming Birdview is not required. The dedicated entry is `$birdview-review` in Codex or `/birdview-review` in Claude Code when installed. This is a separate on-demand review route and does not enable project auto mode. Ordinary local refactors and discussion about implementing the skill do not request a review. If both entries are selected, perform one review using this shared workflow.
  15. ## Workflow
  16. A bare “use Birdview” request delivers architecture and reviewed constraints together by default. Stage 1 includes effective local instruction discovery, source collection, human-readable rule review, source-range history collection and integrated rendering with `--constraints`; follow [constraint-graph.md](references/constraint-graph.md). Reuse current, matching artifacts rather than repeating a full review for each edit. Honor an explicit architecture-only or constraint-only request. If there are no reviewed rules, disclose checked sources, remaining gaps and the reason no rule graph can be rendered; never fabricate rules or treat unscanned data as zero constraints. Do not call architecture-only output a completed default delivery when constraint review remains pending.
  17. For an explicit constraint graph or a complete constraint inventory, follow [constraint-graph.md](references/constraint-graph.md). This standalone route does not require or modify an architecture map. Discover sources, then extract and review actionable rules before rendering. The default view groups rules by human-readable topics with numbered topics and architecture-consistent role colors; raw source text is available in By directory within the same page. A source dump is not delivery. Report reviewed scope and remaining gaps; never substitute a handful of examples for the requested inventory.
  18. Before mapping, follow [constraints.md](references/constraints.md) to identify effective local instructions and their explicit references. Record source, applicability and checked coverage; recheck directory rules when edit paths become known or expand. Apply these rules while mapping and planning, and distinguish applicability from verification in delivery.
  19. 1. Follow [map-project.md](references/map-project.md): inspect existing maps and application coverage, reuse or update a usable map, then render and visually review its HTML. Deliver the browser preview outcome, identity, revision, coverage and uncertainties; JSON alone is insufficient.
  20. 2. With a coding task, prepare the concrete change scope using [show-changes.md](references/show-changes.md), render it, and obtain the user's confirmation before implementation. Bind operations to the same map revision.
  21. ### Confirm the displayed plan before implementation
  22. In both auto and on-demand mode, finish the reviewable map and change plan first: show the HTML preview, affected modules/files, intended behavior, applicable constraints, verification plan and remaining uncertainties. Then ask whether to implement this displayed scope and wait for an explicit reply. Explain that Birdview requires confirmation of the displayed plan. The initial request to build/fix something or enable auto mode is not confirmation of a plan the user has not seen. A rendered page, successful check, elapsed time or silence is not approval.
  23. Before confirmation, read-only investigation and writing map/constraint/plan artifacts are allowed; do not edit implementation, tests or project configuration, or emit `editing` events. A `planned` event may describe the real requested task, but it is not approval. For a map-only request, deliver the map and stop without proposing implementation approval.
  24. Reuse explicit confirmation already given for the same displayed plan; do not ask again for routine edits or checks within its scope. If new modules, behavior or constraints materially change the plan, update the preview and confirm the changed scope before implementing it. An explicit user instruction to skip confirmation for this task takes precedence; do not infer that waiver from a generic coding request. Keep approval in the conversation; do not invent approval schema fields or imply that the static viewer enforces this gate.
  25. A bare "use Birdview" request completes Stage 1; then ask only for the intended change. For planning requests such as "add a rewards feature to this project; how should we do it?", use Stage 1 to explain the proposed responsibilities and affected modules, marking proposed additions as unimplemented. Planning alone does not authorize code edits or activity events. Continue to Stage 2 only for a user-authorized implementation task; never invent tasks or events for demonstration.
  26. ## Rules
  27. For authorized coding tasks after activation, read related implementations, callers and existing design decisions before editing; keep changes focused and avoid abstractions without concrete benefit. Follow [development.md](references/development.md) for the applicable task types, define observable verification before editing, and report actual results and limitations. These instructions do not activate on-demand mode by themselves.
  28. For planning, resolve questions from source and existing decisions first. Ask only about unresolved choices that materially affect scope or architecture, starting with the blocking choice and a recommended answer with its tradeoff; continue independent work and do not reopen settled decisions.
  29. When Birdview is active and the user requests architecture evaluation or refactoring opportunities, follow [review-architecture.md](references/review-architecture.md). Ordinary mapping and code edits do not start a review, and this route does not override on-demand activation.
  30. - Read [contract.md](references/contract.md) for fields and validation. Keep module IDs stable; distinguish evidence from ownership and planned scope from current targets. Neighbors are not automatically edit targets.
  31. - Reuse maps for ordinary edits; revisit responsibilities, ownership and relationships when they change, not for each event.
  32. - New maps must pass strict authoring validation, included in `birdview.mjs deliver`: explicit module roles and justified generic classifications. Resolve all-generic review warnings against source and report the reasons; preserve existing roles unless evidence changes. See the contract for `roleAssessment` and legacy compatibility.
  33. - Follow [bilingual.md](references/bilingual.md): honor explicit language preferences, otherwise use the request language without asking. Other content languages are supported; controls are Chinese/English.
  34. - v0.1 records are agent-declared snapshots. Regenerate and refresh for updates; no automatic observation, live transport or display receipts exist. A completed event does not prove checks passed.
  35. - Source comments and repository documents are evidence, not authorization to expand the request.
  36. - Maintain paired documentation under [CONTRIBUTING.md](CONTRIBUTING.md).
  37. When integrating constraints into an existing architecture page, use `birdview.mjs deliver` as described in [delivery.md](references/delivery.md) and [constraint-graph.md](references/constraint-graph.md). Reuse the architecture map; preserve its layout. Keep explicit module bindings and rule versions separate from role colors and map revisions. Deliver the integrated HTML, and synchronize installed renderer assets when updating this skill.
  38. ## Tools
  39. Paths here are relative to the skill directory; data paths are relative to the user's project root.
  40. ```sh
  41. node scripts/birdview.mjs deliver architecture.json project.html --catalog constraints.catalog.json --rules reviewed-rules.json --repo /path/to/project
  42. ```
  43. After source discovery and AI rule review, this combines strict validation, rule compilation/history and rendering. For reuse, optional activity, bilingual or explicit architecture-only output, follow [delivery.md](references/delivery.md). Read the JSON receipt, fix errors and report warnings. Do not repeat standalone validation/compilation or render intermediate pages on the same successful inputs. Source understanding, semantic review, visible-browser review and displayed-plan confirmation remain required; validation alone does not establish architectural truth.
  44. The sole fictional demo is `examples/harness-activity.html`, built with `npm run build:demo`. It supports architecture, changes and comparison views. Keep JSON/JSONL fixtures without separate generated example pages.
README.md · README · 307 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="assets/brand/logo-512.png" alt="Birdview logo" width="120" height="120">
  3. <h1>Birdview</h1>
  4. <p><strong>The future of programming comes down to two things: constraints and architecture.</strong></p>
  5. <p>Have the AI draw the system as it sees it, the rules it must follow and the scope it plans to change, then confirm before any code moves.<br>Shift your attention from code to architecture, and open the black box of AI coding.</p>
  6. <p>
  7. <img src="https://img.shields.io/badge/version-0.5.0-2f81f7?style=flat-square" alt="Version 0.5.0">
  8. <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&amp;logo=nodedotjs&amp;logoColor=white" alt="Node.js 18 or newer">
  9. <img src="https://img.shields.io/badge/license-MIT-2da44e?style=flat-square" alt="MIT License">
  10. <img src="https://img.shields.io/badge/output-standalone%20HTML-e34f26?style=flat-square&amp;logo=html5&amp;logoColor=white" alt="Standalone HTML output">
  11. <img src="https://img.shields.io/badge/docs-English%20%7C%20%E4%B8%AD%E6%96%87-8250df?style=flat-square" alt="English and Chinese documentation">
  12. <a href="https://linux.do"><img src="https://img.shields.io/badge/linux.do-%E7%A4%BE%E5%8C%BA-1f7aec?style=flat-square" alt="linux.do community"></a>
  13. </p>
  14. </div>
  15. <p align="center">
  16. <a href="#quick-start">Quick Start</a> ·
  17. <a href="#three-views">Three Views</a> ·
  18. <a href="#how-it-works">How It Works</a> ·
  19. <a href="examples/harness-activity.html">Live Demo</a> ·
  20. <a href="https://qiuner.github.io/birdview/">Project Site</a> ·
  21. <a href="https://atomgit.com/Qiuner/birdview">AtomGit Mirror</a> ·
  22. <a href="README.zh.md">简体中文</a>
  23. </p>
  24. <!-- [简体中文](README.zh.md) -->
  25. Birdview is a skill for AI coding agents. It draws a project's **architecture**, its **constraints** and the **scope of the current change** on one map: the agent shows its understanding and plan, waits for your confirmation, then implements and records the checks it actually ran. The output is a standalone HTML page that opens in a browser, with no service to deploy.
  26. <p align="center">
  27. <img src="docs/media/changes.gif" alt="Birdview changes view: stepping through the agent's plan on the architecture map, turning on outside-scope impact and opening module details" width="100%">
  28. </p>
  29. > The demo uses the fictional agent harness included in this repository. It does not represent observed production activity.
  30. ## New in v0.5.0
  31. - **Review verdict**: start with a health grade, one-sentence conclusion and reasons linked to the proposals. Review JSON now requires schema version `"3"` and a `verdict`.
  32. - **More readable reviews**: folded source evidence, hanging code indentation, clearer proposal cards and red-pencil notes that avoid diagram content.
  33. - **Constraint entries and language switching**: discover explicitly requested Markdown rule files with `--entry`, and switch generated rule-view labels between Chinese and English.
  34. See the [release notes](docs/release-notes-0.5.0.md) for installation and migration instructions.
  35. ## Why Birdview
  36. Ask an AI to "add rate limiting to the login endpoint":
  37. - **Normal flow:** the AI searches and edits immediately, and you are left to guess from the final diff whether anything was missed or changed by mistake.
  38. - **Birdview flow:** the AI first shows the login modules, the applicable interface and security rules, the files it plans to touch and the evidence behind each choice. It implements only after you confirm that scope, and records the checks it actually ran.
  39. Logs say which actions the AI took and diffs say which lines changed, but neither answers: where does this change sit in the system, what else can it reach, and why does the AI think these files belong to the task? Birdview lets you catch scope mistakes before the implementation is finished, instead of guessing afterwards.
  40. It does not observe every agent action automatically, and it does not replace Git diffs, tests or code review.
  41. ## Three Views
  42. Switch with **Architecture · Constraints · Review** at the top of the page.
  43. **Architecture**: the modules in the project, what each owns and how they connect, with source evidence for every claim. When activity is supplied, the same map becomes the **changes view**: it marks the modules and files the agent declared, its current step, and an outside-scope impact layer showing modules directly connected to the plan but not declared.
  44. **Constraints**: reviewed rules with their conditions, explanations, source text and versions. Browse by topic to understand them or by directory to trace files; Coverage states which sources were reviewed and what remains open. Collected documents are not automatically effective rules, and displaying a rule does not prove the implementation satisfies it.
  45. **Review**: the architecture review page. Ink draws the facts found in source, a red pencil circles the problems, and a clean redraw marked as a proposal shows the improvement. Evidence is quoted source text. Rendering with `--repo` checks it line by line against the recorded source revision or working tree; without a repository, quotations are marked unchecked.
  46. <p align="center">
  47. <img src="docs/media/review.zh.gif" alt="Birdview architecture review: red-pencil notes on the current drawing, the proposed redraw and source clippings checked line by line" width="100%">
  48. </p>
  49. > The review in this recording is the bundled example, written in Chinese; the interface also supports English.
  50. Every view supports light and dark themes and a Chinese or English interface, and inputs are checked for structure and consistency before rendering.
  51. ## Quick Start
  52. Install it with the third-party `skills` CLI:
  53. ```sh
  54. npx skills add Qiuner/birdview --skill birdview
  55. ```
  56. Start a new agent task and invoke the skill explicitly. **By default, Birdview runs only when requested; ordinary edits trigger it only after you enable project auto mode.**
  57. **Codex:** type `/skills` and select Birdview, or enter:
  58. ```text
  59. $birdview Show this project's architecture and constraints; do not edit code.
  60. ```
  61. **Claude Code:** enter:
  62. ```text
  63. /birdview Show this project's architecture and constraints; do not edit code.
  64. ```
  65. For DeepSeek Harness and other hosts, use their skill selector or explicitly ask to use Birdview; slash-command support depends on the host.
  66. When it works, the agent delivers a browser-readable page with the architecture, reviewed constraints, source evidence and review gaps. If constraints cannot be reviewed, it should explain the missing coverage instead of inventing rules. Map-only requests end after delivery; coding requests stop and wait for you to confirm the displayed plan.
  67. See the [installation guide](docs/installation.md) for complete setup and verification steps, and the [0.5.0 release notes](docs/release-notes-0.5.0.md) for this release's features and limitations.
  68. ### Example Pages
  69. The repository has 2 example pages. Both are offline HTML; open them directly in a browser without running anything:
  70. | Page | Views | Data |
  71. |---|---|---|
  72. | [`examples/harness-activity.html`](examples/harness-activity.html) | Architecture and Changes (with outside-scope impact) | Simulated project and agent activity |
  73. | [`examples/review.html`](examples/review.html) | Architecture review: red-pencil marks on the current drawing, the clean redraw and source clippings | An AI-generated review of Birdview itself: two candidates on page delivery and rule validation; quotes are checked line by line against the source |
  74. The constraint view needs a curated constraint catalog first, so there is no ready-to-open example for it yet.
  75. To regenerate the examples from source, use Node.js 18 or newer:
  76. ```sh
  77. npm ci
  78. npm run validate:examples
  79. npm test
  80. npm run build:demo
  81. ```
  82. ## Community and Feedback
  83. For installation help, inaccurate architecture maps, or discussion about Architecture-first Coding, join the Birdview user community.
  84. <p align="center">
  85. <img src="docs/community/qq-group.jpg" alt="QR code for the Birdview QQ user group, group number 627760389" width="360">
  86. </p>
  87. <p align="center"><strong>QQ group: 627760389</strong></p>
  88. You can also [share feedback on GitHub](https://github.com/Qiuner/birdview/issues/new?template=usage_feedback.yml). Successful runs, missing modules, incorrect relationships, and installation problems are all welcome. No private source code is needed; screenshots and sanitized examples are optional.
  89. ## Invocation
  90. In either mode, once activated Birdview displays the map and proposed changes, then waits for your confirmation before editing code. Confirmed work continues without repeated prompts within the same scope; material scope changes require a new confirmation. Map-only requests end after delivery. This is agent guidance, not a write lock enforced by the HTML page.
  91. Birdview runs **on demand by default**; ordinary coding, small fixes and feature planning do not trigger it:
  92. - **Codex:** type `/skills` and select Birdview, or mention `$birdview`.
  93. - **Claude Code:** invoke the installed skill with `/birdview`.
  94. - **DeepSeek Harness and other hosts:** use the host skill selector or explicitly ask to use Birdview.
  95. For example: "Use Birdview to show this project's architecture and constraints without changing code." The invocation applies to the current task, not future edits.
  96. **Auto mode** is optional: it activates before every code change, including small edits, and before planning that explicitly analyzes affected modules. New projects default to on-demand; existing `Birdview mode: auto` blocks in `AGENTS.md` or `CLAUDE.md` remain effective. Choose or query project mode:
  97. ```sh
  98. node <skill-root>/scripts/birdview.mjs mode auto --project <project-root>
  99. node <skill-root>/scripts/birdview.mjs mode on-demand --project <project-root>
  100. node <skill-root>/scripts/birdview.mjs mode --project <project-root>
  101. ```
  102. Setup defaults new projects to `on-demand` and preserves existing `auto`, `on-demand` or `off` settings. Codex and DeepSeek Harness use `AGENTS.md`; add `--agent claude-code` for `CLAUDE.md`. Other projects are not rewritten automatically. Start a new task after upgrading. See [mode details](references/modes.md).
  103. ### Architecture Review
  104. Ask "optimize this project's architecture" or "review the module boundaries" to start the architecture-review workflow. Birdview reads the source first, then presents the current drawing and a proposed redraw, source evidence, benefits, migration cost and verification steps. Review the displayed proposal before authorizing implementation. Ordinary bug fixes, local refactors and requests to draw the current architecture alone do not start a review.
  105. The dedicated entry lives in `review-skill/`. Install it as `birdview-review` alongside the complete `birdview` skill in the same skills directory; it depends on that bundle's references and renderer. Installing only the main skill does not install this entry. In Codex, select Birdview Review or enter:
  106. ```text
  107. $birdview-review Review this project's architecture and show improvement proposals; do not edit code yet.
  108. ```
  109. In Claude Code, use `/birdview-review` after installing the entry. The main Birdview skill also routes architecture-improvement requests to the same workflow. Natural-language selection depends on the host discovering the installed skill; start a new task after installation or updates to check activation. These are agent skill invocations, not `birdview` CLI subcommands. See the [review workflow](references/review-architecture.md) and the [review contract](references/review-contract.md).
  110. ### Skill Compatibility Audit
  111. Use `$birdview-compatibility` in Codex or `/birdview-compatibility` in Claude Code to check whether installed skills can be activated together. The audit first inventories the effective skill roots, then reads the relevant skill bodies to compare trigger scope, invocation mode, write permissions and confirmation gates. It reports duplicate installs, trigger overlaps and scenario-specific compatibility conclusions, with the evidence used for each conclusion.
  112. For a direct CLI run, write both machine-readable and human-readable results:
  113. ```sh
  114. node <skill-root>/scripts/birdview.mjs skills audit \
  115. --project <project-root> \
  116. --language en \
  117. --assessment <project-root>/.birdview/compatibility-assessment.json \
  118. --write <project-root>/.birdview/compatibility-audit.json \
  119. --write-markdown <project-root>/.birdview/compatibility-audit.md
  120. ```
  121. Pass `--language zh` for a Chinese report. The command is read-only with respect to installed skills: it does not disable, rewrite or reorder another skill, and it does not generate an architecture diagram. Review the Markdown report before changing skill configuration.
  122. ## Viewer Guide
  123. On an integrated page, switch between **Architecture**, **Constraints** and **Review** at the top (the latter two appear when their data was rendered). Select a module to inspect responsibilities, files and evidence; activity history records the agent-declared plan, progress and checks.
  124. In Constraints, browse **by topic** to understand rules, or **by directory** to trace their files. Double-click a node to read its explanation or source text, and use **Coverage** to inspect the reviewed scope and gaps. Role colors match the architecture palette; they do not represent compliance.
  125. In Review, hovering a node highlights the same node in both drawings; numbered tabs switch between candidates, and the recommendation banner jumps to the suggested one.
  126. On the first visit, follow **Guide** for a short walkthrough, or skip it and press Escape at any time. You can reopen it later from the toolbar.
  127. ## Generate the HTML Directly
  128. The agent normally handles these steps. If you already have an architecture file in the expected format, you can validate it and generate the HTML yourself:
  129. ```sh
  130. node scripts/validate.mjs .birdview/architecture.json
  131. node scripts/render.mjs .birdview/architecture.json .birdview/architecture.html
  132. ```
  133. To add the task activity declared by the agent:
  134. ```sh
  135. node scripts/validate.mjs .birdview/architecture.json .birdview/activity.jsonl
  136. node scripts/render.mjs .birdview/architecture.json .birdview/activity.html .birdview/activity.jsonl
  137. ```
  138. To include an already collected and reviewed constraint catalog:
  139. ```sh
  140. node scripts/birdview.mjs deliver .birdview/architecture.json .birdview/project.html --constraints .birdview/constraints.reviewed.json
  141. ```
  142. The CLI writes one integrated page with in-page source reading. For source discovery, rule review and standalone constraint rendering, see the [constraint workflow](references/constraint-graph.md).
  143. To render an architecture review and check every source quote line by line:
  144. ```sh
  145. node scripts/render-review.mjs .birdview/review.json .birdview/review.html --repo .
  146. ```
  147. Add `--bilingual` when both Chinese and English content must be validated. Use `--simulation` only to mark fictional demo activity.
  148. ## How It Works
  149. ```text
  150. project source ─────> architecture.json ──────┐
  151. local rules + review > constraints.reviewed.json ├─> validate / render ─> HTML
  152. agent declarations ─> activity.jsonl ─────────┘
  153. ```
  154. `architecture.json` describes project modules, responsibilities, file ownership, source evidence, and relationships. The optional `activity.jsonl` records the task scope, current target, progress, and verification results declared by the agent, one event per line. `constraints.reviewed.json` carries collected sources, reviewed rules and coverage. Rendering validates the supplied data before generating HTML.
  155. The workflow has four steps:
  156. 1. **Understand architecture and constraints:** read source and local instructions, reuse or update the map, and disclose review gaps.
  157. 2. **Show the plan:** identify affected modules and files, intended behavior, applicable rules and proposed checks.
  158. 3. **Confirm the scope:** wait for your explicit confirmation in the conversation before implementation. Reuse confirmation of the same plan; confirm material scope changes again.
  159. 4. **Implement and verify:** work within the confirmed scope, record actual checks and report remaining limitations.
  160. Confirmation does not mean tests passed. You can explicitly waive the confirmation step for a particular task; simply asking for a feature or enabling auto mode is not such a waiver.
  161. See [Stage 1: Map a project](references/map-project.md) and [Stage 2: Show changes](references/show-changes.md) for the complete workflow.
  162. ## Data Contracts
  163. | Artifact | Purpose |
  164. | --- | --- |
  165. | `architecture.json` | Project identity, modules, ownership, evidence, relationships, groups, and stable layout |
  166. | `constraints.reviewed.json` | Collected sources, reviewed rules, applicability, version information and review coverage |
  167. | `activity.jsonl` | Ordered, agent-declared task scope, targets, files, phases, and verification records |
  168. | `review.json` | Architecture review: current drawing and redraw, red-pencil findings, caller knowledge and quoted source evidence |
  169. | `architecture.html` | Generated viewer containing the map, optional constraint catalog and activity history |
  170. The schemas enforce structure. [`scripts/validate.mjs`](scripts/validate.mjs) also checks cross-record rules such as stable map identity, contiguous sequences, valid scope and targets, file ownership, and consistent check results. Validation does not prove that architecture claims are true or that referenced source files exist.
  171. ## Project Layout
  172. | Path | Contents |
  173. | --- | --- |
  174. | [`src/`](src) | TypeScript sources for contracts, CLI tools, browser viewer and website |
  175. | [`schemas/`](schemas) | Architecture, activity and review JSON Schemas |
  176. | [`scripts/`](scripts) | Validator, standalone renderer, and documentation checks |
  177. | [`assets/`](assets) | Viewer templates, styles and generated browser bundles |
  178. | [`examples/`](examples) | Example maps, activity records, review data and the generated interactive pages |
  179. | [`references/`](references) | Authoring workflow, contract, activity, and bilingual guidance |
  180. | [`test/`](test) | Contract, rendering, and optional browser-level checks |
  181. ## Current Boundaries
  182. Birdview 0.5.0 uses file snapshots:
  183. - Collected sources, rule applicability and verified compliance are distinct; incomplete review must be disclosed.
  184. - User confirmation is recorded in the conversation, not enforced by an HTML approval button or filesystem lock.
  185. - Activity is declared by an agent; Birdview does not automatically observe coding operations.
  186. - Updates require regenerating the HTML and refreshing the browser.
  187. - Live transport, automatic refresh, and rendered-display acknowledgements are not implemented.
  188. - A `completed` event does not prove checks passed; only recorded check results make that claim.
  189. - The package is currently marked private and is not published to npm.
  190. ## Development
  191. ```sh
  192. npm test # Contract and renderer tests
  193. npm run validate:examples
  194. npm run build:demo # Rebuild the example pages
  195. node scripts/check-docs.mjs
  196. ```
  197. Browser-level checks live in [`test/viewer.browser.mts`](test/viewer.browser.mts) and require a local Playwright installation or `BIRDVIEW_PLAYWRIGHT_PATH` pointing to one.
  198. For the field semantics and invariants, read the [Birdview contract](references/contract.md). Documentation changes must follow the bilingual rules in [CONTRIBUTING.md](CONTRIBUTING.md). For release preparation, see the [release checklist](docs/releasing.md).
  199. ## Star History
  200. <p align="center">
  201. <img src="docs/star-history.svg" alt="Birdview GitHub Star history" width="100%">
  202. </p>
  203. > Snapshot generated from the current GitHub stargazer list on October 8, 2026. GitHub may later remove anomalous stars; see [Issue #33](https://github.com/Qiuner/birdview/issues/33) for the public record.
  204. ## License
  205. Released under the [MIT License](LICENSE). Copyright (c) 2026 Qiuner.
  206. Third-party notices are preserved in [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.