ArchHarness — Enterprise Architecture Design & Validation

This file is the multi-tool rules file (AGENTS.md), read by OpenCode, Codex, GitHub Copilot, and Cursor. Claude Code reads the equivalent CLAUDE.md. Both files carry the same shared body — the block delimited by archharness-shared markers below — and CI fails when the two drift (tests/test_rules_files_in_sync.py).

What this is

ArchHarness is a multi-tool architecture skill pack for enterprise architecture work. It runs natively in Claude Code and OpenCode and is discovered by Codex, GitHub Copilot, and Cursor. It turns the AI into a team of architecture specialists you summon on demand, backed by a real CLI (python -m archharness), versioned contracts, and a deterministic gate.

Available agents and skills

Configuration

All company-specific values (DC names, platform names, classification labels) live in config.yaml at the repository root. Edit it before first use — it is the only file you need to change. Skills and rules load these values at runtime: company.name, datacenters (names, locations, zones), and platforms (API gateway, message bus, K8s platform).

Multi-project workspace

One checkout supports many isolated projects. Create projects with the CLI (python -m archharness): init-workspace, init-project, list-projects, doctor. Each project lives under projects/<id>/ with its own input/, working/, output/, and a project.yaml describing id, name, platform, and data_classification.

Working session rules:

• If the cwd is inside projects/<id>/, that project is the active project.
• Use --project <id> to select a project from anywhere in the workspace.
• Inputs resolve against the active project input/; generated files land in the active project output/ (subfolders requirements/, designs/, diagrams/, validation/, reports/).
• Project data dirs are git-ignored. Do not scatter generated files in the repository root when a workspace project is active — target the project output/.

Standards in scope

All skills load company-specific values from config.yaml at runtime. The standards/ directory holds the platform-agnostic rules and topology requirements. Six deployment targets are supported, each with a standard, a placement-rule family (E-*), a design template, and a worked example:

• private-cloud-standard.yaml — F5 ingress model, east-west isolation, PAW, DC zone models
• aws-standard.yaml — Hub-Spoke, ALB/WAF, API Gateway in Spoke VPC, IAM + Secrets Manager
• azure-standard.yaml — Hub-Spoke, App Gateway WAF v2, APIM in Spoke VNET, Key Vault
• gcp-standard.yaml — Shared VPC host + service projects, global HTTPS LB + Cloud Armor, Cloud NAT, CMEK (E-GCP-*)
• aliyun-standard.yaml — resource directory + central VPC, Anti-DDoS → WAF → SLB, CEN, RAM roles + STS (E-ALI-*)
• microsoft-saas-standard.yaml — black-box tenant/environment containers, one boundary component, Entra ID + DLP; Microsoft 365 / Power Platform / Dynamics 365 (E-MS-*)

Diagram shape spec

standards/diagram-style.yaml — full shape, color, arrow, and metadata rules from:

• Private Cloud Architecture Diagram Shape Specification v1.0
• Technical Architecture Diagram Specification v1.0

Validation rules

Skills load rules from .claude/skills/arch-validate/rules/:

• diagram-rules.yaml — V- series: shape, color, arrow, legend
• interaction-rules.yaml — W- series: arrow direction, protocol, integration platform
• security-rules.yaml — S- series: auth, user auth, credential protection
• accuracy-rules.yaml — E- series: DC location, network segments, component completeness
• platform-rules.yaml — platform-specific rules for private cloud, AWS, Azure, GCP, Alibaba Cloud, Microsoft SaaS
• compliance/terminology.yaml — cloud terminology and ISO27001/TOGAF mapping

Scoring

Six dimensions, 10 points total:

• Cloud_Network_Completeness (2.0), Connectivity (1.0), Technical_Component_Completeness (2.0)
• Interaction_Integration (2.0), Security_Compliance (2.0), Terminology_Expression (1.0)

Usage pattern

1. Design → run the design skill to generate architecture YAML from requirements
2. Validate → run the validation skill on the diagram image for a scored JSON report
3. Enforce → run the enforce skill to apply the CI gate policy (or skip for human review)
4. Deep-dive security → run the security skill for an auth/credential/network boundary audit
5. Standards check → run the review skill for committee-style compliance scoring
6. Fix it → run the optimize skill for prioritized improvement suggestions
7. Document it → run the report skill for an executive summary or Confluence page

Pipeline discipline (mandatory order)

Architecture stages run in the order defined by standards/workflow.yaml:

Requirements → design → draw (export PNG) → validate → enforce gate
                                                    │ PASS / WARN → security + review
                                                    │ BLOCK       → pipeline stops
security + review → optimize → report

Gate rules (fail-closed, enforced by the arch-workflow gatekeeper):

• A stage starts only when every artifact in its requires list exists in the active project output//working/.
• Never fabricate predecessor outputs and never skip a stage.
• After the enforce gate, continue only on PASS or WARN. BLOCK requires fixing the findings and re-running validate → enforce.
• Invoke arch-workflow status / arch-workflow can <stage> (@arch-workflow in OpenCode) before starting a stage when in doubt.

Host specifics

Discovery. OpenCode reads this file and the agents under .opencode/agents/, invoked as @arch-*. Codex reads this file and discovers skills under .agents/skills/. GitHub Copilot discovers the @arch-* custom agents under .github/agents/. Cursor reads this file and, in supported builds, the skills under .claude/skills/.

Mirrors. .agents/skills/ is a generated mirror of .claude/skills/; update it with python scripts/sync_agents_skills.py after editing a skill. CI fails when the mirror drifts.

If skills aren't loading, confirm the working directory is the repository root (or a project directory) so .opencode/agents/, .agents/skills/, standards/, tools/, and config.yaml are all found.