@manhd_d/ai-harness 0.7.0 → 0.9.0

package/docs/tool-setup/README.md

@@ -0,0 +1,70 @@
+# Setup AI Harness with coding tools
+
+Official discovery docs reviewed 2026-10-12. Authenticate/install the chosen host with its official
+instructions, then run Harness in the actual repository. Host/version/account capabilities vary;
+these are setup recipes, not a claim that native client behavior was tested in this workspace.
+
+## Common setup
+```bash
+npm install -g @manhd_d/ai-harness
+aih init --adapters java-spring --capabilities product,architecture,delivery
+aih check
+aih setup
+aih doctor
+aih skills
+```
+Node.js 22+ is required by Harness; app stack remains independent. Replace adapter selection with
+react-nextjs/react-native/astro as appropriate. A coding-only maintain task can use just Core + adapter.
+For an existing install, edit .harness/project.json and reviewed update --dry-run/update/check.
+
+Fill .harness/local.md with mode, source docs/MVP/ADRs, public boundaries and actual commands; use
+[project configuration](../project-configuration.md) for Maven/JDK/settings and ignored machine paths.
+Do not bypass runtime permission policy or publish credentials. Configure GitHub/Figma/Confluence MCP
+only when needed, with the host's official setup and authorized access; Harness does not connect accounts.
+
+| Host | Project entry | Skill handling | Guide |
+| --- | --- | --- | --- |
+| Codex CLI/IDE | AGENTS.md and applicable nested/override instructions | .agents/skills native discovery | [Codex](codex.md) |
+| Claude Code | Direct AGENTS support varies with current configuration/version; CLAUDE.md import fallback | .claude/skills wrapper when native slash invocation is desired; manual canonical read always possible | [Claude Code](claude-code.md) |
+| Cursor | AGENTS.md; existing .cursor/rules may also apply | .agents/skills discovery | [Cursor](cursor.md) |
+| Copilot | Client-specific AGENTS support or .github/copilot-instructions.md pointer | CLI supports .agents/skills; IDE support depends on client/version | [Copilot](copilot.md) |
+| Gemini CLI | GEMINI.md import or context.fileName includes AGENTS.md | .agents/skills workspace alias | [Gemini CLI](gemini-cli.md) |
+
+Preserve existing host files; merge only a reviewed pointer/import, never replace the whole config.
+Bridges are project-owned and not managed by aih. Keep one canonical skill body in .agents/skills;
+never copy every rule into each host config or advertise markdown role files as native agents.
+
+## Read-only setup smoke test
+Ask the host:
+```text
+Read the applicable AGENTS.md and .harness/local.md. Do not modify files or execute commands.
+State the selected adapters/capabilities and exact installed paths for solution-framing and one
+relevant skill. Summarize current project mode, known MVP/architecture decisions and missing facts.
+Explain which declarations the configured test command comes from; do not claim any test ran.
+```
+Expected: actual source paths, correct selection and no fabricated file/command/result. If automatic
+skill discovery fails, explicitly ask to read .agents/skills/<installed-name>/SKILL.md. `aih skills`
+is a catalog, and `aih skill <name>` prints canonical instructions; neither invokes an AI model.
+
+## Start prompts
+| Task | Prompt |
+| --- | --- |
+| Idea → MVP | Read Product product-to-solution; clarify the useful user journey, in/out scope and minimum quality before proposing architecture. |
+| Existing BA docs | Use the approved source/revision, extract only this change's requirements and gaps; preserve authoritative docs. |
+| SA design | Read Architecture discovery-to-design; compare minimal viable options, NFRs and justified feature patterns with actual decision sources. |
+| Maintain | Inspect touched module/code/tests and public common APIs; follow existing architecture and update only affected project-map entries. |
+| Delivery | Plan value slices/dependencies using real team estimates; unknown dates remain unknown; link AC/ADRs/OpenSpec. |
+
+## Update and troubleshoot
+Update the global CLI, then review snapshot update --dry-run/update/check. Restart/reload host discovery
+where required; read-only smoke again after setup changes. Keep custom host bridges and local.md.
+If a managed file conflicts, reconcile with Git rather than editing lock hashes. Check workspace root,
+nested override precedence, host context/trust settings, module selection and installed skill paths.
+Private VPN/tool access may be unavailable remotely; report blocked builds rather than inventing success.
+No logged-in host/MCP or live-agent smoke was run for these docs; follow each linked official guide.
+
+## Agent/model preferences
+
+Review [Agent configuration](../agent-configuration.md) and run `aih setup --host <id>` for a declared
+routing plan. Validate native model/effort in the actual picker/client; no account availability is
+probed or host config overwritten. Incompatible defaults need your explicit provider/model mapping.

