architect

Files (7)

• SKILL.md
• analysis-procedure.md · references/
• diagram-guide.md · references/
• patterns.md · references/
• quality-attributes.md · references/
• adr-template.md · templates/
• tradeoff-matrix.md · templates/

SKILL.md (first lines)

# Software Architecture Skill

> Use this skill when making architectural decisions, reviewing system design, analyzing codebase structure, generating architecture diagrams, or evaluating pattern fitness for a project.


KNOWLEDGE_PATH: $HOME/github/teaglebuilt/knowledge

## Procedures

This skill provides five core capabilities. Load the relevant resource before executing.

### 1. Analyze Codebase Architecture

When asked to assess or understand an existing codebase's architecture:

1. Read `references/analysis-procedure.md` for the full analysis playbook
2. Map the project structure, entry points, and dependency graph
3. Identify the dominant patterns in use (layered, hexagonal, vertical slice, etc.)
4. Measure coupling and cohesion indicators
5. Produce a structured assessment with findings and recommendations

**Key commands to run:**
```bash
# Dependency/import analysis (JS/TS)
grep -rn "^import\|^from\|require(" --include="*.ts" --include="*.tsx" --include="*.js" | head -200

# Package dependency graph (monorepo)
cat package.json | jq '.dependencies, .devDependencies'
find . -name "package.json" -not -path "*/node_modules/*" -exec jq '{name: .name, deps: .dependencies}' {} \;

# Module boundary detection
find . -name "index.ts" -o -name "index.js" | grep -v node_modules | sort

# Circular dependency check (if tool available)
npx madge --circular --extensions ts,tsx src/

# Python projects
grep -rn "^import\|^from" --include="*.py" | head -200
cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null

# Go projects
grep -rn "^import" --include="*.go" | head -200
cat go.mod
```

### 2. Evaluate Architecture Options

When comparing patterns or making a structural decision:

1. Read `references/patterns.md` for the pattern decision matrices
2. Read `references/quality-attributes.md` for the scoring framework
3. Identify the top 3-5 quality attributes that matter most for this project
4. Score 2-3 candidate architectures against those attributes
5. Produce a tradeoff analysis using `templates/tradeoff-matrix.md`

### 3. Generate Architecture Decision Record (ADR)

When a decision needs to be documented:

1. Read `templates/adr-template.md`
2. Read any documentation in `docs/` folder that applies to the input.
3. Fill in all sections: context, decision drivers, considered options, decision outcome, consequences
4. Save to the project's ADR directory (typically `docs/adr/` or `.docs/architecture/decisions/`)
5. Name with sequential numbering: `NNNN-short-description.md`

### 4. Generate Architecture Diagrams

When visualizing architecture:

1. Read `references/diagram-guide.md` for C4, sequence, and deployment diagram patterns
2. Use Mermaid syntax for all diagrams
3. Start at the appropriate C4 level:
   - **Context** — System and its external actors/systems
   - **Container** — High-level technical building blocks
   - **Component** — Internal structure of a container
   - **Code** — Class/module level (rarely needed)
4. Include a legend and brief description with each diagram

### 5. Design New Architecture

When designing from scratch or planning a migration:

1. Read `references/patterns.md` for pattern options
2. Read `references/quality-attributes.md` for prioritization
3. Read `references/analysis-procedure.md` section on migration strategies (if migrating)
4. Load any relevant **domain references** (see below)
5. Follow this sequence:
   - Clarify requirements and constraints (ask if not provided)
   - Identify bounded contexts / domain boundaries
   - Select structural pattern(s)
   - Select communication pattern(s)
   - Select data pattern(s)
   - Define deployment strategy
   - Document with ADR + diagrams
   - Define fitness functions to protect architectural intent

---

## Resource Routing

Always log to the console which resources are being used.

### Universal Frameworks

| Task | Resource to Read |
|------|-----------------|
| Analyzing existing code | `references/analysis-procedure.md` |
| Comparing patterns | `references/patterns.md` |
| Scoring options | `references/quality-attributes.md` |
| Creating diagrams | `references/diagram-guide.md` |
| Documenting decisions | `templates/adr-template.md` |
| Comparing options side-by-side | `templates/tradeoff-matrix.md` |

### Skill Reference

Always consider using skills that are relevant any way and always show which skills are being used.

### Domain References

From teaglebuilt/skillz, MIT.

More from teaglebuilt/skillz