Agent-Skills.md

Agent Skills: MANDATORY RULES: VIOLATION IS FORBIDDEN

Software architecture workflow that diagnoses architecture

UncategorizedID: infinite-loop-factory/app-factory/architecture

Repository

infinite-loop-factory/app-factory
infinite-loop-factoryLicense: AGPL-3.0
96

Install this agent skill to your local

pnpm dlx add-skill https://github.com/infinite-loop-factory/app-factory/tree/HEAD/.codex/skills/architecture

Skill Files

Browse the full folder contents for architecture.

Download Skill

Loading file tree…

.codex/skills/architecture/SKILL.md

Skill Metadata

Name
architecture
Description
Software architecture workflow that diagnoses architecture problems, selects the right analysis method, compares options, synthesizes stakeholder input, and produces a recommendation, review, or ADR

MANDATORY RULES: VIOLATION IS FORBIDDEN

  • Response language follows language setting in .agents/oma-config.yaml if configured.
  • NEVER skip steps. Execute from Step 1 in order.
  • Do NOT write implementation code or task plans in this workflow. Hand off to /plan after the architecture decision is made.
  • You MUST use MCP tools throughout the workflow.
    • Use code analysis tools (get_symbols_overview, find_symbol, find_referencing_symbols, search_for_pattern) to inspect the current architecture.
    • Use memory tools (write/edit) to record architecture outputs.
    • Memory path: configurable via memoryConfig.basePath (default: .serena/memories)
    • Tool names: configurable via memoryConfig.tools in .agents/mcp.json
    • Do NOT use raw file reads or grep as substitutes when MCP tools are available.

Vendor note: This workflow executes inline. Use .agents/skills/oma-architecture/SKILL.md and its resources as the primary reference for method selection, stakeholder synthesis, and output format.

L1 Decision Events

Use the oma_emit helper documented in .agents/skills/_shared/runtime/event-spec.md before required L1 decision checkpoints. The helper wraps oma state:emit.

Step 1: Frame the Decision

Clarify what kind of architecture work this is:

  • new architecture recommendation
  • review of an existing architecture
  • structural tradeoff analysis
  • investment prioritization
  • ADR authoring

State explicitly:

  • the decision or pain point
  • constraints
  • quality attributes
  • non-goals

If the problem is vague, start in Diagnostic Mode.

Step 2: Analyze the Existing System

// turbo Use MCP code analysis tools to understand the current architecture:

  • get_symbols_overview for project structure and boundaries
  • find_symbol and find_referencing_symbols for ownership and coupling
  • search_for_pattern for integration points, layering, and recurring pain points

Summarize:

  • key modules/services
  • boundary and ownership model
  • current coupling points
  • likely architecture risks

Step 3: Select the Method

Choose the lightest sufficient method by reading:

  • .agents/skills/oma-architecture/resources/methodology-selection.md

Valid modes:

  • Diagnostic
  • Recommendation
  • Design-Twice
  • ATAM-style
  • CBAM-style
  • ADR

State the selected mode and why it fits better than heavier alternatives.

Step 4: Run the Analysis

Execute the selected method using:

  • .agents/skills/oma-architecture/resources/execution-protocol.md
  • .agents/skills/oma-architecture/resources/output-templates.md

Requirements:

  • compare at least two materially different options for any significant structural decision
  • remain cost-aware: implementation cost, operational cost, team complexity, future change cost
  • distinguish architecture concerns from visual design, task planning, debugging, and Terraform implementation

Step 5: Consult Stakeholders Only If Justified

For cross-cutting decisions, read:

  • .agents/skills/oma-architecture/resources/stakeholder-synthesis.md

Consult only the agents that matter to the decision:

  • oma-pm for business scope and priorities
  • oma-backend for service/API/domain tradeoffs
  • oma-db for data ownership and consistency
  • oma-tf-infra for deployment and operational architecture
  • oma-qa for security, performance, and testability risks
  • oma-frontend / oma-mobile for client complexity and integration impact

Do not turn consultation into consensus theater. Synthesize and recommend explicitly.

Step 6: Present the Recommendation

Present:

  • problem framing
  • selected method
  • options or scenarios reviewed
  • stakeholder perspectives, if any
  • recommendation
  • risks
  • assumptions
  • validation steps

If the decision remains user-owned, present the options with clear tradeoffs rather than a vague summary.

Step 7: Save the Artifact and Hand Off

// turbo Save the architecture artifact to .agents/results/architecture/.

Suggested filenames:

  • architecture-recommendation-<topic>.md
  • architecture-review-<topic>.md
  • adr-<topic>.md
  • cbam-<topic>.md

Emit and verify the required ADR/architecture completion decision:

oma_emit "decision.made" '{"subject":"architecture.adr-complete","decision":"Use the completed architecture recommendation or ADR as the handoff basis.","rationale":"The architecture artifact captures the selected option, tradeoffs, risks, and validation steps."}'
oma state:verify --workflow architecture --checkpoint adr-complete

Then guide the next step:

  • if approved and implementation is next: suggest /plan
  • if the issue is actually debugging or QA, redirect to /debug or /review