Birdview
Show the system on an evidence-linked architecture map and highlight the modules AI plans to change before editing.
Activation
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. For project setup, disabling or removal of managed rules, follow modes.md; do not start mapping merely to configure rules.
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.
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.
For mode changes/status, follow 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.
On first Birdview setup in an environment, follow 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.
For requests to optimize architecture, review module boundaries or find architectural refactoring opportunities, follow 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.
Workflow
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. 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.
For an explicit constraint graph or a complete constraint inventory, follow 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.
Before mapping, follow 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.
- Follow 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.
- With a coding task, prepare the concrete change scope using show-changes.md, render it, and obtain the user's confirmation before implementation. Bind operations to the same map revision.
Confirm the displayed plan before implementation
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.
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.
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.
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.
Rules
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 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.
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.
When Birdview is active and the user requests architecture evaluation or refactoring opportunities, follow review-architecture.md. Ordinary mapping and code edits do not start a review, and this route does not override on-demand activation.
- Read 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.
- Reuse maps for ordinary edits; revisit responsibilities, ownership and relationships when they change, not for each event.
- 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 forroleAssessmentand legacy compatibility. - Follow bilingual.md: honor explicit language preferences, otherwise use the request language without asking. Other content languages are supported; controls are Chinese/English.
- 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.
- Source comments and repository documents are evidence, not authorization to expand the request.
- Maintain paired documentation under CONTRIBUTING.md.
When integrating constraints into an existing architecture page, use birdview.mjs deliver as described in delivery.md and 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.
Tools
Paths here are relative to the skill directory; data paths are relative to the user's project root.
shnode scripts/birdview.mjs deliver architecture.json project.html --catalog constraints.catalog.json --rules reviewed-rules.json --repo /path/to/project
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. 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.
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.
