ArchHarness

Enterprise architecture design and validation skill pack for Claude Code, OpenCode,
Codex, GitHub Copilot, and Cursor.

ArchHarness turns your AI coding assistant into a team of architecture specialists —
a requirements analyst, a senior architect, a paranoid security auditor, a committee reviewer,
and a technical writer — each invocable on demand with a single command.

Not yet another README-only repo. archharness ships a real CLI
(python -m archharness), a multi-project workspace layout, and platform skills that
load enterprise values from a single config file.

What it does

Workflow

Requirements → arch-design → draw in draw.io → arch-validate
                                                      │
                                              arch-enforce gate
                                           PASS / WARN / BLOCK
                                                      │  if PASS/WARN
                                                      │
                                          arch-security  arch-review
                                                      │
                                               arch-optimize
                                                      │
                                               arch-report

Setup

1. Clone

git clone https://github.com/axisrobo/ea-harness.git
cd ea-harness

2. Configure the organisation profile

Edit config.yaml at the repository root to match your organisation's
infrastructure (DC names, platform names, classification prefix). Skills and
LLM rules load these values at runtime.

company:
  name: "Acme Corp"

datacenters:
  - id: "dc-primary"
    aliases: ["Primary DC", "Tokyo DC"]
    location: { city: "Tokyo", country: "JP" }
    zones: ["DMZ", "App Zone", "DB Zone"]

platforms:
  api_gateway: "Kong API Gateway"   # or WSO2, AWS API GW, Azure APIM…
  message_bus: "RabbitMQ"           # or Kafka, Azure Service Bus…
  k8s_platform: "Rancher"
  integration_platforms:
    - "Kong API Gateway"
    - "RabbitMQ"
    - "SFTP/MFT"

If you manage more than one architecture project, put these company values
in config.yaml once and create isolated projects (next step). Per-project
inputs and outputs live under projects/<id>/.

3. Create a workspace and a project

One workspace can hold many architecture projects. Each project has its own
input/, working/, and output/ trees so files never bleed between projects.

# POSIX / macOS / Linux
python -m archharness init-workspace .
python -m archharness init-project payments --name "Payments Platform" --default
python -m archharness list-projects

# Windows PowerShell
python -m archharness init-workspace .
python -m archharness init-project payments --name "Payments Platform" --default
python -m archharness list-projects

This creates:

projects/payments/
├─ project.yaml               # id, name, platform, data classification
├─ input/                     # documents, diagrams, api exports, requirements
├─ working/                   # intermediate files
└─ output/                    # requirements, designs, diagrams, validation, reports

project.yaml and all generated files are git-ignored — only project.yaml and
README.md are tracked when you choose to commit them.

When you work inside a project directory, tools and skills auto-detect the active
project (--project also works from anywhere in the workspace).

4. Install Python dependencies

# POSIX / macOS / Linux
./install.sh

# Windows PowerShell
.\install.ps1

Or manually:

pip install -e ".[all]"
python -m archharness init-workspace .   # only if not created above
python -m archharness doctor             # verify the install

The installer registers skills with your AI tool, creates a workspace when one
is missing, and runs doctor. Add ARCHHARNESS_HOME=/path/to/ea-harness to
your environment if you ever run tools from a different working directory.

5. Open in your AI coding tool

Claude Code

claude .

Skills under .claude/skills/ register as /arch-* slash commands.

OpenCode

opencode .

Agents under .opencode/agents/ register as @arch-* agents.

Codex / GitHub Copilot / Cursor
Point the tool at this repository root. AGENTS.md is read by all three;
Codex discovers skills under .agents/skills/; GitHub Copilot discovers the
@arch-* custom agents under .github/agents/; Cursor builds also read
.claude/skills/.

Tip: working directory should be the repository root (or a project
directory) so skills, tools, and config.yaml are found automatically.

Where each tool discovers ArchHarness

.agents/skills/ is a generated mirror of .claude/skills/. Update it with
python scripts/sync_agents_skills.py after editing any skill; CI enforces
the mirror stays in sync (scripts/check_repo.py validates the whole pack).

Can users install from the chat window?

There is no single cross-tool "chat install" command. What works today:

• Claude Code plugin marketplace (/plugin marketplace add) is the closest
  native chat-install, but this repository does not publish a plugin yet —
  skills installed through a plugin would be cached away from tools/ and
  standards/, breaking their file references. Publishing a marketplace is
  planned once skills resolve resources through ARCHHARNESS_HOME.
• Every other tool: open this repository as the working directory
  (claude ., opencode ., codex, or point Copilot/Cursor at it). Skills,
  agents, and AGENTS.md are then discovered automatically and stay able to
  reach tools/, standards/, and config.yaml.
• Installers (install.ps1 / install.sh) prepare a fresh clone: they
  install the Python package, initialise the workspace, and run doctor.

Command-line reference

diagram, req, and validate-yaml forward their flags to the same Python
tools under tools/, so both invocation styles are equivalent:

python tools/arch-diagram-gen/arch_diagram_gen.py -i arch.yaml
python -m archharness diagram -i arch.yaml

Run a tool from inside projects/<id>/ to target that project automatically;
pass --project <id> to target one from anywhere.

Usage examples

Design a new system

/arch-requirements

Claude conducts a structured interview and produces REQ.md + req.yaml
in the active project's output/requirements/.

Generate a diagram

/arch-design

Produces an architecture YAML blueprint. Then, from inside the project directory:

python ../../tools/arch-diagram-gen/arch_diagram_gen.py -i arch.yaml
# → output/diagrams/arch.drawio

Or explicitly target a project from anywhere in the workspace:

python tools/arch-diagram-gen/arch_diagram_gen.py -i projects/payments/input/arch.yaml \
  --project payments

Validate a diagram

Attach your diagram PNG and run:

/arch-validate

Returns a scored JSON report with must_fix, should_fix, and consider findings.

Full pipeline (OpenCode)

@arch-requirements   # gather requirements
@arch-design         # design the architecture
@arch-validate       # validate the diagram
@arch-enforce        # CI enforcement gate decision
@arch-security       # deep security audit
@arch-review         # committee gate decision
@arch-optimize       # prioritized fix backlog
@arch-report         # Confluence-ready documentation

Scoring dimensions

Validation rules

Rules live in .claude/skills/arch-validate/rules/:

Enforcement gate

After validation, the arch-enforce gate applies policy thresholds
to the validation result and emits a CI-ready decision:

The gate is designed for automated CI pipelines. For human review,
skip the gate and use arch-review directly.

Policy lives in two files:

• standards/arch-gate-policy.yaml — enforcement bounds, override conditions, meta-control
• standards/ci-gate-spec.yaml — per-dimension minimums, blocking rule IDs, profiles (financial / internet-facing / internal)

See ARCHITECTURE.md for the full control objective and audit trail
specification.

Benchmark suite

The benchmark/ directory contains the AI and Ethics revision measurement suite for:

• Exp1: strict C-layer gate-to-A-layer build overhead.
• Exp2: temperature consistency at temperature=0.1 and temperature=0.3.

Current completed candidate results are documented in benchmark/EXPERIMENT_STATUS.md and summarized in benchmark/results/summary.md when local generated result files are present. Generated CSV/summary files are git-ignored; preserve final artifacts separately when preparing a manuscript revision package.

Supported platforms

Standards in standards/ cover three deployment targets:

• Private cloud — F5 ingress, east-west isolation via integration platform, PAW/ADFS
• AWS — Hub-Spoke VPC, ALB+WAF, API Gateway in Spoke VPC, IAM + Secrets Manager
• Azure — Hub-Spoke VNET, App Gateway WAF v2, APIM in Spoke VNET, Key Vault

All platform-specific names (API gateway, message bus, K8s platform) are read
from config.yaml — no hardcoding in rules or skill files.

Project structure

ea-harness/
├── config.yaml              ← Organisation profile — edit this first
├── README.md
├── CLAUDE.md                ← Claude Code project rules
├── AGENTS.md                ← OpenCode / Codex / Copilot / Cursor project rules
├── ARCHITECTURE.md          ← Design rationale
├── archharness/             ← `python -m archharness` CLI (workspace + tools)
├── install.ps1 / install.sh ← cross-platform installers
├── benchmark/               ← Experiment scripts, prompts, status, and generated results
├── projects/<id>/           ← Workspace projects (init with `archharness init-project`)
├── standards/               ← Platform-agnostic rules, topology specs, and gate policy
├── tools/
│   ├── config_loader.py     ← Shared config reader for Python tools
│   ├── arch-diagram-gen/    ← YAML → draw.io + PNG
│   └── arch-req-readers/    ← diagram / doc / API → req.yaml
├── tests/                   ← pytest suite
├── scripts/                 ← check_repo.py, sync_agents_skills.py (also run in CI)
├── .github/workflows/       ← CI pipeline
├── .github/agents/          ← GitHub Copilot custom agents (@arch-*)
├── .agents/skills/          ← Codex discovery mirror (generated)
├── .claude/skills/          ← Skill definitions (Claude Code slash commands)
└── .opencode/agents/        ← Agent definitions (OpenCode @agent-name)

Requirements

• Claude Code, OpenCode, Codex, GitHub Copilot, or Cursor
• Python 3.10+ (pip install -e ".[all]" pulls everything; pyyaml matplotlib is the minimal set)
• draw.io desktop app (optional, for high-fidelity PNG export)

License

MIT — see LICENSE.