playbooks

home / skills / git-fg / thecattoolkit / designing-architecture

designing-architecture skill

/plugins/sys-builder/skills/designing-architecture

This skill helps you design and analyze software architectures using discovery protocols, ADRs, and system design workflows to ensure quality.

npx playbooks add skill git-fg/thecattoolkit --skill designing-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
2.8 KB
---
name: designing-architecture
description: "Applies system architecture and design frameworks for software systems. Provides discovery protocols, system design workflows, architecture decision records (ADRs), and quality evaluation criteria. PROACTIVELY Use when designing new systems, analyzing existing architecture, or making architectural decisions. Do not use for project plan state management, task execution, or phase coordination → see managing-plans skill."
allowed-tools: [Read, Write, Edit, Glob, Grep, TodoWrite]
---

# Architecture Design & Analysis



## Protocol Reference Index

### Discovery & Analysis
- **Protocol**: `references/discovery.md` - Deep discovery workflow (Context Mapping, Requirements, Environment)
- **Protocol**: `references/codebase-discovery.md` - Quick codebase exploration
- **Reference**: `references/quality-checklist.md` - Quality evaluation checklist
- **When to Apply**: MANDATORY before starting any design or analysis task to ensure 100% clarity.

### System Design (Greenfield)
- **Protocol**: `references/system-design.md` - Complete system design workflow
- **When to Apply**: New systems, major features, technology selection

### Architecture Patterns
- **Reference**: `references/architecture-patterns.md` - Design patterns guide
- **When to Apply**: Selecting patterns based on requirements

### Architecture Decision Records
- **Template**: `references/adr-template.md` - ADR template and documentation standards
- **When to Apply**: Documenting significant architectural decisions

**ADR Creation Protocol:**
1. **Auto-increment**: Count existing ADR entries and add 1
2. **Append**: Add to bottom of ADR.md (never delete or modify old entries)
3. **File location**: `.cattoolkit/plan/{project-slug}/ADR.md`
4. **Numbering**: Sequential (ADR-001, ADR-002, etc.)
5. **Append-Only Rule**: Never delete, modify, or reorder entries

**When to Create ADR:**
- Technology stack changes (frameworks, databases)
- Major architectural patterns (auth strategy, state management)
- Breaking API changes (protocol changes, data format changes)
- Infrastructure additions (caching, message queues)
- Significant refactors (directory structure, module organization)

## Workflow Selection

**Protocol Chain:**
1. **Discovery**: ALWAYS start with `references/discovery.md` to gather context.
2. **Analysis/Design**: Based on discovery results:
   - **Greenfield (New System)**: Follow `references/system-design.md`.
   - **Brownfield (Existing System)**: Perform mapping and refactoring analysis.
3. **Documentation**: Document all outcomes with ADRs and diagrams.

## Quality Criteria

Every architecture must address specific quality gates. For the comprehensive evaluation checklist, see `references/quality-checklist.md`.

**Note**: For project plan state management and task execution, use `managing-plans` skill.

Overview

This skill applies proven system architecture and design frameworks to shape software systems, evaluate existing architectures, and document decisions. It provides discovery protocols, end-to-end system design workflows, architecture decision record (ADR) practices, and quality evaluation criteria. Use it proactively when making architectural choices or preparing design deliverables.

How this skill works

Start every engagement with a mandatory discovery workflow to map context, requirements, constraints, stakeholders, and the runtime environment. Based on discovery outcomes the skill selects a workflow: a greenfield system-design path for new systems or a brownfield analysis path for existing systems. It produces ADRs for significant decisions, enforces an append-only ADR practice with sequential numbering, and runs a quality checklist against key quality gates.

When to use it

  • Before designing a new system or major feature (greenfield)
  • When analyzing or refactoring an existing system (brownfield)
  • When choosing or changing core technologies or architecture patterns
  • When documenting breaking API or infrastructure changes
  • Before committing to significant refactors or infra additions

Best practices

  • Always run the full discovery protocol first to ensure clear context and requirements
  • Select architecture patterns based on documented quality attributes and constraints
  • Create an ADR for any decision that affects system behavior, interfaces, or operational model
  • Keep ADRs append-only, sequentially numbered, and stored with project documentation
  • Evaluate designs against the quality checklist (performance, reliability, security, operability) early and iteratively

Example use cases

  • Designing a new microservices platform including data partitioning and service boundaries
  • Evaluating an inherited monolith for strangler-pattern refactor and migration planning
  • Choosing a datastore and caching strategy with documented trade-offs and ADRs
  • Documenting a switch of authentication strategy or introduction of a message queue
  • Running a quality gate review before major release to certify architectural fitness

FAQ

What must I do first when starting a design?

Run the discovery protocol to capture context, stakeholders, requirements, and constraints; this is mandatory before design or analysis.

When should I create an ADR?

Create an ADR for technology stack changes, major patterns, breaking API changes, infrastructure additions, or significant refactors.

How are ADRs managed?

ADRs are append-only, sequentially numbered, and stored with the project documentation so every decision is traceable and immutable.