Agent System

The shop repo runs a multi-tenant agent system on top of Claude Code. Each agent is a distinct identity — with its own persona, constraints, and learned preferences — that loads on demand when you invoke a skill.

How It Works

Every skill (like /dev or /tutor) follows the same bootstrap sequence:

1. The skill loader reads the agent's persona (agent/<name>/system.md) — who it is, how it behaves, what it can and cannot do.
2. It loads shared preferences (agent/shared/preferences.md) — conventions that apply across all agents.
3. It loads agent-specific preferences (agent/<name>/preferences.md) — learned behaviors unique to that agent.
4. The agent executes the task with its full identity in context.

Agents

Three agents cover different modes of work:

Agent	Purpose	Skills	Can edit files?
Dev	Implement features, review code, debug, maintain logs	9 skills	Yes (most)
Tutor	Explain concepts, teach patterns, answer questions	3 skills	No (sessions only)
Student	Solve assignments, produce student-level work	2 skills	Yes

All Skills

Skill	Agent	Description
/dev	Dev	General development tasks
/dev-review	Dev	Read-only code review
/dev-debug	Dev	Investigate and fix issues
/dev-standup	Dev	Daily log from git activity
/dev-test	Dev	Write and run tests
/dev-retro	Dev	Weekly/sprint retrospective
/dev-refactor	Dev	Restructure without changing behavior
/dev-blog	Dev	Write a dev blog post
/tutor	Tutor	Explain concepts with Socratic method
/tutor-explain	Tutor	Walk through code section by section
/tutor-save	Tutor	Save/checkpoint tutor session
/student	Student	Solve assignments as a CS undergrad
/student-review	Student	Grade papers against a rubric
/remember	Utility	Save a lasting preference

Preferences

Preferences are append-only markdown bullets stored in preferences.md files. They accumulate over time as agents learn how you work.

• Shared (agent/shared/preferences.md) — conventions all agents follow (code style, log format, branch rules).
• Agent-specific (agent/<name>/preferences.md) — behaviors unique to one agent (tone, process, formatting).

Preferences are added two ways:

1. Explicitly — run /remember [scope] <preference> to append a specific convention.
2. Automatically — when you correct an agent's behavior, it detects lasting preferences and appends them to the right file.

See Utilities for details on the /remember skill and preference system.

Adding a New Agent

1. Create agent/<name>/system.md with persona, constraints, and workflow.
2. Create agent/<name>/preferences.md as an empty template.
3. Create skill files in .claude/skills/<name>*/SKILL.md.
4. Add the agent to the table in CLAUDE.md.