repo-reader
Introspect, reflect on, and extract architectural patterns, commit trajectories, and engineering heuristics from an attached Git repository. Do not use for simple file tree listing or destructive repository mutations.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- repo-reader
- description
- Introspect, reflect on, and extract architectural patterns, commit trajectories, and engineering heuristics from an attached Git repository. Do not use for simple file tree listing or destructive repository mutations.
02 资源文件 2
- 参考文档CARD.md3.7 KB
- 参考文档config.default.yaml287 B
03 SKILL.md 正文
Repo Reader: Codebase Introspection & Repository Distillation Engine
repo-reader is the repository-level cognitive introspection engine for Brain Harness. Operating atop plugin.brain_bridge, it mounts local Git repositories or remote GitHub/GitLab repositories to analyze multi-language codebases, architectural seams, and historical Git commit trajectories—distilling them into grounded, decision-ready Knowledge Items (KIs).
Every repository reflection session follows a five-stage progression:
[1. Attach & Detect] → [2. 4-Axis Repo Matrix] → [3. Visual Repository Brief] → [4. Synthesis Checkpoint] → [5. KI Extraction & Lineage Commit]
See CARD.md for the companion summary card, 4-axis repository prompt matrix, and invariants.
Consult /crafting-skills for skill craft standards, /mind-reader for foreign brain introspection, and /epistemic-isnad-audit for chain-of-custody provenance rules.
1. Attach & Format Detection
Mount the target repository using the plugin.brain_bridge entrypoint:
- Invoke
brain_attach:folder_path: Target directory path or remote Git URL (e.g.https://github.com/org/repo.git).alias: Descriptive mnemonic identifier (e.g.,upstream_repo,fastapi_core).read_commits:trueto extract Git commit history into cognitive trajectory chunks.max_commits:50to100commits.attach_mode:"lens"(read-only ephemeral introspection).
- Handle Boundary & Archive Snapshots:
- External Workspace Paths: If the target directory is outside the IDE workspace root and direct file tools return permission errors, use shell inspection commands (
run_commandwith PowerShell/bash) anchored in the host workspace. - Nested Root & Non-Git Snapshots: Detect if the repository is an unzipped archive snapshot without
.gitor contains a single nested subdirectory root. If.gitis absent, gracefully pivot Axis 2 from Git commit trajectories to release notes, changelogs, and manifest evolution.
- External Workspace Paths: If the target directory is outside the IDE workspace root and direct file tools return permission errors, use shell inspection commands (
- Verify Format Signature & Manifests:
Confirm format signature (
git_repository,harness_instance,ide_memo) and note detected languages and packaging manifests (pyproject.toml,package.json,Cargo.toml,go.mod, etc.). - Log Mount Volume: Confirm total chunks, code chunks, git commit trajectory chunks, detected branch, and vocabulary index size.
Completion criterion: Target repository mounted with
status: "ok", languages identified, and commit trajectories recorded.
2. 4-Axis Repository Introspection Matrix
Execute four structured queries via brain_query across the mounted repository to interrogate its structural and historical surface:
┌─────────────────────────────────────────────────────────────┐
│ 4-AXIS REPOSITORY INTROSPECTION │
├──────────────────────────────┬──────────────────────────────┤
│ Axis 1: Architecture & Seams │ Axis 2: Commit Trajectories │
│ - IoC / Service registry │ - Historical bug fixes │
│ - Module boundaries & layers │ - Refactor evolution & diffs │
├──────────────────────────────┼──────────────────────────────┤
│ Axis 3: Engineering Standards│ Axis 4: Delta Innovations │
│ - Test patterns & fixtures │ - Deep module designs │
│ - Typing, linting, CI rules │ - Novel algorithms & tooling │
└──────────────────────────────┴──────────────────────────────┘
- Axis 1 (Architectural Topography & Seams):
- Query:
"What are the core architecture patterns, IoC service keys, entrypoints, and module boundaries?" - Purpose: Surface component relationships, dependency flow, and interface contracts.
- Query:
- Axis 2 (Commit Evolution & Trajectories):
- Query:
"What major refactors, breaking changes, or bug fixes occurred in recent commit history?" - Purpose: Understand how the codebase evolved, what pitfalls were encountered, and how design decisions matured.
- Query:
- Axis 3 (Engineering Conventions & Verification Standards):
- Query:
"What testing frameworks, typing standards, CI workflows, and coding conventions are enforced?" - Purpose: Identify testing hygiene, error handling conventions, and verification gates.
- Query:
- Axis 4 (Delta Innovations & Reusable Assets):
- Query:
"What unique algorithms, deep module implementations, or reusable abstractions exist in this repository?" - Purpose: Extract reusable techniques, high-leverage primitives, and domain models.
- Query:
Completion criterion: 4 query result batches harvested, sorted by cosine relevance, with exact source file and commit hash citations.
2.1 Quantitative Scoring & Tiered Prioritization Matrix
When comparing foreign harnesses or evaluating candidate capabilities against Brain Harness, apply the objective scoring formula:
$$\text{Total Score} = \text{Usefulness} + (6 - \text{Difficulty}) + \text{Value} + \text{Architectural Fit}$$
(Each scored 1–5; Difficulty is inverted so that easier adoptions score higher, Max: 20).
Structure candidate features into a 3-Tier Roadmap:
- Tier 1 (Immediate Quick Wins): Python-native, low-medium difficulty, direct service plugin fit (Weeks 1–2).
- Tier 2 (Strategic Safety & Observability): Structural invariants, DAG execution graphs, permission policies, session replays.
- Tier 3 (Horizon Bets): Alternative language runtimes, local model inference, peer-to-peer distributed meshes.
3. The Visual Repository Brief
Synthesize the harvested architectural and commit insights into an interactive, standalone HTML report:
- Output Location: Write to
%TEMP%\repo-reader-<timestamp>.html(Windows) or/tmp/repo-reader-<timestamp>.html(Unix). - Visual Standards:
- Use Tailwind CSS and Mermaid.js via CDN in dark mode (
#0d1117). - Include a Mermaid Repository Architecture & Dependency DAG showing core modules, bridges, and services.
- Display a Commit Evolution & Refactor Timeline highlighting pivotal architectural transitions.
- Provide a side-by-side matrix of Architectural Strengths vs. Friction Areas.
- Use Tailwind CSS and Mermaid.js via CDN in dark mode (
- Delivery: Surface the absolute file path with clickable links to the user.
<!-- Location: %TEMP%\repo-reader-<timestamp>.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Repo Reader: Repository Introspection Brief</title>
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true, theme:'dark'});</script>
</head>
<body class="bg-[#0d1117] text-[#c9d1d9] p-8 max-w-6xl mx-auto font-sans">
<header class="border-b border-[#30363d] pb-4 mb-6">
<h1 class="text-2xl font-bold text-white">Repository Introspection Brief</h1>
<p class="text-sm text-gray-400 mt-1">Multi-Language Codebase Analysis & Commit Trajectory Distillation</p>
</header>
<!-- Mermaid DAG & 4-Axis Repository Analysis Grid -->
</body>
</html>
Completion criterion: Standalone HTML brief generated in
%TEMP%and delivered to user.
4. Synthesis Checkpoint
Present candidate architectural and engineering learnings to the user before committing persistent memory:
- Formulate atomic candidate Knowledge Items (KIs) with:
- Title: Actionable architecture pattern or engineering heuristic.
- Context: Problem space, language/framework context, and trigger conditions.
- Distilled Learning: Positive recommendation, seam choice, or mitigation strategy.
- Provenance Link: Exact file path, line coordinates, and Git commit hash in the source repo.
- Present candidate KIs via an interactive multi-select checkpoint (
ask_question) orRequestFeedback: trueproposal. - Await user confirmation on which items to retain, adjust, or discard before writing files.
Completion criterion: User review checkpoint completed; approved items selected for commit.
5. KI Extraction & Lineage Commit
Persist approved learnings into the host repository's knowledge directory:
- Target Directory: Write to
.harness/knowledge/<ki_id>/on the host. - Metadata Schema (
metadata.json):{ "id": "ki_20260822_repo_01", "title": "Typed Service Key Registration in Plugin Systems", "source_target": "https://github.com/org/repo", "detected_format": "git_repository", "isnad": { "decision_id": "dec_20260822_repo_01", "claims": [ { "assertion": "Typed ServiceKey[T] registration required for IoC containers", "lineage": [ {"node_type": "primary_code", "uri": "src/kernel/context.py#L42-L68", "sha256_hash": "a1b2c3d4", "verified": true} ] } ], "status": "VERIFIED" }, "tags": ["architecture", "ioc_container", "plugin_lifecycle"] } - Artifact Summary: Co-locate
summary.mddetailing the operational guideline and code examples.
Completion criterion: Approved KIs written with unbroken Isnad provenance links and commit citations.
Anti-Patterns
- Surface Code Scanning — Reading file listings without querying deep module implementations or commit evolution.
- Disconnected Commit Analysis — Inspecting commit messages without correlating them to modified code files.
- Foreign Repository Mutation — Attempting to write, commit, or alter files in the external mounted repository.
- Unanchored Seam Extrapolations — Speculating on architectural intent without citing source lines and commit diffs.
04 同仓库更多 Skills
ui-behavior-primitive-architect
Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA/SSR/RTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.
trustgraph-ontology-governor
Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.
shim-harness-governor
Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.
graphiti-zep-memory-governor
Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash/LSH entity dedup, RRF/MMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.
agora-mcp-workbench-architect
Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway/dispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.
skill-eval-assurance-runner
Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.