# project-orchestrator

Adopt this skill: https://proskills.md/skills/other/justinstolzenberg-sudo-openclaw-agent-skills-project-orchestrator

Page: https://proskills.md/skills/other/justinstolzenberg-sudo-openclaw-agent-skills-project-orchestrator
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: project-orchestrator/SKILL.md
size: 8000
upstream: https://github.com/justinstolzenberg-sudo/openclaw-agent-skills/blob/main/project-orchestrator/SKILL.md

````text
---
name: project-orchestrator
description: >
  Orchestrate tracked software projects with a deterministic lifecycle state
  machine, required artifacts, approval gates, review loops, and optional
  Linear synchronization. Use when: creating a new tracked project, checking
  project status, validating project artifacts, transitioning project state,
  planning project work, or enforcing a stage-based workflow for an entry in
  PROJECTS.yaml. NOT for: ad-hoc tasks, one-off questions, or work that is not
  being tracked as a project in the current OpenClaw workspace.
---

# Project Orchestrator

Use this skill to manage tracked software projects through explicit states. The scripts validate states, transitions, and required artifacts against `references/state-machine.yaml`.

## Workspace assumptions

Run from an OpenClaw workspace that uses `PROJECTS.yaml` and `projects/`.

Workspace detection order:
1. `OPENCLAW_WORKSPACE`
2. walk upward from the current directory looking for `PROJECTS.yaml`
3. fallback to `~/.openclaw/workspace`

## Quick reference

All commands output JSON.

```bash
python3 skills/project-orchestrator/scripts/orchestrator.py init <name> --tier <patch|feature|project>
python3 skills/project-orchestrator/scripts/orchestrator.py status <name>
python3 skills/project-orchestrator/scripts/orchestrator.py validate <name>
python3 skills/project-orchestrator/scripts/orchestrator.py transition <name> <TARGET_STATE>
python3 skills/project-orchestrator/scripts/orchestrator.py plan <name>
python3 skills/project-orchestrator/scripts/orchestrator.py review-status <name>
```

If you are already in the skill directory, `python3 scripts/orchestrator.py ...` also works.

## Tiers

Choose the tier at `INTAKE` based on scope.

| Tier | Token budget | Typical scope | Uses `ARCHITECTURE`? |
|------|--------------|---------------|----------------------|
| patch | < 50k | Small, local change | No |
| feature | 50k-300k | Contained feature in an existing system | No |
| project | > 300k | New repo or major architectural change | Yes |

Estimate in tokens, not time. When unsure, start with `feature`. Upgrade to `project` if major architecture work emerges during `BRIEF`.

## State flow

**patch / feature**
```text
INTAKE -> BRIEF -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

**project**
```text
INTAKE -> BRIEF -> ARCHITECTURE -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

**optional UI design path**
```text
INTAKE -> BRIEF -> DESIGN -> PLAN/ARCHITECTURE -> ...
```

Any state can transition to `CANCELED`.

## Approval gates

Approval gates exist at `BRIEF`, `ARCHITECTURE`, `PLAN`, and `REVIEW`.

At each gate:
1. Run `validate <name>`.
2. Confirm the required artifact and review files exist.
3. Present a concise summary to the human operator in the current working channel.
4. Wait for explicit approval.
5. Only then run `transition <name> <TARGET_STATE>`.

Never auto-approve. Never skip approval gates.

## New project workflow

1. Run `init <name> --tier <tier>`.
2. Update the project entry in `PROJECTS.yaml` with repo, path, description, tags, and any external IDs.
3. Write the current-stage artifact in `projects/<name>.md`.
4. Use the templates in `references/templates/`.
5. Run `transition <name> BRIEF` once intake is complete.
6. Continue state by state, validating before every transition.

## Status workflow

1. Run `status <name>`.
2. Read the current state, exit criteria, required artifacts, and valid transitions.
3. Report the result in plain language.

## Transition workflow

1. Run `validate <name>` first.
2. If validation fails, fix the missing artifact or review requirement before proceeding.
3. If the current state is an approval gate, get explicit human approval.
4. Run `transition <name> <TARGET_STATE>`.
5. Confirm the returned JSON shows the expected new state and follow-up actions.
6. If your workspace uses Linear, verify the sync fields in the response and correct failures immediately.

## PM relay watchdog, correct usage

When your runtime cannot keep a persistent PM session alive, use the PM relay helper as an explicitly scoped watchdog.

Recommended commands:

```bash
python3 skills/project-orchestrator/scripts/pm-relay-helper.py activate <name> --state <STATE>
python3 skills/project-orchestrator/scripts/pm-relay-helper.py list-active
python3 skills/project-orchestrator/scripts/pm-relay-helper.py sweep-active
python3 skills/project-orchestrator/scripts/pm-relay-helper.py deactivate <name>
```

