@snappedly-tools/shipyard 0.5.0 → 0.6.0

package/dist/templates/parallel-planner-with-review/setup.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n ${GH_REPO:-} ]]; then
+  [[ "$GH_REPO" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GH_REPO" >&2; exit 1; }
+  git remote set-url origin "https://github.com/$GH_REPO.git"
+fi
+
+# Install for this sandbox's checkout. Host node_modules can contain binaries
+# for a different OS and cannot cover dependencies added by the agent later.
+if [[ -f package.json ]]; then
+  manager=$(node -e 'try { const p = require("./package.json").packageManager; process.stdout.write(p ? p.split("@")[0] : "") } catch {}')
+  if [[ -z "$manager" ]]; then
+    if [[ -f bun.lock || -f bun.lockb ]]; then manager=bun
+    elif [[ -f pnpm-lock.yaml ]]; then manager=pnpm
+    elif [[ -f yarn.lock ]]; then manager=yarn
+    else manager=npm; fi
+  fi
+  case "$manager" in
+    npm) npm install ;;
+    pnpm) corepack pnpm install ;;
+    yarn) corepack yarn install ;;
+    bun)
+      if ! command -v bun >/dev/null; then curl -fsSL https://bun.com/install | bash; export PATH="$HOME/.bun/bin:$PATH"; fi
+      bun install ;;
+    *) echo "Unsupported package manager: $manager" >&2; exit 1 ;;
+  esac
+fi
+
+source_dir=$(mktemp -d)
+trap 'rm -rf "$source_dir"' EXIT
+if ! git clone --depth 1 https://github.com/snappedly/skills.git "$source_dir/repo"; then
+  echo "Could not install Snappedly skills; agent work has not started." >&2
+  exit 1
+fi
+
+mkdir -p "$HOME/.agents/skills" "$HOME/.claude/skills"
+while IFS= read -r -d '' skill_file; do
+  skill_dir=${skill_file%/SKILL.md}
+  skill_name=${skill_dir##*/}
+  rm -rf "$HOME/.agents/skills/$skill_name" "$HOME/.claude/skills/$skill_name"
+  cp -R "$skill_dir" "$HOME/.agents/skills/$skill_name"
+  ln -sfn "$HOME/.agents/skills/$skill_name" "$HOME/.claude/skills/$skill_name"
+done < <(find "$source_dir/repo/skills" -name SKILL.md -print0)
+
+for skill in triage implement implement-spec code-cleanup code-review tdd; do
+  if [[ ! -s "$HOME/.agents/skills/$skill/SKILL.md" || -z $(find "$source_dir/repo/skills" -path "*/$skill/SKILL.md" -print -quit) ]]; then
+    echo "Snappedly skill installation incomplete: $skill" >&2
+    exit 1
+  fi
+done

package/dist/templates/parallel-planner-with-review/spec-wave-prompt.md

@@ -0,0 +1,16 @@
+# Integrate this planning spec dependency wave
+
+The selected template has assigned `/implement` workers to child tickets. Their branches for this wave are `{{WAVE_BRANCHES}}`. The integration branch is `{{BRANCH}}` for planning spec #{{TASK_ID}}. The workflow cherry-picked their committed work into this isolated sandbox.
+
+Follow `/implement-spec` as the whole-spec integrator. Read the complete parent and child issues with comments, repository guidance, and dependency links. Inspect the current branch and ensure every ready ticket in this wave is integrated. If a child branch or cherry-pick was missing, stop and report it. Preserve each ticket's acceptance criteria. Run affected checks, commit corrections, and self-check. Do not create a PR, merge to the target branch, close issues, or start another orchestration chain. Later waves and the selected template's final review stage remain with the surrounding workflow.
+
+If integration or checks fail, report the blocker without a completion marker. Only after this wave is committed and verified, report its integrated tickets, commits, `Checks: <commands and results>`, and limitations:
+
+<handoff>...</handoff>
+<promise>COMPLETE</promise>
+
+## Resolved spec scope
+
+```json
+{{SCOPE}}
+```

package/dist/templates/parallel-planner-with-review/template.json

@@ -1,4 +1,4 @@
 {
   "name": "parallel-planner-with-review",
-  "description": "Plans parallelizable issues, executes with per-branch review, merges"
+  "description": "Plans and implements independent issues in parallel with review, then opens PRs"
 }

package/dist/templates/parallel-planner-with-review/triage-prompt.md

@@ -0,0 +1,5 @@
+Triage GitHub issue #{{TASK_ID}} before Shipyard implementation.
+
+Follow `/triage` and the repository's `docs/agents/triage.md` label mapping. Read the full issue and comments, verify its claim against the codebase, then apply the appropriate category and state label and post the brief or triage notes required by the skill. The maintainer has authorized Shipyard to apply an evidence-based recommendation during this unattended intake. If a decision requires maintainer judgment, use `needs-triage` and record the question. Do not implement the issue or start a PR in this phase.
+
+Report the applied state and evidence. Shipyard will independently re-read GitHub labels and implement only an open issue carrying both `shipyard` and the sole triage state `ready-for-agent`.

package/dist/templates/parallel-planner-with-review/verify-triage.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+issue=${1:?issue number required}
+repo=${2:?GitHub repository required}
+[[ "$issue" =~ ^[0-9]+$ ]] || { echo "Invalid issue number" >&2; exit 1; }
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+
+gh issue view "$issue" --repo "$repo" --json state,labels |
+  node -e '
+    const issue = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
+    const labels = new Set(issue.labels.map((label) => label.name));
+    const states = ["needs-triage", "needs-info", "ready-for-agent", "ready-for-human", "wontfix"];
+    if (issue.state !== "OPEN" || !labels.has("shipyard") ||
+        states.filter((state) => labels.has(state)).join() !== "ready-for-agent") {
+      console.error("Issue cannot be implemented: requires an open issue with shipyard and only ready-for-agent as its triage state");
+      process.exit(1);
+    }
+  '

package/dist/templates/sequential-reviewer/block-scope.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=${1:?scope root required}
+failed=${2:?failed issue required}
+repo=${3:?GitHub repository required}
+scope=${4:?scope issue numbers required}
+branch=${5:-shipyard/issue-$root}
+[[ "$root" =~ ^[0-9]+$ && "$failed" =~ ^[0-9]+$ ]] || { echo "Invalid issue number" >&2; exit 1; }
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$root" || "$scope" == "$root,"* ) && ",$scope," == *",$failed,"* ]] || {
+  echo "Invalid blocked issue scope" >&2; exit 1;
+}
+[[ "$branch" == "shipyard/issue-$root" || "$branch" == "shipyard/spec-$root" ]] || { echo "Invalid scope branch" >&2; exit 1; }
+reason=$(cat)
+[[ -n "$reason" ]] || { echo "Missing failure reason" >&2; exit 1; }
+reason_hash=$(printf '%s' "$reason" | git hash-object --stdin)
+pending_dir=$(git rev-parse --git-path shipyard-pending)
+mkdir -p "$pending_dir"
+umask 077
+pending_file="$pending_dir/$root-$failed.pending"
+trap 'rm -f "${pending_tmp:-}"' EXIT
+confirmed=""
+if [[ -f "$pending_file" ]]; then
+  IFS=$'\t' read -r old_root old_failed old_repo old_scope old_branch old_confirmed < "$pending_file"
+  if [[ "$old_root" == "$root" && "$old_failed" == "$failed" && "$old_repo" == "$repo" && "$old_scope" == "$scope" && "$old_branch" == "$branch" ]]; then
+    confirmed=${old_confirmed:-}
+  fi
+fi
+write_pending() {
+  pending_tmp=$(mktemp "$pending_file.XXXXXX")
+  printf '%s\t%s\t%s\t%s\t%s\t%s\n%s' "$root" "$failed" "$repo" "$scope" "$branch" "$confirmed" "$reason" > "$pending_tmp"
+  mv "$pending_tmp" "$pending_file"
+}
+confirm_blocked() {
+  if [[ ",$confirmed," != *",$1,"* ]]; then
+    confirmed=${confirmed:+$confirmed,}$1
+    write_pending
+  fi
+}
+write_pending
+
+remove_issue_status() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1" >&2
+    return 75
+  fi
+}
+remove_pr_status() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1" >&2
+    return 75
+  fi
+}
+comment_once() {
+  local comments
+  if comments=$(gh issue view "$1" --repo "$repo" --json comments --jq '.comments[].body'); then
+    if grep -Fq "$3" <<< "$comments"; then return 0; fi
+  fi
+  gh issue comment "$1" --repo "$repo" --body "$2"
+}
+
+gh label create shipyard:blocked --repo "$repo" --color B60205 --description 'Shipyard work needs intervention' --force
+status_synced=true
+IFS=',' read -ra affected_ids <<< "$scope"
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    gh issue edit "$affected_id" --repo "$repo" --add-label shipyard:blocked
+    confirm_blocked "$affected_id"
+  done
+  if ! gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update spec #$root status" >&2
+    status_synced=false
+  fi
+else
+  gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked
+  confirm_blocked "$root"
+fi
+
+status=0
+marker="shipyard:blocked:$root:$failed:$reason_hash"
+comment_once "$failed" "Shipyard could not complete this issue. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:failed -->" "$marker:failed" || status=75
+if [[ "$root" != "$failed" ]]; then
+  comment_once "$root" "Shipyard paused this spec because linked ticket #$failed failed. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to each unfinished ticket.
+
+<!-- $marker:parent -->" "$marker:parent" || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" && "$failed" == "$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    comment_once "$affected_id" "Shipyard could not complete this ticket during the spec attempt. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:ticket:$affected_id -->" "$marker:ticket:$affected_id" || status=75
+  done
+fi
+
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  if ! remove_issue_status "$root" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+  if ! remove_issue_status "$root" shipyard:complete; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+else
+  remove_issue_status "$root" shipyard:outstanding-tasks || status=75
+  remove_issue_status "$root" shipyard:complete || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    remove_issue_status "$affected_id" shipyard:pending || status=75
+  done
+else
+  remove_issue_status "$root" shipyard:pending || status=75
+fi
+
+if ! pr_number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty'); then
+  echo "Warning: could not inspect PR status" >&2
+  status_synced=false
+  pr_number=""
+fi
+if [[ -n "$pr_number" ]]; then
+  if ! gh pr edit "$pr_number" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:complete; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+fi
+if [[ "$status" -eq 0 && "$status_synced" == true ]]; then
+  IFS=',' read -ra scope_ids <<< "$scope"
+  for scope_id in "${scope_ids[@]}"; do
+    labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name')
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard
+    fi
+  done
+  rm -f "$pending_file"
+fi
+exit "$status"

package/dist/templates/sequential-reviewer/handoff.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+issue=${1:?issue number required}
+branch=${2:?branch required}
+base=${3:?target branch required}
+repo=${4:?GitHub repository required}
+scope=${5:-$issue}
+outstanding=${6:--}
+previously_completed=${7:--}
+[[ "$issue" =~ ^[0-9]+$ && ( "$branch" == "shipyard/issue-$issue" || "$branch" == "shipyard/spec-$issue" ) ]] || {
+  echo "Invalid issue or branch for PR handoff" >&2; exit 1;
+}
+[[ "$base" =~ ^[A-Za-z0-9._/-]+$ ]] || {
+  echo "Invalid target branch for PR handoff" >&2; exit 1;
+}
+
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$issue" || "$scope" == "$issue,"* ) ]] || { echo "Invalid PR scope" >&2; exit 1; }
+[[ "$outstanding" == - || "$outstanding" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid outstanding tickets" >&2; exit 1; }
+[[ "$previously_completed" == - || "$previously_completed" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid completed tickets" >&2; exit 1; }
+evidence=$(cat)
+[[ -n "$evidence" ]] || { echo "Missing verification evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Checks:' <<< "$evidence" || { echo "Missing check evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Review:' <<< "$evidence" || { echo "Missing review evidence" >&2; exit 1; }
+[[ -z $(git status --porcelain) ]] || {
+  echo "Uncommitted changes prevent PR handoff" >&2; exit 1;
+}
+base_ref=$(git rev-parse --verify "refs/remotes/origin/$base^{commit}") || {
+  echo "Target branch is unavailable in the sandbox" >&2; exit 1;
+}
+branch_base=$base_ref
+if ! git merge-base --is-ancestor "$base_ref" HEAD; then
+  branch_base=$(git merge-base "$base_ref" HEAD) || {
+    echo "PR branch has no common base with the target branch" >&2; exit 1;
+  }
+fi
+[[ -n $(git log "$branch_base"..HEAD --format=%H) ]] || {
+  echo "No verified commit to publish" >&2; exit 1;
+}
+
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+remove_issue_label() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+remove_pr_label() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+title=$(gh issue view "$issue" --repo "$repo" --json title --jq .title)
+body=$(mktemp)
+trap 'rm -f "$body"' EXIT
+links=""
+implemented=""
+IFS=',' read -ra scope_ids <<< "$scope"
+for scope_id in "${scope_ids[@]}"; do links+="#$scope_id "; done
+for ((i=1; i<${#scope_ids[@]}; i++)); do implemented+="#${scope_ids[i]} "; done
+if [[ "$previously_completed" != - ]]; then
+  IFS=',' read -ra completed_ids <<< "$previously_completed"
+  for completed_id in "${completed_ids[@]}"; do links+="#$completed_id "; implemented+="#$completed_id "; done
+fi
+if [[ "$outstanding" != - ]]; then
+  IFS=',' read -ra outstanding_ids <<< "$outstanding"
+  for outstanding_id in "${outstanding_ids[@]}"; do links+="#$outstanding_id "; done
+fi
+printf 'Source issues: %s\nImplemented tickets: %s\n\n## Verification and review\n\n%s\n\nHuman review and merge required.\n\n<!-- shipyard:verified-handoff -->\n' "$links" "$implemented" "$evidence" > "$body"
+
+# Keep Git credentials inside the disposable sandbox, not in the host worktree.
+git remote set-url origin "https://github.com/$repo.git"
+git -c credential.helper='!gh auth git-credential' push -u origin "HEAD:refs/heads/$branch"
+number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+if [[ -z "$number" ]]; then
+  gh pr create --repo "$repo" --head "$branch" --base "$base" --title "$title" --body-file "$body" --draft
+  number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+fi
+[[ -n "$number" ]] || { echo "PR publication did not return an open PR" >&2; exit 1; }
+gh pr edit "$number" --repo "$repo" --body-file "$body"
+draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft)
+url=$(gh pr view "$number" --repo "$repo" --json url --jq .url)
+[[ -n "$url" ]] || { echo "PR publication did not return a URL" >&2; exit 1; }
+if [[ "$draft" == true ]]; then gh pr ready "$number" --repo "$repo" || true; fi
+if ! current_draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft) ||
+   ! current_state=$(gh pr view "$number" --repo "$repo" --json state --jq .state); then
+  echo "Could not confirm PR readiness; retry publication when GitHub is available" >&2
+  exit 75
+fi
+if [[ "$current_draft" != false || "$current_state" != OPEN ]]; then
+  echo "PR did not become ready for human review" >&2
+  exit 1
+fi
+for ((i=1; i<${#scope_ids[@]}; i++)); do
+  if ! gh issue edit "${scope_ids[i]}" --repo "$repo" --add-label shipyard:complete; then
+    echo "Could not mark ticket #${scope_ids[i]} complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  remove_issue_label "${scope_ids[i]}" shipyard:blocked
+  remove_issue_label "${scope_ids[i]}" shipyard:pending
+done
+status_label=shipyard:complete
+status_color=0E8A16
+status_description='Shipyard work ready for human review'
+if [[ "$outstanding" != - ]]; then
+  status_label=shipyard:outstanding-tasks
+  status_color=FBCA04
+  status_description='Spec has uncompleted tickets'
+  for outstanding_id in "${outstanding_ids[@]}"; do
+    labels=$(gh issue view "$outstanding_id" --repo "$repo" --json labels --jq '.labels[].name') || exit 75
+    if grep -Fxq shipyard:blocked <<< "$labels" && ! grep -Fxq shipyard:complete <<< "$labels"; then
+      status_label=shipyard:blocked
+      status_color=B60205
+      status_description='Shipyard work needs intervention'
+      break
+    fi
+  done
+fi
+status_synced=true
+if ! gh label create "$status_label" --repo "$repo" --color "$status_color" --description "$status_description" --force; then
+  echo "Warning: could not create $status_label" >&2
+  status_synced=false
+fi
+if ! gh issue edit "$issue" --repo "$repo" --add-label "$status_label"; then
+  if [[ "$branch" == "shipyard/issue-$issue" ]]; then
+    echo "Could not mark ticket #$issue complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  echo "Warning: could not update spec #$issue status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_issue_label "$issue" "$stale_label"; then
+      if [[ "$branch" == "shipyard/issue-$issue" ]]; then exit 75; fi
+      echo "Warning: could not clear $stale_label from spec #$issue" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$branch" == "shipyard/issue-$issue" ]]; then remove_issue_label "$issue" shipyard:pending; fi
+if ! gh pr edit "$number" --repo "$repo" --add-label "$status_label"; then
+  echo "Warning: could not update PR #$number status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_pr_label "$number" "$stale_label"; then
+      echo "Warning: could not clear $stale_label from PR #$number" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$status_synced" == true ]]; then
+  for scope_id in "${scope_ids[@]}"; do
+    if ! labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name'); then
+      echo "Warning: could not inspect activation on issue #$scope_id; the next invocation will retry cleanup" >&2
+      continue
+    fi
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard ||
+        echo "Warning: could not remove activation from issue #$scope_id; the next invocation will retry cleanup" >&2
+    fi
+  done
+else
+  echo "Warning: status labels need reconciliation; retaining ticket activation" >&2
+fi
+printf '%s\n' "$url"

package/dist/templates/sequential-reviewer/implement-prompt.md

@@ -1,53 +1,19 @@
-# Context
+# Assigned issue scope
 
-## Open issues
+Implement scope #{{TASK_ID}} ({{ISSUE_TITLE}}) on branch `{{BRANCH}}`.
+Read it with `gh issue view {{TASK_ID}} --comments`. Read `AGENTS.md`, `CONTEXT.md`, `docs/agents/workflow.md`, and relevant ADRs.
 
-!`{{LIST_TASKS_COMMAND}}`
+Follow {{SKILL}} in this sequential-reviewer workflow. For a planning spec, deliver only tickets in `SCOPE.tickets` in dependency order and integrate them on this one branch. Other linked tickets are context; do not implement them. Do not create separate child PRs. Use `/tdd` for changed logic and local `/code-cleanup`. Run required focused checks and typechecking, reinstalling candidate dependencies with `bash .shipyard/setup.sh` after manifest changes. Commit and self-check the implementation. The next stage owns independent `/code-review`; do not start another reviewer, orchestration chain, PR, merge, or issue closure.
 
-The list above has already been filtered to issues ready for work and is the sole source of truth for what work exists. Do not run your own unfiltered query to find more issues — if the list is empty, there is nothing to do.
+If incomplete, report the blocker without a completion marker. After a verified commit, report scope, `Checks: <commands and results>`, and limitations:
 
-## Recent RALPH commits (last 10)
-
-!`git log --oneline --grep="RALPH" -10`
-
-# Task
-
-You are RALPH — an autonomous coding agent working through issues one at a time.
-
-## Priority order
-
-Work on issues in this order:
-
-1. **Bug fixes** — broken behaviour affecting users
-2. **Tracer bullets** — thin end-to-end slices that prove an approach works
-3. **Polish** — improving existing functionality (error messages, UX, docs)
-4. **Refactors** — internal cleanups with no user-visible change
-
-Pick the highest-priority open issue that is not blocked by another open issue.
-
-## Workflow
-
-1. **Explore** — read the issue carefully. Pull in the parent PRD if referenced. Read the relevant source files and tests before writing any code.
-2. **Plan** — decide what to change and why. Keep the change as small as possible.
-3. **Execute** — use RGR (Red → Green → Repeat → Refactor): write a failing test first, then write the implementation to pass it.
-4. **Verify** — read the repository's configured feedback-loop contract and run every applicable check for this change. Use the configured static check and focused behavior tests when they exist; include formatting, build, or broader checks when the contract or change requires them. Fix failures before proceeding.
-5. **Commit** — make a single git commit. The message MUST:
-   - Start with `RALPH:` prefix
-   - Include the task completed and any PRD reference
-   - List key decisions made
-   - List files changed
-   - Note any blockers for the next iteration
-6. **Close** — close the issue with `{{CLOSE_TASK_COMMAND}}` explaining what was done.
-
-## Rules
-
-- Work on **one issue per iteration**. Do not attempt multiple issues in a single iteration.
-- Do not close an issue until you have committed the fix and verified tests pass.
-- Do not leave commented-out code or TODO comments in committed code.
-- If you are blocked (missing context, failing tests you cannot fix, external dependency), leave a comment on the issue and move on — do not close it.
+<handoff>...</handoff>
+<promise>COMPLETE</promise>
 
-# Done
+## Resolved scope
 
-When all actionable issues are complete (or you are blocked on all remaining ones), or the open-issues block at the top of this prompt is empty, output the completion signal:
+```json
+{{SCOPE}}
+```
 
-<promise>COMPLETE</promise>
+Read the complete parent and child issue bodies and comments with `gh issue view`, including repository guidance and dependency links.