Archobs

Archobs (Architecture Observability)

Overview

Measure the actual coupling structure of a codebase using three signals: git co-change history, import/dependency edges, and semantic similarity. These signals are fused into a weighted graph, clustered into logical subsystems, and scored for boundary health, risk, and temporal stability.

Use this skill to ground architecture and refactoring decisions in empirical data rather than intuition. The output feeds directly into architecture, design, plan, and review as evidence.

Success looks like: numbered risk hotspots, measured boundary leakage, and prioritized suggestions with concrete scope.

Chooser (Analysis Mode)

• Full report (default): Run the complete pipeline and generate an HTML report with suggestions. Use for initial analysis or periodic health checks.
• Targeted stage: Run a single pipeline stage (inventory, git, deps, embed, build-graph, cluster) when you only need one artifact updated.
• Suggestion loop: Run analysis, apply one suggestion, re-analyze, repeat until convergence. Use for automated refactoring passes.
• Regression check: Compare current metrics against a previous run. Use in finish to verify architecture health did not degrade.

Inputs / Outputs

Inputs: Git repository path with history. Outputs: JSON artifacts — file risk scores (xnbr, hubness, volatility), cluster health (leakage, cohesion, conductance), drift data (ARI, modularity), velocity metrics, team analysis, suggestions. Consumed by architecture, design, plan, review, finish, forecast.

Workflow

1. Check prerequisites:

   • Install codanna: brew install codanna (macOS) or curl -fsSL --proto '=https' --tlsv1.2 https://install.codanna.sh | sh (Linux)
   • Install archobs from the bundled tool: pip install -e 'tools/archobs[full]'
   • Verify the target repo has git history (git log must succeed)

2. Initialize workspace (first run only):

   archobs init --repo <path> --out .archobs
   

   Skip if running report directly — it initializes the workspace automatically. Only run init separately if you need to edit config.json before the first analysis.

   Then ensure archobs-related paths are in the project's .gitignore — these are generated artifacts, caches, and bundled assets that should not be committed:

   for entry in .archobs/ .codanna/ .codannaignore .fastembed_cache lib/; do
     grep -qxF "$entry" .gitignore 2>/dev/null || echo "$entry" >> .gitignore
   done
   

3. Run full analysis (blocking — wait for completion):

   archobs report --repo <path> --out .archobs --suggestions-provider rules
   

   Use --suggestions-provider rules (the default) when running inside a skill — the rule-based engine is fast, deterministic, and produces structured suggestions that the current session can interpret directly.

   Do not proceed to step 4 until the report command has finished. Steps 4–6 depend on the artifacts produced by this command. If the command is run in the background, wait for it to complete before continuing.

GATE: Do not proceed to step 4 until the archobs report command has finished. Steps 4-9 depend on the artifacts it produces. If the command was run in background, wait for completion — do not read stale or missing artifacts.

The completed run must leave .archobs/run_manifest.json with status: "complete". A full report marks any prior HTML report stale while it is running and keeps it visibly stale if the run fails. A targeted stage marks the workspace stale, visibly marks any existing HTML report, and causes archobs show result commands to fail until a full report restores a complete generation.

