Skip to content

jupes/agent-forge-harness / .agents/skills/improve-codebase-architecture

improve-codebase-architecture

Verified

Identify architectural friction and compare refactoring opportunities. Use for architecture assessment before selecting an implementation.

FileKindSize
SKILL.mdskill md4.0 KB
references/DEEPENING.mdmarkdown4.2 KB
references/INTERFACE-DESIGN.mdmarkdown2.5 KB
references/LANGUAGE.mdmarkdown2.6 KB
---
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.
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall