Team Directives

The /speckit.levelup command captures team conventions, patterns, and lessons learned as reusable knowledge packets. These directives persist across sessions and team members, ensuring consistent AI-assisted development.

Why Directives?

AI assistants start each session without your team's accumulated knowledge. Directives solve this by encoding team decisions into files that every /speckit.* command reads for context.

Without directives:

Developer A: "We always use kebab-case for file names" AI assistant: creates myComponent.tsx

With directives:

AI reads use-kebab-case.md directive AI creates my-component.tsx

Creating a Directive

/speckit.levelup We always use kebab-case for file names

The command walks you through:

1. Type — Convention, Pattern, Lesson, or Guideline
2. Description — What the directive says
3. Rationale — Why it matters (what goes wrong without it)
4. Trigger — When to apply it (conditions that activate it)
5. Examples — Good and bad examples
6. Exceptions — When it's OK to deviate

Directive Types

Type	Purpose	Example
Convention	How the team does things	"File names use kebab-case"
Pattern	Reusable implementation approach	"API endpoints: create request/response types first"
Lesson	What went wrong and how to avoid it	"Never use synchronous file I/O in request handlers"
Guideline	Best practice or quality standard	"All components must have accessibility tests"

Directive Format

Stored in .specify/memory/directives/{slug}.md:

# Team Directive: Use Kebab-Case for File Names

**Type**: convention
**Created**: 2026-02-24
**Scope**: all code
**Priority**: must

## Description
All file names in the project must use kebab-case (lowercase words separated by hyphens).

## Rationale
Consistent file naming prevents case-sensitivity issues across operating systems
and makes imports predictable.

## Trigger
When creating any new file in the project.

## Examples

### Good
- `user-profile.tsx`
- `api-client.ts`
- `date-formatter.test.ts`

### Bad
- `UserProfile.tsx`
- `apiClient.ts`
- `dateFormatter.test.ts`

## Exceptions
None. This applies to all files.

Directive Index

All directives are indexed in .specify/memory/directives/index.md. This index is read by every /speckit.* command for context.

Constitution Alignment

When creating a directive, the command checks if it:

Relationship	Action
Reinforces an existing constitution principle	Links the directive to the principle
Suggests a new principle	Recommends a constitution amendment
Conflicts with an existing principle	Flags for resolution

Over time, frequently-used directives should be promoted to constitution principles via /speckit.constitution.

Propagation

If a directive affects existing specs, the command:

1. Identifies which specs are affected
2. Generates refinement suggestions
3. Appends them to .specify/memory/refinement-suggestions.md
4. These suggestions surface when you run /speckit.refine

Examples

Convention: Error Response Format

/speckit.levelup All API error responses must follow the format: { error: string, code: string, details?: object }

Pattern: Feature Flag Implementation

/speckit.levelup When adding a new feature behind a flag, always use the ENABLE_* prefix in env vars and add the flag to .env.template with a default of false

Lesson: Database Migration Safety

/speckit.levelup Never drop columns in a single migration. Always use a two-step process: first deploy code that doesn't read the column, then drop it in a separate migration.

Guideline: Component Accessibility

/speckit.levelup All interactive UI components must include: ARIA labels, keyboard navigation, focus indicators, and minimum contrast ratio of 4.5:1