@plainconceptsplatform/agent-harness 3.3.0 → 3.4.1

package/harness/opencode.jsonc

@@ -1,36 +1,36 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "servers": {
-      "agent-browser": {
-        "type": "local",
-        "command": ["agent-browser", "mcp", "--tools", "core"],
-        "disabled": false
-      }
-    },
-    "timeout": {
-      "catalog": 300000,
-      "execution": 300000
-    }
-  },
-  "compaction": {
-    "auto": true,
-    "buffer": 10000
-  },
-  "permissions": [
-    { "action": "question", "resource": "*", "effect": "allow" },
-    { "action": "skill", "resource": "*", "effect": "allow" }
-  ],
-  "skills": [".agents/skills"],
-  "default_agent": "plan",
-  "agents": {
-    "build": { "mode": "primary" },
-    "plan": {
-      "mode": "primary",
-      "permissions": [
-        { "action": "edit", "resource": "*", "effect": "deny" },
-        { "action": "subagent", "resource": "*", "effect": "deny" }
-      ]
-    }
-  }
-}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "agent-browser": {
+        "type": "local",
+        "command": ["agent-browser", "mcp", "--tools", "core"],
+        "disabled": false
+      }
+    },
+    "timeout": {
+      "catalog": 300000,
+      "execution": 300000
+    }
+  },
+  "compaction": {
+    "auto": true,
+    "buffer": 10000
+  },
+  "permissions": [
+    { "action": "question", "resource": "*", "effect": "allow" },
+    { "action": "skill", "resource": "*", "effect": "allow" }
+  ],
+  "skills": [".agents/skills"],
+  "default_agent": "plan",
+  "agents": {
+    "build": { "mode": "primary" },
+    "plan": {
+      "mode": "primary",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" },
+        { "action": "subagent", "resource": "*", "effect": "deny" }
+      ]
+    }
+  }
+}

package/harness/openspec/config.yaml

@@ -1,20 +1,20 @@
-schema: spec-driven
-
-# Project context (optional)
-# This is shown to AI when creating artifacts.
-# Add your tech stack, conventions, style guides, domain knowledge, etc.
-# Example:
-#   context: |
-#     Tech stack: TypeScript, React, Node.js
-#     We use conventional commits
-#     Domain: e-commerce platform
-
-# Per-artifact rules (optional)
-# Add custom rules for specific artifacts.
-# Example:
-#   rules:
-#     proposal:
-#       - Keep proposals under 500 words
-#       - Always include a "Non-goals" section
-#     tasks:
-#       - Break tasks into chunks of max 2 hours
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/harness/skills-lock.json

@@ -1,17 +1,17 @@
-{
-  "version": 1,
-  "skills": {
-    "find-skills": {
-      "source": "vercel-labs/skills",
-      "sourceType": "github",
-      "skillPath": "skills/find-skills/SKILL.md",
-      "computedHash": "781bd6d3f9b19f8c9af6b53d8d0e4876d0183841b565db34ca7092ffa412d111"
-    },
-    "user-story": {
-      "source": "deanpeters/product-manager-skills",
-      "sourceType": "github",
-      "skillPath": "skills/user-story/SKILL.md",
-      "computedHash": "user-story-placeholder"
-    }
-  }
-}
+{
+  "version": 1,
+  "skills": {
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "skillPath": "skills/find-skills/SKILL.md",
+      "computedHash": "781bd6d3f9b19f8c9af6b53d8d0e4876d0183841b565db34ca7092ffa412d111"
+    },
+    "user-story": {
+      "source": "deanpeters/product-manager-skills",
+      "sourceType": "github",
+      "skillPath": "skills/user-story/SKILL.md",
+      "computedHash": "user-story-placeholder"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",
@@ -42,7 +42,6 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "pnpm@11.10.0",
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
     "chalk": "^5.0.0",
@@ -51,17 +50,6 @@
     "jsonc-parser": "^3.3.1",
     "ora": "^8.0.0"
   },
-  "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "lint:md": "markdownlint-cli2 \"**/*.md\"",
-    "lint:md:fix": "markdownlint-cli2 --fix \"**/*.md\"",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run lint && npm run lint:md && npm run test",
-    "release:dry": "pnpm publish --dry-run --no-git-checks --access public",
-    "release": "pnpm publish --no-git-checks --access public"
-  },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "eslint": "^9.0.0",
@@ -71,5 +59,15 @@
   },
   "vitest": {
     "environment": "node"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "lint:md:fix": "markdownlint-cli2 --fix \"**/*.md\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release:dry": "pnpm publish --dry-run --no-git-checks --access public",
+    "release": "pnpm publish --no-git-checks --access public"
   }
