Skip to content

leek/agent-skills / skills/implement-spec

implement-spec

Verified

Build a whole spec fast: parallel implementer subagents work the ticket frontier, each in its own worktree, merging onto one integration branch; then one review, one verification pass, and one PR or a stack of PRs.

FileKindSize
SKILL.mdskill md28.9 KB
agents/openai.yamlconfig228 B
references/laravel.mdmarkdown691 B
references/leftovers.mdmarkdown846 B
references/resume-and-gates.mdmarkdown3.5 KB
scripts/screenshots-report.shexecutablescript3.5 KB
scripts/spec-run-state.shexecutablescript5.6 KB
scripts/test-screenshots-report.shexecutablescript3.4 KB
scripts/test-spec-run-state.shexecutablescript7.2 KB
scripts/test-worktree-idle.shexecutablescript2.2 KB
scripts/worktree-idle.shexecutablescript2.1 KB

scripts/spec-run-state.sh

View on GitHub
#!/bin/bash
# Read-only start-of-run facts for implement-spec, so the run does not re-derive them
# from git by hand. Changes nothing.
#
# Usage: spec-run-state.sh <slug> [--default <branch>] [--default-only]
#   Run from the main checkout. <slug> is the spec's directory name under .scratch/ (a
#   trailing slash is dropped). A slug that is empty or ".", starts with "-", or holds "/"
#   or ".." is a usage error (exit 2): it also names the notes directory. Needs jq.
#
# Output: JSON
#   {"slug", "branch", "mode": "fresh"|"resume", "finished": [branches already landed],
#    "integration_worktree": path or "", "notes": dir, "base_sha": sha or "",
#    "decision_sweep_done": true|false, "build_decisions": path or "",
#    "local_default_scratch_only": true|false, "default"}
#   With --default-only (what implement's start-branch.sh reads, so the rule lives here
#   once): only {"default", "local_default_scratch_only"}, with no branch or gh lookup.
#
# - branch: <slug> unless it is finished (origin/<default> contains it and it moved past
#   its recorded base_sha, or its PR merged or closed); then the next unfinished or free
#   <slug>-<n>. "resume" means that branch exists and is unfinished.
# - base_sha (resume only): $notes/base_sha, else the first parent of the branch's first
#   merge on the first-parent line.
# - decision_sweep_done: a committed "Build decisions" ticket in .scratch/<slug>/decisions/
#   and no later commit touching the spec or its tickets.
# - local_default_scratch_only: local <default> is ahead of origin/<default> only by
#   commits touching .scratch/<slug>.

set -e

slug=${1:-}
while [ "${slug%/}" != "$slug" ]; do slug=${slug%/}; done
# The same rule as implement's start-branch.sh: the slug is one directory name.
case "$slug" in
  "" | . | -* | */* | *..*)
    [ -z "$slug" ] || echo "Not a slug (one directory name under .scratch/): $slug" >&2
    echo "Usage: spec-run-state.sh <slug> [--default <branch>] [--default-only]" >&2; exit 2 ;;
esac
shift
default=""
default_only=0
while [ $# -gt 0 ]; do
  case "$1" in
    --default) [ -n "${2:-}" ] || { echo "--default needs a branch" >&2; exit 2; }; default=$2; shift ;;
    --default-only) default_only=1 ;;
    *) echo "Unknown arg: $1" >&2; exit 2 ;;
  esac
  shift
done
command -v jq >/dev/null 2>&1 || { echo "spec-run-state.sh needs jq on PATH" >&2; exit 1; }
if [ -z "$default" ]; then
  default=$(git symbolic-ref --short -q refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||') || true
  [ -n "$default" ] || default=main
fi

bool() { [ "$1" = 1 ] && echo true || echo false; }
has_branch() { git rev-parse --verify -q "refs/heads/$1" >/dev/null; }

scratch_only=0
if git rev-parse --verify -q "refs/heads/$default" >/dev/null && git rev-parse --verify -q "refs/remotes/origin/$default" >/dev/null; then
  ahead=$(git rev-list --count "origin/$default..refs/heads/$default")
  other=$(git log --format=%h "origin/$default..refs/heads/$default" -- . ":!.scratch/$slug")
  [ "$ahead" != 0 ] && [ -z "$other" ] && scratch_only=1
fi

if [ "$default_only" = 1 ]; then
  jq -cn --arg default "$default" --argjson scratch_only "$(bool $scratch_only)" \
    '{default: $default, local_default_scratch_only: $scratch_only}'
  exit 0
fi

# Not --path-format=absolute: that needs Git 2.31, and an older git reads it as a path.
common=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)

# A branch that still sits on its recorded base_sha has no ticket merged yet. It is an
# ancestor of origin/<default> too, but it is a run that stopped early, not one that landed.
not_started() {  # not_started <branch>
  local f="$common/implement-spec/$1/base_sha"
  [ -f "$f" ] && [ "$(tr -d '[:space:]' < "$f")" = "$(git rev-parse "$1")" ]
}

is_finished() {  # is_finished <branch>
  if git merge-base --is-ancestor "$1" "origin/$default" 2>/dev/null && ! not_started "$1"; then return 0; fi
  command -v gh >/dev/null 2>&1 || { echo ">> gh missing: PR state of $1 not checked" >&2; return 1; }
  gh pr list --head "$1" --state all --json state --jq '.[].state' 2>/dev/null | grep -qE '^(MERGED|CLOSED)$'
}

finished='[]'
branch=$slug
mode=fresh
n=1
while has_branch "$branch"; do
  if is_finished "$branch"; then
    finished=$(jq -cn --argjson f "$finished" --arg b "$branch" '$f + [$b]')
    n=$((n + 1)); branch="$slug-$n"
  else
    mode=resume; break
  fi
done

notes="$common/implement-spec/$branch"
wt=""
base=""
if [ "$mode" = resume ]; then
  wt=$(git worktree list --porcelain | awk -v b="refs/heads/$branch" '/^worktree /{ p = substr($0, 10) } $0 == "branch " b { print p; exit }')
  if [ -f "$notes/base_sha" ]; then
    base=$(tr -d '[:space:]' < "$notes/base_sha")
  else
    first=$(git rev-list --first-parent --merges --reverse "origin/$default..$branch" | head -n 1)
    [ -n "$first" ] && base=$(git rev-parse "$first^1")
  fi
fi

sweep=0
bd=""
for f in .scratch/"$slug"/decisions/*.md; do
  [ -f "$f" ] || continue
  head -n 8 "$f" | grep -q 'Build decisions' || continue
  bd=$f
  added=$(git log -1 --diff-filter=A --format=%H -- "$f")
  [ -n "$added" ] || break
  later=$(git log --format=%h "$added..HEAD" -- ".scratch/$slug/spec.md" ".scratch/$slug/tickets")
  [ -n "$later" ] || sweep=1
  break
done

jq -cn --arg slug "$slug" --arg branch "$branch" --arg mode "$mode" --argjson finished "$finished" \
  --arg wt "$wt" --arg notes "$notes" --arg base "$base" --argjson sweep "$(bool $sweep)" \
  --arg bd "$bd" --argjson scratch_only "$(bool $scratch_only)" --arg default "$default" \
  '{slug: $slug, branch: $branch, mode: $mode, finished: $finished, integration_worktree: $wt,
    notes: $notes, base_sha: $base, decision_sweep_done: $sweep, build_decisions: $bd,
    local_default_scratch_only: $scratch_only, default: $default}'
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall