# TEAMMATE.md - TEAMMATE Subsystem (Embedded)
**Authority:** subsystem (REAL)
**Layer:** Operational
**Binding:** No
**Quick Reference:**
| `decapod data teammate add --category git --key ssh --value "mine"` | Record a preference |
| `decapod data teammate get --category git --key ssh` | Retrieve a preference |
| `decapod data teammate list` | List all preferences by category |
---
## CLI Surface
```bash
decapod data teammate add --category <cat> --key <key> --value <val> [--context <ctx>] [--source <src>]
decapod data teammate get --category <cat> --key <key>
decapod data teammate list [--category <cat>] [--format text|json]
decapod data teammate schema # JSON schema for programmatic use
```
## Purpose
The teammate plugin catalogs distinct user expectations that persist across sessions, helping AI agents work more effectively with their human collaborators. It transforms one-off instructions into remembered behaviors.
### Why This Matters
Without the teammate plugin:
- User has to repeat "use my SSH key" on every commit
- Agent forgets preferred branch naming conventions
- Code style preferences must be re-explained each session
- Workflow requirements are lost between contexts
With the teammate plugin:
- Preferences are recorded once, remembered always
- Agents check before acting
- Consistent behavior across all interactions
- Builds a profile of how the user likes to work
### Example Use Cases
**Git Preferences:**
```bash
# User says: "always use my SSH key, don't add yourself as a contributor"
decapod data teammate add --category git --key ssh_key --value "use_mine" \
--context "Use user's SSH key for git operations, don't add self as contributor" \
--source "user_request"
# User says: "keep commit messages concise and imperative"
decapod data teammate add --category style --key commit_messages --value "concise_imperative" \
--context "Keep commit messages under 72 chars, use imperative mood" \
--source "user_request"
```
**Workflow Conventions:**
```bash
# User says: "use feature/ prefix for branches"
decapod data teammate add --category workflow --key branch_naming --value "feature/descriptive-name" \
--context "Prefix feature branches with feature/ followed by kebab-case description" \
--source "user_request"
```
## Categories
Standard categories for organizing preferences:
| `git` | Version control preferences | `ssh_key`, `commit_style`, `branch_naming`, `merge_strategy` |
| `style` | Code and documentation style | `commit_messages`, `comment_style`, `naming_conventions` |
| `workflow` | Development workflow | `pr_process`, `testing_requirements`, `review_style` |
| `communication` | Interaction preferences | `verbosity`, `technical_depth`, `update_frequency` |
| `tooling` | Tool-specific preferences | `formatter`, `linter`, `editor_settings` |
### Choosing Categories
- Use existing categories when possible
- Create new categories only for distinct domains
- Keys should be specific within a category
- Values should be actionable by agents
## Preference Lifecycle
### Recording Preferences
When a user expresses a preference:
1. **Capture immediately**: Record while context is fresh
2. **Be specific**: `commit_message_format` not just `style`
3. **Provide context**: Include the "why" not just the "what"
4. **Note the source**: User requests override observed behaviors
```bash
# Good: Specific, contextual, actionable
decapod data teammate add --category git --key ssh_contributor --value "user_only" \
--context "Use user's SSH credentials, never add self as commit contributor" \
--source "user_request"
# Bad: Vague, no context
# decapod data teammate add --category style --key prefs --value "good"
```
### Retrieving Preferences
Agents MUST check preferences before acting:
```bash
# Before committing, check SSH preference
decapod data teammate get --category git --key ssh_contributor
# Before creating a branch, check naming convention
decapod data teammate get --category workflow --key branch_naming
```
### Updating Preferences
Preferences can be updated by recording again with the same category/key:
```bash
# User changes their mind about commit style
decapod data teammate add --category style --key commit_messages --value "detailed_explanatory" \
--context "Now prefer detailed commit messages with full context" \
--source "user_request"
```
## Storage Model
Preferences are stored in `teammate.db` with full audit trail:
| `id` | Unique ULID identifier |
| `category` | Preference category |
| `key` | Preference name (unique within category) |
| `value` | Preference value |
| `context` | Optional explanation |
| `source` | How learned: `user_request`, `observed_behavior`, etc. |
| `created_at` | When first recorded |
| `updated_at` | When last modified |
The `(category, key)` combination is unique - recording again updates the existing preference.
## Agent Guidelines
### Do
- **Check before acting**: Always query relevant preferences before operations
- **Record when learned**: When user expresses a preference, record it immediately
- **Be specific**: Use clear, descriptive keys
- **Provide context**: Explain why the preference matters
- **Respect the source**: User requests take precedence over observed behaviors
### Don't
- **Don't assume**: Never assume preferences without checking
- **Don't ignore**: When user states a preference, don't ignore it
- **Be vague**: Avoid generic keys like `prefs` or `settings`
- **Skip context**: Context helps future agents understand the preference
### Example Workflow
```bash
# User asks to commit something
# 1. Check for git preferences
decapod data teammate get --category git --key ssh_contributor
# Returns: use user's SSH, don't add self as contributor
# 2. Check commit style
decapod data teammate get --category style --key commit_messages
# Returns: concise and imperative
# 3. Perform action respecting preferences
git commit -m "feat: add teammate plugin" # Using user's SSH
# 4. User expresses new preference
# User: "always push to ahr/work branch"
decapod data teammate add --category git --key default_push_branch --value "ahr/work" \
--context "Default branch for pushing work" \
--source "user_request"
```
---
**See also:** `core/PLUGINS.md` for subsystem registry and truth labels.