@tiic-tech/openworkflow 0.1.0

package/skills/build-workflow/scripts/init_workflow.py

@@ -0,0 +1,423 @@
+#!/usr/bin/env python3
+"""Initialize OpenWorkflow upstream contract infrastructure.
+
+The script creates missing repo-local contract folders and seed files. It is
+conservative by default: existing files are not overwritten unless --force is
+provided.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+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:
+    slug = re.sub(r"[^A-Za-z0-9]+", "-", value.strip().lower()).strip("-")
+    return slug or "project"
+
+
+def git_ref(root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=root,
+            check=True,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return None
+    return result.stdout.strip() or None
+
+
+def detect_sources(root: Path) -> list[str]:
+    candidates = [
+        "AGENT.md",
+        "README.md",
+        "README",
+        "build_system_vision.md",
+        "ROADMAP.md",
+        "SPEC.md",
+    ]
+    sources = [candidate for candidate in candidates if (root / candidate).exists()]
+    if (root / "docs").is_dir():
+        sources.append("docs/")
+    return sources or ["AGENT.md"]
+
+
+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 workflow_index(project_slug: str, project_title: str, sources: list[str], ref: str | None) -> str:
+    contract_id = f"workflow:{project_slug}"
+    return (
+        "schema_version: 0.1.0\n"
+        f"contract_id: {contract_id}\n"
+        "contract_type: workflow\n"
+        f"title: {q(project_title + ' workflow index')}\n"
+        "status: active\n"
+        "workflow_root: .codex\n"
+        "active_change: null\n"
+        "source_artifacts:\n"
+        f"{yaml_list(sources, 2)}"
+        f"base_git_ref: {q(ref)}\n"
+        "contracts:\n"
+        f"  - contract_id: {contract_id}\n"
+        "    contract_type: workflow\n"
+        "    path: .codex/workflow/WORKFLOW_INDEX.yaml\n"
+        "    status: active\n"
+        "  - contract_id: workflow:contract-graph\n"
+        "    contract_type: workflow\n"
+        "    path: .codex/workflow/CONTRACT_GRAPH.yaml\n"
+        "    status: active\n"
+        "  - contract_id: context:default\n"
+        "    contract_type: context\n"
+        "    path: .codex/context/CONTEXT_MAP.yaml\n"
+        "    status: draft\n"
+        "  - contract_id: vision:default\n"
+        "    contract_type: vision\n"
+        "    path: .codex/vision/VISION_CONTRACT.yaml\n"
+        "    status: draft\n"
+        "  - contract_id: decision:index\n"
+        "    contract_type: decision\n"
+        "    path: .codex/decisions/DECISION_INDEX.yaml\n"
+        "    status: active\n"
+        "  - contract_id: spec:index\n"
+        "    contract_type: spec\n"
+        "    path: .codex/spec/SPEC_INDEX.yaml\n"
+        "    status: active\n"
+        "  - contract_id: validation:index\n"
+        "    contract_type: validation\n"
+        "    path: .codex/validation/VALIDATION_INDEX.yaml\n"
+        "    status: active\n"
+        "  - contract_id: prototype:index\n"
+        "    contract_type: prototype\n"
+        "    path: .codex/prototypes/PROTOTYPE_INDEX.yaml\n"
+        "    status: active\n"
+    )
+
+
+def contract_graph(project_slug: str) -> str:
+    workflow_id = f"workflow:{project_slug}"
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: workflow:contract-graph\n"
+        "contract_type: workflow\n"
+        "title: OpenWorkflow contract graph\n"
+        "status: active\n"
+        "nodes:\n"
+        f"  - contract_id: {workflow_id}\n"
+        "    contract_type: workflow\n"
+        "    path: .codex/workflow/WORKFLOW_INDEX.yaml\n"
+        "  - contract_id: context:default\n"
+        "    contract_type: context\n"
+        "    path: .codex/context/CONTEXT_MAP.yaml\n"
+        "  - contract_id: vision:default\n"
+        "    contract_type: vision\n"
+        "    path: .codex/vision/VISION_CONTRACT.yaml\n"
+        "  - contract_id: decision:index\n"
+        "    contract_type: decision\n"
+        "    path: .codex/decisions/DECISION_INDEX.yaml\n"
+        "  - contract_id: spec:index\n"
+        "    contract_type: spec\n"
+        "    path: .codex/spec/SPEC_INDEX.yaml\n"
+        "  - contract_id: validation:index\n"
+        "    contract_type: validation\n"
+        "    path: .codex/validation/VALIDATION_INDEX.yaml\n"
+        "  - contract_id: prototype:index\n"
+        "    contract_type: prototype\n"
+        "    path: .codex/prototypes/PROTOTYPE_INDEX.yaml\n"
+        "edges:\n"
+        f"  - from: {workflow_id}\n"
+        "    to: context:default\n"
+        "    relation: initializes\n"
+        "  - from: context:default\n"
+        "    to: vision:default\n"
+        "    relation: informs\n"
+        "  - from: vision:default\n"
+        "    to: decision:index\n"
+        "    relation: constrains\n"
+        "  - from: decision:index\n"
+        "    to: spec:index\n"
+        "    relation: constrains\n"
+        "  - from: spec:index\n"
+        "    to: validation:index\n"
+        "    relation: scopes\n"
+        "  - from: validation:index\n"
+        "    to: prototype:index\n"
+        "    relation: prototypes\n"
+    )
+
+
+def context_map(project_title: str, sources: list[str]) -> str:
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: context:default\n"
+        "contract_type: context\n"
+        f"title: {q(project_title + ' shared context')}\n"
+        "status: draft\n"
+        "source_artifacts:\n"
+        f"{yaml_list(sources, 2)}"
+        "glossary: .codex/context/GLOSSARY.yaml\n"
+        "repo_map: []\n"
+        "source_references: []\n"
+        "depends_on:\n"
+        "  - workflow:contract-graph\n"
+        "produces:\n"
+        "  - vision:default\n"
+        "updated_at: null\n"
+    )
+
+
+def glossary(project_title: str) -> str:
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: context:glossary\n"
+        "contract_type: context\n"
+        f"title: {q(project_title + ' glossary')}\n"
+        "status: draft\n"
+        "terms: []\n"
+        "updated_at: null\n"
+    )
+
+
+def vision_contract(project_title: str) -> str:
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: vision:default\n"
+        "contract_type: vision\n"
+        f"title: {q(project_title + ' vision')}\n"
+        "status: draft\n"
+        "depends_on:\n"
+        "  - context:default\n"
+        "produces:\n"
+        "  - decision:index\n"
+        "goals: []\n"
+        "non_goals: []\n"
+        "users: []\n"
+        "quality_bar: []\n"
+        "decision_priorities: []\n"
+        "updated_at: null\n"
+    )
+
+
+def decision_index(project_title: str) -> str:
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: decision:index\n"
+        "contract_type: decision\n"
+        f"title: {q(project_title + ' decision index')}\n"
+        "status: active\n"
+        "depends_on:\n"
+        "  - vision:default\n"
+        "produces:\n"
+        "  - spec:index\n"
+        "decisions: []\n"
+        "updated_at: null\n"
+    )
+
+
+def spec_index(project_title: str) -> str:
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: spec:index\n"
+        "contract_type: spec\n"
+        f"title: {q(project_title + ' spec index')}\n"
+        "status: active\n"
+        "depends_on:\n"
+        "  - decision:index\n"
+        "produces: []\n"
+        "specs: []\n"
+        "updated_at: null\n"
+    )
+
+
+def validation_index(project_title: str) -> str:
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: validation:index\n"
+        "contract_type: validation\n"
+        f"title: {q(project_title + ' validation index')}\n"
+        "status: active\n"
+        "depends_on:\n"
+        "  - spec:index\n"
+        "produces: []\n"
+        "validations: []\n"
+        "updated_at: null\n"
+    )
+
+
+def prototype_index(project_title: str) -> str:
+    return (
+        "schema_version: 0.1.0\n"
+        "contract_id: prototype:index\n"
+        "contract_type: prototype\n"
+        f"title: {q(project_title + ' prototype index')}\n"
+        "status: active\n"
+        "depends_on:\n"
+        "  - validation:index\n"
+        "produces: []\n"
+        "prototypes: []\n"
+        "updated_at: null\n"
+    )
+
+
+def context_doc(project_title: str) -> str:
+    return (
+        f"# {project_title} Context\n\n"
+        "This file is the human-readable project context surface. Keep durable\n"
+        "indexes and machine-readable references in `CONTEXT_MAP.yaml` and\n"
+        "`GLOSSARY.yaml`.\n"
+    )
+
+
+def vision_doc(project_title: str) -> str:
+    return (
+        f"# {project_title} Vision\n\n"
+        "This file is the human-readable project direction. Keep machine-readable\n"
+        "goals, non-goals, users, quality bars, and priorities in\n"
+        "`VISION_CONTRACT.yaml`.\n"
+    )
+
+
+def init_workflow(args: argparse.Namespace) -> None:
+    root = Path(args.root).expanduser().resolve()
+    project_title = args.project_title or root.name
+    project_slug = slugify(args.project_slug or project_title)
+    sources = args.source_artifact or detect_sources(root)
+    ref = git_ref(root)
+
+    codex = root / ".codex"
+    dirs = [
+        codex / "workflow",
+        codex / "workflow" / "archive",
+        codex / "context",
+        codex / "context" / "archive",
+        codex / "vision",
+        codex / "vision" / "archive",
+        codex / "decisions",
+        codex / "decisions" / "archive",
+        codex / "spec",
+        codex / "spec" / "archive",
+        codex / "validation",
+        codex / "validation" / "archive",
+        codex / "prototypes",
+        codex / "prototypes" / "archive",
+        codex / "changes",
+        codex / "changes" / "archive",
+    ]
+    for directory in dirs:
+        ensure_dir(directory, args.dry_run)
+    for directory in dirs:
+        if directory.name == "archive":
+            touch_gitkeep(directory, args.dry_run)
+
+    write_file(
+        codex / "workflow" / "WORKFLOW_INDEX.yaml",
+        workflow_index(project_slug, project_title, sources, ref),
+        args.force,
+        args.dry_run,
+    )
+    write_file(
+        codex / "workflow" / "CONTRACT_GRAPH.yaml",
+        contract_graph(project_slug),
+        args.force,
+        args.dry_run,
+    )
+    write_file(codex / "context" / "CONTEXT.md", context_doc(project_title), args.force, args.dry_run)
+    write_file(
+        codex / "context" / "CONTEXT_MAP.yaml",
+        context_map(project_title, sources),
+        args.force,
+        args.dry_run,
+    )
+    write_file(codex / "context" / "GLOSSARY.yaml", glossary(project_title), args.force, args.dry_run)
+    write_file(codex / "vision" / "VISION.md", vision_doc(project_title), args.force, args.dry_run)
+    write_file(
+        codex / "vision" / "VISION_CONTRACT.yaml",
+        vision_contract(project_title),
+        args.force,
+        args.dry_run,
+    )
+    write_file(
+        codex / "decisions" / "DECISION_INDEX.yaml",
+        decision_index(project_title),
+        args.force,
+        args.dry_run,
+    )
+    write_file(codex / "spec" / "SPEC_INDEX.yaml", spec_index(project_title), args.force, args.dry_run)
+    write_file(
+        codex / "validation" / "VALIDATION_INDEX.yaml",
+        validation_index(project_title),
+        args.force,
+        args.dry_run,
+    )
+    write_file(
+        codex / "prototypes" / "PROTOTYPE_INDEX.yaml",
+        prototype_index(project_title),
+        args.force,
+        args.dry_run,
+    )
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Initialize OpenWorkflow contract infrastructure.")
+    p.add_argument("--root", default=".", help="Repository root. Defaults to current directory.")
+    p.add_argument("--project-title", default=None, help="Human-readable project title.")
+    p.add_argument("--project-slug", default=None, help="Stable contract slug. Defaults to project title.")
+    p.add_argument("--source-artifact", action="append", default=[], help="Source artifact path. Repeatable.")
+    p.add_argument("--force", action="store_true", help="Overwrite existing files.")
+    p.add_argument("--dry-run", action="store_true", help="Print writes without changing files.")
+    return p
+
+
+def main() -> int:
+    init_workflow(parser().parse_args())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/run-team/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: run-team
+description: Start and drive formal Agent Team development from the current repository state. Use when the user invokes /ow:team CONTENT or asks Codex to continue a governed multi-agent workflow, choose the next scope after MVP or another completed phase, inspect runtime/archive/git state, initialize or reconcile scope runtime, plan milestones and atom tasks, spawn or resume persistent agents, record agent_id values, and execute development through review, QA, issue-fix, and git checkpoint loops.
+---
+
+# Run Team
+
+## Purpose
+
+Use this skill as the execution entrypoint for an existing Agent Team. `/ow:team` is the user-facing entrypoint for both team creation and execution modes. This repo-local skill reads the current repo, runtime state, and user `CONTENT`, then drives the team through planning and actual development.
+
+## Start Protocol
+
+On `/ow:team CONTENT`, do not start coding immediately.
+
+1. Audit the current state.
+   - Run `scripts/audit_team_runtime.py --root . --format markdown`.
+   - Inspect `git status --short`, current branch, and recent commits.
+   - Read `AGENT.md`, `.codex/agents/README.md`, `.codex/agents/orchestrator.md`.
+   - Read `.codex/runtime/STATE_MACHINE.md`, `RUNTIME_INDEX.yaml`, active scope `SCOPE.yaml`, `IMPLEMENT_INDEX.yaml`, `IMPLEMENT_ISSUE_INDEX.yaml`, and `AGENT_ROSTER.yaml`.
+   - Inspect active milestone task/issue files and any relevant `archive/` entries.
+
+2. Load relevant context.
+   - Always load `references/run-loop.md` and `references/runtime-audit.md`.
+   - Load `references/scope-selection.md` when deciding whether to continue the current scope or create a new one.
+   - Load `references/delegation-and-agent-lifecycle.md` before spawning, resuming, or assigning agents.
+   - Load repo source-of-truth docs only when relevant to `CONTENT`.
+
+3. Decide the run mode.
+   - `continue_scope`: continue active scope/milestone.
+   - `new_scope`: create a post-MVP, V1, migration, launch, hardening, or feature scope.
+   - `issue_fix`: convert unresolved issues into fix tasks.
+   - `release_or_checkpoint`: prepare QA/checkpoint/release work.
+   - `runtime_reconcile`: fix stale runtime before development.
+
+4. Ask at most one question.
+   - Ask only if the delivery target or acceptance bar cannot be inferred from `CONTENT` and repo state.
+   - The question must combine target, done criteria, and constraints in one prompt.
+   - If the answer is incomplete, state assumptions and proceed.
+
+5. Plan dependency order.
+   - Define or confirm scope id and goal.
+   - Draft milestones with target, dependencies, expected artifacts, QA gate, and acceptance criteria.
+   - Convert the first milestone into atom tasks.
+   - Write prompts before implementation tasks.
+
+6. Initialize or reconcile runtime.
+   - For new scopes, run `scripts/init_next_scope.py`.
+   - For existing scopes, update only stale or missing runtime files.
+   - Preserve archive history; do not delete old runtime artifacts.
+
+7. Execute through the Agent Team.
+   - Orchestrator must not directly implement product code, docs, QA, review, or prompt-writing work when an eligible subagent can own it.
+   - Spawn or resume the correct persistent/event-driven agent.
+   - Immediately record the returned `agent_id` in `AGENT_ROSTER.yaml` and the task entry.
+   - Keep persistent implementation agents mounted across related atom tasks and issue-fix loops.
+   - Use event-driven review, security, QA, and git-release agents asynchronously where ownership is disjoint.
+
+8. Checkpoint.
+   - Update runtime state after every real state transition.
+   - Run required checks.
+   - Commit coherent runtime/implementation/QA slices, or record why a checkpoint is deferred.
+
+## Runtime Rules
+
+New delegated work must not leave `agent_id: null`.
+
+Use `legacy_untracked` only for historical tasks that predate roster tracking. Do not invent ids.
+
+Direct Orchestrator execution requires `orchestrator_exception`.
+
+If unresolved issues exist in an earlier milestone, record them in that milestone's issue file, then route fix tasks back to the original persistent implementation agent when possible.
+
+## Script Quick Start
+
+Audit:
+
+```bash
+python3 .codex/skills/run-team/scripts/audit_team_runtime.py --root . --format markdown
+```
+
+Create a new scope skeleton:
+
+```bash
+python3 .codex/skills/run-team/scripts/init_next_scope.py \
+  --root . \
+  --scope-id V1 \
+  --scope-title "V1 iteration" \
+  --source-artifact AGENT.md \
+  --milestone "M01:Post-MVP planning"
+```
+
+If this skill is installed globally, run the scripts from that global skill path instead.

package/skills/run-team/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Run Team"
+  short_description: "Start formal Agent Team development"
+  default_prompt: "Use /ow:team to start formal Agent Team development for the next repository goal."

package/skills/run-team/references/delegation-and-agent-lifecycle.md

@@ -0,0 +1,78 @@
+# Delegation And Agent Lifecycle
+
+Use this reference before assigning work.
+
+## Orchestrator Boundary
+
+The Orchestrator owns:
+
+- scope and milestone selection
+- runtime state
+- atom task decomposition
+- prompt assignment
+- agent lifecycle
+- integration
+- checkpoint decisions
+
+The Orchestrator must not directly perform implementation, docs, QA, review, or prompt-writing work when an eligible subagent can own it.
+
+Direct execution requires:
+
+```yaml
+orchestrator_exception: "<reason>"
+```
+
+## Persistent Agents
+
+Use persistent agents for recurring work:
+
+- `tech-prompt-agent`
+- `frontend-agent`
+- `backend-agent`
+- `content-schema-agent`
+- `data-agent`
+- `infra-agent`
+- `docs-agent`
+
+Before spawning a persistent agent, check `AGENT_ROSTER.yaml` for an existing idle or active matching role. Resume it when possible.
+
+After spawn or resume:
+
+- record returned `agent_id` in `AGENT_ROSTER.yaml`
+- record the same `agent_id` in `IMPLEMENT_TASKS.yaml`
+- set lifecycle state to `active`
+- set `current_task`
+
+When the handoff is complete:
+
+- set lifecycle state to `idle` unless blocked or closed
+- set `last_completed_task`
+- clear or update `current_task`
+
+## Event-Driven Agents
+
+Use event-driven agents for:
+
+- `code-review-agent`
+- `security-review-agent`
+- `tdd-qa-agent` unless running a long test authoring stream
+- `git-release-agent`
+
+Event agents may run asynchronously when ownership is disjoint. Close after handoff unless there is a recorded reason to keep them idle.
+
+## Issue Fix Return
+
+When review finds issues:
+
+1. Record issues in the reviewed milestone's `IMPLEMENT_ISSUES.yaml`.
+2. Convert required issues into fix tasks.
+3. Prefer the original persistent implementation `agent_id`.
+4. Spawn a replacement only when the original agent is closed, unavailable, or no longer owns the paths.
+
+## Forbidden States
+
+- new assigned work with `agent_id: null`
+- invented ids for historical work
+- review agents editing implementation files
+- implementation agents committing
+- two agents writing the same path ownership without a merge plan

package/skills/run-team/references/run-loop.md

@@ -0,0 +1,73 @@
+# Run Loop
+
+Use this reference to drive `/ow:team CONTENT` from inspection into execution.
+
+## Execution Flow
+
+```txt
+content_intake
+  -> repo_and_runtime_audit
+  -> source_truth_loading
+  -> run_mode_decision
+  -> scope_or_milestone_plan
+  -> runtime_init_or_reconcile
+  -> atom_task_plan
+  -> prompt_preparation
+  -> spawn_or_resume_agent
+  -> record_agent_id
+  -> delegated_work
+  -> handoff
+  -> review_or_qa
+  -> issue_fix_loop
+  -> checkpoint
+```
+
+## Operating Rules
+
+- Treat `CONTENT` as the seed target, not as a complete plan.
+- Infer from runtime first, then source-of-truth docs, then code state.
+- Do not skip `git status --short`; dirty unrelated files affect checkpoint boundaries.
+- Do not start implementation until the active scope, milestone, task, ownership, and agent session policy are known.
+- Do not let the Orchestrator become the default implementer.
+- Prefer persistent implementation agents for repeated work in the same domain.
+- Use event-driven agents for review, security, QA, release notes, and narrow investigations.
+- Keep `.codex/runtime/` synchronized with reality before moving to unrelated work.
+
+## Run Modes
+
+`continue_scope`:
+
+- Active scope exists.
+- Active milestone has planned, prompted, in-progress, blocked, or fix-required tasks.
+- Continue by reconciling stale state, then assigning the next unblocked task.
+
+`new_scope`:
+
+- Existing scope is complete, frozen, deferred, or no longer matches `CONTENT`.
+- Create a new scope such as `V1`, `POST_MVP`, `LAUNCH`, `CONTENT`, `MIGRATION`, or a short uppercase slug.
+- Initialize runtime before atom tasks.
+
+`issue_fix`:
+
+- Unresolved issues exist and match `CONTENT`.
+- Convert issues into fix tasks and route to the original persistent implementation agent when possible.
+
+`release_or_checkpoint`:
+
+- Work is complete enough for QA, commit, PR, deploy, or release notes.
+- Assign QA/release agents as event-driven work.
+
+`runtime_reconcile`:
+
+- Runtime files are stale, missing, contradictory, or not parseable.
+- Fix runtime before development.
+
+## End State
+
+A successful run should leave:
+
+- updated runtime state
+- agent ids recorded for new delegated work
+- clear task/milestone status
+- review or QA artifacts when relevant
+- a commit decision for coherent slices