skills/docs/engineering/implementation-orchestrator.md

Pi implementation orchestrator skill

implementation-orchestrator implements already-planned tracker tickets from issue selection through isolated implementation worktrees, pull/merge requests, review, merge, and cleanup.

It supports:

• Tea-compatible Gitea/Forgejo repositories through tea
• GitHub repositories through gh
• GitLab repositories through glab

The forge is selected from origin, or explicitly with DEV_WORKFLOW_FORGE.

Install

From this checkout, install globally for your user:

pi install /absolute/path/to/ws-developement-workflow

Or install it only for the current project:

pi install -l /absolute/path/to/ws-developement-workflow

Restart Pi after installation, or run /reload in an existing session. Review the package before installing it: skills can instruct Pi to run commands with your account's permissions.

When to use it

Use this after the human-led wayfinder, planning, specification, and ticket phases have produced implementation tickets.

The skill does not create planning tickets. It only implements tickets that are already labelled:

workflow:ready-for-agent

Invoke it with an optional ticket ID or URL:

# Process only ticket 43
/skill:implementation-orchestrator 43

# Process all available tickets in the current repository
/skill:implementation-orchestrator

The ID must be a tracker issue/ticket, not a branch name, PR/MR ID, or session ID. With an ID, only that ticket is processed. With no ID, the skill considers all open tickets in the current repository.

Prerequisites

Before invoking the skill:

1. Run it from a checkout of the target repository.
2. Ensure origin points to the correct forge repository.
3. Install and authenticate the matching CLI:
   • Tea/Gitea/Forgejo: tea
   • GitHub: gh
   • GitLab: glab
4. Create implementation tickets, optionally grouped under a root issue.
5. Mark implementable tickets workflow:ready-for-agent.
6. Add native child/dependency relationships where supported. Otherwise put explicit issue URLs or the documented blocker marker in the ticket.
7. Configure DEV_WORKFLOW_HUMAN_REVIEWER if the agent may assign human review automatically.

Run the read-only preflight manually from the target repository if needed:

bash /path/to/this-package/skills/forge-cli/scripts/detect-forge.sh

Expected output resembles:

forge=gh
remote=https://github.com/acme/project.git

What happens

For the supplied ticket, or all tickets when no ticket is supplied, the skill:

1. Verifies the repository, forge CLI, authentication, default branch, and capabilities.
2. Reads only the supplied ticket; otherwise reads all open tickets in the repository.
3. Selects only open, unassigned, unblocked workflow:ready-for-agent tickets.
4. For a supplied ticket, runs only that ticket; with no ticket, runs currently unblocked tickets in parallel, up to three isolated workers. Dependent tickets wait for their blockers.
5. Claims each selected ticket and changes it to workflow:implementing, then gives it to one worker in an isolated Git worktree.
6. Runs local checks, pushes the branch, and creates exactly one PR/MR per ticket.
7. Records URLs, status, evidence, blockers, and handoffs in tracker comments.
8. Reviews each PR/MR for correctness/spec and standards, allowing at most three fix rounds.
9. Resolves conflicts through the conflict workflow instead of aborting or guessing.
10. Merges only when review, local checks, CI, target branch, and blocker gates are clean.
11. Closes the integrated ticket, records the merge receipt, and removes the worktree.
12. Re-queries the scoped ticket set after every merge so newly unblocked tickets can run.

Default worker parallelism is three, subject to the available subagent limit.

Ticket labels

The skill uses one active workflow label per ticket:

workflow:ready-for-agent
workflow:ready-for-human
workflow:implementing
workflow:pr-open
workflow:review
workflow:changes-requested
workflow:conflict
workflow:blocked
workflow:merged

Existing workflow:ready-for-human tickets are left untouched and reported as human handoffs. Missing requirements, unsafe ambiguity, credentials, product decisions, unavailable CI, and missing permissions stop the workflow instead of being guessed around.

Forge CLI recipes

After preflight, the shared forge-cli skill contains the common rules and automatically selects one recipe:

• skills/forge-cli/references/tea.md
• skills/forge-cli/references/gh.md
• skills/forge-cli/references/glab.md

Other skills can use it too: install this package globally, then instruct them to load the shared forge-cli skill instead of duplicating CLI syntax.

Completion states

The final report includes:

• merged tickets and PR/MR URLs;
• remaining eligible tickets;
• tickets waiting for human review;
• blocked tickets and exact reasons;
• failed checks and review rounds.

done means no open implementation or human tickets remain in the selected scope. If only human tickets remain, the result is waiting-on-human.

Development checks

Validate the package with:

bash tests/test-workflow.sh

This checks skill metadata, references, shell syntax, forge detection, and eligibility filtering.