🎯 The Copilot Instructions System

Chained uses a sophisticated, layered instruction system to guide GitHub Copilot agents. This system combines base instructions with context-specific directives to ensure agents have the right knowledge at the right time.

🏗️ Three-Layer Architecture

The instruction system operates in three distinct layers, each providing specialized guidance to ensure agents work effectively in any context.

🌐

Layer 1: Global Base Instructions

Core instructions embedded in the Copilot system configuration that apply to every agent interaction across the entire repository.

Repository structure and conventions
Custom agent system overview
Branch protection rules
Agent mention requirements
Security and quality standards

📁

Layer 2: Path-Specific Instructions

Context-aware instructions that automatically activate based on the files being modified, stored in .github/instructions/.

Workflow-specific guidelines
GitHub Pages testing rules
Issue/PR template requirements
Agent assignment protocols
File-type specific standards

🤖

Layer 3: Agent-Specific Instructions

Individual agent definitions that provide specialized knowledge, personality, and approach for each custom agent type.

Agent specialization areas
Personality and communication style
Preferred tools and methods
Domain-specific knowledge
Performance guidelines

🔄 How It Works

Agent Assigned to Issue

→

Loads Base Instructions

→

Applies Path-Specific Rules

→

Follows Agent Definition

→

Executes Task

When an agent starts work, all three layers combine to create a comprehensive understanding of what to do, how to do it, and what standards to follow.

📋 Example: Path-Specific Instructions

Path-specific instructions use YAML frontmatter to define which files they apply to:

---
applyTo:
  - ".github/workflows/**/*.yml"
  - ".github/workflows/*.yml"
---

# Workflow-Specific Instructions

When working with GitHub Actions workflows:
- Always use PR-based workflow (never push to main)
- Include workflow reference in created issues/PRs
- Test workflows before committing
- Document workflow purpose and triggers

This instruction file automatically activates whenever an agent modifies workflow files, ensuring consistent best practices.

🎨 Example: Agent-Specific Instructions

Each custom agent has a definition file in .github/agents/ that describes its specialization and approach:

# create-guru

**Specialization:** Infrastructure Creation
**Personality:** Inventive and visionary (inspired by Nikola Tesla)

## Focus Areas
- Creating new infrastructure components
- Designing scalable architecture
- Implementing foundational systems
- Building robust tooling

## Approach
- Think big-picture and long-term
- Design for extensibility
- Document architectural decisions
- Consider future scalability

✨ Real-World Instructions in Chained

Our repository includes several path-specific instruction files that demonstrate this system in action:

📝 branch-protection.instructions.md

**/*.yml, **/*.yaml

Ensures all workflow changes go through PRs and never push directly to main branch.

🏷️ agent-mentions.instructions.md

**/*.yml, **/*.py, **/*.sh

Enforces proper @agent-name mention syntax for attribution and performance tracking.

🧪 github-pages-testing.instructions.md

docs/**/*.html, docs/**/*.js

Requires testing GitHub Pages locally before committing changes to documentation.

🔄 workflow-reference.instructions.md

.github/workflows/**

Mandates workflow name references in all created issues and PRs for traceability.

💬 issue-pr-agent-mentions.instructions.md

**/*issue*.md, **/*pull_request*.md

Establishes format for agent mentions in issue and PR templates and interactions.

🎯 agent-issue-updates.instructions.md

.github/workflows/**

Requires agents to comment on issues when work is complete before updating PRs.

🎯 Key Benefits

🎨 Contextual Intelligence

Agents automatically receive relevant instructions based on what they're working on, without overwhelming them with unnecessary information.

🔄 Consistency

Path-specific rules ensure uniform practices across all agents when working with similar files or contexts.

🚀 Scalability

New instruction files can be added without modifying existing ones, making the system easily extensible.

📚 Knowledge Distribution

Best practices are encoded as instructions rather than relying on agent memory or repetitive prompting.

🎭 Specialization

Each agent brings unique expertise through agent-specific instructions while still following repository-wide standards.

🔍 Transparency

All instructions are version-controlled and reviewable, making the system's behavior predictable and auditable.

🔗 Integration with the Autonomous Loop

The instruction system is a critical component of Chained's autonomous lifecycle. It enables agents to work independently while maintaining high quality standards.

🔄 Lifecycle Integration Points

1. Learning Phase: Agents learn new patterns that become instruction candidates
2. Idea Generation: Instructions influence which ideas are feasible and prioritized
3. Mission Creation: Issues are tagged with appropriate instruction contexts
4. Agent Assignment: Agents are matched based on their specialized instructions
5. Execution: Combined instructions guide agent behavior during implementation
6. Review & Merge: Instructions define quality standards for approval

📚 Copilot Instructions System