Team AI Directives Starter Kit

A forkable foundation for version-controlled AI agent behavior.

Built on the Twelve-Factor Agentic SDLC — this repository implements Factor XI: Directives as Code, treating all AI instructions as version-controlled assets.

Quick Start: See GETTING_STARTED.md for a 5-minute setup guide.

Installation

This repository can be installed in two ways:

Option 1: As a Spec Kit Extension (Recommended)

Install via the spec-kit CLI using the --team-ai-directives flag:

# Initialize project with team-ai-directives
specify init <project> --team-ai-directives https://github.com/your-org/team-ai-directives.git

The directives are installed to .specify/extensions/team-ai-directives/ and available to all AI agents via the extension system.

# Or from a specific release tag
specify init <project> --team-ai-directives https://github.com/your-org/team-ai-directives/archive/refs/tags/v1.3.0.zip

Option 2: Development (Fork and Clone)

Fork this repository and clone it locally for development or customization:

git clone https://github.com/your-org/team-ai-directives.git
cd team-ai-directives

Then reference it in your project initialization or configuration.

Who This Is For

Engineering teams wanting consistent AI agent behavior
Platform teams building developer self-service with AI
Consultancies creating reusable AI patterns across clients
Organizations adopting the Agentic SDLC methodology

What's Included

This repository provides the building blocks for teaching AI agents how your team works:

Constitution - Core principles that govern all AI behavior
Personas - Role-specific guidance (DevOps, Java, Python, Data, Platform)
Rules - Domain-specific patterns (security, testing, style guides)
Skills - Self-contained capabilities with trigger-based activation

Repository Layout

team-ai-directives/
├── AGENTS.md                  # Instructions for AI agents on how to use this repo
├── README.md                  # This file (for humans)
├── GETTING_STARTED.md         # Quick start guide
├── CONTRIBUTING.md            # Contribution guidelines
├── CHANGELOG.md               # Version history
├── CDR.md                     # Context Directive Records (approved contributions)
├── .mcp.json                  # MCP server configuration
├── .skills.json               # Skills registry and policy
├── context_modules/           # The knowledge library
│   ├── constitution.md        # Core principles
│   ├── personas/              # Role-specific guidance
│   ├── rules/                 # Domain-specific patterns
│   │   ├── style_guides/
│   │   ├── security/
│   │   └── testing/
│   └── examples/              # Code examples and prompt templates
│       ├── testing/
│       └── prompts/
└── skills/                    # Self-contained agent capabilities
    └── {skill-name}/
        ├── SKILL.md           # Main instructions with YAML frontmatter
        ├── references/        # Supporting content
        └── scripts/           # Automation (optional)

How It Works

AI agents read AGENTS.md for instructions on using this repo
Constitution provides foundational principles
Personas provide role-specific guidance with rule references
Skills are triggered by user requests (matched via .skills.json)
Rules are accessed through personas, not directly from skills

Personas

Personas define the role, expertise, preferences, and rule references that shape how an AI agent behaves for a given engineering context. Loading a persona tells the agent who it is for this session — its values, collaboration style, and which domain-specific rules to apply.

How Personas Work

When an agent begins a session, it loads context in this order:

Constitution (context_modules/constitution.md) — non-negotiable team principles applied to every interaction.
Persona (context_modules/personas/*.md) — role-specific defaults, rules, and collaboration style.
Skills (skills/*/SKILL.md) — on-demand capabilities triggered by the user's request.

A persona sits between the universal constitution and the task-specific skill. It tells the agent:

What domain knowledge to prioritize
Which rule files are relevant to its role
How to collaborate (communication style, review preferences, workflow assumptions)
Agent-specific guidance (e.g., always propose infra changes as code)

Personas are passive by default — they don't activate automatically unless your tooling or prompt instructs the agent to load one. You attach a persona to an agent through your IDE settings, a system prompt, or a prompt prefix.

Persona Folder Structure

All personas live in context_modules/personas/:

context_modules/personas/
├── cloud_native_platform_architect.md
├── data_analyst.md
├── devops_engineer.md
├── senior_java_developer.md
└── senior_python_developer.md

Each persona is a single Markdown file. There is no sub-folder nesting — one file per role.

Persona File Anatomy

A well-formed persona file contains some or all of the following sections:

`# Persona: <Name>` (required)

The heading names the persona. Agents use this as the persona identifier.

# Persona: DevOps Engineer

`## Summary` (required)

Describes the persona's motivation, pain points, and success criteria. This is the first context an agent reads to understand its role.

