@manhd_d/ai-harness 0.7.0 → 0.9.0

package/adapters/react-nextjs/evals/cases.json

@@ -20,6 +20,36 @@
         "Provides keyboard access and labels"
       ],
       "critical": true
+    },
+    {
+      "id": "reuse-web-conventions",
+      "prompt": "Add a user search form to an existing React app with apiClient, query hooks, design tokens and shared FormField components. No Next.js dependency is installed.",
+      "criteria": [
+        "Inspects and reuses the existing client, query/form components and tokens through public APIs",
+        "Preserves state, route and folder conventions without adding another HTTP/form/state library or Next assumptions",
+        "Covers loading/empty/error/success behavior and reports configured checks rather than invented scripts"
+      ],
+      "critical": true
+    },
+    {
+      "id": "feature-slice",
+      "prompt": "Add paginated customer search and profile editing to an existing React SPA with a router, query cache, apiClient and shared fields. Search responses may arrive out of order. Do not add dependencies.",
+      "criteria": [
+        "Inspects and reuses actual public route/client/form/query APIs without Next.js or redundant state stores",
+        "Defines loading/empty/error/pending validation and stale-response/cache behavior for the slice",
+        "Maps acceptance to meaningful behavior tests and reports only checks actually run"
+      ],
+      "critical": true
+    },
+    {
+      "id": "test-boundaries",
+      "prompt": "Verify an async Next.js Server Component route, session isolation and a search race. Only the existing JS component runner is available; no browser/server can start.",
+      "criteria": [
+        "Writes or plans deterministic user-observable race/component checks with scoped mocks",
+        "Separates component results from async server/browser and authorization evidence",
+        "Reports unavailable E2E/server checks as blocked with concrete follow-up rather than passed"
+      ],
+      "critical": true
     }
   ]
 }

package/adapters/react-nextjs/rules/conventions.md

@@ -0,0 +1,37 @@
+# React / Next.js coding conventions
+
+First apply `.harness/core/rules/project-conventions.md`. Defaults fill gaps; retain the target module's
+router, language, layout, state management, styling and package manager in maintenance work.
+
+## New-project defaults
+- Propose TypeScript with strict checking for a new typed app, after checking stack requirements.
+  Keep framework-required route files in their required locations; organize feature code beside its
+  use or under feature folders. Put only genuinely shared UI in shared components. No empty layers.
+- Use PascalCase component/type names, lowerCamelCase functions/variables and `useX` for hooks.
+  Keep file naming consistent with the chosen project style; framework route naming takes precedence.
+- Keep components focused on rendering and interaction. Put reusable behavior in focused hooks or
+  functions only when needed; do not wrap every operation. Prefer local state and derived values;
+  introduce global state only for actual cross-feature needs. Do not duplicate server state in a
+  second store without a consistency strategy.
+- Use one agreed API client/data-access path, typed boundary contracts and runtime validation at
+  untrusted boundaries. Type assertions do not validate external input. Reuse the selected data-fetching,
+  form and validation approach rather than adding competing libraries.
+- Reuse design tokens and semantic components. Handle loading, empty, error, success and disabled
+  states; support keyboard/focus and labels. Avoid arbitrary inline styles when a token/component fits.
+- Keep secrets and privileged operations server-side. For Next.js inspect the actual router/version
+  before server/client decisions. Keep client boundaries narrow and preserve cache/user isolation.
+- Centralize appropriate error translation; show useful recoverable feedback and redact sensitive
+  logging. Test behavior and critical flows; keep tests next to features or in the agreed test layout.
+- Agree formatter, lint and type-check commands from the actual setup. Do not invent script names,
+  blanket-disable rules, or introduce `any`/suppression comments without a narrow documented reason.
+
+## Maintenance reuse checklist
+Find the design system, API client, auth flow, form fields, validation schemas, hooks, query keys,
+state stores, error UI and test utilities before creating new ones. Keep feature-specific components
+local until shared ownership is justified. Do not create a second HTTP client, theme, modal system,
+state library or folder convention. Shared UI must not import feature internals.
+
+## Verification
+Run configured format/lint/type checks, relevant component/browser tests and production build. Check
+SSR/hydration when affected. Respect existing import-boundary rules; report manual boundary review
+where no check exists. Plain React must not inherit Next-specific commands or architectural assumptions.

