Skip to content

akunzai/agent-skills / skills/setup-agent-ready-repo

setup-agent-ready-repo

Unverified

Set up a repository so agents can file tickets, open pull or merge requests, and verify their own changes.

scripts/install-templates.sh

View on GitHub
#!/usr/bin/env bash
set -euo pipefail

# Copies this skill's document templates into a target repository, and checks
# installed documents for what an instruction cannot prevent: an unresolved
# <angle placeholder>, a guarantee the current
# templates pin that the document no longer carries, and an @path file
# reference in any docs/agents/*.md.
#
# Copying is the point. A model asked to write a document from a template
# regenerates it, rewording the sentences guarantees.tsv matches. Copying the
# bytes and editing the placeholders in place keeps them.

usage() {
  cat >&2 <<'USAGE'
usage: install-templates.sh --forge <github|gitlab|none> [--force] [DIR]
       install-templates.sh --check [DIR]

  --forge   which ticket document to install beside verification.md:
            github writes pull-request.md, gitlab writes merge-request.md,
            none writes verification.md alone (no remote)
  --force   overwrite a destination that already exists
  --check   scan installed documents for unresolved placeholders,
            guarantees the current templates pin but the document lost, and
            @path file references in any docs/agents/*.md;
            exits non-zero when it finds any
  DIR       repository root (default: current directory)
USAGE
}

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
TEMPLATES="$SKILL_DIR/assets/templates"
GUARANTEES="$SKILL_DIR/assets/guarantees.tsv"

FORGE=""
MODE="install"
FORCE=false
DIR=""

while [ $# -gt 0 ]; do
  case "$1" in
    --forge)
      [ $# -ge 2 ] || { echo "--forge needs a value" >&2; usage; exit 2; }
      FORGE="$2"
      shift
      ;;
    --check) MODE="check" ;;
    --force) FORCE=true ;;
    -h|--help) usage; exit 0 ;;
    -*) echo "unknown option: $1" >&2; usage; exit 2 ;;
    *)
      if [ -n "$DIR" ]; then
        echo "unexpected argument: $1" >&2
        usage
        exit 2
      fi
      DIR="$1"
      ;;
  esac
  shift
done

DIR="${DIR:-.}"
[ -d "$DIR" ] || { echo "not a directory: $DIR" >&2; exit 2; }
DIR="$(cd "$DIR" && pwd)"
DEST="$DIR/docs/agents"

# Markdown hard-wraps prose and indents continuation lines, so a guarantee
# spanning more than a few words straddles a line break and picks up the
# indentation with it. Fold to one line and squeeze the runs, or where the wrap
# happens to fall decides whether a pattern is found.
fold_prose() {
  tr '\n' ' ' | tr -s '[:space:]' ' '
}

# Reports a guarantee the current templates pin that this document no longer
# carries. The document keeps whatever the repo edited into it; what is
# reported is the guarantee, and where in the template to read the original.
check_guarantees() {
  local target=$1 kind=$2 found=0 doc name pattern origin folded
  folded="$(fold_prose < "$target")"
  while IFS=$'\t' read -r doc name pattern origin; do
    case "$doc" in \#*|"") continue ;; esac
    [ "$doc" = "$kind" ] || continue
    printf '%s' "$folded" | grep -qiE "$pattern" && continue
    printf 'BEHIND      %s no longer carries %s\n            template: %s   looked for: /%s/\n' \
      "${target#"$DIR"/}" "$name" "$origin" "$pattern"
    found=1
  done < "$GUARANTEES"
  return "$found"
}

# An @ file reference is '@' plus a repo-relative path. Copilot CLI and
# Claude Code expand those when the document is read. @me, @user, npm
# scopes (@types/node), emails (user@host), and owner/action@vN are not
# paths: emails and action pins have an alnum before '@', and a scope
# has a slash but no file extension and no matching path in the repo.
is_at_file_ref() {
  local path=$1 last rel
  path="${path%.}"
  path="${path%,}"
  [ -n "$path" ] || return 1
  last="${path##*/}"
  case "$path" in
    */*)
      case "$last" in
        *.*) return 0 ;;
      esac
      rel="${path#./}"
      [ -e "$DIR/$rel" ]
      ;;
    *.*)
      return 0
      ;;
    *)
      return 1
      ;;
  esac
}

check_at_path_refs() {
  # A per-line `< <(...)` process substitution crashes bash 3.2 (exit
  # 133/139, no output) after a few hundred lines: each iteration leaks a
  # subshell/fd that the interpreter never reclaims. Prefixing every line
  # with a space (so a line-leading @ref still matches the "non-alnum
  # before @" rule) and running grep -n once over the whole file keeps the
  # same match set and line numbers in a single process substitution.
  local file=$1 rel=${1#"$DIR"/} found=0 lineno raw path
  while IFS=: read -r lineno raw; do
    [ -n "$raw" ] || continue
    path="${raw#*@}"
    path="${path%.}"
    path="${path%,}"
    if is_at_file_ref "$path"; then
      printf 'ATPATH      %s:%s @%s\n' "$rel" "$lineno" "$path"
      found=1
    fi
  done < <(sed 's/^/ /' "$file" | grep -noE '[^A-Za-z0-9]@[A-Za-z0-9._/-]+' || true)
  return "$found"
}

check_docs() {
  local found=0 f leftover kind
  for f in "$DEST/issue-tracker.md" "$DEST/pull-request.md" \
           "$DEST/merge-request.md" "$DEST/verification.md"; do
    [ -f "$f" ] || continue
    # A placeholder inside a sample command (`gh issue view <number>`) is not a
    # template artefact; a bare <language> or an alternation such as
    # <gh | glab> is. `placeholder:...` and a ```placeholder fence are the
    # reserved marker for everything else that still needs a real value:
    # unlike an <angle> shape, the keyword itself says so, so nothing has to
    # guess whether a given <bracket> is a value to fill in or an example to
    # keep.
    # shellcheck disable=SC2016  # backticks are literal, not command substitution
    leftover=$(grep -oE '<language>|<[^<>]+ \| [^<>]+>|`placeholder:[^`]*`|^```placeholder$' "$f" | head -n 1 || true)
    if [ -n "$leftover" ]; then
      printf 'PLACEHOLDER %s still carries %s\n' "${f#"$DIR"/}" "$leftover"
      found=1
    fi
    case "$(basename "$f")" in
      pull-request.md|merge-request.md) kind=request ;;
      *) kind="$(basename "$f" .md)" ;;
    esac
    check_guarantees "$f" "$kind" || found=1
  done
  if [ -d "$DEST" ]; then
    for f in "$DEST"/*.md; do
      [ -f "$f" ] || continue
      check_at_path_refs "$f" || found=1
    done
  fi
  if [ "$found" -eq 0 ]; then
    echo "documents carry no unresolved placeholder, no @path file reference,"
    echo "and are level with every guarantee the current templates pin"
  fi
  return "$found"
}

install_one() {
  local src="$1" dst="$2"
  [ -f "$src" ] || { echo "missing template: $src" >&2; exit 2; }
  if [ -e "$dst" ] && [ "$FORCE" != true ]; then
    printf 'skip  %s already exists\n' "${dst#"$DIR"/}"
    return 0
  fi
  cp "$src" "$dst"
  printf 'copy  %s\n' "${dst#"$DIR"/}"
}

if [ "$MODE" = check ]; then
  check_docs
  exit $?
fi

case "$FORGE" in
  github|gitlab|none) ;;
  "") echo "--forge is required to install" >&2; usage; exit 2 ;;
  *) echo "unknown forge: $FORGE" >&2; usage; exit 2 ;;
esac

mkdir -p "$DEST"
install_one "$TEMPLATES/verification.md" "$DEST/verification.md"
case "$FORGE" in
  github)
    install_one "$TEMPLATES/issue-tracker.md" "$DEST/issue-tracker.md"
    install_one "$TEMPLATES/pull-request.md" "$DEST/pull-request.md"
    ;;
  gitlab)
    install_one "$TEMPLATES/issue-tracker.md" "$DEST/issue-tracker.md"
    install_one "$TEMPLATES/pull-request.md" "$DEST/merge-request.md"
    ;;
esac

echo "Now edit the copies in place: replace every <angle placeholder>, delete"
echo "the lines that do not apply, and leave the template's own sentences alone."
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: 472kUpdated 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