The Recursive Artifact Framework (RAF)

🤖 Overview

This repository serves as a reference implementation for the Recursive Artifact Framework (RAF).

RAF is an architectural pattern for Agentic AI that decouples an agent's Identity (Shell), Logic (Brain), and Memory (State). It is designed to run natively within GitHub Copilot (VS Code & Web) by leveraging the "Context Window" as a processing unit and the file system as long-term storage.

The Core Philosophy

In the era of "1,000 Simultaneous Experiments," software is no longer just a tool; it is an employee. To manage this digital workforce, we cannot rely on ephemeral chat history. We must rely on persistent, self-maintaining artifacts.

The Golden Rule: Nullius in Verba ("Take nobody's word for it"). If a decision, rule, or architectural state exists only in the chat window, it does not exist. Agents must write their state to disk [Source: Conversation History].

---

📐 The Artifact Triad

Every agent in this framework acts as a system composed of three mandatory files. An agent cannot exist as a standalone entity.

Component	File Extension	Role	Analogy
The Definition	*.agent.md	The Controller: Defines identity, tools, and handoffs. It loads the Brain and Memory.	The "Job Description" & ID Badge.
The Instructions	*.instructions.md	The Brain: The "Objective Function." Contains immutable rules, negative constraints, and style guides.	The "Employee Handbook" & SOPs.
The Design	*.design.md	The Memory: The "State." Persists scope, architectural decisions, and the maintenance log.	The "Project Whiteboard" & Memory.

---

📂 Repository Topology

To ensure auto-discovery by GitHub Copilot and VS Code, artifacts must reside in specific directories.

.
├── .github/
│   ├── agents/                     # [The Shells] Executable Agent Profiles
│   │   ├── agent-architect.agent.md
│   │   ├── documentation-agent.agent.md
│   │   └── sql-optimizer.agent.md
│   │
│   ├── instructions/               # [The Brains] Scoped Logic & Rules
│   │   ├── copilot.instructions.md # Global axioms (apply to ALL)
│   │   ├── docs.instructions.md    # Scoped to documentation
│   │   └── sql.instructions.md     # Scoped to SQL files
│   │
│   └── design/                     # [The Memories] State & Architecture
│       ├── agents.design.md        # Meta-design for the framework itself
│       ├── docs.design.md          # Documentation Diátaxis structure
│       └── schema.design.md        # Database schema state
│
└── src/                            # Application Source Code

---

🚀 Artifact Specifications

1. The Agent Definition (.agent.md)

Location: .github/agents/ This file allows the user to invoke the agent using @agent-name in Copilot Chat. It utilizes the Recursive Mandate to load its own context.

Key Features:

• Handoffs: Defines valid transitions to other agents (e.g., Planner -> Builder).
• Tooling: Explicitly lists MCP tools (e.g., filesystem, database access).

---
name: agent-architect
description: Designs and scaffolds new agent capabilities.
tools: [read, edit, search]
handoffs:
  - label: Implement Design
    agent: code-implementer
---
You are the Agent Architect.
1. Load your Brain: #file:.github/instructions/agent-arch.instructions.md
2. Load your Memory: #file:.github/design/agents.design.md

2. The Instructions (.instructions.md)

Location: .github/instructions/ These files define the Objective Function of the agent. They use YAML frontmatter to strictly scope rules to specific files, preventing context pollution.

Key Features:

• applyTo: Glob patterns that trigger these rules automatically when relevant files are open.
• Axiomatic Logic: Binary rules (Do/Don't) rather than vague suggestions.

---
applyTo:
  - "**/*.ts"
  - ".github/agents/*.agent.md"
---
# Architectural Axioms
- NEVER hardcode secrets.
- ALWAYS update the associated .design.md file when changing architecture.

3. The Design (.design.md)

Location: .github/design/ This is the Persistence Layer. Since LLM context windows are finite, agents must offload "long-term memory" to these files.

Key Features:

• Scope: Explicitly lists what the agent owns and ignores.
• Maintenance Log: A chronological history of why changes were made, written by the agent itself.

---

🔄 Workflows & Protocols

1. The "Bootstrap" Workflow

Used when creating a new feature or agent.

1. User: Invokes @agent-architect with a high-level goal.
2. Architect:
   • Creates a new .design.md file to define the "Platonic Ideal" of the solution.
   • Creates a .instructions.md file to define the constraints.
   • Creates the .agent.md shell to link them.
3. Result: A fully formed "Employee" ready to work.

2. The "Recursive Update" Loop

The primary maintenance loop for all agents.

1. Read: The agent reads its .instructions.md to understand how to act.
2. Check: The agent reads its .design.md to understand the current state.
3. Act: The agent modifies code in src/.
4. Reflect: The agent MUST update its .design.md file to reflect the changes it just made (e.g., "Added getUser method to API interface").

3. The Handoff Protocol

Orchestrating multiple agents.

• Scenario: You are in planning-mode and the design is complete.
• Action: Click the "Start Implementation" handoff button defined in the agent's frontmatter.
• Result: Context is transferred to the implementation-agent, which automatically loads the coding.instructions.md and the recently updated feature.design.md.

---

🛠️ MCP Integration (Model Context Protocol)

This framework supports Model Context Protocol (MCP) servers to give agents capability beyond text editing.

• Read/Write: The framework uses the filesystem MCP server to allow agents to create their own instruction files.
• External Data: Agents can be configured to query database schemas or API specs via MCP before writing code.

---

📦 Installation & Setup

1. Clone this repository.
2. Install GitHub Copilot Extension in VS Code.
3. Enable Custom Instructions: Ensure github.copilot.chat.codeGeneration.useInstructionFiles is set to true in VS Code settings.
4. Sync Settings: (Optional) Enable Settings Sync for "Prompts and Instructions" to share agent behaviors across devices.

---

This framework implements the agentic design principles described in the "Recursive Artifact Framework" and complies with GitHub Copilot's v1.106+ custom agent specifications.