dic-workflow-kit 1.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "dic-workflow-kit",
+  "version": "1.0.0",
+  "description": "Design-implementation consistency workflow with OpenSpec obligations, BDD knowledge, Skills, and Subagents.",
+  "author": {
+    "name": "TonyClaw"
+  },
+  "repository": "https://gitcode.com/TonyClaw/DICWorkflowKit",
+  "license": "UNLICENSED",
+  "keywords": [
+    "codex",
+    "openspec",
+    "design-consistency",
+    "multi-agent",
+    "bdd"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "DIC Workflow Kit",
+    "shortDescription": "Design-to-code consistency workflow",
+    "longDescription": "Auditable OpenSpec intake, obligation extraction, implementation inspection, repair planning, validation, Skills, and bounded Subagent handoffs.",
+    "developerName": "TonyClaw",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write",
+      "Validation",
+      "Subagents"
+    ],
+    "defaultPrompt": [
+      "Check this OpenSpec change against implementation and tests.",
+      "Build an obligation matrix for this design change.",
+      "Repair design-to-code inconsistencies with evidence."
+    ],
+    "brandColor": "#C7000B"
+  }
+}

package/INSTRUCTION.md

@@ -0,0 +1,82 @@
+# Design-Implementation Consistency Workflow
+
+Use this workflow when a Coding Agent must check or repair whether implementation matches design intent.
+
+This instruction is generic. It must not assume a contest, language, framework, directory name, agent host, or operating system.
+
+## Core Contract
+
+- Work autonomously when invoked by an automated runner.
+- Resolve the workflow root from the directory containing this `INSTRUCTION.md`.
+- Resolve the project root from the workflow root, adapter config, or repository evidence.
+- Treat design/spec/API/schema/config/README sources as stronger than existing implementation.
+- Treat public examples and tests as smoke signals, not the full design surface.
+- Do not edit protected design sources unless explicitly instructed.
+- Write intermediate evidence under `logs/trace/`.
+- Write final evidence under `reports/` and `result/`.
+
+## Default Stages
+
+```text
+workflow-intake
+-> workflow-profile
+-> spec-reader
+-> profile-builder
+-> contract-oracle
+-> flow-auditor
+-> impl-inspector
+-> repair-planner
+-> code-repairer
+-> validation-runner
+-> final-reviewer
+```
+
+## Required Evidence
+
+At minimum, produce:
+
+```text
+reports/project-profile.json
+reports/contract-obligations.json
+reports/contract-obligations.md
+reports/final-consistency-report.md
+reports/FINAL_RESULT.json
+result/output.md
+logs/trace/
+```
+
+If a helper or external tool is unavailable, record the exact blocker and continue with the smallest source-backed fallback.
+
+## Subagent Economy
+
+Subagents are useful only when they produce bounded, auditable artifacts. Before delegating, record:
+
+- why the subagent is needed
+- bounded inputs
+- expected artifact
+- local budget
+- fallback route
+- acceptance check
+
+Do not launch a subagent only to produce chat summaries. If a handoff has no trace artifact, output, decision, validation summary, repair queue item, or terminal blocker, treat it as ineffective delegation and recover locally.
+
+## OpenSpec Rule
+
+If OpenSpec files are present, use `knowledge-openspec` before repair planning. Confirm:
+
+- proposal intent is reflected in specs
+- spec scenarios are mapped to implementation and tests
+- tasks are completed or terminally classified
+- archived specs do not override current specs
+- implementation does not silently exceed or contradict the accepted design
+
+## Final Status
+
+Use one of:
+
+- `PASS`
+- `PARTIAL`
+- `BLOCKED`
+- `FAIL`
+
+Do not use `SUCCESS`, `DONE`, or informal status labels in final machine-readable output.

package/README.md

