Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,13 @@ else (and no label) is built. Change routing in `scripts/super-board-wave-plan.s

Skills call the dispatcher scripts as `.claude/bin/<script>`.

## Workspace boards

A config with `repos` drives several sibling checkouts from one board. `scripts/super-board-workspace.py`
resolves it into one single-repo config per repo, so single-repo scripts stay single-repo: point them
at a resolved config and that checkout. Card identity is `<repo>#<n>`; a bare number is ambiguous.
Claude waves only: Codex lanes and the `claude-p` backend refuse.

## Writing

Commits, PR bodies, tickets and comments in this repo follow
Expand Down
2 changes: 1 addition & 1 deletion install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@ for skill in $PRIMARY_SKILLS $SECONDARY_SKILLS; do
install_skill "$skill" "$SHARED/skills/$skill" || true
done

SCRIPTS="super-board-project-verifier.py super-board-skills-ready.py super-board-calibration.py super-board-verification-ready.py super-board-github-read.py super-board-collect-state.py super-board-run.sh super-board-gh-guard.sh super-board-card.sh super-board-status.py super-board-wave-plan.sh super-board-lane.sh super-board-codex-lane.sh super-board-codex-wave.sh super-board-deps.sh super-board-preflight.sh super-board-merge-gate.sh super-board-merge-policy.py super-board-approval.py super-board-env-check.sh super-board-agents-md.py super-board-settings.py super-board-setup.py super-board-usage.sh super-board-throttle.sh super-board-host.sh super-board-pr-body.sh super-review-file-refactor.sh super-qa-file-bug.sh super-board-stop.sh"
SCRIPTS="super-board-workspace.py super-board-project-verifier.py super-board-skills-ready.py super-board-calibration.py super-board-verification-ready.py super-board-github-read.py super-board-collect-state.py super-board-run.sh super-board-gh-guard.sh super-board-card.sh super-board-status.py super-board-wave-plan.sh super-board-lane.sh super-board-codex-lane.sh super-board-codex-wave.sh super-board-deps.sh super-board-preflight.sh super-board-merge-gate.sh super-board-merge-policy.py super-board-approval.py super-board-env-check.sh super-board-agents-md.py super-board-settings.py super-board-setup.py super-board-usage.sh super-board-throttle.sh super-board-host.sh super-board-pr-body.sh super-review-file-refactor.sh super-qa-file-bug.sh super-board-stop.sh"
for script in $SCRIPTS; do
if [ -f "$REPO_ROOT/scripts/$script" ]; then
copy_file "$REPO_ROOT/scripts/$script" "$SHARED/bin/$script"
Expand Down
5 changes: 3 additions & 2 deletions scripts/super-board-card.sh
Original file line number Diff line number Diff line change
Expand Up @@ -141,11 +141,12 @@ read_card() { # $1 = issue; sets ITEM_ID STATUS_NAME
[ -n "$node" ] || { echo "#$1 is not on project $OWNER/$NUMBER" >&2; return 3; }
ITEM_ID=$(echo "$node" | jq -r .id)
STATUS_NAME=$(echo "$node" | jq -r '.fieldValueByName.name // ""')
cache_put '.items[$k] = $v' --arg k "$1" --arg v "$ITEM_ID"
# Keyed by repo: one board spans repos on a workspace, and #12 exists in each.
cache_put '.items[$k] = $v' --arg k "$REPO#$1" --arg v "$ITEM_ID"
}

item_id() { # $1 = issue
ITEM_ID=$(cache_get ".items[\"$1\"]")
ITEM_ID=$(cache_get ".items[\"$REPO#$1\"]")
[ -n "$ITEM_ID" ] || read_card "$1"
}

