Bot Stamp

A self-bootstrapping .bot/ directory structure that gives any AI coding agent persistent context, memory, and identity within a repository.

What It Does

When you tell your AI agent to "bot stamp this repo," it creates a .bot/ directory with structured files that make the agent smarter over time:

• INTAKE.md — Project context the agent loads on every session
• PURPOSE.md — Mission, success criteria, standing orders, and non-goals
• SOUL.md — Agent personality and voice (optional but fun)
• mistakes.md — Log of things that went wrong and how they were fixed
• working_summary.md — Session handoff: what was happening, what's next
• setup.sh — One-time environment setup
• memory/ — Persistent memory that survives across sessions
• projects/ — Deliverable tracking per workstream

It also rewrites CLAUDE.md (or your agent's equivalent instruction file) to reference these files and enforce a session startup ritual.

Quick Start

Tell your AI coding agent:

Read the bot-stamp repo README at github.com/sequel-data/bot-stamp and follow the instructions to stamp this repo.

That's it. The agent reads this file and does the rest.

---

Instructions for AI Agents

You are being asked to "bot stamp" the current repository. Follow these steps exactly.

Step 1: Analyze the Repository

Before creating any files, understand the repo:

1. Read the existing README, CLAUDE.md, and any documentation
2. Check git log --oneline -20 for recent activity
3. Identify: project name, language/framework, purpose, and who works on it
4. Ask the user to fill in anything you can't determine (customer name, contacts, etc.)

Step 2: Create the .bot/ Directory Structure

Create all of the following files. Replace {{placeholders}} with real values from Step 1.

.bot/INTAKE.md

# Project Intake

## Customer

- **Name:** {{customer or org name}}
- **Industry:** {{industry}}
- **Key contacts:**
  - {{name}} — {{role}}
- **Relationship notes:** {{context about the relationship}}

## Project

- **Project name:** {{project name}}
- **One-line summary:** {{what this project does in one sentence}}
- **Start date:** {{date}}
- **Target completion:** {{date or "Ongoing"}}
- **Related repos:**
  - {{org/repo-name}} — {{one-line description of relationship}}

## Background

{{2-3 paragraphs: why this project exists, what problem it solves, relevant history}}

## Scope

**In scope:**
- {{list what this agent should help with}}

**Out of scope:**
- {{list what this agent should NOT do}}

## Tech Stack

- **Languages:** {{languages used}}
- **Frameworks:** {{frameworks}}
- **Infrastructure:** {{hosting, CI/CD, etc.}}
- **Tools:** {{CLI tools, package managers, etc.}}

## Acceptance Criteria

- [ ] {{measurable outcome 1}}
- [ ] {{measurable outcome 2}}

.bot/PURPOSE.md

# Purpose

## Mission

{{One paragraph: what this agent is here to do for this project}}

## Success Looks Like

- {{observable outcome 1}}
- {{observable outcome 2}}
- {{observable outcome 3}}

## Standing Orders

<!-- Persistent behavioral preferences that apply across all sessions and tasks. -->
<!-- These steer the agent's judgment when no specific instruction applies. -->

- {{e.g., "Always prefer readability over cleverness"}}
- {{e.g., "When in doubt, ask — don't guess"}}
- {{e.g., "Prefer editing existing files to creating new ones"}}

## Non-Goals

- We are NOT trying to {{thing that's out of scope}}
- We are NOT building {{thing that would be scope creep}}

.bot/SOUL.md

# Soul

## Identity

{{Who is this agent? A name, a personality archetype, or just "a focused engineering assistant for {{project}}"}}

## Personality Traits

- {{trait 1 — e.g., "Concise and direct — the user reads on mobile"}}
- {{trait 2 — e.g., "Technical precision over hand-waving"}}
- {{trait 3 — e.g., "Asks clarifying questions rather than guessing"}}

## Voice

- {{how the agent communicates — e.g., "Short sentences. No fluff. Lead with action."}}

.bot/setup.sh

#!/bin/bash
# One-time setup for this project's tooling.
# Run once per machine, not per session.

set -e

echo "=== Bot Stamp Setup ==="

# Check for project-specific tooling
# Add checks for your project's requirements here.
# Examples:

# Node.js
if command -v node &>/dev/null; then
  echo "[ok] Node $(node --version)"
else
  echo "[warn] Node.js not found"
fi

# Python
if command -v python3 &>/dev/null; then
  echo "[ok] Python $(python3 --version 2>&1)"
else
  echo "[warn] Python 3 not found"
fi

# Git
if command -v git &>/dev/null; then
  echo "[ok] Git $(git --version)"
else
  echo "[warn] Git not found"
fi

echo ""
echo "=== Setup complete ==="

.bot/memory/MEMORY.md

# Project Memory Index

<!-- This file is the index of all project memories. Each entry is one line, under 150 chars. -->
<!-- Memory files live in this directory. Add entries as you learn things. -->
<!-- This file is loaded at session start to give context about the project. -->

.bot/mistakes.md

# Mistakes & Corrections

<!-- The highest-value memory file. Load this on every session start. -->
<!-- If you only read one file, read this one — it prevents repeat failures. -->

## Mistakes

<!-- Log: what you tried, what broke, what fixed it, and the rule going forward. -->
<!-- Format: "Tried X → broke Y → fix was Z → Rule: never do X again." -->

## Corrections

<!-- User corrections that override default behavior. -->
<!-- Format: "User said: don't do X. Why: reason. Rule: do Y instead." -->

.bot/working_summary.md

# Working Summary

<!-- Updated at the end of every session. Makes recovery instant. -->

## Last Session

- **Date:** {{date}}
- **What I was doing:** {{brief description of task in progress}}
- **What's done:** {{completed items}}
- **What's next:** {{immediate next steps}}
- **Open questions:** {{unresolved decisions or blockers}}
- **State to preserve:** {{branch name, uncommitted files, running processes, etc.}}

.bot/projects/README.md

# Project Deliverables

Each file in this directory tracks one project/workstream.
Create a new file per project using the template below.

## Template

{{Project Name}}

Status: {{active | paused | completed | cancelled}}

Overview

• Started: {{date}}
• Target: {{date}}
• Lead: {{who owns this}}
• Priority: {{high | medium | low}}

Objective

{{One paragraph: what are we delivering and why}}

Deliverables

• Deliverable 1
• Deliverable 2

Acceptance Criteria

• Criterion 1
• Criterion 2

Decisions Log

Date	Decision	Rationale

Notes

Step 3: Update CLAUDE.md

Create or rewrite CLAUDE.md at the repo root. This is the file that Claude Code (and compatible agents) load automatically on every session.

The CLAUDE.md must include these sections:

# {{Project Name}}

## Soul

See .bot/SOUL.md for personality and voice.

## Purpose

See .bot/PURPOSE.md for mission and goals.
See .bot/INTAKE.md for project context, scope, and tech stack.

## Learning Flywheel

This repo gets smarter over time. Every session should leave the project better than it found it.

1. **On session start:** Read `.bot/INTAKE.md`, `.bot/mistakes.md`, `.bot/working_summary.md`, and `.bot/memory/MEMORY.md` to load context
2. **During work:** Save to `.bot/memory/` when any of these triggers fire:
   - You hit an unexpected error
   - The user corrects your approach
   - You discover a non-obvious dependency or constraint
   - A test fails for a surprising reason
   - An API behaves differently than documented
   - A config value has a non-obvious default or side effect
3. **On mistakes:** When something breaks, log it in `.bot/mistakes.md` immediately — format: "Tried X → broke Y → fix was Z → Rule: never do X again."
4. **On correction:** When the user says "don't do X" or "that's wrong," log it in `.bot/mistakes.md` under Corrections — format: "User said: don't do X. Why: reason. Rule: do Y instead."
5. **On task completion:** If acceptance criteria in INTAKE.md were met, check them off. Update project files in `.bot/projects/`.
6. **On session end:** Update `.bot/working_summary.md` with what you were doing, what's done, what's next, and any open questions. Update `.bot/memory/MEMORY.md` with anything learned.

## Memory

This project uses a persistent memory system in `.bot/memory/`.
Read `.bot/memory/MEMORY.md` for the index of what's been learned.

## Session Startup (MANDATORY)

On every session start:
1. Read `.bot/INTAKE.md` for project context
2. Read `.bot/mistakes.md` to avoid repeat failures
3. Read `.bot/working_summary.md` to resume where you left off
4. Read `.bot/memory/MEMORY.md` to load accumulated knowledge

## Project Tracking

Each workstream is tracked in `.bot/projects/`. See `.bot/projects/README.md` for the template.

## Boundaries

- Do not expose secrets, API keys, or credentials under any circumstances
- Never guess about APIs — verify first

Add any repo-specific sections (coding conventions, deployment methods, test commands, etc.) below these standard sections.

Important: If a CLAUDE.md already exists, preserve any existing repo-specific content and merge it with the bot stamp sections. Do not delete useful existing instructions.

Step 4: Update .gitignore

Add these lines if not already present:

# Bot stamp — ignore sensitive/ephemeral files
.env
*.env

Memory files are committed by default — they are the accumulated value of the agent's work and should survive machine failures, re-clones, and team sharing. If specific memory files contain ephemeral scratch notes, add them to .bot/memory/.gitignore on a case-by-case basis.

Step 5: Verify

After creating all files:

1. Confirm all 8 .bot/ files exist
2. Confirm CLAUDE.md references .bot/ files (including mistakes.md and working_summary.md)
3. Confirm .gitignore has the bot stamp entries
4. Report what you created and what the user should review

---

File Tree

When complete, the repo should contain:

repo/
  .bot/
    INTAKE.md          # Project context (includes related repos)
    PURPOSE.md         # Mission, standing orders, and goals
    SOUL.md            # Agent identity
    mistakes.md        # Mistakes log and user corrections
    working_summary.md # Session handoff state
    setup.sh           # One-time setup
    memory/
      MEMORY.md        # Memory index
    projects/
      README.md        # Tracking template
  CLAUDE.md            # Auto-loaded agent instructions

FAQ

Q: What if I don't use Claude Code? A: The .bot/ directory is agent-agnostic. The CLAUDE.md file is specific to Claude Code, but you can create an equivalent for your agent (e.g., .cursorrules, AGENTS.md, or whatever your tool reads on startup). The key idea is the same: structured project context that loads automatically.

Q: Should I check .bot/ into git? A: Yes — everything. Memory files, mistakes, working summary, all of it. These are the accumulated value of your agent's work. They should survive machine failures, re-clones, and team onboarding. Only .env files are gitignored by default.

Q: Can I customize the structure? A: Absolutely. This is a starting point. Add sections to INTAKE.md for your domain, expand the memory system, add more project templates. The structure is intentionally simple so it's easy to extend.

Q: What about the SOUL.md — is that serious? A: It's optional but useful. Even if you don't want a persona, defining voice and communication style ("be concise," "lead with code," "ask before assuming") measurably improves agent behavior.

Q: Can I set up a /stamp slash command so I don't have to paste the URL? A: Yes. In Claude Code, add a skill definition to your agent's .claude/settings.json or global settings that reads this repo's README and executes the stamping instructions. The exact wiring depends on your agent framework — the key is to make the stamp invocable by name rather than requiring the user to paste a GitHub URL each time.

License

MIT