feat: add on-demand code layouts (0.5.2)

.agents/skills/omp-flow-check/SKILL.md

@@ -16,6 +16,13 @@ Fail closed unless all are available:
 - work Concept and predecessor-linked handoff, plus any applicable linked design or decisions;
 - real implementation diff;
 
+## Code layouts (on demand)
+
+Read only for the matching code-review question; resolve the installed path from the project root,
+not from the Skill directory:
+
+- Adversarial review of bounded implemented code: `.omp-flow/workflow/code/interrogate.md`.
+
 ## Review Order
 
 Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses

.agents/skills/omp-flow-design/SKILL.md

@@ -11,6 +11,13 @@ description: Turn a selected synthesis in an omp-flow task Bundle into linked re
   allowed output paths, actor ID, and receipt.
 - Source provenance needed for the design is readable through ordinary links.
 
+## Code layouts (on demand)
+
+Read only for the matching code-design question; resolve the installed path from the project root,
+not from the Skill directory:
+
+- Caller, interface, data-shape, and ownership design: `.omp-flow/workflow/code/architect.md`.
+
 ## Procedure
 
 Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses

.agents/skills/omp-flow-research/SKILL.md

@@ -12,6 +12,14 @@ description: Investigate repository or external evidence within an omp-flow task
 - The entry contains a usable question or links to the current framing.
 - Each independent question has an explicit output path, normally under `research/`.
 
+## Code layouts (on demand)
+
+Read only the layout matching a code question. Resolve these installed paths from the project
+root, not from the Skill directory:
+
+- Code execution and data/state ownership explanation: `.omp-flow/workflow/code/how.md`.
+- Code history, original rationale, and current validity: `.omp-flow/workflow/code/why.md`.
+
 ## Decide Research Scope
 
 For each consequential question, state which provisional anchor assumption, principal

.claude/skills/omp-flow-check/SKILL.md

@@ -16,6 +16,13 @@ Fail closed unless all are available:
 - work Concept and predecessor-linked handoff, plus any applicable linked design or decisions;
 - real implementation diff;
 
+## Code layouts (on demand)
+
+Read only for the matching code-review question; resolve the installed path from the project root,
+not from the Skill directory:
+
+- Adversarial review of bounded implemented code: `.omp-flow/workflow/code/interrogate.md`.
+
 ## Review Order
 
 Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses

.claude/skills/omp-flow-design/SKILL.md

@@ -11,6 +11,13 @@ description: Turn a selected synthesis in an omp-flow task Bundle into linked re
   allowed output paths, actor ID, and receipt.
 - Source provenance needed for the design is readable through ordinary links.
 
+## Code layouts (on demand)
+
+Read only for the matching code-design question; resolve the installed path from the project root,
+not from the Skill directory:
+
+- Caller, interface, data-shape, and ownership design: `.omp-flow/workflow/code/architect.md`.
+
 ## Procedure
 
 Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses

.claude/skills/omp-flow-research/SKILL.md

@@ -12,6 +12,14 @@ description: Investigate repository or external evidence within an omp-flow task
 - The entry contains a usable question or links to the current framing.
 - Each independent question has an explicit output path, normally under `research/`.
 
+## Code layouts (on demand)
+
+Read only the layout matching a code question. Resolve these installed paths from the project
+root, not from the Skill directory:
+
+- Code execution and data/state ownership explanation: `.omp-flow/workflow/code/how.md`.
+- Code history, original rationale, and current validity: `.omp-flow/workflow/code/why.md`.
+
 ## Decide Research Scope
 
 For each consequential question, state which provisional anchor assumption, principal

.omp/skills/omp-flow-check/SKILL.md

@@ -16,6 +16,13 @@ Fail closed unless all are available:
 - work Concept and predecessor-linked handoff, plus any applicable linked design or decisions;
 - real implementation diff;
 
+## Code layouts (on demand)
+
+Read only for the matching code-review question; resolve the installed path from the project root,
+not from the Skill directory:
+
+- Adversarial review of bounded implemented code: `.omp-flow/workflow/code/interrogate.md`.
+
 ## Review Order
 
 Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses

.omp/skills/omp-flow-design/SKILL.md

