pod
Other formats agents might prefer:
markdownjsonllms.txt

Agent? You probably want markdown or json, or Pod over MCP.

Reported issues for archy

Pod holds 18 of 28 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to archy.

Most discussed

chore(distribution): the official MCP registry listing is stale at 0.13.3, and server.json drifts every release

Split out of #324, which listed the official registry as a pending submission. It is not pending. It is listed, and it has been stale since launch day.

What is live right now

name        : io.github.hslee16/archy
version     : 0.13.3
publishedAt : 2026-05-13T18:13:26Z     <- Show HN day, never updated since
status      : active, isLatest: true

Verified against https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hslee16/archy on 2026-07-25.

archy is on 0.42.0.

Read the thread · 2026-07-25 · closed · 4 comments

bench: execute the Q1b agent A/B (does archy-in-the-loop reduce structurally-bad edits?)

Child of #346. The central claim archy is built on, and the one thing never measured.

Status

The protocol already exists. docs/research/INLOOP_PREVALENCE_EMPIRICS.md resolved Q1a and specified an executable Q1b design with a powered A/B and a control baseline. AGENT_CAUSAL_REASONING_SYNTHESIS.md §10 records it:

Q1b (the causal claim, does archy-in-loop reduce agent regressions) remains open but now has a powered, executable A/B protocol and a control baseline (this study). Q1

Read the thread · 2026-07-25 · closed · 3 comments

fix(deps): mcp 2.0 removed mcp.server.fastmcp, so unbounded mcp>=1.28.1 ships a broken MCP server

Found during the v0.43.0 release smoke test, on a fresh wheel install into a clean venv.

The bug

pyproject.toml declared mcp>=1.28.1 with no upper bound. mcp 2.0.0 removed mcp.server.fastmcp, which src/archy/mcp.py imports at module scope:

from mcp.server.fastmcp import FastMCP    # mcp.py:96

So a fresh pip install archy resolves mcp 2.0.0 and the MCP server dies on import:

$ uv venv v && uv pip install --python v/bin/python archy-0.43.0-py3-none-an

