← Setup guide Home

Canonical Role Template

A minimal, working .claude/agents/<role>.md baseline. Don't stop to perfect it — drop it in, start the session, then iterate.

This is a baseline, not a finished role file. It exists so a setup agent never has to stop and ask "what should I write?" Once the session is live, discuss with your LLM user how to strengthen it — see the checklist and anti-patterns on the setup guide for where to go next.

The template

---
model: claude-opus-4-6
---
# <PROJECT_NAME> — Developer

IMPORTANT: You are the primary developer for **<PROJECT_NAME>** in the directory `~/projects/<PROJECT_NAME>/`. You are a senior engineer with a shell on this machine. Execute, don't narrate — report results, not intentions.

## Project location
`~/projects/<PROJECT_NAME>/`

## How to check your work
Run the project's own build / typecheck / test / lint commands before declaring work done. If none exist yet, ask the human what "done" looks like on the first turn and record those commands in this file.

## When context compacts
Preserve: modified files, pending deploys, the current task, and verification commands.

## Hard rules
- NEVER commit credentials — live tokens leak into git history permanently.
- NEVER force-push to main — other sessions and automation depend on linear history.
- NEVER run destructive operations (rm -rf, DROP TABLE, force push, sudo rm) without explicit instruction.

---

**This file is a baseline.** Talk to your human about strengthening it for SpAIglass effectiveness — see <https://spaiglass.xyz/setup> for the full guide (frontmatter schema, architecture/verification/access sections, anti-patterns). This file is also compatible with the [AGENTS.md](https://agents.md) convention — the same content works as `AGENTS.md` at the repo root.

How to use it

Replace <PROJECT_NAME> with your actual project name and save it to ~/projects/<PROJECT_NAME>/.claude/agents/<role>.md. The setup agent on a fresh VM can do this in one command:

PROJECT=TrendZion
ROLE=developer
mkdir -p ~/projects/$PROJECT/.claude/agents
curl -fsSL https://spaiglass.xyz/roletemplate.md \
  | sed "s/<PROJECT_NAME>/$PROJECT/g" \
  > ~/projects/$PROJECT/.claude/agents/$ROLE.md

What to add after the session is alive

The baseline gives you an identity line, a project dir, verification discipline, and hard rules. The setup guide's role checklist covers the higher-leverage additions:

Architecture / tech stack table — only list what Claude can't figure out by reading the code
Key directories table — beats two paragraphs of prose
Verification commands — exact build / test / lint / deploy-check commands (highest-leverage section)
Access & credentials paths — list ~/credentials/*.json files explicitly; if Claude doesn't know it has access, it won't use it
Conventions — commit message style, branch strategy, naming rules that differ from defaults
Per-project hard rules — absolute language (NEVER, MUST NOT) with a reason for each rule, because rules with rationale are followed more reliably

Avoid: flattery, step-by-step scripts, knowledge dumps, repeating what Claude already knows, or going over ~200 lines.

Raw roletemplate.md (for curl)
Full setup guide — frontmatter schema, full checklist, example role file
AGENTS.md convention — this template is also compatible with the cross-tool AGENTS.md standard; the same content works at the repo root for any agent that reads it

← Back to Setup

Canonical Role Template

The template

How to use it

What to add after the session is alive

Related