refine-architecture

Automate structured architecture reviews with multi-reviewer analysis of .goodplan/architecture files.

Updated Aug 27, 2026

Search Tags:#automation #architecture #refinement #decisions #review #epic #subsystems

Ready to run

npx skills add https://github.com/ian97531/goodplan --skill refine-architecture

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: refine-architecture
Source: https://github.com/ian97531/goodplan/tree/main/skills/refine-architecture
Command: npx skills add https://github.com/ian97531/goodplan --skill refine-architecture

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This skill automates architecture refinement by orchestrating specialized reviewers to improve module depth, boundaries, and alignment with decisions.

Core Features & Use Cases

Spawns Software Architecture + Holistic reviewers for architecture assessment and uses decisions to ground context.
Iteratively refines the active epic's architecture directory, backing up before changes and tracking progress across rounds.
Enforces governance: loads decisions, maturity conventions, and reviewer criteria; stops when quality thresholds are met.

Quick Start

Start the refinement workflow on the active epic by invoking the refine-architecture command with no arguments.

Frequently Asked Questions about refine-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I automate architecture review and refinement for an active epic?▼

Automate architecture refinement by spawning multiple reviewers to iteratively analyze and improve module depth and boundaries. The workflow orchestrates specialized assessments against your active epic's architecture files until quality thresholds are met.

What is an iterative architecture refinement workflow?▼

Iterative architecture refinement is a cyclic process that applies specialized reviewers to assess design files, back up changes, and track progress across up to eight rounds. It enforces governance by loading decisions and maturity conventions to guide structured improvements.

Do I need existing architecture files and decisions to run an automated architecture review?▼

Yes, automated architecture reviews require a repository of .goodplan/architecture files and an active epic. The workflow enforces these prerequisites and loads existing decisions and maturity conventions to ground the reviewer context before making any changes.

How does multi-reviewer architecture assessment improve subsystem boundaries?▼

Multi-reviewer architecture assessment improves subsystem boundaries by spawning Software Architecture and Holistic reviewers simultaneously. This dual perspective grounds the analysis in project decisions and enforces governance criteria to iteratively refine module depth until quality thresholds are satisfied.

What are the limitations of automated architecture refinement iterations?▼

Automated architecture refinement is limited to a maximum of eight iterations per run. The process automatically stops when quality thresholds are met, generating a final refinement report, and requires existing .goodplan/architecture files to function correctly.

What's the best way to orchestrate structured architecture reviews for software design?▼

The best way to orchestrate structured architecture reviews is to invoke an automated refinement command that handles reviewer spawning, backup creation, and progress tracking. This enforces governance and applies maturity conventions to generate a final refinement report.