# Architecture Improve

> Use when you want architecture- and pipeline-level optimisation ideas for a repo — find god-nodes, tight coupling, duplicate subsystems, redundant pipeline hops, serial steps that could be parallel, idempotency/retry gaps, un-rehosted data — and have them drawn as `proposed` nodes on an existing architecture-map. Proposals arrive as plain-language cards a non-developer can decide on, and approved…

- **Type:** Skill
- **Install:** `agentstack add skill-martinplarsen-claude-architecture-skills-architecture-improve`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MartinPLarsen](https://agentstack.voostack.com/s/martinplarsen)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MartinPLarsen](https://github.com/MartinPLarsen)
- **Source:** https://github.com/MartinPLarsen/claude-architecture-skills/tree/main/architecture-improve

## Install

```sh
agentstack add skill-martinplarsen-claude-architecture-skills-architecture-improve
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Architecture Improve

Deep-research an architecture-map (`map.js`) for **what to change**, then paint each idea
back onto the map as a `proposed` node carrying a structured proposal. The sibling of
`architecture-cleanup`: map = WHAT exists → cleanup = what to REMOVE → improve = what to CHANGE.

**Core principle — proposals-only.** improve surfaces optimisation ideas and draws them on
the map. It NEVER edits source, opens PRs, or applies a change (ADR-012: only cleanup gets an
execution layer; improve's changes are judgment-heavy refactors, not mechanical removals).

## When to use

- "Optimise the architecture", "improve the pipeline", "where can this be better".
- After mapping (and ideally cleaning) a repo, to plan structural/flow improvements.
- **Not** for line-level perf, micro-optimisation, or product/feature redesign (D4 boundary).
- **Not** for finding dead code to delete — that's `architecture-cleanup`.
- Recommended order: cleanup → improve (don't optimise code you're about to delete).

## Input — map.js (ADR-010)

The input is `/architecture-map/map.js` (`window.MAP_DATA`). If it doesn't exist, build
it first with the `architecture-map` skill, then run improve on the result. If a fresh
`architecture-cleanup` overlay exists, improve reads it (see Cross-skill, ADR-014).

## The two lenses (D4)

Every proposal is tagged with exactly one lens:

- 🏗️ **structure** — coupling, god-nodes (high fan-in + fan-out), duplicate subsystems, layering
  violations, missing seams.
- 🔀 **pipeline** — redundant hops, serial steps that could run in parallel, idempotency/retry
  gaps, data stored as expiring temp URLs instead of re-hosted, missing back-pressure.

## Step 1 — deep research (fan-out, C3 gate)

1. **Ensure the map exists & is fresh.** No `map.js` → build via `architecture-map`. A stale map
   gives stale proposals, so re-map if the repo moved.
2. **Cheap seed signals (deterministic).** Reuse cleanup's topology helper to focus the research —
   it gives per-node degree (god-node = high inbound+outbound), `duplicateGroups` (dup tech), and
   blast-radius:
   ```bash
   node ../architecture-cleanup/analyze-map.mjs /architecture-map/map.js > /tmp/seed.json
   ```
3. **Cost gate (C3) — warn on scale BEFORE firing.** Reader count = number of subsystems on the
   map. If it is **> 8**, tell the user the count + a rough token estimate and wait for a go.
   At/under 8, proceed.
4. **Fan out, one reader per subsystem.** Reuse `architecture-audit`'s Map-phase pattern
   (scout + parallel readers via the Workflow tool / subagents). Each reader carries BOTH lenses
   in its brief and is pre-seeded with `seed.json` hints for its subsystem (high-degree nodes,
   dup groups). One reader per subsystem keeps the agent count = subsystem count.
   Each reader returns candidate proposals: `{problem, change, tradeoff, effort, impact, lens,
   affectedNodes[]}`.

## Step 2 — synthesize & prioritise (Q1)

1. **Dedup & merge** candidate proposals across subsystems (one synthesis pass).
2. **Light verify the big ones.** For high-impact proposals, sanity-check the claim against the
   code before committing it to the map (honesty principle — no plausible-but-wrong proposals).
   This is a check, not a second full fan-out.
3. **Band each proposal** from its `effort` (S/M/L) × `impact` (low/med/high) — **discrete bands,
   never a numeric score** (we have no telemetry; a number would be false precision):

   | Band | Condition |
   |------|-----------|
   | ⚡ **quick win** | impact high · effort S |
   | 🎯 **big bet** | impact high · effort M/L |
   | 🧹 **fill-in** | everything else |
   | ⛔ **skip** | impact low · effort L (surfaced, recommended against) |

## Step 3 — write proposals onto the map

Each proposal becomes a `proposed` node (the change drawn) + edges to the shipped nodes it
affects. The structured `proposal:{}` object lives on the **proposed** node, never on a shipped
node — a field on a shipped node would be dropped by `merge-map.mjs` on the next audit, whereas
proposed nodes/edges survive re-audit (ADR-013).

1. **Git-snapshot the map FIRST (ADR-011).** Make sure `map.js` is committed (or stash-clean) so
   backout is one `git restore`.
2. **Build `proposals.json`** — an array of `{node:{id,label,tech?,engine?,subsystem?},
   proposal:{problem,change,tradeoff,effort,impact,lens}, edges:[{from,to,data}]}`. See helper
   `--selftest` for the exact shape. `id`s must be NEW (a proposed id may not clobber a shipped node).
3. **Apply (additive, idempotent):**
   ```bash
   node apply-proposals.mjs /architecture-map/map.js /tmp/proposals.json > /tmp/map.js \
     && mv /tmp/map.js /architecture-map/map.js
   ```
4. **Refresh the viewer if it predates the proposal panel:**
   `cp ../architecture-map/assets/index.html /architecture-map/`.

## Step 4 — report (Q6)

improve has **no fixed taxonomy** (optimisation is open-ended) — but a fixed proposal shape and
a fixed ordering. Hand the user:

- A header line: `N proposals — X quick wins, Y big bets`.
- **One plain-language card per proposal** (format:
  `../architecture-cleanup/references/finding-card-and-issues.md` — What it is / Why it is an
  improvement / What you gain / Risk, technical detail folded). Grouped by band
  (⚡ quick wins → 🎯 big bets → 🧹 fill-ins → ⛔ skip). The raw problem/change/tradeoff +
  effort/impact + affected nodes + lens live in the folded Evidence block.
- The open command: `open /architecture-map/index.html`. A 💡 **Proposals (N)** toggle
  (on by default) rings the proposed nodes amber; clicking one shows the full proposal block.

## Step 5 — PRD-ready tracker issues (on approval)

When the user approves proposals (per proposal or per band), convert them to issues in the
project's tracker (Linear, GitHub Issues, Jira — via its workflow skill if you have one).
Structure, sub-issue PRD template (Background/Solution/Acceptance criteria/Risk/Evidence),
estimate/label/priority mapping: all in
`../architecture-cleanup/references/finding-card-and-issues.md`. Parent `Improve: 
()` + one sub-issue per approved proposal. Draft the whole batch, show the user titles +
estimates, ONE go creates them. Unapproved proposals stay on the map only. This does NOT
change ADR-012: improve still never executes — the issues are the handoff to whoever builds.

## Cross-skill with cleanup (ADR-014)

If a `removable` overlay is present, improve **reads it and routes around it**:

- **Exclude** removable-flagged nodes from the candidate set — don't optimise code already slated
  for deletion. Report: "N nodes skipped (flagged removable by cleanup)".
- Routing **around** or **replacing** a removable node is fine (additive).
- If a proposal would **build on** a removable node, surface the conflict explicitly — never build
  silently on something being deleted.

## Cost (C3)

Step 1's seed pass is static/cheap. The fan-out warns on scale (reader count > 8) before firing.
There is no removal/execution cost — improve only proposes.

## Helpers

- `apply-proposals.mjs  ` — additive, idempotent write-back of `proposed`
  nodes/edges + `proposal:{}` objects (ADR-011/013). Validates bands + edge endpoints; throws
  rather than write garbage. `--selftest` to verify.
- Reuses `../architecture-cleanup/analyze-map.mjs` for the deterministic seed signals (degree,
  duplicate-tech, blast-radius). No second analysis helper.

## Red flags — STOP

- About to edit source / open a PR / apply a change → don't. improve is proposals-only (C2/ADR-012).
- About to put `proposal` on a shipped node → wrong; it must live on a proposed node (ADR-013).
- About to assign a numeric priority score → wrong; bands only (Q1).
- About to propose a line-level perf tweak or a feature redesign → out of scope (D4).
- About to optimise a node cleanup flagged `removable` → stop; exclude or surface the conflict (ADR-014).
- About to fan out > 8 readers without warning the user → stop, warn first (C3).
- About to create tracker issues without the batch-go → stop (Step 5).
- Report card leads with node-ids/paths instead of plain language → wrong; detail goes in the folded Evidence block.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MartinPLarsen](https://github.com/MartinPLarsen)
- **Source:** [MartinPLarsen/claude-architecture-skills](https://github.com/MartinPLarsen/claude-architecture-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-martinplarsen-claude-architecture-skills-architecture-improve
- Seller: https://agentstack.voostack.com/s/martinplarsen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.