4. Read results — use archobs show to extract metrics (no ad-hoc Python or Parquet libraries needed).

   All show subcommands read from Parquet artifacts independently — run them in parallel when calling from an agent. This avoids sequential round-trips and is 5-6x faster.

   Recommended for agents — run individual queries in parallel (avoids output truncation on large repos):

   # Run these in parallel:
   archobs show risks --top 10 --format json
   archobs show clusters --sort leakage --format json
   archobs show drift --format json
   archobs show summary --format json
   archobs show velocity --window 30 --compare --format json
   archobs show suggestions --format json
   archobs show team --format json
   

   Note: show edges requires a cluster_id from show clusters or show velocity. Run it after those complete, targeting the top 2-3 leakiest or most active clusters:

   archobs show edges <cluster_id> --format json
   

   Or use --top-active to auto-select the most active clusters by file_change_count (eliminates the sequential round-trip):

   archobs show edges --top-active 3 --format json
   

   Large repos warning: --top-active output scales with cluster size. Hub clusters (100+ files) can have 15+ neighbors, producing output that exceeds context limits. Use --max-neighbors 10 to cap neighbor count per cluster:

   archobs show edges --top-active 3 --max-neighbors 10 --format json
   

   Edge JSON output schema (per neighbor):

   neighbor_cluster, neighbor_label, total_weight, edge_count, leakage_share,
   top_pairs: [{path_a, path_b, weight}]
   

   leakage_share = total_weight / parent_cluster.external_weight — the fraction of the queried cluster's leakage flowing to this neighbor (e.g., 0.62 means 62% of the cluster's external coupling goes to this neighbor).

   Convenience — compact all-in-one (agent-friendly, <50KB output):

   archobs show all --compact --format json
   

   The --compact flag limits output to 5 risks, 10 clusters, and edges for top-3 clusters only. Velocity always includes added_paths in JSON output.

   When to use compact vs parallel queries:

   • Repos < 500 files: show all --compact is sufficient for a quick overview
   • Repos 500–2000 files: parallel individual queries recommended — compact output truncates important context
   • Repos > 2000 files: parallel queries required, and consider --top limits to control output size

   Full dump — for human review or when you need everything:

   archobs show all --top 5 --format json
   

   Avoid --top 0 on large repos — output can exceed context limits.

   Additional queries:

   archobs show files --format json                           # complete file-to-cluster mapping
   archobs show cluster-files <id> --format json              # files in a specific cluster
   archobs show velocity --window 30 --compare --format json  # added_paths included by default in JSON
   archobs show risks --min-risk 0.5 --min-volatility 0.5 --format json  # high-risk AND high-churn files
   archobs show commits --since 30 --format json              # commit-level data with cluster annotations
   archobs show hot-files --window 30 --top 10 --format json  # hottest files by commit count with clusters
   archobs show suggestions --format json                     # structured suggestions (reads suggestions.json)
   

   Use --format table (default) for human-readable output, --format json for structured agent consumption, or --format csv for piping.

   To discover column names for any artifact: archobs schema file_metrics

5. Interpret key metrics (see references/interpreting-metrics.md):

   File-level risk (archobs show risks):

   Signal	Threshold	Meaning
   risk	> 0.5	High combined risk — prioritize for refactoring
   xnbr	> 0.35	Cross-boundary neighbor ratio — file bridges multiple concerns
   hubness	> 0.45	High fan-in — changes here have wide blast radius
   volatility	relative	High churn rate compared to peers

   Filter directly: archobs show risks --min-risk 0.5 --format json or --min-xnbr 0.35 or --min-hubness 0.45 or --min-volatility 0.5.

   Cluster-level health (archobs show clusters):

   Signal	Threshold	Meaning
   leakage	> 0.20	Boundary is porous — responsibilities bleed across
   cohesion	< 0.30	Weak internal connectivity — cluster may be artificial
   conductance	relative	Cross-boundary edge fraction (lower is healthier)

   Drift (archobs show drift):

   Signal	Threshold	Meaning
   ari_prev	< 0.50	Architecture is unstable — subsystem map is reshuffling
   modularity	declining	Boundaries are weakening over time

   Drift trend interpretation — the trend across windows matters more than any single value:

   Pattern	Interpretation
   ARI rising toward 1.0	Stabilizing — architecture is settling after upheaval
   ARI falling across windows	Degrading — boundaries are being broken
   ARI oscillating	Volatile — team is experimenting with structure
   Modularity declining while ARI rises	New cross-cutting features are landing in a stable structure

   When reporting drift, always examine the ARI trend (last 2+ windows) rather than applying a single threshold. A codebase with ARI 1.0 → 0.38 → 0.58 → 0.77 is stabilizing, not unstable.

   Young repos: Repos with less than 6 months of history may produce fewer drift windows than configured. This is expected — interpret the trend with whatever windows are available.

   Velocity (archobs show velocity):

   Signal	Suggests
   High growth_ratio	New capability being built — define boundaries early
   High churn_ratio	Feature refinement/iteration in progress
   High acceleration (with --compare)	Active development push
   Low acceleration	Work winding down — safe window for refactoring
   High recent_file_changes_30d in cluster	Focused sprint in one area
   High external_inbound_weight	Gravitational center — other clusters pull toward this one

   --compare flag: Use --compare to enable acceleration metrics (compares current window to prior window of the same length). Without it, only absolute velocity is shown. With it, you get prior_commit_count, acceleration (current/prior ratio), and is_emerging (true when a cluster had zero commits in the prior window).

   Velocity sort order: show velocity sorts by distinct_commits by default. Use --sort file_change_count or --sort acceleration (requires --compare) for alternative orderings. Note that show edges --top-active sorts by file_change_count, which can produce a different ranking than the default velocity output.

   Known limitation — deleted files: Velocity uses an inner join between commits and the current file inventory. Files deleted during the analysis window have no cluster assignment, so their commits are silently dropped. The deleted_count column reflects only deletions of files that still exist in the inventory (renamed/moved), not files fully removed from the codebase.

   Filter to active clusters: archobs show velocity --window 30 --compare --min-acceleration 1.0 --min-growth-ratio 0.1 --format json

   For detailed velocity signal interpretation (feature adjacency reasoning, acceleration context, convergent hub patterns), see the forecast skill (internal engine).

