@openflowjs/cli 0.2.0

package/dist/core-artifacts/openflow/skills/workflow-governance/references/knowledge-schema.md

@@ -0,0 +1,241 @@
+# Knowledge File Schema
+
+Complete schema definitions for `.openflow/knowledge/` files. Read this reference when creating, validating, or curating knowledge entries during `/openflow-finalize`.
+
+## Knowledge Types and ID Prefixes
+
+| Type | Prefix | Directory |
+|------|--------|-----------|
+| Decision | `D-NNN` | `knowledge/decisions/` |
+| Guideline | `G-NNN` | `knowledge/guidelines/` |
+| Pitfall | `P-NNN` | `knowledge/pitfalls/` |
+| Process | `PR-NNN` | `knowledge/processes/` |
+
+Use zero-padded sequential numbers: `001-`, `002-`, `003-`. Check existing files before creating to avoid collisions.
+
+> Note: The `problems/` directory is a legacy alias for `pitfalls/`. New entries should use `pitfalls/`. Existing `problems/` entries remain valid and use the same `P-NNN` prefix and `type: pitfall` schema.
+
+## Decision Files (`decisions/NNN-<slug>.md`)
+
+```yaml
+---
+id: D-NNN
+type: decision
+date: YYYY-MM-DD
+scope: [file, package, concept]
+tags: [category, category]
+evidence:
+  - iteration: <iteration-id>
+    outcome: success | partial | failure
+    summary: <one line>
+status: active | superseded | deprecated
+superseded_by: null | D-NNN
+applies_to: [file, package, concept]
+---
+
+## Decision
+
+<One sentence stating the decision.>
+
+## Rationale
+
+<Why this decision was made.>
+
+## Pattern
+
+<Reusable pattern this decision exemplifies.>
+
+## Source
+
+- Iteration: <iteration-id>
+```
+
+## Pitfall Files (`pitfalls/NNN-<slug>.md`)
+
+Pitfalls cover both known traps to avoid (preventive) and problems that were encountered and resolved (reactive).
+
+```yaml
+---
+id: P-NNN
+type: pitfall
+date: YYYY-MM-DD
+scope: [file, package, concept]
+tags: [category, category]
+evidence:
+  - iteration: <iteration-id>
+    outcome: success | partial | failure
+    summary: <one line>
+symptoms:
+  - <observable symptom string>
+---
+
+## Pitfall
+
+<One sentence describing the known problem.>
+
+## Symptoms
+
+<Observable signs that this pitfall has occurred or is occurring.>
+
+## Root Cause
+
+<What typically causes this issue.>
+
+## Prevention
+
+<How to avoid this pitfall in the future.>
+
+## Fix
+
+<How to resolve it when encountered.>
+
+## Source
+
+- Iteration: <iteration-id>
+```
+
+## Guideline Files (`guidelines/NNN-<slug>.md`)
+
+```yaml
+---
+id: G-NNN
+type: guideline
+date: YYYY-MM-DD
+scope: [file, package, concept]
+tags: [category, category]
+evidence:
+  - iteration: <iteration-id>
+    outcome: success | partial | failure
+    summary: <one line>
+---
+
+## Guideline
+
+<One sentence describing the recommended practice.>
+
+## When to Apply
+
+<Conditions under which this guideline is relevant.>
+
+## Pattern
+
+<The recommended approach.>
+
+## Source
+
+- Iteration: <iteration-id>
+```
+
+## Process Files (`processes/NNN-<slug>.md`)
+
+```yaml
+---
+id: PR-NNN
+type: process
+date: YYYY-MM-DD
+scope: [file, package, concept]
+tags: [category, category]
+evidence:
+  - iteration: <iteration-id>
+    outcome: success | partial | failure
+    summary: <one line>
+---
+
+## Process
+
+<One sentence describing the process.>
+
+## When to Follow
+
+<Conditions under which this process should be applied.>
+
+## Steps
+
+<Numbered list of steps to follow.>
+
+## Validation
+
+<How to verify the process was followed correctly.>
+
+## Source
+
+- Iteration: <iteration-id>
+```
+
+## Lifecycle
+
+1. **Creation**: Knowledge files are created during `/openflow-finalize` when durable knowledge meets extraction criteria.
+2. **Retrieval**: Knowledge files are read during `/openflow-spec` and `/openflow-implement` by the `knowledge-retrieval` skill.
+3. **Superseding**: When a decision is overturned, set `status: superseded` and `superseded_by` to the new decision ID. Do not delete old files.
+4. **Removal**: Knowledge entries can be removed only by explicit user request. Move to `knowledge/archive/` rather than deleting.
+
+## Knowledge Index Structure
+
+Knowledge indexes provide fast lookup without scanning all files. They are maintained by the `knowledge-curator` during the archive phase.
+
+### catalog.json
+
+Top-level machine-readable index at `knowledge/catalog.json`:
+
+```json
+{
+  "version": 1,
+  "updated_at": "YYYY-MM-DD",
+  "entries": [
+    {
+      "id": "D-001",
+      "type": "decision",
+      "title": "Short title",
+      "tags": ["tag1"],
+      "scope": ["package-a"],
+      "summary": "One-line summary"
+    }
+  ]
+}
+```
+
+Fields:
+- `version` (integer): Schema version. Currently `1`.
+- `updated_at` (string): ISO date of last update (`YYYY-MM-DD`).
+- `entries` (array): All knowledge entries across all types.
+  - `id` (string): Knowledge ID with type prefix (`D-NNN`, `G-NNN`, `P-NNN`, `PR-NNN`).
+  - `type` (string): One of `decision`, `guideline`, `pitfall`, `process`.
+  - `title` (string): Short human-readable title.
+  - `tags` (array of strings): Categories for retrieval.
+  - `scope` (array of strings): Affected files, packages, or concepts.
+  - `summary` (string): One-sentence summary for quick scanning.
+
+### Per-type index.json
+
+Each knowledge subdirectory has its own `index.json` for type-scoped lookups:
+
+`knowledge/decisions/index.json`, `knowledge/guidelines/index.json`, `knowledge/pitfalls/index.json`, `knowledge/processes/index.json`
+
+```json
+{
+  "type": "decision",
+  "entries": [
+    {
+      "id": "D-001",
+      "title": "Short title",
+      "tags": ["tag1"],
+      "scope": ["package-a"],
+      "summary": "One-line summary"
+    }
+  ]
+}
+```
+
+### CATALOG.md
+
+`knowledge/CATALOG.md` is a human-readable panoramic directory of all knowledge. It is generated or updated by the archive phase and provides a browsable overview for developers and reviewers.
+
+### Index Update Timing
+
+Indexes are maintained exclusively during the `/openflow-finalize` phase by the `knowledge-curator` agent:
+
+1. After new knowledge files are created, regenerate `catalog.json` from all knowledge files.
+2. Update the relevant per-type `index.json` files for any types that had new or modified entries.
+3. Regenerate `CATALOG.md` from the updated catalog data.
+
+Indexes must never be modified outside of the archive phase.

