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

Agent / Skill	Claude Code	OpenCode	Role
arch-workflow	`/arch-workflow`	`@arch-workflow`	Pipeline gatekeeper — enforces stage order; BLOCK stops pipeline
arch-requirements	`/arch-requirements`	`@arch-requirements`	Structured interview → REQ.md + req.yaml
arch-req-from-diagram	`/arch-req-from-diagram`	`@arch-req-from-diagram`	draw.io / PNG → partial req.yaml
arch-req-from-doc	`/arch-req-from-doc`	`@arch-req-from-doc`	PDF / DOCX / MD → partial req.yaml
arch-req-from-api	`/arch-req-from-api`	`@arch-req-from-api`	CMDB / ServiceNow / CSV → partial req.yaml
arch-req-merge	`/arch-req-merge`	`@arch-req-merge`	Merge partials, detect conflicts, gap report
arch-design	`/arch-design`	`@arch-design`	Requirements → architecture YAML + draw.io guidance
arch-diagram	`/arch-diagram`	`@arch-diagram`	Architecture YAML → draw.io XML + PNG
arch-validate	`/arch-validate`	`@arch-validate`	Diagram image → scored JSON report (6 dimensions)
arch-enforce	`/arch-enforce`	`@arch-enforce`	CI enforcement gate — PASS / WARN / BLOCK with exit code
arch-security	`/arch-security`	`@arch-security`	Auth / credentials / network boundary deep-dive
arch-review	`/arch-review`	`@arch-review`	Committee gate: APPROVED / CONDITIONS / REJECTED
arch-optimize	`/arch-optimize`	`@arch-optimize`	Prioritized fix backlog (P0/P1/P2/P3)
arch-report	`/arch-report`	`@arch-report`	Confluence page / executive summary / risk brief

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

The pipeline is mandatory and gated by artifacts. The order and required input/output files are defined in standards/workflow.yaml. The arch-workflow gatekeeper checks that every required artifact of the next stage exists (and that the enforce gate recorded PASS or WARN) before the stage starts. A BLOCK decision stops the pipeline until findings are fixed and validation is re-run. Never skip a stage or fabricate predecessor outputs; invoke @arch-workflow status / @arch-workflow can <stage> when in doubt.

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

Tool	Project rules	Skills / agents	Invocation
Claude Code	`CLAUDE.md`	`.claude/skills/`	`/arch-validate`, `/arch-design`, …
OpenCode	`AGENTS.md`	`.opencode/agents/`	`@arch-validate`, `@arch-design`, …
Codex	`AGENTS.md`	`.agents/skills/`	skill selector on `.agents/skills/`
GitHub Copilot	`AGENTS.md`	`.github/agents/`	`@arch-validate`, `@arch-design`, …
Cursor	`AGENTS.md`	`.claude/skills/` (supported builds)	`/skills`

.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?

Claude Code — yes, via the plugin marketplace. In the Claude Code chat window:

/plugin marketplace add axisrobo/ea-harness
/plugin install archharness@archharness-marketplace
/reload-plugins

Plugin skills are namespaced as /archharness:arch-validate, /archharness:arch-design, /archharness:arch-workflow, etc. (the plugin caches a copy of the skills). For shared resources (standards/, tools/, config.yaml) the skills resolve through the installed package or a checkout — so run pip install archharness[all] (or set ARCHHARNESS_HOME) once.

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

Command	Purpose
`python -m archharness --version`	Show the installed version
`python -m archharness root`	Print the resource root (config.yaml + tools/)
`python -m archharness doctor`	Self-check installation, workspace, and project
`python -m archharness init-workspace .`	Create the workspace metadata
`python -m archharness init-project <id>`	Scaffold an isolated project
`python -m archharness diagram -i arch.yaml`	Run the diagram generator (draw.io/PNG/D2/PlantUML)
`python -m archharness req --doc brief.md`	Run the requirements readers + merger
`python -m archharness validate-yaml config.yaml`	YAML syntax gate (CI fail-closed check)

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.

Self-contained install (no checkout needed). pip install archharness[all] ships tools/, standards/, and the skill tree inside the package, so python -m archharness root returns a bundled resource root and the CLI tools work from any working directory:

pip install "archharness[all]"              # PyPI (once published), or:
pip install https://github.com/axisrobo/ea-harness/releases/download/v0.3.2/archharness-0.3.2-py3-none-any.whl
python -m archharness root        # → …/site-packages/archharness/data
python -m archharness doctor

Regenerate the bundled data before building a wheel with python scripts/assemble_data.py.

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

Dimension	Weight
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
Total	10.0

Validation rules

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

File	Series	Coverage
`diagram-rules.yaml`	V-	Shape, color, arrow direction, legend
`interaction-rules.yaml`	W-	Protocol, auth, integration platform placement
`security-rules.yaml`	S-	System auth, user auth, credential protection
`accuracy-rules.yaml`	E-	DC location, network segments, component completeness
`platform-rules.yaml`	—	AWS / Azure / private cloud specific rules
`compliance/terminology.yaml`	—	Cloud terms, ISO 27001 / TOGAF mapping

Enforcement gate

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

Decision	Condition	Exit code
PASS	Score ≥ 8.0 AND no `must_fix` issues	0
WARN	Score ≥ 6.0 AND < 8.0 AND no `must_fix` issues	0
BLOCK	Score < 6.0 OR any `must_fix` issue present	1

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-*)
├── .claude-plugin/          ← Claude Code plugin marketplace manifest
├── plugins/archharness/     ← Claude Code plugin bundle (skills mirror, generated)
├── .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.

Navigation Menu

Uh oh!

Repository files navigation

ArchHarness

What it does

Workflow

Setup

1. Clone

2. Configure the organisation profile

3. Create a workspace and a project

4. Install Python dependencies

5. Open in your AI coding tool

Where each tool discovers ArchHarness

Can users install from the chat window?

Command-line reference

Usage examples

Design a new system

Generate a diagram

Validate a diagram

Full pipeline (OpenCode)

Scoring dimensions

Validation rules

Enforcement gate

Benchmark suite

Supported platforms

Project structure

Requirements

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.archharness		.archharness
.claude-plugin		.claude-plugin
.claude/skills		.claude/skills
.github		.github
.opencode/agents		.opencode/agents
archharness		archharness
benchmark		benchmark
papers		papers
plugins/archharness		plugins/archharness
scripts		scripts
standards		standards
tests		tests
tools		tools
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
config.yaml		config.yaml
install.ps1		install.ps1
install.sh		install.sh
opencode.json		opencode.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

ArchHarness

What it does

Workflow

Setup

1. Clone

2. Configure the organisation profile

3. Create a workspace and a project

4. Install Python dependencies

5. Open in your AI coding tool

Where each tool discovers ArchHarness

Can users install from the chat window?

Command-line reference

Usage examples

Design a new system

Generate a diagram

Validate a diagram

Full pipeline (OpenCode)

Scoring dimensions

Validation rules

Enforcement gate

Benchmark suite

Supported platforms

Project structure

Requirements

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages