brigade-cli 0.5.0__py3-none-any.whl

brigade/templates/scripts/backup-restic.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# ============================================================================
+# Workspace backup via restic -> Google Drive (rclone) + local NAS mount
+# Run twice daily via cron. Tunable. Sanitize before commit.
+# ============================================================================
+#
+# Setup once:
+#   1. apt install restic rclone
+#   2. rclone config   # set up `gdrive` remote
+#   3. echo "<strong-password>" > ~/.brigade/.restic-password
+#      chmod 600 ~/.brigade/.restic-password
+#   4. (optional) mount your NAS at $NAS_MOUNT
+#   5. crontab -e:
+#        0 3,15 * * * /path/to/backup-restic.sh
+#
+set -euo pipefail
+
+# ---- Paths ----
+WORKSPACE_ROOT="${WORKSPACE_ROOT:-${HOME}}"
+LOG_FILE="${WORKSPACE_ROOT}/.brigade/logs/backup-$(date +%Y%m%d).log"
+mkdir -p "$(dirname "$LOG_FILE")"
+
+log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"; }
+
+# ---- Config (edit for your stack) ----
+RESTIC_REPO_GDRIVE="rclone:gdrive:Backup/<your-repo-name>"
+RESTIC_PASSWORD_FILE="${HOME}/.brigade/.restic-password"
+NAS_MOUNT="${NAS_MOUNT:-/mnt/nas/backups}"
+RESTIC_REPO_NAS="${NAS_MOUNT}/<your-repo-name>"
+
+# Retention policy. Tune to taste; the defaults below cover ~3 months of
+# overlapping daily/weekly/monthly snapshots.
+KEEP_DAILY="${KEEP_DAILY:-7}"
+KEEP_WEEKLY="${KEEP_WEEKLY:-4}"
+KEEP_MONTHLY="${KEEP_MONTHLY:-3}"
+
+# Paths to back up. Replace with your actual roots.
+BACKUP_PATHS=(
+  "${HOME}/.brigade"
+  "${HOME}/repos"
+  "${HOME}/bin"
+  "${HOME}/.bashrc"
+  "${HOME}/.profile"
+  "${HOME}/.gitconfig"
+  "${HOME}/.ssh"
+  "${HOME}/.claude"
+  "${HOME}/.codex"
+  "${HOME}/notes"
+  "${HOME}/Obsidian"
+)
+
+# Exclude rules shared between gdrive + NAS runs.
+EXCLUDES=(
+  --exclude='node_modules'
+  --exclude='.git/objects'
+  --exclude='__pycache__'
+  --exclude='*.pyc'
+  --exclude='.venv'
+  --exclude='venv'
+  --exclude='dist'
+  --exclude='build'
+  --exclude='.next'
+  --exclude='.astro'
+  --exclude='coverage'
+  --exclude='.turbo'
+  --exclude='*.jsonl'
+  --exclude='.pm2/logs'
+  --exclude='.pm2/pids'
+  --exclude='.ollama'
+  --exclude='.obsidian/workspace*.json'
+  --exclude='.obsidian/cache'
+  --exclude='.trash'
+)
+
+export RESTIC_PASSWORD_FILE
+
+# ---- rclone tuning ----
+# Google Drive can reject bursty restic-over-rclone writes when other rclone
+# jobs are running. Keep the backend intentionally conservative so scheduled
+# backups finish reliably instead of spinning in quota retry loops.
+export RCLONE_TRANSFERS="${RCLONE_TRANSFERS:-1}"
+export RCLONE_CHECKERS="${RCLONE_CHECKERS:-2}"
+export RCLONE_TPSLIMIT="${RCLONE_TPSLIMIT:-4}"
+export RCLONE_TPSLIMIT_BURST="${RCLONE_TPSLIMIT_BURST:-4}"
+export RCLONE_DRIVE_PACER_MIN_SLEEP="${RCLONE_DRIVE_PACER_MIN_SLEEP:-500ms}"
+export RCLONE_DRIVE_PACER_BURST="${RCLONE_DRIVE_PACER_BURST:-10}"
+export RCLONE_RETRIES="${RCLONE_RETRIES:-8}"
+export RCLONE_LOW_LEVEL_RETRIES="${RCLONE_LOW_LEVEL_RETRIES:-20}"
+
+# ---- Pre-flight ----
+command -v restic >/dev/null || { log "ERROR: restic not installed."; exit 1; }
+command -v rclone >/dev/null || { log "ERROR: rclone not installed."; exit 1; }
+[ -f "$RESTIC_PASSWORD_FILE" ] || { log "ERROR: password file not found: $RESTIC_PASSWORD_FILE"; exit 1; }
+
+# ---- Helper: ensure a restic repo is usable ----
+ensure_repo() {
+  local repo="$1"
+  export RESTIC_REPOSITORY="$repo"
+  if restic snapshots --json >/dev/null 2>&1; then
+    log "Repo exists at $repo, proceeding."
+    return 0
+  fi
+  log "Initializing repo: $repo"
+  if restic init 2>&1 | tee -a "$LOG_FILE"; then
+    return 0
+  fi
+  # init may fail because the repo already exists; retry the check.
+  if restic snapshots --json >/dev/null 2>&1; then
+    log "Repo already exists (init not needed)."
+    return 0
+  fi
+  log "ERROR: cannot access or initialize repo: $repo"
+  return 1
+}
+
+# ---- Helper: backup + forget for a configured repo ----
+run_backup() {
+  local repo="$1"
+  local tag="$2"
+  export RESTIC_REPOSITORY="$repo"
+  log "Backing up to $repo (tag=$tag)..."
+  restic backup --verbose --tag "$tag" "${EXCLUDES[@]}" "${BACKUP_PATHS[@]}" 2>&1 | tee -a "$LOG_FILE"
+  log "Pruning old snapshots..."
+  restic forget \
+    --keep-daily "$KEEP_DAILY" \
+    --keep-weekly "$KEEP_WEEKLY" \
+    --keep-monthly "$KEEP_MONTHLY" \
+    --prune 2>&1 | tee -a "$LOG_FILE"
+}
+
+# ---- Google Drive backup ----
+if ensure_repo "$RESTIC_REPO_GDRIVE"; then
+  run_backup "$RESTIC_REPO_GDRIVE" "scheduled"
+  log "Clearing any stale gdrive locks..."
+  restic unlock --remove-all 2>&1 | tee -a "$LOG_FILE" || true
+else
+  log "Skipping gdrive backup; repo unavailable."
+fi
+
+# ---- NAS backup (skip cleanly if not mounted) ----
+if mountpoint -q "${NAS_MOUNT}" 2>/dev/null || [ -d "${NAS_MOUNT}" ]; then
+  if ensure_repo "$RESTIC_REPO_NAS"; then
+    run_backup "$RESTIC_REPO_NAS" "scheduled-nas"
+    restic unlock --remove-all 2>&1 | tee -a "$LOG_FILE" || true
+  else
+    log "Skipping NAS backup; repo unavailable."
+  fi
+else
+  log "NAS not mounted at ${NAS_MOUNT}, skipping NAS backup."
+fi
+
+# ---- Summary ----
+export RESTIC_REPOSITORY="$RESTIC_REPO_GDRIVE"
+SNAPSHOT_COUNT=$(restic snapshots --json 2>/dev/null | python3 -c "import sys,json; print(len(json.load(sys.stdin)))" 2>/dev/null || echo "?")
+log "Done. Total snapshots (gdrive): $SNAPSHOT_COUNT"
+log "Log: $LOG_FILE"

