Qship

> Issue source — tracker = {{TRACKER_TYPE}} (chosen at onboarding). Follow the issue-source protocol in $SKILLS_ROOT/qship/references/tracker-contract.md — it defines, per tracker, how to FETCH / CHILDREN / CREATE / TRANSITION / READ-TRD. For none: treat $ARGUMENTS as the spec (pasted text or a local file path) and skip all tracker MCP calls.

qship -- Full Development Pipeline

Orchestrates the complete development lifecycle for one or more Jira tickets. Takes ticket IDs, fetches details from Jira, creates branches, plans implementation, writes code, reviews, hunts for bugs, fixes issues, and creates pull requests.

⛔ Read first — autonomy contract & hook enforcement

Before doing anything, read [references/autonomy-contract.md](references/autonomy-contract.md) in full. It defines persistence rules, the read-before-execute rule, the no-skip rule, and local-DB pre-authorisation. Every section below assumes you've internalised it. Sub-agents you spawn must read it too — pass them a one-line pointer, never paste the contract verbatim.

A skill is a prompt; prompts can be hallucinated past. qship backs the soft rules with three hard layers: PreToolUse blocks PR-create/push without evidence, Stop/SubagentStop blocks termination while progress files have PENDING rows, and qship-persist.sh is the outer ralph loop that keeps re-invoking until /qshipcheck says PASSED. Without those hooks the contract is advisory — verify they're wired with jq '.hooks | keys' ~/.claude/settings.json (expect PreToolUse, Stop, SubagentStop).

The three enforcement layers

1. PreToolUse hook — require-phase3-evidence.sh (already wired in ~/.claude/settings.json)

Blocks gh pr create, git push ... {{JIRA_PROJECT_KEY}}-*, and gh pr comment when {{STATE_ROOT}}/worktrees//phase3-evidence.md is missing, empty, or lacks HTTP/curl output + a "no network surface" rationale. Keeps Phase 4 from running with fake Phase 3 evidence.

1. Stop + SubagentStop hooks — require-pipeline-complete.sh (wired in ~/.claude/settings.json)

On every attempted termination, the hook reads {{STATE_ROOT}}/worktrees/*/phase2-progress.md, phase3-evidence.md, and trd-coverage.json (modified within the last QSHIP_FRESHNESS_MIN=240 minutes) and returns {"decision":"block","reason":"..."} whenever:

• a phase2-progress.md row is still PENDING, or
• phase3-evidence.md is empty / lacks HTTP evidence / lacks "no network surface" rationale, or
• trd-coverage.json has any row with passes: false.

Includes a stop_hook_active guard to prevent infinite loops. Stale worktrees (>4h untouched) are treated as abandoned and do NOT block — delete them to clear stuck blocks. This is what stops the orchestrator hallucinating completion mid-pipeline — the LLM no longer decides whether to continue; the progress files do.

1. Outer persistence loop — qship-persist.sh (ralph pattern wrapper)

For fully unattended runs, launch qship via: ``bash bash {{USER_HOME}}/.claude/skills/qship/hooks/qship-persist.sh {{JIRA_PROJECT_KEY}}-42 # or for a batch: MAX_ITERS=15 bash {{USER_HOME}}/.claude/skills/qship/hooks/qship-persist.sh {{JIRA_PROJECT_KEY}}-1 {{JIRA_PROJECT_KEY}}-2 {{JIRA_PROJECT_KEY}}-3 ` This bash loop re-invokes claude -p "/qship $TICKET" with a fresh context each iteration until claude -p "/qshipcheck $TICKET" prints PASSED. State lives in the filesystem ({{STATEROOT}}/worktrees//), so each iteration resumes exactly where the previous one left off. Survives context compaction, dropped connections, and rogue "I'm done" completion reports. Logs per-ticket to {{STATEROOT}}/persist-logs/`.

Permission allowlist (3rd layer of physical unblocking). The project .claude/settings.local.json pre-authorises the bash patterns qship routinely runs (alembic, migration runners, {{STATE_ROOT}}/worktrees/* scripts, worktree cp commands, claude -p /qship*). The text in SKILL.md that says "local DB writes are pre-authorised" now has an actual allowlist backing it — prompts do not auto-approve anything; the JSON file does.

How the three layers compose

| Failure mode | What catches it | |---|---| | Orchestrator says "pipeline complete" with Phase 3 unrun | PreToolUse blocks the push/PR | | Orchestrator tries to yield to user with PENDING rows | Stop hook blocks termination, feeds back the specific PENDING steps | | Context compaction drops the autonomy contract from prompt | qship-persist.sh restarts a fresh session and the Stop hook immediately picks up the pending state | | Sub-agent reports "skipped for time" | Orchestrator's progress file still shows PENDING → next iteration continues that step | | alembic upgrade head triggers a permission prompt | Allowlist entry pre-authorises — no pause |

Hook files

• ~/.claude/skills/qship/hooks/qship-evidence-lib.sh — shared evidence validator (sourced by the two hooks below)
• ~/.claude/skills/qship/hooks/require-phase3-evidence.sh — PreToolUse (Phase 4 gate on PR create / epic push)
• ~/.claude/skills/qship/hooks/require-pre-pr-test-pass.sh — PreToolUse (Step 12.0 gate: blocks gh pr create until full test suite is fresh-green per repo via phase4-tests-passed..flag files)
• ~/.claude/skills/qship/hooks/require-pipeline-complete.sh — Stop + SubagentStop (anti-yield gate)
• ~/.claude/skills/qship/hooks/qship-compute-context.sh — classifies the diff into API/UI booleans (run by Phase 1)
• ~/.claude/skills/qship/hooks/qship-persist.sh — outer loop (ralph wrapper)
• ~/.claude/skills/qship/hooks/qship-watchdog.sh — one-shot stall detector (file mtime + commit age + suspicious-idle-child sniff). Orchestrator runs this every ~5 min while a Phase 1/2/3/4 worker is in background. See "Worker stall watchdog" below.

Worker stall watchdog (orchestrator-side loop)

Background workers can wedge mid-step (the canonical failure: an xhigh planner subprocess held open stdio and stalled the worker's Bash tool for 2+ hours on {{JIRAPROJECTKEY}}-EX11 — see [feedbackqshipworkerstallwatchdog.md](file://{{USERHOME}}/.claude/projects/-Users-{{LOCALDBUSER}}-work-{{GHORG}}-{{COMPANYSLUG}}-codebase/memory/feedbackqshipworkerstall_watchdog.md)). The harness reports the agent as "running" indefinitely because the agent never finishes a tool call. Without a watchdog the orchestrator silently waits forever.

Rule for every background worker dispatch: after Agent(... run_in_background: true), the orchestrator MUST poll progress every 5 minutes via the watchdog. The cheapest mechanism depends on how you were invoked:

| Invocation | Recommended cadence mechanism | |---|---| | /loop 5m /qship (preferred for unattended) | The /loop interval is itself the watchdog tick — every fire, run qship-watchdog.sh and react. | | In-session /qship | After each background dispatch, schedule a re-entry via ScheduleWakeup delaySeconds=300 (when in /loop dynamic mode) OR manually run bash ~/.claude/skills/qship/hooks/qship-watchdog.sh --strict on each turn before sending control back to the user. | | qship-persist.sh outer loop | The persist loop already re-enters every iteration; add a watchdog call near the top of each iteration. |

Watchdog mechanics (qship-watchdog.sh — exits 0=OK / 1=STALL):

1. File-mtime check: newest non-noise file under {{STATE_ROOT}}/worktrees// was modified within STALL_FILE_MIN minutes (default 12). A worker actively writing code touches a file at least every few minutes.
2. Commit-age check: at least one new commit on the branch within STALL_COMMIT_MIN minutes (default 25). Only counts as a stall signal when files are ALSO stale — a worker may be deep in a long edit without committing.
3. Suspicious-idle-child sniff: scans for child processes whose argv contains claude -p / codex exec --model / --effort xhigh AND has been alive > STALL_BG_MIN minutes (default 30) AND is using -o etime,pcpu,command` — if it's been idle 30+ min with no output, it's hung.
4. SendMessage the worker by agent ID (NOT by name — the name binding may be stale after session resume) telling it to: (a) BashOutput/KillShell the hung shell, (b) stop re-planning at xhigh (the Step 5/6 plan is already authoritative), (c) resume from the current branch tip per phase2-progress.md PENDING rows, (d) write phase1-blocker.md instead of silently hanging if genuinely blocked. The exact recovery prompt is recorded in the memory lesson.
5. Do NOT redispatch a new worker unless the SendMessage returns "no agent with that ID" (truly gone) — two workers on the same worktree will rewrite each other's commits.
6. Re-run the watchdog 5 min later. If still STALL on a different reason, escalate to the user.

False-positive defense: the watchdog is read-only — it never kills processes or touches the worktree. It only reports. The orchestrator is the decision-maker. Tune STALL_FILE_MIN / STALL_COMMIT_MIN / STALL_BG_MIN via env vars for tickets where long-running tests or codex review rounds legitimately take more time than the defaults.

If any of these are missing or not registered in ~/.claude/settings.json, treat every soft gate below as advisory. Verify with:

jq '.hooks | keys' ~/.claude/settings.json
# should include: PreToolUse, Stop, SubagentStop

> Evidence format — the split-evidence (API + UI) contract, Playwright reporter setup, escape rationales, and how to debug a hook block live in [references/evidence-format.md](references/evidence-format.md).

---

Autonomy contract — see [references/autonomy-contract.md](references/autonomy-contract.md)

The contract is intentionally factored into a separate file so it can be linked (not pasted) into sub-agent prompts. Read it once at the start of an iteration; the rules apply to every step below.

The orchestrator's TL;DR for the rules in that file:

• Don't stop until /qshipcheck returns PASSED. Compaction is automatic; persist state to phase2-progress.md / phase3-evidence.md / trd-coverage.json.
• Read referenced skills/files in full before executing. Skimming produces silent failures (e.g., missing qmanualt DEV_MODE patches).
• No step may be skipped or substituted. /qshipcheck flags violations and re-runs from the first skip.
• Local writes to {{LOCAL_DEV_DB_NAME}} are auto-approved; staging/prod still prompt.

Local development — Python version

qship assumes pyenv is on PATH. The codebase requires Python 3.10+ (uses dict | None PEP 604 syntax, match statements, etc.). The system python3 on macOS is 3.9.6 and will fail with TypeError: unsupported operand type(s) for | on import.

When workers or the orchestrator invoke pytest, alembic, python -m black, or any other Python tool manually, prepend pyenv shims to PATH or use pyenv exec:

export PATH="{{USER_HOME}}/.pyenv/shims:$PATH"
# or:
pyenv exec pytest tests/ -v
# or use the per-repo venv (always 3.11+):
{{CODEBASE_ROOT}}//venv/bin/python -m pytest tests/ -v

Failure {{JIRAPROJECTKEY}}-EX01: orchestrator ran python -m alembic upgrade head and hit SyntaxError: invalid syntax because python resolved to 3.9.6.

Pipeline Overview

The pipeline runs in 5 phases:

| Phase | Steps | Owner | Purpose | |-------|-------|-------|---------| | Phase 1: Build | 1–7.4 | Opus sub-agent | Plan, implement, clean up | | Phase 1.5: TRD Mirror | 7.45 | Opus sub-agent (audited by orchestrator) | Line-by-line TRD vs code gap analysis + fix all gaps | | Phase 2: Review | 7.5–11.5 | Opus sub-agents (dispatched by orchestrator) | Simplify, review, bug hunt, fix, verify | | Phase 3: Accept | 14 | Opus sub-agent runs /qe2etest (audited by orchestrator) | E2E testing with coverage audit loop | | Phase 4: Deliver | 12–13, 15 | Opus sub-agent (dispatched by orchestrator) | Create PRs, final review, pipeline check |

All phases use Opus sub-agents for maximum quality. The orchestrator never executes work itself — it dispatches, monitors, audits, and redispatches.

All Steps

> Step numbers are stable identifiers, not a chronological order. External skills (qshipcheck, qshipphasecheck, qshipmaster, qshipp2) reference them by name, so they can't be renumbered without coordinated cross-skill edits. The actual execution order is the Phase column: 1 → 1.5 → 2 → 3 → 4. Inside Phase 4, the order is 12 → 13 → 15 (Step 14 is Phase 3). Step 7's internal sub-steps (memory search, TDD loop, migration handling, completion check) use unnumbered headings inside pipeline-steps.md to avoid colliding with the top-level Steps 7.3/7.4 below.

| # | Phase | Step | What it does | |---|-------|------|-------------| | 1 | 1 | Jira Fetch | Retrieve ticket details from Jira via Atlassian MCP | | 2 | 1 | Repo Detection | Determine which repos are affected (read from repos.json) | | 3 | 1 | Pull Latest | Fetch and checkout latest develop in each affected repo | | 4 | 1 | Create Branch | Create a feature branch from develop (-) | | 4.1 | 1 | Baseline Verify | Run full test suite on clean branch to confirm green baseline | | 5 | 1 | Write Plan | Generate a detailed implementation plan using the writing-plans skill | | 6 | 1 | Plan Review | Validate plan against codebase patterns, analogous code, and CLAUDE.md | | 7 | 1 | Implement (TDD) | Execute the plan with red-green-refactor TDD cycle; batch checkpoints for 5+ task plans | | 7.3 | 1 | Directory Check | Verify new files are in correct directories; fix misplaced files | | 7.4 | 1 | Clean Defensive Code | Remove unneeded try/except blocks and redundant null checks | | G1 | Gate | Phase 1 Gate | Orchestrator audits Phase 1 output for stubs/TODOs before proceeding | | 7.45 | 1.5 | TRD Mirror Review + Fix | Opus sub-agent does line-by-line TRD vs code comparison, implements all gaps | | 7.5 | 2 | Simplify | Run code simplifier agent on all changed code; §7.5.3 verifies suggestions were APPLIED, not just listed | | 8 | 2 | Code Review | §8.0 complexity tier first (T1=0 / T2=1 / T3=2 / T4=3 reviewers). Up to four parallel reviewers + qmigrationdevcheck (§8.5.1, alembic) + qauthtrailingslash (§8.6.5, routes) → unified phase2-findings.md. T1–T3 mark unused reviewer rows SKIPPED [tier T]. | | 9 | 2 | Bug Hunt | Fan-out scales with §8.0 tier — T1=0 / T2=2 / T3=3 / T4=5 bug hunters against the diff | | 10 | 2 | Bug Validation | Validate qbug findings — filter false positives, confirm real bugs | | 11 | 2 | Fix Issues | Read phase2-findings.md; tick every MUST FIX or move to Rejected with rationale. Universal no-drop rule: NO finding from ANY source may be silently skipped — applies equally to qcheckt, simplifier, Agent 1/2, qauthtrailingslash, qmigrationdevcheck, cross-branch, etc. | | 11.5 | 2 | Verification Gate | Fresh test run + formatting check + phase2-findings.md closure audit — hard gate before Phase 3 | | 11.6 | 2 | Quick E2E (/qe2etest) | Per-worker smoke against the change — fast, cheap, before the full Phase 3 /qe2etest run (which uses the complete scenario matrix and delegates UI to /qmanualt) | | 11.7 | 2 | Memory Capture (/qmemory) | Persist any reusable lesson from this ticket before Phase 3 | | G2 | Gate | Phase 2 Gate | Run /qshipphasecheck phase2 — BLOCKS Phase 3 if ANY step missing | | 14 | 3 | E2E Testing | Opus sub-agent runs full E2E, orchestrator audits coverage, redispatches for gaps | | G3 | Gate | Phase 3 Gate | Run /qshipphasecheck phase3 — BLOCKS Phase 4 if E2E not done | | 12.0 | 4 | Final Test Pass | Full pytest tests/ -v per affected repo with fix loop. Drops phase4-tests-passed..flag. Enforced by PreToolUse hook on gh pr create — no flag → no PR. | | 12 | 4 | Create PR | Commit, push, and open pull requests targeting develop | | 12.5 | 4 | Watch CI | `gh pr checks --wat

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 3awny
• Source: 3awny/qship
• License: MIT

Install and usage instructions live in the source repository linked above.