@tiic-tech/openworkflow 0.1.0

package/skills/build-prototype/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: build-prototype
+description: Turn a validation artifact into a focused prototype discovery plan and todo list. Use when the user wants to build the smallest local prototype for a core assumption before creating specs, changes, Agent Teams, runtime state, or production implementation plans.
+---
+
+# Build Prototype
+
+## Purpose
+
+Create and execute the prototype discovery loop for one validation target. This
+skill turns `VALIDATION.yaml` and `PROTOTYPE_BRIEF.md` into a constrained
+prototype plan and todo contract.
+
+Prototype work is not production work. It should answer the validation
+question quickly, often with hardcoded data, a single HTML file, or a small
+local demo.
+
+## Inputs
+
+Required:
+
+- `.codex/validation/<validation_id>/VALIDATION.yaml`
+- `.codex/validation/<validation_id>/PROTOTYPE_BRIEF.md`
+
+Optional:
+
+- `.codex/context/CONTEXT_MAP.yaml`
+- `.codex/vision/VISION_CONTRACT.yaml`
+- direct user constraints about the prototype medium or acceptance bar
+
+Do not load unrelated specs, changes, runtime state, reviews, archives, or
+implementation history unless the validation question explicitly depends on
+them.
+
+## Output
+
+Write prototype artifacts under:
+
+```txt
+.codex/prototypes/<prototype_id>/
+  PROTOTYPE_PLAN.md
+  TODO.yaml
+  RESULT.md
+  EVIDENCE.md
+  artifact/
+  archive/
+```
+
+`TODO.yaml` is the machine-readable prototype contract. `PROTOTYPE_PLAN.md` is
+the human-readable execution plan. `RESULT.md` and `EVIDENCE.md` are updated
+after local review or user feedback.
+
+## Workflow
+
+1. Load the validation contract and prototype brief.
+2. Keep the core question unchanged.
+3. Convert prototype `include` scope into a short todo list.
+4. Preserve `exclude` scope as hard boundaries.
+5. Prefer the smallest artifact that a user can experience locally.
+6. Initialize artifacts with `scripts/init_prototype.py`.
+7. Implement the prototype directly when the user asks for execution and the
+   scope remains small enough for the main agent.
+8. Use subagents only for narrow parallel work; prototype orchestration does not
+   require `/ow:team`.
+9. Record what was tested in `EVIDENCE.md` and the user-facing outcome in
+   `RESULT.md`.
+
+## Forbidden Defaults
+
+- Do not create `SPEC.yaml`, `CHANGE.yaml`, `.codex/runtime/`, or Agent Team
+  artifacts from this skill.
+- Do not add auth, persistence, deployment, billing, admin, upload, or full AI
+  integration unless the validation contract names that as the core assumption.
+- Do not expand the prototype to cover later features.
+- Do not treat code completeness as validation success; success means the core
+  question can be answered.
+
+## Handoff
+
+After user review, hand off to `/ow:decision`.
+
+Expected decision outcomes:
+
+- `continue`: prototype is strong enough to become a focused production slice
+- `pivot`: adjust the vision or validation target
+- `stop`: archive or clean the prototype path
+- `needs_more_evidence`: revise the prototype scope and test again

package/skills/build-prototype/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build Prototype"
+  short_description: "Create a focused prototype from validation artifacts"
+  default_prompt: "Use /ow:prototype to turn a validation target into a local prototype plan."

package/skills/build-prototype/references/prototype-protocol.md

@@ -0,0 +1,56 @@
+# Prototype Discovery Protocol
+
+Use this reference when creating or executing prototypes.
+
+## Prototype Is Not Production
+
+A prototype answers one validation question. It should not become a hidden
+production implementation plan.
+
+Allowed shortcuts:
+
+- hardcoded sample data
+- single HTML files
+- local-only assets
+- mocked LLM output
+- fake persistence in memory
+- narrow UI paths
+
+Avoid by default:
+
+- production database schemas
+- authentication
+- deployment setup
+- full component architecture
+- complete API design
+- broad test matrices
+- team runtime state
+
+## Prototype Todo Shape
+
+Todos should map directly to the validation include scope. Keep each item
+experience-facing when possible:
+
+```txt
+create interactive globe
+place sample flags
+show hover thumbnails
+open detail panel
+verify user can answer the core question
+```
+
+Do not turn prototype todos into a full backlog.
+
+## Evidence
+
+Evidence can be lightweight:
+
+- local URL or file path
+- screenshot path
+- user feedback summary
+- known constraints
+- decision recommendation
+
+Evidence should be enough for `/ow:decision` to record continue, pivot,
+stop, or needs_more_evidence.
+

package/skills/build-prototype/scripts/init_prototype.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Initialize OpenWorkflow prototype discovery artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+
+def q(value: str | None) -> str:
+    return "null" if value is None else json.dumps(value)
+
+
+def slugify(value: str) -> str:
+    return re.sub(r"[^A-Za-z0-9]+", "-", value.strip().lower()).strip("-") or "prototype"
+
+
+def yaml_list(items: list[str], indent: int) -> str:
+    prefix = " " * indent
+    if not items:
+        return f"{prefix}[]\n"
+    return "".join(f"{prefix}- {q(item)}\n" for item in items)
+
+
+def ensure_dir(path: Path, dry_run: bool) -> None:
+    if dry_run:
+        print(f"DIR  {path}")
+        return
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def write_file(path: Path, content: str, force: bool, dry_run: bool) -> None:
+    if path.exists() and not force:
+        print(f"SKIP {path}")
+        return
+    if dry_run:
+        action = "OVERWRITE" if path.exists() else "WRITE"
+        print(f"{action} {path}")
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    print(f"WRITE {path}")
+
+
+def touch_gitkeep(path: Path, dry_run: bool) -> None:
+    gitkeep = path / ".gitkeep"
+    if gitkeep.exists():
+        return
+    if dry_run:
+        print(f"WRITE {gitkeep}")
+        return
+    gitkeep.write_text("", encoding="utf-8")
+
+
+def todo_yaml(args: argparse.Namespace, prototype_id: str, artifact_path: str) -> str:
+    todo_items = args.todo or [f"Build prototype surface for {item}" for item in args.include]
+    lines = [
+        "schema_version: 0.1.0",
+        f"contract_id: prototype:{prototype_id}",
+        "contract_type: prototype",
+        f"title: {q(args.title)}",
+        "status: planned",
+        "source_artifacts:",
+    ]
+    lines.extend(f"  - {q(source)}" for source in args.source_artifact)
+    lines.extend(
+        [
+            "depends_on:",
+            f"  - {args.validation_contract}",
+            "produces: []",
+            f"validation_contract: {args.validation_contract}",
+            f"core_question: {q(args.core_question)}",
+            "prototype_scope:",
+            "  include:",
+        ]
+    )
+    lines.extend(f"    - {q(item)}" for item in args.include)
+    lines.append("  exclude:")
+    lines.extend(f"    - {q(item)}" for item in args.exclude)
+    lines.append("todo:")
+    for index, item in enumerate(todo_items, start=1):
+        task_id = f"P{index:03d}"
+        lines.extend(
+            [
+                f"  - task_id: {task_id}",
+                f"    title: {q(item)}",
+                "    status: planned",
+                "    acceptance:",
+                f"      - {q('Prototype demonstrates: ' + item)}",
+            ]
+        )
+    lines.extend(
+        [
+            "acceptance:",
+            *[f"  - {q(item)}" for item in args.acceptance],
+            "artifact:",
+            f"  path: {artifact_path}",
+            f"  type: {args.artifact_type}",
+            "decision_handoff:",
+            "  target: /ow:decision",
+            "  requires_user_review: true",
+            "result_artifact: RESULT.md",
+            "evidence_artifact: EVIDENCE.md",
+            "prototype_plan: PROTOTYPE_PLAN.md",
+            "updated_at: null",
+        ]
+    )
+    return "\n".join(lines) + "\n"
+
+
+def prototype_plan(args: argparse.Namespace, prototype_id: str, artifact_path: str) -> str:
+    return f"""# Prototype Plan: {args.title}
+
+Prototype id: `prototype:{prototype_id}`
+
+Validation source: `{args.validation_contract}`
+
+## Core Question
+
+{args.core_question}
+
+## Build
+
+{bullet_list(args.include)}
+
+## Do Not Build
+
+{bullet_list(args.exclude)}
+
+## Artifact
+
+- Path: `{artifact_path}`
+- Type: `{args.artifact_type}`
+
+## Acceptance
+
+{bullet_list(args.acceptance)}
+
+## Decision Handoff
+
+After local review, use `/ow:decision` to record whether this prototype
+supports `continue`, `pivot`, `stop`, or `needs_more_evidence`.
+"""
+
+
+def result_doc(args: argparse.Namespace, prototype_id: str) -> str:
+    return f"""# Prototype Result: {args.title}
+
+Prototype id: `prototype:{prototype_id}`
+
+Status: pending user review
+
+## Outcome
+
+Pending. Do not create production specs or changes until `/ow:decision`
+records the outcome.
+"""
+
+
+def evidence_doc(args: argparse.Namespace, prototype_id: str, artifact_path: str) -> str:
+    return f"""# Prototype Evidence: {args.title}
+
+Prototype id: `prototype:{prototype_id}`
+
+## Artifact
+
+- `{artifact_path}`
+
+## Review Notes
+
+- Pending local review.
+
+## Known Constraints
+
+- Prototype scope excludes production hardening unless explicitly listed in
+  `TODO.yaml`.
+"""
+
+
+def artifact_placeholder(args: argparse.Namespace, prototype_id: str) -> str:
+    return f"""<!doctype html>
+<html lang=\"en\">
+<head>
+  <meta charset=\"utf-8\">
+  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">
+  <title>{args.title}</title>
+  <style>
+    body {{ font-family: system-ui, sans-serif; margin: 2rem; line-height: 1.5; }}
+    main {{ max-width: 760px; }}
+    code {{ background: #f4f4f4; padding: 0.1rem 0.25rem; }}
+  </style>
+</head>
+<body>
+  <main>
+    <h1>{args.title}</h1>
+    <p><strong>Prototype id:</strong> <code>prototype:{prototype_id}</code></p>
+    <p><strong>Core question:</strong> {args.core_question}</p>
+    <p>Replace this placeholder with the smallest local artifact that can answer the validation question.</p>
+  </main>
+</body>
+</html>
+"""
+
+
+def bullet_list(items: list[str]) -> str:
+    if not items:
+        return "- None."
+    return "\n".join(f"- {item}" for item in items)
+
+
+def init_prototype(args: argparse.Namespace) -> None:
+    root = Path(args.root).expanduser().resolve()
+    prototype_id = args.prototype_id or slugify(args.title)
+    target = root / ".codex" / "prototypes" / prototype_id
+    artifact_dir = target / "artifact"
+    archive_dir = target / "archive"
+    artifact_path = f".codex/prototypes/{prototype_id}/artifact/{args.artifact_name}"
+
+    for directory in [target, artifact_dir, archive_dir]:
+        ensure_dir(directory, args.dry_run)
+    touch_gitkeep(archive_dir, args.dry_run)
+
+    write_file(target / "TODO.yaml", todo_yaml(args, prototype_id, artifact_path), args.force, args.dry_run)
+    write_file(target / "PROTOTYPE_PLAN.md", prototype_plan(args, prototype_id, artifact_path), args.force, args.dry_run)
+    write_file(target / "RESULT.md", result_doc(args, prototype_id), args.force, args.dry_run)
+    write_file(target / "EVIDENCE.md", evidence_doc(args, prototype_id, artifact_path), args.force, args.dry_run)
+    if args.artifact_type == "single_html":
+        write_file(artifact_dir / args.artifact_name, artifact_placeholder(args, prototype_id), args.force, args.dry_run)
+    else:
+        touch_gitkeep(artifact_dir, args.dry_run)
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Initialize prototype discovery artifacts.")
+    p.add_argument("--root", default=".", help="Repository root.")
+    p.add_argument("--prototype-id", default=None, help="Stable prototype slug.")
+    p.add_argument("--title", required=True, help="Prototype title.")
+    p.add_argument("--validation-contract", required=True, help="Upstream validation contract id.")
+    p.add_argument("--source-artifact", action="append", default=[], help="Source artifact path. Repeatable.")
+    p.add_argument("--core-question", required=True, help="The validation question this prototype answers.")
+    p.add_argument("--include", action="append", default=[], help="Prototype inclusion. Repeatable.")
+    p.add_argument("--exclude", action="append", default=[], help="Prototype exclusion. Repeatable.")
+    p.add_argument("--todo", action="append", default=[], help="Prototype todo. Repeatable.")
+    p.add_argument("--acceptance", action="append", default=[], help="Acceptance evidence. Repeatable.")
+    p.add_argument("--artifact-type", default="single_html", help="Artifact type, default single_html.")
+    p.add_argument("--artifact-name", default="index.html", help="Artifact filename.")
+    p.add_argument("--force", action="store_true", help="Overwrite existing artifacts.")
+    p.add_argument("--dry-run", action="store_true", help="Print writes without changing files.")
+    return p
+
+
+def main() -> int:
+    init_prototype(parser().parse_args())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/build-team/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: build-team
+description: Build or regenerate a repo-specific Agent Team workflow from the current repository goal. Use when the user invokes /ow:team CONTENT or asks Codex to create, adapt, or formalize an Agent Team with orchestrator/subagent roles, scoped responsibilities, runtime state machine, milestone/task planning, review/QA loops, git checkpoint rules, and .codex/runtime initialization or maintenance.
+---
+
+# Build Team
+
+## Purpose
+
+Create a repeatable Agent Team operating system for the current repository. Treat `CONTENT` from `/ow:team CONTENT` as the user's seed intent, then derive the team from the actual repo instead of copying a fixed roster blindly.
+
+The final team must include:
+
+- an `AGENT.md` project guide or an equivalent update to the existing guide
+- `.codex/agents/` role documents for the orchestrator and selected subagents
+- `.codex/runtime/` initialized with scopes, milestones, tasks, prompts, reviews, issues, and archive folders
+- `.codex/runtime/scopes/<scope_id>/AGENT_ROSTER.yaml` for persistent and event-driven agent lifecycle tracking
+- a state machine that binds planning, implementation, review, QA, fixes, checkpoint commits, and archiving
+
+## Required Repo Scan
+
+Before asking the user anything, inspect the repo state and infer the project goal.
+
+Run or equivalent:
+
+```bash
+pwd
+git status --short
+git branch --show-current
+git log --oneline -5
+rg --files -g '!node_modules' -g '!dist' -g '!build' -g '!coverage'
+rg -n "goal|scope|mvp|roadmap|milestone|agent|runtime|architecture|launch|todo|spec" .
+```
+
+Read the relevant files from this scan, prioritizing:
+
+- `AGENT.md`, `.codex/agents/README.md`, `.codex/runtime/**`
+- `README*`, `docs/**`, `DESIGN_SPEC/**`, `SPEC*`, `ROADMAP*`, `LAUNCH_CHECKLIST*`
+- package or framework manifests such as `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`
+- existing tests and CI files
+
+Summarize internally:
+
+- current repo goal and current delivery stage
+- source-of-truth documents
+- application roots and ownership boundaries
+- existing workflow artifacts that must be preserved
+- dirty worktree changes that must not be overwritten
+
+## Ask Exactly One Question
+
+After the repo scan, ask one question and only one question before designing the team. The question must compress all missing high-value slots into a single prompt.
+
+Use this shape:
+
+```txt
+I infer this repo is aiming at <repo_goal>. For this /ow:team run, what delivery target should the team optimize for, what counts as done for the first milestone, and are there any agent roles/tools that must be included or forbidden?
+```
+
+Parameter slots filled by the answer:
+
+- `delivery_target`
+- `first_milestone_done_criteria`
+- `required_roles`
+- `forbidden_roles_or_tools`
+- `scope_id` if the user names one
+- `validation_bar`
+
+Do not ask follow-up questions. If the answer is incomplete, state assumptions and proceed.
+
+## Design Workflow
+
+Once the scan and the single answer are complete, plan the build in dependency order.
+
+1. Define the scope.
+   - Choose a stable `scope_id`, usually `MVP`, `V1`, `MIGRATION`, or a short uppercase slug.
+   - Identify source-of-truth artifacts and non-goals.
+   - Define application roots and protected roots.
+
+2. Select the team.
+   - Always include `orchestrator`.
+   - Include implementation agents only for real repo domains, such as frontend, backend, content-schema, data, infra, docs, or testing.
+   - Include `tech-prompt-agent` when tasks need formal prompts before implementation.
+   - Include `tdd-qa-agent` for executable checks and milestone QA.
+   - Include `code-review-agent` for async artifact review.
+   - Include `security-review-agent` only when the repo handles secrets, auth, deployment, external input, APIs, dependencies, or infrastructure.
+   - Include `git-release-agent` when milestone branches, commits, PRs, or releases are part of the workflow.
+
+3. Define role boundaries.
+   - Orchestrator owns runtime state, task transitions, integration, and git checkpoint decisions.
+   - Orchestrator uses delegation-first execution: it must assign or resume an eligible subagent before doing implementation, docs, QA, review, or prompt-writing work directly.
+   - Direct Orchestrator execution requires an `orchestrator_exception` note in the task state.
+   - Implementation agents edit only their `owned_paths` and never commit.
+   - Review and security agents write review artifacts and issue logs; they do not edit implementation files.
+   - QA agents may write tests and QA reports; they do not commit.
+   - Git release agents draft branch, commit, PR, and release text; final git actions remain with the Orchestrator unless the user explicitly changes that boundary.
+
+4. Define agent session topology.
+   - Persistent agents stay mounted across related atom tasks and issue-fix loops.
+   - Use persistent agents for planning and recurring implementation domains such as frontend, backend, content/schema, data, docs, or infra.
+   - Event-driven agents run asynchronously or one-off, then close after handoff.
+   - Use event-driven agents for code review, security review, milestone QA, git release drafting, and narrow investigations.
+   - Require the Orchestrator to capture every returned `agent_id` after spawn or resume and write it to `AGENT_ROSTER.yaml` and the task entry.
+   - Do not leave `agent_id: null` after assignment. Use `legacy_untracked` only for historical tasks that predate roster tracking.
+
+5. Define milestones.
+   - Convert the repo goal into dependency-ordered milestones.
+   - Keep contracts before broad implementation.
+   - Each milestone needs source artifacts, expected artifacts, dependencies, QA gate, acceptance criteria, and estimated atom task range.
+
+6. Define atom task schema.
+   - Make tasks small enough for one agent and one ownership boundary.
+   - Require `agent_session_policy`, `agent_id`, `preferred_agent_id`, `assigned_at`, `resumed_from_agent_id`, `handoff_required`, `orchestrator_exception`, `status`, `artifact_status`, `review_status`, `qa_status`, `is_output_done`, dependencies, `owned_paths`, `allowed_paths`, checks, and prompt path.
+   - Do not treat file existence as completion.
+
+7. Initialize or reconcile `.codex/runtime/`.
+   - Use `scripts/init_team_runtime.py` for the base directory and YAML skeleton when possible.
+   - Preserve existing runtime files unless the user explicitly asks to regenerate.
+   - Add missing archive folders even when runtime state already exists.
+
+8. Write or update coordination artifacts.
+   - `AGENT.md`
+   - `.codex/agents/README.md`
+   - `.codex/agents/<role>.md`
+   - `.codex/runtime/**`
+
+9. Validate.
+   - Ensure all YAML is parseable or structurally consistent.
+   - Ensure every referenced prompt/review/task path has a parent directory.
+   - Ensure role docs declare `can_modify_code`, `can_commit`, `owns`, `forbidden_paths`, inputs, and outputs.
+   - Ensure every newly assigned task has a non-null `agent_id`.
+   - Check `git status --short` and report created or changed files.
+
+## Runtime Initialization
+
+The runtime root must be:
+
+```txt
+.codex/runtime/
+```
+
+Required hierarchy:
+
+```txt
+.codex/runtime/
+  RUNTIME_INDEX.yaml
+  STATE_MACHINE.md
+  archive/
+  scopes/
+    <scope_id>/
+      SCOPE.yaml
+      MILESTONES.yaml
+      IMPLEMENT_INDEX.yaml
+      IMPLEMENT_ISSUE_INDEX.yaml
+      AGENT_ROSTER.yaml
+      archive/
+      milestones/
+        <milestone_id>/
+          IMPLEMENT_TASKS.yaml
+          IMPLEMENT_ISSUES.yaml
+          prompts/
+          reviews/
+          archive/
+```
+
+Use `archive/` for superseded plans, stale prompts, obsolete reviews, replaced QA evidence, and frozen milestone snapshots. Do not delete historical coordination artifacts unless the user explicitly requests cleanup.
+
+Run the helper from the repo root, adapting arguments to the planned scope:
+
+```bash
+python3 .codex/skills/build-team/scripts/init_team_runtime.py \
+  --scope-id MVP \
+  --scope-title "MVP implementation" \
+  --source-artifact AGENT.md \
+  --milestone "M01:Repo initialization"
+```
+
+If this skill is installed outside the repo, run the script from the skill folder path instead.
+
+## Agent Session Topology
+
+Persistent agents:
+
+- Use for recurring planning and implementation work.
+- Keep mounted while the milestone or related issue-fix loop is active.
+- Resume the same `agent_id` for related atom tasks before spawning a replacement.
+- Send review-discovered fix tasks back to the original persistent implementation agent when ownership still matches.
+
+Event-driven agents:
+
+- Use for async code review, security review, milestone QA, git release drafting, and one-off investigations.
+- Allow event-driven review to run against an earlier milestone while persistent implementation agents continue later work, as long as ownership is disjoint.
+- Close event-driven agents after handoff unless the Orchestrator records a reason to keep them idle.
+
+The Orchestrator must immediately write every returned subagent `agent_id` to both:
+
+```txt
+.codex/runtime/scopes/<scope_id>/AGENT_ROSTER.yaml
+.codex/runtime/scopes/<scope_id>/milestones/<milestone_id>/IMPLEMENT_TASKS.yaml
+```
+
+New assigned work must not keep `agent_id: null`.
+
+## State Machine
+
+Use this operating flow:
+
+```txt
+repo_scan
+  -> user_parameter_question
+  -> scope_design
+  -> runtime_bootstrap
+  -> milestone_plan
+  -> atom_task_plan
+  -> agent_session_topology
+  -> prompt_preparation
+  -> spawn_or_resume_agent
+  -> record_agent_id
+  -> implementation_or_event_work
+  -> artifact_ready
+  -> async_review
+  -> issue_fix_loop
+  -> resume_original_persistent_agent_for_fix
+  -> milestone_qa
+  -> git_checkpoint_decision
+  -> archive_or_freeze
+  -> next_milestone
+```
+
+Allowed task `status` values:
+
+```txt
+planned
+prompted
+claimed
+in_progress
+artifact_ready
+review_pending
+reviewed
+fix_required
+qa_ready
+done
+blocked
+archived
+```
+
+Allowed `artifact_status` values:
+
+```txt
+missing
+created
+validated
+archived
+```
+
+Allowed `review_status` values:
+
+```txt
+none
+pending
+passed
+issues_found
+waived
+```
+
+Allowed `qa_status` values:
+
+```txt
+not_run
+passed
+failed
+waived
+```
+
+Allowed milestone `status` values:
+
+```txt
+planned
+active
+qa
+completed
+frozen
+blocked
+deferred
+archived
+```
+
+## References
+
+Load `references/team-protocol.md` before writing `AGENT.md` or `.codex/agents/*.md`.
+
+Load `references/runtime-schema.md` before writing or reconciling `.codex/runtime/**`.