# Team capabilities
### Generic agents don't know your system

Out-of-the-box agents are impressive—until you need them to work with *your* codebase. They don't know:

- Your custom component library exists
- That all dropdowns should use `custom-dropdown.tsx`, not native `<select>`
- Your API conventions, naming patterns, or architectural decisions
- The tribal knowledge your team repeats in every code review

Without this context, agents produce technically correct but organizationally wrong outputs. You end up re-prompting the same instructions repeatedly—or worse, fixing the same mistakes in review.

> [!TIP]
> Team capabilities encode what your team already knows into prompts that agents always follow. No more "remember to use our custom dropdown" in every conversation.

**Who this is for:** Teams with established codebases, internal libraries, or domain-specific conventions. Solo developers building personal productivity packs. Anyone tired of repeating context to AI.

---

## The capability layering model

Valdr capabilities are designed to stack. Start with a generic foundation, then add team-specific overlays that encode your institutional knowledge.

```
┌─────────────────────────────────────────────┐
│  Team-specific capability                   │
│  "Always use custom-dropdown.tsx"           │
│  "Follow our API naming conventions"        │
├─────────────────────────────────────────────┤
│  Domain capability                          │
│  "TypeScript best practices"                │
│  "React component patterns"                 │
├─────────────────────────────────────────────┤
│  Base capability                            │
│  "Code review standards"                    │
│  "Testing requirements"                     │
└─────────────────────────────────────────────┘
```

Each layer adds specificity without replacing what's below. The agent inherits general best practices *and* your team's specific conventions.

### Pack naming conventions

The `pack` attribute groups related capabilities together. Valdr uses these conventions:

| Pack | Use for | Examples |
| --- | --- | --- |
| `valdr` | Valdr-provided capabilities and general-purpose prompts | `typescript.core`, `review.code` |
| `{team}` | Team-specific capabilities | `acme.ui.components`, `mycompany.api` |
| `{domain}` | Domain-specific packs you maintain | `healthcare.hipaa`, `fintech.compliance` |

**Default pack:** Use `pack="valdr"` for capabilities that follow Valdr's standard patterns and could be reused across projects. Use your team or domain name for capabilities encoding organization-specific knowledge.

> [!TIP]
> Pack names are normalized to lowercase. `pack="Valdr"` and `pack="VALDR"` both resolve to `valdr`.

---

## Example: TypeScript agent with UI specialization

### The problem

You have a TypeScript codebase with a custom component library. Every time you ask an agent to build UI, it:

- Uses native HTML elements instead of your components
- Ignores your design tokens
- Creates inconsistent patterns across the codebase

You keep saying "use our CustomDropdown" but it doesn't stick across sessions.

### The solution: capability layering

**Base agent:** Generic TypeScript capabilities

```markdown
<!--<capability id="typescript.core" pack="valdr" role="core">-->
# TypeScript Core

- Use strict TypeScript with explicit return types
- Prefer composition over inheritance
- Follow ESLint rules defined in the repo
<!--</capability>-->
```

**Team overlay:** UI component conventions

```markdown
<!--<capability id="acme.ui.components" pack="acme" role="context">-->
# ACME UI Component Standards

## Required components
Always use our custom components instead of native HTML or third-party libraries:

| Instead of | Use |
| --- | --- |
| `<select>` | `CustomDropdown` from `@acme/ui/custom-dropdown` |
| `<input type="text">` | `TextInput` from `@acme/ui/text-input` |
| `<button>` | `Button` from `@acme/ui/button` |
| `<dialog>` | `Modal` from `@acme/ui/modal` |

## Design tokens
- Colors: import from `@acme/tokens/colors`
- Spacing: use `spacing.sm`, `spacing.md`, `spacing.lg`
- Typography: use `Text` component with `variant` prop

## Component patterns
- All form fields must use `FormField` wrapper for consistent labels/errors
- Modals must include `aria-labelledby` pointing to the title
- Loading states use `Skeleton` component, not spinners
<!--</capability>-->
```

### The result

When you bind both capabilities to your TypeScript agent:

```yaml
capabilities:
  - typescript.core        # Generic foundation
  - acme.ui.components     # Team-specific overlay
```

The agent now *always* knows to use `CustomDropdown`. No repeated prompting. No review corrections. The institutional knowledge is baked in.

---

## What to encode in team capabilities

### Codebase conventions

- Component libraries and when to use each component
- API patterns (REST conventions, error handling, pagination)
- File/folder structure expectations
- Naming conventions (variables, files, routes)

### Architectural decisions

- State management patterns (Redux, Zustand, context usage)
- Data fetching strategies (React Query, SWR, custom hooks)
- Error boundary placement
- Feature flag conventions

### Quality standards

- Testing requirements specific to your stack
- Accessibility standards beyond WCAG defaults
- Performance budgets and optimization patterns
- Security practices for your domain

### Tribal knowledge

- "We tried X approach and it failed because Y"
- "Always check Z before deploying to production"
- "The legacy module requires special handling"
- Undocumented but critical integration points

