@tyroneross/build-loop 0.30.3

package/skills/api-registry-bridge/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: api-registry-bridge
+description: Use when Phase 1 Assess or Phase 5 Iterate detects a new API dependency, API config fails, or the user asks to "register this API" or "check the API registry". Consults api-registry plugin; degrades gracefully if plugin is absent.
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# api-registry-bridge (inside build-loop)
+
+## Activation
+
+- **Assess phase:** new API detected in dep diff (new package added to `package.json` / `requirements.txt`) or new vendor-prefixed env key in `.env.example`. Also runs unconditionally as a cheap doc-freshness check (see §"Phase 1 doc-freshness check").
+- **Iterate phase:** API config attempt fails with 401/403/404/timeout/auth error.
+
+## Contract
+
+1. Check `~/.api-registry/registry.db` exists.
+   - If **not**: log `api-registry not present — skipping source verification` and continue build-loop flow. No failure.
+
+2. Extract service name from failure message or dep diff.
+
+3. Invoke `/api-registry:lookup <name>`.
+   - If `found: true` and `deprecated_notes` present: HALT iteration; surface the warning to the user BEFORE retry.
+   - If `stale_warning: true`: suggest `/api-registry:refresh <name>` but don't block.
+   - If `cooldown.install_blocked: true`: see §"New-dependency cooldown".
+
+4. If config question remains, invoke `/api-registry:docs <name> <specific config question>`.
+   - api-registry answers from its local doc cache first; Context7 is the fallback path only.
+
+5. If lookup returns `found: false`: prompt user once per build-loop run to add the service. Don't re-prompt on every iteration.
+
+## Phase 1 doc-freshness check
+
+At the start of Phase 1 Assess, after the registry-present check:
+
+1. Read `~/.api-registry/staleness.json` (written by api-registry's SessionStart hook / `staleness.ts --marker`).
+   - Absent or unreadable → skip silently.
+2. If any `stale[]` entry names a service relevant to this build (its package appears in the dep manifest, or it is a `protocol`-category source and the build touches MCP), the doc is stale (`last_checked` > 7 days).
+3. **Refresh stale docs in-session before planning**: for each relevant stale doc, invoke `/api-registry:docs <service> <topic>` so the cache is re-verified/re-curated before the plan is drafted. This keeps Phase 2 planning grounded in current docs, not a stale cache.
+4. This is advisory — never blocks the build. Log what was refreshed; route the summary to the run report.
+
+## New-dependency cooldown
+
+When Assess detects a newly added third-party package:
+
+1. `/api-registry:lookup <name>` returns a `cooldown` block.
+2. If `cooldown.install_blocked: true` (latest version released < 7 days ago, service not `author_owned`):
+   - Surface the `cooldown.reason` to the user.
+   - The `pre_bash_dependency_cooldown.sh` PreToolUse hook is the enforcement point — it already rewrites/denies fresh installs at the Bash boundary. The registry verdict is the *advisory* signal that explains *why* a hook rewrite happened; it does not replace the hook.
+   - `author_owned: true` services (`@tyroneross/*` scope + the user's own projects) are exempt — `cooldown.install_blocked` is always `false` for them, matching the hook's allowlist.
+3. The 7-day registry cooldown window and the hook's 7-day install cooldown are deliberately the same number (supply-chain dwell time). If they ever diverge, the hook is authoritative for *enforcement*; the registry is authoritative for *explanation*.
+
+## What this does NOT do
+
+- Does not modify the registry (except via `/api-registry:docs`, which re-curates the cache by design — that is the cache staying fresh, not the bridge mutating registry metadata).
+- Does not block the build if api-registry is absent.
+- Does not fabricate URLs.
+- Does not duplicate the cooldown *enforcement* — that is `pre_bash_dependency_cooldown.sh`'s job.

package/skills/architecture/dead/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: build-loop:architecture-dead
+description: Use when the user asks to "find dead code", "scan for orphaned components", or "clean up unused files", or during Phase 4 Review before a release. Scans for unreachable components and dead code; build-loop's native scan from NavGator's CLI.
+version: 0.1.0
+user-invocable: false
+source: NavGator/commands/dead.md
+source_hash: e01c7f0e3c71a2a5c695c1d0ea9d3506672e6032cd58078f8f5b7b49b7b1a75d
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Dead-Code / Orphan Scan
+
+Detect orphaned components — those NavGator tracks but with zero incoming AND zero outgoing connections. Use the `mcp__plugin_navgator__dead` MCP tool (or `navgator dead` CLI).
+
+> **Divergence note**: NavGator has no discrete SKILL.md for dead-code analysis. The canonical wrapper is `commands/dead.md`. This skill encodes the same workflow.
+
+## When to Activate
+
+- Phase 4 Review-F Report: orphan scan after build completes — diff against the Phase 1 Assess baseline to surface NEW orphans introduced this build
+- User asks "find dead code", "any orphaned components", "what's unused"
+
+## Pre-flight
+
+1. If `.navgator/architecture/index.json` does not exist → no-op with `NavGator: no architecture snapshot found — skipping dead-code scan`.
+
+## Workflow
+
+1. Run `mcp__plugin_navgator__dead` (or `navgator dead`)
+2. Group findings by type: unused packages, unused DB models, unused queues, unused infra, unused services
+3. For significant findings (unused infra like Heroku/Render configs, unused queues), investigate whether they should be removed
+4. Suggest cleanup actions for clearly dead components
+
+## What Counts as Dead
+
+- Components detected by NavGator with zero incoming AND zero outgoing connections
+- Only meaningful types are checked (packages, queues, services, infra, database models)
+- Internal code files are NOT flagged (too many to be useful)
+
+## Diff Against Baseline
+
+If `.build-loop/state.json.architecture.dead.baseline` exists from Phase 1 Assess:
+- Compute `new_orphans = current - baseline`
+- Surface only the new ones in Review-F (existing orphans are pre-existing tech debt, not this build's regression)
+
+## Output
+
+Write to `.build-loop/state.json.architecture.dead` with `{total_orphans, new_orphans[], by_type{}}`.
+
+## Sibling Skills
+
+- `build-loop:architecture-scan` — refresh data first
+- `build-loop:architecture-rules` — broader violation check (orphan is one warning category there)
+- `build-loop:architecture-review` — full integrity review
+
+*Source: NavGator `commands/dead.md`. The canonical implementation is the CLI / MCP tool. Drift-checked by `build-loop:sync-skills`.*

package/skills/architecture/impact/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: build-loop:architecture-impact
+description: Use when Phase 1 Assess evaluates top-risk components, Phase 5 Iterate precedes a cross-layer fix, or the user asks "what does changing X break". Blast-radius analysis tracing upstream/downstream dependencies for a component or file before refactor.
+version: 0.1.0
+user-invocable: false
+source: NavGator/skills/impact-analysis/SKILL.md
+source_hash: e1eab41fae52db57fd80c996fec0d2480703e4ac407f5cf8e81edb882511a413
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Impact Analysis & Connections
+
+Analyze what's affected by a change and map component connections using the NavGator MCP tools (`mcp__plugin_navgator__impact`, `mcp__plugin_navgator__connections`, `mcp__plugin_navgator__trace`). Native to build-loop — content adapted from `NavGator/skills/impact-analysis/SKILL.md`. If NavGator is not installed, no-op with a one-line note.
+
+## When to Activate
+
+- Phase 1 Assess: after `build-loop:architecture-scan`, run impact on the top 5 highest-risk components and write a compact summary into `.build-loop/state.json.architecture.impact`
+- Phase 5 Iterate: BEFORE any escalation, run impact on the affected component to confirm whether the failing fix is cross-layer
+- User asks what's affected by changing a component or file
+- Before major changes to shared components
+
+## Pre-flight
+
+1. If `.navgator/architecture/index.json` does not exist → no-op with `NavGator: no architecture snapshot found — skipping impact analysis`. Recommend `build-loop:architecture-scan` first.
+
+## Impact Analysis
+
+Use `mcp__plugin_navgator__impact` with the component name to analyze blast radius.
+
+**Input:** Component name (e.g., "express", "prisma", "/api/users")
+
+**Returns:**
+- Component's name, type, and layer
+- **Incoming connections**: components/files that USE this component (may need changes)
+- **Outgoing connections**: components this one depends on
+- Severity assessment (critical/high/medium/low based on dependent count)
+- Specific file paths and line numbers for each connection
+
+### File-Based Impact
+
+If the user provides a file path instead of a component name:
+1. The tool resolves the file to its parent component automatically via file map lookup
+2. If no component found, suggest running `build-loop:architecture-scan` to refresh data
+
+## Connection Mapping
+
+Use `mcp__plugin_navgator__connections` to show all connections for a component.
+
+**Input:** Component name (required), direction (optional: "in", "out", or "both")
+
+**Returns:**
+- All incoming connections (what connects TO this component)
+- All outgoing connections (what this component connects TO)
+- File paths and line numbers for each connection
+
+## Dataflow Tracing
+
+For deeper data-flow analysis, defer to sibling skill `build-loop:architecture-trace` — same MCP tool family, focused on input→output pipelines.
+
+## Decision Tree
+
+| User Intent | MCP Tool | Notes |
+|-------------|----------|-------|
+| "What breaks if I change X?" | `mcp__plugin_navgator__impact` | Full blast radius |
+| "Show connections for X" | `mcp__plugin_navgator__connections` | All connections |
+| "What depends on X?" | `mcp__plugin_navgator__connections` (direction: "in") | Incoming only |
+| "What does X use?" | `mcp__plugin_navgator__connections` (direction: "out") | Outgoing only |
+| "Is it safe to modify X?" | `mcp__plugin_navgator__impact` | Check severity |
+
+## After Analysis
+
+Present results clearly:
+1. Severity level and summary
+2. Direct dependents (most important to review)
+3. Transitive dependents (may be affected)
+4. Recommendation: which files to review before making changes
+
+Write summary into `.build-loop/state.json.architecture.impact[<component>]` with fields `{severity, direct_count, transitive_count, layers_crossed}`.
+
+## Sibling Skills
+
+- `build-loop:architecture-scan` — refresh data first
+- `build-loop:architecture-trace` — pipeline trace
+- `build-loop:architecture-rules` — violation check after change
+- `build-loop:architecture-review` — full integrity review
+
+*Source: copied verbatim from NavGator and rewritten for build-loop. Drift-checked by `build-loop:sync-skills`.*

package/skills/architecture/review/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: build-loop:architecture-review
+description: Use when Phase 4 Review covers a build that crosses 2+ layers, or the user asks for an "architectural review" or "full integrity check". Covers system flow, component connections, documentation drift, and lessons; heavy-weight, native copy from NavGator.
+version: 0.1.0
+user-invocable: false
+source: NavGator/skills/code-review/SKILL.md
+source_hash: 61d49f3329da9dbf059fe54b24b3fe6537050c2d159fcac8d00fadb292dd5d4c
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Architectural Integrity Review
+
+Orchestrates impact analysis, data-flow tracing, the rules engine, and the lessons system into a 5-phase architectural review. Native to build-loop — content adapted from `NavGator/skills/code-review/SKILL.md`. This skill is an architectural integrity reviewer — not a linter, not a bug hunter.
+
+## What This Skill IS vs. IS NOT
+
+**IS:**
+- System flow — how data moves from user input through the system to output
+- Component communication — APIs, data formats, connection patterns between layers
+- API contract validation — interface changes and whether consumers are updated
+- LLM architecture — provider routing, prompt patterns, model selection logic
+- Documentation drift — whether docs reflect what the code actually does
+- Lessons learned — patterns that caused issues, tracked and matched over time
+- Freshness validation — periodic research to avoid stale architectural knowledge
+
+**IS NOT:**
+- Code linter or style checker
+- Individual function bug hunter — local logic errors, off-by-one mistakes
+- Security vulnerability scanner — use `security-reviewer` agent or dedicated tools
+- Test coverage auditor
+- TypeScript type error detector — the compiler handles that
+- Performance optimizer — out of scope
+
+## When to Activate
+
+- Build-orchestrator Phase 4 Review when the build touches 2+ layers (cross-layer change)
+- User asks "review architecture", "is this safe to merge", "what did I break"
+- After a large refactor
+
+## Scope Resolution
+
+| Invocation | Scope |
+|------------|-------|
+| Default (no flags) | `git diff origin/main..HEAD` — changed files since branch diverged |
+| `--all` | Full architecture review across all components |
+| `<component>` | Focused review on one component and its direct connections |
+| `--validate` | Run Phase 5 freshness validation regardless of age |
+| `learn "..."` | Record a manual lesson, skip full review |
+
+When scope is ambiguous, default to `git diff origin/main..HEAD`. If the branch has no divergence from main, ask the user what to review.
+
+## Prerequisites
+
+1. `.navgator/architecture/index.json` must exist. If not, run `build-loop:architecture-scan` first.
+2. If `generated_at` is >24 hours old, warn before proceeding.
+3. Load `.navgator/architecture/file_map.json` for file-to-component resolution.
+4. Load `.navgator/architecture/graph.json` for connection traversal.
+5. If `.navgator/lessons/lessons.json` is missing, create:
+   ```json
+   { "schema_version": "1.0.0", "lessons": [] }
+   ```
+
+Do not proceed without architecture data. Stale data is worse than pausing.
+
+---
+
+## Phase 1 — Structural Changes
+
+**Goal:** Identify which components and layers were touched.
+
+1. Run `git diff [scope] --stat` to get changed files
+2. For each changed file, look it up in `file_map.json` → parent component ID
+3. Look up component ID in `index.json` → type and layer
+4. Classify each change: new component / modified connection / config change / documentation
+5. Identify which layers were touched: frontend, backend, database, infra, external
+6. Flag any cross-layer change as **higher risk**
+7. Note any new files that don't resolve to any tracked component
+
+```
+PHASE 1: STRUCTURAL CHANGES
+  N components touched across N layers
+  Cross-layer: [ComponentA (frontend→backend), ComponentB (backend→database)]
+  New components: [unconnected — needs scan to track]
+  Layers: frontend(N) | backend(N) | database(N) | infra(N)
+```
+
+---
+
+## Phase 2 — Connection & Flow Integrity
+
+**Goal:** Verify connections valid, data flows intact.
+
+For each component from Phase 1:
+
+1. Call `build-loop:architecture-impact` (uses `mcp__plugin_navgator__impact`)
+2. Call `build-loop:architecture-trace` direction=both
+3. Call `mcp__plugin_navgator__connections` direction=both
+
+| Issue | Severity | Detection |
+|-------|----------|-----------|
+| Orphaned component | Important | New component with 0 incoming AND 0 outgoing connections |
+| Broken reference | Critical | Connection points to a component not in `graph.json` |
+| Layer violation | Critical | Frontend connects directly to database, bypassing backend |
+| High fan-out | Important | Component has >8 outgoing dependencies |
+| Import cycle | Critical | Component A → B → A |
+| API contract mismatch | Critical | Interface changed, consumers not updated |
+| Self-referencing connection | Important | Component listed as its own dependency |
+
+```
+PHASE 2: CONNECTION INTEGRITY
+  Rules: N violations (N critical, N important, N minor)
+  [CRITICAL] Layer violation: ComponentA (frontend) → ComponentB (database)
+    File: src/pages/users.tsx:45
+    Why: Frontend bypasses API layer, creating tight coupling.
+```
+
+If no violations: report "No connection integrity issues found" — do not omit.
+
+---
+
+## Phase 2.5 — LLM Purpose Classification
+
+**Goal:** Classify what each LLM call does, not just who it calls.
+
+1. Run `mcp__plugin_navgator__llm_map` with `--classify`
+2. For each uncategorized use case: read the primary file, determine purpose (summarization, extraction, search/ranking, generation, embedding, classification, translation, agent/tool-use, validation, analysis, synthesis)
+3. Note system effect (search results, UI charts, DB writes, queue processing, API responses)
+4. Record classifications as lessons in `.navgator/lessons/lessons.json` with category `'llm-architecture'`
+
+---
+
+## Phase 3 — Documentation Drift
+
+**Goal:** Verify docs reflect what code does.
+
+1. Read README.md — for each CLI command/flag in implementation, verify it appears in CLI Reference. Run `--help` and compare.
+2. Read CLAUDE.md — verify command table is complete (every `/build-loop:*` slash command listed)
+3. List all directories under `skills/` — for each capability, verify a skill file exists
+4. Read `plugin.json` — verify all referenced directories and entry points exist on disk
+5. For each new/modified capability from Phase 1, check that it appears in README, CLAUDE.md, AND a skill file
+
+An **agent-invisible feature** is one in code but absent from agent-readable files (CLAUDE.md or skill files). Highest-priority gap — silently degrades agent capability.
+
+```
+PHASE 3: DOCUMENTATION DRIFT
+  [AGENT-INVISIBLE] --validate added but not in CLAUDE.md command table
+  [STALE] README references `navgator check` (renamed to `/navgator:check`)
+  [UNDOCUMENTED] navgator coverage --typespec — no skill file
+```
+
+If no drift: report "Documentation matches implementation".
+
+---
+
+## Phase 4 — Lessons Check
+
+**Goal:** Match findings against known patterns; record new ones.
+
+### Matching Known Lessons
+
+1. Read `.navgator/lessons/lessons.json`
+2. For each lesson, check whether any changed file/component/finding matches `signature` patterns
+3. If a match: flag with recurrence context. Do not silently skip.
+
+### Recording New Lessons
+
+For each NEW finding (not already in `lessons.json`), append:
+
+```json
+{
+  "id": "<sha256(category+pattern) truncated to 8 chars>",
+  "category": "layer-violation|orphaned-component|api-contract|doc-drift|import-cycle|triplicated-logic|other",
+  "pattern": "human-readable description",
+  "signature": ["regex or code fragment to match recurrence"],
+  "severity": "critical|important|minor",
+  "context": {
+    "first_seen": "ISO 8601",
+    "last_seen": "ISO 8601",
+    "occurrences": 1,
+    "files_affected": ["paths"],
+    "resolution": "specific fix"
+  },
+  "example": { "bad": "...", "good": "...", "why": "..." },
+  "validation": { "last_validated": "ISO 8601", "source": "agent", "status": "unvalidated" }
+}
+```
+
+If a lesson already exists for the pattern (matched by `id` or `signature`), update `last_seen`, increment `occurrences`, merge `files_affected`. Don't duplicate.
+
+---
+
+## Phase 5 — Freshness Validation
+
+**Goal:** Lessons referencing external APIs or libraries still reflect current best practice.
+
+Trigger only when:
+- User passed `--validate`
+- Lesson references an external API/library/version-specific behavior
+- More than 30 days since `validation.last_validated` on any matched lesson
+
+For each lesson needing validation:
+1. WebSearch the referenced API/library/pattern
+2. Verify still recommended approach
+3. Update `validation.last_validated`, `validation.status` (`current`/`stale`), `validation.source` (`web-search`)
+4. If stale, add `validation.note` explaining what changed
+
+---
+
+## What to Ignore
+
+- Individual function logic — use a debugger
+- Code style/formatting — use a linter
+- Test coverage — use coverage tools
+- Performance — use profiling
+- Security vulnerabilities — use `security-reviewer`
+- TypeScript type errors — compiler handles those
+- Spelling/grammar in comments
+
+If a finding falls into one of these, note briefly and redirect: "This is a linter issue — outside architectural review scope." Then move on.
+
+## Sibling Skills
+
+- `build-loop:architecture-scan` — refresh data first
+- `build-loop:architecture-impact`, `build-loop:architecture-trace`, `build-loop:architecture-rules`, `build-loop:architecture-dead` — sub-steps of this review
+
+*Source: copied verbatim from NavGator and rewritten for build-loop. Drift-checked by `build-loop:sync-skills`.*

package/skills/architecture/rules/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: build-loop:architecture-rules
+description: Use when Phase 4 Review checks architectural integrity, the user asks to "check for violations" or "find circular deps", or before a release. Detects orphans, layer violations, circular dependencies, and hotspots; build-loop's native rules engine from NavGator.
+version: 0.1.0
+user-invocable: false
+source: NavGator/commands/test.md
+source_hash: 4a967c08ff3d7cddd408e7caefcd07b09e8931bcaccf9ea70c0f5aa94349e0d1
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Architecture Rules / Violation Check
+
+Run NavGator's rules engine to detect architectural violations using the `mcp__plugin_navgator__rules` MCP tool. Classifies findings as blocking (circular dependency, layer violation, database isolation breach, frontend-direct-DB at error level) vs warning (hotspot, high-fan-out, orphan).
+
+> **Divergence note**: NavGator has no discrete SKILL.md for rules. The canonical wrapper is `commands/test.md`, which orchestrates `navgator rules` + `navgator dead` + pipeline traces. This skill extracts the rules-only workflow.
+
+## When to Activate
+
+- Phase 4 Review-D Fact-Check: when code changed in this build, run rules to detect new violations
+- Phase 1 Assess: optionally run as a baseline so Review-D can diff
+- User asks "any architecture violations", "is this safe to merge", "what did I break"
+
+## Pre-flight
+
+1. If `.navgator/architecture/index.json` does not exist → no-op with `NavGator: no architecture snapshot found — skipping rules check`. Recommend `build-loop:architecture-scan`.
+2. Check `index.json` `generated_at` timestamp. If >24 hours old, warn: "Architecture data is N hours old — consider running `build-loop:architecture-scan` first for accurate results."
+
+## Rules Workflow
+
+1. Run `mcp__plugin_navgator__rules` (or `navgator rules --json`)
+2. Classify each finding:
+
+| Severity | Categories |
+|----------|-----------|
+| **Blocking** | `circular-dependency`, `layer-violation`, `database-isolation`, `frontend-direct-db` (error level) |
+| **Warning** | `hotspot`, `high-fan-out`, `orphan` |
+
+3. Diff against the Phase 1 baseline if present in `.build-loop/state.json.architecture.rules.baseline`
+4. Flag recurrences against `.navgator/lessons/lessons.json` (lessons with matching `signature`)
+5. Write the result to `.build-loop/state.json.architecture.rules` with `{blocking_count, warning_count, new_violations[], recurrences[]}`
+
+## Decision
+
+- **Blocking findings** → route back to Phase 5 Iterate with the violation as a fresh criterion
+- **Warning findings** → log to `.build-loop/issues/` and surface in Review-F Report
+- **No new violations** → continue Review pipeline; report "No new architectural violations introduced"
+
+## Report Format
+
+```
+ARCHITECTURE RULES
+==================
+Blocking: N (N new this build)
+Warnings: N (N new this build)
+Recurrences against lessons: N
+
+[BLOCKING] Layer violation: ComponentA (frontend) → ComponentB (database)
+  File: src/pages/users.tsx:45
+  Recurrence: matches lesson 'frontend-direct-db' (last seen 2026-03-15)
+```
+
+If no findings: report "No connection-integrity issues found" — do not omit the section.
+
+## Sibling Skills
+
+- `build-loop:architecture-scan` — refresh data first
+- `build-loop:architecture-impact` — pre-flight blast-radius for any blocking finding's affected component
+- `build-loop:architecture-dead` — orphan-only scan (warnings flagged here too)
+- `build-loop:architecture-review` — runs rules as part of a 5-phase integrity review
+
+*Source: NavGator `commands/test.md` (the orchestrator that calls `navgator rules`). The canonical rules engine is the MCP tool. Drift-checked by `build-loop:sync-skills`.*

package/skills/architecture/scan/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: build-loop:architecture-scan
+description: Use when Phase 1 Assess detects stale architecture state, the user asks for an "architecture scan", or before blast-radius analysis. Refreshes Build Loop's native component and connection data in `.build-loop/architecture/`, with NavGator reserved for escalation-only capabilities.
+version: 0.1.0
+user-invocable: false
+source: NavGator/skills/architecture-scan/SKILL.md
+source_hash: 1b4e25d6198373d261502a296dad2ea96abc9e66166115007db940cd48fe7cbb
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Architecture Scan & Status
+
+Scan project architecture, check health, and monitor staleness using Build Loop's native architecture engine (`python -m build_loop.architecture scan`). NavGator remains an optional escalation adapter for capabilities not yet ported into the native engine, such as `llm-map`, `schema`, and `diagram`.
+
+## When to Activate
+
+- Phase 1 Assess: ensure architecture data is fresh (>24h old → re-scan) before sibling skill `build-loop:architecture-impact` consumes it
+- User asks about project architecture, stack, or dependencies
+- After `npm install`, `pip install`, or similar dependency operations
+- User adds/removes dependencies or makes structural changes
+
+## Pre-flight
+
+1. Prefer the repo-local Build Loop venv when present: `<build-loop>/.venv/bin/python -m build_loop.architecture`.
+2. Run `scan` before `rules`, `dead`, `impact`, or `trace` when `.build-loop/architecture/index.json` is missing or stale.
+3. Use `--mode navgator` only when the requested capability is explicitly NavGator-only or the native command reports that escalation is required.
+
+## Scanning
+
+Use the native scanner to detect components and connections. It maps source imports and the Gator-derived runtime edges that Build Loop now owns natively: path-alias imports, manifest package use, frontend `/api/...` fetches, and conservative service/LLM calls.
+
+**Options:**
+- Default: `python -m build_loop.architecture scan --json`
+- Incremental marker: add `--incremental` when the caller is refreshing after a small change
+
+After scanning, present a smart-brevity brief:
+- **Line 1**: "Scanned [project]. [N] components, [N] connections."
+- **Runtime edges**: summarize `connection_counts_by_type` when present
+- **What to watch**: low-confidence detections or missing route/package/service targets
+- **AI routing**: providers and model count if service/LLM calls detected
+
+## Status
+
+Read `.build-loop/architecture/index.json` and `.build-loop/architecture/manifest.json` to show architecture summary without re-scanning. Returns: component counts, connection counts by type, last scan timestamp, and staleness indicator when available.
+
+If no architecture data exists, recommend running scan first.
+
+## Health Checks
+
+Health information is included in scan output:
+- Outdated packages
+- Security vulnerabilities
+- Orphaned connections (dead-code references)
+- Missing imports and unused dependencies
+
+## Decision Tree
+
+| User Intent | Tool | Notes |
+|-------------|----------|-------|
+| "Scan my project" | native `scan` | Full scan |
+| "Refresh after edit" | native `scan --incremental` | Marks scan as incremental |
+| "What's my stack?" | read native manifest/index | No re-scan needed |
+| "Any unused packages?" | native `scan`, then `dead` | `dead` checks manifest declarations |
+| "Is architecture data fresh?" | read native manifest/index | Check timestamp |
+
+## Output Format
+
+Keep output concise. Do NOT dump raw JSON. Summarize into a scannable brief. Write the compact summary into `.build-loop/state.json.architecture.scan` under fields `{component_count, connection_count, connection_counts_by_type, last_scan, staleness, providers}`.
+
+## Sibling Skills
+
+- `build-loop:architecture-impact` — blast radius for a component
+- `build-loop:architecture-trace` — data flow trace
+- `build-loop:architecture-rules` — violation check
+- `build-loop:architecture-dead` — orphan scan
+- `build-loop:architecture-review` — full integrity review
+
+*Source: copied verbatim from NavGator and rewritten for build-loop. Drift-checked by `build-loop:sync-skills`.*

package/skills/architecture/trace/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: build-loop:architecture-trace
+description: Use when the user asks to "trace data flow", "follow this request end-to-end", or "show how X reaches Y". Follows a component's connections from input to output across the architecture; build-loop's native trace copied from NavGator's CLI.
+version: 0.1.0
+user-invocable: false
+source: NavGator/commands/trace.md
+source_hash: d1a62f22ebcf3f19e2f9d52c6df565a4ba5ed53a676b5e02e43e670273f6d9f8
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Architecture Data-Flow Trace
+
+Follow data flow through the architecture using the NavGator `mcp__plugin_navgator__trace` MCP tool. Trace pipelines forward (cron → route → service → DB → queue → LLM) or backward (consumer → producer).
+
+> **Divergence note**: NavGator does not ship a discrete SKILL.md for trace — only a slash command (`commands/trace.md`) that wraps the MCP tool. This skill encodes the same workflow as a build-loop-native skill.
+
+## When to Activate
+
+- Phase 1 Assess: trace pipelines for cron jobs and queue producers when prompts or LLM calls are in scope
+- Phase 5 Iterate: trace forward from a failing endpoint or backward from a downstream symptom to pinpoint the broken link
+- User asks "how does X data flow", "what feeds X", "what does X feed"
+- Component is a cron job, API route, database model, or queue
+
+## Pre-flight
+
+1. If `.navgator/architecture/index.json` does not exist → no-op with `NavGator: no architecture snapshot found — skipping trace`. Recommend `build-loop:architecture-scan`.
+
+## Trace Workflow
+
+1. Run `mcp__plugin_navgator__trace` with the component name
+2. If the component is a cron job or API route, trace forward to show the full pipeline
+3. If it's a database model or queue, trace both directions to show producers AND consumers
+4. Present the trace as a readable pipeline:
+
+```
+/api/cron/refresh-rss [Vercel cron]
+  → route.ts [backend]
+  → rss-ingestion-service [service]
+  → Article [database]
+  → search-enhancement-queue [queue]
+  → OpenAI [LLM provider]
+```
+
+5. Flag any anomalies in the trace (dead ends, duplicate consumers, missing connections)
+6. If trace returns 0 paths, suggest the component might be orphaned (run `build-loop:architecture-dead`) or data may need refreshing (`build-loop:architecture-scan`)
+
+## Tool Options
+
+- `direction: "forward" | "backward" | "both"` — one-way or bidirectional trace
+- `production: true` — filter out test/script connections
+- `max_paths: N` — cap path enumeration on highly-connected components
+
+## Output
+
+Write trace summary into `.build-loop/state.json.architecture.trace[<component>]` with `{paths_count, layer_chain, anomalies[]}`.
+
+## Sibling Skills
+
+- `build-loop:architecture-scan` — refresh data first
+- `build-loop:architecture-impact` — blast-radius alongside trace
+- `build-loop:architecture-dead` — confirm orphan if trace returns 0 paths
+- `build-loop:architecture-review` — full integrity review
+
+*Source: NavGator CLI command (`commands/trace.md`). The canonical implementation is the MCP tool, not a skill file. Drift-checked by `build-loop:sync-skills`.*