@@ -0,0 +1,202 @@
+# Design-Implementation Consistency Workflow Kit
+
+Version: `1.0.0`
+
+Design-Implementation Consistency Workflow Kit, or DIC Workflow Kit, is a portable agentic workflow package for checking and repairing whether implementation matches design intent.
+
+It is designed for teams that use OpenSpec, design documents, API contracts, schemas, or product requirements before asking Coding Agents to implement code. The kit turns that process into an auditable workflow: read source truth, map design to implementation, inspect gaps, plan small repairs, validate evidence, and produce final consistency reports.
+
+The kit is not tied to one contest, one repository, one language stack, or one agent host. It can be installed into OpenCode, referenced by Claude Code, used from Codex, or adapted by another coding-agent runner.
+
+> The differentiator is not the number of agents. DIC Workflow Kit uses design intent, typed handoffs, project profiles, validation evidence, and residual-risk reporting to prove that implementation remains aligned with its design contract.
+
+## Install in Codex with npm
+
+The npm package contains all seven Skills and all nine Subagents. Install it into the default personal Codex plugin marketplace with:
+
+```text
+npx dic-workflow-kit install
+```
+
+Or install the CLI globally:
+
+```text
+npm install --global dic-workflow-kit
+dic-workflow-kit install
+```
+
+Before the package is published to the npm registry, install the same CLI directly from the repository:
+
+```text
+npm install --global git+ssh://git@gitcode.com/TonyClaw/DICWorkflowKit.git
+dic-workflow-kit install
+```
+
+The installer writes the plugin to `~/.agents/plugins/plugins/dic-workflow-kit` and registers it in `~/.agents/plugins/marketplace.json`. It preserves unrelated entries and replaces only the entry with the same plugin name.
+
+Use `npx dic-workflow-kit install --dry-run` to preview the destination, or `--marketplace-root /path/to/.agents/plugins` for an isolated environment. Start a new Codex task after installation so its Skills and Subagents are discovered.
+
+For a defense-oriented walkthrough of the project claims and their code evidence, see [答辩引导：项目特点与代码证据](docs/答辩引导-项目特点与代码证据.md).
+
+## Why This Exists
+
+Coding Agents are good at changing code, but they often optimize for local green tests, visible examples, or the latest error message. In design-first projects, especially OpenSpec projects, the harder question is different:
+
+> Does the implementation still match the design contract?
+
+DIC Workflow Kit answers that question with a repeatable workflow:
+
+1. Identify authoritative design sources.
+2. Build a project profile.
+3. Map design requirements to implementation areas.
+4. Inspect implementation gaps.
+5. Plan small source-backed repair slices.
+6. Validate with project-declared commands.
+7. Record evidence, residual risks, and final artifacts.
+
+## Repository Layout
+
+| Path | Purpose |
+| --- | --- |
+| `INSTRUCTION.md` | Generic operating manual for autonomous design-implementation consistency work. |
+| `skills/` | Installable Skills: workflow controls and reusable knowledge packs. |
+| `agents/` | Installable Agent prompts: bounded roles for evidence production and repair flow. |
+| `adapters/` | Optional adapters for OpenSpec, generic repos, contests, and stack-specific environments. |
+| `schemas/` | Stable JSON schemas for project profile, handoff, and final evidence artifacts. |
+| `scripts/` | Portable Python standard-library helpers. |
+| `examples/` | Small examples showing how to apply the kit to different project styles. |
+
+## Skills in Workflow Order
+
+Skills are listed by the point at which they first participate in the default workflow. Knowledge Skills are conditional: load them only when repository evidence or the current stage requires them.
+
+| Order | Skill | Type | Workflow Position | Core Role |
+| --- | --- | --- | --- | --- |
+| 00 | `workflow-core` | Workflow mechanism | Entire run | Defines source priority, evidence rules, typed handoffs, final statuses, and durable output contracts. |
+| 01 | `workflow-intake` | Workflow method | Before Subagents | Finds design sources, implementation roots, test roots, protected paths, validation commands, and adapter hints. |
+| 02 | `workflow-profile` | Workflow method | Before Subagents | Normalizes intake evidence into the project profile consumed by every downstream role. |
+| 03 | `knowledge-openspec` | Knowledge pack | During source reading, if OpenSpec is detected | Interprets proposals, designs, specs, scenarios, tasks, active changes, and archived capabilities. |
+| 04 | `knowledge-bdd` | Knowledge pack | After obligations are confirmed, when behavior coverage is needed | Derives Given-When-Then acceptance scenarios from confirmed design rules and flow contracts. |
+| 05 | `workflow-repair` | Workflow method | Audit through final review | Controls source-backed inspection, repair planning, minimal code changes, validation loops, and evidence updates. |
+| 06 | `knowledge-repair-distill` | Knowledge pack | During repair planning or when execution drifts | Supplies gap taxonomy, convergence guidance, model-steering hints, and validation gates. |
+
+## Subagents in Execution Order
+
+Each Subagent appears in its default execution order. A stage may be skipped only with evidence, and a Subagent is useful only when its output is consumed by the next decision.
+
+| Step | Subagent | Phase | Consumes | Produces |
+| --- | --- | --- | --- | --- |
+| 01 | `spec-reader` | Source truth | Project profile and authoritative design sources | Source-backed requirement brief, source anchors, protected paths, unresolved questions |
+| 02 | `profile-builder` | Project profile confirmation | Intake evidence and repository structure | `reports/project-profile.json` |
+| 03 | `contract-oracle` | Obligation mapping | Confirmed requirements, scenarios, and feedback hypotheses | Source-confirmed obligation queue |
+| 04 | `flow-auditor` | Flow completeness | Obligation queue and optional BDD scenarios | Lifecycle, transition, branch, side-effect, and integration-flow audit |
+| 05 | `impl-inspector` | Implementation inspection | Confirmed obligations and flow audit | Source-backed implementation gap report; no code edits |
+| 06 | `repair-planner` | Repair planning | Gap report, protected paths, and available validation commands | Small repair slices with source anchors, stop conditions, and fallback routes |
+| 07 | `code-repairer` | Code repair | Approved repair slices | Minimal code changes, changed-file evidence, and repair notes |
+| 08 | `validation-runner` | Validation | Project-declared commands and changed implementation | Evaluator-readable validation logs and summaries under `logs/trace/validation/` |
+| 09 | `final-reviewer` | Final gate | All prior evidence, changed files, validation, and output artifacts | Final consistency decision, residual risks, and result recommendation |
+
+## Default Workflow
+
+```text
+workflow-core
+-> workflow-intake
+-> workflow-profile
+-> [knowledge-openspec, when detected]
+-> spec-reader
+-> profile-builder
+-> contract-oracle
+-> [knowledge-bdd, when behavior coverage is needed]
+-> workflow-repair
+-> flow-auditor
+-> impl-inspector
+-> [knowledge-repair-distill, when planning or drift requires it]
+-> repair-planner
+-> code-repairer
+-> validation-runner
+-> final-reviewer
+```
+
+The same flow can be read as four evidence gates:
+
+```text
+DISCOVER
+workflow-intake
+-> workflow-profile
+
+UNDERSTAND
+-> spec-reader
+-> profile-builder
+-> contract-oracle
+
+INSPECT + REPAIR
+-> flow-auditor
+-> impl-inspector
+-> repair-planner
+-> code-repairer
+
+VERIFY
+-> validation-runner
+-> final-reviewer
+```
+
+This chain is intentionally evidence-first. Skills provide workflow controls or stage-specific knowledge; Subagents consume bounded inputs and produce typed evidence. A workflow with fewer strong handoffs is better than a decorative chain of agents with no consumed evidence.
+
+## OpenSpec Focus
+
+For OpenSpec projects, the kit treats these as first-class design sources:
+
+| OpenSpec Source | How It Is Used |
+| --- | --- |
+| `openspec/specs/**/spec.md` | Stable capability requirements and scenarios. |
+| `openspec/changes/**/proposal.md` | Intent behind a planned change. |
+| `openspec/changes/**/design.md` | Technical design rationale and constraints. |
+| `openspec/changes/**/tasks.md` | Implementation checklist and completion evidence. |
+| `openspec/changes/**/specs/**/spec.md` | Delta requirements and scenarios for active changes. |
+| Archived specs | Historical context, never stronger than current active specs. |
+
+The kit checks whether proposals, specs, scenarios, and tasks were actually reflected in implementation and tests.
+
+To scope intake to one OpenSpec Change, pass its identifier explicitly. Active changes are preferred; if no active match exists, the archived location is resolved and recorded in the profile. Keep evidence outside the target repository with `--output-root`:
+
+```text
+python scripts/dic_workflow.py \
+  --root /path/to/project \
+  --output-root /path/to/evidence \
+  init --change 2026-06-09-add-ts-local-skill-source
+```
+
+The resulting profile records the Change lifecycle, proposal/design/tasks documents, delta specs, and matching promoted baseline specs. When `openspec/designs/spec-to-design-map.md` contains the capability, the profile also mounts its architecture designs, module designs, ADRs, validation summary, and executable command suggestions. Archived change-specific validation commands are omitted because their active Change target no longer exists.
+
+## Output Contract
+
+By default, a run should produce artifacts relative to the selected submission/workflow root:
+
+```text
+reports/project-profile.json
+reports/contract-obligations.json
+reports/contract-obligations.md
+reports/implementation-gaps.md
+reports/repair-plan.md
+reports/final-consistency-report.md
+reports/FINAL_RESULT.json
+result/output.md
+logs/trace/
+```
+
+For an explicit OpenSpec Change, `init` generates both obligation artifacts automatically. Requirements and Scenarios receive stable IDs, source line references, authority labels, parent relationships, and structured Given/When/Then clauses. Active changes use delta specs as authority; archived changes use the promoted current baseline so historical text cannot override current design truth.
+
+Adapters can change or extend this contract. For example, a contest adapter may require a fixed `result/output.md`, while an internal CI adapter may publish JSON evidence to an artifact store.
+
+## Portability Rules
+
+- Do not hardcode local absolute paths.
+- Do not assume Windows, Linux, macOS, PowerShell, Bash, or `cmd`.
+- Resolve paths from the active `INSTRUCTION.md`, project profile, or adapter configuration.
+- Use Python standard library only for helper scripts.
+- Resolve external tools such as `git`, `mvn`, `npm`, `pnpm`, `pytest`, or `openspec` from the target environment `PATH` only when needed.
+- Treat missing external tools as environment evidence, not as design failure.
+
+## Status
+
+This repository currently contains the first generalized scaffold extracted from a contest-specific design-implementation repair workflow. It is intended to become the reusable upstream kit for future OpenSpec and design-first Coding Agent workflows.