6. Team analysis — check bus factor and knowledge concentration per cluster:

   archobs show team --format json
   archobs show team --sort concentration --format json
   archobs show team --sort bus_factor --min-size 3 --format json
   

   Signal	Threshold	Meaning
   bus_factor	1	Single point of failure — one person owns the cluster
   hhi	> 0.5	High knowledge concentration — few authors dominate
   top_author_pct	> 0.8	Top contributor owns 80%+ of commits

7. Fitness check — CI-gatable architecture health evaluation:

   # Quick check with defaults
   archobs check --format json
   
   # CI mode (JSON output, exit code 0/1)
   archobs check --ci
   
   # Custom thresholds
   archobs check --max-file-risk 0.7 --max-leakage 0.5 --min-bus-factor 2 --ci
   

   The check command is read-only — it never runs the pipeline or writes artifacts, making it safe for CI. Add to your CI pipeline:

   - name: Architecture fitness check
     run: archobs check --out .archobs --ci
   

   Default thresholds: --max-file-risk 0.8 --max-leakage 0.6 --min-cohesion 0.4 --max-risk-mean 0.5 --min-bus-factor 2 --min-cluster-size 2

   Bus factor check is optional — skipped if bus_factor.parquet doesn't exist (team analysis not run).

8. Route findings to the right skill:

   • High leakage between clusters: architecture (boundary redesign) or design (Facade — see structural pattern references)
   • High-risk file with mixed concerns: design (pattern selection and implementation guides)
   • Multiple high-risk areas needing sequencing: plan (prioritize refactoring order)
   • Development momentum and feature prediction: forecast internal engine (which clusters are active, what features are likely next). When running forecast in the same session, archobs artifacts are already available — the forecast skill can read directly from .archobs/ without re-extraction. added_paths are included by default in JSON output, surfacing exactly which new files are being built in each cluster. Quick trajectory in the same session (no skill switch needed): run archobs show velocity --window 30 --compare --format json (added_paths included by default), check git branch -r --sort=-committerdate | head -20, and apply feature adjacency heuristics from the forecast skill. For full trajectory analysis with commit message themes and detailed interpretation, invoke the forecast skill (internal mode).
   • Pre-merge health check: finish (verify metrics did not regress)
   • Thorough assessment of structural findings: review (type: architecture)

