Skip to content

Architecture Workflow Loop

Intent

Ensure rapid experimentation does not create architectural debt by embedding an explicit architecture audit and refactor step directly inside the development workflow.

Context

This pattern appears in experimentation-heavy systems where features evolve quickly and architectural drift becomes likely.

Observed in:

  • Iterative AI system development
  • Agent-based architectures
  • Continuous refactoring environments

The pressure emerges from a tension between fast feature iteration and long-term architectural stability.

Without an explicit governance mechanism, the system accumulates structural debt.

Agentic profile

  • System shape: multi-agent
  • Orchestration mode: hybrid

Agent-to-agent interaction

  • Present: true
  • Mechanism: shared-state
  • Evidence: src/core/pipeline/context.py#PipelineContext

Tool protocols

  • MCP: absent
  • Tool calling: present
  • Evidence: src/agents/insights/agent.py#generate_insights

Optimisation target

  • Primary: reliability
  • Secondary: developer-velocity
  • Notes: The pattern trades small development friction for long-term system stability.

Simplicity vs autonomy

  • Position: balanced
  • Rationale: The workflow preserves architectural discipline while still allowing rapid experimentation.

Forces

  • Rapid iteration introduces structural drift.
  • Refactors are often postponed when delivery pressure is high.
  • Agent-based architectures amplify coupling risks.
  • Architecture reviews are traditionally periodic rather than continuous.
  • Structural problems compound quickly if not addressed immediately.

Solution

Introduce an architecture governance loop inside the delivery workflow.

Instead of merging changes directly after validation:

  1. Implement the change
  2. Validate behavior
  3. Run an architecture audit
  4. Refactor structural issues
  5. Stabilize and merge

This creates a continuous cycle:

Build → Validate → Audit → Refactor → Stabilize

The architecture audit becomes a mandatory checkpoint before merge, ensuring structural corrections happen immediately.

Operationalisation (CAS Implementation)

This pattern can be operationalised within CAS (Continuous Architecture System) by embedding governance capabilities directly into the delivery workflow.

Mapping to CAS Components

  • Build (Prevent)
  • CAS Skills guide code agents before implementation

  • Examples: select-pattern, define-contract, validate-against-rules

  • Validate

  • Standard test suites (unit, integration)

  • Schema and contract validation for structured outputs

  • Audit (Detect)

  • Automated audit via GitHub Actions or CI pipelines

  • Steps include:

    • Extraction of signals and patterns from code
    • Execution of rules-context-loader
    • Alignment Engine to compare AEM (state) vs AID (intent)

  • Refactor (Correct)

  • Audit outputs generate structured architecture_work
  • Architecture decisions are captured and updated via ADRs

  • Refactors are applied at architectural level, not just code level

  • Stabilize

  • Merge policies enforce governance checkpoints
  • Early stages: non-blocking audit with human-in-the-loop
  • Later stages: blocking conditions for critical violations

Execution Flow

Code Agent → CAS Skills → Code → CI Audit → Architecture Work → ADR → Refactor → Merge

Notes

  • Prevention is lightweight and advisory; detection and correction provide stronger guarantees
  • Governance is applied via rule context (rules-context-loader) rather than embedded in prompts
  • This implementation enables continuous, automated architecture governance in agentic development workflows

Implementation signals

Observable signals this pattern exists:

  • Explicit architecture audit step before merge
  • Refactor commits triggered by architectural violations
  • Workflow documentation referencing architecture checks
  • Audit-driven refactor phases during feature development
  • Architecture-focused test suites validating system structure

Evidence

  • runner-agentic-intelligence/src/agents/orchestrator.py — orchestration refactoring during pipeline migration
  • runner-agentic-intelligence/src/core/pipeline/context.py — typed PipelineContext introduced after architecture audit
  • Weekly learning artefacts documenting audit → refactor cycles
  • Architecture audit reports highlighting violations and structural corrections

Consequences

Benefits

  • Prevents architecture drift during rapid experimentation
  • Surfaces structural problems early
  • Encourages disciplined refactoring
  • Improves long-term system maintainability

Costs

  • Slower merge cycle for individual changes
  • Additional cognitive overhead during development

Failure modes

  • Audits become superficial checklists instead of structural analysis
  • Teams bypass the audit step under delivery pressure
  • Refactor step becomes optional instead of mandatory

Reuse notes

This pattern fits:

  • Systems evolving through continuous experimentation
  • AI and agent-based architectures
  • Small teams maintaining architecture discipline without formal review boards

This pattern does not fit well in:

  • Static systems with infrequent changes
  • Projects with heavy centralized architecture governance

Minimal version:

Build → Validate → Architecture Audit → Merge

Preconditions:

  • Team understands architectural boundaries
  • Audit criteria are clearly defined
  • Refactors are accepted as part of normal delivery

Confidence

Medium

Observed clearly during multiple refactor cycles in the runner intelligence system, but limited validation across additional projects or teams.

⸻