package/README.zh-CN.md

@@ -0,0 +1,172 @@
+# 设计—实现一致性 Workflow Kit
+
+版本：`1.0.0`
+
+Design-Implementation Consistency Workflow Kit，简称 DIC Workflow Kit，是一套可移植的智能体工作流包，用于检查和修复“代码实现是否符合设计意图”。
+
+它面向 OpenSpec、设计文档、API 契约、Schema 或产品需求先行的项目。工作流从权威设计源出发，建立项目画像，映射设计与实现，识别缺口，执行小步修复，运行项目声明的验证命令，并输出可审计的一致性证据。
+
+> 项目的差异不在 Agent 数量。DIC Workflow Kit 通过设计意图、类型化交接、项目画像、验证证据和残余风险报告，证明实现仍然符合设计契约。
+
+## 通过 npm 安装到 Codex
+
+npm 包完整包含 7 个 Skills 和 9 个 Subagents：
+
+```text
+npx dic-workflow-kit install
+```
+
+也可以先全局安装 CLI：
+
+```text
+npm install --global dic-workflow-kit
+dic-workflow-kit install
+```
+
+在 npm registry 正式发布前，可以直接从仓库安装同一个 CLI：
+
+```text
+npm install --global git+ssh://git@gitcode.com/TonyClaw/DICWorkflowKit.git
+dic-workflow-kit install
+```
+
+默认安装到 `~/.agents/plugins/plugins/dic-workflow-kit`，并在 `~/.agents/plugins/marketplace.json` 中注册。安装器会保留其他 marketplace 条目，只更新同名插件。使用 `--dry-run` 预演，或使用 `--marketplace-root` 指定隔离目录。安装后请新建 Codex 任务，以重新发现 Skills 和 Subagents。
+
+答辩时如何讲解项目特点并定位代码证据，请参考[《答辩引导：项目特点与代码证据》](docs/答辩引导-项目特点与代码证据.md)。
+
+## 为什么需要它
+
+Coding Agent 很擅长修改代码，但容易围绕局部报错、公开样例或最近一次失败进行优化。对于设计先行的项目，更重要的问题是：
+
+> 当前实现是否仍然满足已确认的设计契约？
+
+DIC Workflow Kit 将这个问题转换为一条可重复执行的证据链：
+
+1. 定位权威设计源。
+2. 生成项目画像。
+3. 建立设计要求与实现区域的映射。
+4. 审计流程与实现缺口。
+5. 规划有来源依据的小修复。
+6. 使用项目声明的命令验证。
+7. 记录证据、变更文件、残余风险和最终产物。
+
+## 目录结构
+
+| 路径 | 作用 |
+| --- | --- |
+| `INSTRUCTION.md` | 通用执行契约，定义设计—实现一致性工作流。 |
+| `skills/` | 工作流控制 Skill 和可插拔知识包。 |
+| `agents/` | 按阶段工作的 Subagent，负责生产和消费证据。 |
+| `adapters/` | OpenSpec、通用仓库、比赛环境等适配层。 |
+| `schemas/` | 项目画像、Agent 交接和最终结果的 JSON Schema。 |
+| `scripts/` | 仅依赖 Python 标准库的辅助脚本。 |
+| `examples/` | 不同项目形态的使用示例。 |
+
+## Skills：按工作流加载顺序
+
+下表按照 Skill 第一次介入默认流程的位置排列。Knowledge Skill 是条件加载项：只有项目证据或当前阶段需要时才挂载。
+
+| 顺序 | Skill | 类型 | 介入阶段 | 主要作用 |
+| --- | --- | --- | --- | --- |
+| 00 | `workflow-core` | 工作流机制 | 全流程 | 定义事实源优先级、证据规则、Handoff、最终状态和产物契约。 |
+| 01 | `workflow-intake` | 工作流方法 | Subagent 启动前 | 识别设计源、实现目录、测试目录、保护路径、验证命令和 Adapter 线索。 |
+| 02 | `workflow-profile` | 工作流方法 | Subagent 启动前 | 将 Intake 证据规范化为所有下游角色共同消费的项目画像。 |
+| 03 | `knowledge-openspec` | 知识包 | 读取设计源时；检测到 OpenSpec 才加载 | 理解 proposal、design、spec、scenario、task、active change 和 archived capability。 |
+| 04 | `knowledge-bdd` | 知识包 | 契约确认后；需要行为覆盖时 | 从已确认设计规则和流程契约生成 Given–When–Then 验收场景。 |
+| 05 | `workflow-repair` | 工作流方法 | 审计、修复与最终审核阶段 | 控制有来源的检查、修复计划、最小变更、验证循环和证据更新。 |
+| 06 | `knowledge-repair-distill` | 知识包 | 修复规划或模型跑偏时 | 提供缺口分类、收敛策略、模型引导提示和验证门槛。 |
+
+## Subagents：按实际执行顺序
+
+每个 Subagent 都按默认执行顺序排列。只有留下证据时才能跳过某个阶段；只有产物被下一步消费时，该次委派才算有效。
+
+| 步骤 | Subagent | 阶段 | 消费的输入 | 主要产物 |
+| --- | --- | --- | --- | --- |
+| 01 | `spec-reader` | 事实源读取 | 项目画像和权威设计源 | 带文件锚点的需求摘要、保护路径和未决问题 |
+| 02 | `profile-builder` | 项目画像确认 | Intake 证据和仓库结构 | `reports/project-profile.json` |
+| 03 | `contract-oracle` | 契约义务映射 | 已确认需求、场景和反馈假设 | 有来源依据的实现义务队列 |
+| 04 | `flow-auditor` | 流程完整性审计 | 实现义务和可选 BDD 场景 | 生命周期、状态迁移、分支、副作用和集成流程审计 |
+| 05 | `impl-inspector` | 实现检查 | 已确认义务和流程审计 | 实现缺口报告；不修改代码 |
+| 06 | `repair-planner` | 修复规划 | 缺口、保护路径和验证命令 | 包含来源锚点、停止条件和回退路径的小修复片段 |
+| 07 | `code-repairer` | 代码修复 | 已批准的修复片段 | 最小代码变更、变更文件证据和修复说明 |
+| 08 | `validation-runner` | 验证 | 项目声明的命令和变更后实现 | `logs/trace/validation/` 下的日志与验证摘要 |
+| 09 | `final-reviewer` | 最终阶段门 | 所有证据、变更文件、验证结果和最终产物 | 最终一致性结论、残余风险和结果建议 |
+
+## 默认执行链
+
+```text
+workflow-core
+-> workflow-intake
+-> workflow-profile
+-> [knowledge-openspec：检测到 OpenSpec 时]
+-> spec-reader
+-> profile-builder
+-> contract-oracle
+-> [knowledge-bdd：需要行为覆盖时]
+-> workflow-repair
+-> flow-auditor
+-> impl-inspector
+-> [knowledge-repair-distill：修复规划或执行跑偏时]
+-> repair-planner
+-> code-repairer
+-> validation-runner
+-> final-reviewer
+```
+
+也可以将它理解为四个证据阶段：
+
+```text
+发现上下文
+workflow-intake -> workflow-profile
+
+确认设计
+spec-reader -> profile-builder -> contract-oracle
+
+检查与修复
+flow-auditor -> impl-inspector -> repair-planner -> code-repairer
+
+验证与审核
+validation-runner -> final-reviewer
+```
+
+Skills 提供全局控制或阶段知识；Subagents 消费边界明确的输入并产出类型化证据。少量但有效的 Handoff，优于没有产物被消费的装饰性 Agent 链。
+
+## OpenSpec 适配重点
+
+| OpenSpec 文件 | 使用方式 |
+| --- | --- |
+| `openspec/specs/**/spec.md` | 当前稳定能力要求和场景。 |
+| `openspec/changes/**/proposal.md` | 变更意图。 |
+| `openspec/changes/**/design.md` | 技术设计和约束。 |
+| `openspec/changes/**/tasks.md` | 实现任务和完成证据。 |
+| `openspec/changes/**/specs/**/spec.md` | 活跃变更中的增量需求。 |
+| archived specs | 历史上下文，不能覆盖当前有效 Spec。 |
+
+## 默认输出契约
+
+```text
+reports/project-profile.json
+reports/contract-obligations.json
+reports/contract-obligations.md
+reports/implementation-gaps.md
+reports/repair-plan.md
+reports/final-consistency-report.md
+reports/FINAL_RESULT.json
+result/output.md
+logs/trace/
+```
+
+Adapter 可以扩展输出契约。例如比赛环境可能要求固定的 `result/output.md`，内部 CI 则可以将 JSON 证据发布到制品存储。
+
+## 平台无关要求
+
+- 不硬编码本机绝对路径。
+- 不假设 Windows、Linux、macOS、PowerShell、Bash 或 `cmd`。
+- 从 `INSTRUCTION.md`、项目画像或 Adapter 配置解析路径。
+- Python helper 只依赖标准库。
+- `git`、`mvn`、`npm`、`pnpm`、`pytest`、`openspec` 等外部工具仅在验证需要时从目标环境 `PATH` 解析。
+- 工具缺失属于环境证据，不等同于设计失败。
+
+## 当前状态
+
+该仓库包含从比赛场景中抽取出的第一版通用化设计—实现一致性工作流骨架，目标是成为 OpenSpec 和其他设计先行 Coding Agent 工作流的可复用上游能力。

