improve-architecture

Name: improve-architecture
Author: Rune-kit

80stars21forks

How to install improve-architecture?

rune-kit/rune/improve-architecture

$npx -y skills add Rune-kit/rune --skill improve-architecture

Installs into the current project.

Summary

Find architectural friction in a codebase and propose deepening opportunities. Use when user wants to improve architecture, find refactor candidates, consolidate shallow modules, or make a codebase more testable. Outputs scored proposals (depth/leverage/locality) that surgeon and

Files · 1

View on GitHub

SKILL.md

1	# improve-architecture
2
3	## Purpose
4
5	Surface architectural friction in a codebase and propose deepening opportunities — refactors that turn shallow modules into deep ones. Output is structured (numeric scores + JSON proposal payloads) so `surgeon`, `review`, and `audit` can consume it programmatically without re-reading the codebase.
6
7	The goal is testability and AI-navigability: a deep module presents a small interface that hides large machinery, so tests target one surface and future agents can reason about the system without traversing N small wrappers.
8
9	## Vocabulary (controlled — use exactly)
10
11	These eight terms have precise meanings. Banned aliases: "boundary" (overloaded with DDD), "component" (UI-specific), "service" (microservice-specific), "layer" (too generic). See [references/language.md](references/language.md) for full definitions.
12
13	- Module — anything with an interface and an implementation (function, class, package, slice).
14	- Interface — everything a caller must know to use the module: types, invariants, ordering, error modes, config.
15	- Implementation — the code inside.
16	- Depth — leverage at the interface; large behavior behind a small interface.
17	- Seam — where an interface lives; place behavior can be altered without editing in place.
18	- Adapter — concrete thing satisfying an interface at a seam.
19	- Leverage — what callers get from depth.
20	- Locality — what maintainers get from depth.
21
22	## Triggers
23
24	- Called by `cook` Phase 5 (quality gate) when refactor signals appear in scout output
25	- Called by `surgeon` before any deepening session — produces the proposal surgeon executes
26	- Called by `audit` to compute the architecture sub-score
27	- Called by `review` when a reviewer flag mentions "shallow", "wrapper", "indirection"
28	- Manual: `/rune improve-architecture <module-path>`
29
30	## Calls (outbound)
31
32	- `scout` (L2): re-scan target module + callers when input context is stale
33	- `brainstorm` (L2): when the deepened module needs a new interface, hand off in `design-it-twice` mode (see brainstorm v0.6+)
34	- `journal` (L3): record an ADR if the user rejects a candidate with a load-bearing reason
35
36	## Called By (inbound)
37
38	- `cook` (L1): Phase 5 quality gate
39	- `surgeon` (L2): pre-refactor input; consumes the proposal payload
40	- `audit` (L2): Phase 4 architecture sub-score
41	- `review` (L2): when shallow-module flag fires during review
42	- User: manual invocation
43
44	## Cross-Hub Connections
45
46	- `improve-architecture` → `surgeon` — proposal payload feeds surgeon's deepening session
47	- `improve-architecture` ↔ `brainstorm` — when interface needs design-it-twice exploration
48	- `improve-architecture` → `audit` — emits architecture sub-score
49	- `improve-architecture` → `journal` — records ADRs for rejected candidates with load-bearing reasons
50
51	## Inputs
52
53	- Required: target module path (e.g. `src/auth/`) OR signal `codebase.scanned` from a recent scout pass
54	- Optional: existing `CONTEXT.md` (domain glossary, used to name modules in their domain language)
55	- Optional: `docs/adr/` directory (existing ADRs that constrain proposals — do not re-litigate)
56
57	## Executable Steps
58
59	### Step 1 — Read existing context
60
61	Read in order, silently skipping any that don't exist:
62
63	1. `CONTEXT.md` (or `CONTEXT-MAP.md` + per-bounded-context `CONTEXT.md`)
64	2. Relevant `docs/adr/` files
65	3. The target module's source files (use `Glob` to enumerate, cap at 30 files)
66	4. Direct callers of the module (grep for imports / require / use)
67
68	If `CONTEXT.md` is missing, do not flag it — treat as "no domain glossary yet". If an ADR contradicts a candidate you're forming, mark it and only surface the candidate if the friction is genuine enough to warrant ADR revision.
69
70	### Step 2 — Score the candidate(s)
71
72	For each candidate module, compute three numeric scores (1–5) and one verdict (enum):
73
74	\| Metric \| Formula / Rubric \|
75	\|--------\|------------------\|
76	\| Depth \| `clamp_1_5(implementation_complexity / interface_complexity)` — 1 = shallow wrapper, 5 = small interface hides large machine \|
77	\| Leverage \| `clamp_1_5(num_callers * unique_use_cases / interface_method_count)` — 1 = thin caller benefit, 5 = many callers, fewer methods to learn \|
78	\| Locality \| `clamp_1_5(code_concentration_index)` — 1 = logic spread across N callers, 5 = logic concentrated in one place \|
79	\| Deletion test \| enum: `vanish` (was pass-through) \\| `concentrate` (was earning keep) \\| `redistribute` (mixe

People who liked this also viewed

6 picks

Type

improve-architecture

80stars21forks

View on GitHub

How to install improve-architecture?

rune-kit/rune/improve-architecture

$npx -y skills add Rune-kit/rune --skill improve-architecture

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# improve-architecture
2
3	## Purpose
4
5	Surface architectural friction in a codebase and propose deepening opportunities — refactors that turn shallow modules into deep ones. Output is structured (numeric scores + JSON proposal payloads) so `surgeon`, `review`, and `audit` can consume it programmatically without re-reading the codebase.
6
7	The goal is testability and AI-navigability: a deep module presents a small interface that hides large machinery, so tests target one surface and future agents can reason about the system without traversing N small wrappers.
8
9	## Vocabulary (controlled — use exactly)
10
11	These eight terms have precise meanings. Banned aliases: "boundary" (overloaded with DDD), "component" (UI-specific), "service" (microservice-specific), "layer" (too generic). See [references/language.md](references/language.md) for full definitions.
12
13	- Module — anything with an interface and an implementation (function, class, package, slice).
14	- Interface — everything a caller must know to use the module: types, invariants, ordering, error modes, config.
15	- Implementation — the code inside.
16	- Depth — leverage at the interface; large behavior behind a small interface.
17	- Seam — where an interface lives; place behavior can be altered without editing in place.
18	- Adapter — concrete thing satisfying an interface at a seam.
19	- Leverage — what callers get from depth.
20	- Locality — what maintainers get from depth.
21
22	## Triggers
23
24	- Called by `cook` Phase 5 (quality gate) when refactor signals appear in scout output
25	- Called by `surgeon` before any deepening session — produces the proposal surgeon executes
26	- Called by `audit` to compute the architecture sub-score
27	- Called by `review` when a reviewer flag mentions "shallow", "wrapper", "indirection"
28	- Manual: `/rune improve-architecture <module-path>`
29
30	## Calls (outbound)
31
32	- `scout` (L2): re-scan target module + callers when input context is stale
33	- `brainstorm` (L2): when the deepened module needs a new interface, hand off in `design-it-twice` mode (see brainstorm v0.6+)
34	- `journal` (L3): record an ADR if the user rejects a candidate with a load-bearing reason
35
36	## Called By (inbound)
37
38	- `cook` (L1): Phase 5 quality gate
39	- `surgeon` (L2): pre-refactor input; consumes the proposal payload
40	- `audit` (L2): Phase 4 architecture sub-score
41	- `review` (L2): when shallow-module flag fires during review
42	- User: manual invocation
43
44	## Cross-Hub Connections
45
46	- `improve-architecture` → `surgeon` — proposal payload feeds surgeon's deepening session
47	- `improve-architecture` ↔ `brainstorm` — when interface needs design-it-twice exploration
48	- `improve-architecture` → `audit` — emits architecture sub-score
49	- `improve-architecture` → `journal` — records ADRs for rejected candidates with load-bearing reasons
50
51	## Inputs
52
53	- Required: target module path (e.g. `src/auth/`) OR signal `codebase.scanned` from a recent scout pass
54	- Optional: existing `CONTEXT.md` (domain glossary, used to name modules in their domain language)
55	- Optional: `docs/adr/` directory (existing ADRs that constrain proposals — do not re-litigate)
56
57	## Executable Steps
58
59	### Step 1 — Read existing context
60
61	Read in order, silently skipping any that don't exist:
62
63	1. `CONTEXT.md` (or `CONTEXT-MAP.md` + per-bounded-context `CONTEXT.md`)
64	2. Relevant `docs/adr/` files
65	3. The target module's source files (use `Glob` to enumerate, cap at 30 files)
66	4. Direct callers of the module (grep for imports / require / use)
67
68	If `CONTEXT.md` is missing, do not flag it — treat as "no domain glossary yet". If an ADR contradicts a candidate you're forming, mark it and only surface the candidate if the friction is genuine enough to warrant ADR revision.
69
70	### Step 2 — Score the candidate(s)
71
72	For each candidate module, compute three numeric scores (1–5) and one verdict (enum):
73
74	\| Metric \| Formula / Rubric \|
75	\|--------\|------------------\|
76	\| Depth \| `clamp_1_5(implementation_complexity / interface_complexity)` — 1 = shallow wrapper, 5 = small interface hides large machine \|
77	\| Leverage \| `clamp_1_5(num_callers * unique_use_cases / interface_method_count)` — 1 = thin caller benefit, 5 = many callers, fewer methods to learn \|
78	\| Locality \| `clamp_1_5(code_concentration_index)` — 1 = logic spread across N callers, 5 = logic concentrated in one place \|
79	\| Deletion test \| enum: `vanish` (was pass-through) \\| `concentrate` (was earning keep) \\| `redistribute` (mixe

People who liked this also viewed

6 picks

Type