gitadmin
b9567c5e39
The name dev-workflow described a category, not what the skill does. It orchestrates implementation of already-planned tickets, so the new name says that. Skill dir, docs page, name field and openai display name are updated to match; validate-skill.sh moves with the dir and its paths are fixed for the new depth and engineering/ layout.
147 lines
5.2 KiB
Markdown
147 lines
5.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
pi install /absolute/path/to/ws-developement-workflow
|
|
```
|
|
|
|
Or install it only for the current project:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
workflow:ready-for-agent
|
|
```
|
|
|
|
Invoke it with an optional ticket ID or URL:
|
|
|
|
```text
|
|
# 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
|
|
bash /path/to/this-package/skills/forge-cli/scripts/detect-forge.sh
|
|
```
|
|
|
|
Expected output resembles:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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
|
|
bash tests/test-workflow.sh
|
|
```
|
|
|
|
This checks skill metadata, references, shell syntax, forge detection, and eligibility filtering.
|