package/adapters/contest/README.md

@@ -0,0 +1,13 @@
+# Contest Adapter
+
+Use this adapter only when an external judge requires fixed output paths, time limits, or scoring conventions.
+
+Typical requirements:
+
+- final readable output at `result/output.md`
+- intermediate evidence under `logs/trace/`
+- final JSON or Markdown under `reports/`
+- no human interaction during execution
+- strict timeout handling
+
+Keep contest-specific requirements here instead of putting them into workflow-core.

package/adapters/generic/README.md

@@ -0,0 +1,18 @@
+# Generic Repository Adapter
+
+Use this adapter when no stronger project-specific adapter applies.
+
+Detection sources:
+
+- `README*`
+- `docs/**`
+- `design/**`
+- `spec/**`
+- `api/**`
+- `schemas/**`
+- source directories
+- test directories
+- CI config
+- package/build metadata
+
+The generic adapter should not invent design rules. It only indexes available evidence and marks unknown areas as `VERIFY`.

package/adapters/openspec/README.md

@@ -0,0 +1,24 @@
+# OpenSpec Adapter
+
+Use this adapter when the project uses OpenSpec for design-first development.
+
+Detection hints:
+
+- `openspec/specs/**/spec.md`
+- `openspec/changes/**/proposal.md`
+- `openspec/changes/**/design.md`
+- `openspec/changes/**/tasks.md`
+- `openspec/changes/**/specs/**/spec.md`
+
+Validation hints:
+
+- Prefer project-declared OpenSpec commands.
+- If an `openspec` executable is available, `openspec validate --strict` is a likely validation candidate.
+- Missing `openspec` is environment evidence, not design failure.
+
+Consistency checks:
+
+- active change requirements map to implementation
+- scenarios map to tests or payload evidence
+- tasks are completed or terminally classified
+- archived specs do not override active specs

