arch
Purpose
This skill handles root SE architecture tasks, including system design, creating Architecture Decision Records (ADRs), performing trade-off analyses, and selecting tech stacks. It integrates with OpenClaw's core engine to output structured artifacts like diagrams, documents, or JSON reports.
When to Use
Use this skill when starting a new system design, evaluating architectural decisions, or resolving trade-offs in tech choices. Apply it during project kickoffs, refactoring, or when scaling systems, especially for complex applications involving microservices, cloud infrastructure, or distributed systems.
Key Capabilities
- Generate ADRs in Markdown format with sections for context, decision, and consequences.
- Analyze trade-offs using predefined models (e.g., CAP theorem for distributed systems).
- Recommend tech stacks based on inputs like requirements, constraints, and performance metrics.
- Produce system design diagrams via integration with tools like PlantUML.
- Support iterative refinement of designs through feedback loops.
Usage Patterns
Invoke the skill via OpenClaw CLI or API for interactive or scripted workflows. Start with a command to initialize a design session, then chain subcommands for analysis. For example, pipe outputs to other tools for visualization. Always provide inputs as JSON files for consistency. Use environment variables for authentication, like $OPENCLAW_API_KEY, to secure requests.
Common Commands/API
Use the OpenClaw CLI with the arch subcommand. Prefix all commands with openclaw arch.
- Design a system:
openclaw arch design --input design.json --output system.mdThis generates a system design document. The--inputflag requires a JSON file with fields like {"requirements": ["scalable"], "components": ["database", "API"]}. - Create an ADR:
openclaw arch adr --title "Use Microservices" --context "Monolith limitations" --decision "Adopt microservices"Example snippet:openclaw arch adr --title "Microservices ADR" > adr.md cat adr.md # Outputs: # Architecture Decision Record\n## Title: Microservices ADR\n## Context:... - Analyze trade-offs:
openclaw arch tradeoff --options "monolith,microservices" --criteria "scalability,cost"API endpoint: POST /api/skills/arch/tradeoff with body: {"options": ["monolith"], "criteria": ["cost"]} Response: JSON like {"winner": "microservices", "reasons": ["better scalability"]}. - Select tech stack:
openclaw arch techstack --requirements "high-availability,nodejs" --constraints "budget:low"Config format: JSON input e.g., {"requirements": ["REST API"], "constraints": {"budget": 1000}} API: POST /api/skills/arch/techstack returns {"recommendations": ["Express.js", "MongoDB"]}.
Always set $OPENCLAW_API_KEY for API calls, e.g., in curl: curl -H "Authorization: Bearer $OPENCLAW_API_KEY" -X POST https://api.openclaw.ai/api/skills/arch/design.
Integration Notes
Integrate with OpenClaw by including the skill in workflows via CLI piping or API chaining. Dependencies: Node.js runtime for local execution. For auth, set $OPENCLAW_API_KEY as an environment variable before running commands. Example integration with Git: Hook into pre-commit to validate designs, e.g., openclaw arch validate --file architecture.md && git commit. Use JSON for inputs/outputs to enable parsing in scripts. Avoid direct file modifications; use --output flags. If using in a CI/CD pipeline, wrap commands in a script like:
export OPENCLAW_API_KEY=your_key
openclaw arch design --input ci-input.json > output.mdError Handling
Common errors include invalid inputs (e.g., missing JSON fields) or auth failures. Check for HTTP 401 on API calls if $OPENCLAW_API_KEY is unset or invalid—fix by exporting the variable. For CLI, errors like "Invalid flag" return exit code 1; parse with if [$? -ne 0]; then echo "Fix input and retry"; fi. Handle trade-off analysis errors (e.g., unsupported criteria) by catching JSON responses like {"error": "Criterion not found"} and retry with corrected inputs. Always validate JSON schemas before commands using tools like jq:
jq . design.json # Ensure it's valid JSON
openclaw arch design --input design.jsonConcrete Usage Examples
- Generate an ADR for a microservices migration: First, prepare a JSON file: {"title": "Microservices Migration", "context": "Current monolith is unscalable"}. Run:
openclaw arch adr --input adr-input.json --output migration-adr.md. This produces a Markdown ADR file for version control, e.g., commit it to track decisions. - Analyze trade-offs for database selection: Input options via CLI:
openclaw arch tradeoff --options "MongoDB,PostgreSQL" --criteria "flexibility,query-speed". Review the output JSON to decide, then integrate into design:openclaw arch design --input previous-output.json. This workflow helps in selecting PostgreSQL for complex queries based on analysis results.
Graph Relationships
- Relates to: se-design (for detailed implementation), se-implementation (for code-level integration)
- Depends on: core-engine (for processing), se-tools (for visualization utilities)
- Conflicts with: none directly, but avoid overlapping with se-security for access controls