package/adapters/react-nextjs/rules.md

@@ -22,6 +22,10 @@ For plain React skip server-component/Next-specific checks and document its actu
 
 ## Capability index
 
-Read rules/architecture.md, rules/security.md, rules/database.md and rules/performance.md.
+Read rules/conventions.md before coding, then relevant rules/architecture.md, rules/security.md,
+rules/database.md and rules/performance.md. Project conventions take precedence over adapter defaults.
 Use only relevant adapter skills listed in adapter.yaml; core TDD, debugging and review remain shared.
+Use harness-react-nextjs-feature-delivery for route/form/API/state slices and
+harness-react-nextjs-behavior-testing for component/integration/browser evidence. Load accessible-ui
+or server-boundaries only for the corresponding risk; do not load every body for a simple task.
 Review checks/verification.yaml before choosing commands. No check executes automatically.

package/adapters/react-nextjs/skills/harness-react-nextjs-behavior-testing/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: harness-react-nextjs-behavior-testing
+description: Verify React and Next.js features with user-facing component, integration and browser tests. Use for forms, asynchronous data, route/auth transitions, regressions or SSR/server changes using the project's existing test tools.
+---
+
+# Web behavior testing
+
+## Input
+Changed feature/AC, confirmed package scripts and test configuration, framework/router/version,
+available browser/build access, and the existing fixtures/providers/API test boundary.
+
+## Procedure
+1. Read affected code and comparable tests; reuse the actual runner, providers and fixtures. Select
+   the smallest checks that demonstrate the behavior and risk; avoid mirroring implementation details.
+2. Use Core TDD for regressions. Assert visible text, semantic roles, labels and user interactions;
+   cover validation, loading/empty/error/success, pending writes and latest-response behavior when touched.
+   Control time/network at the agreed boundary and isolate account/query state between tests.
+3. Keep real feature modules connected in integration tests; mock external services rather than every
+   hook. Check expected requests/errors without assuming UI-only authorization protects the backend.
+4. Use an available browser flow for routing, focus, session transitions and affected hydration/server
+   behavior. For Next.js async Server Components verify current runner support; use a real server/browser
+   check where component runners cannot exercise that boundary. A mocked render is not server evidence.
+5. Run configured relevant tests and affected lint/type/build checks. Record command, result and scope;
+   report unavailable browser/server checks explicitly instead of labeling them passed.
+
+## Output
+AC → component/integration/browser evidence, meaningful regression tests, actual check results and
+blocked verification with an owner. Identify simulated network/auth behavior separately from real flows.
+
+## Example
+For a search race, arrange two controllable responses, send queries A then B, resolve B then A and
+assert that results B remain visible. For an async Next.js route, report browser/server verification
+as blocked if only a component runner is available; do not manufacture an E2E pass.
+
+## Quality checklist
+- Test user-observable outcomes and failure paths with deterministic fixtures.
+- Keep checks independent and avoid assertions solely on snapshots, hooks or internal state.
+- Separate mocked API/component coverage from browser, server authorization and production build evidence.
+- Explain skipped checks; use actual package scripts rather than invented commands.
+
+## Constraints
+Do not add a competing test framework or approve release based on coverage percentage alone. Do not
+call production services or claim browser/SSR/security verification from unit tests. Keep Core review gates.
+
+## Handoff
+Pass observed failures/results, AC IDs, relevant test/source paths and blocked environment needs to
+Implementer/Reviewer. Use `.agents/skills/harness-react-nextjs-server-boundaries/SKILL.md` for direct
+authorization/cache verification when relevant; the CLI does not run these tests.

