@firatcand/roster 0.4.0 → 1.0.1

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

@@ -1,136 +1,55 @@
 #!/usr/bin/env bash
-# bindings-prompt.sh — read ## Tools and bindings from agent.md, prompt user, append YAML
+# bindings-prompt.sh — DISABLED in v1.0 (ROS-78).
 #
-# Args:
-#   $1 = path to agent.md (the global agent contract)
-#   $2 = path to instance config/default.yaml (will append tools: block)
+# Pre-v1.0 behavior: read `## Tools and bindings` from agent.md (legacy
+# two-level `tool: key: {required, description}` schema), prompt the user
+# for binding values, and append a `tools:` block to a project-instance
+# config at `projects/<inst>/config/default.yaml`.
 #
-# 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
+# Both inputs change in v1.0:
+#   1. The shipped `## Tools and bindings` block in agent.md is now a flat
+#      schema (`tool: { env_var, required, description }` per
+#      conventions.md). The legacy parser silently emits an empty
+#      `tools.<tool>:` block when it encounters scalar values where it
+#      expects a mapping.
+#   2. The instance-config target is gone — agent config lives at
+#      `<function>/<agent>/config.yaml`, and env-var values belong in
+#      workspace `/.env` (overridable in `<agent>/.env`).
 #
-# Non-TTY environments fall back to TODO placeholders for every binding.
+# The proper v1.0 flow (read agent.md flat schema → write metadata to
+# config.yaml `tools:` block → prompt for required env-var values and
+# append to `/.env`) requires the env-merge loader that ships in Phase 2.
+# Rather than ship a script whose advertised behavior is broken against
+# the new schema, this script aborts with manual-configuration instructions
+# (edit agent.md schema → mirror to config.yaml → fill /.env).
+#
+# Tracking: re-enable as part of the Phase 2 cli-plumbing reshape
+# (env-merge loader + doctor checks 13-15).
 
 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 = ""
+cat >&2 <<'MSG'
+bindings-prompt.sh is disabled in Roster v1.0.
 
-        if value == "" or value.lower() == "skip":
-            out_lines.append(f"    {key}: # TODO: {description}")
-        else:
-            out_lines.append(f"    {key}: {yaml_quote(value)}")
+The legacy two-level schema parser this script uses is incompatible with
+the flat ## Tools and bindings schema documented in conventions.md
+("Tool bindings" section). The Phase 2 reshape (env-merge loader +
+config.yaml/.env split) will rebuild this flow.
 
-print("\n".join(out_lines))
+Configure tool bindings by hand (the env-merge loader reads them at
+runtime — what's missing is the auto-mirroring generator this script
+was meant to provide):
 
-if tty is not None:
-    tty.close()
-PYEOF
-)
+  1. Open <function>/<agent>/agent.md and confirm the ## Tools and
+     bindings YAML block lists each tool with env_var, required, and
+     description fields (see conventions.md § "Tool bindings").
+  2. Mirror that block as the tools: mapping in
+     <function>/<agent>/config.yaml.
+  3. Add the corresponding env var values to workspace /.env (or, for
+     agent-scoped overrides, <function>/<agent>/.env).
 
-# Append to instance config
-{
-  echo ""
-  echo "$FINAL_YAML"
-} >> "$INSTANCE_CONFIG"
+(The chief-of-staff guided create-agent flow shipped in v0.4 is also on
+the pre-v1 shape; it will be updated alongside the env-merge loader.)
+MSG
 
-echo "" >&2
-echo "✓ Tool bindings appended to $INSTANCE_CONFIG" >&2
+exit 2

package/templates/scaffold/scripts/new-agent.sh

@@ -62,7 +62,7 @@ description: "$fn agent — TODO: fill in description"
 
 # /$name
 
-You are operating the \`$fn/$name\` agent. Load \`$fn/$name/agent.md\` and the project's relevant context.
+You are operating the \`$fn/$name\` agent. Load \`$fn/$name/agent.md\` and the workspace's relevant context.
 
 The user request is: \$ARGUMENTS
 
@@ -70,28 +70,25 @@ The user request is: \$ARGUMENTS
 
 Parse the user request:
 
-1. **If it matches \`run <plan-name> for <project>\` or \`run <plan-name> on <project>\`**:
+1. **If it matches \`run <plan-name>\`**:
    - Load \`$fn/$name/plans/<plan-name>.yaml\`. If it doesn't exist, list available plans and ask user to pick.
-   - Load \`projects/<project>/CLAUDE.md\` and relevant guidelines.
-   - Load \`$fn/$name/projects/<project>/config/default.yaml\`.
-   - Validate that all required tool bindings are non-TODO. Abort if not.
-   - Execute the plan steps. Substitute \`\${tools.X.Y}\`, \`\${inputs.X}\`, \`\${config.X}\`.
-   - Log to \`$fn/$name/projects/<project>/log/runs/<YYYY-MM>/<YYYY-MM-DD-HHMM>.md\`.
-   - Surface HITL approvals per the plan's approval_channel.
-
-2. **If only a project is named (no plan)**:
+   - Load \`$fn/$name/config.yaml\` and resolve env via \`resolveAgentEnv\` (\`$fn/$name/.env\` overrides workspace \`/.env\`).
+   - Load workspace guidelines referenced under \`config.yaml\` \`guideline_refs:\` (e.g., \`/guidelines/voice.md\`, \`/guidelines/icps/\`, \`/guidelines/messaging.md\`).
+   - Validate that all required tool bindings have non-empty env vars. Abort with a clear message if not.
+   - Execute the plan steps. Substitute \`\${tools.X.env_var}\`, \`\${inputs.X}\`, \`\${config.X}\`.
+   - Log to \`$fn/$name/logs/runs/<YYYY-MM>/<YYYY-MM-DD-HHMM>.md\`.
+   - Surface HITL approvals per the plan's \`approval_channel\`.
+
+2. **If no plan is named**:
    - List available plans from \`$fn/$name/plans/\` with descriptions. Ask user to pick.
 
-3. **If neither plan nor project is named**:
-   - List available projects and plans. Ask user to specify both.
-
-4. **For ad-hoc strategic work**: suggest invoking \`$fn/EXPERT.md\` instead.
+3. **For ad-hoc strategic work**: suggest invoking \`$fn/EXPERT.md\` instead.
 
 ## Constraints
 
 - Only run plans that exist as files in \`$fn/$name/plans/\`.
 - Don't bypass approval gates.
-- File writes go to the instance's \`log/runs/\` unless the plan explicitly writes elsewhere.
+- File writes go to \`$fn/$name/logs/runs/\` unless the plan explicitly writes elsewhere.
 EOF
 }
 
@@ -137,7 +134,7 @@ fi
 
 echo "Creating agent: $FN/$NAME"
 
-mkdir -p "$TARGET"/{subagents,playbook,logs,projects/_template,.claude/skills,.claude/plugins}
+mkdir -p "$TARGET"/{subagents,playbook,pending,logs/runs,logs/feedback,.claude/skills,.claude/plugins}
 
 # agent.md stub
 cat > "$TARGET/agent.md" << EOF
@@ -149,45 +146,36 @@ cat > "$TARGET/agent.md" << EOF
 
 ## Inputs
 
-The orchestrator expects:
-
-- \`project\`: project slug
-- <other inputs>
+The orchestrator expects per-plan inputs (declared in each plan's \`inputs:\` block).
 
 Read at runtime:
 
 - \`agent.md\` (this file)
-- \`projects/<project>/<this-agent>/config/default.yaml\`
-- \`projects/<project>/CLAUDE.md\`
-- \`projects/<project>/guidelines/voice.md\`
-- <other guidelines this agent uses>
-- \`<this-agent>/projects/<project>/playbook/\` — project-scoped lessons
-- \`<this-agent>/playbook/\` — global lessons
+- \`config.yaml\` (workspace-root-relative guideline refs + tool bindings)
+- Workspace guidelines referenced under \`config.yaml\` \`guideline_refs:\` (e.g., \`/guidelines/voice.md\`, \`/guidelines/icps/\`, \`/guidelines/messaging.md\`)
+- \`playbook/\` — validated lessons (single playbook per agent)
 
-## Steps
+Env resolution: \`<this-agent>/.env\` overrides workspace \`/.env\`. Required tool env vars validated before the plan runs.
 
-1. Resolve config and context
-2. <step>
-3. <step>
+## Plans
 
-## Subagents
+Named plans this agent runs (files in \`plans/<plan>.yaml\`). One-line description per plan.
+No default plan — invoking without a plan triggers an interactive "which plan?" prompt.
 
-- <subagent-name>.md — <one-liner>
+- <plan-name>: <one-liner>
 
-## Tools
-
-Agent-scoped MCPs at \`<this-agent>/.mcp.json\`:
-- <tool/MCP> — <purpose>
+## Subagents
 
-Universal MCPs (Slack, Google Drive) inherited from agent-team root.
+- <subagent-name>.md — <one-liner>
 
 ## Outputs
 
-Run file at \`projects/<project>/<this-agent>/log/runs/<YYYY-MM>/<YYYY-MM-DD-HHMM>.md\`. See \`conventions.md\` § "Run file format".
+Run file at \`logs/runs/<YYYY-MM>/<YYYY-MM-DD-HHMM>.md\`. See \`conventions.md\` § "Run file format".
+Per-plan output schemas live in each plan's \`outputs:\` block.
 
 ## Approval
 
-\`approval_channel: auto\` — in-session if interactive, Slack \`#${FN}\` if cron (resolved via \`SLACK_HITL_CHANNEL_$(echo "$FN" | tr '[:lower:]-' '[:upper:]_')\` in \`.env\`).
+\`approval_channel: auto\` — in-session if interactive, Slack \`#${FN}\` if cron (resolved via \`SLACK_HITL_CHANNEL_$(echo "$FN" | tr '[:lower:]-' '[:upper:]_')\` in workspace \`/.env\`).
 
 ## Lessons protocol
 
@@ -206,39 +194,49 @@ cat > "$TARGET/README.md" << EOF
 
 ## Files
 
-- \`agent.md\` — orchestrator contract
+- \`agent.md\` — orchestrator contract (behavioral prompt, plans list, tool bindings schema)
+- \`config.yaml\` — guideline refs + tool bindings (workspace-root paths)
+- \`.env\` — agent-scoped env overrides (gitignored, 0600 — optional, inherits from workspace \`/.env\`)
+- \`plans/\` — named workflows (\`<plan>.yaml\`)
 - \`subagents/\` — specialized roles
-- \`playbook/\` — global lessons (one file per lesson)
-- \`logs/\` — agent-level operational logs
-- \`.claude/\` — agent-scoped skills, plugins
-- \`.mcp.json\` — agent-scoped MCPs (CREATE THIS — see template comment)
-- \`projects/\` — per-project instances
+- \`playbook/\` — validated lessons (single playbook per agent)
+- \`pending/\` — HITL items awaiting approval
+- \`logs/runs/\`, \`logs/feedback/\` — run outputs + mirrored feedback
+- \`asset-references.md\` — which workspace assets this agent uses (thin pointer)
+- \`.claude/\` — agent-scoped Claude Code config (skills, plugins, settings)
+- \`.mcp.json\` — agent-scoped MCPs
 
 ## Invocation
 
-From a project instance session:
+From the workspace root:
 
 \`\`\`bash
-cd $FN/$NAME/projects/<project>/
 claude
-"Run $NAME on <inputs>"
+> /$NAME run <plan-name>
 \`\`\`
 
-From cron: see ROS-39 (Phase 2.5 scheduling primitives — wrapper layout + install script land then).
+Or via natural language:
+
+\`\`\`
+"Run $FN/$NAME using the <plan-name> plan"
+\`\`\`
+
+From cron: see ADR-0001 (subscription-billed scheduling via native local schedulers). Install via \`roster schedule install $FN/$NAME <plan> --cron "<expr>" --tool claude|codex\`.
 
 ## Configuration
 
-Per-project: \`projects/<proj>/$FN/$NAME/config/default.yaml\` (created by \`new-agent-instance.sh\`).
+\`config.yaml\` (this agent) — guideline refs + tool bindings.
+Workspace \`/.env\` (root) + optional \`<this-agent>/.env\` for agent-scoped overrides.
 
 ## Outputs
 
-\`projects/<proj>/$FN/$NAME/log/runs/<YYYY-MM>/<YYYY-MM-DD-HHMM>.md\`
+\`logs/runs/<YYYY-MM>/<YYYY-MM-DD-HHMM>.md\` — one file per invocation.
 EOF
 
 # .mcp.json stub
 cat > "$TARGET/.mcp.json" << EOF
 {
-  "_comment": "Agent-scoped MCPs for $NAME. Available when working in this agent's tree (including project instances). Add MCPs this agent specifically needs. Universal MCPs (Slack, Google Drive) are inherited from agent-team/.mcp.json.",
+  "_comment": "Agent-scoped MCPs for $NAME. Available when working in this agent's tree. Add MCPs this agent specifically needs. Universal MCPs (Slack, Google Drive) are inherited from the workspace .mcp.json.",
   "mcpServers": {}
 }
 EOF
@@ -273,41 +271,50 @@ cat > "$TARGET/subagents/_template.md" << 'EOF'
 <Specific criteria for acceptable output.>
 EOF
 
-# Project instance template
-mkdir -p "$TARGET/projects/_template/config"
-mkdir -p "$TARGET/projects/_template/playbook"
-mkdir -p "$TARGET/projects/_template/log/runs"
-mkdir -p "$TARGET/projects/_template/log/feedback"
-
-cat > "$TARGET/projects/_template/config/default.yaml" << EOF
----
-agent: $NAME
-project: <project-slug>
-created: <YYYY-MM-DD>
-last_modified: <YYYY-MM-DD>
----
-
-# $NAME Config — <Project>
-
-# See $FN/$NAME/agent.md § "Inputs" for required fields.
-# Use prose comments to explain "why" alongside "what".
+# config.yaml — agent config (guideline refs + tool bindings)
+# Minimal stub. The env-merge loader (resolveAgentEnv) reads bindings
+# from this file's tools: block, with env-var values sourced from
+# workspace /.env (or this agent's .env override). Until the dialogue-
+# driven generator that auto-mirrors agent.md → config.yaml ships,
+# copy the ## Tools and bindings YAML block from agent.md into the
+# tools: mapping below by hand.
+cat > "$TARGET/config.yaml" << EOF
+agent: $FN/$NAME
+plans_dir: ./plans/
+
+# Workspace-root-relative refs. Loader rejects literal absolute fs paths
+# like /Users/, /home/, /etc/, /var/, /tmp/, /opt/.
+guideline_refs:
+  voice: /guidelines/voice.md
+  icps: /guidelines/icps/
+  messaging: /guidelines/messaging.md
+  # add more as needed:
+  # brand_book: /guidelines/brand-book.md
+  # do_and_dont: /guidelines/do-and-dont.md
+  # compliance: /guidelines/compliance.md
+  # competitors: /guidelines/competitors.md
+
+# Tool bindings. Each tool entry names the env var, required flag, and a
+# short description. Env vars themselves live in workspace /.env (or are
+# overridden in this agent's .env).
+tools: {}
 EOF
 
-cat > "$TARGET/projects/_template/asset-references.md" << EOF
-# Asset references — $NAME / <project>
+# asset-references.md — thin pointer at agent root
+cat > "$TARGET/asset-references.md" << EOF
+# Asset references — $FN/$NAME
 
-This agent uses these assets from \`projects/<project>/guidelines/asset-links.md\`:
+This agent uses these assets from \`guidelines/asset-links.md\`:
 
 - <e.g., specific asset by name>
 EOF
 
 touch "$TARGET/playbook/.gitkeep"
-touch "$TARGET/logs/.gitkeep"
+touch "$TARGET/pending/.gitkeep"
+touch "$TARGET/logs/runs/.gitkeep"
+touch "$TARGET/logs/feedback/.gitkeep"
 touch "$TARGET/.claude/skills/.gitkeep"
 touch "$TARGET/.claude/plugins/.gitkeep"
-touch "$TARGET/projects/_template/playbook/.gitkeep"
-touch "$TARGET/projects/_template/log/runs/.gitkeep"
-touch "$TARGET/projects/_template/log/feedback/.gitkeep"
 
 # === Tool bindings prompt (added by tool-bindings workflow) ===
 # Ask the user whether to define tools now. If yes, collect tool names and scaffold
@@ -346,24 +353,25 @@ if [ -t 0 ] && [ "${AGENT_TEAM_NO_CONFIRM:-0}" != "1" ]; then
           echo ""
           echo "## Tools and bindings"
           echo ""
-          echo "Per-project tool bindings expected by this agent. Chief-of-staff prompts for these when scaffolding a new agent-instance. Values land in \`projects/<project>/config/default.yaml\` under a \`tools:\` key."
+          echo "Tool bindings expected by this agent. The env-merge loader reads these from \`<agent>/config.yaml\` (under a \`tools:\` key), with env-var values from workspace \`/.env\` (overridable in \`<agent>/.env\`). For now, mirror the YAML block below into \`config.yaml\` by hand — the auto-mirroring generator that would derive it from this section is not yet shipped."
           echo ""
-          echo "Fill in each tool's bindings below. Schema: each binding has a \`required\` flag (true/false) and a \`description\`."
+          echo "Fill in each tool's bindings below. Schema per conventions.md § \"Tool bindings\": each tool has a \`env_var\` (the env-var name the runtime reads), a \`required\` flag (true/false), and a one-line \`description\`."
           echo ""
           echo '```yaml'
           for tool in "${TOOL_NAMES[@]}"; do
+            tool_env=$(echo "$tool" | tr '[:lower:]-' '[:upper:]_')
             echo "$tool:"
-            echo "  # TODO: define bindings"
-            echo "  #   <binding_name>:"
-            echo "  #     required: true"
-            echo "  #     description: \"...\""
+            echo "  env_var: ${tool_env}_API_KEY  # TODO: confirm env var name"
+            echo "  required: true               # TODO: confirm required vs optional"
+            echo "  description: \"\"             # TODO: one-line description"
           done
           echo '```'
         } >> "$NEW_AGENT_MD"
 
         echo ""
         echo "✓ Added '## Tools and bindings' to $NEW_AGENT_MD with stubs for: ${TOOL_NAMES[*]}"
-        echo "  Edit agent.md to fill in actual bindings before adding instances."
+        echo "  Edit agent.md to fill in env_var names + descriptions, then mirror the tools: block into <agent>/config.yaml by hand."
+        echo "  (The env-merge loader reads bindings from <agent>/config.yaml at runtime; the auto-mirroring generator that would copy this block for you is not yet shipped, so this step is manual.)"
       else
         echo "  No valid tool names provided. Skipping section."
       fi
@@ -399,12 +407,12 @@ echo ""
 echo "✓ Agent '$FN/$NAME' created at $TARGET"
 echo ""
 echo "Next steps:"