Expand Down
3 changes: 3 additions & 0 deletions scripts/super-board-codex-wave.sh
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@ launcher = Path(sys.argv[1]).resolve().with_name('super-board-lane.sh')
try:
config_path = Path(args.config).resolve()
config = json.loads(config_path.read_text())
if isinstance(config, dict) and ('repos' in config or 'workspace' in config):
print('Codex waves do not support workspace boards yet: use a Claude host.', file=sys.stderr)
sys.exit(78)
cards = json.loads(args.cards if args.cards.lstrip().startswith('[') else Path(args.cards).read_text())
if not isinstance(config, dict) or not isinstance(cards, list):
raise ValueError('config must be an object; cards must be an array')
Expand Down
44 changes: 41 additions & 3 deletions scripts/super-board-deps.sh
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,16 @@
# "runnable" on an ambiguous line is how a card gets built against a base branch
# that does not have what it needs yet — one wave saved, one rewrite spent.
#
# CROSS-REPO BLOCKERS (workspace boards only). Given --workspace-open and --aliases,
# a blocker may name another repo in the workspace: `- acme-api#12 — why` or
# `blocked-by: 32, acme/acme-api#12`. It appears in `blockers` as a
# lower-case "owner/name#12" string; same-repo blockers stay plain numbers. A repo the
# workspace does not know is `parseable: false`. Without these flags a qualified ref
# stays unreadable, exactly as before.
#
# Usage:
# super-board-deps.sh --repo <owner/name> [--issues 12,34] [--from <payload.json>]
# [--workspace-open <open-refs.json> --aliases <json>]
#
# Stdout, one object keyed by issue number:
# { "40": { "number": 40, "title": "…", "state": "OPEN",
Expand All @@ -60,13 +68,15 @@
set -euo pipefail

HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
REPO=""; LIMIT="200"; ONLY=""; FROM=""
REPO=""; LIMIT="200"; ONLY=""; FROM=""; WS_OPEN="null"; ALIASES="{}"
while [ $# -gt 0 ]; do
case "$1" in
--repo) REPO="$2"; shift 2 ;;
--limit) LIMIT="$2"; shift 2 ;;
--issues) ONLY="$2"; shift 2 ;;
--from) FROM="$2"; shift 2 ;; # a saved `gh issue list --json …` payload; tests use this
--workspace-open) WS_OPEN=$(cat "$2"); shift 2 ;;
--aliases) ALIASES="$2"; shift 2 ;;
*) echo "unknown arg: $1" >&2; exit 64 ;;
esac
done
Expand Down Expand Up @@ -95,7 +105,8 @@ fi

APPROVAL_REPO="$REPO"
[ -z "$FROM" ] || APPROVAL_REPO=""
echo "$ISSUES" | jq --arg only "$ONLY" '
SELF=$(printf '%s' "$REPO" | tr '[:upper:]' '[:lower:]')
echo "$ISSUES" | jq --arg only "$ONLY" --arg self "$SELF" --argjson wsopen "$WS_OPEN" --argjson aliases "$ALIASES" '
# ---- the parser ---------------------------------------------------------
# Everything after the LAST "## Blocked by" heading, stopping at the next
# "## " heading so a following section is never swallowed.
Expand All @@ -118,6 +129,24 @@ echo "$ISSUES" | jq --arg only "$ONLY" '
def refs: [ .[] | select(test("^[ \t]*-[ \t]*#[0-9]+"))
| capture("^[ \t]*-[ \t]*#(?<n>[0-9]+)").n | tonumber ];

