@openflowjs/cli 0.2.0

package/dist/core-artifacts/openflow/skills/spec/references/tasks-template.md

@@ -0,0 +1,99 @@
+# TASKS.md
+
+Execution checklist for `/openflow-implement`.
+
+Location: `.openflow/iterations/<iteration-id>/TASKS.md`
+
+Required for Level 2+ only. Level 0 and Level 1 do not produce TASKS.md.
+
+## Task Template
+
+```markdown
+# Tasks
+
+## Slice 1: <name>
+
+- [ ] T-001: <task outcome>
+  - **Files:** <files to create or modify>
+  - **Dependencies:** <T-### or "none">
+  - **Read First:** <files to read before starting>
+  - **Action:** <specific implementation steps>
+  - **Acceptance Criteria:** <observable condition proving completion>
+  - **Validation:** <command, check, or review signal expected>
+  - Evidence: pending
+
+## Slice 2: <name>
+
+- [ ] T-002: <task outcome>
+  - **Files:** <files to create or modify>
+  - **Dependencies:** T-001
+  - **Read First:** <files to read before starting>
+  - **Action:** <specific implementation steps>
+  - **Acceptance Criteria:** <observable condition>
+  - **Validation:** <command or check>
+  - Evidence: pending
+```
+
+## Field Definitions
+
+- **Files:** Files the task will create or modify. Enables file-level dependency detection.
+- **Dependencies:** Task IDs that must complete first. Use "none" for independent tasks.
+- **Read First:** Files the executor should read before starting implementation.
+- **Action:** Concrete steps specific enough that an agent can implement without chat history.
+- **Acceptance Criteria:** Observable condition proving completion. Must be binary-checkable (yes/no). Maps to SPEC.md acceptance criteria.
+- **Validation:** Command, check, or review signal that verifies correctness.
+- **Evidence:** Filled during `/openflow-implement`. Must remain `pending` during spec phase.
+
+## Anti-Pattern Rules (Banned Phrases)
+
+Tasks must NOT contain these vague phrases:
+
+- "Implement the feature" (without specifying what)
+- "Handle edge cases" (without listing which cases)
+- "Update relevant files" (without naming them)
+- "Fix issues" (without describing what is broken)
+- "Make it work" (without defining "work")
+- "Refactor as needed" (without stating what and why)
+- "Add appropriate tests" (without specifying test cases)
+- "Ensure proper handling" (without defining proper)
+
+Any task using these phrases without concrete detail fails the specificity test.
+
+## Specificity Test
+
+Every task must pass:
+
+1. Can an agent implement without reading chat history?
+2. Are target files named explicitly?
+3. Is the action concrete enough to start coding immediately?
+4. Is the validation check unambiguous?
+5. Does acceptance criteria map to SPEC.md?
+
+## Example Task
+
+```markdown
+## Slice 1: Add level field to flow.json
+
+- [ ] T-001: Add `level` field to flow.json schema and CLI
+  - **Files:** `src/flow/schema.ts`, `src/flow/create.ts`, `src/cli/flow-set.ts`
+  - **Dependencies:** none
+  - **Read First:** `src/flow/schema.ts`, `src/flow/create.ts`
+  - **Action:**
+    1. Add `level: 0 | 1 | 2 | 3` field to FlowSchema in `src/flow/schema.ts`
+    2. Set default `level: 1` in `src/flow/create.ts` createFlow function
+    3. Add `openflow flow set-level <0|1|2|3>` command in `src/cli/flow-set.ts`
+  - **Acceptance Criteria:** `flow.json` contains a `level` field; CLI accepts `set-level` with values 0-3; `npm test -- --grep "level"` passes
+  - **Validation:** `npm test -- --grep "level"` passes; `openflow flow set-level 2` succeeds
+  - Evidence: pending
+```
+
+## Rules
+
+- Use stable task IDs (T-001, T-002, etc.).
+- Group tasks by vertical slice rather than by abstract layer when possible.
+- Each task must have validation defined before execution starts.
+- Evidence stays `pending` until `/openflow-implement` runs validation.
+- Do not mark tasks complete during spec phase.
+- A checked task must include concrete evidence: command output, test result, screenshot, reviewer signal, extension result, or exact blocker text.
+- Evidence must not be only `done`, `complete`, `yes`, `pending`, `todo`, or similar status words.
+- Archive can leave a task unchecked only when Evidence starts with or clearly includes `deferred:`, `blocked:`, or `waived:` plus rationale.