@@ -11,6 +11,13 @@ description: Turn a selected synthesis in an omp-flow task Bundle into linked re
   allowed output paths, actor ID, and receipt.
 - Source provenance needed for the design is readable through ordinary links.
 
+## Code layouts (on demand)
+
+Read only for the matching code-design question; resolve the installed path from the project root,
+not from the Skill directory:
+
+- Caller, interface, data-shape, and ownership design: `.omp-flow/workflow/code/architect.md`.
+
 ## Procedure
 
 Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses

.omp/skills/omp-flow-research/SKILL.md

@@ -12,6 +12,14 @@ description: Investigate repository or external evidence within an omp-flow task
 - The entry contains a usable question or links to the current framing.
 - Each independent question has an explicit output path, normally under `research/`.
 
+## Code layouts (on demand)
+
+Read only the layout matching a code question. Resolve these installed paths from the project
+root, not from the Skill directory:
+
+- Code execution and data/state ownership explanation: `.omp-flow/workflow/code/how.md`.
+- Code history, original rationale, and current validity: `.omp-flow/workflow/code/why.md`.
+
 ## Decide Research Scope
 
 For each consequential question, state which provisional anchor assumption, principal

README.md

@@ -109,6 +109,20 @@ brainstorm ↔ research → design → QbD → work map → QbD → implementati
 
 这是一条推理方向，不是 runtime phase state。证据可以让工作回到 framing 或 design；实现结果也必须经过不同 actor 的独立复核。完整语义见 [Workflow index](templates/.omp-flow/workflow/index.md)。
 
+### 按需代码布局（0.5.2）
+
+代码场景可以按需读取 `.omp-flow/workflow/code/` 下的作业布局：
+
+- [How](templates/.omp-flow/workflow/code/how.md)：理解子系统职责、数据归属与实际运行路径。
+- [Why](templates/.omp-flow/workflow/code/why.md)：从代码锚点追溯历史证据、约束与取舍。
+- [Architect](templates/.omp-flow/workflow/code/architect.md)：先写调用者用例，再推导数据结构和接口。
+- [Interrogate](templates/.omp-flow/workflow/code/interrogate.md)：独立检查具体失败路径、已排除风险与验证缺口。
+
+Research、Design、Check Skills 只保留触发条件与路径索引，不预加载全部布局。
+布局复用当前分派的 Concept；小节可以按任务调整，不是新的 Workflow、固定文档 schema
+或批准门。`init` 和 `update` 为所有选定 Harness 安装这些布局，沿用现有的本地修改保护。
+
+
 ## 项目知识与文档系统
 
 omp-flow 把不同生命周期和可信度的知识分开放置，但全部保持为普通 Markdown：

README_EN.md

@@ -115,6 +115,21 @@ brainstorm ↔ research → design → QbD → work map → QbD → implementati
 
 This is a reasoning direction, not runtime phase state. Evidence can return work to framing or design, and implementation results still require independent review by a different actor. See the [Workflow index](templates/.omp-flow/workflow/index.md) for the complete semantics.
 
+### On-demand code layouts (0.5.2)
+
+For code-specific work, read the matching recipe under `.omp-flow/workflow/code/`:
+
+- [How](templates/.omp-flow/workflow/code/how.md): subsystem responsibilities, data ownership, and actual execution paths.
+- [Why](templates/.omp-flow/workflow/code/why.md): code anchors, historical evidence, constraints, and tradeoffs.
+- [Architect](templates/.omp-flow/workflow/code/architect.md): caller examples before data structures and interfaces.
+- [Interrogate](templates/.omp-flow/workflow/code/interrogate.md): independent failure-path review, cleared risks, and verification gaps.
+
+The Research, Design, and Check Skills contain only trigger/path indexes; they do not preload every
+layout. Reuse the assigned Concept and adapt suggested sections to the task. Layouts are not new
+Workflows, fixed document schemas, or approval gates. `init` and `update` install them for every
+selected Harness using the existing local-customization protection.
+
+
 ## Project knowledge and documentation
 
 omp-flow separates knowledge with different lifetimes and confidence levels while keeping all of it as ordinary Markdown:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-flow",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Agent-native OKF task Bundles with a minimal portable runtime kernel.",
   "type": "module",
   "main": "dist/index.js",

