Toolbox

#!/usr/bin/env bash
set -euo pipefail

if [[ $# -lt 2 ]]; then
  echo "usage: $0 <issue-or-task-id> <slug>" >&2
  exit 64
fi

task_id="$1"
slug="$2"
branch="agent/${task_id}-${slug}"
root="$(git rev-parse --show-toplevel)"
worktree="${root}/.worktrees/${branch//\//-}"

git fetch origin main
git worktree add "$worktree" -b "$branch" origin/main

cat <<MSG
Worktree ready:
  branch:   $branch
  path:     $worktree

Run the agent from that path, commit there, then open a PR back to main.
MSG

Keep each agent on one task, one branch, and one PR. Delete the worktree after merge with:

git worktree remove .worktrees/agent-123-example

Use this before optimizing model choice. Bad prompt shape can erase the discount before the request reaches the model.

## Prompt cache audit

- [ ] Static system prompt is first.
- [ ] Tool definitions are before any user/session data.
- [ ] Few-shot examples are stable and before dynamic context.
- [ ] User input is after a visible delimiter.
- [ ] Retrieved context is after the stable prefix.
- [ ] No timestamp, UUID, nonce, random salt, or request ID appears before the cache boundary.
- [ ] Retry logic does not rewrite the stable prefix.
- [ ] Logs record input tokens, output tokens, cached tokens, and cache hit rate per route.
- [ ] Alert if a high-volume route drops below 70% prompt-cache hit rate.
- [ ] Template changes include a before/after cache-rate note in the PR.

If the first variable appears above the first reusable block, the prompt is not cache-shaped yet.

## Goal

Ship <specific outcome> for <user/system>.

## Done means

- <observable behavior 1>
- <observable behavior 2>
- <test/check that proves it>
- <PR, deploy, or artifact location>

## Non-goals

- Do not <tempting expansion>.
- Do not refactor <unrelated area>.

## Constraints

- Preserve <existing behavior>.
- Use <existing framework/helper/API>.
- Keep changes inside <files/modules>.

## Verification

Run:

1. <command>
2. <command>

Then manually check:

- <route/UI/API/output>

If the agent cannot point to a line under “Done means,” it is not done.

## MCP server admission policy

An MCP server may be used in a production-adjacent agent path only when:

1. Version is pinned to an exact release, digest, or commit.
2. Owner is named in the service catalog.
3. Credentials are scoped to the smallest read/write surface.
4. A known-good fixture call runs on a schedule.
5. Health check validates semantic output, not just process liveness.
6. Failure mode is explicit: fail closed, degrade, or human-review.
7. Logs include server version, tool name, request ID, and redacted result shape.
8. Upgrade PR includes fixture output before and after.
9. Removal path is known if the server is abandoned.

No owner, no pin, no fixture: no production path.

Treat stdio as transport detail. The blast radius comes from credentials and decisions, not ports.

{
  "receipt_version": "1",
  "command": "deploy promote",
  "operation_id": "op_20260710_143012_8f41",
  "actor": "[email protected]",
  "target": {
    "type": "service",
    "id": "svc_api",
    "name": "api"
  },
  "change": {
    "before": {
      "version": "2026.07.09-1"
    },
    "after": {
      "version": "2026.07.10-1"
    }
  },
  "verify": "deploy status svc_api --operation op_20260710_143012_8f41",
  "rollback": "deploy promote svc_api 2026.07.09-1"
}

Print the receipt to stdout and persist it server-side. Terminal scrollback is not an audit log.