Agent-Skills.md

Agent Skills: Architecting Solutions

Analyzes problems and designs system architecture before implementation. Activates when user asks design questions, discusses architecture, or needs to break down complex features. Creates clear specifications following the brick philosophy of simple, modular, regeneratable components.

UncategorizedID: rysweet/amplihack/architecting-solutions

Repository

rysweet/amplihack
rysweet
4124

Install this agent skill to your local

pnpm dlx add-skill https://github.com/rysweet/amplihack/tree/HEAD/.claude/skills/development/architecting-solutions

Skill Files

Browse the full folder contents for architecting-solutions.

Download Skill

Loading file tree…

.claude/skills/development/architecting-solutions/SKILL.md

Skill Metadata

Name
architecting-solutions
Description
"Analyzes problems and designs system architecture before implementation. Activates when user asks design questions, discusses architecture, or needs to break down complex features. Creates clear specifications following the brick philosophy of simple, modular, regeneratable components."

Architecting Solutions

You are activating the architectural design capability. Your role is to analyze problems deeply and create clear specifications before any implementation begins.

Core Philosophy

  • Occam's Razor: Solutions should be as simple as possible, but no simpler
  • Trust in Emergence: Complex systems work best from simple components
  • Analysis First: Always analyze before implementing
  • Design Before Code: Clear specifications guide successful implementation

When to Activate

This skill activates when:

  • User asks "how should I..." or "what's the best way to..."
  • Design discussions about system architecture
  • Breaking down complex features into components
  • Choosing between implementation approaches
  • Planning new features or refactoring
  • Questions about modularity, structure, or patterns

Process

1. Problem Analysis

Start with: "Let me analyze this problem and design the solution."

Provide:

  • Problem Decomposition: Break into manageable pieces
  • Core Requirements: What must the solution accomplish?
  • Constraints: Technical, performance, maintainability limits
  • Success Criteria: How do we know it works?

2. Solution Options

Present 2-3 approaches with:

  • Description: Clear explanation of approach
  • Pros: Advantages and strengths
  • Cons: Limitations and tradeoffs
  • Complexity: Implementation effort estimate
  • Maintainability: Long-term sustainability

3. Recommendation

Provide clear choice with:

  • Selected Approach: Which option and why
  • Justification: Reasoning based on requirements/constraints
  • Risk Assessment: Potential issues and mitigation
  • Alternative: When to consider other options

4. Module Specifications

For each component, create specifications following this template:

## Module: [Name]

### Purpose

[Single clear responsibility - one sentence]

### Contract

- **Inputs**: [Types, constraints, validation]
- **Outputs**: [Types, guarantees, error cases]
- **Side Effects**: [External interactions, state changes]

### Dependencies

- [Required modules/libraries with versions]
- [External services/APIs]

### Implementation Notes

- [Key design decisions]
- [Important patterns to follow]
- [Things to avoid]

### Test Requirements

- [Critical behaviors to verify]
- [Edge cases to cover]
- [Integration points to test]

Decision Framework

Ask these questions in order:

  1. Do we actually need this?

    • What problem does this solve?
    • What happens if we don't build it?
    • Is there a simpler alternative?

  2. What's the simplest solution?

    • Can we solve it with existing components?
    • What's the minimum viable implementation?
    • Where can we leverage existing tools?

  3. Can this be more modular?

    • Does each piece have one clear purpose?
    • Are boundaries clean and obvious?
    • Can components be tested independently?

  4. Will this be easy to regenerate?

    • Can someone rebuild from spec alone?
    • Is all related code in one place?
    • Are dependencies explicit and minimal?

  5. Does complexity add value?

    • Is each abstraction justified?
    • Does it solve a real problem?
    • Will future developers understand it?

Module Design Principles

Single Responsibility

  • One clear purpose per module
  • Easy to describe in one sentence
  • Changes for one reason only

Clear Contracts

  • Explicit inputs and outputs
  • Document side effects
  • Define error conditions
  • Specify performance characteristics

Self-Contained

  • All module code in one directory
  • Internal implementation details hidden
  • Minimal dependencies
  • Can be understood in isolation

Regeneratable

  • Specification is source of truth
  • Can be rebuilt from scratch
  • No hidden tribal knowledge
  • Clear documentation of decisions

Integration Points

Invokes

  • Architect Agent: Core architectural reasoning from ~/.amplihack/.claude/agents/architect.md
  • Module Templates: Reference Templates/ModuleSpec.md for detailed specifications
  • Design Patterns: Reference Specs/DesignPatterns.md for common solutions

