@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-core/runtime/hooks/index_gate.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block protected source access until indexes were observed."""
+
+from __future__ import annotations
+
+import json
+
+from hook_common import (
+    direct_tool_paths,
+    ensure_session,
+    is_mutation_tool,
+    load_policy,
+    locked_state,
+    project_root,
+    read_event,
+    record_prechange_fingerprints,
+    required_evidence,
+    tool_requests_protected_source,
+)
+
+
+def main() -> int:
+    event = read_event()
+    root = project_root(event)
+    policy = load_policy(root)
+    session_id = ensure_session(root, event)
+    required = required_evidence(root, policy)
+
+    with locked_state(root, session_id) as state:
+        state["required_evidence"] = required
+        observed = set(state.get("evidence", []))
+
+    blocked, paths = tool_requests_protected_source(event, root, policy)
+    missing = [path for path in required if path not in observed]
+    strict = str(policy.get("mode", "strict")).lower() == "strict"
+    if strict and required and missing and blocked:
+        reason = (
+            "INDEX_GATE_BLOCKED: protected source access requires observed index evidence. "
+            f"Read these files first, in order: {', '.join(missing)}. "
+            f"Blocked target: {', '.join(paths)}. The gate records successful tool reads, not assistant promises."
+        )
+        print(
+            json.dumps(
+                {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PreToolUse",
+                        "permissionDecision": "deny",
+                        "permissionDecisionReason": reason,
+                    }
+                },
+                ensure_ascii=False,
+            )
+        )
+        return 0
+
+    if is_mutation_tool(event):
+        record_prechange_fingerprints(root, session_id, direct_tool_paths(event, root))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

package/plugins/devflow-core/runtime/hooks/injection_code_specification.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""Thin wrapper for backward compatibility — delegates to start.py."""
+
+from start import main
+
+if __name__ == "__main__":
+    main()