## Summary
- **Motivation**: Enable reliable, scalable, and secure software delivery through automation, IaC, and observability.
- **Pain Points**: Manual deployments, configuration drift, lack of visibility.
- **Success Criteria**: Fully automated CI/CD pipelines, declarative infrastructure, secure secret management.

`## Rule References` (recommended)

Links the persona to domain-specific rule files using the @rule:<path> syntax. Agents resolve these paths relative to context_modules/rules/.

## Rule References
- CI/CD Pipelines: @rule:devops/github_actions.md
- Secrets Management: @rule:devops/external_secrets_operator.md, @rule:devops/secrets_management_dry.md
- Testing: @rule:testing/python_testing.md

`## Collaboration Preferences` (recommended)

Describes how the persona prefers to work: communication style, review expectations, workflow assumptions, and advocacy positions.

## Collaboration Preferences
- Prefers infrastructure changes reviewed through pull requests with clear descriptions
- Values declarative configurations over imperative scripts
- Expects "everything as code" — infrastructure, configs, and pipelines in version control

`## Tool Context` (optional)

Lists the tooling ecosystem this persona operates in. Helps agents make appropriate technology choices without asking the user every time.

## Tool Context
- CI: GitHub Actions, GitLab CI
- CD/GitOps: ArgoCD, Flux
- IaC: Terraform, Crossplane
- Secrets: HashiCorp Vault, AWS Secrets Manager

`## Guidance for Agents` (optional)

Explicit behavioral instructions for agents taking actions on behalf of this persona.

## Guidance for Agents
- Always propose infrastructure changes as code, never manual operations
- When working with secrets, always use secret management services — never hardcode or commit secrets
- Always consider disaster recovery, backup strategies, and rollback procedures

Built-In Personas

File	Persona	Primary Domain
`senior_python_developer.md`	Senior Python Developer	Python, PEP 8, testing, CI/CD
`senior_java_developer.md`	Senior Java Developer	Java, Spring Boot, JUnit 5, Google Style
`devops_engineer.md`	DevOps Engineer	CI/CD, Helm, IaC, secrets management, GitOps
`cloud_native_platform_architect.md`	Cloud-Native Platform Architect	Kubernetes, Crossplane, ArgoCD, platform engineering
`data_analyst.md`	Data Analyst	SQL, dashboards, reproducible reporting, large datasets

Each built-in persona is self-contained and production-ready. Fork and adjust them to match your team's specific tooling and standards.

Creating a Custom Persona

Create a new file in context_modules/personas/:
```
touch context_modules/personas/my_role.md
```

Add the following template and fill it in:

# Persona: My Role

## Summary
- **Motivation**: [What drives this role]
- **Pain Points**: [What slows them down]
- **Success Criteria**: [What good looks like]

## Rule References
- [Domain]: @rule:[domain]/[rule-file].md

## Collaboration Preferences
- [How this persona prefers to work]

## Tool Context
- [Tools and platforms this persona uses]

## Guidance for Agents
- [Behavioral instructions for autonomous actions]

Reference any applicable rule files from context_modules/rules/. Browse the available rules:

context_modules/rules/
├── devops/
├── framework/
├── orchestration/
├── security/
├── style-guides/
└── testing/

Attach the persona in your agent configuration.

Using Personas

Option A: IDE Custom Instructions (GitHub Copilot)

In VS Code with GitHub Copilot, add the persona content directly to a .github/copilot-instructions.md file or reference it in your workspace settings:

// .vscode/settings.json
{
  "github.copilot.chat.codeGeneration.instructions": [
    { "file": "context_modules/personas/devops_engineer.md" }
  ]
}

Option B: System Prompt Prefix

Prepend the persona content to your agent's system prompt:

[Load persona: context_modules/personas/devops_engineer.md]

User request: ...

Option C: Prompt Reference at Session Start

Tell the agent explicitly which persona to adopt at the start of a conversation:

You are acting as the DevOps Engineer persona defined in
context_modules/personas/devops_engineer.md. Load that file
and apply it to all responses in this session.

Personas vs. Skills

	Persona	Skill
Purpose	Defines who the agent is	Defines what the agent can do
Scope	Entire session	Triggered per task
Location	`context_modules/personas/`	`skills/*/SKILL.md`
Activation	Loaded at session start	Loaded on-demand by trigger phrases
Registered in `.skills.json`?	No	Yes
Contains rules?	References rules via `@rule:`	May embed rules inline

A persona provides the stable identity and preferences for a session. Skills provide the domain-specific execution instructions for individual tasks. They complement each other and are both loaded alongside the constitution.

Skills

Skills are self-contained, reusable AI agent capabilities. Each skill packages a domain's instructions, context, and optional automation so an AI agent can reliably apply it on demand without requiring the user to supply background knowledge each time.

How Skills Work

When a user makes a request, an agent:

Reads .skills.json to discover available skills.
Matches the user's intent against each skill's description and trigger phrases.
Loads the relevant SKILL.md to obtain domain-specific instructions.
Optionally loads files from references/ for deeper context.
Applies the skill while completing the task.

Skills are loaded on-demand — only the skills relevant to the current request are activated. Required skills defined in .skills.json are always available to the agent.

Skill Folder Structure

All internal skills live under skills/{skill-name}/:

skills/
└── my-skill/
    ├── SKILL.md          # Required — primary instructions for the agent
    ├── references/       # Optional — supplementary reference documents
    │   ├── guide.md
    │   └── patterns.md
    └── scripts/          # Optional — automation scripts for the skill
        └── setup.sh

`SKILL.md`

The entry point for every skill. It uses a YAML front matter block to declare metadata, followed by Markdown instructions:

---
name: my-skill
description: >
  Short description of the skill's purpose.
  Use when [trigger phrases that describe when to activate this skill].
---

# My Skill

## What This Skill Provides
...

## When to Use This Skill
...

## Core Patterns
...

The description field is critical — it tells the agent when to activate the skill. Write it in natural language and include representative phrases a user might say.

The `.skills.json` Manifest

.skills.json is the single source of truth for skill discovery and policy. It defines which skills are required, recommended, internal, blocked, or available in the registry.

{
  "version": "1.0.0",
  "source": "team-ai-directives",
  "description": "Team skills manifest for the Skills Package Manager.",
  "skills": {
    "required": { ... },
    "recommended": { ... },
    "internal": { ... },
    "blocked": [ ... ]
  },
  "registry": {
    "description": "Additional skills available for manual discovery.",
    "skills": { ... }
  },
  "policy": { ... }
}

Skill Categories in `.skills.json`

Category	Meaning
`required`	Always loaded by the agent; auto-installed if `auto_install_required` is `true`
`recommended`	Suggested skills; surfaced to the agent but not mandatory
`internal`	Skills hosted locally in this repository
`blocked`	Skills explicitly prohibited; the agent must refuse to use them
`registry`	Additional skills available for on-demand discovery and installation

Skill Entry Format

Each skill entry in the manifest uses a URI as its key:

Local skill: "local:./skills/my-skill"
External skill: "github:org/repo/skill-name"

"local:./skills/my-skill": {
  "version": "*",
  "description": "Human-readable description of what the skill does.",
  "categories": ["tag1", "tag2"]
}

External skills add source and url fields pointing to the raw SKILL.md:

"github:org/repo/skill-name": {
  "version": "^1.0.0",
  "description": "...",
  "categories": ["..."],
  "source": "https://github.com/org/repo",
  "url": "https://raw.githubusercontent.com/org/repo/main/skills/skill-name/SKILL.md"
}

Configuring Skills

Adding a Local Skill

Create the skill folder and SKILL.md (see Creating a New Skill below).
Register the skill in .skills.json under the appropriate category:

"skills": {
  "required": {
    "local:./skills/my-skill": {
      "version": "*",
      "description": "What my skill does.",
      "categories": ["my-category"]
    }
  }
}

Adding an External Skill

External skills are fetched from a URL at runtime. Add them to recommended or registry:

"recommended": {
  "github:org/repo/skill-name": {
    "version": "^1.0.0",
    "description": "Short description with trigger phrases.",
    "categories": ["relevant", "tags"],
    "source": "https://github.com/org/repo",
    "url": "https://raw.githubusercontent.com/org/repo/main/skills/skill-name/SKILL.md"
  }
}

Blocking a Skill

To prevent an agent from using a specific skill (e.g., a deprecated or insecure external skill), add it to the blocked list:

"blocked": [
  {
    "id": "github:unsafe-org/deprecated-skill",
    "reason": "Security vulnerability - deprecated by maintainer"
  }
]

Creating a New Skill

mkdir -p skills/my-skill/references

Create skills/my-skill/SKILL.md:

---
name: my-skill
description: >
  Describe what the skill does. Use when the user asks to [action],
  [another action], or [trigger phrase].
---

# My Skill

## What This Skill Provides

Brief overview of the domain knowledge and capabilities this skill covers.

## When to Use This Skill

- Scenario 1
- Scenario 2

## Core Patterns

### Pattern Name

**Rule**: State the rule clearly.

**Implementation**:
- Step or detail
- Step or detail

**References**: See references/guide.md

Then register it in .skills.json.

Using Skills as an Agent

When processing a request, an agent resolves skills in this order:

Constitution — context_modules/constitution.md (always loaded).
Persona — relevant file from context_modules/personas/ based on task context.
Skill — triggered by matching the user's intent to a skill description.

To activate a skill manually, tell the agent which skill to use:

"Using the github-actions skill, create a reusable workflow for deploying to Kubernetes."

The agent will read skills/github-actions/SKILL.md and any referenced rule files before responding.

How Personas and Skills Work Together

A persona and one or more skills are loaded at the same time. They complement rather than duplicate each other.

For example, a DevOps Engineer session might look like:

Constitution — foundational team principles always apply
Persona: devops_engineer.md — sets the role identity, collaboration preferences, and tool context
Skill: github-actions — activated when the user asks about CI/CD pipelines
Skill: helm-charts — activated when the user asks about packaging for Kubernetes

The persona tells the agent who it is. The skills tell it how to execute specific tasks.

External Skills

External skills are fetched at runtime from their url field in .skills.json. They are not stored locally in this repository.

To discover registry skills, ask your AI agent:

"What skills are available in the registry?"

The agent will read .skills.json, list the registry entries, and describe when each is useful. To use one, the agent fetches the SKILL.md from the provided url.

Policy Settings

The policy section of .skills.json controls agent behavior:

"policy": {
  "auto_install_required": true,
  "enforce_blocked": true,
  "allow_project_override": true
}

Setting	Default	Description
`auto_install_required`	`true`	Required skills are automatically loaded without user prompting
`enforce_blocked`	`true`	The agent refuses to use any skill in the `blocked` list
`allow_project_override`	`true`	Individual projects can override manifest settings locally

Commands

The extension provides these commands for spec-kit integration:

Command	Purpose
`adlc.team-ai-directives.verify`	Health check - verifies extension installation, skills registry, CDR tracking, and constitution alignment
`adlc.team-ai-directives.discover`	Auto-discovers relevant personas, rules, and examples for the current feature
`adlc.team-ai-directives.constitution`	Loads team constitution principles before project constitution update

Hooks

The extension automatically runs commands via hooks:

Hook	Command	Description
`before_specify`	discover	Auto-discovers context for specification
`before_plan`	discover	Auto-discovers context for planning
`before_constitution`	constitution	Loads team principles before project constitution update

Run verification anytime:

specify run adlc.team-ai-directives.verify

Versioning

Use git tags (v1.0.0, v2.0.0, etc.) to manage breaking changes. Downstream consumers can pin to specific versions.

Customization

Fork this repository and customize:

Constitution - Add your team's principles
Personas - Define roles matching your team
Rules - Add domain-specific patterns
Skills - Create capabilities for your workflows
.mcp.json - Configure your MCP servers
.skills.json - Register your skills

Contributing

See CONTRIBUTING.md for guidelines. All changes require pull request review.

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
commands		commands
context_modules		context_modules
skills		skills
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.mcp.json		.mcp.json
.skills.json		.skills.json
AGENTS.md		AGENTS.md
CDR.md		CDR.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
GETTING_STARTED.md		GETTING_STARTED.md
README.md		README.md
extension.yml		extension.yml

Folders and files

Latest commit

History

Repository files navigation

Team AI Directives Starter Kit

Installation

Option 1: As a Spec Kit Extension (Recommended)

Option 2: Development (Fork and Clone)

Who This Is For

What's Included

Repository Layout

How It Works

Personas

How Personas Work

Persona Folder Structure

Persona File Anatomy

# Persona: <Name> (required)

## Summary (required)

## Rule References (recommended)

## Collaboration Preferences (recommended)

## Tool Context (optional)

## Guidance for Agents (optional)

Built-In Personas

Creating a Custom Persona

Using Personas

Option A: IDE Custom Instructions (GitHub Copilot)

Option B: System Prompt Prefix

Option C: Prompt Reference at Session Start

Personas vs. Skills

Skills

How Skills Work

Skill Folder Structure

SKILL.md

The .skills.json Manifest

Skill Categories in .skills.json

Skill Entry Format

Configuring Skills

Adding a Local Skill

Adding an External Skill

Blocking a Skill

Creating a New Skill

Using Skills as an Agent

How Personas and Skills Work Together

External Skills

Policy Settings

Commands

Hooks

Versioning

Customization

Contributing

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

`# Persona: <Name>` (required)

`## Summary` (required)

`## Rule References` (recommended)

`## Collaboration Preferences` (recommended)

`## Tool Context` (optional)

`## Guidance for Agents` (optional)

`SKILL.md`

The `.skills.json` Manifest

Skill Categories in `.skills.json`

Packages