archharness 0.3.2__tar.gz

archharness-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArchHarness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archharness-0.3.2/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include archharness/data *
+global-exclude *.py[cod]
+global-exclude __pycache__

archharness-0.3.2/PKG-INFO

@@ -0,0 +1,447 @@
+Metadata-Version: 2.4
+Name: archharness
+Version: 0.3.2
+Summary: Enterprise architecture skill pack and multi-project workspace tools
+License: MIT
+Project-URL: Homepage, https://github.com/axisrobo/ea-harness
+Project-URL: Repository, https://github.com/axisrobo/ea-harness
+Project-URL: Releases, https://github.com/axisrobo/ea-harness/releases
+Project-URL: Documentation, https://github.com/axisrobo/ea-harness#readme
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: diagram
+Requires-Dist: matplotlib>=3.7; extra == "diagram"
+Provides-Extra: documents
+Requires-Dist: pdfplumber>=0.10; extra == "documents"
+Requires-Dist: python-docx>=1.1; extra == "documents"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == "llm"
+Requires-Dist: openai>=1.0; extra == "llm"
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.7; extra == "all"
+Requires-Dist: pdfplumber>=0.10; extra == "all"
+Requires-Dist: python-docx>=1.1; extra == "all"
+Requires-Dist: anthropic>=0.40; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Dynamic: license-file
+
+# 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`](./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
+
+```bash
+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.
+
+```yaml
+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.
+
+```bash
+# POSIX / macOS / Linux
+python -m archharness init-workspace .
+python -m archharness init-project payments --name "Payments Platform" --default
+python -m archharness list-projects
+```
+
+```powershell
+# Windows PowerShell
+python -m archharness init-workspace .
+python -m archharness init-project payments --name "Payments Platform" --default
+python -m archharness list-projects
+```
+
+This creates:
+
+```text
+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
+
+```bash
+# POSIX / macOS / Linux
+./install.sh
+
+# Windows PowerShell
+.\install.ps1
+```
+
+Or manually:
+
+```bash
+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**
+```bash
+claude .
+```
+Skills under `.claude/skills/` register as `/arch-*` slash commands.
+
+**OpenCode**
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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`.