9. Read suggestions (if generated): If you already ran archobs show all --format json in step 4, suggestions are included under the "suggestions" key — no additional command needed.

   When using individual parallel queries (step 4), add archobs show suggestions --format json to your parallel batch — this reads suggestions.json directly with no extra computation:

   archobs show suggestions --format json
   

   Alternatively, use archobs prompts --out .archobs for markdown-formatted output.

   Each suggestion includes: priority, title, why (evidence), change (action), scope (affected files).

Minimum viable execution

When context or time is constrained, these are the load-bearing steps:

1. Run report (step 3) — must complete before anything else. Wait for it.
2. Read summary + risks (step 4) — archobs show summary --format json and archobs show risks --top 10 --format json.
3. Interpret key metrics (step 5) — file risk thresholds, cluster leakage, drift trend.
4. Route findings (step 8) — which downstream skill gets the findings.

Steps that can be cut under pressure: team analysis (step 6), fitness check (step 7), suggestion loop, detailed edge inspection.

Combined Archobs + Trajectory Workflow

For the combined archobs + trajectory workflow, see the forecast skill (internal engine — combined archobs + trajectory workflow). That version includes archobs show suggestions --format json in the parallel batch and is the canonical reference.

Clarifying Questions

• What is the target repository path?
• Is this a first analysis or a follow-up? (Previous .archobs/ artifacts will be overwritten.)
• Should suggestions use an LLM provider (claude/codex) or rule-based only?
• Is there a specific area of concern, or should we analyze the full codebase?
• What languages are in the repo? (Supports Python, TypeScript, JavaScript, Java.)

Guardrails

• Do not run on repos with fewer than ~10 tracked source files — the graph needs sufficient signal.
• Do not treat cluster assignments as ground truth — they are statistical groupings that approximate logical subsystems.
• Do not skip interpreting metrics before routing to other skills — raw numbers without context lead to wrong decisions.
• Do not use the suggestion loop without human review of each applied change.
• Do not commit archobs artifacts to the repository — .archobs/, .codanna/, .codannaignore, .fastembed_cache, and lib/ must all be in .gitignore.
• If leidenalg is not installed, the tool falls back to greedy modularity (lower-quality clustering) — note this in output.

Common failure modes

• Doesn't wait for the report command to complete before reading results — reads stale or missing Parquet artifacts and produces incorrect metrics.
• Only looks at risk scores, ignores drift data — misses that the architecture is actively reshuffling (low ARI) which makes broad refactoring moves dangerous.
• Treats cluster labels as authoritative ground truth — labels are statistical groupings, not verified architectural boundaries. Always cross-reference with actual code.
• Runs on a repo without recent git history — stale commit data produces stale velocity and coupling metrics.

Map To Existing Skills

• Boundary redesign from leakage data: architecture
• In-process pattern selection from coupling data: design
• Refactoring prioritization from risk scores: plan
• Development trajectory and feature prediction from cluster activity: forecast (internal engine)
• Architecture health regression gate: finish
• Architecture-type adversarial review: review
• Facade/Adapter for porous boundaries: design (structural pattern references)
• Mediator for high-hubness coordination files: design (behavioral pattern references)

References

• Interpreting archobs metrics: references/interpreting-metrics.md
• Running archobs locally: references/running-archobs.md
• Tool source and standalone docs: tools/archobs/README.md

Output Template

When reporting analysis results:

• Summary: cluster count, edge count, embedding provider, modularity score.
• Top risk files (3-5): path, risk score, primary signal (xnbr/hubness/volatility), recommended action.
• Leakiest clusters (1-3): cluster ID, leakage %, strongest outward pull, boundary recommendation.
• Drift assessment: stable / degrading / improving (with ARI values).
• Suggestions (if generated): priority-ordered list with scope and evidence.
• Trajectory (when running with forecast internal engine):
  • Active feature initiatives (grouped by domain, not by cluster)
  • Feature adjacency predictions with confidence levels
  • Recommended architectural actions for growing areas
• Next skill: which skill to invoke based on the dominant finding pattern.