@tiic-tech/openworkflow 0.1.0

package/references/discovery-artifact-contracts.md

@@ -0,0 +1,155 @@
+# Discovery Artifact Contracts
+
+M10 defines the artifact layer consumed by the audit-first discovery loop. The
+artifact layer must answer one question:
+
+> What is the smallest durable state an agent needs to continue accurately?
+
+## Format Responsibilities
+
+- YAML is the source of truth. Agents load YAML first because it is structured,
+  diffable, compact, and validateable.
+- Markdown is a short human audit note. It explains why a state changed, but it
+  must not be the only source of a decision.
+- HTML is an optional generated review surface. It is useful for humans when
+  comparing evidence, screenshots, and diagrams, but it must be generated from
+  YAML or evidence manifests and should not be loaded by default by agents.
+- Raw evidence is referenced by path or URL from YAML. Screenshots, logs,
+  recordings, prototype URLs, and browser notes stay outside the source-of-truth
+  contract.
+
+## Progressive Disclosure
+
+Agents should load context in this order:
+
+1. Level 0: workflow and audit indexes.
+2. Level 1: command context packet and artifact contract registry.
+3. Level 2: the current stage YAML artifact named by the index.
+4. Level 3: short Markdown note when the YAML does not explain intent enough.
+5. Level 4: generated HTML and raw evidence only for human review or evidence
+   inspection.
+
+The first two levels must be enough to know what not to load.
+
+## Discovery Artifact Types
+
+### vision_session
+
+Produced by `/ow:vision`.
+
+Source of truth path:
+`.openworkflow/vision/sessions/<id>/VISION_SESSION.yaml`
+
+Purpose:
+Capture one focused vision clarification session without turning it into a
+feature ranking or prototype task list.
+
+Required facts:
+
+- current question
+- stable answers
+- unresolved questions
+- vision delta
+- handoff readiness
+
+### validation_target
+
+Produced by `/ow:validation`.
+
+Source of truth path:
+`.openworkflow/validation/<id>/VALIDATION.yaml`
+
+Purpose:
+Name the highest-leverage thing to validate first and explain why it is
+existential, supporting, later, or out of scope.
+
+Required facts:
+
+- core question
+- feature classification
+- critical assumptions
+- prototype scope
+- acceptance criteria
+- decision options
+
+### prototype_evidence
+
+Produced by `/ow:proto`.
+
+Source of truth path:
+`.openworkflow/prototypes/<id>/EVIDENCE.yaml`
+
+Purpose:
+Record the prototype mode, reference analysis, static concept direction,
+runnable implementation, verification evidence, self-critique, and what remains
+unknown.
+
+Required facts:
+
+- validation target
+- core question
+- prototype mode
+- reference analysis
+- visual direction
+- visual concept policy
+- static concept evidence
+- prototype artifact
+- run command or URL
+- implementation evidence
+- observations
+- evidence references
+- verification
+- self-critique
+- known limits
+- result status
+
+Validation notes:
+
+- Local evidence references must point to files inside the workflow root.
+- Visual, interaction, and 3D/material prototypes must either record generated
+  concept evidence or explicitly record that the user skipped image generation
+  with a reason.
+- Self-critique dimensions must be populated before handoff.
+
+### decision_record
+
+Produced internally by `/ow:decision` through `/ow:proto` or `/ow:tune`.
+
+Source of truth path:
+`.openworkflow/decisions/<id>/DECISION.yaml`
+
+Purpose:
+Record the user-reviewed or tune-reviewed outcome of the prototype loop and the
+authorized next user-facing command. This is an audit artifact; users should not
+need to invoke `/ow:decision` manually during normal proto/tune loops.
+
+Required facts:
+
+- reviewed evidence
+- outcome
+- rationale
+- accepted scope
+- rejected scope
+- revision scope
+- next command
+- follow-up questions
+
+Outcome values:
+
+- `continue`: evidence is accepted and may hand off to design.
+- `revise`: user requested another tune pass.
+- `pivot`: user wants to change direction.
+- `stop`: user wants to stop the loop.
+- `needs_more_evidence`: evidence is inconclusive.
+
+## First-Consumer Rules
+
+As an agent, I want every artifact to be readable in under one screen before I
+open any evidence. To make that possible:
+
+- Use stable identifiers and paths.
+- Put the current decision state near the top.
+- Keep narrative in Markdown notes, not YAML fields.
+- Reference evidence instead of embedding it.
+- Record what is forbidden or deferred so later agents do not reopen scope.
+- Include a handoff field that names the next command.