src/cli/init.ts

@@ -128,6 +128,10 @@ const WORKFLOW_LIBRARY_FILES = [
   'spec-formation.md',
   'experiment.md',
   'workflow-maintenance.md',
+  'code/how.md',
+  'code/why.md',
+  'code/architect.md',
+  'code/interrogate.md',
 ] as const;
 
 const CORE_RESOURCES: readonly ManagedResource[] = [
@@ -137,8 +141,8 @@ const CORE_RESOURCES: readonly ManagedResource[] = [
     group: 'core',
   },
   ...WORKFLOW_LIBRARY_FILES.map(fileName => ({
-    sourcePath: path.join('templates', '.omp-flow', 'workflow', fileName),
-    destinationPath: path.join('.omp-flow', 'workflow', fileName),
+    sourcePath: path.join('templates', '.omp-flow', 'workflow', ...fileName.split('/')),
+    destinationPath: path.join('.omp-flow', 'workflow', ...fileName.split('/')),
     group: 'core' as const,
   })),
   {

templates/.omp-flow/workflow/code/architect.md

@@ -0,0 +1,67 @@
+# Architect: Design a Code Boundary
+
+Use this optional code layout with `omp-flow-design` when a selected synthesis needs a concrete
+code interface, data model, or ownership boundary. The Skill, linked decisions, and native
+assignment remain authoritative. Reuse the assigned Design/interface output Concept; the headings
+below are suggestions, not a mandatory schema or a separate Concept per invocation.
+
+This is design, not implementation. Keep sketches in prose or Concept code blocks. Do not commit
+source stubs, placeholder implementations, or an API merely to make the design look executable.
+The layout supplies neither automatic sign-off nor permission to bypass human/QbD approval.
+
+## Show callers before signatures
+
+1. Restate the observable problem, binding requirements, non-goals, and evidence from the selected
+   synthesis. Name the concrete consequence the design must enable or prevent.
+2. Start with realistic caller examples: where the call happens, what information is available,
+   the useful result, and the failure the caller must handle. Include a lifecycle or asynchronous
+   example only when the target needs one. Do not invent consumers to justify an abstraction.
+3. Use those examples to derive the smallest useful public boundary, then sketch signatures or
+   messages. Explain each component's causal purpose in plain language. Prefer a deep boundary
+   that owns meaningful work and hides internal detail over shallow wrappers or exposed internals.
+
+## Make data and ownership authoritative
+
+- Describe the relevant data shape and the meaning of its fields: required/optional values, units,
+  identity, validity, and lifetime where material. Distinguish authoritative state from derived or
+  cached views; avoid two competing sources of truth.
+- Show access paths from creation or loading through readers, writers, transformations, persistence,
+  and disposal. Name the owner allowed to mutate state and the boundary where ownership transfers.
+- Assign responsibility for validation, resource acquisition/release, and partial completion.
+  Explain ordering or concurrent access only where it affects this design; do not add machinery for
+  hypothetical requirements.
+- Specify the public contract: inputs, outputs, important invariants, errors, and which failures
+  callers handle versus which the boundary prevents. Cover cancellation, cleanup, and side effects
+  when applicable, including what remains after failure. Never rely on an unexplained fallback.
+- Keep private representation and incidental operations behind the boundary. Explain unavoidable
+  compatibility or migration obligations without introducing an unrequested parallel API.
+
+## Compare only material alternatives
+
+Use the research evidence and caller examples to compare alternatives that could change the
+selected boundary, correctness, cost, or maintainability. State the relevant trade-off and why the
+chosen option solves the observed problem. There is no minimum candidate count, mandatory prototype,
+or requirement to manufacture alternatives for a mechanical decision. Record consequential rejected
+options and the evidence that would reopen them.
+
+## Plan verification and return signals
+
+Map observable requirements and important invariants to specific checks: caller-level examples,
+contract tests, failure/cleanup cases, or other evidence suited to the risk. Separate proposed
+commands and expected observations from verification actually performed. Name any material unknown
+and its owner; an unresolved blocking decision is not ready for decomposition.
+
+State what observation would invalidate the design or its framing, such as an incompatible caller,
+a violated ownership assumption, or an unmet binding constraint. Return that evidence to Main
+through the assigned output for further research, framing, or design rather than suppressing it to
+preserve the sketch. Main owns transitions and approval; the Architect does not approve its own gate.
+
+## Suggested output navigation
+
+Adapt or omit sections as useful:
+
+- **Problem and caller examples:** observable requirements, constraints, non-goals, and source links.
+- **Boundary and data model:** proposed contract, authoritative values, access paths, and ownership.
+- **Behavior and invariants:** normal operation, relevant failures, concurrency, and cleanup.
+- **Trade-offs:** evidence-led choice, material alternatives, and compatibility obligations.
+- **Verification and open decisions:** acceptance checks, return signals, and consequential unknowns.

templates/.omp-flow/workflow/code/how.md

@@ -0,0 +1,58 @@
+# How: Trace Code Behavior
+
+Use this optional code layout with `omp-flow-research` when the question is how a concrete code
+path works. The Skill and native assignment remain authoritative. Write into the assigned output
+Concept; a small explanation can be inline there. The headings below are suggested navigation,
+not a required schema, a separate Concept per invocation, or a workflow gate.
+
+## Bound the explanation
+
+- Name the question, observed revision, and code anchor: entry point, symbol, or behavior. State
+  which decision or assumption the explanation can change.
+- Read the implementation and its callers before relying on comments or tests. Follow only the
+  dependencies needed to explain the target; do not turn a local question into a repository tour.
+- Use useful `file:line` references at that revision for consequential claims. Separate observed
+  behavior, inference, and unknowns; a function name is not evidence of what it does.
+
+## Follow behavior and ownership
+
+1. Establish each relevant component's responsibility and boundary. Identify who supplies inputs,
+   validates them, calls the next component, and consumes the result.
+2. Track data and state: authoritative values, derived copies, mutable fields, persistence, and
+   the owner allowed to change each. For resources, identify acquisition, transfer, lifetime, and
+   the party responsible for release.
+3. Trace an actual normal execution from the caller through significant branches and back to the
+   externally visible result. Include asynchronous handoffs and ordering when they affect behavior.
+4. Trace relevant error, cancellation, and cleanup paths separately. Show where failure originates,
+   how it propagates, which side effects survive, and what is released on partial completion.
+   If cancellation is unsupported, say so with evidence; if it was not investigated, say that
+   instead. Do not invent a cancellation or cleanup guarantee.
+5. Read relevant tests and contracts as supporting evidence. Record commands and results only when
+   exercised, and distinguish source-based reasoning from runtime observation.
+6. Explain gotchas that change a caller's expectations: hidden mutation, blocking work, ownership
+   transfer, ordering, failure after a side effect, or cleanup that depends on the caller. Include
+   only those supported by this target, not a generic risk inventory.
+
+## Scale to the question
+
+Keep simple targets in the assigned Concept. For a complex target, identify only slices that can
+be investigated independently, with their boundaries and the shared question they answer.
+Only Main/coordinator may delegate those slices through the existing native operation contract:
+Bundle, role, bounded objective, entry and output Concepts, actor ID, opaque receipt, and predecessor
+when required. A dispatched child never spawns or redispatches. There is no fixed worker count or
+mandatory decomposition.
+
+## Suggested output navigation
+
+Adapt or omit sections that do not help the reader:
+
+- **Anchor and scope:** question, revision, entry point, and relevant callers.
+- **Responsibilities and ownership:** components, important values/resources, writers, and lifetimes.
+- **Execution:** normal path and relevant error/cancel/cleanup branches, with code references;
+  a small sequence sketch or table is useful only if it clarifies the flow.
+- **Gotchas and limits:** surprising behavior, evidence strength, and uninvestigated paths.
+- **Conclusion:** the answer, its effect on the decision, and remaining consequential questions.
+
+If observed behavior contradicts the framing or an accepted contract, preserve that evidence and
+report the contradiction through the assigned output to Main. An explanation is not authority to
+change code, expand scope, or transition the workflow.