Rules:
- track only projects that are actively in flight
- keep the active-project list as the source of truth for relay scope
- do not run global sweeps across every tracked project
- do not respawn a PM owner if a real blocker already explains the gap
- do not respawn into an operator-approval-only wait state
- keep idle watchdog runs silent, and only surface user-facing updates when the watchdog actually changes something meaningful

## Linear integration

Linear support is built into the scripts. Use it when your workspace tracks projects there.

### Commands

```bash
python3 skills/project-orchestrator/scripts/linear_integration.py create-project
python3 skills/project-orchestrator/scripts/linear_integration.py create-issue
python3 skills/project-orchestrator/scripts/linear_integration.py create-issues-from-plan
python3 skills/project-orchestrator/scripts/linear_integration.py update-state
python3 skills/project-orchestrator/scripts/linear_integration.py sync-state
python3 skills/project-orchestrator/scripts/linear_integration.py add-comment
python3 skills/project-orchestrator/scripts/linear_integration.py get-issue
python3 skills/project-orchestrator/scripts/linear_integration.py validate-transition
```

### Rules

- Keep orchestrator state and Linear state aligned if the project has a `linear_project_id`.
- Use your workspace's configured bot or service account for agent-owned issues.
- Assign human-only tasks to the human operator.
- When work is completed during `BUILD`, update the related Linear issue state immediately.

### State mapping

| Orchestrator state | Linear state |
|--------------------|--------------|
| INTAKE, BRIEF | Backlog |
| ARCHITECTURE | Todo |
| PLAN | In Progress |
| BUILD | In Dev |
| REVIEW | Review |
| SHIP | In Prod |
| CLOSED | Done |
| CANCELED | Canceled |

## Templates

Templates live in `references/templates/`.

- `brief.md` - `BRIEF`
- `design-spec.md` - `DESIGN`
- `architecture.md` - `ARCHITECTURE`
- `plan.md` - `PLAN`
- `review-checklist.md` - `REVIEW`
- `inter-agent-review.md` - approval-gate review loops

## Inter-agent review workflow

Approval-gate artifacts should go through a review loop before operator approval.

Pattern:

```text
producer -> critic -> project-manager review -> operator approval
```

### Recommended roles by stage

| Stage | Producer | Critic |
|-------|----------|--------|
| BRIEF | main agent or project lead agent | domain expert reviewer |
| ARCHITECTURE | architect agent | senior engineer reviewer |
| PLAN | planner agent | tech lead reviewer |
| REVIEW | reviewer agent | QA reviewer |

### Review process

1. Producer writes or updates the artifact.
2. Critic reviews it and records issues as `BLOCKING`, `SIGNIFICANT`, or `MINOR`.
3. Producer responds and revises.
4. Repeat up to 3 rounds.
5. A project-manager pass decides whether the artifact is ready for operator review.
6. Present the artifact and review summary to the operator.

### Review files

Store review files in `projects/` and use the template at `references/templates/inter-agent-review.md`.

Suggested naming:

```text
projects/<name>-review-<stage>-round<N>.md
```

Run:

```bash
python3 skills/project-orchestrator/scripts/orchestrator.py review-status <name>
```

Use the result to confirm whether review files exist and whether sign-off is complete.

## Pre-close verifications

Before moving from `SHIP` to `CLOSED`, require two independent checks.

### 1. Test verification

Have an independent reviewer inspect t
````

## File: README.md
upstream: https://github.com/justinstolzenberg-sudo/openclaw-agent-skills/blob/main/README.md

````text
# Project Orchestrator

Structured project lifecycle orchestration for OpenClaw.

This skill adds a deterministic state machine around tracked software projects so work moves through explicit stages, required artifacts, review loops, and approval gates instead of ad-hoc status changes.

## What it is for

Use this skill when you want OpenClaw to manage a real project in a workspace that already tracks projects in `PROJECTS.yaml`.

It is most useful when you want:

- predictable stage transitions
- explicit approval gates before major work proceeds
- artifact validation before transitions
- structured producer/critic review loops
- optional Linear project and issue sync
- a clear paper trail in `projects/<name>.md`

It is not a general task manager for one-off questions or untracked work.

## Lifecycle

```text
INTAKE -> BRIEF -> [DESIGN] -> [ARCHITECTURE] -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

Rules:

- `DESIGN` is optional and intended for UI-heavy work.
- `ARCHITECTURE` is only used for `project` tier work.
- Any state can transition to `CANCELED`.
- Approval gates exist at `BRIEF`, `ARCHITECTURE`, `PLAN`, and `REVIEW`.

### Tier flows

**patch**
```text
INTAKE -> BRIEF -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

**feature**
```text
INTAKE -> BRIEF -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

**feature with UI design**
```text
INTAKE -> BRIEF -> DESIGN -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