package/references/engineering-skill-reference-research.md

@@ -0,0 +1,204 @@
+# Engineering Skill Reference Research
+
+M08 studies `mattpocock/skills` as a reference for improving OpenWorkflow skill
+and command design before M09 deepens the discovery loop.
+
+Reference clone:
+
+- Source: `https://github.com/mattpocock/skills/tree/main/skills/engineering`
+- Local path: `/tmp/mattpocock-skills`
+- Inspected commit: `e74f0061bb67222181640effa98c675bdb2fdaa7`
+
+## Reference Skill Inventory
+
+The engineering set is intentionally small and composable:
+
+- `grill-with-docs`: one-question-at-a-time interrogation that updates domain
+  glossary and ADRs when decisions crystallize.
+- `prototype`: throwaway prototypes that answer one question, split into logic
+  and UI branches.
+- `tdd`: red-green-refactor through vertical slices, with strong warnings
+  against bulk horizontal test writing.
+- `diagnose`: disciplined bug loop: feedback loop, reproduce, hypothesize,
+  instrument, fix, regression-test, cleanup.
+- `triage`: issue state machine with explicit categories, states, and
+  maintainer checkpoints.
+- `to-prd`: synthesize current context into a PRD without re-interviewing.
+- `to-issues`: break a PRD or plan into vertical-slice issues.
+- `zoom-out`: ask for a higher-level system view when local context is not
+  enough.
+- `improve-codebase-architecture`: look for deepening opportunities using
+  shared architectural vocabulary.
+- `setup-matt-pocock-skills`: repo setup for issue tracker and domain docs.
+
+## Distinctive Patterns
+
+### 1. Small Skills, Strong Boundaries
+
+Each skill has a narrow job and refuses adjacent work. `prototype` does not
+become production implementation. `diagnose` does not hypothesize before it has
+a feedback loop. `tdd` does not write all tests before implementation.
+
+OpenWorkflow should adopt this boundary style for command protocols. Each
+`/ow:*` command should state:
+
+- what question it answers
+- what it may read
+- what it may write
+- what it must not create
+- which command may follow
+
+### 2. Feedback Loops Are First-Class
+
+The reference skills are strongest when they define the feedback loop before
+work starts:
+
+- `diagnose` requires a deterministic pass/fail loop before cause analysis.
+- `tdd` requires one failing behavior test before implementation.
+- `prototype` requires one explicit question and one command to run.
+
+OpenWorkflow should encode this directly in M09. `/ow:prototype` should not be
+"build a demo"; it should be "build the smallest runnable artifact that answers
+the current validation question."
+
+### 3. Progressive Disclosure
+
+Several skills use small entrypoint files with focused supporting references:
+
+- `prototype/SKILL.md` routes to `LOGIC.md` or `UI.md`.
+- `tdd/SKILL.md` links to test, mocking, interface-design, and refactoring
+  references.
+- `grill-with-docs/SKILL.md` links to context and ADR formats.
+
+OpenWorkflow should keep generated command files short, but allow each command
+to point at focused protocol references. This avoids giant command files while
+still giving agents precise rules when needed.
+
+### 4. Anti-Patterns Are Explicit
+
+The reference skills repeatedly say what not to do:
+
+- Do not leave prototypes rotting in the repo.
+- Do not write horizontal test suites.
+- Do not proceed with diagnosis without a repro loop.
+- Do not create ADRs unless the decision is hard to reverse, surprising, and
+  trade-off driven.
+
+OpenWorkflow should add explicit anti-pattern sections to command protocols.
+This is especially important for preventing artifact drift and token bloat.
+
+### 5. Human Checkpoints Are Concrete
+
+The skills do not ask vague approval questions. They ask for specific
+checkpoint decisions:
+
+- Which interface should be tested?
+- Which vertical slices are too coarse or too fine?
+- Which architecture candidate should be explored?
+- Is this issue ready for an AFK agent?
+
+OpenWorkflow should use the same style: each `/ow:*` command should know when
+to ask the user and what kind of answer is needed.
+
+## Adopt
+
+OpenWorkflow should adopt these patterns directly:
+
+- one-question-at-a-time clarification for `/ow:vision`
+- explicit "question being answered" for `/ow:validation` and `/ow:prototype`
+- prototype branches by question type: logic/state vs UI/experience
+- one command to run a prototype
+- anti-pattern sections in generated command protocols
+- vertical-slice thinking for later `/ow:change`
+- diagnosis-style feedback-loop discipline for future bug workflows
+- sparing ADR logic: record only decisions that are hard to reverse,
+  surprising, and trade-off driven
+
+## Adapt
+
+These patterns are useful but must be adapted:
+
+- `CONTEXT.md` should map to `.openworkflow/context/CONTEXT.md` and
+  `.openworkflow/context/CONTEXT_MAP.yaml`, not become a separate root-level
+  source of truth.
+- ADRs can inform future decisions, but OpenWorkflow's primary durable records
+  are `.openworkflow/decisions/` contracts.
+- `to-prd` and `to-issues` map conceptually to `/ow:spec` and `/ow:change`,
+  but M09 should not implement those yet.
+- `prototype` should keep its throwaway mindset, but OpenWorkflow should still
+  write durable prototype evidence under `.openworkflow/prototypes/`.
+- Issue tracker states are useful for later team execution, but OpenWorkflow
+  should first express state in local contracts before integrating GitHub,
+  Linear, or other trackers.
+
+## Reject For Now
+
+OpenWorkflow should not adopt these as M09 defaults:
+
+- GitHub issue tracker as the central planning artifact.
+- Root-level `CONTEXT.md` and `docs/adr/` as mandatory structure.
+- Skill-specific setup command as a prerequisite for core workflow use.
+- Broad production implementation protocols before the discovery loop is
+  stable.
+- Copying reference skill content verbatim into generated OpenWorkflow command
+  files.
+
+## M09 Implications
+
+M09 should deepen the discovery loop:
+
+```txt
+/ow:vision -> /ow:validation -> /ow:prototype -> /ow:decision
+```
+
+### /ow:vision
+
+Adopt `grill-with-docs` style:
+
+- ask one question at a time
+- recommend an answer for each question
+- inspect repo context when the answer can be discovered
+- sharpen fuzzy language into canonical terms
+- update `.openworkflow/vision/` and `.openworkflow/context/` only when the
+  concept is stable
+- avoid creating validation, prototype, spec, change, or runtime artifacts
+
+### /ow:validation
+
+Borrow the "answer one question" discipline:
+
+- identify the core validation question
+- classify features as existential, supporting, later, or out of scope
+- define what evidence would prove or disprove the current product direction
+- produce a prototype brief, not a production plan
+
+### /ow:prototype
+
+Adapt `prototype` directly:
+
+- choose a branch based on the validation question:
+  - logic/state prototype
+  - UI/experience prototype
+- make the prototype obviously throwaway
+- provide one command or URL to run it
+- surface the relevant state or variants
+- write durable evidence and result artifacts under `.openworkflow/prototypes/`
+- forbid spec, change, team, persistence, and production hardening
+
+### /ow:decision
+
+Combine prototype cleanup and ADR selectivity:
+
+- record what the prototype answered
+- choose `continue`, `pivot`, `stop`, or `needs_more_evidence`
+- keep only the decision-rich evidence
+- only authorize `/ow:spec` when the prototype evidence supports continuation
+- archive or mark throwaway prototype artifacts instead of letting them rot
+
+## Key Design Rule
+
+OpenWorkflow should learn from the reference repo's engineering discipline, but
+keep its own core contract:
+
+> Commands may be small and composable, but durable truth lives in
+> `.openworkflow/`, not in chat memory, issue comments, or tool-specific files.

package/references/npm-cli-architecture.md

@@ -0,0 +1,63 @@
+# npm-first CLI Architecture
+
+OpenWorkflow should be distributed as an npm package with an `openworkflow`
+binary.
+
+Primary initialization flow:
+
+```bash
+npx openworkflow init <folder> --tools codex
+openworkflow validate --root <folder>
+```
+
+## Source Of Truth
+
+Initialized projects use `.openworkflow/` as the platform-independent source of
+truth:
+
+```txt
+.openworkflow/
+  workflow/
+  context/
+  vision/
+  validation/
+  prototypes/
+  decisions/
+  specs/
+  changes/
+  runtime/
+```
+
+Tool-specific folders are adapters. For Codex:
+
+```txt
+.codex/
+  agents/
+  skills/
+  commands/
+```
+
+The adapter can be regenerated from `.openworkflow/`; it must not become the
+canonical workflow state.
+
+## Package Layout
+
+```txt
+packages/
+  cli/
+    src/
+  core/
+    src/
+  adapters/
+    codex/
+      src/
+```
+
+`core` owns contract generation and validation. `cli` owns argument parsing and
+command routing. `adapters/*` generate tool-specific surfaces.
+
+## M04 Scope
+
+M04 provides a minimal working CLI foundation. It does not publish to npm or
+replace every existing Python prototype helper.
+

package/references/runtime-command-surface.md

@@ -0,0 +1,169 @@
+# Runtime Command Surface
+
+This reference records runtime command-surface decisions from dogfooding a real
+`/ow:vision -> /ow:validation -> /ow:proto -> /ow:decision` run.
+
+## OpenSpec Findings
+
+OpenSpec separates what a command means from where a tool expects that command
+to live:
+
+- Command content is tool-agnostic.
+- Tool adapters decide file path and frontmatter.
+- OpenSpec's older Codex adapter used global prompt files, but Codex's official
+  custom workflow mechanism is repo-local Skills.
+- OpenWorkflow's Codex adapter should generate Skills under `.agents/skills/`.
+- Artifact instructions use XML-style tags such as `<task>`, `<rules>`, and
+  `<template>`.
+- HTML comments tell the agent which sections are constraints and must not be
+  copied into output artifacts.
+
+OpenWorkflow should adopt the adapter separation and XML/comment convention,
+but keep its own validation-first discovery loop.
+
+## Minimal Init
+
+`openworkflow init` should create the runtime substrate plus inert artifact
+templates advertised by `ARTIFACT_CONTRACTS.yaml`:
+
+```txt
+.openworkflow/
+  config.yaml
+  workflow/
+    WORKFLOW_INDEX.yaml
+  audit/
+    COMMAND_AUDIT_INDEX.yaml
+    CONTEXT_PACKETS.yaml
+    ARTIFACT_CONTRACTS.yaml
+    DISCLOSURE_LEVELS.yaml
+  vision/_templates/VISION_SESSION.yaml
+  validation/_templates/VALIDATION.yaml
+  prototypes/_templates/EVIDENCE.yaml
+  decisions/_templates/DECISION.yaml
+  design/_templates/PRODUCT_DESIGN.yaml
+```
+
+Stage indexes and active artifacts are lazy-created by commands:
+
+- `/ow:vision` creates `.openworkflow/vision/`.
+- `/ow:validation` creates `.openworkflow/validation/`.
+- `/ow:proto` creates `.openworkflow/prototypes/`.
+- `/ow:tune` updates `.openworkflow/prototypes/` and writes internal decision audit records.
+- `/ow:design` creates `.openworkflow/design/`.
+- `/ow:spec` creates `.openworkflow/specs/`.
+
+This keeps a new target repo from pretending every workflow stage already
+exists while still making advertised authoring templates available to agents.
+
+## Codex Skill Registration
+
+For Codex, OpenWorkflow commands should be generated as repo-local Skills:
+
+```txt
+.agents/skills/ow-vision/SKILL.md
+.agents/skills/ow-validation/SKILL.md
+.agents/skills/ow-proto/SKILL.md
+.agents/skills/ow-tune/SKILL.md
+.agents/skills/ow-design/SKILL.md
+```
+
+Each `SKILL.md` uses frontmatter:
+
+```yaml
+---
+name: ow-vision
+description: Create or refine the product vision contract through focused collaboration.
+---
+```
+
+Each skill may include `agents/openai.yaml` for Codex App display metadata:
+
+```yaml
+interface:
+  display_name: "/ow:vision"
+  short_description: "Create or refine the product vision contract through focused collaboration."
+  default_prompt: "Use /ow:vision for this OpenWorkflow repository."
+```
+
+The durable OpenWorkflow semantic command remains `/ow:vision`; the explicit
+Codex invocation is `$ow-vision`. Codex may also expose enabled Skills in the
+slash command list, but OpenWorkflow treats Skill registration as the adapter
+contract.
+
+OpenWorkflow should not generate `.codex/commands/ow/*.md`,
+`.codex/skills/*`, or `$CODEX_HOME/prompts/ow-*.md` as the default Codex
+surface. Generated legacy files in those locations may be safely removed when
+they carry the OpenWorkflow generated marker.
+
+## Interactive Command Behavior
+
+Interactive commands should be quiet:
+
+- Ask one clear question.
+- Do not narrate routine file reads, writes, or validation.
+- Do not run full validation after every user answer.
+- Save checkpoints when a stage completes, when the user asks to save, or when
+  the command needs a durable handoff.
+
+Agent-only protocol should live in XML-style blocks and comments, for example:
+
+```xml
+<agent_protocol>
+<!-- Internal instructions. Do not expose routine protocol steps to the user. -->
+<inner_thinking>
+Private reasoning, critique, and scope checks. Do not expose chain-of-thought.
+</inner_thinking>
+</agent_protocol>
+
+<user_behavior>
+Ask one question at a time. Keep the visible response short.
+</user_behavior>
+```
+
+## /ow:tune And Internal Decision Audit
+
+`/ow:tune` is the user-facing prototype iteration command. `/ow:tune` and
+`/ow:tune:proto` default to the current prototype. If no current prototype
+exists but a current validation target exists, tune may orchestrate first
+prototype creation through `/ow:proto` behavior.
+
+`/ow:decision` remains an internal audit command. Proto and tune flows write
+decision records automatically after evidence changes or user review outcomes.
+Normal user-facing handoffs should point to `/ow:tune`, `/ow:design`, or
+`/ow:validation`, not ask users to manually invoke `/ow:decision`.
+
+## /ow:design
+
+`/ow:design` bridges accepted prototype evidence to product development. It is
+not production implementation and not a one-shot giant PRD.
+
+Required artifact:
+
+```txt
+.openworkflow/design/<id>/PRODUCT_DESIGN.yaml
+```
+
+The required product design should capture:
+
+- accepted prototype evidence
+- target users and user personas
+- user journey map
+- user stories
+- feature matrix
+- KANO classification and priority
+- product behavior model
+- UX states and edge cases
+- accepted, rejected, and deferred scope
+- open questions
+- readiness for `/ow:spec`
+
+Conditional packets may be created only when needed:
+
+- `TECH_SPEC.yaml`
+- `FRONTEND_SPEC.yaml`
+- `BACKEND_SPEC.yaml`
+- `API_CONTRACT.yaml`
+- `DB_SCHEMA_MODEL.yaml`
+
+These packets must remain opt-in so `/ow:design` does not recreate the artifact
+bloat that OpenWorkflow is trying to avoid.