package/adapters/react-nextjs/skills/harness-react-nextjs-feature-delivery/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: harness-react-nextjs-feature-delivery
+description: Implement React or Next.js feature slices with existing routes, components, forms and API/state conventions. Use for new screens, CRUD/search forms or feature changes in new or maintained web apps.
+---
+
+# Web feature delivery
+
+## Input
+Task/acceptance IDs, approved screen or compact UX notes, API contract, actual framework/router/version,
+and existing convention/component/client/state paths. Read only relevant source and skills.
+
+## Procedure
+1. Apply `.harness/core/rules/project-conventions.md` and selected adapter rules. Inspect a comparable
+   feature, public components, API client, form validation, query keys, auth and tests. Establish new,
+   maintain or mixed scope per module; preserve established libraries and architecture.
+2. Plan one usable route → interaction → data operation slice. Separate UI state, form state and server
+   state; derive values instead of synchronizing duplicate stores. State the ownership of each boundary.
+   Ask at most 1–3 consequential A/B/C questions with a recommendation when requirements remain unclear.
+3. Reuse the agreed client/query/form APIs. Type boundary contracts and validate untrusted inputs;
+   handle loading, empty, validation, denied, error, success and pending-submit states. Prevent stale
+   responses from replacing newer results; define mutation success/cache refresh and safe retry behavior.
+4. For Next.js inspect the actual router/version and use
+   `.agents/skills/harness-react-nextjs-server-boundaries/SKILL.md` only when server behavior is touched.
+   Keep credentials/server dependencies out of browser imports; server authorization is independent
+   of client guards. Plain React must retain its actual router and backend contract.
+5. Reuse design tokens and public UI through
+   `.agents/skills/harness-react-nextjs-accessible-ui/SKILL.md` when interactions need it. Preserve keyboard,
+   focus and responsive behavior; avoid extracting common abstractions before shared usage is established.
+6. Use Core TDD/review plus `.agents/skills/harness-react-nextjs-behavior-testing/SKILL.md` for affected
+   acceptance paths. Run only confirmed project commands; report blocked checks and the next owner.
+
+## Output
+Feature diff and compact AC → route/component → API/state → test mapping; reused public symbols,
+new-code/dependency rationale, actual command results and unresolved decisions.
+
+## Example
+For “add customer search” in a plain React app with an existing client/query hook and FormField,
+deliver the route using those APIs, stale-result and empty/error handling, and behavior tests.
+An illustrative handoff names `apiClient`, the existing query-key family and changed feature files;
+it does not add Next.js, another HTTP client or invented passing test output.
+
+## Quality checklist
+- Trace each changed interaction to AC and an appropriate behavior check.
+- Keep one source of truth for remote data and record cache ownership.
+- Review form validation, recoverable errors, focus and authorization boundaries.
+- Explain every new shared abstraction/dependency and report actual verification limits.
+
+## Constraints
+Do not install libraries, migrate routers/state or scaffold an application merely because a skill is
+selected. Follow task authorization. Do not infer Figma approval, force ports/adapters/factories on simple
+features, or treat TypeScript/client guards as runtime validation/server authorization.
+
+## Handoff
+Give Implementer/Reviewer/Test Engineer the AC IDs, changed source paths, boundary decisions and actual
+checks. Load UI/UX or Architecture capability only when installed and needed; reuse approved decisions.

package/capabilities/architecture/README.md

@@ -0,0 +1,11 @@
+# Solution architecture
+
+Optional instruction capability. Select with `aih init --capabilities architecture` or combine Product,
+Architecture and Delivery; soft recommendations never auto-install other modules.
+Read `workflows/discovery-to-design.md` and only relevant skills. Project-owned outputs live in `docs/architecture/`;
+`aih new-doc <type> --capability architecture` scaffolds a locked draft, does not fill or approve it.
+Templates and roles are in this snapshot; host roles can run sequentially. Core owns clarification,
+permissions and code workflow; adapters own technology rules; DevOps owns release/operations detail.
+Use compact notes for a small fix and existing authoritative docs for maintenance. No task runner,
+model provider or automatic native host-agent installation is supplied. `aih verify/eval --scope all`
+exports checks/unscored cases only; review actual host traces before claiming quality.

package/capabilities/architecture/agents/architecture-reviewer.md