package/agents/code-repairer.md

@@ -0,0 +1,17 @@
+---
+name: code-repairer
+version: 1.0.0
+description: Implement approved repair slices while preserving contracts, minimizing blast radius, and avoiding unrelated refactors.
+mode: subagent
+---
+
+You are the Code Repairer.
+
+Mission:
+
+- Edit only in-scope implementation files.
+- Keep changes small and source-backed.
+- Preserve frozen contracts.
+- Record changed files and repair rationale.
+
+If a compile failure appears, re-check the governing source rule before applying follow-up fixes.

package/agents/contract-oracle.md

@@ -0,0 +1,17 @@
+---
+name: contract-oracle
+version: 1.0.0
+description: Convert source requirements, OpenSpec scenarios, and feedback hypotheses into source-confirmed implementation obligations.
+mode: subagent
+---
+
+You are the Contract Oracle.
+
+Mission:
+
+- Convert requirements into obligations.
+- Confirm each obligation against source files.
+- Reject or mark non-applicable candidates with evidence.
+- Route confirmed obligations to flow audit or implementation inspection.
+
+Do not use knowledge packs as source truth.

package/agents/final-reviewer.md

@@ -0,0 +1,19 @@
+---
+name: final-reviewer
+version: 1.0.0
+description: Perform the final consistency gate across source coverage, protected paths, validation evidence, residual risks, changed files, and output artifacts.
+mode: subagent
+---
+
+You are the Final Reviewer.
+
+Mission:
+
+- Check source coverage.
+- Check protected paths.
+- Check hidden or deep flow risks.
+- Check validation/result consistency.
+- Check final artifacts.
+- Reject decorative subagent usage that produced no consumed evidence.
+
+Final quality is measured by evidence, not by agent count.

