@codebehind/agent-workflow 1.0.0

package/templates/scripts/agent/ensure-codebase.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="${1:-.}"
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+CODEBASE_FILE="$REPO_ROOT/.agent-workflow/codebase.md"
+
+if [[ -f "$CODEBASE_FILE" && -s "$CODEBASE_FILE" ]]; then
+  echo "$CODEBASE_FILE already exists"
+  exit 0
+fi
+
+mkdir -p "$(dirname "$CODEBASE_FILE")"
+cat > "$CODEBASE_FILE" <<'EOF'
+# Codebase overview
+
+## Purpose
+Briefly describe what this application does.
+
+## Main areas
+- Backend:
+- Frontend:
+- Persistence:
+- External services:
+
+## Key commands
+- Install:
+- Backend dev:
+- Frontend dev:
+- Tests:
+
+## Important conventions
+- Branching:
+- API patterns:
+- DB / migration patterns:
+- Documentation expectations:
+
+## Notes for future agents
+- Keep this file concise.
+- Update it when architecture or commands materially change.
+EOF
+
+echo "$CODEBASE_FILE created"

package/templates/scripts/agent/git-detect-default-branch.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REMOTE="${1:-origin}"
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  echo "Not inside a git repository" >&2
+  exit 1
+fi
+
+if git symbolic-ref -q --short "refs/remotes/${REMOTE}/HEAD" >/dev/null 2>&1; then
+  git symbolic-ref -q --short "refs/remotes/${REMOTE}/HEAD" | sed "s#^${REMOTE}/##"
+  exit 0
+fi
+
+if git remote show "$REMOTE" >/dev/null 2>&1; then
+  branch="$(git remote show "$REMOTE" | sed -n '/HEAD branch/s/.*: //p' | head -n1)"
+  if [[ -n "$branch" ]]; then
+    echo "$branch"
+    exit 0
+  fi
+fi
+
+for candidate in main master test develop; do
+  if git show-ref --verify --quiet "refs/remotes/${REMOTE}/${candidate}"; then
+    echo "$candidate"
+    exit 0
+  fi
+done
+
+echo "Could not determine default branch for remote ${REMOTE}" >&2
+exit 1

package/templates/scripts/agent/git-find-open-mr.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BRANCH="${1:-$(git rev-parse --abbrev-ref HEAD)}"
+
+glab mr list --source-branch "$BRANCH" --state opened --json iid,web_url,title | jq '.[0] // empty'

package/templates/scripts/agent/git-open-mr.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <title> <description-file> [target-branch]" >&2
+  exit 1
+fi
+
+TITLE="$1"
+DESCRIPTION_FILE="$2"
+TARGET_BRANCH="${3:-$(scripts/agent/git-detect-default-branch.sh origin)}"
+SOURCE_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+
+if existing="$(scripts/agent/git-find-open-mr.sh "$SOURCE_BRANCH")" && [[ -n "$existing" ]]; then
+  IID="$(echo "$existing" | jq -r '.iid')"
+  scripts/agent/git-update-mr.sh "$IID" "$DESCRIPTION_FILE" "$TITLE"
+  exit 0
+fi
+
+glab mr create \
+  --source-branch "$SOURCE_BRANCH" \
+  --target-branch "$TARGET_BRANCH" \
+  --title "$TITLE" \
+  --description-file "$DESCRIPTION_FILE"

package/templates/scripts/agent/git-prepare-worktree.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <spec|task> <slug> [repo_root]" >&2
+  exit 1
+fi
+
+STAGE="$1"
+SLUG="$2"
+REPO_ROOT="${3:-$(pwd)}"
+
+case "$STAGE" in
+  spec) BRANCH="agent/spec/${SLUG}"; WT_NAME="spec-${SLUG}" ;;
+  task) BRANCH="agent/task/${SLUG}"; WT_NAME="task-${SLUG}" ;;
+  *) echo "Stage must be 'spec' or 'task'" >&2; exit 1 ;;
+esac
+
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+cd "$REPO_ROOT"
+
+REPO_NAME="$(basename "$REPO_ROOT")"
+RUN_ROOT="${HOME}/agent-runs/${REPO_NAME}"
+WORKTREE_DIR="${RUN_ROOT}/worktrees/${WT_NAME}"
+DEFAULT_BRANCH="$(${REPO_ROOT}/scripts/agent/git-detect-default-branch.sh origin)"
+
+mkdir -p "${RUN_ROOT}/worktrees"
+
+git fetch origin --prune
+
+if git worktree list --porcelain | awk '/^worktree /{print $2}' | grep -Fxq "$WORKTREE_DIR"; then
+  if [[ -d "$WORKTREE_DIR" ]]; then
+    echo "Syncing existing worktree with origin/${DEFAULT_BRANCH}..." >&2
+    git -C "$WORKTREE_DIR" rebase "origin/${DEFAULT_BRANCH}"
+    echo "WORKTREE_DIR=${WORKTREE_DIR}"
+    exit 0
+  else
+    git worktree prune
+  fi
+fi
+
+if git show-ref --verify --quiet "refs/heads/${BRANCH}"; then
+  git branch -D "$BRANCH"
+fi
+
+rm -rf "$WORKTREE_DIR"
+git worktree add "$WORKTREE_DIR" -b "$BRANCH" "origin/${DEFAULT_BRANCH}"
+
+cat <<OUT
+WORKTREE_DIR=${WORKTREE_DIR}
+BRANCH=${BRANCH}
+DEFAULT_BRANCH=${DEFAULT_BRANCH}
+
+OUT

package/templates/scripts/agent/git-push-branch.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REMOTE="${1:-origin}"
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+
+if [[ "$BRANCH" == "HEAD" ]]; then
+  echo "Detached HEAD; cannot push" >&2
+  exit 1
+fi
+
+git push -u "$REMOTE" "$BRANCH"

package/templates/scripts/agent/git-update-mr.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IID="${1:-}"
+DESCRIPTION_FILE="${2:-}"
+TITLE="${3:-}"
+
+if [[ -z "$IID" ]]; then
+  existing="$(scripts/agent/git-find-open-mr.sh)"
+  IID="$(echo "$existing" | jq -r '.iid // empty')"
+fi
+
+if [[ -z "$IID" ]]; then
+  echo "No open MR found for current branch" >&2
+  exit 1
+fi
+
+args=(mr update "$IID")
+
+if [[ -n "$TITLE" ]]; then
+  args+=(--title "$TITLE")
+fi
+
+if [[ -n "$DESCRIPTION_FILE" && "$DESCRIPTION_FILE" != "-" ]]; then
+  args+=(--description-file "$DESCRIPTION_FILE")
+fi
+
+glab "${args[@]}"

package/templates/scripts/agent/implement-task.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <slug> <spec_name>" >&2
+  exit 1
+fi
+
+SLUG="$1"
+SPEC_NAME="$2"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+echo "Preparing task worktree for '${SLUG}'..." >&2
+OUTPUT=$(bash "${REPO_ROOT}/scripts/agent/git-prepare-worktree.sh" task "${SLUG}" "${REPO_ROOT}")
+WORKTREE_DIR=$(echo "${OUTPUT}" | grep '^WORKTREE_DIR=' | cut -d= -f2-)
+
+echo "Worktree: ${WORKTREE_DIR}" >&2
+cd "${WORKTREE_DIR}"
+exec claude --dangerously-skip-permissions -p "use implement-spec skill from ${SPEC_NAME}"

package/templates/scripts/agent/mr-template.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 5 ]]; then
+  echo "Usage: $0 <spec|task> <spec-path|-> <plan-path|-> <doc-path|-> <artifacts-path|->" >&2
+  exit 1
+fi
+
+MODE="$1"
+SPEC_PATH="$2"
+PLAN_PATH="$3"
+DOC_PATH="$4"
+ARTIFACTS_PATH="$5"
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+COMMIT_SHA="$(git rev-parse --short HEAD)"
+
+cat <<EOF2
+## Summary
+- Workflow mode: ${MODE}
+- Branch: ${BRANCH}
+- Commit: ${COMMIT_SHA}
+
+## Paths
+- Spec: ${SPEC_PATH}
+- Plan: ${PLAN_PATH}
+- Docs: ${DOC_PATH}
+- Artifacts: ${ARTIFACTS_PATH}
+
+## Notes for review
+- Review only the files relevant to this workflow stage.
+- Spec branches should normally contain spec/assets/docs-only changes.
+- Task branches may contain plan, implementation, verification artifacts, and related docs updates.
+EOF2

package/templates/scripts/agent/post-run-summary.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 4 ]]; then
+  echo "Usage: $0 <spec_path> <plan_path> <docs_path> <artifacts_path>" >&2
+  exit 1
+fi
+
+SPEC_PATH="$1"
+PLAN_PATH="$2"
+DOCS_PATH="$3"
+ARTIFACTS_PATH="$4"
+
+cat <<EOF
+## Agent run summary
+- Spec: \
+$SPEC_PATH
+- Plan: \
+$PLAN_PATH
+- Docs: \
+$DOCS_PATH
+- Artifacts: \
+$ARTIFACTS_PATH
+EOF

package/templates/scripts/agent/prepare-spec.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: $0 <slug> <notion_url>" >&2
+  exit 1
+fi
+
+SLUG="$1"
+NOTION_URL="$2"
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+echo "Preparing spec worktree for '${SLUG}'..." >&2
+OUTPUT=$(bash "${REPO_ROOT}/scripts/agent/git-prepare-worktree.sh" spec "${SLUG}" "${REPO_ROOT}")
+WORKTREE_DIR=$(echo "${OUTPUT}" | grep '^WORKTREE_DIR=' | cut -d= -f2-)
+
+echo "Worktree: ${WORKTREE_DIR}" >&2
+cd "${WORKTREE_DIR}"
+exec claude --dangerously-skip-permissions -p "use prepare-spec skill from ${NOTION_URL}"

package/templates/scripts/agent/start-worktree.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 3 ]]; then
+  echo "Usage: $0 <repo_root> <base_branch> <spec_slug> [feature_prefix]" >&2
+  exit 1
+fi
+
+REPO_ROOT="$1"
+BASE_BRANCH="$2"
+SPEC_SLUG="$3"
+FEATURE_PREFIX="${4:-feature/agent}"
+
+REPO_ROOT="$(cd "$REPO_ROOT" && pwd)"
+WORKTREE_BASE="$REPO_ROOT/.worktrees"
+BRANCH_NAME="${FEATURE_PREFIX}/${SPEC_SLUG}"
+WORKTREE_PATH="$WORKTREE_BASE/$SPEC_SLUG"
+
+mkdir -p "$WORKTREE_BASE"
+cd "$REPO_ROOT"
+
+git fetch origin "$BASE_BRANCH" --prune
+if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
+  :
+else
+  git branch "$BRANCH_NAME" "origin/$BASE_BRANCH"
+fi
+
+if [[ -d "$WORKTREE_PATH" ]]; then
+  echo "$WORKTREE_PATH"
+  exit 0
+fi
+
+git worktree add "$WORKTREE_PATH" "$BRANCH_NAME" >/dev/null
+
+echo "$WORKTREE_PATH"

package/templates/scripts/agent/verify-acceptance.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <spec_path>" >&2
+  exit 1
+fi
+
+SPEC_PATH="$1"
+REPO_ROOT="$(pwd)"
+
+node "$REPO_ROOT/scripts/agent/prepare-acceptance.mjs" "$SPEC_PATH"