package/dist/core-artifacts/openflow/skills/workflow-governance/references/state-files.md

@@ -0,0 +1,148 @@
+# State Files
+
+This reference covers OpenFlow's machine-readable state files and human-readable status mirrors. AI agents must never write `flow.json` or `current.json` directly — use the openflow CLI commands defined in `cli-reference`.
+
+## current.json
+
+`current.json` points commands to the active iteration.
+
+Location: `.openflow/current.json`
+
+Shape:
+
+```json
+{
+  "activeIteration": "2026-05-09-openflow-spec-prompts"
+}
+```
+
+Rules:
+
+- `activeIteration` must be a folder name under `.openflow/iterations/`.
+- Use `null` when no iteration is active.
+- Do not store stage, level, or gate state here. Those belong in the iteration `flow.json`.
+- Update this file via `openflow iteration create|switch|close`.
+
+## flow.json
+
+`flow.json` is the machine-readable state for one iteration.
+
+Location: `.openflow/iterations/<iteration-id>/flow.json`
+
+Spec-stage shape:
+
+```json
+{
+  "id": "2026-05-09-openflow-spec-prompts",
+  "title": "OpenFlow spec prompt design",
+  "level": "2",
+  "stage": "spec",
+  "revision": 1,
+  "gate": "review_required",
+  "createdAt": "2026-05-09T10:00:00+08:00",
+  "updatedAt": "2026-05-09T10:30:00+08:00",
+  "activeTask": null
+}
+```
+
+Rules:
+
+- Keep `id` equal to the iteration folder name.
+- Use `stage: "spec"` throughout the spec phase.
+- Use `stage: "implement"` while implementing approved tasks.
+- Use `stage: "finalize"` while preparing `SUMMARY.md` and final validation.
+- Use `stage: "archived"` only after final validation passes and the iteration is ready to move under `.openflow/archive/`.
+- Use `level` values `"0"`, `"1"`, `"2"`, or `"3"`.
+- Increment `revision` when `SPEC.md`, `TASKS.md`, or `PLAN.md` changes materially.
+- Update `updatedAt` whenever durable artifacts change.
+- Keep `activeTask` as `null` during spec.
+- Set `activeTask` to the active `T-###` during implement.
+- Set `activeTask` back to `null` before final archive.
+- Store gate status here instead of parsing `STATE.md`.
+
+**flow.json must be modified only via openflow CLI commands** — never written directly by AI agents:
+
+- Gate changes: `openflow flow set-gate <gate>`
+- Stage transitions: `openflow flow set-stage <stage>`
+- Revision increments: `openflow flow inc-revision`
+- Task activation: `openflow flow set-task <T-###>` or `openflow flow set-task -`
+- Drift recovery: `openflow flow restart-spec --reason "<why>" --task <T-###>`
+
+The initial `flow.json` is created by `openflow iteration create`.
+
+## STATE.md
+
+`STATE.md` is a readable status summary. It mirrors `flow.json` but does not replace it.
+
+Location: `.openflow/iterations/<iteration-id>/STATE.md`
+
+Template:
+
+```markdown
+# OpenFlow State
+
+- Flow: 2026-05-09-openflow-spec-prompts
+- Title: OpenFlow spec prompt design
+- Stage: spec
+- Level: 2
+- Revision: 1
+- Active task: none
+- Gate status: review_required
+
+## Open Questions
+
+- None.
+
+## Last Update
+
+- 2026-05-09T10:30:00+08:00: Spec artifacts prepared for review.
+
+## Next Action
+
+- Run `openflow review --flow .openflow/iterations/2026-05-09-openflow-spec-prompts --mode spec`.
+```
+
+Rules:
+
+- Keep it short.
+- Update it after the other artifacts so it reflects reality.
+- Do not hide scope, acceptance, or task detail here; link to `SPEC.md` and `TASKS.md` by implication through the same folder.
+
+## Review Files
+
+Review artifacts live under `.openflow/iterations/<iteration-id>/reviews/`.
+
+Only `spec-review.json` is used in the workflow (no archive-review.json). The Review UI displays SPEC.md as the primary review target. PLAN.md, TASKS.md, and CONTEXT.md are shown as collapsible reference material.
+
+### spec-review.json
+
+Location: `reviews/spec-review.json`
+
+Shape:
+
+```json
+{
+  "stage": "spec",
+  "revision": 1,
+  "status": "approved",
+  "reviewedAt": "2026-05-09T10:45:00+08:00",
+  "comments": [],
+  "requestedChanges": []
+}
+```
+
+### spec-reviewer.md
+
+Location: `reviews/spec-reviewer.md` — Markdown output from the `artifact-reviewer` (mode: spec) AI subagent.
+
+### history.jsonl
+
+Location: `reviews/history.jsonl` — append-only log of review iterations.
+
+Rules:
+
+- The Review UI writes `spec-review.json`.
+- The main agent reads review files and updates `flow.json` and `STATE.md`.
+- Do not store review state in root `.openflow/REVIEW.json` for new iterations.
+- If review requests changes, revise the same iteration and run `openflow flow inc-revision`.
+- Preserve reviewer findings unless they are superseded by a later review file or history entry.

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