-}
+}

package/skills/agent-harness-cli/SKILL.md

@@ -1,86 +1,86 @@
----
-name: agent-harness-cli
-description: Drive the agent-harness CLI - install the Plain Concepts Platform Harness into a repository, bring an existing one up to date, set up a teammate's machine, or rerun a single step. Load when asked to install, update, or repair the Platform Harness, when a repo needs AI/agent scaffolding set up, or when a command like `npx @plainconceptsplatform/agent-harness` fails and needs diagnosing.
-license: MIT
----
-
-# agent-harness CLI
-
-`agent-harness` installs the **Plain Concepts Platform Harness** into a repository and keeps it up to date. The harness is Plain Concepts' own, and it is the set of files agents work from: slash commands, `pc-*` skills (the `pc-` is Plain Concepts), an agent team, OpenCode plugins, an OpenSpec workspace, and generated `ARCHITECTURE.md` and `DESIGN.md`.
-
-Everything runs against the **current working directory**. `cd` into the target repository first; there is no `--path` flag.
-
-## Pick the right verb
-
-Read the repo before running anything. `.opencode/harness.json` is the marker for "harness already installed".
-
-| Situation | Command |
-| --- | --- |
-| No `.opencode/harness.json` | `npx @plainconceptsplatform/agent-harness@latest` (the install wizard) |
-| Harness present, want the latest release's files | `npx @plainconceptsplatform/agent-harness@latest update` |
-| Harness present, new machine or new teammate | `npx @plainconceptsplatform/agent-harness join` |
-| One specific thing needs redoing | a single step command, see below |
-
-Requires Node.js 18+.
-
-## The install wizard is interactive
-
-The wizard asks about source scope, backlog and repository platform, three models, and optional token-optimization tools. **Do not run it in a non-interactive shell.** It will hang or abort. If you cannot present prompts to a human, say so and hand the command to the user rather than trying to drive it.
-
-Everything else (`update`, and the single-step commands other than `platform`, `models`, `optimization`) runs without prompts.
-
-## Single-step commands
-
-Run one step without the full wizard. Each reuses context from `.opencode/harness.json` when it needs to.
-
-```
-clean           Remove pre-existing AI files (AGENTS.md, .cursorrules, CLAUDE.md, ...)
-platform        Choose backlog + repository platform
-copy            Copy agents, skills, commands, docs into the repo
-openspec        Initialize the OpenSpec workspace
-models          Choose plan / build / fast models
-optimization    Configure RTK, quota, Simple English, codegraph, agentmemory, humanizer
-browser         Install agent-browser (npm package + its Chrome for Testing)
-metadata        Rewrite .opencode/harness.json
-```
-
-`metadata` last if you ran several, because it refreshes the config the others read.
-
-## What lands in the repo
-
-```
-.opencode/
-  harness.json            harness config: platform, models, agents.maxConcurrent
-  harness-managed.json    hash per managed file, so update spares your edits
-  harness.user.json       per-developer model override (gitignored)
-  harness-run.json        live subagent wave state (gitignored)
-  commands/               slash commands
-  plugins/                pc-subagent-monitor, pc-subagent-tiers, pc-system-reminders
-  agents/                 fullstack-engineer + user-created *-engineer files
-.agents/skills/           pc-* skills
-AGENTS.md ARCHITECTURE.md DESIGN.md
-```
-
-After a fresh install, the next move is `/repo-initialize` inside OpenCode. That is what generates real `ARCHITECTURE.md` and `DESIGN.md` and activates the agent team. Installing the harness alone does not do it.
-
-## `update` is edit-safe
-
-`update` compares each managed file against the hash recorded in `.opencode/harness-managed.json`. Files you changed by hand are left alone and reported as preserved. Generated skills (`pc-guardrails-project`, `pc-merge-risk-assess`) are never overwritten once populated. So `update` is safe to run repeatedly, and a second consecutive run should report no changes.
-
-## Diagnosing failures
-
-**"This project was set up by opencode-onboard v1".** The repo has v1 state files or `ob-*` skills. v2 renamed both and does not migrate. Re-onboard on a clean branch; do not try to rename the files by hand, because the marker comments inside the installed skills changed too.
-
-**"No config found. Run the wizard first."** `update` or a step needs `.opencode/harness.json` and it is absent. Run the wizard.
-
-**A platform step reports nothing and changes nothing.** Platform content is injected into `<!-- PC-PLATFORM-*-START/END -->` marker pairs. If a marker pair is missing from the target file, injection is skipped silently. Check the markers exist before concluding the step worked.
-
-**Skills missing after install.** Skill installation ends with `npx skills experimental_install --yes`, run once at the end of the optimization step. If it failed, rerun it directly in the repo.
-
-**Platform CLI warnings.** The harness expects `gh` (GitHub), `az` + azure-devops extension (Azure DevOps), `acli` (Jira), `glab` (GitLab), each authenticated. These are warnings, not fatal; the harness installs, but the matching `/ops-*` flows will not work until the CLI is present.
-
-## Rules
-
-- Never edit `.opencode/harness.json` by hand to change models. Use `/make-user-model <tier> <model>` inside OpenCode, or the `models` step.
-- Never commit `harness.user.json` or `harness-run.json`. Both belong in `.opencode/.gitignore`, which `join` verifies.
-- `clean` deletes files. Confirm with the user before running it on a repo that already has AI configuration worth keeping.
+---
+name: agent-harness-cli
+description: Drive the agent-harness CLI - install the Plain Concepts Platform Harness into a repository, bring an existing one up to date, set up a teammate's machine, or rerun a single step. Load when asked to install, update, or repair the Platform Harness, when a repo needs AI/agent scaffolding set up, or when a command like `npx @plainconceptsplatform/agent-harness` fails and needs diagnosing.
+license: MIT
+---
+
+# agent-harness CLI
+
+`agent-harness` installs the **Plain Concepts Platform Harness** into a repository and keeps it up to date. The harness is Plain Concepts' own, and it is the set of files agents work from: slash commands, `pc-*` skills (the `pc-` is Plain Concepts), an agent team, OpenCode plugins, an OpenSpec workspace, and generated `ARCHITECTURE.md` and `DESIGN.md`.
+
+Everything runs against the **current working directory**. `cd` into the target repository first; there is no `--path` flag.
+
+## Pick the right verb
+
+Read the repo before running anything. `.opencode/harness.json` is the marker for "harness already installed".
+
+| Situation | Command |
+| --- | --- |
+| No `.opencode/harness.json` | `npx @plainconceptsplatform/agent-harness@latest` (the install wizard) |
+| Harness present, want the latest release's files | `npx @plainconceptsplatform/agent-harness@latest update` |
+| Harness present, new machine or new teammate | `npx @plainconceptsplatform/agent-harness join` |
+| One specific thing needs redoing | a single step command, see below |
+
+Requires Node.js 18+.
+
+## The install wizard is interactive
+
+The wizard asks about source scope, backlog and repository platform, three models, and optional token-optimization tools. **Do not run it in a non-interactive shell.** It will hang or abort. If you cannot present prompts to a human, say so and hand the command to the user rather than trying to drive it.
+
+Everything else (`update`, and the single-step commands other than `platform`, `models`, `optimization`) runs without prompts.
+
+## Single-step commands
+
+Run one step without the full wizard. Each reuses context from `.opencode/harness.json` when it needs to.
+
+```
+clean           Remove pre-existing AI files (AGENTS.md, .cursorrules, CLAUDE.md, ...)
+platform        Choose backlog + repository platform
+copy            Copy agents, skills, commands, docs into the repo
+openspec        Initialize the OpenSpec workspace
+models          Choose plan / build / fast models
+optimization    Configure RTK, quota, Simple English, codegraph, agentmemory, humanizer
+browser         Install agent-browser (npm package + its Chrome for Testing)
+metadata        Rewrite .opencode/harness.json
+```
+
+`metadata` last if you ran several, because it refreshes the config the others read.
+
+## What lands in the repo
+
+```
+.opencode/
+  harness.json            harness config: platform, models, agents.maxConcurrent
+  harness-managed.json    hash per managed file, so update spares your edits
+  harness.user.json       per-developer model override (gitignored)
+  harness-run.json        live subagent wave state (gitignored)
+  commands/               slash commands
+  plugins/                pc-subagent-monitor, pc-subagent-tiers, pc-system-reminders
+  agents/                 fullstack-engineer + user-created *-engineer files
+.agents/skills/           pc-* skills
+AGENTS.md ARCHITECTURE.md DESIGN.md
+```
+
+After a fresh install, the next move is `/repo-initialize` inside OpenCode. That is what generates real `ARCHITECTURE.md` and `DESIGN.md` and activates the agent team. Installing the harness alone does not do it.
+
+## `update` is edit-safe
+
+`update` compares each managed file against the hash recorded in `.opencode/harness-managed.json`. Files you changed by hand are left alone and reported as preserved. Generated skills (`pc-guardrails-project`, `pc-merge-risk-assess`) are never overwritten once populated. So `update` is safe to run repeatedly, and a second consecutive run should report no changes.
+
+## Diagnosing failures
+
+**"This project was set up by opencode-onboard v1".** The repo has v1 state files or `ob-*` skills. v2 renamed both and does not migrate. Re-onboard on a clean branch; do not try to rename the files by hand, because the marker comments inside the installed skills changed too.
+
+**"No config found. Run the wizard first."** `update` or a step needs `.opencode/harness.json` and it is absent. Run the wizard.
+
+**A platform step reports nothing and changes nothing.** Platform content is injected into `<!-- PC-PLATFORM-*-START/END -->` marker pairs. If a marker pair is missing from the target file, injection is skipped silently. Check the markers exist before concluding the step worked.
+
+**Skills missing after install.** Skill installation ends with `npx skills experimental_install --yes`, run once at the end of the optimization step. If it failed, rerun it directly in the repo.
+
+**Platform CLI warnings.** The harness expects `gh` (GitHub), `az` + azure-devops extension (Azure DevOps), `acli` (Jira), `glab` (GitLab), each authenticated. These are warnings, not fatal; the harness installs, but the matching `/ops-*` flows will not work until the CLI is present.
+
+## Rules
+
+- Never edit `.opencode/harness.json` by hand to change models. Use `/make-user-model <tier> <model>` inside OpenCode, or the `models` step.
+- Never commit `harness.user.json` or `harness-run.json`. Both belong in `.opencode/.gitignore`, which `join` verifies.
+- `clean` deletes files. Confirm with the user before running it on a repo that already has AI configuration worth keeping.