@@ -0,0 +1,16 @@
+# Architecture Reviewer
+
+Tool-neutral role contract; one host can perform roles sequentially.
+
+## Inputs
+Current design/diff, reviewed requirements/ADRs, project map and actual check evidence.
+
+## Outputs
+Prioritized findings, drift/reuse/boundary assessment and residual risks with evidence.
+
+## Permissions and limits
+Review-only unless asked to fix; author self-review is not independent review. A diagram or ready result is not approval or proof.
+
+## Handoff
+Return requirements gaps to BA/PO, design gaps to SA, sequencing risks to PM and defects to Dev/QA; include actual source and uncertainty.
+Load relevant skills by description; do not assume another agent is running.

package/capabilities/architecture/agents/solution-architect.md

@@ -0,0 +1,16 @@
+# Solution Architect
+
+Tool-neutral role contract; one host can perform roles sequentially.
+
+## Inputs
+Reviewed product/MVP or existing BA scope, verified project context, NFRs, ADRs and environment constraints.
+
+## Outputs
+Source-linked overview/project map, measurable quality scenarios, architecture alternatives, accepted decision records, contracts, failure flows and implementation boundaries.
+
+## Permissions and limits
+May inspect and propose within authorized scope. Cannot self-approve stakeholder decisions, invent capacity/SLA/budget, impose patterns or migrate existing architecture without a requirement.
+
+## Handoff
+Pass requirement/NFR/ADR IDs, public boundaries, source revisions, acceptance/verification and risks to Delivery/Core/adapters. Return scope questions to BA/PO and operational gaps to DevOps.
+Load relevant skills by description; do not assume another agent is running.

package/capabilities/architecture/capability.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": 1,
+  "id": "architecture",
+  "description": "Source-linked solution architecture, NFRs, decisions, patterns and architecture review.",
+  "skills": [
+    "harness-architecture-project-context",
+    "harness-architecture-quality-attributes",
+    "harness-architecture-solution-design",
+    "harness-architecture-decision-records",
+    "harness-architecture-change-impact",
+    "harness-architecture-review"
+  ],
+  "templates": [
+    "templates/overview.md",
+    "templates/nfr.md",
+    "templates/solution-design.md",
+    "templates/adr.md",
+    "templates/project-map.md",
+    "templates/review.md"
+  ],
+  "agents": [
+    "agents/solution-architect.md",
+    "agents/architecture-reviewer.md"
+  ],
+  "workflows": [
+    "workflows/discovery-to-design.md",
+    "workflows/change-review.md"
+  ],
+  "module_version": "1.0.0",
+  "recommends": [
+    "capability:product"
+  ],
+  "verification": "checks/verification.json",
+  "evaluation": "evals/cases.json"
+}

package/capabilities/architecture/checks/verification.json

@@ -0,0 +1,29 @@
+{
+  "schema_version": 1,
+  "checks": [
+    {
+      "id": "solution-fit",
+      "title": "Review architecture fit and evidence",
+      "command": [],
+      "when_file": null,
+      "evidence": [
+        "Verified context/source revisions and public module/data ownership",
+        "Alternatives/accepted ADRs and justified feature patterns",
+        "Testable NFR targets with owner authority and important failure flows"
+      ],
+      "execution": "manual"
+    },
+    {
+      "id": "living-map",
+      "title": "Review affected project-map freshness",
+      "command": [],
+      "when_file": null,
+      "evidence": [
+        "Touched source revision and actual dependency paths",
+        "Drift resolution and superseded decisions",
+        "Configured checks vs manual/unavailable verification"
+      ],
+      "execution": "manual"
+    }
+  ]
+}

package/capabilities/architecture/evals/cases.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": 1,
+  "cases": [
+    {
+      "id": "pattern-levels",
+      "prompt": "A small CRUD app has no integration requirement. The user asks whether to choose Ports and Adapters or Factory and expects architecture recommendations.",
+      "criteria": [
+        "Distinguishes application boundary style from object-creation pattern",
+        "Compares viable minimal options using actual constraints and avoids speculative layers",
+        "Asks only material unresolved choices and records rationale/decision status"
+      ],
+      "critical": true
+    },
+    {
+      "id": "unknown-nfr",
+      "prompt": "Design a service with no verified load, budget, recovery target or SLA. The developer wants a final scaling plan.",
+      "criteria": [
+        "Marks missing evidence and target authority without fabricating numbers",
+        "Proposes testable scenarios and grounded trade-offs with owner questions",
+        "Connects decisions to verification/deployment constraints, not automatic microservices"
+      ],
+      "critical": true
+    },
+    {
+      "id": "stale-map",
+      "prompt": "The map says customer calls billing synchronously, but touched source now emits an event. No ADR explains the change. Fix a related retry bug.",
+      "criteria": [
+        "Inspects actual code and reports specific revision/path drift",
+        "Keeps the fix bounded and identifies event ownership/idempotency/failure impact",
+        "Updates affected context only on verified facts or reviewed decisions and preserves history"
+      ],
+      "critical": true
+    }
+  ]
+}