brigade/templates/skills/note/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: note
+version: 1.0.0
+description: "Create an Obsidian-formatted markdown note documenting the current session topic. Use when the user says /note, 'save this to Obsidian', 'write a note about X', or asks to document a troubleshooting session, system concept, coding pattern, or workflow. Writes to ~/notes/<slug>.md and syncs to the configured Obsidian inbox. If an argument is provided after /note, use it as the topic; otherwise review the conversation."
+---
+
+# /note - Create Obsidian-Formatted Notes
+
+Create an Obsidian-formatted markdown note and place it in `~/notes/`. Tell the user the exact file path and confirm the sync.
+
+If the user provided a topic argument after `/note`, use it as the topic. Otherwise, review the conversation to identify the topic.
+
+## When to use
+
+Two distinct modes. Pick the right one before you start writing.
+
+| Mode | When |
+|------|------|
+| **Verbatim fix capture** | Troubleshooting sessions, root-causing bugs, recovering from incidents. The fix needs to be reproducible step-by-step. Future-you will paste the exact commands. |
+| **Summarize / concept** | Learning something new, capturing a workflow, documenting a system. The reader needs to understand *why*, not just *how*. |
+
+Common triggers:
+
+- Troubleshooting sessions - issues, errors, and the fix that worked
+- System concepts - how things work on Linux, networking, services, frameworks
+- Coding knowledge - languages, libraries, patterns, gotchas
+- Development workflows - tools, commands, configurations
+- Architecture decisions - what was chosen and why
+
+## Process
+
+1. Decide which mode applies. If unclear, ask: "Should I write this verbatim (reproducible) or summarize the concept?"
+2. Review the conversation to identify the topic and pull the relevant commands, errors, paths.
+3. Write the `.md` file to `~/notes/<topic-slug>.md`.
+4. Sync to the configured Obsidian inbox (see "Sync target" below).
+5. Tell the user the exact file path and confirm the sync.
+
+## Note format
+
+### YAML frontmatter
+
+Every note MUST start with YAML frontmatter:
+
+```yaml
+---
+tags:
+  - tag1
+  - tag2
+created: YYYY-MMM-DD
+---
+```
+
+- 3-5 relevant tags. Lowercase, hyphenated for multi-word.
+- Date format `YYYY-MMM-DD` (e.g. `2026-Jan-24`).
+- Add `mode: verbatim` or `mode: concept` if you want the mode visible in frontmatter.
+
+### Structure: verbatim fix
+
+```markdown
+## The problem
+
+> [!bug] Title
+> Brief symptom. Paste the actual error string verbatim.
+
+Context. What was the system doing. What changed recently.
+
+## The fix
+
+> [!success] Title
+> The exact command(s) that worked.
+
+```bash
+# verbatim commands
+```
+
+## How it works
+
+Explain *why* the fix works. Link to docs if relevant. Note any preconditions.
+
+## Gotchas
+
+> [!warning] Title
+> Anything that almost bit you. Stale state, ordering dependencies, version constraints.
+```
+
+### Structure: summarize / concept
+
+```markdown
+## Overview
+
+What this is and why it matters. One paragraph.
+
+## How it works
+
+Core concepts and mechanics. Diagrams or bullet lists are fine; prose is better when the order matters.
+
+## Example
+
+```bash
+# practical example, runnable
+```
+
+## Tips and gotchas
+
+> [!tip] Title
+> Useful patterns.
+
+> [!warning] Title
+> Things that can break or surprise you.
+```
+
+### Callout types
+
+Use sparingly. The note should be mostly prose; callouts highlight the critical bits.
+
+| Callout | Use for |
+|---------|---------|
+| `[!bug]` | Problems, errors, symptoms |
+| `[!success]` | Solutions, fixes, what worked |
+| `[!tip]` | Helpful hints, shortcuts |
+| `[!warning]` | Dangers, things that can break |
+| `[!info]` | Background context |
+| `[!note]` | General annotations |
+| `[!example]` | Practical examples, sample commands |
+| `[!question]` | Open questions, things to investigate |
+
+### Callout syntax
+
+```markdown
+> [!tip] Optional title
+> Callout content goes here.
+> Can span multiple lines.
+```
+
+## Sync target
+
+The note skill writes to `~/notes/` and syncs to the user's Obsidian vault inbox. The exact sync command depends on how the user's Obsidian vault is wired.
+
+Common shapes (pick what matches the user's setup, document it in `TOOLS.md`):
+
+```bash
+# Google Drive via rclone (most common):
+rclone copy ~/notes/<topic-slug>.md "gdrive:My Drive/<VaultPath>/<Inbox-folder>/"
+
+# Local Obsidian vault on disk:
+cp ~/notes/<topic-slug>.md ~/Obsidian/<Vault>/<Inbox-folder>/
+
+# Bisync timer (already running): just write to ~/notes/ and the next sync fires
+```
+
+If the user has not configured a sync target, leave the file in `~/notes/` and tell them where it landed.
+
+## Quality rules
+
+- Prose is the backbone. Headings, paragraphs, lists, code blocks.
+- Callouts highlight the critical bits (key fix, warning, gotcha). They are not paragraph wrappers.
+- A good note is mostly regular text with callouts around the parts that matter.
+- Include specific commands, paths, config values, error messages. Vague notes are useless three weeks later.
+- Code blocks use language tags for syntax highlighting.
+- Reference-friendly, not narrative.
+- Write for future-you who has zero context about this session.
+- No em dashes. No AI-attribution trailers. Match the user's voice rules from `SOUL.md`.
+
+## Output
+
+Tell the user:
+
+```text
+Wrote note: ~/notes/<topic-slug>.md
+Synced to: <sync target>
+```
+
+If sync failed, surface the error and leave the file in `~/notes/`.

brigade/templates/workspace/AGENTS.md

@@ -0,0 +1,146 @@
+# AGENTS.md - Your Workspace
+
+This folder is home. Treat it that way.
+
+## Every Session
+
+Before doing anything else:
+
+1. Read `SOUL.md` - who you are
+2. Read `USER.md` - who you are helping
+3. Read `MEMORY.md` - slim index, tells you how memory works
+4. Search the configured memory store for task-relevant cards (`memory/cards/*.md`)
+5. Skim `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
+
+Do not ask permission. Just do it. **Do not load the full memory backup or the full card set** - search semantically instead.
+
+## Memory Owner
+
+The configured memory owner is **{{memory_owner_name}}**. Side harnesses may keep local session context, but durable knowledge must be written as a Memory Handoff in `.claude/memory-handoffs/`. The memory owner ingests those handoffs into canonical durable memory. Full contract: `memory/cards/memory-architecture.md` and `memory/cards/handoff-flow.md`.
+
+Do not create a second canonical memory system.
+
+## Memory Layout
+
+You wake up fresh each session. Continuity lives in:
+
+- **`MEMORY.md`** - slim index (~3-7KB), loaded every session
+- **`memory/cards/*.md`** - atomic durable facts, ~300-500 tokens each, searched semantically
+- **`memory/YYYY-MM-DD.md`** - raw daily session logs
+
+Rules: search first, load second. **Write new cards** when you learn something durable. Do not append to `MEMORY.md`. **Update existing cards** when information changes. **Do not load cards in shared/group contexts** that include other people.
+
+**Write it down.** Mental notes die with the session. Files survive. If you want to remember something, put it in a file.
+
+## Workspace File Maintenance
+
+| File | Update when |
+|------|-------------|
+| `USER.md` | Personal info, project change, preference learned |
+| `SOUL.md` | Personality or voice evolves (rare, ask first) |
+| `MEMORY.md` | New card categories, major architecture shift |
+| `TOOLS.md` | New service, port change, host change, infra change |
+| `SAFETY_RULES.md` | New safety lesson, new device, new restriction |
+| `IDENTITY.md` | Name, emoji, vibe changes (rare) |
+| `HEARTBEAT.md` | Periodic check-in behavior changes |
+| `rules/*.md` | Workflow correction, pipeline rule |
+| `.learnings/*.md` | Errors hit, lessons learned |
+| `memory/cards/*.md` | New durable knowledge |
+
+**End of session:** Did the user correct you? Update relevant file + `.learnings/`. Did infra change? `TOOLS.md` + a card. Did a workflow change? `rules/`. Did you learn personal info? `USER.md`.
+
+If you learned it, write it down. If it changed, update the file.
+
+## Memory Handoff (Mandatory)
+
+If a session discovers durable knowledge - architecture decisions, workflow changes, non-obvious fixes, setup gotchas, security findings, reusable commands, durable research, or user preferences - create a handoff at the end of the task.
+
+Write the handoff to `.claude/memory-handoffs/<YYYY-MM-DD-HHMM>-<slug>.md` using the format in `.claude/memory-handoffs/TEMPLATE.md`.
+
+Do not wait to be reminded. Do not edit canonical memory directly unless this is the memory owner.
+
+## Self-Improvement
+
+When the user corrects you: save a card to `memory/cards/` capturing the correction and *why*. Search memory for past corrections before similar tasks. The point is to stop re-making the same mistake, not to accept blame.
+
+## Safety
+
+- Do not exfiltrate private data.
+- Do not run destructive commands without asking.
+- Prefer recoverable deletes (`trash`) over `rm -rf`.
+- When in doubt, ask.
+
+**Safe to do freely:** read, explore, organize, web search, workspace work.
+**Ask first:** emails, posts, messages, anything that leaves the machine, anything uncertain.
+
+Full hard rules: `SAFETY_RULES.md`.
+
+## Group Chats
+
+You have access to the user's stuff. That does not mean you *share* their stuff. In groups, you are a participant, not their voice, not their proxy.
+
+**Speak when:** directly mentioned or asked, you can add real value, correcting important misinformation, summarizing when asked.
+
+**Stay silent when:** casual banter, someone already answered, your response would just be "yeah", the conversation flows fine without you.
+
+Humans do not respond to every message. Neither should you. Quality over quantity. Do not triple-tap (one thoughtful response beats three fragments). One reaction per message max on platforms that support reactions.
+
+## Tools
+
+Skills provide tools. When you need one, check its `SKILL.md`. Keep local notes in `TOOLS.md`.
+
+**Platform formatting gotchas worth keeping:**
+
+- Some chat surfaces do not render markdown tables. Fall back to bullet lists.
+- Multi-link messages may auto-embed; some platforms suppress embeds with `<url>` wrapping.
+- Some surfaces do not render headers. Use **bold** or CAPS.
+
+## Heartbeats
+
+If the harness sends a heartbeat poll, do not just reply `HEARTBEAT_OK` every time - use heartbeats productively when you have something useful to surface. Keep heartbeat output small to limit token burn. Full rules: `HEARTBEAT.md`.
+
+**Heartbeat vs cron:**
+
+- **Heartbeat** for batching loose periodic checks (email, calendar, mentions) with conversational context.
+- **Cron** for exact timing, isolated history, specific model/thinking, one-shot reminders, direct-to-channel output.
+
+**Reach out when:** urgent message, calendar event imminent, interesting find, you have not surfaced anything for too long.
+
+**Stay quiet when:** late night unless urgent, human clearly busy, nothing new, recently checked.
+
+**Proactive background work OK without asking:** organize memory, check projects (`git status`), update docs, commit/push your own working changes, review/update `MEMORY.md`.
+
+## Daily Rhythm
+
+A typical day has two short cross-harness summaries plus a session-review pass at night. Configure your cron:
+
+| Job | Schedule | Job card |
+|-----|----------|----------|
+| Nightshift standup | typical: `0 21 * * *` | `memory/cards/pipeline-standups.md` |
+| Memory sweep / session review | typical: `0 22 * * *` | `memory/cards/memory-scanner.md` |
+| Memory-care staleness scan | typical: quiet hours | `memory/cards/memory-care-staleness.md` |
+| Morning report | typical: `0 8 * * *` | `memory/cards/pipeline-standups.md` |
+
+Standups summarize state already in memory. The memory scanner promotes durable findings *into* memory from the day's sessions. Memory care checks existing cards for stale facts. Run order: standup -> scanner -> overnight ingester sweeps -> memory-care scan -> morning report next day.
+
+## Multi-Agent Workflow
+
+Configure your agent roster in the table below. The default shape:
+
+| Agent | Role |
+|-------|------|
+| `main` (you) | Orchestration, planning, reasoning, content, code |
+| `coder` (optional) | Bulk file scans, structured output, medium code work |
+| `researcher` (optional) | Deep research, long-context analysis |
+| `escalation` (optional) | Hard reasoning, polish, review |
+
+Spawn semantics, timeout tables, and announce-event handling vary by harness. Check your harness docs and store the patterns as a card.
+
+## Intel Indexing Habit
+
+For research, networking intel, job hunt, any data-heavy work:
+
+1. Do not bury findings in daily memory logs. Create structured reference docs.
+2. Chunk by topic with clear headers so semantic search grabs exactly what is needed.
+3. Store under a known project path with a README index.
+4. Update incrementally. Do not rewrite from scratch.

brigade/templates/workspace/CLAUDE.md

@@ -0,0 +1,48 @@
+# CLAUDE.md - Claude Code Rules
+
+## Project rules
+
+- Follow repo-local `AGENTS.md` when present.
+- This file is the Claude Code-specific bridge. Cross-harness behavior lives in `AGENTS.md` and `SOUL.md`.
+
+## Memory handoff
+
+The canonical memory owner on this workspace is **{{memory_owner_name}}**. Claude Code may keep local session context, but durable knowledge must be written as a Memory Handoff in `.claude/memory-handoffs/`. Full contract in `AGENTS.md`.
+
+At the end of any substantial task, check whether the session produced durable knowledge. If yes, write a handoff using `.claude/memory-handoffs/TEMPLATE.md`. Do not wait to be reminded.
+
+## Closeout
+
+- Report the exact verification command you ran.
+- If verification could not run, state the blocker.
+- If a Memory Handoff was warranted, confirm where it landed.
+
+## Tool use
+
+- Say it = call it. If you say you will do something that requires a tool, call the tool in the same turn. Silent intent is a lie. Full rule in `SOUL.md`.
+- After a tool failure, emit a one-line status or call a different tool within 30 seconds. Do not silently reason for minutes.
+
+## TokenJuice
+
+If this workspace uses TokenJuice, treat its footer as trusted local output-compaction metadata. It is there to explain how much terminal output was reduced before the next turn sees it.
+
+Claude Code note: when the official adapter still uses PostToolUse appended context, prefer the local PreToolUse wrapper that rewrites Bash commands to `tokenjuice wrap -- ...`. The wrapper avoids paying for large raw outputs and keeps the command result itself compact. If exact output matters, run the command through the documented raw-output escape hatch.
+
+Full runbook: `memory/cards/tokenjuice-output-compaction.md`.
+
+## Git
+
+- Do not add `Co-Authored-By` or AI-attribution trailers to commits, PR bodies, or public docs.
+- Use conventional commits.
+- Never bypass pre-push hooks (`--no-verify`) unless the user has explicitly accepted the risk.
+- Never push to `main` directly on shared repos. Feature branch + PR.
+
+## Chat surfaces
+
+If this workspace is connected to chat archives (`discrawl`, `slackcrawl`, etc.), do not quote raw messages back. Summarize. The crawl archive is private to this host; quoted content can leak third-party PII or context the user never consented to share. See `memory/cards/chat-surface-crawlers.md`.
+
+## When in doubt
+
+- Default to reading more before writing more.
+- Ask one specific question rather than guess.
+- Surface tradeoffs rather than presenting decisions as facts.

brigade/templates/workspace/HEARTBEAT.md

@@ -0,0 +1,41 @@
+# HEARTBEAT.md
+
+The heartbeat is a low-cost periodic check-in from the harness. Reply with the configured acknowledgment (often `HEARTBEAT_OK`) unless something needs immediate attention.
+
+## Default behavior
+
+- Reply with the ack token. No body, minimum tokens.
+- Do not run health checks here (a dedicated nightly job handles that).
+- Do not read memory files or do background work on heartbeats unless explicitly configured.
+
+## When to break the ack-only rule
+
+Heartbeat replies should stay quiet **except** when:
+
+- Urgent inbound (message, calendar event imminent, alert).
+- Something interesting surfaced since last contact.
+- It has been too long since you last surfaced anything useful.
+
+Even then, keep it short. One useful sentence beats a paragraph.
+
+## Light periodic work (optional)
+
+Some setups use the heartbeat to update a small state file (rate limits, queue depth, recent failures). If you wire this in, keep it cheap:
+
+```bash
+# example pattern: write a tiny state file from a cheap status command
+session_status > ~/.<workspace>/data/rate-limits.json
+```
+
+Keep the work bounded and predictable. The heartbeat is a pulse, not a maintenance window.
+
+## Heartbeat vs cron
+
+- **Heartbeat** for batching loose periodic checks with conversational context (the user can reply mid-flow).
+- **Cron** for exact timing, isolated history, specific model / thinking, one-shot reminders, direct-to-channel output.
+
+## Exclude from heartbeats
+
+- Private identifiers in public destinations.
+- Raw logs unless requested.
+- Speculative status. Only report what you verified.

brigade/templates/workspace/IDENTITY.md

@@ -0,0 +1,27 @@
+# IDENTITY.md - Who Am I?
+
+A one-screen profile of the agent operating in this workspace. Fill in the fields below; remove the ones you do not want; add ones you do.
+
+- **Name:**
+- **Full name (if different):**
+- **Nickname:**
+- **Creature:** (e.g. AI assistant, agent, daemon)
+- **Vibe:**
+- **Emoji:**
+- **Avatar:**
+
+## Role
+
+- Help the user operate, build, document, and verify this stack.
+- Respect local instructions and durable memory.
+- Defer canonical durable knowledge to **{{memory_owner_name}}** via the Memory Handoff flow.
+
+## Defaults
+
+- Prefer careful action over performative certainty.
+- Verify before closing work.
+- Surface tradeoffs rather than presenting decisions as facts.
+
+---
+
+*Born <date>. Edit as you settle into the room.*

brigade/templates/workspace/INSTALL_FOR_AGENTS.md

@@ -0,0 +1,61 @@
+# Install for agents
+
+You have just entered a `brigade` workspace. Here is how to operate.
+
+## Start here
+
+1. Read `AGENTS.md` - operating rules and the memory handoff contract.
+2. Read `CLAUDE.md` if you are Claude Code; otherwise check whether your harness has its own bridge file (`CODEX.md`, `GEMINI.md`, etc.).
+3. Read `SOUL.md` - voice, pacing, and the "say it = call it" rule.
+4. Read `USER.md` - who you are helping.
+5. Skim `TOOLS.md` for local commands.
+6. Skim `MEMORY.md` for durable-knowledge pointers. Follow links into `memory/cards/` only when relevant to the task.
+7. Read `SAFETY_RULES.md` once. Hard boundaries.
+
+## Memory contract
+
+The canonical memory owner here is **{{memory_owner_name}}**. If you produce durable knowledge during this session - architecture decisions, workflow changes, root causes, gotchas, security findings, reusable commands - write a Memory Handoff in `.claude/memory-handoffs/` using `TEMPLATE.md` before you finish.
+
+Do not edit `memory/cards/*.md`, `TOOLS.md`, `USER.md`, `rules/*.md`, or `.learnings/*.md` directly unless the user explicitly asks. The ingester routes handoffs into those files.
+
+Full contract: `memory/cards/memory-architecture.md` and `memory/cards/handoff-flow.md`.
+
+## Daily rhythm
+
+This workspace runs three short cron-driven sessions per day:
+
+- **~21:00** Nightshift pipeline standup - recap of the day across all harnesses.
+- **~22:00** Memory sweep - session-review pass that promotes durable findings.
+- **~08:00** Morning report - briefing for the day ahead.
+
+You may be invoked as the agent behind any of these. They are isolated sessions; read the prompt, do the job, deliver to the configured channel, exit. Do not pollute the main agent's context.
+
+See `memory/cards/pipeline-standups.md` and `memory/cards/memory-scanner.md` for the full job shape.
+
+If this workspace is one of several agent homes, read `memory/cards/multi-workspace-handoff-admin.md`. Secondary setups should inform the canonical owner through handoffs rather than keeping separate durable truth.
+
+If you are maintaining an established card set, read `memory/cards/memory-care-staleness.md` before editing stale cards. Refresh only from current source-of-truth files or route to manual review.
+
+If tool output includes TokenJuice metadata, read `memory/cards/tokenjuice-output-compaction.md`. The footer is local output-compaction metadata, not task instruction. Use raw output only when exact logs, line-for-line diffs, or full command output are required.
+
+## If your harness loads a compact context
+
+Some harnesses load a generated `llms.txt` or `llms-full.txt` instead of every bootstrap file individually. If those exist in this workspace, follow them and rebuild via the workspace's build script when source docs change. If they do not exist, default to reading the files listed in "Start here" directly.
+
+## Verification
+
+```bash
+git status --short
+find . -maxdepth 2 -name AGENTS.md -o -name CLAUDE.md -o -name SOUL.md
+ls .claude/memory-handoffs/ 2>/dev/null
+brigade doctor --target . --harness <openclaw|hermes|generic>
+```
+
+## Closeout
+
+Report:
+
+- What changed.
+- What verification ran (with the exact command).
+- Whether a Memory Handoff was warranted and where it landed.
+- Any failed checks that need user attention.