package/skills/pc-guardrails-generic/SKILL.md

@@ -1,53 +1,53 @@
----
-name: pc-guardrails-generic
-description: Generic guardrails, foundational rules that all agents follow. Users add specialized guardrails skills for specific concerns. Covers secrets, code quality, security, tool usage, and engineer workflow.
-license: MIT
----
-
-## Transitive loads (optimization skills)
-
-The marker sections below name the optimization skills this project selected. Load each before doing any work.
-
-## Secrets
-
-- Treat `.env` files as write-only: write to them when configuring, read credentials at runtime from the environment or secret store.
-- Never put a credential, API key, or token in a log line, output, or commit in anything but encrypted or template form.
-
-## Code
-
-- Zero comments by default. Write one only for what the code cannot show and we do not control: a vendor bug, an external contract, a legal rule. Leave every file you touch with no comment slop, old or new.
-- Never add a file that collects unrelated things — `constants.js`, `types.ts`, `utils.ts`. One responsibility per file, split by domain. A file importing from many unrelated modules is already the symptom.
-
-## Temporary files
-
-- Never write outside `$REPO_ROOT` or an OS temp directory: the next agent cannot see it and nobody cleans it up. Scratch goes under `$REPO_ROOT/.opencode/.tmp/` (enforced by pc-system-reminders).
-- Never report a `.tmp/` path as a deliverable. Copy or move the artifact to its repository path first. Never leave scratch files behind unless they are evidence for a failure you are reporting.
-
-## Tests
-
-- Never write more tests than the change requires. A bug fix gets one regression test. A new function gets tests for its public contract, not every internal branch. Never aim for a coverage number.
-- Never test framework or library internals. Test your code's contract, not that EF Core saves a tracked entity.
-- Never generate integration, e2e, or snapshot tests unless explicitly asked. Mock nothing you do not own — use a fake that records state. Never add a test that duplicates a type-check or linter rule.
-- `node .opencode/scripts/check-diff.mjs` enforces the comment and test rules on the diff and must exit 0.
-
-<!-- PC-GUARDRAILS-RTK-START -->
-<!-- PC-GUARDRAILS-RTK-END -->
-
-<!-- PC-GUARDRAILS-CODEGRAPH-START -->
-<!-- PC-GUARDRAILS-CODEGRAPH-END -->
-
-<!-- PC-GUARDRAILS-MEMORY-START -->
-<!-- PC-GUARDRAILS-MEMORY-END -->
-
-<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-START -->
-<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-END -->
-
-<!-- PC-GUARDRAILS-HUMANIZER-START -->
-<!-- PC-GUARDRAILS-HUMANIZER-END -->
-
-## Engineer workflow (when spawned)
-
-The lead puts your task IDs and their text in your prompt. Two things about that are not up to you:
-
-- Load every skill under your `## Abilities` before you start, guardrails first, one `skill` call per `@skill-name`. Editing, shell and spawning are blocked until you have (pc-system-reminders).
-- Edit only files in your assigned scope, then return: task IDs done, files changed, tests and lint result, decisions made. Then exit. Never poll for more work or claim a task the lead did not give you.
+---
+name: pc-guardrails-generic
+description: Generic guardrails, foundational rules that all agents follow. Users add specialized guardrails skills for specific concerns. Covers secrets, code quality, security, tool usage, and engineer workflow.
+license: MIT
+---
+
+## Transitive loads (optimization skills)
+
+The marker sections below name the optimization skills this project selected. Load each before doing any work.
+
+## Secrets
+
+- Treat `.env` files as write-only: write to them when configuring, read credentials at runtime from the environment or secret store.
+- Never put a credential, API key, or token in a log line, output, or commit in anything but encrypted or template form.
+
+## Code
+
+- Zero comments by default. Write one only for what the code cannot show and we do not control: a vendor bug, an external contract, a legal rule. Leave every file you touch with no comment slop, old or new.
+- Never add a file that collects unrelated things — `constants.js`, `types.ts`, `utils.ts`. One responsibility per file, split by domain. A file importing from many unrelated modules is already the symptom.
+
+## Temporary files
+
+- Never write outside `$REPO_ROOT` or an OS temp directory: the next agent cannot see it and nobody cleans it up. Scratch goes under `$REPO_ROOT/.opencode/.tmp/` (enforced by pc-system-reminders).
+- Never report a `.tmp/` path as a deliverable. Copy or move the artifact to its repository path first. Never leave scratch files behind unless they are evidence for a failure you are reporting.
+
+## Tests
+
+- Never write more tests than the change requires. A bug fix gets one regression test. A new function gets tests for its public contract, not every internal branch. Never aim for a coverage number.
+- Never test framework or library internals. Test your code's contract, not that EF Core saves a tracked entity.
+- Never generate integration, e2e, or snapshot tests unless explicitly asked. Mock nothing you do not own — use a fake that records state. Never add a test that duplicates a type-check or linter rule.
+- `node .opencode/scripts/check-diff.mjs` enforces the comment and test rules on the diff and must exit 0.
+
+<!-- PC-GUARDRAILS-RTK-START -->
+<!-- PC-GUARDRAILS-RTK-END -->
+
+<!-- PC-GUARDRAILS-CODEGRAPH-START -->
+<!-- PC-GUARDRAILS-CODEGRAPH-END -->
+
+<!-- PC-GUARDRAILS-MEMORY-START -->
+<!-- PC-GUARDRAILS-MEMORY-END -->
+
+<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-START -->
+<!-- PC-GUARDRAILS-SIMPLE-ENGLISH-END -->
+
+<!-- PC-GUARDRAILS-HUMANIZER-START -->
+<!-- PC-GUARDRAILS-HUMANIZER-END -->
+
+## Engineer workflow (when spawned)
+
+The lead puts your task IDs and their text in your prompt. Two things about that are not up to you:
+
+- Load every skill under your `## Abilities` before you start, guardrails first, one `skill` call per `@skill-name`. Editing, shell and spawning are blocked until you have (pc-system-reminders).
+- Edit only files in your assigned scope, then return: task IDs done, files changed, tests and lint result, decisions made. Then exit. Never poll for more work or claim a task the lead did not give you.

package/skills/pc-guardrails-project/SKILL.md

@@ -1,8 +1,8 @@
----
-name: pc-guardrails-project
-description: Project-specific guardrails extracted from ARCHITECTURE.md and project config files. Populated by /make-guardrails. Load this skill before implementing any change to understand boundaries, conventions, and constraints for this codebase.
-license: MIT
----
-
-<!-- This skill is a placeholder until /make-guardrails is run. -->
-<!-- /make-guardrails will populate this file with project-specific rules. -->
+---
+name: pc-guardrails-project
+description: Project-specific guardrails extracted from ARCHITECTURE.md and project config files. Populated by /make-guardrails. Load this skill before implementing any change to understand boundaries, conventions, and constraints for this codebase.
+license: MIT
+---
+
+<!-- This skill is a placeholder until /make-guardrails is run. -->
+<!-- /make-guardrails will populate this file with project-specific rules. -->

package/skills/pc-make-architecture/structure-template.md

@@ -1,64 +1,64 @@
-# ARCHITECTURE.md structure template
-
-Write (or update) `ARCHITECTURE.md` following this structure. Only include sections relevant to the project; omit sections with no evidence.
-
-- Architecture Overview: what the system is, what problem it solves, major architectural style
-- 1. Project Structure: annotated directory tree with purpose of each major directory
-- 2. High-Level System Diagram: Mermaid diagram of actors, services, data stores, external systems
-- 3. Core Components: each major component: name, responsibility, key files, technologies, inputs/outputs
-  - 3.1 Frontend / User Interface (if present)
-  - 3.2 Backend / Server / API (if present)
-  - 3.3 Shared Libraries / Common Code (if present)
-  - 3.4 CLI / Scripts / Automation (if present)
-- 4. Data Flow: request lifecycle, key user journeys, sequence diagram for main runtime flow
-- 5. Data Stores: all persistent storage: type, purpose, schemas, migration approach
-- 6. External Integrations / APIs: each integration: method, config location, auth, failure behavior
-- 7. Key Technologies: full stack summary with architectural relevance of each
-- 8. Deployment & Infrastructure: build artifacts, env config, containerization, CI/CD, hosting
-- 9. Security Architecture: auth, authz, secrets, input validation, trust boundaries
-- 10. Monitoring & Observability: logging, metrics, tracing, error reporting
-- 11. Performance & Scalability: caching, batching, concurrency, known bottlenecks
-- 12. Development Workflow: local setup, install/dev/test/build/lint commands
-- 13. Testing Strategy: test frameworks, locations, coverage gates, gaps
-- 14. Architectural Decisions & Rationale: key choices with evidence and tradeoffs
-- 15. Constraints, Risks, and Technical Debt: tight coupling, TODOs, operational risks
-- 16. Future Considerations: documented roadmap + reasonable recommendations (labeled as such)
-- 17. Project Identification: name, language, type, runtime, date of review, maintainer
-- 18. Glossary / Acronyms: project-specific terms an agent or new developer needs to know
-
-Append at the very end of the file:
-```
-<!-- Last updated: <current ISO timestamp> -->
-```
-
-Rules:
-- Be specific and concrete: include actual directories, files, modules, commands.
-- Mark anything undiscoverable as "Not evident from the repository".
-- Use Mermaid diagrams where helpful.
-- Write as if this document will be committed and maintained over time.
-
-## Writing rules
-
-These rules govern the voice and shape of every section. The ARCHITECTURE.md is the primary artifact an agent reads to understand the system's invariants — it must teach constraints, not just inventory structure. These are enforced by re-reading each section after generation (see the self-check in the skill).
-
-1. **Every section must answer "what breaks if this is violated," not just "what exists."** A section that only describes structure without stating the constraint it protects and the consequence of crossing it is reference material, not architecture. "The system has four modules" is structure; "Modules must not cross-reference each other in Domain or Application, and flow goes through port interfaces or domain events" is a constraint.
-
-2. **Architectural decisions must carry their rationale and what they superseded.** A decision table row that says "Adopt X" is a fact; "Adopt X because Y, supersedes decision Z which assumed W" is a constraint that teaches an agent why a change would be wrong. If a decision was reached after rejecting an alternative, name the alternative and why it was rejected.
-
-3. **State boundaries as prohibitions with consequences.** "Layering is enforced: Api → Application → Domain" is a constraint. "Api → Application → Domain" alone is a dependency list. "Only the Composition namespace in Api reaches Infrastructure" is a constraint; "Api depends on Infrastructure" is a fact. Prefer the constraint form: name the boundary, state who must not cross it, and what breaks when it is crossed.
-
-4. **Include what was tried and rejected, not just what was chosen.** The most valuable architecture decisions are the ones where an alternative was tested and found wanting. A section that says "dynamic sessions were rejected because they accept no volumes, cost more at scale, and are blocked by policy" teaches an agent more than "the engine runs as a container app."
-
-5. **Narrative over inventory.** Describe how the system behaves, what holds it together, and where the seams are. A reader who understands the constraints can infer the structure; a reader who only sees the structure cannot infer the constraints.
-
-## Self-check (before writing the file)
-
-Re-read every section you are about to write. Then:
-
-1. **Identify inventory-only sections.** If a section describes what exists without stating what breaks when its constraints are violated, rewrite it as constraint-embedded prose or cut it.
-
-2. **Check decision rows.** Every row in the decisions table must carry its rationale. If a decision has no "why," it is a fact, not a decision — cut it or find the rationale.
-
-3. **Scan for bare dependency lists.** "Api depends on Application depends on Domain" is a fact. Rewrite it as: name the boundary, state who must not cross it, and what breaks when it is crossed.
-
-4. **Verify rejected alternatives are present where they matter.** If a significant architectural choice was made, the rejected alternative and the reason for rejection should be in the document. An agent that does not know what was rejected will propose it again.
+# ARCHITECTURE.md structure template
+
+Write (or update) `ARCHITECTURE.md` following this structure. Only include sections relevant to the project; omit sections with no evidence.
+
+- Architecture Overview: what the system is, what problem it solves, major architectural style
+- 1. Project Structure: annotated directory tree with purpose of each major directory
+- 2. High-Level System Diagram: Mermaid diagram of actors, services, data stores, external systems
+- 3. Core Components: each major component: name, responsibility, key files, technologies, inputs/outputs
+  - 3.1 Frontend / User Interface (if present)
+  - 3.2 Backend / Server / API (if present)
+  - 3.3 Shared Libraries / Common Code (if present)
+  - 3.4 CLI / Scripts / Automation (if present)
+- 4. Data Flow: request lifecycle, key user journeys, sequence diagram for main runtime flow
+- 5. Data Stores: all persistent storage: type, purpose, schemas, migration approach
+- 6. External Integrations / APIs: each integration: method, config location, auth, failure behavior
+- 7. Key Technologies: full stack summary with architectural relevance of each
+- 8. Deployment & Infrastructure: build artifacts, env config, containerization, CI/CD, hosting
+- 9. Security Architecture: auth, authz, secrets, input validation, trust boundaries
+- 10. Monitoring & Observability: logging, metrics, tracing, error reporting
+- 11. Performance & Scalability: caching, batching, concurrency, known bottlenecks
+- 12. Development Workflow: local setup, install/dev/test/build/lint commands
+- 13. Testing Strategy: test frameworks, locations, coverage gates, gaps
+- 14. Architectural Decisions & Rationale: key choices with evidence and tradeoffs
+- 15. Constraints, Risks, and Technical Debt: tight coupling, TODOs, operational risks
+- 16. Future Considerations: documented roadmap + reasonable recommendations (labeled as such)
+- 17. Project Identification: name, language, type, runtime, date of review, maintainer
+- 18. Glossary / Acronyms: project-specific terms an agent or new developer needs to know
+
+Append at the very end of the file:
+```
+<!-- Last updated: <current ISO timestamp> -->
+```
+
+Rules:
+- Be specific and concrete: include actual directories, files, modules, commands.
+- Mark anything undiscoverable as "Not evident from the repository".
+- Use Mermaid diagrams where helpful.
+- Write as if this document will be committed and maintained over time.
+
+## Writing rules
+
+These rules govern the voice and shape of every section. The ARCHITECTURE.md is the primary artifact an agent reads to understand the system's invariants — it must teach constraints, not just inventory structure. These are enforced by re-reading each section after generation (see the self-check in the skill).
+
+1. **Every section must answer "what breaks if this is violated," not just "what exists."** A section that only describes structure without stating the constraint it protects and the consequence of crossing it is reference material, not architecture. "The system has four modules" is structure; "Modules must not cross-reference each other in Domain or Application, and flow goes through port interfaces or domain events" is a constraint.
+
+2. **Architectural decisions must carry their rationale and what they superseded.** A decision table row that says "Adopt X" is a fact; "Adopt X because Y, supersedes decision Z which assumed W" is a constraint that teaches an agent why a change would be wrong. If a decision was reached after rejecting an alternative, name the alternative and why it was rejected.
+
+3. **State boundaries as prohibitions with consequences.** "Layering is enforced: Api → Application → Domain" is a constraint. "Api → Application → Domain" alone is a dependency list. "Only the Composition namespace in Api reaches Infrastructure" is a constraint; "Api depends on Infrastructure" is a fact. Prefer the constraint form: name the boundary, state who must not cross it, and what breaks when it is crossed.
+
+4. **Include what was tried and rejected, not just what was chosen.** The most valuable architecture decisions are the ones where an alternative was tested and found wanting. A section that says "dynamic sessions were rejected because they accept no volumes, cost more at scale, and are blocked by policy" teaches an agent more than "the engine runs as a container app."
+
+5. **Narrative over inventory.** Describe how the system behaves, what holds it together, and where the seams are. A reader who understands the constraints can infer the structure; a reader who only sees the structure cannot infer the constraints.
+
+## Self-check (before writing the file)
+
+Re-read every section you are about to write. Then:
+
+1. **Identify inventory-only sections.** If a section describes what exists without stating what breaks when its constraints are violated, rewrite it as constraint-embedded prose or cut it.
+
+2. **Check decision rows.** Every row in the decisions table must carry its rationale. If a decision has no "why," it is a fact, not a decision — cut it or find the rationale.
+
+3. **Scan for bare dependency lists.** "Api depends on Application depends on Domain" is a fact. Rewrite it as: name the boundary, state who must not cross it, and what breaks when it is crossed.
+
+4. **Verify rejected alternatives are present where they matter.** If a significant architectural choice was made, the rejected alternative and the reason for rejection should be in the document. An agent that does not know what was rejected will propose it again.