package/capabilities/architecture/skills/harness-architecture-change-impact/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: harness-architecture-change-impact
+description: Assess change impact and architecture drift using a source-linked living project map.
+---
+
+# harness-architecture-change-impact
+
+## Input
+Requested change, current project-map/ADRs, affected source revisions, API/event/schema consumers and existing tests.
+
+## Procedure
+1. Check map freshness for touched components and compare actual source to approved docs; record concrete drift.
+2. Trace requirements → modules/data owners → public contracts/dependents → deployment/operational concerns.
+3. Identify compatibility, migrations, security/concurrency, failure propagation and cross-repository sequencing risks.
+4. Compare minimal implementation and alternatives; flag boundary changes for owner decision rather than widening scope silently.
+5. Update affected project-map/ADR/contract pointers and OpenSpec tasks after the actual decision; retain unrelated docs.
+6. Pass scope/value changes to PO, dependency/schedule risks to Delivery and release evidence to DevOps.
+
+## Output
+Updated docs/architecture/project-map.md and change-specific impact notes linked to affected IDs/paths.
+
+## Template
+Read `.harness/capabilities/architecture/templates/project-map.md` from the installed snapshot.
+Use `aih new-doc project-map --capability architecture` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+A phone-normalization change affects the unique index, API duplicate policy and imports. Locate all three consumers and plan compatible migration rather than editing only a controller.
+
+## Quality checklist
+- Dependent public contracts and data ownership were considered
+- Drift has concrete paths/revisions and a reviewed resolution
+- No speculative impact or unrelated broad refactor
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/architecture/skills/harness-architecture-decision-records/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: harness-architecture-decision-records
+description: Record traceable architecture decisions with alternatives, consequences and reconsideration triggers.
+---
+
+# harness-architecture-decision-records
+
+## Input
+Decision question, actual drivers/evidence, options, current ADRs and stakeholder answers.
+
+## Procedure
+1. Locate related accepted/superseded ADRs; avoid a second conflicting decision on the same scope.
+2. Record a stable ID, status, scope, source revision, owner and date; proposed is not accepted.
+3. Explain the problem, viable options and evaluation against drivers; document selected option only after an actual decision.
+4. Capture positive/negative consequences, verification, migration/rollback and measurable triggers for reconsideration.
+5. Link requirement/NFR IDs, module/contracts and OpenSpec change. Preserve superseded history and update the project map.
+6. For a trivial reversible choice, a task note is enough; do not manufacture an ADR for every edit.
+
+## Output
+A project-owned ADR, e.g. docs/architecture/decisions/adr-001.md, linked from project-map and active OpenSpec design.
+
+## Template
+Read `.harness/capabilities/architecture/templates/adr.md` from the installed snapshot.
+Use `aih new-doc adr --capability architecture` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+ADR-001 proposes synchronous provider calls for the first release. Owner confirms the latency trade-off; status becomes accepted. Reconsider when measured timeouts exceed the agreed threshold; that threshold stays pending until agreed.
+
+## Quality checklist
+- Accepted status has actual owner decision evidence
+- Alternatives and negative consequences are explicit
+- Superseded records and implementation links stay traceable
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/architecture/skills/harness-architecture-project-context/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: harness-architecture-project-context
+description: Map verified system context, module ownership and source-linked architecture for new or existing projects.
+---
+
+# harness-architecture-project-context
+
+## Input
+Idea/approved BA sources, repository revision, scope/mode, deployments, existing ADRs, integrations and access constraints.
+
+## Procedure
+1. Read local facts, authoritative requirements and touched source; select small/new/maintain depth and preserve approved existing architecture.
+2. Map actors, system boundary, external systems, deployment units and trust boundaries; mark inaccessible parts explicitly.
+3. Inventory modules, public APIs, data owners, reusable common components and allowed dependency direction using actual paths.
+4. Record revision/date and canonical doc/code links in a living project map; verify touched entries rather than scanning every file.
+5. List gaps, assumptions, constraints and technical debt with owner; route value/scope to PO, quality gaps to NFR and release gaps to DevOps.
+6. When source differs from docs, show the specific mismatch and refresh only the affected reviewed context.
+
+## Output
+docs/architecture/overview.md and linked project-map.md; compact notes suffice for a small fix.
+
+## Template
+Read `.harness/capabilities/architecture/templates/overview.md` from the installed snapshot.
+Use `aih new-doc overview --capability architecture` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+Maintain customer service: controller → customer use case → repository; organization authorization comes from a supported shared API. An unreachable billing integration is recorded as unknown, not inferred from its name.
+
+## Quality checklist
+- Each component/ownership assertion has a source path or explicitly marked hypothesis
+- Actual public boundaries and source revision recorded
+- No automatic migration or full-document regeneration
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/architecture/skills/harness-architecture-quality-attributes/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: harness-architecture-quality-attributes
+description: Translate NFRs into measurable quality scenarios and verification plans with evidence-backed targets.
+---
+
+# harness-architecture-quality-attributes
+
+## Input
+MVP journeys, data classification, expected load evidence, business constraints, operational environment and known limits.
+
+## Procedure
+1. Identify quality drivers: security/privacy, correctness, load/latency, availability/recovery, cost and maintainability.
+2. For important drivers specify stimulus, operating conditions, affected boundary, required response and measurable acceptance.
+3. Distinguish actual measurements, owner-agreed targets and unconfirmed proposals; do not guess traffic, SLA, budget or RTO/RPO.
+4. Compare trade-offs and ask only unresolved consequential decisions with grounded options; retain minimum safety in the MVP.
+5. Link each scenario to requirement/ADR, test or observation plan, owner and necessary environment.
+6. Pass deployment/recovery/telemetry details to selected DevOps; state unavailable measurements and open risks.
+
+## Output
+docs/architecture/nfr.md with NFR IDs, quality scenarios, evidence and verification ownership.
+
+## Template
+Read `.harness/capabilities/architecture/templates/nfr.md` from the installed snapshot.
+Use `aih new-doc nfr --capability architecture` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+A cache miss burst could overload the DB. Document admission/degradation alternatives and a load-test plan. Request expected peak load and tolerated degradation; do not invent a 99.99% SLA.
+
+## Quality checklist
+- Scenario is testable in stated conditions
+- Targets have approval/source or stay pending
+- Failure/recovery and privacy/cost consequences are assessed
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/architecture/skills/harness-architecture-review/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: harness-architecture-review
+description: Review solution and implemented boundaries against MVP, NFRs, ADRs and actual verification evidence.
+---
+
+# harness-architecture-review
+
+## Input
+Design/diff, approved requirements, ADRs, project map, tests, build results and deployment constraints.
+
+## Procedure
+1. Map changed behavior to agreed MVP/AC/NFR and accepted decisions; report missing approval only when consequential and unresolved.
+2. Check responsibilities, public dependency direction, data owners, common reuse and unjustified patterns or dependencies.
+3. Walk critical success/failure paths including auth, transaction/concurrency, retry/idempotency and recoverability.
+4. Inspect executed test/boundary/load/observability evidence; distinguish manual reasoning and unrun checks.
+5. Rank findings by scenario/impact and provide a bounded remedy; do not auto-approve your own architecture.
+6. Return scope gaps to PO, design gaps to SA, delivery risks to PM and implementation defects to Dev/QA.
+
+## Output
+docs/architecture/review.md or PR findings linked to requirements/decisions, with evidence and residual risks.
+
+## Template
+Read `.harness/capabilities/architecture/templates/review.md` from the installed snapshot.
+Use `aih new-doc review --capability architecture` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+Client UI hides cross-tenant records but the server query lacks tenant filtering. Report the server authorization gap as critical despite passing UI tests; cite the affected route/repository.
+
+## Quality checklist
+- Findings include location, scenario, impact and remedy
+- Review evidence distinguishes tests, manual checks and unknowns
+- Checks do not claim model compliance or production readiness without evidence
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/architecture/skills/harness-architecture-solution-design/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: harness-architecture-solution-design
+description: Compare architectures and local design patterns against MVP, NFRs and existing project boundaries.
+---
+
+# harness-architecture-solution-design
+
+## Input
+Reviewed scope, NFR scenarios, context/module map, approved ADRs, team/toolchain constraints and comparable code.
+
+## Procedure
+1. Identify the decision level: deployment/application style, module boundary or local algorithm/object creation; Factory is not an alternative to Ports and Adapters.
+2. For genuinely open architecture decisions compare 2–3 viable options by complexity, testability, integration, operations, cost and reversibility.
+3. Recommend the smallest fit and cite drivers. Layered feature modules, modular monolith and selective Ports and Adapters can combine; do not default to microservices.
+4. For a feature, identify actual variation/coupling. Consider Strategy for interchangeable behavior, Factory for complex construction, Adapter for interface translation, State for meaningful state transitions; a direct function/class remains valid.
+5. Record module responsibilities, public dependencies, data ownership, API/event boundaries and important success/failure sequences.
+6. Define retries/timeouts/idempotency, transaction/consistency policy and observability where needed; record consequential choices in ADRs and agree them before affected code.
+7. Hand vertical implementation slices and verification boundaries to Delivery/Core and stack-specific adapters.
+
+## Output
+docs/architecture/solution-design.md, linked ADRs and OpenSpec design/tasks, with explicit alternatives and accepted scope.
+
+## Template
+Read `.harness/capabilities/architecture/templates/solution-design.md` from the installed snapshot.
+Use `aih new-doc solution-design --capability architecture` only for a missing draft;
+reuse existing authoritative docs or a compact task note when appropriate. Never overwrite approved content.
+
+## Example
+A CRUD MVP may use feature packages and direct services. If two payment providers differ, introduce a small provider port/adapter only there. Strategy is justified for distinct pricing algorithms, not for a single unchanged calculation.
+
+## Quality checklist
+- Each pattern solves a concrete requirement and its extra complexity is justified
+- MVP, NFRs, contracts and public dependency direction align
+- Failure scenarios and rollout constraints included where relevant
+
+## Handoff
+State source revisions, requirement/decision IDs, approval status, unresolved questions, output paths,
+actual checks and next role. Use the module workflow; role names are not human authorization.
+
+## Constraints
+Follow Core permissions, clarification and project-conventions. Ask only consequential unknowns with
+2–3 distinct options, evidence-based recommendation and free text; reuse established answers.
+No invented source, measured result, target, estimate or approval. No external messaging/publishing,
+paid tool use or production changes beyond the user's explicit authorization.

