- Session start step 0: read USER.md at workspace root if present - Read once at session start, not on re-anchors - ~30 token cost - USER.md.template added - README updated
3.2 KiB
SmallClaw
Structured development workflow for AI models. Keeps projects organized, prevents hallucination, stays token-efficient.
Works with small models (8B+). Scales to large ones.
What it does
Maintains a set of lightweight "brain files" so the model always knows:
- Where the project is (STATUS.md — ~50 tokens)
- What it's allowed to touch (CONTEXT.md — ~80 tokens)
- What happened before (SESSIONS.md — rolling log)
The model reads these at session start (~130 tokens), works within their boundaries, and updates them at session end. Git is the ground truth.
Project Tiers
| Tier | Source files | Brain files | Mandatory tokens |
|---|---|---|---|
| Nano | <5 | STATUS + CONTEXT + SESSIONS | ~130 |
| Small | 5–20 | + PLAN + ARCH + GLOSSARY + CHANGELOG | ~650 |
Choose at project init. Nano skips everything the model doesn't need for small scripts.
File Structure
your-project/
├── brain/
│ ├── STATUS.md ← ground truth (read first, always)
│ ├── CONTEXT.md ← file scope for current task
│ ├── SESSIONS.md ← rolling work log
│ ├── ARCH.md ← modules, file index, decisions (small tier)
│ ├── PLAN.md ← milestones (small tier)
│ ├── GLOSSARY.md ← domain terms (small tier)
│ └── CHANGELOG.md ← user-facing changes (small tier)
└── ...source files...
Quick Start
Install the skill:
mkdir -p /path/to/openclaw/skills/dev-project
cp SKILL.md /path/to/openclaw/skills/dev-project/SKILL.md
Then start a conversation:
"Start a new project — MyApp. Python CLI tool, 3 files. Gitea at git.example.com."
The model creates brain/, asks a few questions, and you're working.
User Guide
Read GUIDE.md — it teaches you how to communicate effectively with the model using this system. The skill teaches the model what to do; the guide teaches you how to get the best out of it.
USER.md
Optional file at workspace root (not inside brain/). If present, the model reads it once at session start to learn your name, pronouns, timezone, and formatting preferences. Shared across all projects in the workspace.
Copy USER.md.template and fill it in.
Key Design Decisions
- Git is ground truth. STATUS.md describes git state. If they disagree, git wins.
- CONTEXT.md is the scope enforcer. The model only edits files listed there.
- Mid-session re-anchoring. After 15+ tool calls, re-read STATUS.md and CONTEXT.md to prevent drift.
- SESSIONS.md rolls over. Max 10 entries; older ones move to archive. Keeps reads cheap.
- No learnings module. SmallClaw is deliberately simple. For error capture and self-improving features, see SmallClawPlus.
Forge Support
| Forge | Template dir |
|---|---|
| Gitea (primary) | .gitea/ |
| Forgejo | .forgejo/ |
| GitHub | .github/ |
See Also
- SmallClawPlus — adds dependency graph, error capture, learning system, self-reflection. For medium-small models (30B+) on larger projects.
- GUIDE.md — how to talk to the model effectively.