package/dist/core-artifacts/openflow/skills/workflow-governance/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: openflow-workflow-governance
+description: Use with OpenFlow commands to decide level, stage, gate, review, and routing behavior.
+---
+
+# OpenFlow Workflow Governance
+
+Use this skill whenever an OpenFlow command needs to decide what workflow path is allowed.
+
+This skill owns durable rules. Commands should stay thin. Stage skills should use these rules instead of redefining them.
+
+## Core Model
+
+OpenFlow has three user-facing AI-tool commands:
+
+- `/openflow-spec`
+- `/openflow-implement`
+- `/openflow-finalize`
+
+The shell CLI is auxiliary. It installs assets, validates artifacts, starts the Review UI, and runs extensions. It does not own spec, implement, or finalize behavior.
+
+## Durable Unit
+
+One delivery effort lives in one folder:
+
+```text
+.openflow/iterations/<iteration-id>/
+```
+
+Only project-level control files live directly under `.openflow/`, such as:
+
+- `config.json`
+- `current.json`
+- `knowledge/` -- project-level durable knowledge store (decisions, guidelines, pitfalls, processes)
+
+Do not scatter iteration files at `.openflow/STATE.md` or `.openflow/SPEC.md`.
+
+## Directory Contract
+
+Project-level files:
+
+```text
+.openflow/
+  config.json
+  current.json
+  iterations/
+  archive/
+  knowledge/
+    decisions/
+    guidelines/
+    pitfalls/
+    processes/
+    archive/
+    catalog.json
+    CATALOG.md
+    decisions/index.json
+    guidelines/index.json
+    pitfalls/index.json
+    processes/index.json
+```
+
+Iteration files:
+
+```text
+.openflow/iterations/<iteration-id>/
+  flow.json
+  STATE.md
+  SPEC.md
+  CONTEXT.md
+  TASKS.md
+  PLAN.md
+  WORKING_MEMORY.md
+  reviews/
+    spec-reviewer.md
+    spec-review.json
+    plan-reviewer.md
+    history.jsonl
+  extensions/
+```
+
+`PLAN.md`, review outputs, and extensions are created only when useful or required by the stage.
+
+`config.json.language` controls the language for generated OpenFlow documents. Use the configured tag, such as `en-US` or `zh-CN`; if absent, default to `en-US`. SPEC.md is the only artifact whose body language follows `config.language` — all other artifacts and templates use English by default.
+
+## Source Of Truth
+
+- `flow.json` is the machine-readable state source — read-only for AI; modify only via openflow CLI commands. See `references/state-files.md`.
+- `config.json` is the project-level settings source.
+- `STATE.md` is a human-readable summary mirroring `flow.json`.
+- `SPEC.md` is the default human review document.
+- `PLAN.md` is the technical execution plan for Level 2+ iterations.
+- `CONTEXT.md`, `TASKS.md` are primarily AI execution support.
+- Review approval state belongs in `reviews/*.json`, not in comments inside `SPEC.md` or `PLAN.md`.
+- `WORKING_MEMORY.md` is per-iteration scratchpad. See `implement/references/working-memory.md`.
+
+For complete state file schemas and editing rules, see `references/state-files.md`.
+
+OpenFlow MCP is only for Review UI interaction. Do not use it as a config, current pointer, or flow-state API.
+
+Do not generate an HTML spec as the canonical artifact. The Review UI renders `SPEC.md` into HTML with consistent styling and interaction. HTML export can exist later as a derived artifact, not as source of truth.
+
+## ID Conventions
+
+Use stable IDs so Review UI, tasks, and future evidence can point to the same concepts:
+
+- Requirements: `R-001`, `R-002`
+- Decisions: `D-001`, `D-002`
+- Acceptance criteria: `A-001`, `A-002`
+- Tasks: `T-001`, `T-002`
+- Knowledge entries: `D-NNN` (decisions), `G-NNN` (guidelines), `P-NNN` (pitfalls), `PR-NNN` (processes)
+
+Do not renumber existing IDs during a revision unless the item was removed and the change is clearly noted.
+
+## Artifact Write Order
+
+Write order is level-conditional. Validate after writing with `openflow validate --flow .openflow/iterations/<iteration-id>` before crossing a stage boundary.
+
+### Level 0
+
+No OpenFlow artifacts. Skip entirely.
+
+### Level 1
+
+1. Iteration directory and `flow.json` are created by `openflow iteration create`.
+2. Write `CONTEXT.md` **only** when exploration produced findings worth preserving (optional for Level 1).
+3. Write `SPEC.md` (Goal + Scope + Non-Goals + Acceptance only). Use the template in `spec/references/spec-template.md`.
+4. Update `STATE.md` last so it summarizes the files actually written.
+
+### Level 2
+
+1. Iteration directory and `flow.json` are created by `openflow iteration create`.
+2. Write `CONTEXT.md` from confirmed exploration and assumptions. Use `spec/references/context-template.md`.
+3. Write `SPEC.md` for human review. Use `spec/references/spec-template.md`.
+4. After SPEC gate is approved: write `PLAN.md` (`spec/references/plan-template.md`) and `TASKS.md` (`spec/references/tasks-template.md`).
+5. Update `STATE.md` last so it summarizes the files actually written.
+
+### Level 3
+
+1. Iteration directory and `flow.json` are created by `openflow iteration create`.
+2. Write `CONTEXT.md` from confirmed exploration and assumptions.
+3. Write `SPEC.md` for human review.
+4. Submit SPEC for `artifact-reviewer` (mode: spec) AI review, then Human Review UI (Gate 1).
+5. After SPEC gate passes (`flow.json.gate` must be `approved`): write `PLAN.md` and `TASKS.md`.
+6. Submit PLAN+TASKS for `artifact-reviewer` (mode: plan) AI review only (no second human gate). Save output to `reviews/plan-reviewer.md`.
+7. Update `STATE.md` last so it summarizes the files actually written.
+
+When revising after feedback, preserve useful history and only change artifacts affected by the requested change.
+
+## Level Routing
+
+Choose the correct level based on scope, risk, and complexity.
+
+| Level | Name | Criteria | Artifacts | Gate |
+| --- | --- | --- | --- | --- |
+| 0 | Skip | Single file, <10 lines, zero risk | None -- skip OpenFlow entirely | No gate |
+| 1 | Simple | 1-3 files, no tech decisions | SPEC only (Goal + Scope + Non-Goals + Acceptance) | No formal gate (conversational confirm) |
+| 2 | Standard | 3+ files, needs tech decisions | SPEC + PLAN + TASKS | Single review gate (SPEC only, via Review UI) |
+| 3 | Deep | Architecture, security, migration, cross-boundary, data model, or high ambiguity | Full set (SPEC + PLAN + TASKS + reviews) | Single review gate (SPEC only, AI reviewer + Review UI) |
+
+### Level Selection Rules
+
+- Start at Level 1 by default. Move up or down based on evidence.
+- Downgrade to Level 0 only when the change is single file, under 10 lines, and zero risk.
+- Escalate to Level 2 when the work affects 3+ files, needs technical decisions, or involves shared components.
+- Escalate to Level 3 when the work changes architecture, package boundaries, public contracts, data models, security-sensitive behavior, performance-critical paths, or requires a migration/rollout strategy.
+
+Routing is performed by the main agent. Subagents may review routing rationale but cannot decide the stage or gate.
+
+## Stage Rules
+
+Valid stages:
+
+- `spec`: clarify and approve what should be built.
+- `implement`: implement approved tasks and collect evidence.
+- `blocked`: stop because a decision, dependency, permission, or failing gate prevents progress.
+- `finalize`: prepare final summary, validation, durable knowledge, and archive.
+- `archived`: closed. Do not resume except by creating a new iteration or explicitly reopening by user request.
+
+Do not cross stages silently. A command may prepare the next handoff, but it must not perform the next command's work.
+
+## Spec Phase Opening Sequence (Four Steps)
+
+At the start of the Spec phase for Level 2+ (after iteration is created, before writing SPEC.md), the agent must follow this opening sequence. Level 1 does not require this sequence — write SPEC.md directly.
+
+1. **Read repository state** (includes knowledge retrieval):
+   - First call the `knowledge-retrieval` skill to retrieve relevant project knowledge from `.openflow/knowledge/`.
+   - Then explore the codebase to understand current project state, architectural patterns, technical constraints, and prior decisions.
+   - Write exploration results and retrieved knowledge into CONTEXT.md.
+   - Do not skip this step and ask the user directly.
+
+2. **Write explicit assumptions**: in the Assumptions section of CONTEXT.md, record:
+   - Confirmed facts (from code exploration).
+   - Reasonable assumptions about unknowns (based on experience and context).
+   - Rationale and confidence level for each assumption.
+
+3. **At most ONE question**: only ask the user when:
+   - Assumptions cannot cover a critical information gap.
+   - The missing information would significantly affect implementation correctness.
+   - The information cannot be obtained through code exploration or reasonable inference.
+
+   Limit to at most ONE question per Spec phase.
+
+4. **Continue if not blocked**: if assumptions cover all necessary information, continue writing SPEC.md without asking. Do not ask just to "feel more certain".
+
+**Core principle**: prefer code exploration and explicit assumptions over user interaction. Ask only when assumptions truly cannot cover critical information, and at most one question.
+
+## Gate Rules
+
+Gate requirements are level-conditional:
+
+- **Level 0**: No gate. No OpenFlow artifacts.
+- **Level 1**: No formal gate. Conversational confirm with the user is sufficient.
+- **Level 2**: Single review gate. SPEC.md is reviewed via Review UI. PLAN/TASKS/CONTEXT are shown as reference material. Approved review required before implement.
+- **Level 3**: Single review gate. SPEC.md is reviewed by `artifact-reviewer` (mode: spec) AI then Human Review UI. PLAN+TASKS are reviewed by `artifact-reviewer` (mode: plan) AI only (no separate human gate).
+
+Changing `SPEC.md`, `TASKS.md`, or `PLAN.md` after approval increments `flow.json.revision` and resets the gate to `draft` or `changes_requested`.
+
+Completed implement tasks require evidence. A checked task with weak evidence is not complete.
+
+Finalize requires all required tasks, reviews, and extension results to be complete, passed, or explicitly deferred with rationale.
+
+## User Interaction Rules
+
+Ask questions only when the answer changes scope, acceptance, boundaries, platform, data, permissions, or risk.
+
+Prefer repository exploration and explicit assumptions over low-value questions.
+
+For Claude Code, blocking clarification must use the exact tool `AskUserQuestion`. Research the repository first, then use one call with exactly one high-signal question. Include a recommended answer with rationale when applicable, and do not replace that tool call with plain prose.
+
+Use short review loops:
+
+1. ask or revise
+2. update artifacts
+3. validate
+4. review
+5. repeat only while the gate is not satisfied
+
+## Reference
+
+For the detailed state machine and routing checklist, read `references/workflow.md`.
+
+For state file schemas (flow.json, current.json, STATE.md, review files) and editing rules, read `references/state-files.md`.
+
+For knowledge file schemas (decisions, guidelines, pitfalls, processes) and index structure, read `references/knowledge-schema.md`.
+
+## Subagent Scheduling Strategy
+
+This section defines how the main agent decides whether to use subagents during execution and how to schedule them in PLAN.md.
+
+### Difficulty Assessment
+
+Before executing each task, the main agent assesses difficulty:
+
+| Difficulty | Indicators | Executor | Review |
+|------------|-----------|----------|--------|
+| Simple | Single file, clear logic, 1-2 steps, config/docs | Dispatch `executor-quick` | None or `code-reviewer` (mode: compliance) |
+| Medium | Multi-file coordination, context understanding, 3-5 steps | Dispatch `executor-general` | `code-reviewer` (mode: compliance) |
+| Complex | Cross-module, architectural judgment, >5 steps | Dispatch `executor-deep` | `code-reviewer` (mode: compliance), then `code-reviewer` (mode: quality) |
+
+Difficulty assessment dimensions:
+- **File scope**: 1 file → Simple, 2-5 files → Medium, 6+ or cross-module → Complex
+- **Change type**: config/docs → Simple, feature/fix → Medium, architecture/security → Complex
+- **Risk level**: low → Simple, medium → Medium, high → Complex
+
+### Subagent Roles
+
+| Role | Agent File | Model | Tools | When Used |
+|------|-----------|-------|-------|-----------|
+| Executor (Deep) | `agents/openflow-executor-deep.md` | opus | Read, Write, Edit, Glob, Grep, Bash | Complex tasks: architecture, cross-module, security |
+| Executor (General) | `agents/openflow-executor-general.md` | sonnet | Read, Write, Edit, Glob, Grep, Bash | Standard tasks: features, bug fixes, integration |
+| Executor (Quick) | `agents/openflow-executor-quick.md` | haiku | Read, Write, Edit, Glob, Grep, Bash | Simple tasks: config, docs, single-file changes |
+| Code Reviewer | `agents/openflow-code-reviewer.md` | opus | Read, Glob, Grep, Bash | After executor completes (mode: compliance, quality) |
+| Artifact Reviewer | `agents/openflow-artifact-reviewer.md` | opus | Read, Glob, Grep, Bash | Spec/plan/evidence/docs review |
+| Explorer | `agents/openflow-explorer.md` | haiku | Read, Glob, Grep, Bash | Code search, file discovery, codebase exploration |
+| Knowledge Curator | `agents/openflow-knowledge-curator.md` | sonnet | Read, Glob, Grep, Bash, Write, Edit | Knowledge dedup, validation, indexing |
+
+### Review Level Decision
+
+| Difficulty | Compliance Review (code-reviewer mode: compliance) | Quality Review (code-reviewer mode: quality) |
+|-----------|------------------------------------------------------|------------------------------------------------|
+| Simple | Optional (if behavior changed) | No |
+| Medium | Yes | No |
+| Complex | Yes | Yes |
+
+### Model Selection
+
+| Task Complexity | Executor | Recommended Model |
+|----------------|----------|-------------------|
+| Simple (1-2 files, config/docs) | executor-quick | haiku |
+| Standard (multi-file, features/fixes) | executor-general | sonnet |
+| Complex (architecture, security) | executor-deep | opus |
+
+### Constraints
+
+- Subagents cannot make routing or phase-transition decisions.
+- Each executor subagent is fresh -- no inherited session context.
+- Spec compliance review must complete before code quality review (strict order).
+- Do not dispatch parallel executors for tasks that touch the same files.
+- Subagent usage is dynamic and based on difficulty -- it is not mandatory for all tasks.
+- `executor-quick` may BLOCK if task exceeds 1-2 file scope -- upgrade to `executor-general`.
+
+## Shared Reviewer Output Format
+
+All OpenFlow reviewers should follow this consistent output format for clarity and tool compatibility:
+
+```markdown
+## <Reviewer Type> Review
+
+Status: approved | changes_required
+
+### Findings
+
+- [BLOCKER] <issue>
+  - Evidence: <file/path and section or line if available>
+  - Fix: <specific change needed>
+
+### Coverage Notes
+
+- <brief notes on what was reviewed and coverage level>
+
+### Residual Risk
+
+- <remaining risk or "None identified.">
+```
+
+**Status values:**
+- `approved` - No blocking findings. Proceed.
+- `changes_required` - Blocking issues found. Fix and resubmit.
+
+**Severity levels:**
+- `BLOCKER` - Must fix before proceeding.
+- `WARNING` - Should fix but not blocking.
+- `INFO` - Observational, no action required.
+
+When no findings exist, use:
+```markdown
+### Findings
+
+No blocking findings.
+```
+
+## Knowledge Directory
+
+OpenFlow maintains a project-level knowledge store for cross-iteration learning:
+
+```text
+.openflow/
+  knowledge/
+    decisions/    # D-NNN
+    guidelines/   # G-NNN
+    pitfalls/     # P-NNN
+    processes/    # PR-NNN
+    archive/
+    catalog.json
+    CATALOG.md
+```
+
+For complete file schemas and index structure, see `references/knowledge-schema.md`.
+
+### Type Disambiguation: Guideline vs Pitfall
+
+- **Guideline** describes **what to do** -- a recommended practice, a proven pattern, a preferred approach.
+- **Pitfall** describes **what goes wrong** -- a known failure mode, a common mistake, a subtle bug. This includes both known traps to avoid (preventive) and problems that were encountered and resolved (reactive).
+
+If a knowledge entry could be either, prefer **guideline** when the primary value is showing the right way, and prefer **pitfall** when the primary value is warning about a specific failure that is hard to diagnose.
+
+### Extraction Criteria
+
+Not every iteration produces knowledge files. Only extract when:
+
+- **Decisions**: Affects multiple iterations, non-obvious architecture choice, involves a trade-off.
+- **Guidelines**: Reusable recommended practices that have been validated in at least one iteration, patterns that generalise beyond the current scope.
+- **Pitfalls**: Root cause was non-trivial to diagnose, fix pattern is reusable, the lesson prevents future mistakes.
+- **Processes**: Multi-step business workflows that require consistent adherence, operational procedures where deviation causes defects.
+
+### Numbering
+
+Use zero-padded sequential numbers: `001-`, `002-`, `003-`. Each knowledge type has its own ID prefix (D-NNN, G-NNN, P-NNN, PR-NNN).
+
+## Knowledge Index Structure
+
+Knowledge indexes provide fast lookup without scanning all files. They are maintained by the `knowledge-curator` during the archive phase. For complete index schemas, see `references/knowledge-schema.md`.
+
+Indexes must never be modified outside of the archive phase.