jupes/agent-forge-harness / .agents/skills/improve-codebase-architecture
improve-codebase-architecture
VerifiedIdentify architectural friction and compare refactoring opportunities. Use for architecture assessment before selecting an implementation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| references/DEEPENING.md | markdown | 4.2 KB |
| references/INTERFACE-DESIGN.md | markdown | 2.5 KB |
| references/LANGUAGE.md | markdown | 2.6 KB |
SKILL.md
View on GitHub---
name: improve-codebase-architecture
description: Identify architectural friction and compare refactoring opportunities. Use for architecture assessment before selecting an implementation.
---
# Improve Codebase Architecture
Use this skill to find **deepening opportunities**: refactors that turn shallow **Modules** into deeper ones by putting more useful behavior behind a smaller, clearer **Interface**.
The output is candidates and a guided design conversation. Do not refactor, create a new **Interface**, or rewrite production code until the user selects a candidate and asks for implementation.
## Required Vocabulary
Use these terms exactly: **Module**, **Interface**, **Implementation**, **Depth**, **Seam**, **Adapter**, **Leverage**, and **Locality**. Do not replace them with "component," "service," "API," or "boundary." See [references/LANGUAGE.md](references/LANGUAGE.md).
Principles: run the **deletion test**; treat the **Interface** as the test surface; one **Adapter** is a hypothetical **Seam** and two **Adapters** make it real.
## Agent Forge Context
Load existing context first:
1. `knowledge/_shared.yaml`.
2. Relevant `knowledge/repos/*.yaml` for domain language and repo patterns.
3. Active Beads issue context, including `design:` and `worklog:` comments.
4. Existing ADRs when the repo already has them.
If knowledge or ADR files are absent, proceed silently. Do not create `CONTEXT.md`, ADRs, knowledge YAML, or Beads issues up front. Beads is the default place for durable decisions and follow-up work unless the user explicitly asks otherwise.
## Process
### 1. Explore Organically
Walk the codebase with focused searches, file reads, and exploration agents when the scope is broad. Note where understanding becomes expensive:
- Understanding one concept requires bouncing between many small **Modules**.
- A **Module** is shallow: its **Interface** is nearly as complex as its **Implementation**.
- Pure functions exist only for testability while real bugs hide in call choreography, with poor **Locality**.
- Tightly-coupled **Modules** leak across **Seams**.
- Code is untested or hard to test through its current **Interface**.
Apply the **deletion test** to suspected shallow **Modules**. A strong candidate is one where deletion would spread complexity across callers instead of making it disappear.
### 2. Present Candidates
Present a numbered list. For each candidate include:
- **Files/Modules** - files and **Modules** involved.
- **Problem** - why the current architecture causes friction.
- **Solution** - what would change in plain English.
- **Benefits** - **Leverage**, **Locality**, and test impact.
Use domain language from `knowledge/` and Beads with the architecture vocabulary. If a candidate conflicts with an ADR or Beads `design:` decision, surface it only when real friction justifies revisiting that decision. Do not propose new **Interfaces** yet. End by asking: "Which of these would you like to explore?"
### 3. Grilling Loop
After the user chooses a candidate, ask through constraints before proposing implementation: what behavior belongs behind the deepened **Interface**, where the **Seam** should live, which dependencies fit [references/DEEPENING.md](references/DEEPENING.md), what callers should stop knowing, and which tests should survive internal refactors.
Record durable decisions in Beads with `design:` or `worklog:` comments. If follow-up implementation work appears, create or suggest Beads issues with priority. If the user rejects a candidate for a load-bearing reason, ask whether to record it in Beads or an existing ADR mechanism.
### 4. Design Interfaces Only After Selection
When the user wants alternatives for the selected candidate, hand off to [references/INTERFACE-DESIGN.md](references/INTERFACE-DESIGN.md). That workflow compares multiple possible **Interfaces** only after candidate selection.
## Completion
Each candidate cites observed code friction and expected behavioral benefits. Record the selected candidate's decisions and unresolved constraints before handoff.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |