@tiic-tech/openworkflow 0.1.0

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build Team"
+  short_description: "Create a repo-specific Agent Team workflow"
+  default_prompt: "Use /ow:team to create an Agent Team workflow for this repository."

package/skills/build-team/references/runtime-schema.md

@@ -0,0 +1,275 @@
+# Runtime Schema Reference
+
+Use this reference when creating or reconciling `.codex/runtime/**`.
+
+## Directory Layout
+
+Required layout:
+
+```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 `.gitkeep` files in empty `archive/`, `prompts/`, and `reviews/` folders.
+
+## RUNTIME_INDEX.yaml
+
+```yaml
+active_scope: MVP
+scopes:
+  - scope_id: MVP
+    title: MVP implementation
+    status: active
+    source: AGENT.md
+    path: .codex/runtime/scopes/MVP/
+    base_git_ref: null
+```
+
+## SCOPE.yaml
+
+```yaml
+scope_id: MVP
+title: MVP implementation
+status: active
+source_artifacts:
+  - AGENT.md
+base_git_ref: null
+runtime_protocol:
+  agent_team_protocol: .codex/agents/README.md
+  orchestrator_role: .codex/agents/orchestrator.md
+  agent_roster: .codex/runtime/scopes/MVP/AGENT_ROSTER.yaml
+boundary:
+  application_roots: []
+  protected_roots:
+    - .git/
+    - .codex/runtime/
+```
+
+## MILESTONES.yaml
+
+```yaml
+scope_id: MVP
+source_artifacts:
+  - AGENT.md
+milestones:
+  - milestone_id: M01
+    title: Repo initialization
+    status: planned
+    scope: Initialize the repo and workflow contracts.
+    target: A runnable baseline with clear ownership and checks.
+    dependencies: []
+    required_specs:
+      - AGENT.md
+    expected_artifacts: []
+    estimated_atom_tasks: 3-6
+    task_file: .codex/runtime/scopes/MVP/milestones/M01/IMPLEMENT_TASKS.yaml
+    issue_file: .codex/runtime/scopes/MVP/milestones/M01/IMPLEMENT_ISSUES.yaml
+    qa_gate:
+      - baseline checks pass
+    acceptance:
+      - runtime state is current
+```
+
+## IMPLEMENT_INDEX.yaml
+
+```yaml
+scope_id: MVP
+active_milestone: M01
+milestones:
+  - milestone_id: M01
+    status: active
+    title: Repo initialization
+    task_file: .codex/runtime/scopes/MVP/milestones/M01/IMPLEMENT_TASKS.yaml
+    issue_file: .codex/runtime/scopes/MVP/milestones/M01/IMPLEMENT_ISSUES.yaml
+    qa_report: null
+    branch: feat/m01-repo-initialization
+    last_checkpoint: null
+```
+
+## IMPLEMENT_TASKS.yaml
+
+Each milestone has one task file:
+
+```yaml
+tasks:
+  - task_id: M01-T001
+    milestone_id: M01
+    task_name: Initialize workflow baseline
+    task_type: implementation
+    status: planned
+    agent_name: orchestrator
+    agent_id: null
+    agent_session_policy: persistent
+    preferred_agent_id: null
+    assigned_at: null
+    resumed_from_agent_id: null
+    handoff_required: true
+    orchestrator_exception: null
+    required_artifacts:
+      - AGENT.md
+    required_tasks: []
+    implement_prompt_path: .codex/runtime/scopes/MVP/milestones/M01/prompts/M01-T001.md
+    expected_output_artifact: Workflow baseline
+    output_artifact_path: []
+    owned_paths:
+      - .codex/runtime/
+    allowed_paths:
+      - .codex/runtime/
+    forbidden_paths:
+      - .git/
+    checks_required: []
+    artifact_status: missing
+    review_status: none
+    qa_status: not_run
+    is_output_done: false
+    notes: ""
+```
+
+After assignment, `agent_id` must be a real returned agent id. Use `legacy_untracked` only for historical tasks that predate roster tracking.
+
+## AGENT_ROSTER.yaml
+
+Each scope owns one agent lifecycle file:
+
+```yaml
+scope_id: MVP
+roster_version: 1
+updated_at: null
+lifecycle_status_values:
+  - available
+  - active
+  - idle
+  - blocked
+  - closed
+  - archived
+  - legacy_untracked
+session_policies:
+  persistent:
+    purpose: Keep domain agents mounted across related atom tasks and issue-fix loops.
+    reuse_rule: Resume the existing matching agent_id before spawning a replacement.
+  event:
+    purpose: Run async or one-off review, security, QA, and git drafting work.
+    reuse_rule: Close after handoff unless the Orchestrator records a reason to keep it idle.
+persistent_agents:
+  - agent_name: frontend-agent
+    agent_id: null
+    lifecycle_status: available
+    session_policy: persistent
+    owns:
+      - frontend/src/app/
+      - frontend/src/components/
+    current_task: null
+    last_completed_task: null
+    active_milestone: null
+    notes: Spawn once for frontend work, then resume for related tasks and fixes.
+event_agents:
+  - agent_name: code-review-agent
+    agent_id: null
+    lifecycle_status: available
+    session_policy: event
+    trigger: artifact_ready
+    closes_after_handoff: true
+    notes: Writes review artifacts and issue logs, then closes.
+legacy_tracking:
+  task_agent_ids_before_roster: legacy_untracked
+  note: Do not invent ids for historical null task agent_id values.
+```
+
+## IMPLEMENT_ISSUES.yaml
+
+Milestone-local issue file:
+
+```yaml
+issues:
+  - id: M01-I001
+    task: M01-T001
+    severity: major
+    status: open
+    owner: frontend-agent
+    loc: path/to/file.ts:42
+    title: Short issue title
+    expected: Expected behavior.
+    fix_task: null
+    review: .codex/runtime/scopes/MVP/milestones/M01/reviews/M01-T001-review.md
+```
+
+Scope-level issue index:
+
+```yaml
+scope_id: MVP
+issues: []
+```
+
+Use the scope-level index only for cross-milestone issues, deferred risks, reopened regressions, and architecture-level concerns.
+
+## Status Values
+
+Task `status`:
+
+```txt
+planned, prompted, claimed, in_progress, artifact_ready, review_pending, reviewed, fix_required, qa_ready, done, blocked, archived
+```
+
+`artifact_status`:
+
+```txt
+missing, created, validated, archived
+```
+
+`review_status`:
+
+```txt
+none, pending, passed, issues_found, waived
+```
+
+`qa_status`:
+
+```txt
+not_run, passed, failed, waived
+```
+
+Milestone `status`:
+
+```txt
+planned, active, qa, completed, frozen, blocked, deferred, archived
+```
+
+Issue `status`:
+
+```txt
+open, fixed, waived, deferred, reopened, archived
+```
+
+Issue `severity`:
+
+```txt
+blocker, critical, major, minor, nit
+```
+
+## Maintenance Rules
+
+- Update runtime state when task reality changes, not at the end of a session.
+- Update `AGENT_ROSTER.yaml` when agent lifecycle changes.
+- New delegated tasks must not leave `agent_id: null`.
+- Keep YAML compact; put detailed reasoning in `prompts/` and `reviews/`.
+- Archive superseded coordination artifacts instead of deleting them.
+- Freeze completed milestone directories after QA and checkpoint decisions.
+- Do not allow implementation agents to update global runtime indexes unless the Orchestrator assigns an explicit state task.

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

@@ -0,0 +1,244 @@
+# Agent Team Protocol Reference
+
+Use this reference when creating `AGENT.md` and `.codex/agents/*.md`.
+
+## Operating Priorities
+
+P0 Orchestrator focus and delegation boundary:
+
+- decompose work into atom tasks and assign or resume eligible subagents before direct execution
+- reserve Orchestrator context for scope, dependency, runtime state, lifecycle, integration, and checkpoint decisions
+- directly edit only runtime state, assignment prompts, coordination protocol, checkpoint metadata, and minimal integration glue unless an exception applies
+- record `orchestrator_exception` when the Orchestrator directly performs implementation, docs, QA, review, or prompt-writing work that a subagent could have owned
+- prefer resuming the persistent agent that owns the relevant domain before spawning a replacement
+
+Allowed direct-work exceptions:
+
+- no suitable role exists and creating one would be larger than the task
+- an integration conflict requires a small Orchestrator-owned merge adjustment
+- the user explicitly asks the Orchestrator to perform the work directly
+- an urgent blocker prevents safe delegation
+
+P1 Git workflow integrity:
+
+- inspect `git status --short`, current branch, and recent commits before formal work
+- define the intended checkpoint boundary before edits
+- keep unrelated user changes out of commits
+- include runtime state changes in the same checkpoint when task reality changed
+- record skipped checks in task notes and commit bodies
+- let only the Orchestrator commit unless the user explicitly changes the rule
+
+P2 Work state machine and agent lifecycle tracking:
+
+- identify active scope, milestone, task, dependencies, and ownership before edits
+- identify `agent_session_policy`, selected agent role, and expected lifecycle before delegation
+- capture the returned `agent_id` after every spawn or resume operation
+- write that `agent_id` to both `AGENT_ROSTER.yaml` and the task entry before delegated work proceeds
+- update `.codex/runtime/` when task ownership, output, review, QA, blocker, or checkpoint state changes
+- update `.codex/runtime/scopes/<scope_id>/AGENT_ROSTER.yaml` when an agent is spawned, resumed, active, idle, blocked, closed, or archived
+- reconcile stale runtime state before starting unrelated work
+- never infer completion from file existence alone
+- never leave `agent_id: null` after assignment; use `legacy_untracked` only for historical tasks that predate roster tracking
+
+P3 Source truth, QA, and domain fidelity:
+
+- source-of-truth specs govern implementation order and scope
+- TDD or executable checks are required for code work whenever practical
+- review, QA, accessibility, security, and content discipline run inside P0/P1/P2
+
+## Required Agent Frontmatter
+
+Each `.codex/agents/<role>.md` file should start with:
+
+```yaml
+---
+name: kebab-case-agent-name
+description: One-sentence role summary.
+agent_type: orchestration | planning | implementation | qa | review | security | git | docs | data | infra
+version: 1.0
+required_skills: []
+optional_skills: []
+required_reads: []
+inputs: []
+outputs: []
+owns: []
+forbidden_paths: []
+allowed_behavior: []
+can_modify_code: false
+can_commit: false
+invoked_by: orchestrator | user
+---
+```
+
+These fields describe coordination boundaries. They do not grant runtime permissions.
+
+## Core Roles
+
+### orchestrator
+
+Purpose: Own the implementation state machine, runtime artifacts, integration, and git checkpoint decisions.
+
+Required behavior:
+
+- read `AGENT.md`, `.codex/agents/README.md`, and source-of-truth docs
+- own `.codex/runtime/**`
+- create scope, milestone, task, prompt, review, issue, QA, and checkpoint state
+- assign subagents only after dependencies, ownership, and prompt paths are clear
+- maintain `AGENT_ROSTER.yaml`
+- capture every returned subagent `agent_id` and write it into runtime state
+- resume persistent agents for related atom tasks and issue-fix loops
+- integrate outputs and decide commits
+- never delegate away final state and git responsibility
+- never default to doing implementation, docs, QA, review, or prompt-writing work directly when an eligible subagent can own it
+
+Typical outputs:
+
+- `.codex/runtime/RUNTIME_INDEX.yaml`
+- `.codex/runtime/scopes/<scope_id>/**`
+- `.codex/runtime/scopes/<scope_id>/AGENT_ROSTER.yaml`
+- assignment prompts
+- milestone QA/checkpoint updates
+
+### tech-prompt-agent
+
+Purpose: Convert atom tasks into implementation prompts.
+
+Boundary:
+
+- may write only `.codex/runtime/scopes/<scope_id>/milestones/<milestone_id>/prompts/`
+- must not edit implementation files
+- must not commit
+
+Prompt contents:
+
+- mission
+- required reads
+- ownership
+- TDD or executable check requirement
+- implementation contract
+- UX/accessibility/security contract where relevant
+- non-goals
+- expected artifacts
+- done criteria
+
+### implementation agents
+
+Purpose: Build scoped product artifacts.
+
+Select names from the repo domain:
+
+- `frontend-agent`
+- `backend-agent`
+- `content-schema-agent`
+- `data-agent`
+- `infra-agent`
+- `docs-agent`
+- `migration-agent`
+
+Boundary:
+
+- edit only assigned `owned_paths` and `allowed_paths`
+- never edit global runtime indexes unless explicitly assigned a runtime task
+- never commit
+- report exact files changed, checks run, output artifacts, risks, and task id
+
+### tdd-qa-agent
+
+Purpose: Define and run tests, executable checks, and milestone QA.
+
+Boundary:
+
+- may write tests and QA reports
+- may write `.codex/runtime/scopes/<scope_id>/milestones/<milestone_id>/reviews/*-qa.md`
+- should not implement product behavior unless assigned a fix task
+- must not commit
+
+### code-review-agent
+
+Purpose: Review completed artifacts asynchronously.
+
+Boundary:
+
+- may write review Markdown and update milestone-local issue logs
+- must not edit implementation files
+- must not commit
+
+Finding priorities:
+
+- correctness
+- source-truth alignment
+- task ownership drift
+- TDD/check gaps
+- maintainability
+- accessibility and responsive behavior where relevant
+- typed contracts and schema drift where relevant
+- security-sensitive mistakes where relevant
+
+### security-review-agent
+
+Purpose: Review secrets, auth, external input, APIs, file uploads, dependencies, deployment, analytics, and infrastructure.
+
+Boundary:
+
+- invoke only when security-sensitive scope exists
+- write security review artifacts and issue entries
+- do not edit implementation files
+- critical or blocker findings must be resolved before milestone completion
+
+### git-release-agent
+
+Purpose: Draft branch strategy, checkpoint boundaries, commit messages, PR text, and release notes.
+
+Boundary:
+
+- inspect runtime and git status
+- draft only
+- final staging, commit, push, and PR actions remain with the Orchestrator unless the user explicitly changes the rule
+
+## Assignment Rules
+
+- Assign implementation work only when `implement_prompt_path` exists.
+- Assign delegated work only after selecting `agent_session_policy: persistent | event`.
+- Spawn or resume the agent, then immediately record the returned `agent_id`.
+- Update both `AGENT_ROSTER.yaml` and `IMPLEMENT_TASKS.yaml` with the same `agent_id`.
+- Assign parallel tasks only when `owned_paths` are disjoint.
+- Mark runtime state before or immediately after real work state changes.
+- Convert unresolved review findings into fix tasks before milestone QA.
+- Route fix tasks back to the original persistent implementation `agent_id` when that agent is still available and ownership still matches.
+- Do not start the next milestone while blocker, critical, or required major issues remain open in the current milestone.
+
+## Agent Session Topology
+
+Persistent agents preserve memory across related work. Use them for planning and repeated implementation domains:
+
+- `tech-prompt-agent`
+- `frontend-agent`
+- `backend-agent`
+- `content-schema-agent`
+- `data-agent`
+- `infra-agent`
+- `docs-agent`
+- `migration-agent`
+
+Event-driven agents run asynchronously or one-off and close after handoff:
+
+- `code-review-agent`
+- `security-review-agent`
+- `tdd-qa-agent` unless it is actively authoring a long test suite across tasks
+- `git-release-agent`
+
+Asynchronous review is allowed. For example, a persistent frontend agent may work on `M02` while an event-driven review agent reviews `M01`. If review finds issues, it writes `M01` issues. The Orchestrator later converts them into fix tasks and resumes the original persistent implementation agent when possible.
+
+## Handoff Contract
+
+All agents return:
+
+- task id
+- summary
+- files changed or artifacts written
+- checks run and results
+- skipped checks with reasons
+- known risks
+- next recommended state transition
+
+The Orchestrator uses this handoff to update runtime state and decide checkpoint commits.