Birdview skill

---
name: birdview
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.
---

# Birdview

[中文](SKILL.zh.md)

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](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.

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](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.

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.

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.

## 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](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.

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.

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.

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.
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.

### 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.