[Read the thread](https://github.com/hslee16/Archy/issues/391) · 2026-08-01 · closed · 2 comments

### research: what, if anything, archy should take from Moderne / OpenRewrite

## Why

Moderne (https://moderne.ai/) is a commercial platform for large-scale automated
code change, built on the open-source OpenRewrite engine. It is priced as an
enterprise tool. The question for this ticket is narrow and empirical: **is there
anything Moderne does that archy could do, or should do, so that reaching for a
paid platform is not the only option?**

The answer might well be "no, almost none of it" - see Scope below. Research it,
write down the answer either way, close the ticket

[Read the thread](https://github.com/hslee16/Archy/issues/385) · 2026-07-30 · open · 2 comments

### feat(contracts): intended-vs-actual conformance score (ADL refinement/traceability → architecture-erosion monitor)

## Motivation

From deep-reading Medvidovic & Taylor, *"A Classification and Comparison Framework for Software Architecture Description Languages"* (IEEE TSE 26(1), 2000). Classical ADLs were *prescriptive* (hand-written intended architecture); the paper rewards languages that can relate the intended architecture to its realization (**refinement / traceability**).

Archy is a *recovery* tool, so that axis becomes: declare the intended topology, measure the **drift** between intended and actual, 

[Read the thread](https://github.com/hslee16/Archy/issues/271) · 2026-07-13 · closed · 2 comments

### MCP surface consolidation pass v2: invisible-tool audit (14 -> ~9)

## Why now

Prompted by gingerBill, ["Good Tools Are Invisible"](https://www.gingerbill.org/article/2026/07/10/good-tools-are-invisible/). The thesis: a good tool disappears into the background; the toolmaker's job is *good defaults* that do the thinking once so a thousand users don't each re-derive it, with escape hatches reserved for the genuine minority.

archy's job is an inversion of that essay: **archy exists to make the invisible visible** (coupling, cycles, duplication, drift). But archy

[Read the thread](https://github.com/hslee16/Archy/issues/265) · 2026-07-10 · closed · 2 comments

### Static fragility proxy (git-free hotspot stand-in)

## Summary

Add a **static fragility proxy**: rank modules that are high-instability **and** high-fan-in ("central and volatile") as a first-cut "be careful here" signal that ships **without** the git-history overhead of the full `archy hotspots` feature.

## Motivation

`archy hotspots` is the gold-standard refactor-priority signal but requires git history (single `git log --name-only` pass) and so returns nothing on a fresh checkout, a shallow clone, or a non-git tree. A purely structural prox

[Read the thread](https://github.com/hslee16/Archy/issues/134) · 2026-05-25 · open · 2 comments

### Opt-in agent hooks (archy install --hooks)

## Summary

Add `archy install --hooks`: register a lifecycle hook in each detected agent client that runs the archy gate automatically after edits, so the feedback loop fires whether or not the agent remembers to call the MCP tools.

## Motivation

The MCP tools are pull-based: the loop only closes if the agent chooses to call `archy diff` / `archy score`. The 2026-05 agent-loop test showed agents sometimes read `archy.yaml` + `CLAUDE.md` directly instead of calling the tools, so contract feedb

[Read the thread](https://github.com/hslee16/Archy/issues/132) · 2026-05-25 · closed · 2 comments

## Most recent

### docs(claude): the one inviolable rule is the last thing in CLAUDE.md

Raised by the `prompt_best_practices` review during #369's write-up, and filed rather than folded in because it is about the file's pre-existing structure, not that change.

## The finding

**"Branch and open a PR. Never push to `main`."** is the single highest-stakes rule in `CLAUDE.md`: an absolute prohibition with no exceptions, unlike almost everything else in the file, which is a conditional heuristic. It currently sits in the shortest section, at the very end, after ~150 lines about CI, ga

[Read the thread](https://github.com/hslee16/Archy/issues/381) · 2026-07-27 · open · 0 comments

### MCP: fold archy_dsm into archy_graph(view="dsm") (#265)

Part of #265 (invisible-tool consolidation). Medium confidence.

**Fold:** `archy_dsm` -> `archy_graph(..., view="dsm")` (or `response_format="dsm"`).

**Why:** `archy_dsm` and `archy_graph` are both "show me the structure." dsm is explicitly visualization-only; graph already routes across summary/full/focus via `response_format`. A DSM is one more rendering of the same dependency graph, a *view*, not a separate decision. Two "inspect the graph" schemas collapse to one, removing an overlap the a

[Read the thread](https://github.com/hslee16/Archy/issues/269) · 2026-07-10 · closed · 1 comment

### MCP: unify archy_check + archy_contracts + archy_cycles into one constraint-validation tool (#265)

Part of #265 (invisible-tool consolidation). Highest conceptual payoff, medium risk, design first.

**Fold:** the three "what architectural rules am I breaking" tools into one `archy_check`:
- `archy_check` (layer rules from `archy.yaml`)
- `archy_contracts` (import-linter contracts, "stricter than check")
- `archy_cycles` (the acyclicity invariant)

**Why:** to a caller these answer one question, "is my structure legal, and where not?" Three separate tools force the agent to know that contracts

[Read the thread](https://github.com/hslee16/Archy/issues/268) · 2026-07-10 · closed · 1 comment

### MCP: demote archy_status off the agent-facing surface (#265)

Part of #265 (invisible-tool consolidation).

**Move:** drop `archy_status` from the `archy mcp` tool surface; keep the capability as CLI (`archy index status`) and/or fold the freshness fields into an existing tool.

**Why (high confidence):** `archy_status` reports index plumbing (`last_synced_at`, `cached_files`, `watching`). By the README's own note, results are *never stale* (every tool syncs on demand), so an agent almost never needs to consult freshness mid-task, it is diagnostic, not a d

[Read the thread](https://github.com/hslee16/Archy/issues/267) · 2026-07-10 · closed · 1 comment

### MCP: fold archy_trend into archy_score(view="history") (#265)

Part of #265 (invisible-tool consolidation).

**Fold:** `archy_trend(path, last_n)` -> `archy_score(path, view="history", last_n=10)`.

**Why (high confidence, low risk):** `archy_trend` does one thing: read recent score history. That is a *view of the score over time*, not a separate decision the agent makes. `archy_score` already carries mode flags (`record=`, `strict=`), so a `view="current"|"history"` switch is idiomatic and mirrors the #227 pattern. Two tool schemas that both say "the score

[Read the thread](https://github.com/hslee16/Archy/issues/266) · 2026-07-10 · closed · 1 comment

### Duplicate detection: semantic de-noiser to raise precision (follow-up to #133)

Follow-up to #133 (duplicate-function detection, shipped CLI-first in PR #241). Gates the `archy_duplicates` MCP tool.

## Problem

The shipped detector clusters functions by normalized AST shape + a `--min-nodes` size floor. A 15x3 false-positive spot-check on fastapi / pytest / django (see `docs/research/RESEARCH_METRICS.md` section 12) measured **~42% precision at the default** (`--min-nodes 30`; 19/45 clusters were genuine duplication). Real duplication *is* surfaced, but the false-positive 

[Read the thread](https://github.com/hslee16/Archy/issues/242) · 2026-07-04 · closed · 1 comment

### MCP surface modernization: adopt 2025-2026 best practices (tracker)

# MCP surface modernization: adopt 2025-2026 best practices

Tracking issue. Driven by an audit of archy's MCP surface against a verified deep-research pass on current MCP best practices (Anthropic engineering guidance + the modelcontextprotocol.io spec, 2025-2026).

## Verdict: yes, the surface is getting messy

archy exposes **19 MCP tools** (~2.5-3k tokens of descriptions always in context) on the official `mcp` SDK FastMCP (`mcp>=1.27.1`, which already supports `annotations` / `title` / `str

[Read the thread](https://github.com/hslee16/Archy/issues/230) · 2026-06-24 · closed · 0 comments

### MCP: standardize the two-mechanism error model (protocol errors vs isError tool results)

## Gap
Error reporting is inconsistent across archy's tools: some return a union with a structured error payload (`archy_diff -> DiffReport | DiffErrorPayload`, `archy_graph -> GraphPayload | GraphTooLargePayload`, `archy_dsm -> ... | DSMErrorPayload`), while others raise. There is no single documented convention an agent can rely on to detect and recover from a failure.

## Best practice (sourced)
MCP defines **two** error-reporting mechanisms, and they are for different cases:
- **Protocol-lev

[Read the thread](https://github.com/hslee16/Archy/issues/229) · 2026-06-24 · closed · 0 comments

### MCP: verify/adopt structuredContent + outputSchema (2025-06-18 structured output)

## Gap / question
archy returns Pydantic models that FastMCP serializes to JSON. The **2025-06-18** spec added structured tool output (`structuredContent` + an optional `outputSchema` on the Tool). It is unclear what archy currently emits on the wire and whether it is taking full advantage.

## Best practice (sourced)
- 2025-06-18 added `structuredContent` (JSON object) plus optional `outputSchema` (JSON Schema); servers that declare `outputSchema` MUST return conforming results and clients SHOU

[Read the thread](https://github.com/hslee16/Archy/issues/228) · 2026-06-24 · closed · 0 comments

### MCP: consolidate overlapping tool clusters (19 -> ~12-13) via mode/lens params

## Gap
The surface has grown to **19 tools** (~2.5-3k tokens of descriptions always in context) with several overlapping clusters:
- **Graph x4:** `archy_graph`, `archy_graph_focus`, `archy_graph_summary`, `archy_dsm`.
- **Refactor x3:** `archy_hotspots`, `archy_high_risk_modules`, `archy_what_to_refactor_next` (the last already FUSES the first two).
- **Impact x2:** `archy_impact`, `archy_affected`.
- **Score/baseline overlap:** `archy_record_baseline` largely duplicates `archy_score(record=Tru

[Read the thread](https://github.com/hslee16/Archy/issues/227) · 2026-06-24 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/hslee16/archy/issues).