package/plugins/devflow-core/runtime/hooks/post_tool.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: record index evidence and files changed by successful tools."""
+
+from __future__ import annotations
+
+from hook_common import (
+    command_text,
+    direct_tool_paths,
+    ensure_session,
+    evidence_observed,
+    is_command_tool,
+    is_mutation_tool,
+    load_policy,
+    locked_state,
+    project_root,
+    read_event,
+    required_evidence,
+)
+
+
+def main() -> int:
+    event = read_event()
+    root = project_root(event)
+    policy = load_policy(root)
+    session_id = ensure_session(root, event)
+    required = required_evidence(root, policy)
+    optional = [
+        str(item.get("path") if isinstance(item, dict) else item)
+        for item in policy.get("optional_evidence", [])
+    ]
+    observed = evidence_observed(event, root, required + optional)
+    touched = direct_tool_paths(event, root) if is_mutation_tool(event) else []
+
+    with locked_state(root, session_id) as state:
+        state["evidence"] = sorted(set(state.get("evidence", [])) | set(observed))
+        state["touched_files"] = sorted(set(state.get("touched_files", [])) | set(touched))
+        if is_command_tool(event) and command_text(event):
+            state["rescan_required"] = True
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

package/plugins/devflow-core/runtime/hooks/start.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""Session bootstrapper: inject compact workflow context and initialize hook state."""
+
+import json
+import os
+import sys
+from io import StringIO
+from pathlib import Path
+
+from hook_common import cli_dir_name, initialize_session, project_root, read_event
+
+
+def should_skip() -> bool:
+    return os.environ.get("OMP_NON_INTERACTIVE") == "1"
+
+
+def read_file(path: Path, fallback: str = "") -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (FileNotFoundError, PermissionError):
+        return fallback
+
+
+def detect_cli_dir(project_dir: Path) -> str:
+    """Resolve the native config directory, including marketplace execution."""
+    return cli_dir_name()
+
+
+def load_config(project_dir: Path, cli_dir: str) -> dict:
+    defaults = {
+        "sources": {
+            "state": ".planning/STATE.md",
+            "workflow": ".context/workflow.md",
+            "indexes": [
+                ".planning/rules/INDEX.md",
+                ".context/spec/index.md",
+                ".planning/navigation/INDEX.md",
+                ".planning/code-index/INDEX.md",
+            ],
+            "lessons": ".context/lessons/README.md",
+            "commands": f"{cli_dir}/commands/start.md",
+        }
+    }
+    config_path = project_dir / cli_dir / "hook-config.json"
+    if config_path.exists():
+        try:
+            loaded = json.loads(config_path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                merged = {**defaults, **loaded}
+                merged["sources"] = {
+                    **defaults["sources"],
+                    **loaded.get("sources", {}),
+                }
+                return merged
+        except json.JSONDecodeError:
+            pass
+    return defaults
+
+
+def parse_scalar(value: str):
+    value = value.strip()
+    if value == "[]":
+        return []
+    if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")):
+        return value[1:-1]
+    return value
+
+
+def parse_state_frontmatter(full: str) -> dict:
+    if not full.startswith("---\n"):
+        return {}
+    end = full.find("\n---", 4)
+    if end == -1:
+        return {}
+
+    data = {}
+    lines = full[4:end].splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if not line.strip() or line.startswith(" "):
+            i += 1
+            continue
+        if ":" not in line:
+            i += 1
+            continue
+
+        key, raw = line.split(":", 1)
+        key = key.strip()
+        raw = raw.strip()
+        if raw:
+            data[key] = parse_scalar(raw)
+            i += 1
+            continue
+
+        values = []
+        j = i + 1
+        while j < len(lines) and lines[j].startswith("- "):
+            values.append(parse_scalar(lines[j][2:]))
+            j += 1
+        if values:
+            data[key] = values
+            i = j
+        else:
+            i += 1
+    return data
+
+
+def format_state_from_frontmatter(full: str) -> str:
+    state = parse_state_frontmatter(full)
+    if not state.get("current_step") and not state.get("status"):
+        return ""
+
+    completed = state.get("completed_steps") or []
+    pending = state.get("pending_steps") or []
+    completed_text = ", ".join(completed) if completed else "none"
+    pending_text = ", ".join(pending) if pending else "none"
+
+    parts = [
+        "## Workflow State",
+        "",
+        f"- **Current Flow**: {state.get('current_flow', 'unknown')}",
+        f"- **Current Feature**: {state.get('current_feature', 'unknown')}",
+        f"- **Current Phase**: {state.get('current_phase', 'unknown')}",
+        f"- **Current Step**: {state.get('current_step', 'unknown')}",
+        f"- **Status**: {state.get('status', 'unknown')}",
+    ]
+    if state.get("checkpoint"):
+        parts.append(f"- **Checkpoint**: {state.get('checkpoint')}")
+    parts.extend(
+        [
+            f"- **Completed Steps**: {completed_text}",
+            f"- **Pending Steps**: {pending_text}",
+            "",
+            "## Blockers",
+            "",
+            "无。",
+            "",
+            "## Recommended Next Step",
+            "",
+        ]
+    )
+    if state.get("status") == "completed" and not pending:
+        parts.append("Workflow complete — no pending workflow steps.")
+    elif state.get("checkpoint"):
+        parts.append(f"Await checkpoint confirmation: {state.get('checkpoint')}.")
+    elif pending:
+        parts.append(f"Continue with next pending step: {pending[0]}.")
+    else:
+        parts.append("Inspect workflow state with workflow-orchestrator before proceeding.")
+    return "\n".join(parts)
+
+
+def load_state_section(project_dir: Path, state_path: str) -> str:
+    full = read_file(project_dir / state_path)
+    if not full:
+        return ""
+
+    frontmatter_summary = format_state_from_frontmatter(full)
+    if frontmatter_summary:
+        return frontmatter_summary
+
+    lines = full.split("\n")
+    sections = []
+    capture = False
+    for line in lines:
+        if line.startswith("## ") and any(
+            kw in line for kw in ["Workflow State", "Completion", "Blockers", "Next Action", "Recommended Next Step"]
+        ):
+            capture = True
+            sections.append(line)
+        elif line.startswith("## ") and capture:
+            capture = False
+            sections.append("")
+        elif capture:
+            sections.append(line)
+
+    extracted = "\n".join(sections).strip()
+    if not extracted:
+        return full[:1500]
+    return extracted
+
+
+def main():
+    if should_skip():
+        sys.exit(0)
+
+    event = read_event()
+    project_dir = project_root(event)
+    initialize_session(project_dir, event)
+    cli_dir = detect_cli_dir(project_dir)
+    config = load_config(project_dir, cli_dir)
+    sources = config.get("sources", {})
+
+    output = StringIO()
+
+    # 项目身份
+    project_name = project_dir.name
+    project_md = read_file(project_dir / ".planning" / "PROJECT.md")
+    for line in project_md.split("\n"):
+        if line.startswith("- **Name**:"):
+            project_name = line.split(":")[-1].strip()
+            break
+
+    output.write(
+        "<session-context>\n"
+        f"你正在 {project_name} 项目中进行研发工作。\n"
+        "该项目使用 .planning/ 跟踪研发流水线进度，状态写入和上下文同步由 OMP extension 强制执行。\n"
+        "索引只用于加速定位；发现索引缺失或过期时，直接回退到 LSP、搜索和源码，并报告降级状态。\n"
+        "</session-context>\n\n"
+    )
+
+    # 跨 clear 意图
+    intent_path = project_dir / ".planning" / ".next-intent"
+    intent = {}
+    if intent_path.exists():
+        try:
+            intent = json.loads(intent_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, PermissionError):
+            pass
+        try:
+            intent_path.unlink()
+        except PermissionError:
+            pass
+
+    if intent:
+        output.write("<intent>\n")
+        output.write(json.dumps(intent, ensure_ascii=False))
+        output.write("\n</intent>\n\n")
+
+    # Pipeline 状态
+    state_path = sources.get("state", ".planning/STATE.md")
+    state_text = load_state_section(project_dir, state_path)
+    if state_text:
+        output.write("<pipeline-state>\n")
+        output.write(state_text)
+        output.write("\n</pipeline-state>\n\n")
+
+    # 研发流程
+    workflow_path = sources.get("workflow", ".context/workflow.md")
+    workflow_text = read_file(project_dir / workflow_path)
+    if workflow_text:
+        output.write("<workflow>\n")
+        output.write(workflow_text)
+        output.write("\n</workflow>\n\n")
+
+    # 只注入入口清单；具体内容按需读取，过期时回退到源码事实。
+    index_paths = sources.get("indexes", [])
+    if index_paths:
+        output.write("<index-entrypoints>\n")
+        for rel_path in index_paths:
+            status = "available" if (project_dir / rel_path).is_file() else "missing"
+            output.write(f"- {rel_path}: {status}\n")
+        output.write("</index-entrypoints>\n\n")
+
+    # 经验教训
+    lessons_path = sources.get("lessons", ".context/lessons/README.md")
+    lessons_text = read_file(project_dir / lessons_path)
+    if lessons_text and lessons_text.strip():
+        output.write("<lessons>\n")
+        output.write(lessons_text)
+        output.write("\n</lessons>\n\n")
+
+    # 初始化指令
+    commands_path = sources.get("commands", f"{cli_dir}/commands/start.md")
+    start_text = read_file(project_dir / commands_path)
+    if start_text:
+        output.write("<instructions>\n")
+        output.write(start_text)
+        output.write("\n</instructions>\n\n")
+
+    output.write(
+        "<ready>\n"
+        "精简会话上下文已经加载。等待用户请求，并服从 Devflow 工具的状态门禁与同步判定。\n"
+        "</ready>"
+    )
+
+    result = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": output.getvalue(),
+        }
+    }
+    print(json.dumps(result, ensure_ascii=False), flush=True)
+
+
+if __name__ == "__main__":
+    main()