@@ -0,0 +1,119 @@
+# OpenFlow Workflow Rules
+
+## Iteration Resolution
+
+When a command starts:
+
+1. Read `.openflow/current.json`.
+2. If `activeIteration` points to an existing folder, read its `flow.json`.
+3. Continue the active iteration only when the stage matches the command or the user explicitly asks to revise it.
+4. Create a new iteration when there is no active iteration or the active iteration has moved beyond the requested command's stage.
+
+Suggested iteration id:
+
+```text
+YYYY-MM-DD-short-slug
+```
+
+Use the user's requested change to form the slug. Keep it stable once created.
+
+## Level Routing Decision Tree
+
+Route before writing the spec. Revise the route if exploration reveals more risk.
+
+Start at Level 1. Move up or down based on evidence.
+
+### Level 0 (Skip) -- Use when ALL are true:
+
+- Single file change
+- Under 10 lines
+- Zero risk (no API, schema, security, or migration impact)
+- Acceptance is obvious
+- No OpenFlow artifacts needed -- implement directly
+
+### Level 1 (Simple) -- Default starting point:
+
+Use when:
+
+- 1-3 files affected
+- No technical decisions required
+- No public API, schema, migration, security, package boundary, or broad docs impact
+- Validation is straightforward
+
+Artifacts: SPEC only (Goal + Scope + Non-Goals + Acceptance).
+Gate: No formal gate. Conversational confirm.
+
+### Level 2 (Standard) -- Use when ANY are true:
+
+- 3+ files or modules involved
+- Technical decisions required
+- User-visible behavior changes
+- Tests, docs, CLI behavior, or Review UI behavior changes
+- Acceptance needs explicit criteria
+- Shared components affected
+- Moderate unknowns but no architectural risk
+
+Artifacts: SPEC + PLAN + TASKS.
+Gate: Single review gate. SPEC.md is reviewed via Review UI (PLAN/TASKS/CONTEXT shown as reference). Approved review required before implement.
+
+### Level 3 (Deep) -- Use when ANY are true:
+
+- Architecture or package boundaries change
+- Public API, storage, migration, auth/security, performance, or extension contracts change
+- Multiple independent implementation tracks need coordination
+- Mistakes would be hard to detect with simple tests
+- The user is still making product decisions that materially affect the design
+- Data model changes or cross-boundary coordination required
+
+Artifacts: Full set (SPEC + PLAN + TASKS + reviews).
+Gate: 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).
+
+## Gate Values
+
+Recommended `flow.json.gate` values:
+
+- `draft`: artifacts are being prepared.
+- `review_required`: ready for human review.
+- `changes_requested`: review found changes.
+- `approved`: gate passed.
+- `skipped`: gate intentionally skipped for a Level 0 or Level 1 flow.
+- `blocked`: gate cannot proceed.
+
+## Revision Rules
+
+Increment `flow.json.revision` when any of these change materially:
+
+- `SPEC.md`
+- `TASKS.md`
+- `PLAN.md`
+
+Do not increment for formatting-only changes that do not alter scope, acceptance, or tasks.
+
+When revision increments after an approval:
+
+1. reset `flow.json.gate`
+2. update `STATE.md`
+3. append or preserve review history
+4. require review again when level requires it
+
+## Blocked State
+
+Use `blocked` when progress would otherwise guess across a material decision or failing gate.
+
+Record:
+
+- what is blocked
+- who or what can unblock it
+- which artifact needs revision
+- the last safe state
+
+Do not continue execution work while the gate is blocked.
+
+## Concurrent Iterations
+
+Multiple iterations can exist simultaneously under `.openflow/iterations/`. The active iteration in `.openflow/current.json` determines which iteration commands operate on by default.
+
+- Use `openflow iteration list` to see all iterations and their stages.
+- Use `openflow iteration switch <id>` to change the active iteration.
+- Starting a new spec (`/openflow-spec`) while another iteration is active creates a new iteration and switches to it.
+- The previous iteration remains in its current state and can be resumed later.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { runOpenFlowCli } from "./run-openflow-cli.js";
+export { runReviewMcpServer } from "./mcp/review-mcp-server.js";
+export { startReviewServer, type ReviewMode, type ReviewServerOptions, type RunningReviewServer } from "./mcp/review-server.js";
+export * from "./core/index.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { runOpenFlowCli } from "./run-openflow-cli.js";
+export { runReviewMcpServer } from "./mcp/review-mcp-server.js";
+export { startReviewServer } from "./mcp/review-server.js";
+export * from "./core/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAuE,MAAM,wBAAwB,CAAC;AAChI,cAAc,iBAAiB,CAAC"}

package/dist/mcp/review-mcp-server.d.ts

@@ -0,0 +1 @@
+export declare function runReviewMcpServer(): Promise<void>;