-echo "  1. Fill in $TARGET/agent.md (purpose, inputs, steps, subagents, tools, outputs)"
-echo "  2. Add subagents: cp $TARGET/subagents/_template.md $TARGET/subagents/<name>.md and fill in"
-echo "  3. Add agent-scoped MCPs to $TARGET/.mcp.json if needed (HeyReach, Apollo, etc.)"
-echo "  4. Update $TARGET/README.md with a real description"
-echo "  5. Add at least one plan to $TARGET/plans/ (e.g., $TARGET/plans/<plan-name>.yaml)"
-echo "  6. Edit .claude/commands/$NAME.md to fill in the description"
-echo "  7. Add an instance to a project: bash scripts/new-agent-instance.sh <project> $FN $NAME"
+echo "  1. Fill in $TARGET/agent.md (purpose, inputs, plans, subagents, tools, outputs)"
+echo "  2. Fill in $TARGET/config.yaml (guideline_refs, tools)"
+echo "  3. Add subagents: cp $TARGET/subagents/_template.md $TARGET/subagents/<name>.md and fill in"
+echo "  4. Add agent-scoped MCPs to $TARGET/.mcp.json if needed (HeyReach, Apollo, etc.)"
+echo "  5. Update $TARGET/README.md with a real description"
+echo "  6. Add at least one plan to $TARGET/plans/ (e.g., $TARGET/plans/<plan-name>.yaml)"
+echo "  7. Edit .claude/commands/$NAME.md to fill in the description"
 echo ""
 echo "Reference: see gtm/sdr/ for a complete example."