**project**
```text
INTAKE -> BRIEF -> ARCHITECTURE -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

**project with UI design**
```text
INTAKE -> BRIEF -> DESIGN -> ARCHITECTURE -> PLAN -> BUILD -> REVIEW -> SHIP -> CLOSED
```

## Workspace expectations

This skill assumes a standard OpenClaw workspace with at least:

- `PROJECTS.yaml`
- `projects/`
- `skills/project-orchestrator/`

The scripts auto-detect the workspace by:

1. `OPENCLAW_WORKSPACE`
2. walking upward from the current directory looking for `PROJECTS.yaml`
3. falling back to `~/.openclaw/workspace`

## Prerequisites

### Required

- Python 3.10+
- an OpenClaw workspace using `PROJECTS.yaml`

### Optional

- Linear credentials if you want project and issue sync
- `anthropic` Python package plus an Anthropic API key if you want to use the design generator
- a runtime that can launch subagents if you want the full producer/critic review workflow

## Install

From your workspace root:

```bash
mkdir -p ~/.openclaw/workspace/skills
cp -r /path/to/openclaw-agent-skills/project-orchestrator ~/.openclaw/workspace/skills/
```

Or symlink it:

```bash
ln -s /path/to/openclaw-agent-skills/project-orchestrator ~/.openclaw/workspace/skills/project-orchestrator
```

## Core commands

Run these from the workspace root.

```bash
python3 skills/project-orchestrator/scripts/orchestrator.py init <name> --tier <patch|feature|project>
python3 skills/project-orchestrator/scripts/orchestrator.py status <name>
python3 skills/project-orchestrator/scripts/orchestrator.py validate <name>
python3 skills/project-orchestrator/scripts/orchestrator.py transition <name> <TARGET_STATE>
python3 skills/project-orchestrator/scripts/orchestrator.py plan <name>
python3 skills/project-orchestrator/scripts/orchestrator.py review-status <name>
```

All commands return JSON.

## Typical workflow

1. Initialize a tracked project with `init`.
2. Fill in the project entry in `PROJECTS.yaml`.
3. Write the current-stage artifact in `projects/<name>.md` using the provided templates.
4. Run `validate` before every approval gate or transition.
5. Use `transition` to move to the next valid state.
6. Keep review files and audit artifacts alongside the project summary.

## Review model

The recommended pattern at approval gates is:

```text
producer -> critic -> project-manager review -> operator approval
```

In practice that means:

- one agent or subagent produces the artifact
- a second agent critiques it and raises issues
- a coordinating project-manager pass checks whether the result is ready
- the human operator gives final approval

The repository includes a reusable review template at:

```text
references/templates/inter-agent-review.md
```

## PM relay watchdog, correct usage

When your runtime cannot keep a persistent PM session alive, use the PM relay helper as an explicitly scoped watchdog.

Recommended commands:

```bash
python3 skills/project-orchestrator/scripts/pm-relay-helper.py activate <name> --state <STATE>
python3 skills/project-orchestrator/scripts/pm-relay-helper.py list-active
python3 skills/project-orchestrator/scripts/pm-relay-helper.py sweep-active
python3 skills/project-orchestrator/scripts/pm-relay-helper.py deactivate <name>
```

Rules:
- track only projects that are actively in flight
- keep the active-project list as the single source of truth for relay scope
- do not run global sweeps across every tracked project
- do not respawn a PM owner if a real blocker already explains the gap
- do not respawn into an operator-approval-only wait state
- keep idle watchdog runs silent, and only send user-facing updates when the watchdog actually changes something meaningful

## Linear integration

Linear support is built in, but it is a workflow choice rather than a documentation prerequisite.

Relevant helpers:

```bash
python3 skills/project-orchestrator/scripts/linear_integration.py create-project
python3 skills/project-orchestrator/scripts/linear_integration.py create-issue
python3 skills/project-orchestrator/scripts/linear_integration.py create-issues-from-plan
python3 skills/project-orchestrator/scripts/linear_integration.py update-state
python3 skills/project-orchestrator/scripts/linear_integration.py sync-state
```

Set the required Linear environment variables in the workspace where you run the scripts.

## Optional design workflow

For UI-heavy projects, the skill includes a design generator and SVG wireframe generator.

```bash
python3 skills/project-orchestrator/scripts/design-producer.py --brief <file> --output-dir <dir> --wireframes
python3 skills/project-orchestrator/scripts/wireframe-gen.py --input <spec.json> --output-dir <dir>
```

The design generator looks for an API key in this order:

1. `--api-key`
2. `ANTHROPIC_API_KEY`
3. an OpenClaw `auth-profiles.json` if present

## Included files

```text
project-orchestrator/
├── SKILL.md
├── README.md
├── scripts/
│   ├── orchestrator.py
│   ├── linear_integration.py
│   ├── pm-checker.py
│   ├── design-producer.py
│   └── wireframe-gen.py
├── references/
│   ├── state-machine.yaml
│   ├── design-workflow.md
│   └── templates/
└── tests/
```

## Notes on strictness

This skill is intentionally opinionated.

It favors:

- explicit states over informal progress updates
- validation over trust
- review loops over single-pass artifacts
- operator approval over silent transitions

If that is the operating model you want, this skill is a good fit.
````