package/plugins/devflow-core/skills/workflow-orchestrator/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: workflow-orchestrator
+description: Use when the user asks to continue, resume, advance, inspect, or route a .planning-based workflow; when the OMP development agent must decide the next workflow skill from project state; or when a checkpoint must be handled before proceeding.
+---
+
+# Workflow Orchestrator
+
+## Overview
+
+Control-plane entrypoint for project workflows. Reads `.planning/STATE.md`, `.planning/workflows/*.yaml`, and the artifact registry, decides the next action, and preserves checkpoint gates. Pipeline delegates here after parameter parsing and breakpoint detection.
+
+This skill is the **single source of truth for all execution-time rules**: gate rules, CP protocol, failure branches, parallel windows, state writeback, lessons injection, and requirement writeback. Pipeline only handles entry (args + breakpoint).
+
+## Quick Start
+
+If the project has no generated control-plane files, initialize them through the single-writer runtime:
+
+```text
+devflow_bootstrap(feature="<feature>", phase="<phase>")
+```
+
+Use `force=true` only when replacing invalid generated workflow/state files is intentional and reviewed.
+
+Run the state inspector first:
+
+```text
+devflow_state(action="inspect")
+```
+
+Use the JSON result to choose one of these actions:
+
+| `action` | Required behavior |
+|----------|-------------------|
+| `await_user_confirmation` | Stop. Summarize the checkpoint and ask the user to confirm before advancing. |
+| `route_failure_branch` | Stop normal flow. Load the indicated remediation workflow and start its entry step. |
+| `run_parallel_window` | Run all indicated independent branch steps if parallel execution is available, otherwise use the fallback order. |
+| `run_project_context` | Load and execute `workflow-project-context`, then run the state inspector again. |
+| `run_next_step` | Load and execute the indicated `next_step.skill`. |
+| `run_current_step` | Re-run or finish the indicated `current_step.skill`. |
+| `workflow_complete` | Report completion and do not call another workflow skill. |
+| `blocked` | Report the blocking reason and ask for the minimum missing input. |
+
+When `blocked` includes a `recovery` command, run or propose that command before attempting normal dispatch.
+
+`inspect_state.rb` runs `validate_state.rb` before dispatching normal actions. If validation fails, stop at `action: blocked` and fix the reported state/artifact inconsistency before continuing. Do not treat `status: completed` as authoritative unless `validate_state.rb --json` returns `ok: true`.
+
+When `run_project_context` is returned, do not initialize workflow state manually first. Execute `workflow-project-context` with the user's provided codebase locations and project-init arguments, verify it writes `.planning/PROJECT.md`, `.planning/navigation/INDEX.md`, `.context/spec/index.md`, and `.planning/STATE.md`, then run `inspect_state.rb --json` again and continue from the returned action.
+
+## Automatic Run Loop
+
+When the invocation contains `<devflow-runtime-directive>`, run the workflow continuously instead of stopping after one successful step:
+
+1. Inspect state and execute exactly the returned action.
+2. After a successful step transition and artifact synchronization, inspect state again.
+3. Continue with the newly returned action and load only that step's Skill.
+4. Stop only when the inspector returns `await_user_confirmation`, `blocked`, or `workflow_complete`; also stop on an explicit user interruption or an unrecoverable tool failure.
+5. At `await_user_confirmation`, present the checkpoint and yield to the user. Resume the same loop only after an explicit confirmation and successful `devflow_transition`.
+
+Do not interpret “automatic” as permission to cross a checkpoint, weaken a gate, retry a stale revision without re-inspection, or continue after a blocked action. If context pressure requires a new turn, preserve project truth in `.planning`, finish required context synchronization, and use `/devflow resume` rather than inventing state from the conversation.
+
+## Step Execution Protocol
+
+Each step execution follows this fixed sequence:
+
+**Before execution:**
+1. Call `devflow_skill_script(script="orchestrator-manage-lessons", args=["--select", "--next-step", "<step-id>", "--json"])`. If lessons are returned, prepend their content before loading the skill. This is **mandatory**, not advisory.
+2. Read the step definition from `feature-development.yaml` for `inputs`, `outputs`, and `meta_output`.
+
+**Execution:**
+3. Load the named skill from `skill://<skill>`.
+4. Pass along the resolved `inputs`, `outputs`, `meta_output`, current feature, and phase.
+5. Ensure the skill writes both its `outputs` AND its `meta_output` (the `.meta.json` file).
+
+**After execution:**
+6. Verify the step's outputs exist, record the revision returned by `devflow_state(action="inspect")`, then call `devflow_transition(action="complete-step", step="<step-id>", expectedRevision=<revision>)`.
+7. If the YAML step has `meta_output`, verify the `.meta.json` file exists and has the required fields. If missing, mark the step as `blocked` with reason "missing_meta_output".
+8. `devflow_transition` validates the proposed state before writing and rejects inconsistent updates. Never repeat the transition after it reports success.
+9. Call `devflow_artifact(action="sync", preserve=false)` only when the registry still shows stale `planned`/`generated` statuses for completed steps.
+
+## Checkpoint Rules
+
+Never cross CP checkpoints silently. CP definitions (prompts, options, fields) are in the active workflow YAML (`feature-development.yaml` → `checkpoints`).
+
+When the inspector returns `await_user_confirmation`:
+
+1. Read the checkpoint definition from YAML: `checkpoints.<cp-id>`.
+2. Prefer structured checkpoint fields when present:
+   - `producing_step`
+   - `required_outputs`
+   - `required_meta_output`
+   - `required_meta_fields`
+   - `summary_fields`
+   - `prompt`
+   - `confirm_options`
+   - `skip_policy`
+3. Read the producing step's `meta_output` or checkpoint `required_meta_output` → `.meta.json` to get structured field values (e.g., `fp_count`, `br_count`).
+4. Verify the listed required outputs exist.
+5. Check artifact registry content_valid status for the listed outputs.
+6. Use `ask` to present the CP prompt, filling in the `summary_fields` from `.meta.json` data.
+7. If the user confirms, inspect the current revision and call `devflow_transition(action="confirm-checkpoint", expectedRevision=<revision>)`.
+8. If the user asks for fixes or rejects the checkpoint, keep `.planning/STATE.md` at `status: waiting_checkpoint`, inspect the current revision, call `devflow_transition(action="checkpoint-decision", decision="needs_fix", expectedRevision=<revision>)`, and route to the requested remediation.
+
+CP skip rules:
+- CP-1, CP-API, CP-2, CP-3, CP-4: **never skip**.
+- CP-2 is the Merge Gate. It cannot be skipped in the dual-track workflow.
+
+## Global Gate Rules
+
+After each step completes, verify the step's gate before advancing:
+
+| Step | Gate | Block if |
+|------|------|---------|
+| requirement-triage | triage.meta.json `status` is `routed` AND `route` is `ready_for_wayfinder` | Reject advance to requirement-wayfinder |
+| requirement-wayfinder | 决策地图.meta.json `status=ready_for_baseline` AND `ready_for_baseline=true` | Reject advance to domain-modeling |
+| domain-modeling | 领域模型记录及 meta 存在且标识当前功能 | Reject advance to requirement-feasibility-review |
+| requirement-feasibility-review | 可实现性审查.meta.json `status=ready_for_baseline`、`baseline_gate=pass`、`gap_count=0` 且无 critical finding | Reject advance to requirement-baseline |
+| requirement-baseline | baseline.md review conclusion is "通过" AND baseline.meta.json `review_status` is `passed` AND blocking counters are all 0 | Reject advance to api-contract |
+| api-contract | api-contract.meta.json `review_status` is `passed` AND `pending_contract_count` is 0 | Reject advance to dual tracks |
+| ui-spec | UI-SPEC.md review conclusion is "通过" | Reject advance to feature-breakdown |
+| feature-breakdown | 功能点梳理.md review conclusion is "通过" | Reject advance to tech-specs |
+| api-call-guide | api-call-guide.meta.json `frontend_consumable` and `mock_ready` are true, pending_items is empty | Reject merge gate |
+| frontend-tech-spec + backend-tech-spec | Both review conclusions are "通过" | Reject integration-verify |
+| integration-verify | integration-report.meta.json `merge_gate_status` is `passed` and all mismatch/blocking counters are 0 | Reject advance to change-plan |
+| change-plan | 变更清单.md review conclusion is "通过" | Reject advance to execute |
+
+If a gate fails, the current step must be re-executed. Do not skip failing gates.
+
+## Requirement Writeback Gate
+
+When any later step discovers or introduces a change that alters external behavior, the requirement baseline must be updated first before downstream documents or code are modified.
+
+Must writeback to `.planning/requirements/baseline.md` when:
+- New or changed user-visible behavior, notifications, failure handling, retry policy, scheduling, permissions, API contracts, or data write rules
+- Missing edge cases, compatibility requirements, historical impacts, or non-functional constraints found during execution
+- User adds/modifies requirements during tech-spec, change-plan, execution, or verification
+
+After writeback, sync affected feature-breakdown, tech-specs, change-plan, and STATE.md. Do not let baseline become stale while downstream artifacts advance.
+
+## Simplification Gate
+
+If a user's request looks like a simple change, it cannot skip the pipeline automatically. Only propose simplification when ALL of:
+- Change touches only a single file, method, or document
+- No new tables, APIs, routes, permissions, configs, migrations, or cross-layer impacts
+- Requirements are clear with no conflicts, reuse, historical, or alternative decisions pending
+
+User must explicitly agree before any steps are skipped.
+
+## Failure Branch Rules
+
+When the inspector returns `route_failure_branch`:
+
+1. Do not continue to the normal `next_step`.
+2. Load the returned `failure_branch.workflow_config`.
+3. Start the branch at `failure_branch.entry_step`.
+4. Preserve the original feature and phase.
+5. After the remediation verification step passes, return using `failure_branch.resume_after_success`.
+
+## Parallel Window Rules
+
+When the inspector returns `run_parallel_window`:
+
+0. **Track filtering**（新增）：读取 STATE.md 的 `active_track` 字段
+   - 如果 `active_track == "A"`：只路由完整需求主链及 Track A 步骤（requirement-triage、requirement-wayfinder、domain-modeling、requirement-feasibility-review、requirement-baseline、api-contract、backend-tech-spec、api-call-guide），完成后阻断在轨道边界
+   - 如果 `active_track == "B"`：新需求必须完成完整需求主链；前端设计步骤仍依赖 api-contract。允许步骤为 requirement-triage、requirement-wayfinder、domain-modeling、requirement-feasibility-review、requirement-baseline、api-contract、ui-spec、feature-breakdown、frontend-tech-spec、api-supplement，完成后阻断在轨道边界
+   - 如果未设置或无效：保留全部 branch_steps（双轨道）
+   - 过滤后如果只剩一个步骤，退化为串行执行（不启动并行窗口）
+
+1. Confirm every returned branch step has its dependencies satisfied.
+2. If the environment supports safe parallel work, dispatch the branch steps independently.
+3. If not, execute `serial_fallback_order`.
+4. Do not run the join step until every branch output exists and is registered as successful.
+
+## State Writeback Rules
+
+Use `devflow_transition` for deterministic state updates. Direct file edits and direct calls to writer scripts are blocked by the OMP extension.
+
+Common operations:
+
+```text
+devflow_transition(action="complete-step", step="<step-id>", expectedRevision=<revision>)
+devflow_transition(action="confirm-checkpoint", expectedRevision=<revision>)
+devflow_transition(action="checkpoint-decision", decision="needs_fix", expectedRevision=<revision>)
+devflow_transition(action="enter-failure-branch", expectedRevision=<revision>)
+```
+
+Always obtain `<revision>` from a fresh `devflow_state(action="inspect")`. A stale
+revision is rejected without changing state, registry, or next-intent files.
+
+Checkpoint confirmation also writes the configured `.planning/.next-intent`.
+
+When `devflow_transition` succeeds, it automatically regenerates the Markdown body of STATE.md from the YAML state + artifact registry. The body is marked `<!-- GENERATED — DO NOT EDIT -->` and must not be manually edited.
+
+## Lessons Rules
+
+Lessons injection is **mandatory** before every step execution (see Step Execution Protocol, step 1).
+
+```text
+devflow_skill_script(script="orchestrator-manage-lessons", args=["--select", "--next-step", "<step-id>", "--json"])
+```
+
+If the returned candidates list is non-empty, load the lesson files and prepend their content as context before loading the skill's SKILL.md.
+
+Create a lesson template only from concrete evidence:
+
+```text
+devflow_skill_script(script="orchestrator-manage-lessons", args=["--write-template", "--title", "<title>", "--source", "<artifact>", "--json", "--write"])
+```
+
+Call the write form only when the template should be created. Do not invent root cause, fix, or prevention content without evidence from the source artifact.
+
+## Meta Output Protocol
+
+Steps with `meta_output` in the workflow YAML must produce a `.meta.json` file alongside their main output. The orchestrator verifies these:
+
+1. After step execution, check if the YAML step has `meta_output`.
+2. If yes, verify the `.meta.json` file at `meta_output.path` exists.
+3. Verify all `required: true` fields are present and non-null.
+4. If missing or incomplete, mark step as blocked and do not advance.
+
+The `.meta.json` data feeds CP prompts — e.g., CP-1 reads `baseline.meta.json` to show `fp_count: 7` instead of having the AI count manually.
+
+## Initialization Rules
+
+This skill must be portable. Do not require manually-created `.planning` control files.
+
+If `.planning/STATE.md` is missing and project context files are also missing, route to `workflow-project-context` instead of asking for `init_state.rb`. If `.planning/STATE.md` is missing but project context files already exist, keep the existing `init_state.rb` recovery path.
+
+If `.planning/STATE.md` contains blockers with `type: PENDING_TEMPLATE`, stop normal dispatch and report the missing depth spec template. The blocker must name the codebase, topic, matched path, missing template path, and impact.
+
+Use these generators:
+
+| Script | Generates |
+|--------|-----------|
+| `init_workflow.rb` | `.planning/workflows/*.yaml` and workflow README from bundled templates. |
+| `init_state.rb` | `.planning/STATE.md` YAML front matter. |
+| `sync_artifacts.rb` | `.planning/artifacts/index.yaml` from active workflow outputs. |
+
+The generated files may be project-specific instances, but their creation path must remain inside this skill.
+
+## Boundaries
+
+- Do not modify existing `workflow-*` skill behavior.
+- Auto-execute only the parallel window returned by the inspector while the runtime loop is active. Use task agents when isolation is safe; otherwise use `serial_fallback_order`.
+- Do not infer a missing workflow. If `.planning/STATE.md` has no machine-readable front matter, ask to initialize workflow state.
+- Do not skip CP-1, CP-3, or CP-4. CP-2 can only be skipped if the active workflow config explicitly allows it.
+- Do not treat `.planning/pipeline-state.md` as the primary state source when YAML front matter exists in `.planning/STATE.md`.
+- Do not advance a step if its `meta_output` `.meta.json` is missing or incomplete.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `.planning/STATE.md` | Primary runtime state, YAML front matter + auto-generated Markdown body. |
+| `.planning/workflows/<current_flow>.yaml` | Active workflow config: step topology, CP definitions, meta_output contracts. |
+| `failure_branch.workflow_config` | Optional remediation workflow returned by the inspector. |
+| active workflow `artifact_registry.source` | Artifact status registry with content validation. |
+| `scripts/inspect_state.rb` | Deterministic state and next-action inspector. |
+| `scripts/init_workflow.rb` | Creates required workflow YAML files from bundled templates. |
+| `scripts/init_state.rb` | Creates or repairs `.planning/STATE.md` front matter. |
+| `scripts/sync_artifacts.rb` | Generates artifact registry with content validation. |
+| `scripts/validate_state.rb` | Verifies STATE.md, workflow steps, dependencies, outputs, meta outputs, and artifact statuses agree before dispatch or writeback. |
+| `scripts/advance_state.rb` | State writeback + Markdown body auto-generation. |
+| `scripts/update_triage_route.rb` | Deterministically updates `.planning/requirements/{feature}/入口分诊.meta.json` route/status after clarify or wayfinder. |
+| `scripts/manage_lessons.rb` | Lesson candidate selector and evidence-based template writer. |
+| `templates/` | Portable workflow templates used by `init_workflow.rb`. |

package/plugins/devflow-core/skills/workflow-orchestrator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Workflow Orchestrator"
+  short_description: "Route .planning workflows, checkpoints, remediation, and parallel windows"
+  default_prompt: "Inspect .planning/STATE.md and route the workflow safely"