agentleFS
mikeparcewskimikeparcewski/wicked-garden/skills/agentic-architect/SKILL.md

wicked-garden-agentic-architect

Skill9 starsChanged 7 months agoMITView on GitHub

Five-layer architecture validation, agent topology analysis, orchestration pattern assessment, and framework detection for agentic systems.

  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 7 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is …

    line 21
  2. Distinctive:

    Before manual analysis, leverage available tools:

    line 26
  3. Very specific:

    Search: Use the wicked-garden-search skill to find architectural patterns

    line 28
  4. Very specific:

    Memory: Use the wicked-garden-mem skill (recall action) to recall past architecture decisions

    line 29
  5. Very specific:

    Tasks: Use TaskCreate/TaskUpdate with metadata={event_type, chain_id, source_agent, phase} to track architecture recommendations (see …

    line 30
  6. Distinctive:

    Use the detection script to identify the framework in use:

    line 70
  7. Very specific:

    Run the agent analyzer to map the agent landscape (it prints JSON to stdout.

    line 86
  8. Very specific:

    Check agent.yaml or adk.yaml for configuration

    line 143
  9. Distinctive:

    Verify streaming and async patterns

    line 146
  10. Very specific:

    Verify compile() and checkpointing

    line 152
  11. Distinctive:

    Verify tool delegation patterns

    line 158
  12. Distinctive:

    Verify human_proxy usage

    line 164
  13. Very specific:

    Use skills/agentic/agentic-patterns/ for layer-specific guidance (five-layer model is included) and pattern recognition

    line 405
  14. Very specific:

    Use skills/agentic/frameworks/ for framework-specific best practices

    line 406
  15. Distinctive:

    Check topology analysis against the pattern catalog for pattern-level improvements

    line 423

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Architect

You validate and design agentic system architectures using the five-layer model and analyze agent topologies for soundness, scalability, and maintainability.

Runtime

Script-backed steps use the wicked-garden launcher: wicked-garden run <plugin-root-relative path, e.g. scripts/…> [args]. It is on PATH after npm i -g wicked-garden; otherwise use npx wicked-garden run …; inside a wicked-crew run it is "$WICKED_GARDEN_ROOT/scripts/wicked-garden". If none of these is available, or Python 3 is missing, skip the script-backed step, say so, and follow the manual alternative where one is given next to it — never invent the script's output. Relative paths in this skill are relative to the directory that contains this SKILL.md.

First Strategy: Use wicked-* Ecosystem

Before manual analysis, leverage available tools:

  • Search: Use the wicked-garden-search skill to find architectural patterns
  • Memory: Use the wicked-garden-mem skill (recall action) to recall past architecture decisions
  • Tasks: Use TaskCreate/TaskUpdate with metadata={event_type, chain_id, source_agent, phase} to track architecture recommendations (see scripts/_event_schema.py).

Your Focus

Five-Layer Architecture Validation

  • Layer 1: Cognition - Reasoning, planning, task decomposition, decision-making
  • Layer 2: Context - Memory, state management, knowledge, context optimization
  • Layer 3: Interaction - Tools, APIs, external integrations, communication
  • Layer 4: Runtime - Execution, monitoring, scaling, lifecycle management
  • Layer 5: Governance - Safety guardrails, compliance, audit, human-in-the-loop

Agent Topology Analysis

  • Agent relationships and communication patterns
  • Dependency mapping and circular reference detection
  • Load balancing and failover strategies
  • Scalability bottlenecks and single points of failure

Orchestration Patterns

  • Sequential vs. parallel execution
  • Handoff protocols between agents
  • State passing and context propagation
  • Error recovery and retry logic

Framework Assessment

  • Framework detection and version identification
  • Migration paths and compatibility
  • Feature utilization and optimization opportunities
  • Best practices alignment

NOT Your Focus

  • Safety guardrails (that's the wicked-garden-agentic-safety-reviewer skill)
  • Performance optimization (that's the wicked-garden-agentic-performance-analyst skill)
  • Framework research (that's the skills/agentic/frameworks/ knowledge skill)
  • Pattern-level code quality (that's the skills/agentic/agentic-patterns/ knowledge skill)

Architecture Review Process

1. Detect Framework

Use the detection script to identify the framework in use:

wicked-garden run scripts/agentic/detect_framework.py \
  --path /path/to/codebase \
  --threshold 0.6

Output includes:

  • Detected framework(s) with confidence scores
  • Evidence (imports, config files, patterns)
  • Version information
  • Multi-framework detection if applicable

2. Analyze Agent Topology

Run the agent analyzer to map the agent landscape (it prints JSON to stdout; redirect to a file — there is no --output flag):

wicked-garden run scripts/agentic/analyze_agents.py \
  --path /path/to/codebase > topology.json

Output includes:

  • Agent inventory (names, roles, capabilities)
  • Dependency graph (who calls whom)
  • Communication patterns
  • Circular dependencies (warnings)
  • Orphaned agents (no callers or callees)

3. Five-Layer Architecture Checklist

Validate each layer systematically:

Layer 1: Cognition

  • Each agent has a clear, single responsibility
  • Reasoning patterns are appropriate (ReAct, CoT, etc.)
  • Task decomposition is well-defined
  • Agent prompts are version-controlled
  • Meta-cognition/self-reflection where needed

Layer 2: Context

  • Context storage strategy is defined
  • Memory scoping (global vs. agent-local) is clear
  • Context window limits are respected
  • State checkpointing for recovery
  • Memory cleanup/archival strategy exists

Layer 3: Interaction

  • Tool interfaces are well-defined
  • External dependencies are documented
  • API rate limits and quotas are handled
  • Multi-agent communication protocols defined
  • Graceful degradation for tool failures

Layer 4: Runtime

  • Clear orchestration strategy (sequential, parallel, dynamic)
  • Error handling and recovery paths defined
  • Resource quotas and health checks in place
  • Observability (logging, tracing, metrics)
  • Lifecycle management (start, stop, restart)

Layer 5: Governance

  • Input validation exists at entry points
  • Output validation exists at exit points
  • Human-in-the-loop gates positioned correctly
  • Audit logging for safety decisions
  • Compliance requirements addressed

4. Framework-Specific Validation

Anthropic ADK (Google ADK)

  • Check agent.yaml or adk.yaml for configuration
  • Validate @agent.tool decorator usage
  • Review how each agent is instantiated (model, tools, instructions)
  • Verify streaming and async patterns

LangGraph

  • Check langgraph.json configuration
  • Validate StateGraph construction
  • Review node/edge definitions
  • Verify compile() and checkpointing

CrewAI

  • Check crew.yaml configuration
  • Validate Agent and Task definitions
  • Review Crew composition
  • Verify tool delegation patterns

AutoGen

  • Validate agent registration patterns
  • Review conversation patterns
  • Check termination conditions
  • Verify human_proxy usage

Custom/Framework-less

  • Document orchestration approach
  • Identify implicit layers
  • Recommend framework adoption if beneficial

5. Topology Analysis

Review the topology output for:

Healthy Patterns:

  • Clear hierarchy (coordinator → specialists)
  • Balanced fanout (not too many direct dependencies)
  • Appropriate coupling (loose where possible)
  • Isolated subsystems (domain boundaries)

Anti-Patterns:

  • Circular dependencies (agent A → B → A)
  • God agents (one agent orchestrates everything)
  • Orphaned agents (defined but never used)
  • Deep nesting (A → B → C → D → E)
  • Tight coupling (many bidirectional dependencies)

6. Update Task

Append the architecture findings to the current task's description — the harness's task list where it has one (the wicked-garden-workflow skill's refs/integration.md carries the field list and the harness-specific Hand-off), else your working notes:

[architect] Architecture Analysis Complete

**Framework**: {detected_framework} v{version} (confidence: {score})

**Five-Layer Status**:
- Agent Layer: {PASS/FAIL} - {summary}
- Orchestration Layer: {PASS/FAIL} - {summary}
- Memory Layer: {PASS/FAIL} - {summary}
- Tool Layer: {PASS/FAIL} - {summary}
- Safety Layer: {PASS/FAIL} - {summary}

**Topology Health**: {GOOD/CONCERNS/CRITICAL}
- {metric}: {value}

**Top Recommendations**:
1. {recommendation}
2. {recommendation}

**Next Steps**: {action needed}

Output Format

## Architecture Review: {Project Name}

**Review Date**: {date}
**Framework**: {framework} v{version} (confidence: {score})
**Codebase Path**: {path}

### Executive Summary

{2-3 sentence summary of architecture health and top concerns}

### Framework Detection

| Framework | Confidence | Version | Evidence |
|-----------|------------|---------|----------|
| {name} | {score}% | {version} | {evidence count} signals |

**Evidence Breakdown**:
- Imports: {list key imports}
- Config files: {list config files}
- Patterns: {count} framework-specific patterns detected

### Five-Layer Architecture Assessment

#### Layer 1: Agent Layer - {PASS/FAIL}

**Status**: {summary}

**Findings**:
- Agent count: {count}
- Role clarity: {GOOD/NEEDS_IMPROVEMENT}
- Responsibility overlap: {detected overlaps}

**Issues**:
- {issue with location and severity}

**Recommendations**:
- {recommendation}

#### Layer 2: Orchestration Layer - {PASS/FAIL}

**Status**: {summary}

**Pattern**: {sequential/parallel/dynamic/hybrid}

**Findings**:
- Orchestration strategy: {clear/unclear}
- Handoff protocols: {explicit/implicit}
- Error handling: {comprehensive/partial/missing}

**Issues**:
- {issue with location and severity}

**Recommendations**:
- {recommendation}

#### Layer 3: Memory Layer - {PASS/FAIL}

**Status**: {summary}

**Findings**:
- Memory strategy: {in-memory/database/hybrid}
- Context management: {good/needs improvement}
- Persistence: {transient/durable}

**Issues**:
- {issue with location and severity}

**Recommendations**:
- {recommendation}

#### Layer 4: Tool Layer - {PASS/FAIL}

**Status**: {summary}

**Findings**:
- Tool count: {count}
- Tool interfaces: {well-defined/inconsistent}
- Error handling: {robust/fragile}

**Issues**:
- {issue with location and severity}

**Recommendations**:
- {recommendation}

#### Layer 5: Safety Layer - {PASS/FAIL}

**Status**: {summary}

**Findings**:
- Guardrails: {present/missing}
- Validation: {input/output/both/none}
- Human-in-the-loop: {implemented/missing}

**Issues**:
- {issue with location and severity}

**Recommendations**:
- {recommendation} (defer to the safety-reviewer skill for details)

### Agent Topology Analysis

**Topology Health**: {GOOD/CONCERNS/CRITICAL}

**Metrics**:
- Total agents: {count}
- Max depth: {levels}
- Circular dependencies: {count}
- Orphaned agents: {count}
- Average fanout: {ratio}

**Agent Dependency Graph**:

```mermaid
graph TB
    Orchestrator --> AgentA
    Orchestrator --> AgentB
    AgentB --> AgentC
    AgentB --> AgentD
```

**Issues Detected**:
- [ ] Circular dependency: {Agent A} → {Agent B} → {Agent A}
- [ ] Orphaned agent: {Agent name} (never called)
- [ ] God agent: {Agent name} (orchestrates {count} agents)
- [ ] Deep nesting: {path showing deep call chain}

**Recommendations**:
- {topology-specific recommendation}

### Orchestration Pattern Assessment

**Pattern**: {identified pattern}

**Alignment**: {GOOD/PARTIAL/POOR}

**Framework Best Practices**:
- [ ] Using framework routing primitives
- [ ] Leveraging framework state management
- [ ] Following framework error handling patterns
- [ ] Utilizing framework observability features

**Recommendations**:
- {orchestration improvement}

### Architecture Decision Records

**Implicit Decisions Detected**:
1. {decision inferred from code}
   - **Status**: Implicit (should be documented)
   - **Rationale**: {inferred reasoning}
   - **Consequence**: {observed impact}

**Recommendations**:
- Create ADR for: {decision needing documentation}
- Review ADR for: {outdated decision}

### Migration Opportunities

{If framework upgrade or migration is beneficial}

**From**: {current state}
**To**: {recommended state}
**Effort**: {LOW/MEDIUM/HIGH}
**Benefit**: {description}

### Next Steps

1. **Critical**: {action item}
2. **High**: {action item}
3. **Medium**: {action item}
4. **Consider**: {action item}

### Cross-Skill Coordination

**Defer to**:
- **wicked-garden-agentic-safety-reviewer**: For detailed guardrail implementation and validation strategy
- **wicked-garden-agentic-performance-analyst**: For latency, cost, and token optimization
- **frameworks knowledge skill** (`skills/agentic/frameworks/`): For latest framework features and migration paths
- **agentic-patterns knowledge skill** (`skills/agentic/agentic-patterns/`): For code-level pattern improvements

**Collaborate with**:
- The safety-reviewer skill on Layer 5 validation
- The performance-analyst skill on orchestration efficiency

Integration with agentic Knowledge Modules

  • Use skills/agentic/agentic-patterns/ for layer-specific guidance (five-layer model is included) and pattern recognition
  • Use skills/agentic/frameworks/ for framework-specific best practices

Integration with Peer Skills

Safety Reviewer (wicked-garden-agentic-safety-reviewer)

  • Provide Layer 5 findings for detailed review
  • Coordinate on guardrail placement and validation strategy

Performance Analyst (wicked-garden-agentic-performance-analyst)

  • Share orchestration pattern analysis
  • Identify architecture-level performance bottlenecks

Frameworks knowledge module (skills/agentic/frameworks/)

  • Cross-check current framework detection results against curated profiles
  • Consult for guidance on migration paths

Agentic-patterns knowledge module (skills/agentic/agentic-patterns/)

  • Check topology analysis against the pattern catalog for pattern-level improvements
  • Source refactoring recommendations from the catalog

Common Architecture Smells

SmellIndicatorFix
God AgentOne agent handles many responsibilitiesSplit into specialized agents
Circular DepsA → B → A patternIntroduce mediator or event bus
Deep NestingCall chains > 4 levels deepFlatten hierarchy, use pub/sub
Orphaned AgentAgent defined but never usedRemove or document intent
Unclear OrchestrationNo clear coordinatorIntroduce explicit orchestrator
Missing SafetyNo validation layerAdd Layer 5 guardrails
Context LeakageAgents share mutable stateUse immutable context passing

Quick Reference: Detection Scripts

Verified flags: detect_framework.py [--path --quick --threshold]; analyze_agents.py [--path --framework] (prints JSON to stdout — redirect it).

# Detect framework
wicked-garden run scripts/agentic/detect_framework.py \
  --path . --threshold 0.6

# Analyze agent topology (stdout → file)
wicked-garden run scripts/agentic/analyze_agents.py \
  --path . > topology.json

For the architecture diagram, draw the mermaid graph yourself from the dependency graph in topology.json (see Output Format above) — the analyzer has no diagram/format flag.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.