leek/agent-skills / skills/implement-spec
implement-spec
VerifiedBuild 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 28.9 KB |
| agents/openai.yaml | config | 228 B |
| references/laravel.md | markdown | 691 B |
| references/leftovers.md | markdown | 846 B |
| references/resume-and-gates.md | markdown | 3.5 KB |
| scripts/screenshots-report.shexecutable | script | 3.5 KB |
| scripts/spec-run-state.shexecutable | script | 5.6 KB |
| scripts/test-screenshots-report.shexecutable | script | 3.4 KB |
| scripts/test-spec-run-state.shexecutable | script | 7.2 KB |
| scripts/test-worktree-idle.shexecutable | script | 2.2 KB |
| scripts/worktree-idle.shexecutable | script | 2.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}'
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |