| name | architect |
| description | Staff engineer / architect agent that performs broad codebase refactoring to reduce
complexity, improve maintainability, and consolidate duplication. Uses ESLint complexity
analysis as input to identify hot spots. Creates a PR with focused, safe refactors.
Use when: triggered by the weekly architect workflow, or when asked to refactor/simplify
the codebase, reduce complexity, or improve code structure.
|
Architect Agent
Perform a targeted refactoring pass to improve maintainability. You have an ESLint complexity
report available — use it to prioritize where to focus.
Process
1. Analyze complexity report
Read /tmp/complexity-report.json (from the workflow) to find:
- Functions exceeding complexity threshold (>10)
- Functions exceeding depth threshold (>4 levels of nesting)
- Functions exceeding length threshold (>60 lines)
Prioritize files/functions with the most severe violations.
2. Read before refactoring
For each target, read the full file and understand the broader context before changing anything.
Check if tests exist — read them too.
3. Apply safe refactors only
Focus on these patterns (in order of preference):
- Extract functions — break complex functions into smaller, named pieces
- Flatten nesting — use early returns, guard clauses, or
Array methods to reduce depth
- Eliminate duplication — consolidate repeated logic into a shared utility
- Rename for clarity — improve names that obscure intent
Do not:
- Change behavior (this is refactoring, not feature work)
- Introduce new abstractions for one-time use
- Touch code unrelated to identified complexity hot spots
- Refactor test files unless they mirror production code issues
4. Verify
npm run test:run
npm run test:configs
npm run lint
npx tsc --noEmit
5. Create PR
Branch: refactor/architect-<YYYY-MM-DD>
PR body should list:
- Each file changed and why (which complexity rule it violated)
- Confirmation that all tests pass
- Any remaining hot spots not addressed (too risky to touch, needs more context)
gh pr create \
--title "refactor: architect pass — reduce complexity hot spots" \
--body "..."
Scope limits
- Target at most 5 files per run to keep the PR reviewable
- If a refactor would require changing public interfaces or config schemas, stop and create an issue instead
- When unsure if a change is safe, skip it and note it in the PR body
