verified-merge

Files (5)

• CONFIG.template.md
• SKILL.md
• adapter-contract.md
• reference.md
• test-scenarios.md

SKILL.md (first lines)

# Verified Merge

Deliver one unit of work end to end: resolve a source adapter, fetch normalized context, implement with tests, verify locally, open or update a PR, review, keep CI green, merge only with approval, verify after merge, and sync lifecycle events to the adapter.

This workflow is tracker-neutral. Jira, Work Orders, and future sources are adapters — not hard dependencies.

## Start Here

At invocation, announce:

> "I'm using verified-merge to deliver this unit of work through verified merge."

Then:

1. Read project config from [CONFIG.template.md](CONFIG.template.md) if present.
2. Resolve the source adapter using [adapter-contract.md](adapter-contract.md) routing rules.
3. Invoke the adapter's `fetch` to produce a NormalizedDeliveryContext.
4. Write or update `docs/verified-merge/delivery.json` for the unit.
5. Run the delivery pipeline below, emitting lifecycle events to the adapter at each checkpoint.

Read [adapter-contract.md](adapter-contract.md) before any adapter invocation.

## Governed work-order path (`implement_work_orders`)

For EC2 workflow dispatch, use **`verified-merge-governed`** (this filesystem skill is skipped on
governed dispatch). That path calls `run_coding_backend`, which clones, runs OpenCode, commits,
pushes, and opens the PR — then returns `{ "work_order_id": "...", "pr_url": "..." }`.

Merge completion for `await_human_merge` is external: `POST /webhooks/github` on a merged
`pull_request` event (preferred), or orchestrator `resume_external_event` with
`event_type=github.merge` and matching `pr_url`.

## Prerequisites

| Requirement | Purpose |
|---|---|
| Resolved source adapter | Fetch and sync unit context |
| GitHub CLI (`gh`) | PR creation, checks, merge |
| superpowers plugin | brainstorming, TDD, verification, debugging, planning |
| cursor-team-kit plugin | new-branch-and-pr, review-and-ship, loop-on-ci, fix-ci |
| `ts-pr-description` (this library) | Generate PR titles and descriptions |
| Atlassian MCP (Jira adapter only) | Fetch and transition Jira issues |

See [reference.md](reference.md) for the full dependency table.

## When to Use

Use this workflow when the user:

- Provides a Work Order id such as `WO-003` or a path under `docs/planner/**`.
- Provides a Jira key such as `PROJ-123` and asks to process, ship, merge, or verify it.
- Pastes unit content and asks for end-to-end delivery.
- Says "verified merge", "merged and verified", or "deliver this work order".

Do not use this for PRD creation (`ts-plan-prd`) or PRD-to-Work-Orders planning (`prd-to-work-orders`).

## Hard Gates

- One unit of work per branch and PR.
- Never merge without explicit user approval.
- Never emit `post_merge_verified` before post-merge verification succeeds.
- Never emit `in_development` before acceptance criteria are testable and oversized scope is resolved.
- Never claim ready, fixed, passing, merge-ready, merged, or verified without fresh evidence. **REQUIRED SUB-SKILL:** Use `superpowers:verification-before-completion`.
- Never implement ambiguous requirements by guessing. Use `superpowers:brainstorming` or ask focused questions.
- Never fix bugs, test failures, build failures, or CI failures without root-cause investigation. **REQUIRED SUB-SKILL:** Use `superpowers:systematic-debugging`.
- Never edit `docs/prd-to-work-orders/manifest.json` from this workflow.
- Scaffolds bootstrap **new** structure only; never invoke a build scaffold to modify an existing app (see Step 5).
- Never use `--no-verify`, `--no-gpg-sign`, force-push, or skip CI without explicit user request.
- Prefer updating the same PR for feedback unless the user explicitly asks for a new PR.

## Lifecycle Checkpoints

At each checkpoint:

1. Update `docs/verified-merge/delivery.json`.
2. Invoke the resolved adapter's `on_event` with the event name and payload.
3. Continue the pipeline only after the checkpoint completes.

Events: `context_accepted`, `in_development`, `pr_opened`, `pr_updated`, `ci_green`, `merged`, `post_merge_verified`, `blocked`.

## Pipeline

### 1. Resolve Adapter and Fetch Context

1. Run adapter routing from [adapter-contract.md](adapter-contract.md):
   - Auto-detect from input shape (`WO-###` -> work-order, `PROJ-###` -> jira).
   - Fall back to configured `delivery.source` (default: work-order).
   - Ask if no adapter resolves.
2. **REQUIRED:** Load and follow the resolved adapter skill (`source-work-order` or `ts-source-jira`).
3. Produce a NormalizedDeliveryContext.
4. If fetch fails, ask the user to paste details or fix adapter setup.
5. Emit `context_accepted` and initialize `docs/verified-merge/delivery.json`.

If the user pasted content without an id, treat pasted text as the description and proceed only when acceptance criteria can be made testable.

### 2. Scope and Requirements Check

Classify the unit before implementation:

- Ambiguous acceptance criteria: **REQUIRED SUB-SKILL:** Use `superpowers:brainstorming`.
- Multiple independent subsystems: stop and propose splitting into separate units or PRs.
- Multi-step implementation: **REQUIRED SUB-SKILL:** Use `superpowers:writing-plans`.
- Work Order with unresolved dependencies: stop and report blocking dependency ids.
- Straightforward change with clear acceptance criteria: proceed with a concise implementation plan.

Do not start code changes until scope and acceptance criteria are clear enough to test.

### 3. Mark In Development

When the unit is clear enough to proceed:

1. Emit `in_development`.
2. Let the adapter sync external tracker status if configured.
3. If sync fails, report available options and continue without inventing status.

### 4. Create Isolated Workspace

- **REQUIRED SUB-SKILL:** Use `superpowers:using-git-worktrees` (default).
- If the user prefers branch-only work, create the branch directly.

From TribalScale/ts-harness, Apache-2.0.

More from TribalScale/ts-harness