mcpField
R
repo-architecture

repo-architecture

github.com/objectivlabsDevelopment9242 installsUpdated 19w ago
Repository

About repo-architecture

repo-architecture is RepoSkillOpt's repository-specific skill for analyzing the current architecture, aimed at developers assessing dependencies and change impact. It requires a Repository Specification, grounds findings in code evidence, and checks the resulting architecture and impact artifacts.

Key features

  1. 01Corroborate code evidence against the repository specification
  2. 02Map context, containers, and components
  3. 03Trace end-to-end sequences and dependency graphs
  4. 04Analyze change impact on modules, tests, and call sites
  5. 05Label claims as facts, inferences, or unknowns
  6. 06Run completeness checks on architecture and impact artifacts

Use cases

  1. 01Map modules and dependencies in a repository
  2. 02Assess the impact of changing a named target
  3. 03Verify architecture and call paths before implementation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/objectivlabs/reposkillopt --skill repo-architecture

After installing, type/repo-architecturein Claude Code to confirm it loaded.

Bundled filesCHANGELOG.md

Details

From the project README

RepoSkillOpt — As-Is Architecture Analysis (Canonical Skill)

Purpose

This is the repo-specializing analysis layer of RepoSkillOpt. The generic understanding skill (repo-skillopt) is unchanged — it produces the repo-neutral Repository Specification. This skill specializes on a specific repository: it deepens that Repository Specification into an evidence-grounded view of the current architecture and answers "what would a change ripple into?" — before anything is touched. It produces an Architecture View and a Change-Impact (blast-radius) Analysis, and is the analyze as-is stage the plan to-be skill (repo-orchestration) consumes. The skill's own content is vendor-neutral (no coding-agent runtime dependency); its output is repo-specific.

Trigger Conditions

Activate when the user asks to map the architecture, assess dependencies/coupling/layering, or evaluate "what would change if we… / is it safe to change X" — or recognizable equivalents. Do not activate for unrelated requests.

Prerequisite

A Repository Specification (.reposkillopt/specs/repository-specification.md). If absent, state the prerequisite and point the user to the repository-understanding skill; do not fabricate an architecture from shallow inspection.

Operating Principles

  • Build on the spec, corroborate against code. The Repository Specification is the starting evidence; verify every architectural claim against the actual files, configs, and call sites.
  • Ground every major claim. Each carries exactly one label — **[fact]**, **[inference]**, **[unknown]**, **[human]**; **[fact]** MUST carry a resolvable file:line/symbol citation.
  • No silent omission. Unresolvable structure or impact is **[unknown]** with the reason, never dropped.
  • Do not overclaim. Do not describe layers or flows you have not traced; mark inference as inference.
  • Repository facts stay repository-scoped. Only patterns explicitly marked candidate-for-generic may enter the skill-convergence loop.

Workflow

(a) Read the Repository Specification and the entrypoints, manifests, and core modules it cites.

(b) Architecture View (.reposkillopt/architecture/architecture-view.md, per templates/architecture-view.md): C4-style levels — Context (system + external actors), Containers (runtime/deployable units), Components (modules within containers) — plus Key sequences (end-to-end flows, cited at each hop) and a Dependency graph (cited internal edges). Every component and edge cites a real file:line. Diagrams (graph, sequenceDiagram) are visual aids and carry no citations; every node/edge they show also appears as a cited line.

(c) Change-Impact Analysis (.reposkillopt/impact/change-impact-analysis.md, per templates/change-impact-analysis.md): for the named target/change, the affected modules, tests, contracts, and call sites — each row with a confidence label (high|medium|low) tied to evidence strength (direct cited call site = high; name-resolution/inference = medium; dynamic/unresolved = low and **[unknown]**) and a citation. Locate impact with a fast scanner (rg/grep) and read only the matched lines you cite.

(d) Deterministic completeness gate. Before finishing, the artifacts MUST pass the deterministic checks (check_architecture_view, check_impact_analysis): every component/edge cited and resolvable; every impact row carries a citation and a confidence label.

Output Discipline

Labels: **[fact]** (verified; cited), **[inference]** (state the basis), **[unknown]** (also listed as such), **[human]** (cite the Feedback Item id). Citations use path:line, path:start-end, path:Symbol[:line], or cmd:/output:. Trivial recitations need no label.

Human Feedback Loop

Corrections are recorded as Feedback Items (templates/human-feedback.md) under .reposkillopt/feedback/ and applied to the artifact in place. Repository-specific corrections stay repository-scoped.

Skill Convergence Loop

When recurrent feedback (≥3 related items) marked candidate-for-generic reveals a weakness in this skill, draft a Skill Edit Proposal (templates/skill-edit-proposal.md). It may be accepted only after passing the validation gate (rubric/validation-gate.md): regenerate the artifacts for a disjoint held-out reference set with no per-dimension rubric regression (see rubric/asis-architecture-rubric.md) and the deterministic checks still passing. Nothing is silently promoted; acceptance bumps the version + adds a CHANGELOG entry. Mirror every accepted edit into the four adapters (adapter-equivalence).

Comments

Markdown supported