@firatcand/roster 0.1.0 → 0.4.0

package/templates/scaffold/scripts/audit-repo.sh

@@ -0,0 +1,240 @@
+#!/usr/bin/env bash
+# audit-repo.sh — full repo audit; runs project + agent audits, plus repo-level checks
+# Usage: bash scripts/audit-repo.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+source "$ROOT/scripts/lib/functions.sh"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+RUN_TIME=$(date +%Y-%m-%d-%H%M)
+LOG_DIR="$ROOT/chief-of-staff/logs/$(date +%Y-%m)"
+mkdir -p "$LOG_DIR"
+REPORT="$LOG_DIR/audit-repo-$RUN_TIME.md"
+
+REPO_FAILURES=()
+REPO_WARNINGS=()
+REPO_PASSED=()
+
+# === Repo-level checks ===
+
+# Universal .mcp.json
+if [ ! -f "$ROOT/.mcp.json" ]; then
+  REPO_WARNINGS+=("[.mcp.json] universal MCP config missing")
+elif command -v python3 >/dev/null 2>&1; then
+  if ! python3 -c "import json; json.load(open('$ROOT/.mcp.json'))" 2>/dev/null; then
+    REPO_FAILURES+=("[.mcp.json] invalid JSON")
+  else
+    REPO_PASSED+=("[.mcp.json] valid")
+  fi
+fi
+
+# Universal .claude/settings.json
+if [ ! -f "$ROOT/.claude/settings.json" ]; then
+  REPO_WARNINGS+=("[.claude/settings.json] universal settings missing")
+elif command -v python3 >/dev/null 2>&1; then
+  if ! python3 -c "import json; json.load(open('$ROOT/.claude/settings.json'))" 2>/dev/null; then
+    REPO_FAILURES+=("[.claude/settings.json] invalid JSON")
+  else
+    REPO_PASSED+=("[.claude/settings.json] valid")
+  fi
+fi
+
+# Required root files
+for f in CLAUDE.md conventions.md README.md; do
+  if [ ! -f "$ROOT/$f" ]; then
+    REPO_FAILURES+=("[$f] missing at repo root")
+  else
+    REPO_PASSED+=("[$f] present")
+  fi
+done
+
+# Build a regex of registered functions for matching grandparent dirs.
+REGISTERED_FNS_PIPE=$(read_functions 2>/dev/null | tr '\n' '|' | sed 's/|$//')
+
+# Find orphaned instances (instance folder exists but agent doesn't)
+ORPHANS=()
+while IFS= read -r path; do
+  ORPHANS+=("$path")
+done < <(find "$ROOT" -type d -path "*/projects/*" -not -path "*/projects/_template*" -not -path "*/_archive/*" 2>/dev/null | while read p; do
+  PARENT=$(dirname $(dirname "$p"))
+  if [ -d "$PARENT" ] && [ ! -f "$PARENT/agent.md" ]; then
+    # This is a project folder under a non-agent — that's actually projects/ root
+    # We only care about instances: <fn>/<agent>/projects/<proj>/ where agent.md is missing
+    GRANDPARENT=$(dirname "$PARENT")
+    GP_NAME=$(basename "$GRANDPARENT")
+    if [ -n "$REGISTERED_FNS_PIPE" ] && echo "$GP_NAME" | grep -qE "^($REGISTERED_FNS_PIPE)\$"; then
+      echo "$p"
+    fi
+  fi
+done)
+
+for orphan in "${ORPHANS[@]:-}"; do
+  REL="${orphan#$ROOT/}"
+  REPO_WARNINGS+=("[$REL] orphaned instance — parent agent has no agent.md")
+done
+
+# Registered function should have a folder
+while IFS= read -r fn; do
+  [ -z "$fn" ] && continue
+  if [ ! -d "$ROOT/$fn" ]; then
+    REPO_FAILURES+=("[$fn] registered in .config/functions.yaml but folder does not exist")
+    REPO_FAILURES+=("  → Suggested fix: mkdir $fn && cp <stub README>, OR remove from .config/functions.yaml")
+  fi
+done < <(read_functions 2>/dev/null || true)
+
+# has_expert: true → EXPERT.md must exist
+while IFS=$'\t' read -r slug has_expert; do
+  [ -z "$slug" ] && continue
+  if [ "$has_expert" = "true" ] && [ ! -f "$ROOT/$slug/EXPERT.md" ]; then
+    REPO_WARNINGS+=("[$slug/EXPERT.md] registry says has_expert=true but file missing")
+  fi
+done < <(read_functions_with_metadata 2>/dev/null || true)
+
+# HITL channel env vars: every function should have SLACK_HITL_CHANNEL_<FN> in .env.example
+ENV_EXAMPLE="$ROOT/.env.example"
+if [ -f "$ENV_EXAMPLE" ]; then
+  while IFS= read -r fn; do
+    [ -z "$fn" ] && continue
+    var="SLACK_HITL_CHANNEL_$(echo "$fn" | tr '[:lower:]-' '[:upper:]_')"
+    if ! grep -q "^${var}=" "$ENV_EXAMPLE"; then
+      REPO_WARNINGS+=("[.env.example] missing $var (function '$fn' has no HITL channel env var)")
+    fi
+  done < <(read_functions 2>/dev/null || true)
+  if ! grep -q "^SLACK_HITL_CHANNEL_ADMIN=" "$ENV_EXAMPLE"; then
+    REPO_WARNINGS+=("[.env.example] missing SLACK_HITL_CHANNEL_ADMIN (used by dreamer + chief-of-staff)")
+  fi
+fi
+
+# Function-shaped top-level dirs not in the registry
+KNOWN_NON_FUNCTIONS="dreamer chief-of-staff projects scripts logs _archive"
+for dir in "$ROOT"/*/; do
+  basename=$(basename "$dir")
+  [[ "$basename" == .* ]] && continue
+  echo "$KNOWN_NON_FUNCTIONS" | grep -qw "$basename" && continue
+  if [ -n "$REGISTERED_FNS_PIPE" ] && echo "$basename" | grep -qE "^($REGISTERED_FNS_PIPE)\$"; then
+    continue
+  fi
+  if find "$dir" -maxdepth 2 -name 'agent.md' -type f 2>/dev/null | head -1 | grep -q .; then
+    REPO_WARNINGS+=("[$basename/] looks function-shaped but not registered in .config/functions.yaml")
+    REPO_WARNINGS+=("  → Suggested fix: add to registry via 'bash scripts/create-function.sh $basename' (or remove if intended)")
+  fi
+done
+
+# === Run audit-project for each project ===
+PROJECTS=()
+while IFS= read -r path; do
+  PROJECTS+=("$path")
+done < <(find "$ROOT/projects" -maxdepth 1 -mindepth 1 -type d -not -name '_template' 2>/dev/null || true)
+
+PROJECT_RESULTS=()
+for proj_path in "${PROJECTS[@]:-}"; do
+  PROJ=$(basename "$proj_path")
+  RESULT=$(bash "$ROOT/scripts/audit-project.sh" "$PROJ" 2>&1 | head -5 || echo "  (audit failed)")
+  PROJECT_RESULTS+=("### $PROJ")
+  PROJECT_RESULTS+=("\`\`\`")
+  while IFS= read -r line; do
+    PROJECT_RESULTS+=("$line")
+  done <<< "$RESULT"
+  PROJECT_RESULTS+=("\`\`\`")
+  PROJECT_RESULTS+=("")
+done
+
+# === Run audit-agent for each agent ===
+AGENTS=()
+while IFS= read -r fn; do
+  [ -z "$fn" ] && continue
+  if [ -d "$ROOT/$fn" ]; then
+    while IFS= read -r path; do
+      AGENTS+=("$fn:$(basename "$path")")
+    done < <(find "$ROOT/$fn" -maxdepth 1 -mindepth 1 -type d 2>/dev/null || true)
+  fi
+done < <(read_functions 2>/dev/null || true)
+
+AGENT_RESULTS=()
+for entry in "${AGENTS[@]:-}"; do
+  FN="${entry%%:*}"
+  AGENT="${entry##*:}"
+  RESULT=$(bash "$ROOT/scripts/audit-agent.sh" "$FN" "$AGENT" 2>&1 | head -5 || echo "  (audit failed)")
+  AGENT_RESULTS+=("### $FN/$AGENT")
+  AGENT_RESULTS+=("\`\`\`")
+  while IFS= read -r line; do
+    AGENT_RESULTS+=("$line")
+  done <<< "$RESULT"
+  AGENT_RESULTS+=("\`\`\`")
+  AGENT_RESULTS+=("")
+done
+
+# === Status ===
+if [ ${#REPO_FAILURES[@]} -gt 0 ]; then
+  STATUS="fail"
+elif [ ${#REPO_WARNINGS[@]} -gt 0 ]; then
+  STATUS="warn"
+else
+  STATUS="pass"
+fi
+
+# Write report
+{
+  echo "---"
+  echo "operation: audit-repo"
+  echo "ran: $TIMESTAMP"
+  echo "status: $STATUS"
+  echo "---"
+  echo ""
+  echo "# Repo Audit"
+  echo ""
+  echo "## Summary"
+  echo "- Projects audited: ${#PROJECTS[@]}"
+  echo "- Agents audited: ${#AGENTS[@]}"
+  echo "- Repo-level passed: ${#REPO_PASSED[@]}"
+  echo "- Repo-level warnings: ${#REPO_WARNINGS[@]}"
+  echo "- Repo-level failures: ${#REPO_FAILURES[@]}"
+  echo ""
+  if [ ${#REPO_FAILURES[@]} -gt 0 ]; then
+    echo "## Repo-level Failures"
+    for line in "${REPO_FAILURES[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  if [ ${#REPO_WARNINGS[@]} -gt 0 ]; then
+    echo "## Repo-level Warnings"
+    for line in "${REPO_WARNINGS[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  if [ ${#REPO_PASSED[@]} -gt 0 ]; then
+    echo "## Repo-level Passed"
+    for line in "${REPO_PASSED[@]}"; do
+      echo "- $line"
+    done
+    echo ""
+  fi
+  echo "## Project audits (summaries)"
+  echo ""
+  for line in "${PROJECT_RESULTS[@]:-}"; do
+    echo "$line"
+  done
+  echo ""
+  echo "## Agent audits (summaries)"
+  echo ""
+  for line in "${AGENT_RESULTS[@]:-}"; do
+    echo "$line"
+  done
+  echo ""
+  echo "Individual audit reports are in $LOG_DIR/"
+} > "$REPORT"
+
+# Print summary
+echo "Repo audit: $STATUS"
+echo "  Projects: ${#PROJECTS[@]} | Agents: ${#AGENTS[@]}"
+echo "  Repo-level: ${#REPO_PASSED[@]} passed, ${#REPO_WARNINGS[@]} warnings, ${#REPO_FAILURES[@]} failures"
+[ ${#REPO_FAILURES[@]} -gt 0 ] && {
+  echo "Repo failures:"
+  for line in "${REPO_FAILURES[@]}"; do echo "  $line"; done
+}
+echo "Full report: $REPORT"

package/templates/scaffold/scripts/create-function.sh

@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+# create-function.sh — register a new function category and scaffold its folder
+# Usage: bash scripts/create-function.sh <slug> [--description "..."] [--with-expert] [--no-confirm]
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$ROOT/.config/functions.yaml"
+
+source "$ROOT/scripts/lib/functions.sh"
+
+usage() {
+  cat <<EOF
+Usage: $0 <slug> [--description "..."] [--with-expert] [--no-confirm]
+
+  <slug>           required, lowercase kebab-case, ^[a-z][a-z0-9-]*\$
+  --description    one-line description (prompted if omitted in TTY)
+  --with-expert    scaffold EXPERT.md stub and set has_expert: true
+  --no-confirm     skip the interactive proliferation prompt
+
+Environment:
+  AGENT_TEAM_NO_CONFIRM=1   equivalent to --no-confirm
+EOF
+}
+
+if [ $# -lt 1 ]; then
+  usage >&2
+  exit 1
+fi
+
+SLUG=""
+DESCRIPTION=""
+WITH_EXPERT=""        # "" | "true" | "false"; "" means unresolved (will prompt)
+DESC_PROVIDED=0
+NO_CONFIRM=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --description)
+      [ $# -lt 2 ] && { echo "ERROR: --description requires a value" >&2; exit 1; }
+      DESCRIPTION="$2"
+      DESC_PROVIDED=1
+      shift 2
+      ;;
+    --description=*)
+      DESCRIPTION="${1#--description=}"
+      DESC_PROVIDED=1
+      shift
+      ;;
+    --with-expert)
+      WITH_EXPERT="true"
+      shift
+      ;;
+    --no-confirm)
+      NO_CONFIRM=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --*)
+      echo "ERROR: unknown flag '$1'" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      if [ -z "$SLUG" ]; then
+        SLUG="$1"
+        shift
+      else
+        echo "ERROR: unexpected positional arg '$1'" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
+if [ "${AGENT_TEAM_NO_CONFIRM:-0}" = "1" ]; then
+  NO_CONFIRM=1
+fi
+
+if [ -z "$SLUG" ]; then
+  echo "ERROR: <slug> is required" >&2
+  usage >&2
+  exit 1
+fi
+
+# 1. Validate slug format
+if ! [[ "$SLUG" =~ ^[a-z][a-z0-9-]*$ ]]; then
+  echo "ERROR: slug '$SLUG' is invalid. Must be lowercase, start with a letter, and only contain a-z, 0-9, and hyphens." >&2
+  exit 1
+fi
+
+# 2. Check config exists and is parseable
+if [ ! -f "$CONFIG" ]; then
+  echo "ERROR: $CONFIG not found or unreadable" >&2
+  exit 1
+fi
+if ! read_functions >/dev/null 2>&1; then
+  echo "ERROR: failed to read $CONFIG (malformed YAML or unreadable)" >&2
+  read_functions >/dev/null  # re-run to surface stderr
+  exit 1
+fi
+
+# 3. Check slug not already in registry
+if is_valid_function "$SLUG"; then
+  echo "ERROR: function '$SLUG' is already registered in $CONFIG" >&2
+  exit 1
+fi
+
+# 4. Check folder doesn't exist
+TARGET="$ROOT/$SLUG"
+if [ -e "$TARGET" ]; then
+  echo "ERROR: '$TARGET' already exists on disk" >&2
+  exit 1
+fi
+
+# 5. Resolve description
+is_tty() { [ -t 0 ] && [ -t 1 ]; }
+
+if [ $DESC_PROVIDED -eq 0 ]; then
+  if is_tty; then
+    printf "Description (one line, e.g. 'Research — discovery, market analysis'): " >&2
+    IFS= read -r DESCRIPTION
+  fi
+  if [ -z "$DESCRIPTION" ]; then
+    echo "ERROR: --description not provided and not running interactively" >&2
+    exit 1
+  fi
+fi
+
+# Strip trailing whitespace
+DESCRIPTION="${DESCRIPTION%"${DESCRIPTION##*[![:space:]]}"}"
+if [ -z "$DESCRIPTION" ]; then
+  echo "ERROR: description is empty" >&2
+  exit 1
+fi
+
+# 6. Resolve has_expert
+if [ -z "$WITH_EXPERT" ]; then
+  if is_tty; then
+    printf "Does this function need an expert? (y/N): " >&2
+    IFS= read -r ANS
+    case "$ANS" in
+      y|Y|yes|YES) WITH_EXPERT="true" ;;
+      *) WITH_EXPERT="false" ;;
+    esac
+  else
+    WITH_EXPERT="false"
+  fi
+fi
+
+# 7. Soft proliferation reminder
+if [ "$NO_CONFIRM" -eq 0 ] && is_tty; then
+  cat >&2 <<EOF
+About to create function: $SLUG
+Reminder: function categories should map to how you mentally divide work.
+Will you have at least 2-3 agents in this function within ~90 days?
+If not, the agent likely fits an existing function. Press Ctrl-C to abort,
+or any key to proceed.
+EOF
+  read -r -n 1 _ || true
+  echo "" >&2
+fi
+
+# === Mutations begin here ===
+# Track what we created so we can roll back on failure.
+CREATED_PATHS=()
+CONFIG_BACKUP="$(mktemp -t functions-yaml-backup.XXXXXX)" || {
+  echo "ERROR: could not create backup tempfile" >&2
+  exit 1
+}
+cp "$CONFIG" "$CONFIG_BACKUP"
+
+rollback() {
+  echo "Rolling back partial changes..." >&2
+  for p in "${CREATED_PATHS[@]:-}"; do
+    [ -e "$p" ] && rm -rf "$p"
+  done
+  cp "$CONFIG_BACKUP" "$CONFIG"
+}
+trap 'rollback; rm -f "$CONFIG_BACKUP"' ERR
+
+# 8. Append entry to YAML
+{
+  printf '  - slug: %s\n' "$SLUG"
+  printf '    description: %s\n' "$DESCRIPTION"
+  printf '    has_expert: %s\n' "$WITH_EXPERT"
+} >> "$CONFIG"
+
+# 9. Create folder
+mkdir -p "$TARGET"
+CREATED_PATHS+=("$TARGET")
+
+# 10. Stub README.md
+README_PATH="$TARGET/README.md"
+{
+  printf '# Global %s agents\n\n' "$SLUG"
+  printf '%s\n\n' "$DESCRIPTION"
+  printf 'No agents yet. Add via:\n\n'
+  printf '```bash\n'
+  printf 'bash scripts/new-agent.sh %s <agent-name>\n' "$SLUG"
+  printf '```\n\n'
+  printf "When you add the first agent here, see \`gtm/sdr/\` as the canonical example of an agent's directory layout.\n"
+} > "$README_PATH"
+
+# 11. Optional EXPERT.md stub
+if [ "$WITH_EXPERT" = "true" ]; then
+  EXPERT_PATH="$TARGET/EXPERT.md"
+  cat > "$EXPERT_PATH" <<EOF
+# $SLUG Expert
+
+<!--
+This is a stub. Fill in the expert system prompt for this function.
+
+Experts shape SUBSTRATE (project guidelines), not artifacts. They critique
+and generate guideline files in \`projects/<project>/guidelines/\`.
+
+Required sections (see other EXPERT.md files for examples once they exist):
+- Identity (1 paragraph)
+- Scope (guide / critique / generate guidelines)
+- Skill routing (table)
+- Practitioner panel (optional, only if it adds value)
+- Read-first protocol
+- Output rules (what writes where, what doesn't)
+- Stage filter (early-stage constraints)
+
+Keep it concise. Lean on skills rather than restating their content here.
+-->
+
+# Stub: replace with the function's expert system prompt.
+EOF
+fi
+
+# 12. Append to operation log
+LOG_DIR="$ROOT/chief-of-staff/logs/$(date +%Y-%m)"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/operations-$(date +%Y-%m-%d).md"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+{
+  echo ""
+  echo "## $TIMESTAMP — create-function: $SLUG"
+  echo "Description: $DESCRIPTION"
+  echo "has_expert: $WITH_EXPERT"
+} >> "$LOG_FILE"
+
+# Success — disarm rollback trap
+trap - ERR
+rm -f "$CONFIG_BACKUP"
+
+echo ""
+echo "✓ Function '$SLUG' created."
+echo "  Folder:      $TARGET/"
+echo "  README:      $README_PATH"
+[ "$WITH_EXPERT" = "true" ] && echo "  EXPERT.md:   $TARGET/EXPERT.md (stub)"
+echo "  Registry:    $CONFIG (entry appended)"
+echo "  Log:         $LOG_FILE"
+echo ""
+SLUG_ENV=$(echo "$SLUG" | tr '[:lower:]-' '[:upper:]_')
+
+echo "Reminders for the new function:"
+echo "  1. HITL routing — agents in this function will route to #${SLUG}"
+echo "     - Create the Slack channel #${SLUG}"
+echo "     - Add to .env: SLACK_HITL_CHANNEL_${SLUG_ENV}=#${SLUG}"
+[ "$WITH_EXPERT" = "true" ] && echo "  2. Fill in $TARGET/EXPERT.md with the expert system prompt"
+echo "  $([ "$WITH_EXPERT" = "true" ] && echo 3 || echo 2). Add the first agent: bash scripts/new-agent.sh $SLUG <agent-name>"

package/templates/scaffold/scripts/lib/README.md

@@ -1,12 +1,17 @@
 # Shared script libraries
 
-Helper functions for use across scripts. Empty for now — add as scripts grow.
+Helper functions for use across scripts.
 
 Conventions:
 - Bash: `<n>.sh`, sourced via `source "$(dirname $0)/lib/<n>.sh"`
 - Python: `<n>.py` if needed (use `pip install --break-system-packages`)
 - Keep functions narrow
 
+## Current inhabitants
+
+- `functions.sh` — read/validate the function registry at `.config/functions.yaml`. Pure bash + falls back to `python3` + `pyyaml` when available for safer YAML parsing.
+- `bindings-prompt.sh` — interactive prompts for per-tool bindings during `new-agent-instance.sh`. Requires `python3` + `pyyaml` for the YAML output rendering (falls back gracefully when unavailable).
+
 Example future additions:
 - `lib/lesson.sh` — read/write lesson files, validate schema
 - `lib/run.sh` — append to run files, format frontmatter

package/templates/scaffold/scripts/lib/bindings-prompt.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# bindings-prompt.sh — read ## Tools and bindings from agent.md, prompt user, append YAML
+#
+# Args:
+#   $1 = path to agent.md (the global agent contract)
+#   $2 = path to instance config/default.yaml (will append tools: block)
+#
+# Behavior:
+#   1. Extract YAML block from `## Tools and bindings` in agent.md
+#   2. For each tool/key, prompt user via /dev/tty for value (showing required/optional + description)
+#   3. Empty input or "skip" → write `# TODO: <description>` placeholder
+#   4. Append a `tools:` block to the instance config
+#
+# Non-TTY environments fall back to TODO placeholders for every binding.
+
+set -euo pipefail
+
+AGENT_MD="${1:-}"
+INSTANCE_CONFIG="${2:-}"
+
+if [ -z "$AGENT_MD" ] || [ -z "$INSTANCE_CONFIG" ]; then
+  echo "Usage: $0 <agent.md> <instance-config/default.yaml>" >&2
+  exit 1
+fi
+
+if [ ! -f "$AGENT_MD" ]; then
+  echo "ERROR: agent.md not found at $AGENT_MD" >&2
+  exit 1
+fi
+if [ ! -f "$INSTANCE_CONFIG" ]; then
+  echo "ERROR: instance config not found at $INSTANCE_CONFIG" >&2
+  exit 1
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "ERROR: python3 is required for bindings-prompt.sh" >&2
+  exit 1
+fi
+
+# Drive prompts + YAML emission via python; pass file paths via env to avoid quoting hell.
+export AGENT_MD INSTANCE_CONFIG
+
+FINAL_YAML=$(python3 << 'PYEOF'
+import os, re, sys
+
+agent_md = os.environ["AGENT_MD"]
+with open(agent_md) as f:
+    content = f.read()
+
+m = re.search(r'## Tools and bindings.*?\n```yaml\n(.*?)\n```', content, re.DOTALL)
+if not m:
+    sys.stderr.write(f"ERROR: no '## Tools and bindings' YAML block in {agent_md}\n")
+    sys.exit(1)
+
+schema_text = m.group(1)
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("ERROR: pyyaml required (pip3 install --user pyyaml)\n")
+    sys.exit(1)
+
+try:
+    schema = yaml.safe_load(schema_text)
+except Exception as e:
+    sys.stderr.write(f"ERROR parsing bindings schema: {e}\n")
+    sys.exit(1)
+
+if not isinstance(schema, dict):
+    sys.stderr.write("Bindings schema is not a YAML mapping\n")
+    sys.exit(1)
+
+# Try to open /dev/tty for interactive input. Fall back to all-TODO if unavailable.
+try:
+    tty = open("/dev/tty", "r")
+    interactive = True
+except OSError:
+    tty = None
+    interactive = False
+    sys.stderr.write("(non-interactive environment — all bindings will be TODO placeholders)\n")
+
+def yaml_quote(value: str) -> str:
+    if value == "":
+        return '""'
+    if any(c in value for c in [":", "#", "@", "{", "}", "[", "]", ",", "&", "*", "!", "|", ">", "'", '"', "%", "`"]):
+        escaped = value.replace('\\', '\\\\').replace('"', '\\"')
+        return f'"{escaped}"'
+    return value
+
+out_lines = []
+out_lines.append("")
+out_lines.append("# Tool bindings (filled via chief-of-staff scaffolding prompt)")
+out_lines.append("tools:")
+
+for tool, bindings in schema.items():
+    if not isinstance(bindings, dict):
+        continue
+    out_lines.append(f"  {tool}:")
+    for key, meta in bindings.items():
+        if not isinstance(meta, dict):
+            continue
+        required = bool(meta.get("required", False))
+        description = str(meta.get("description", "") or "")
+        marker = "(required)" if required else "(optional)"
+
+        value = ""
+        if interactive:
+            sys.stderr.write(f"\n  {tool}.{key} {marker}\n")
+            sys.stderr.write(f"    {description}\n")
+            sys.stderr.write(f"    > ")
+            sys.stderr.flush()
+            try:
+                value = tty.readline().strip()
+            except (OSError, KeyboardInterrupt):
+                value = ""
+
+        if value == "" or value.lower() == "skip":
+            out_lines.append(f"    {key}: # TODO: {description}")
+        else:
+            out_lines.append(f"    {key}: {yaml_quote(value)}")
+
+print("\n".join(out_lines))
+
+if tty is not None:
+    tty.close()
+PYEOF
+)
+
+# Append to instance config
+{
+  echo ""
+  echo "$FINAL_YAML"
+} >> "$INSTANCE_CONFIG"
+
+echo "" >&2
+echo "✓ Tool bindings appended to $INSTANCE_CONFIG" >&2

package/templates/scaffold/scripts/lib/functions.sh

@@ -20,7 +20,8 @@ read_functions() {
   fi
   if _have_pyyaml; then
     python3 -c "
-import yaml, sys
+import yaml, re, sys
+SLUG_RE = re.compile(r'^[a-z][a-z0-9-]*\$')
 try:
     with open('$config') as f:
         data = yaml.safe_load(f) or {}
@@ -29,12 +30,23 @@ except yaml.YAMLError as e:
     sys.exit(1)
 for fn in data.get('functions', []):
     slug = fn.get('slug', '')
-    if slug:
-        print(slug)
+    if not slug:
+        continue
+    if not SLUG_RE.match(slug):
+        sys.stderr.write(\"ERROR: malformed slug '\" + slug + \"' in $config — must match ^[a-z][a-z0-9-]*\$\n\")
+        sys.exit(1)
+    print(slug)
 " || return 1
   else
-    grep -E '^[[:space:]]*-[[:space:]]*slug:[[:space:]]*' "$config" \
-      | sed -E 's/^[[:space:]]*-[[:space:]]*slug:[[:space:]]*//; s/[[:space:]]*$//'
+    local slug
+    while IFS= read -r slug; do
+      if ! [[ "$slug" =~ ^[a-z][a-z0-9-]*$ ]]; then
+        echo "ERROR: malformed slug '$slug' in $config — must match ^[a-z][a-z0-9-]*\$" >&2
+        return 1
+      fi
+      printf '%s\n' "$slug"
+    done < <(grep -E '^[[:space:]]*-[[:space:]]*slug:[[:space:]]*' "$config" \
+      | sed -E 's/^[[:space:]]*-[[:space:]]*slug:[[:space:]]*//; s/[[:space:]]*$//')
   fi
 }