package/templates/scaffold/scripts/rename-agent.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# rename-agent.sh — renames a global agent everywhere it appears
+# Usage: bash scripts/rename-agent.sh <function> <old> <new>
+
+set -euo pipefail
+
+if [ $# -ne 3 ]; then
+  echo "Usage: $0 <function> <old> <new>"
+  exit 1
+fi
+
+FN="$1"
+OLD="$2"
+NEW="$3"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+if ! [[ "$NEW" =~ ^[a-z][a-z0-9-]*$ ]]; then
+  echo "ERROR: New slug must be lowercase, alphanumeric + hyphens, starting with a letter."
+  exit 1
+fi
+
+OLD_DIR="$ROOT/$FN/$OLD"
+NEW_DIR="$ROOT/$FN/$NEW"
+
+if [ ! -d "$OLD_DIR" ]; then
+  echo "ERROR: Agent '$FN/$OLD' not found at $OLD_DIR"
+  exit 1
+fi
+
+if [ -d "$NEW_DIR" ]; then
+  echo "ERROR: Agent '$FN/$NEW' already exists at $NEW_DIR"
+  exit 1
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mv "$OLD_DIR" "$NEW_DIR"
+echo "  Moved: $FN/$OLD/ → $FN/$NEW/"
+
+SED_INPLACE=(-i)
+if [[ "$(uname)" == "Darwin" ]]; then
+  SED_INPLACE=(-i '')
+fi
+
+# Broad replace on prose files only — these are markdown stubs where the
+# old slug appears in headings / paths and we want every reference updated.
+for f in "$NEW_DIR"/agent.md "$NEW_DIR"/README.md "$NEW_DIR"/asset-references.md; do
+  [ -f "$f" ] && sed "${SED_INPLACE[@]}" "s|$OLD|$NEW|g" "$f"
+done
+
+# config.yaml: only the identity field. A broad replace would corrupt env-var
+# names, comments, and any value that legitimately contains $OLD.
+CFG="$NEW_DIR/config.yaml"
+if [ -f "$CFG" ]; then
+  sed "${SED_INPLACE[@]}" "s|^agent: $FN/$OLD$|agent: $FN/$NEW|" "$CFG"
+fi
+
+while IFS= read -r f; do
+  case "$f" in
+    *"_archive/"*) continue ;;
+    *"/logs/"*) continue ;;
+    *"/log/runs/"*) continue ;;
+    *"/log/feedback/"*) continue ;;
+    *"/playbook/"*) continue ;;
+    *) sed "${SED_INPLACE[@]}" "s|$FN/$OLD|$FN/$NEW|g" "$f" ;;
+  esac
+done < <(grep -rl "$FN/$OLD" --include='*.md' --include='*.yaml' --include='*.json' --include='*.sh' --include='*.txt' "$ROOT" 2>/dev/null)
+
+OLD_CMD="$ROOT/.claude/commands/$OLD.md"
+NEW_CMD="$ROOT/.claude/commands/$NEW.md"
+if [ -f "$OLD_CMD" ]; then
+  mv "$OLD_CMD" "$NEW_CMD"
+  sed "${SED_INPLACE[@]}" "s|$OLD|$NEW|g" "$NEW_CMD"
+  echo "  Renamed slash command: .claude/commands/$OLD.md → $NEW.md"
+fi
+
+LOG_DIR="$ROOT/chief-of-staff/logs/$(date +%Y-%m)"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/operations-$(date +%Y-%m-%d).md"
+{
+  echo ""
+  echo "## $TIMESTAMP — rename-agent: $FN/$OLD → $FN/$NEW"
+} >> "$LOG_FILE"
+
+echo ""
+echo "Files mentioning '$OLD' that were NOT auto-updated (review manually):"
+grep -rln "$OLD" "$ROOT" 2>/dev/null | grep -v "_archive\|/logs/\|/log/runs/\|/log/feedback/\|/playbook/" | sed "s|$ROOT/|  - |" || echo "  (none found)"
+
+echo ""
+echo "✓ Rename complete."
+echo "  Operation log: $LOG_FILE"

package/templates/scaffold/scripts/save-state.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# save-state.sh — write workspace state.md
+#
+# In v1, workspace = project. state.md lives at workspace root.
+# Format: see conventions.md § "State file format". Normally Claude writes
+# state.md directly when asked. This script exists for external invocation
+# or scripted updates.
+#
+# Usage: bash scripts/save-state.sh "<state notes (multiline OK)>"
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 \"<state notes>\""
+  exit 1
+fi
+
+NOTES="$*"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+STATE_FILE="$ROOT/state.md"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+cat > "$STATE_FILE" << EOF
+---
+updated: $TIMESTAMP
+---
+
+$NOTES
+EOF
+
+echo "✓ Saved workspace state"
+echo "  $STATE_FILE"