package/docs/tool-setup/claude-code.md

@@ -0,0 +1,57 @@
+# Claude Code
+
+Install/authenticate with [official setup](https://code.claude.com/docs/en/setup), then follow
+[common setup](README.md) and launch `claude` at the repository root.
+
+## Instructions
+Current Claude documentation describes direct AGENTS.md support with version/configuration conditions.
+If direct discovery is unavailable, add the following import to an existing project CLAUDE.md, or
+create the file if absent, without discarding any other content:
+```markdown
+@AGENTS.md
+```
+Check the host's loaded project instructions and nested/global files. Keep one canonical AGENTS;
+do not add a hook that prints a duplicate copy. The import remains a documented compatibility option.
+
+## Skills
+Claude documents .claude/skills for project skills. Harness does not assume .agents/skills is a native
+Claude skill location. Manual canonical loading from AGENTS instructions works without slash registration.
+If you want native invocation for a selected skill, create a small project-owned wrapper at
+.claude/skills/harness-product-mvp-definition/SKILL.md:
+```markdown
+---
+name: harness-product-mvp-definition
+description: Define an MVP using this project's installed AI Harness instructions.
+---
+Read the applicable AGENTS.md and then the canonical project file
+.agents/skills/harness-product-mvp-definition/SKILL.md. Follow its procedure and handoff;
+keep actual owner decisions and verification status explicit.
+```
+Then use `/harness-product-mvp-definition` in a supporting session. This wrapper is a pointer,
+not a copied skill body; maintain only needed wrappers and preserve existing native skills.
+
+## Verify and use
+Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
+known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
+ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
+all skill bodies. Application commands come from local.md/environment.json and actual build files.
+Follow host permission settings; no instruction creates missing account, network or tool access.
+
+## Update / troubleshooting
+Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
+review nested instructions and restart/reload the host when discovery changes. A Harness integrity
+check is separate from host discovery, app build or behavioral compliance. Native client login/setup
+was not exercised here; official references below establish the documented discovery mechanism.
+
+## Official references (checked 2026-10-12)
+- [Memory, AGENTS and imports](https://code.claude.com/docs/en/memory)
+- [Project skills and invocation](https://code.claude.com/docs/en/skills)
+
+## Native model configuration
+Use [Agent preferences](../agent-configuration.md) with an explicitly available Anthropic model or
+reviewed host mapping. OpenAI Sol/Astra preferences cannot run directly in Claude Code. Native model
+selection follows [official model config](https://code.claude.com/docs/en/model-config); use /model and
+client-supported effort controls, preserving existing settings/authentication. Native per-role agents
+use [official subagent format](https://code.claude.com/docs/en/sub-agents) in .claude/agents with model
+and supported effort settings. Role contracts can be referenced by a short instruction. aih does not
+write these files, infer account access or equate native Claude reasoning with OpenAI reasoning.

package/docs/tool-setup/codex.md

@@ -0,0 +1,44 @@
+# Codex CLI and IDE
+
+Install/authenticate Codex from [official CLI](https://developers.openai.com/codex/cli/) or
+[IDE extension](https://developers.openai.com/codex/ide/), then follow [common setup](README.md).
+Launch `codex` or open the IDE at the initialized repository root.
+
+## Instructions and skills
+Codex reads AGENTS.md through its project hierarchy and can prefer AGENTS.override.md. Inspect
+applicable global/nested overrides when behavior differs; do not overwrite user defaults.
+Harness exposes declared skills in .agents/skills, the documented repository skill path. Start a new
+session after setup/update if needed; ask for one installed skill by name or canonical path.
+Markdown role contracts in .harness/core/agents and selected capabilities are read by the host;
+they are not automatically installed as native Codex subagents. .harness/local.md remains project context.
+
+## Verify and use
+Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
+known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
+ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
+all skill bodies. Application commands come from local.md/environment.json and actual build files.
+Follow host permission settings; no instruction creates missing account, network or tool access.
+
+## Update / troubleshooting
+Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
+review nested instructions and restart/reload the host when discovery changes. A Harness integrity
+check is separate from host discovery, app build or behavioral compliance. Native client login/setup
+was not exercised here; official references below establish the documented discovery mechanism.
+
+## Official references (checked 2026-10-12)
+- [AGENTS discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md)
+- [Skill discovery](https://learn.chatgpt.com/docs/build-skills)
+
+## Native model configuration
+Follow [Agent preferences](../agent-configuration.md), then verify model access and supported effort.
+The official [config guide](https://learn.chatgpt.com/docs/config-file/config-basic) supports a reviewed
+merge into .codex/config.toml for CLI/IDE:
+```toml
+model = "gpt-6.1-sol"
+model_reasoning_effort = "medium"
+```
+For deliberate native agents use the current [subagent guide](https://learn.chatgpt.com/docs/agent-configuration/subagents).
+Standalone .codex/agents/*.toml uses name, description and developer_instructions, with optional model
+and model_reasoning_effort. Keep a small instruction pointing to the installed role/skill, not duplicated
+bodies. No files are generated/applied by aih; actual schema/client/account and thread-limit semantics
+must be checked. A normal session does not switch model automatically per Harness role.

package/docs/tool-setup/copilot.md

@@ -0,0 +1,42 @@
+# GitHub Copilot IDE and CLI
+
+Install/sign in with [official Copilot docs](https://docs.github.com/en/copilot). In the IDE, open
+the project and use the supported Agent mode; for CLI start the authenticated `copilot` client at
+the root. Apply [common setup](README.md).
+
+## Instructions
+Support for AGENTS and skills varies between IDE/CLI/cloud features. Preserve existing settings.
+For a repository-wide IDE bridge, merge into .github/copilot-instructions.md:
+```markdown
+Before implementation, read the applicable root/nested AGENTS.md and .harness/local.md.
+Follow the installed Core/selected capability workflows and only the relevant skill in .agents/skills.
+Report exact source paths, owner decisions and actual verification; do not infer test results.
+```
+This asks the agent to read files, not an automatic content import. Verify with the smoke prompt.
+Copilot CLI documents .agents/skills as a project skill directory; `/skills reload` and
+`/skills info <name>` can verify discovery there. IDE support must be checked for that specific client;
+use the canonical manual path when automatic discovery is unavailable.
+
+## Verify and use
+Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
+known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
+ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
+all skill bodies. Application commands come from local.md/environment.json and actual build files.
+Follow host permission settings; no instruction creates missing account, network or tool access.
+
+## Update / troubleshooting
+Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
+review nested instructions and restart/reload the host when discovery changes. A Harness integrity
+check is separate from host discovery, app build or behavioral compliance. Native client login/setup
+was not exercised here; official references below establish the documented discovery mechanism.
+
+## Official references (checked 2026-10-12)
+- [IDE repository instructions](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide)
+- [CLI skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
+
+## Agent routing
+
+Read [Agent preferences](../agent-configuration.md). Verify current model picker/account and effort
+controls; aih setup --host copilot returns declarations only. Native per-role model switching or
+concurrency requires specific client support; otherwise perform roles sequentially with the selected
+session model. Never substitute premium or overwrite existing host settings automatically.

package/docs/tool-setup/cursor.md

@@ -0,0 +1,44 @@
+# Cursor
+
+Install/sign in via [official Cursor docs](https://cursor.com/docs). Open the repository folder and
+Agent, then follow [common setup](README.md).
+
+## Instructions and skills
+Cursor supports project/nested AGENTS.md and .agents/skills. Preserve existing .cursor/rules and
+check their scope with project conventions before adding another rule. Ask Agent to read applicable
+AGENTS/local.md and use one installed skill; inspect discovery in the current client.
+If a specific workspace needs an explicit rule pointer, create a project-owned .cursor/rules/harness.mdc:
+```markdown
+---
+description: Use the installed AI Harness for this repository.
+alwaysApply: true
+---
+Read the applicable AGENTS.md and its referenced project context before changing code.
+Load only the installed skill needed for the task from .agents/skills.
+```
+Do not copy the full Harness snapshot into the rule. AGENTS already supplies the canonical entry;
+use this bridge only if needed, avoiding contradictory project/global/nested instructions.
+
+## Verify and use
+Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
+known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
+ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
+all skill bodies. Application commands come from local.md/environment.json and actual build files.
+Follow host permission settings; no instruction creates missing account, network or tool access.
+
+## Update / troubleshooting
+Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
+review nested instructions and restart/reload the host when discovery changes. A Harness integrity
+check is separate from host discovery, app build or behavioral compliance. Native client login/setup
+was not exercised here; official references below establish the documented discovery mechanism.
+
+## Official references (checked 2026-10-12)
+- [Rules and AGENTS](https://cursor.com/docs/rules)
+- [Skills and .agents discovery](https://cursor.com/docs/skills)
+
+## Agent routing
+
+Read [Agent preferences](../agent-configuration.md). Verify current model picker/account and effort
+controls; aih setup --host cursor returns declarations only. Native per-role model switching or
+concurrency requires specific client support; otherwise perform roles sequentially with the selected
+session model. Never substitute premium or overwrite existing host settings automatically.

package/docs/tool-setup/gemini-cli.md

@@ -0,0 +1,41 @@
+# Gemini CLI
+
+Install/authenticate from [official docs](https://geminicli.com/docs/), follow [common setup](README.md)
+and launch `gemini` at the initialized root.
+
+## Instructions and skills
+Gemini uses GEMINI.md by default. Merge an import into the existing root GEMINI.md if needed:
+```markdown
+@./AGENTS.md
+```
+Alternatively, merge `context.fileName` in the existing project settings.json so the list includes
+AGENTS.md while preserving other configured context names. Do not replace the entire settings file
+or use both routes to inflate context unnecessarily. `/memory show` checks loaded content and
+`/memory reload` refreshes it according to current official docs.
+Gemini documents .agents/skills as a workspace alias. Avoid duplicating the same skills in
+.gemini/skills; check current discovery and ask for the installed skill needed by the task.
+
+## Verify and use
+Run the [read-only smoke prompt](README.md) before an implementation task. Check actual paths and
+known decisions, then use the idea/document/SA/maintain prompts on that page. If discovery is missing,
+ask to read the exact installed `.agents/skills/harness-*/SKILL.md` relevant to the task; do not paste
+all skill bodies. Application commands come from local.md/environment.json and actual build files.
+Follow host permission settings; no instruction creates missing account, network or tool access.
+
+## Update / troubleshooting
+Use the common reviewed CLI/snapshot update procedure. Preserve existing project/global host config,
+review nested instructions and restart/reload the host when discovery changes. A Harness integrity
+check is separate from host discovery, app build or behavioral compliance. Native client login/setup
+was not exercised here; official references below establish the documented discovery mechanism.
+
+## Official references (checked 2026-10-12)
+- [Context/imports/settings](https://geminicli.com/docs/cli/gemini-md/)
+- [Workspace skill aliases](https://geminicli.com/docs/cli/skills/)
+
+## Native model configuration
+Use [Agent preferences](../agent-configuration.md) with an explicitly available Google/Vertex model
+or reviewed mapping. Check the native /model picker against [official model selection](https://geminicli.com/docs/cli/model/).
+Main --model selection does not override native subagent models; configure them separately following
+[official subagents](https://geminicli.com/docs/core/subagents/) and your client's generation settings.
+Reasoning/thinking controls are model-specific. No OpenAI model is assumed to run directly here and
+no native JSON/agent file is created by aih. Verify actual delegation and capacity before parallel work.

package/docs/versioning.md

@@ -1,5 +1,7 @@
 # Versioning and migration
 
+Maintainer entry point: [Harness maintenance and impact matrix](harness-maintenance.md).
+
 Framework version is in harness.yaml and package.json; keep both and package-lock.json synchronized. Use three-part SemVer releases and Git tags vX.Y.Z after review.
 0.6.0 was initially published manually to npm. Future versions are prepared by Release Please after human PR review; do not publish directly from a feature PR.
 
@@ -102,3 +104,39 @@ No new configuration/lock schema version: 0.5 Product templates, `aih new-doc`,
 ## Foundation hardening (unreleased after 0.6)
 
 Module contracts gain optional version and dependency fields without changing config/lock schema 1. Existing consumer snapshots retain default adapter-only verify/eval. After a reviewed update, `--scope all` enables locked Core/capability/composition evaluation, and `--scope core` works in core-only projects. Feature branches keep the latest release version; Release Please's generated PR chooses and synchronizes the next number. Use tagged releases for other consumers rather than interpreting an unreleased commit as a published update.
+
+## Project coding conventions (unreleased)
+
+Config and lock remain schema 1. Core adds project-conventions.md; Java/Spring, React/Next.js and React Native module contracts advance to 1.1.0 with conventions, manual checks and evaluation cases. Distribution version remains release-PR owned. Reviewed update adds managed assets and preserves existing local.md, environment and unmanaged AGENTS text. Old local.md is not rewritten; the host can append missing facts after inspection. Re-export evaluation datasets/reports after update because bundle hashes change. See [Project conventions](project-conventions.md).
+
+## Harness maintenance contract (unreleased)
+
+Maintainer guidance and impact templates do not alter consumer instructions or schemas. Kubernetes module 1.0.1 adds discovery links to its existing rules; use the usual reviewed update dry-run/update/check sequence. Project-owned files remain preserved, and rollback uses the consumer installation commit. Distribution version remains Release Please-owned.
+
+## Product, Architecture and Delivery (unreleased)
+
+Product module 1.2.0 is additive; Architecture/Delivery start at 1.0.0 and are optional. Distribution
+version remains Release Please-owned. Config/lock/capability schemas stay 1. Existing new-doc calls
+keep Product paths and old PM role/plan template IDs. Explicit --capability selects another installed
+module and requires declared locked metadata/templates; undeclared files are not document types.
+On a consumer branch add architecture/delivery to project.json if needed, review update --dry-run,
+update and check; existing docs, local facts and host bridges remain project-owned. Re-export eval
+reports for the changed bundle. No automatic old-plan migration; revert installation commit to roll back.
+
+## Agent routing and release-test repair (unreleased)
+
+Agent config uses independent schema 1; project/lock schema remains 1. Reviewed update adds a locked
+default and seeds agents.json only if absent; custom bytes and host files survive. Old alternate source
+bundles use the CLI canonical seed if necessary. Existing configs are validated before writes and new
+role gaps inherit/report project defaults. Inspect new payload/update diff; re-export eval reports after
+bundle changes. Revert consumer installation commit for rollback. Release update tests use relative
+versions instead of hardcoded 0.7.0, preserving downgrade refusal on future release branches.
+
+## Frontend/mobile coding and onboarding (unreleased)
+
+React/Next.js and React Native module contracts advance from 1.1.0 to 1.2.0 additively: existing skill
+IDs remain, feature/screen and behavior-testing skills plus manual checks/unscored cases are added.
+Project/lock/agent schemas and the distribution version stay unchanged. Existing consumers run the
+usual reviewed update dry-run/update/check; local.md, agents.json, native host config and app files are
+project-owned and preserved. Re-export eval reports after bundle changes; revert the consumer install
+commit for rollback. See [Frontend/mobile coding](frontend-mobile.md).

package/evals/README.md

@@ -46,3 +46,16 @@ regression thresholds using the harness-ai-evaluation skill. Do not combine thos
 Adapter-specific scenarios are installed with each selected adapter. Use `aih eval` and
 `aih eval --report report.json`; see [adapter evaluation](../docs/adapters.md). This is a separate
 dataset from the Core cases scored by scripts/score-eval.js. Neither command invokes a model.
+
+## Project-convention scenarios
+
+`aih eval --scope all` includes five Core cases for new-project defaults, mixed-module maintenance, inappropriate reuse, unsafe legacy code and conflicting sources, plus one reuse scenario in each Java/Spring, React/Next.js and React Native adapter when selected. Use a disposable consumer containing the concrete files described by the prompt and keep their paths in the trace. Score actual inspected files, reused symbols, new-code rationale and verification honesty. New cases have not been run against a live agent; install/update and report tests only establish the CLI contract.
+
+## Product / solution / delivery scenarios
+
+After selecting relevant capabilities, `aih eval --scope all` includes MVP minimum-quality, architecture
+pattern-level/NFR/stale-map, delivery estimate/scope-change and cross-role handoff cases. Core also
+checks proportional handling of a small clear fix. All new cases remain unscored; run in a disposable
+project through the intended host and review actual inspected files/decisions/code/test evidence.
+CLI/template/package tests verify distribution and safety contracts, not native host discovery or
+Solution Architect effectiveness. The [host smoke prompt](../docs/tool-setup/README.md) is read-only.

package/harness.yaml

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "name": "ai-harness",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "adapters": [
     "java-spring",
     "react-nextjs",
@@ -19,6 +19,8 @@
     "uiux",
     "product",
     "devops",
-    "monetization"
+    "monetization",
+    "architecture",
+    "delivery"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhd_d/ai-harness",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Reusable AI development rules, skills and workflows with a safe local installer",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
   "files": [
     "bin/",
     "cli/*.js",
+    "config/",
     "core/",
     "adapters/",
     "capabilities/",

package/templates/AGENTS.md

@@ -3,7 +3,14 @@
 
 1. Read `.harness/core/rules/foundations.md`, `.harness/core/rules/context.md` and `.harness/core/policies/security.md`.
 2. Read `.harness/core/policies/permissions.md` and `.harness/core/workflows/spec-to-code.md`.
+   For new projects or consequential changes, apply `.harness/core/workflows/solution-framing.md`;
+   preserve approved MVP/architecture and use compact notes for small clear fixes.
 3. Read `.harness/local.md` and `.harness/environment.json` (if present) for project facts and commands.
+   Read project-owned `.harness/agents.json` when present and `.harness/core/workflows/agent-routing.md`.
+   Model/execution settings are preferences: verify actual host support, keep simple work sequential,
+   and never switch to premium automatically. Host/runtime permissions still apply.
+   Before coding, read `.harness/core/rules/project-conventions.md`: establish new/maintain/mixed scope,
+   inspect comparable code and search reusable components before adding files or abstractions.
    For first-run or missing environment facts, use `.harness/core/workflows/project-setup.md`.
    Machine paths may come from ignored `.harness/machine.json`; do not copy private values into shared files.
    Before consequential implementation, follow `.harness/core/workflows/clarification.md`:

package/templates/openspec/design.md

@@ -4,6 +4,12 @@
 TODO: Verified constraints and current behavior.
 ## Goals / Non-Goals
 TODO: Scope boundaries.
+## Convention and Reuse Plan
+TODO: New/maintain/mixed scope, applicable convention source paths, comparable implementations,
+reusable public APIs, intended code placement and rationale for new components/dependencies.
+## Solution Fit
+TODO: Link MVP/AC/NFR, affected modules/data/contracts, important failure flows, accepted ADRs or
+proportional decision notes, dependencies and rollout/rollback constraints.
 ## Decisions
 TODO: Chosen approach, alternatives and trade-offs.
 ## Risks / Trade-offs

package/templates/openspec/tasks.md

@@ -2,6 +2,7 @@
 
 ## 1. Acceptance and design
 - [ ] 1.1 Replace draft placeholders and agree acceptance scenarios and test boundaries.
+- [ ] 1.2 Link applicable MVP/NFR/architecture decisions and dependency/verification boundaries; use a compact note when a full design pack is unnecessary.
 ## 2. Vertical implementation
 - [ ] 2.1 Add one failing behavior test, implement the slice and record the green result.
 ## 3. Verification and review