From upfront
Execute an architecture evolution plan phase by phase — restructuring only, tests verified at phase boundaries
How this skill is triggered — by the user, by Claude, or both
Slash command
/upfront:re-architectThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are executing an architecture evolution plan. This is **restructuring only** — no new features, no behavior changes, no new tests. Existing tests must pass at the end of each phase.
You are executing an architecture evolution plan. This is restructuring only — no new features, no behavior changes, no new tests. Existing tests must pass at the end of each phase.
The key difference from /upfront:build: tests WILL break during a phase as you move files and update imports. That's expected. You only verify at phase boundaries, not per-edit. The post-edit hook is NOT installed for re-architect runs.
The user provides a path to an evolution doc (e.g., specs/ARCHITECTURE-EVOLUTION.md), or it's detected automatically if only one exists.
Read it fully. Understand the priority order, the constraints, and what each phase changes.
[████████░░░░░░░░░░░░░░░░] 2/5 — Extract auth from core package
Moving: internal/core/auth.go, internal/core/auth_test.go → internal/auth/
Updating: [N] import paths across [M] files
Work through the phase's changes:
Do this methodically — move one module at a time, update all references, then move the next. Don't move everything at once and hope for the best.
Run the full build and test suite:
[project's build command]
[project's test command]
If tests pass: Phase complete. Commit and announce:
refactor([area]): [phase N]/[total] [description]
Architecture evolution: specs/ARCHITECTURE-EVOLUTION.md
If tests fail: Fix the failures. These should only be import path issues or reference updates you missed. If a test failure indicates a behavioral change, you've done something wrong — revert and re-approach.
If build fails: Same — should only be missing imports or moved references. Fix them.
After each phase, update specs/ARCHITECTURE.md to reflect the new structure. The architecture doc must always match reality.
[████████████████░░░░░░░░] 3/5 — Layer extraction ✓
Tests: [N] passing
Build: clean
ARCHITECTURE.md: updated
Proceeding to Phase 4...
Auto-proceed between phases (no manual verification needed — this is restructuring, not new behavior). Pause only if a phase fails verification.
specs/ARCHITECTURE.md with the final state and "Last reviewed" dateAppend to specs/LEARNINGS.md:
## [date] — Architecture evolution
**What changed:** [summary of phases executed]
**Surprises:** [hidden couplings found, unexpected dependencies, things that were harder to move than expected]
**What the agent got wrong:** [if any phases needed multiple attempts, what went wrong]
For each phase that made a structural choice, append to specs/DECISIONS.md:
## [date] — Restructuring: [phase description]
**Decision:** [what was moved/split/extracted]
**Rationale:** [why this structure is better]
Tell the user:
/upfront:architect again in 3-5 features to check for drift."If a phase's verification fails more than 3 times with the same error, stop:
Stuck: Phase [N] verification has failed 3 times.
Error: [what keeps failing]
This might indicate a behavioral dependency on the old structure.
Options:
a) I investigate the dependency and adjust the approach
b) Skip this phase and continue with the rest
c) You look at this manually
npx claudepluginhub thinkupfront/upfront --plugin upfrontImproves architecture incrementally by fixing circular dependencies, high coupling, god files, boundary violations, and unclear module structures without full migration. Scans and measures before/after.
Guides architectural decisions including refactoring, module restructuring, dependency management, component extraction, and code organization following SOLID principles and layered architecture.
Autonomous comprehensive refactoring through a three-phase pipeline: tactical cleanup, architectural restructuring, then final tactical pass.