---

## Capability examples by team type

### Frontend team

```markdown
<!--<capability id="acme.frontend.react" pack="acme" role="context">-->
# ACME React Conventions

## State management
- Global state: Zustand stores in `src/stores/`
- Server state: React Query with custom hooks in `src/hooks/queries/`
- Form state: React Hook Form with Zod validation

## Component structure
- Colocate styles with components using CSS modules
- Props interfaces exported from component file
- Storybook stories required for all shared components

## Testing
- Unit tests for hooks and utilities
- Integration tests for user flows using Testing Library
- E2E critical paths in Playwright
<!--</capability>-->
```

### Backend team

```markdown
<!--<capability id="acme.backend.api" pack="acme" role="context">-->
# ACME API Conventions

## Endpoint patterns
- RESTful routes: `/api/v1/{resource}/{id}`
- List endpoints return `{ data: [], meta: { total, page, limit } }`
- Errors return `{ error: { code, message, details } }`

## Database access
- All queries through repository pattern
- Use transactions for multi-table writes
- Soft deletes with `deleted_at` timestamp

## Authentication
- JWT validation middleware on all `/api/` routes
- Rate limiting: 100 req/min for authenticated, 20 for anonymous
- Audit logging for all write operations
<!--</capability>-->
```

### Platform/DevOps team

```markdown
<!--<capability id="acme.platform.infra" pack="acme" role="context">-->
# ACME Infrastructure Conventions

## Deployment
- All services deploy via GitHub Actions
- Staging auto-deploys on merge to `main`
- Production requires manual approval + tag

## Observability
- Structured logging with correlation IDs
- Metrics exposed on `/metrics` for Prometheus
- Distributed tracing with OpenTelemetry

## Secrets
- Never hardcode secrets; use environment variables
- Secrets stored in AWS Secrets Manager
- Rotate credentials quarterly
<!--</capability>-->
```

---

## Building your first team capability

### 1. Identify repeated instructions

Start with pain points:
- What do you keep telling the AI?
- What mistakes do reviewers catch repeatedly?
- What context does every new team member need?

### 2. Write the capability prompt

Keep it focused. One capability = one domain. Use tables for quick reference, prose for nuance. Don't try to encode everything at once—capabilities work best when they capture high-frequency, high-impact rules.

```markdown
<!--<capability id="yourteam.domain.focus" pack="yourteam" role="context">-->
# Your Team Domain Focus

## Quick reference
| Rule | Implementation |
| --- | --- |
| ... | ... |

## Detailed guidance
...
<!--</capability>-->
```

### 3. Register and bind

Register the capability in PM MCP, then bind it to relevant agents:

```yaml
# Agent charter binds capabilities
capabilities:
  - typescript.core           # Generic
  - review.code               # Generic
  - yourteam.domain.focus     # Team-specific
```

### 4. Iterate based on results

After a few sessions:
- Did the agent follow the new rules?
- Were there edge cases you didn't cover?
- Does the capability need to be split or combined?

Capabilities evolve with your team's knowledge.

---

## Why this matters

| Without team capabilities | With team capabilities |
| --- | --- |
| Repeat context every session | Context is always present |
| Inconsistent outputs across agents | Uniform adherence to standards |
| Review catches avoidable mistakes | Mistakes prevented at generation |
| New team members need onboarding | Knowledge is encoded and enforced |
| Tribal knowledge lives in heads | Tribal knowledge lives in prompts |

### The compound effect

Every capability you encode:
- Saves time on every future session
- Reduces review burden
- Improves consistency
- Captures knowledge that might otherwise be lost

Over time, your team builds a **capability library** that makes agents genuinely productive—not just impressive demos.

### Verified, not just declared

When team capabilities use [structured tags](../tag-system/), Valdr's [scoring system](../tag-system/scoring/) can verify that agents actually followed your conventions. You don't just *hope* the agent used your custom dropdown—you can *prove* it did.

---

## Sharing and evolving capabilities

### Within your team

- Store capabilities in your repo (`agents/prompts/team/`)
- Version alongside code
- Review changes like any other PR

### Across teams

- Extract common patterns into shared packs
- Publish to internal capability registry
- Let other teams benefit from your knowledge

### Contributing to the community

When you've battle-tested a capability:
- Generalize team-specific details
- Contribute to the open-source Valdr Packs repository
- Help others skip the learning curve you already climbed

---

## Getting started

1. **Audit your last 10 agent sessions** — what context did you repeat?
2. **Pick one high-frequency pain point** — start small
3. **Write a focused capability** — 50-200 words is often enough
4. **Bind it to your agent and test** — does behavior improve?
5. **Iterate and expand** — build your capability library over time

The goal isn't to encode everything on day one. It's to capture knowledge incrementally, turning your team's expertise into agent infrastructure.

The goal isn't to make agents smarter—it's to make them *aligned* with how you already work.

## Product view

Read [Team Capabilities for AI Agents](/valdr/docs/features/team-capabilities/) for the platform-level positioning behind this feature.