# Workspace boards: a blocker token becomes a number (this repo), a lower-case
# "owner/name#n" (another repo), or null (unreadable, or a repo not in the workspace).
def canon:
. as $t
| if test("^[0-9]+$") then tonumber
elif $wsopen == null then null
else ( ($t | capture("^(?<r>[A-Za-z0-9_./-]+)#(?<n>[0-9]+)$")) // null ) as $c
| if $c == null then null
else $aliases[$c.r | ascii_downcase] as $full
| if $full == null then null
elif $full == $self then ($c.n | tonumber)
else "\($full)#\($c.n)" end
end
end;
def qualified: if $wsopen == null then [] else
[ .[] | select(test("^[ \t]*-[ \t]*[A-Za-z0-9_./-]+#[0-9]+"))
| capture("^[ \t]*-[ \t]*(?<t>[A-Za-z0-9_./-]+#[0-9]+)").t ] end;

# A BULLET that claims None while naming an issue is the landmine of 2026-08-20.
# Restricted to bullets on purpose: a blockquote underneath may legitimately
# explain why a past blocker no longer applies, and naming it there is history,
Expand Down Expand Up @@ -160,6 +189,8 @@ echo "$ISSUES" | jq --arg only "$ONLY" '
{ parseable: true, blockers: [], human_gated: true, why: "" }
elif ($v | test("^[0-9]+(,[0-9]+)*$")) then
{ parseable: true, blockers: ($v / "," | map(tonumber)), human_gated: false, why: "" }
elif $wsopen != null and ($v / "," | map(canon) | all(. != null)) then
{ parseable: true, blockers: ($v / "," | map(canon)), human_gated: false, why: "" }
else
{ parseable: false, blockers: [], human_gated: false,
why: ("the `blocked-by:` line reads \"" + $v + "\" — it must be issue numbers alone, or `-`") }
Expand All @@ -173,6 +204,11 @@ echo "$ISSUES" | jq --arg only "$ONLY" '
elif ($sec | none_but_names) then
{ parseable: false, blockers: ($sec | refs), human_gated: false,
why: "the section says None and then names an issue — a planner reads no blocker, a human reads one" }
elif ($sec | qualified | map(canon) | any(. == null)) then
{ parseable: false, blockers: [], human_gated: false,
why: "`## Blocked by` names a repo that is not in this workspace" }
elif (($sec | qualified) | length) > 0 then
{ parseable: true, blockers: (($sec | refs) + ($sec | qualified | map(canon))), human_gated: false, why: "" }
elif (($sec | refs) | length) > 0 then
{ parseable: true, blockers: ($sec | refs), human_gated: false, why: "" }
elif ($sec | any(.[]; test("^[ \t]*-?[ \t]*[Nn]one"))) then
Expand All @@ -181,7 +217,9 @@ echo "$ISSUES" | jq --arg only "$ONLY" '
{ parseable: false, blockers: [], human_gated: false,
why: "`## Blocked by` section has no `- #N` bullets and no `- None.`" }
end ) as $p
| ( [ $p.blockers[] | select(. as $b | $open | index($b)) ] ) as $stillOpen
| ( [ $p.blockers[] | select(. as $b | if ($b | type) == "string"
then (($wsopen // []) | index($b)) != null
else ($open | index($b)) end) ] ) as $stillOpen
| { number: $i.number, title: $i.title, state: $i.state,
blockers: $p.blockers, openBlockers: $stillOpen,
parseable: $p.parseable,
Expand Down
3 changes: 3 additions & 0 deletions scripts/super-board-github-read.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,9 @@ def halt_path():
# One repo, every worktree: <main checkout>/.claude/super-board/ when the common
# dir is <root>/.git; a submodule's (.git/modules/<path>) is not, so keep it inside.
common = Path(result.stdout.strip())
# A workspace shares one token bucket, so every repo in it shares one halt file.
if common.name == '.git' and (common.parent.parent / '.claude/super-board/workspace').is_file():
return common.parent.parent / '.claude/super-board/github-halt.json'
state = common.parent / '.claude/super-board' if common.name == '.git' else common / 'super-board'
return state / 'github-halt.json'

Expand Down
2 changes: 2 additions & 0 deletions scripts/super-board-lane.sh
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,8 @@ try:
except (OSError, ValueError, AttributeError) as error:
fail(f'Invalid {backend.label} lane input: {error}')
# Without --<backend> this is the usage fallback, and that is opt-in per board.
if 'repos' in config or 'workspace' in config:
fail(f'{backend.label} lanes do not support workspace boards yet: use a Claude host.', 78)
if not explicit and config.get('usage_fallback', 'none') != backend.name:
fail(f'{backend.label} fallback refused: usage_fallback is not "{backend.name}" in {config_path}; pass {flag} for an explicit {backend.label} run.', 78)

Expand Down
8 changes: 4 additions & 4 deletions scripts/super-board-skills-ready.py
Original file line number Diff line number Diff line change
Expand Up @@ -421,9 +421,9 @@ def report(root, host, cards=None, profile=None, lane=None, require=(), home=Non

def hydrate(cards, root):
helper = Path(__file__).with_name('super-board-github-read.py')
def read_issue(number, kind, fields):
def read_issue(number, kind, fields, cwd):
process = subprocess.run([sys.executable, str(helper), '--kind', kind, '--', 'issue', 'view', str(number),
'--json', fields], cwd=root, text=True, capture_output=True)
'--json', fields], cwd=cwd, text=True, capture_output=True)
if process.returncode:
print(process.stderr, file=sys.stderr, end='')
raise SystemExit(process.returncode)
Expand All @@ -432,12 +432,12 @@ def read_issue(number, kind, fields):
if not isinstance(card, dict) or type(card.get('number')) is not int or card['number'] < 1:
raise ValueError('card needs a positive number before issue hydration')
if 'body' not in card:
data = read_issue(card['number'], 'issue', 'number,title,body')
data = read_issue(card['number'], 'issue', 'number,title,body', card.get('repoPath') or root)
if data.get('number') != card['number'] or not isinstance(data.get('body'), str):
raise ValueError('guarded issue hydration returned the wrong issue/body')
card['body'] = data['body']
if 'labels' not in card:
data = read_issue(card['number'], 'json', 'labels')
data = read_issue(card['number'], 'json', 'labels', card.get('repoPath') or root)
if not isinstance(data, dict) or not isinstance(data.get('labels'), list):
raise ValueError('guarded issue hydration returned no labels array')
card['labels'] = data['labels']
Expand Down
32 changes: 29 additions & 3 deletions scripts/super-board-status.py
Original file line number Diff line number Diff line change
Expand Up @@ -384,7 +384,7 @@ def gh(*args: str, check: bool = True) -> str:
items(first:100, after:$after) {
pageInfo { endCursor hasNextPage }
nodes {
content { ... on Issue { number title labels(first:20){nodes{name}} } }
content { ... on Issue { number title repository{nameWithOwner} labels(first:20){nodes{name}} } }
fieldValues(first:8) {
nodes { ... on ProjectV2ItemFieldSingleSelectValue {
name field { ... on ProjectV2SingleSelectField { name } } } }
Expand Down Expand Up @@ -494,21 +494,45 @@ def render_kanban(
return "\n".join(boxes)


def workspace_status(config_path: Path) -> int:
"""A workspace board: one kanban per repo, each read from its own checkout."""
here = Path(__file__).resolve().parent
done = subprocess.run([sys.executable, str(here / "super-board-workspace.py"), "resolve",
"--config", str(config_path)], capture_output=True, text=True)
if done.returncode:
print(done.stderr, file=sys.stderr, end="")
return done.returncode
worst = 0
for name, info in json.loads(done.stdout).items():
print(f"\n── {name} ──")
sys.stdout.flush()
code = subprocess.run([sys.executable, str(Path(__file__).resolve()), "--config", info["configPath"]],
cwd=info["repoPath"]).returncode
worst = worst or code
return worst


def main() -> int:
config_slug = resolve_config_slug(sys.argv)
# `--config <resolved.json>`: one repo of a workspace, run from that checkout.
resolved_path = sys.argv[2] if len(sys.argv) > 2 and sys.argv[1] == "--config" else None
config_slug = Path(resolved_path).stem if resolved_path else resolve_config_slug(sys.argv)
if not valid_slug(config_slug):
print(
f"invalid config slug: {config_slug!r} "
f"(allowed chars: letters, digits, '.', '_', '-')",
file=sys.stderr,
)
return 64
config_path = Path(f".claude/super-board/configs/{config_slug}.json")
config_path = Path(resolved_path or f".claude/super-board/configs/{config_slug}.json")
if not config_path.is_file():
print(f"config not found: {config_path}", file=sys.stderr)
return 66

cfg = json.loads(config_path.read_text())
if "repos" in cfg:
return workspace_status(config_path)
only_repo = (cfg.get("repo") or {}).get("remote", "") if cfg.get("workspace") else ""
only_repo = re.sub(r"^.*github\.com[:/]|\.git$", "", only_repo).lower()
project_owner: str = cfg["project"]["owner"]
project_number: int = int(cfg["project"]["number"])
runs_dir = cfg.get("paths", {}).get("runs_dir", "docs/super-board/runs")
Expand Down Expand Up @@ -548,6 +572,8 @@ def fetch_page(after: str | None) -> dict[str, Any]:
c = n.get("content") or {}
if not c.get("number"):
continue
if only_repo and (c.get("repository") or {}).get("nameWithOwner", "").lower() != only_repo:
continue
items.append({
"number": c["number"],
"title": sanitize_title(c.get("title") or ""),
Expand Down
7 changes: 7 additions & 0 deletions scripts/super-board-verification-ready.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,13 @@ def readiness_error(config):
"""Return a setup error, or None when at least one project command is usable."""
if not isinstance(config, dict):
return "config must be a JSON object"
if isinstance(config.get("repos"), dict):
for name, entry in config["repos"].items():
own = entry.get("verify_commands", config.get("verify_commands")) if isinstance(entry, dict) else None
error = readiness_error({"verify_commands": own})
if error:
return f"repos.{name}: {error}"
return None
commands = config.get("verify_commands")
if not isinstance(commands, list) or any(not isinstance(c, str) for c in commands):
return "verify_commands must be an array of project command strings"
Expand Down
15 changes: 14 additions & 1 deletion scripts/super-board-wave-plan.sh
Original file line number Diff line number Diff line change
Expand Up @@ -74,27 +74,40 @@
# "stranded": [ {"number":44,"title":"…"} ] }
set -euo pipefail

CONFIG=""; ITEMS_FILE=""; DEPS_FILE=""
CONFIG=""; ITEMS_FILE=""; DEPS_FILE=""; NO_CAP=0
while [ $# -gt 0 ]; do
case "$1" in
--config) CONFIG="$2"; shift 2 ;;
--items) ITEMS_FILE="$2"; shift 2 ;;
--deps) DEPS_FILE="$2"; shift 2 ;;
--no-cap) NO_CAP=1; shift ;; # the workspace planner caps after merging repos
*) echo "unknown arg: $1" >&2; exit 64 ;;
esac
done
[ -n "$CONFIG" ] && [ -e "$CONFIG" ] || { echo "config not found: ${CONFIG:-<unset>}" >&2; exit 66; }

# A workspace config (`repos` map) plans one wave across every repo: see
# super-board-workspace.py. A process substitution cannot be read twice, so only a
# real file is probed here; the check after the read refuses one that slipped past.
if [ -f "$CONFIG" ] && jq -e 'has("repos")' "$CONFIG" >/dev/null 2>&1; then
exec python3 "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/super-board-workspace.py" plan --config "$CONFIG" \
${ITEMS_FILE:+--items "$ITEMS_FILE"} ${DEPS_FILE:+--deps "$DEPS_FILE"}
fi

# Read the config ONCE — $CONFIG may be a process substitution (test mode),
# which is a FIFO and cannot be read twice.
CONFIG_JSON=$(cat "$CONFIG")
if echo "$CONFIG_JSON" | jq -e 'has("repos")' >/dev/null 2>&1; then
echo "a workspace config must be a real file: .claude/super-board/configs/<slug>.json" >&2; exit 64
fi
HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
printf '%s\n' "$CONFIG_JSON" | python3 "$HERE/super-board-verification-ready.py" --config -
export SB_REPO_PATH=$(echo "$CONFIG_JSON" | jq -r '.repo.path // "."')
python3 "$HERE/super-board-github-read.py" --check
VARIANT=$(echo "$CONFIG_JSON" | jq -r '.variant // ""')
# 0 or absent = unlimited. A wave is sized by the dependency graph, not a knob.
MAX_WORKERS=$(echo "$CONFIG_JSON" | jq -r '.max_workers // 0')
[ "$NO_CAP" = 0 ] || MAX_WORKERS=0
OWNER=$(echo "$CONFIG_JSON" | jq -r '.project.owner')
NUMBER=$(echo "$CONFIG_JSON" | jq -r '.project.number')

Expand Down
Loading