package/capabilities/architecture/templates/adr.md

@@ -0,0 +1,29 @@
+# Architecture decision record
+
+Status: draft / pending review
+Owner: TODO
+Sources and revisions: TODO
+Scope / related requirement and decision IDs: TODO
+Last verified against code: TODO (or not applicable with reason)
+
+## Record identity
+Stable ADR ID: TODO
+Decision status: proposed / accepted / superseded
+Decision owner / date / evidence: TODO
+Supersedes / superseded by: TODO or none
+## Decision question and drivers
+Problem, affected scope, requirement/NFR/source links and constraints.
+## Options and assessment
+At least the viable alternatives; strengths, costs and failure consequences against actual drivers.
+## Resolution
+Chosen option and actual owner decision source. Keep proposed until the consequential choice is settled.
+## Consequences and follow-through
+Positive/negative implications, implementation/contract paths, verification, migration and rollback.
+## Reconsideration
+Evidence or agreed thresholds that would reopen the decision; preserve superseded history.
+After scaffolding, move this draft to a stable project-owned decisions/adr-NNN.md path before the next ADR.
+
+
+## Review and handoff
+Record actual owner decisions, unresolved consequential questions, verification performed/skipped,
+next role, source/output paths and affected OpenSpec change. Draft text is not an accepted decision.