package/agents/flow-auditor.md

@@ -0,0 +1,15 @@
+---
+name: flow-auditor
+version: 1.0.0
+description: Audit business and use-case flow completeness, including lifecycle, branches, state transitions, side effects, integration paths, and failure handling.
+mode: subagent
+---
+
+You are the Flow Auditor.
+
+Mission:
+
+- Discover source-confirmed flows.
+- Check happy, boundary, exception, branch, state, side-effect, and integration paths.
+- Write flow completeness findings.
+- Keep reads bounded and write progress artifacts for long audits.

package/agents/impl-inspector.md

@@ -0,0 +1,15 @@
+---
+name: impl-inspector
+version: 1.0.0
+description: Inspect implementation against source-confirmed obligations without editing files.
+mode: subagent
+---
+
+You are the Implementation Inspector.
+
+Mission:
+
+- Map obligations to implementation areas.
+- Identify missing, partial, contradictory, or over-broad implementation.
+- Inspect tests only as evidence, not as source truth.
+- Produce a gap report for repair planning.

package/agents/profile-builder.md

@@ -0,0 +1,17 @@
+---
+name: profile-builder
+version: 1.0.0
+description: Build a normalized project profile from repository evidence so downstream agents stop guessing paths, tools, and source hierarchy.
+mode: subagent
+---
+
+You are the Profile Builder.
+
+Mission:
+
+- Build or refresh `reports/project-profile.json`.
+- Identify project type hints.
+- Record design sources, implementation roots, test roots, protected paths, and validation commands.
+- Select adapters with evidence.
+
+Do not hardcode a known repository shape.