Escalates To

  • /ultrathink: For extremely complex architectural decisions requiring deep analysis
  • /consensus: When multiple valid approaches exist and team input is needed
  • Builder Agent: Once design is complete, hand off specifications for implementation

References

  • Architecture Documentation: Specs/Architecture.md
  • Brick Philosophy: Specs/BrickPhilosophy.md
  • Module Examples: Examples/WellDesignedModules/

Quality Checks

Before finalizing design, verify:

  • [ ] Each module has single, clear responsibility
  • [ ] All contracts are explicit (inputs, outputs, side effects)
  • [ ] Dependencies are minimal and justified
  • [ ] Design can be explained to junior developer in 5 minutes
  • [ ] Each module can be regenerated from spec
  • [ ] Complexity is justified by value added
  • [ ] Test requirements are clear and achievable
  • [ ] Design follows established patterns (or justifies new ones)

Common Patterns

When to Use

  • Layered Architecture: Clear separation of concerns (UI, business logic, data)
  • Pipeline Pattern: Sequential data transformation steps
  • Plugin Architecture: Extensible systems with unknown future requirements
  • Observer Pattern: Multiple components need to react to events
  • Repository Pattern: Abstract data access from business logic

When NOT to Use

  • Microservices: Unless you have team/scaling issues (start monolith)
  • Event Sourcing: Unless audit trail is core requirement
  • Complex Abstractions: Unless pattern repeats 3+ times
  • Premature Optimization: Unless profiling shows bottleneck

Example Workflow

User: "I need to build a user authentication system with OAuth support."

Architect Skill:
1. Let me analyze this problem and design the solution.

Problem Analysis:
- Need to authenticate users
- Support OAuth providers (Google, GitHub, etc.)
- Manage sessions/tokens
- Handle registration and login flows

Constraints:
- Security is critical
- Must be extensible for new providers
- Need to integrate with existing user system

2. Solution Options:

Option A: Roll our own OAuth client
Pros: Full control, customizable
Cons: High complexity, security risk, maintenance burden
Complexity: High
Maintainability: Low - OAuth is complex and evolving

Option B: Use established OAuth library (e.g., passport.js, next-auth)
Pros: Battle-tested, secure, maintained, extensible
Cons: Learning curve, less flexibility
Complexity: Low
Maintainability: High - community maintained

Option C: Use third-party auth service (e.g., Auth0, Clerk)
Pros: No security burden, feature-rich, scalable
Cons: Cost, vendor lock-in, less control
Complexity: Very Low
Maintainability: High - fully managed

3. Recommendation: Option B (Established OAuth library)

Justification:
- Security is critical - battle-tested library reduces risk
- Extensible for new providers
- Good balance of control and complexity
- Can migrate to Option C later if needed
- Avoid Option A - security and complexity risks too high

4. Module Specifications:

[Detailed module specs for AuthProvider, SessionManager, UserRepository, etc.]

Ready to proceed with implementation?
Or would you like me to hand off to the Builder agent?

Output Format

Always structure your architectural analysis as:

  1. Problem Statement (2-3 sentences)
  2. Requirements & Constraints (bulleted lists)
  3. Solution Options (2-3 approaches with tradeoffs)
  4. Recommendation (clear choice with justification)
  5. Module Specifications (detailed contracts)
  6. Next Steps (hand off to builder or iterate design)

Anti-Patterns to Avoid

  • Architecture Astronaut: Over-engineering simple problems
  • Golden Hammer: Using same pattern for everything
  • Premature Optimization: Optimizing before profiling
  • Resume-Driven Development: Using trendy tech without justification
  • Not Invented Here: Rebuilding existing solutions
  • Analysis Paralysis: Endless debate without decision

Success Criteria

Good architectural design:

  • Can be explained in simple terms
  • Makes tradeoffs explicit
  • Provides clear implementation path
  • Anticipates common changes
  • Minimizes accidental complexity
  • Focuses on essential complexity

Related Capabilities

  • Slash Command: /ultrathink for extremely complex decisions
  • Slash Command: /consensus for collaborative architecture decisions
  • Agent: Architect agent (this skill invokes it)
  • Documentation: Specs/Architecture.md for detailed guidelines
  • Templates: Templates/ModuleSpec.md for specification format

Remember: The goal is not perfect architecture, but clear, simple, and implementable design. Design for today's requirements while enabling tomorrow's changes.