DotAgents Unified Design Specification

Core Philosophy

Strict separation of Identity, Capabilities, Semantic Context, and Memories — unified under a single .agents/ tree that acts as the agent-facing “LLM-wiki.”

Two modes serve different scopes:

Scope Root Description Spec-kit
USER ~ Shared skills & knowledge visible across projects and agents Not involved
PROJECT . (repo root) Per-project agent context with multi-agent collaboration Optional, independent

Scope Definitions

AgentFS operates in two scopes. These definitions are canonical — all guardrails, skills, and documentation reference them.

Scope Root Path Resolves To Purpose
USER ~/.agents/ /home/<user>/.agents/ Machine-wide shared library: skills and knowledge visible across all projects and agents
PROJECT ./.agents/ <repo-root>/.agents/ Per-repository agent workspace: identity, profiles, memories, and project-scoped skills

What Lives Where

Resource USER (~/.agents/) PROJECT (./.agents/)
skills/ ✅ shared ✅ project-specific
knowledge/ ✅ shared ❌ never
memories/ ❌ never ✅ per-agent
profiles/ ❌ never ✅ multi-agent
SOUL.md ❌ never ✅ agent identity
AGENTS.md ❌ never ✅ (at repo root ./)
index.md ✅ ✅
log.md ✅ ✅

Rule of thumb: If the agent says “USER scope”, it means ~/.agents/. If it says “PROJECT scope”, it means ./.agents/ relative to the current repository root.

Installation Paths

USER scope (~/.agents/) must be set up before PROJECT scope can work, since PROJECT scope skills and scripts are typically invoked from the USER-scoped skill library.

Clone the published AgentFS repository directly into ~/.agents/:

git clone https://github.com/rhtevan/agentfs.git ~/.agents

This gives the user the complete skill library, knowledge bundles, and structural scaffolding — ready to use immediately.

Path B: Minimal Install

For users who want a clean, empty ~/.agents/ and prefer to cherry-pick skills selectively:

  1. Clone the repo to a staging location (not ~/.agents/): 
    git clone https://github.com/rhtevan/agentfs.git ~/repos/agentfs
  2. Make the staging location visible to the agent (e.g., add ~/repos/agentfs/skills/ to the agent’s skill search paths — see the relevant agent setup skill for details).
  3. Ask the agent to run the agentfs-setup skill with USER scope:

    “Set up AgentFS in USER scope”

    The agent loads the skill, recognises the USER scope hint, and scaffolds an empty ~/.agents/ with skills/, knowledge/, index.md, and log.md.

  4. Cherry-pick specific skills using the skill-merge skill or manual copy.

After USER Setup: Agent Configuration

Each agent needs its own setup to discover AgentFS context files:

Agent Setup Skill
Goose goose-agentfs-setup
Hermes hermes-agentfs-setup

After USER Setup: PROJECT Setup

In any git repository, ask the agent to run the agentfs-setup skill:

“Set up AgentFS for this project”

Since PROJECT is the default scope, no additional scope hint is needed. The agent scaffolds .agents/ and creates AGENTS.md at the repo root.

Prompt Stacking Order

When an agent assembles its system prompt from .agents/ resources, the intended stacking order is:

1. SOUL.md           ← "Who am I?" — agent identity (human-authored)
2. AGENTS.md         ← "How does this project work?" — project rules (human-authored)
3. skills/           ← Available capabilities (shared across agents)
4. knowledge/        ← Domain context (USER-scoped, shared across projects)
5. MEMORY.md         ← "What have I learned?" — project/env facts (agent-learned)
6. USER.md           ← "Who are they?" — user profile (agent-learned)

Items 1, 5, 6 are per-agent (default agent uses .agents/ root; named agents use .agents/profiles/<name>/). Items 2, 3 are shared across all agents in the project. Item 4 (knowledge) is USER-scoped (~/.agents/knowledge/) — shared across all projects and agents.

USER Scope — File Structure

~/
└── .agents/
    ├── index.md                             # Directory listing (OKF entry point)
    ├── log.md                               # Append-only activity tracker
    │
    ├── skills/                              # Capability Layer (Agent Skills)
    │   ├── index.md                         # Skills directory
    │   └── <skill-name>/
    │       ├── SKILL.md
    │       └── <bundled_resources>
    │
    └── knowledge/                           # Semantic Context Layer (OKF)
        ├── index.md
        └── <topic>/
            └── <concept>.md                 # YAML frontmatter: type required

Purpose: A shared library of skills and knowledge that spans across all projects and is visible to any agent. No agent identity, no memories, no profiles — purely a capability and knowledge store.

Excluded from USER scope:

PROJECT Scope — File Structure

./ (Repository Root)
├── AGENTS.md                                # Workspace entry point
│
├── .agents/                                 # The DotAgents Directory
│   ├── index.md                             # Directory listing (OKF entry point)
│   ├── log.md                               # Append-only activity tracker
│   ├── SOUL.md                              # Default agent identity (human-authored)
│   │
│   ├── profiles/                            # Named Agent Profiles
│   │   ├── index.md                         # Profile directory listing
│   │   └── <agent-name>/                    # Created by agentfs-profile skill
│   │       ├── SOUL.md                      # This agent's identity
│   │       └── memories/
│   │           ├── USER.md                  # This agent's model of the user
│   │           └── MEMORY.md                # This agent's learned project facts
│   │
│   ├── skills/                              # Capability Layer (Agent Skills)
│   │   ├── index.md                         # Skills directory
│   │   └── <skill-name>/                    # Shared across all agents
│   │       ├── SKILL.md
│   │       └── <bundled_resources>
│   │
│   └── memories/                            # Default Agent Memories
│       ├── USER.md                          # Default agent's model of the user
│       └── MEMORY.md                        # Default agent's project experiences
│
├── .specify/                                # Spec-kit engine (if used)
│   ├── templates/
│   ├── scripts/bash/
│   ├── memory/
│   │   └── constitution.md
│   ├── feature.json
│   └── init-options.json
│
└── specs/                                   # Spec-kit output (if used)
    └── <feature-branch-name>/
        ├── spec.md
        ├── plan.md
        ├── tasks.md
        └── ...

Multi-Agent Collaboration

PROJECT scope supports multiple agents working together on the same project.

Shared layers (all agents see these)

Per-agent layers (scoped to each agent)

Default agent vs named profiles

The default agent uses files at the .agents/ root:

Named agents get their own profile under .agents/profiles/<name>/:

Profiles are created by the companion agentfs-profile skill, which scaffolds the directory structure and seeds template files.

Each profile is equivalent to a distinct ROLE — it defines who the agent is, what it remembers, and how it models the user. All roles share the same skills and knowledge, and all follow the same guardrails defined in AGENTS.md at the project root. This ensures coherent collaboration: a “verifier” agent and a “coder” agent both see the same project rules but bring different expertise and perspectives.

The profile structure uses a well-known convention (SOUL.md, memories/USER.md, memories/MEMORY.md) that maps naturally to any agent framework’s native profile concept. Agent-specific compatibility details belong in the corresponding agent setup skill (e.g., hermes-agentfs-setup, goose-agentfs-setup).

Layer Descriptions

1. Workspace Layer — AGENTS.md (PROJECT only)

Entry point for coding agents. Contains operational guardrails, build/test commands, code style. Points to .agents/. Carries <!-- SPECKIT START/END --> markers for Spec-kit’s agent-context extension to manage automatically.

Template versioning: Every generated AGENTS.md carries a version stamp <!-- agentfs-template-version: X.Y --> on line 1. The agentfs-setup skill’s --sync mode compares this against the current template version and regenerates template-owned sections while preserving project-owned sections (Agent Profiles table, SPECKIT block).

Section ownership: AGENTS.md is divided into two zones:

Signal Routing architecture:

README sync rule: When AgentFS design, guardrails, skills schema, or template structure changes, the README (~/.agents/README.md) MUST be updated in the same commit or session. This is a hard requirement, not advisory — unlike the soft README staleness check in Guardrail #10.

Defines ten structural guardrails (reordered by usage frequency):

  1. 🔄 Progressive Disclosure — browse index.md before opening files
  2. ⚖️ Memory Scope — memories are PROJECT-only; graduation path to OKF
  3. 🔄 Cross-Agent Discovery — read CLAUDE.md, .cursorrules, etc.
  4. ⚖️ Skill Placement — default to USER, PROJECT only when explicit
  5. ⛔ Filesystem Integrity — link integrity, log currency, content file currency, and index currency in a single guardrail
  6. 🔄 Idempotency — every skill and workflow must be idempotent
  7. ⚖️ Anti-Sycophancy — refuse conflicting requests, log overrides
  8. 🔄 Anti-Daydreaming — ephemeral session canary name; spot-check for context drift; never persisted to AgentFS files
  9. ⛔ Checkpoints & Resumability — checkpoint before destructive ops
  10. ⛔ Git Push Safety — mandatory 5-step preflight before any git push: stop → scan → present report → wait for approval → push

Guardrail Type System

Each guardrail is classified by its enforcement mechanism:

Type Marker Trigger Agent Behavior Key Action Pattern
Gate ⛔ Specific action point STOP, complete checklist, then proceed STOP → [verb chain] → RESUME/WAIT
Rule ⚖️ Decision point Choose correctly from constrained options Default X; exception when Y
Habit 🔄 Continuous / periodic Maintain behavioral norm throughout session [trigger]: action

Three types map to three fundamental flow-control primitives: Gate = checkpoint, Rule = branch, Habit = feedback loop.

Two additional patterns (Trigger and Invariant) were considered during design but collapse into existing types at the agent behavioral level:

Only guardrails with proven multi-step failure modes receive the Gate type. Overusing Gate dilutes its interrupt force.

Includes an Agent Profiles table — an agent-agnostic registry of all profiles in the project:

## Agent Profiles

| Agent | Identity | Memories |
|-------|----------|----------|
| default | [SOUL](./.agents/SOUL.md) | [memories/](./.agents/memories/MEMORY.md) |
| coder | [SOUL](./.agents/profiles/coder/SOUL.md) | [memories/](./.agents/profiles/coder/memories/MEMORY.md) |

The default row is seeded by seed-agents-md.sh during initial setup. Named profile rows are appended automatically by create-profile.sh (from agentfs-profile skill). This makes profiles discoverable by any agent reading AGENTS.md — framework-independent.

2. Navigation & Log — .agents/ root

3. Identity Layer — SOUL.md

Human-authored agent personality and communication defaults. The default agent’s SOUL lives at .agents/SOUL.md; named profiles have their own at .agents/profiles/<name>/SOUL.md.

4. Profiles Layer — .agents/profiles/ (PROJECT only)

The profiles/ directory serves two complementary purposes:

1. Multi-Agent Collaboration Hub Named agent profiles enable multiple AI agents to collaborate on the same project while maintaining distinct identities and memory spaces. Each profile is a self-contained agent persona with its own SOUL.md (identity) and memories/ directory (USER.md + MEMORY.md). The profile structure uses a well-known convention (SOUL.md, memories/USER.md, memories/MEMORY.md) that maps naturally to any agent framework’s native profile concept.

2. ROLE-Based Agent Specialization Each profile is equivalent to defining a different ROLE. A profile carries its own:

All profiles in a project follow the same structural guardrails defined in the project-root AGENTS.md. While each profile has its own identity and memories, every agent operating under any profile MUST adhere to the link integrity, log currency, index currency, progressive disclosure, and skill placement rules codified in AGENTS.md. This ensures consistent, predictable behavior across all agents collaborating on the project.

Skills remain shared across all profiles — only identity and memories are per-profile. Knowledge lives at ~/.agents/knowledge/ (USER scope) and is shared across all projects and agents. This allows specialized agents (e.g., a “verifier” role focused on testing, a “researcher” role focused on information gathering) to leverage the same capability set while maintaining distinct perspectives.

Created and managed by the agentfs-profile skill.

5. Capability Layer — .agents/skills/

Agent Skills format. Each skill = folder with SKILL.md + optional bundled resources. Progressive disclosure via metadata → body → resources. Shared across all agents. Present in both USER and PROJECT scopes.

SKILL.md Frontmatter Schema

Every SKILL.md MUST begin with YAML frontmatter containing:

Field Required Type Purpose
name Yes string Skill name — MUST match parent directory name
description Yes string Signal phrases — comma-separated trigger phrases for intent matching. See Signal Phrase Rules below
metadata.tags Yes list[string] Tag-based discovery (e.g., [agentfs, setup])

Schema change (v2.0.0): metadata.signals has been removed. Signal phrases now live in the description field, which is the only metadata always loaded into the agent’s context via the built-in skills listing.

Signal Phrase Rules:

The description field is the signal routing surface — the LLM matches user intent against these phrases to select the correct skill.

Opening paragraph requirement: Since description contains signal phrases (not prose), the SKILL.md body MUST include a hydrated human-readable paragraph immediately after the # Title heading.

Signal phrases are surfaced in skills/index.md by the skill-index skill (in the Description column) for progressive discovery. They are NOT compiled into AGENTS.md — the Signal Routing table in AGENTS.md is reserved for LLM-direct routes and genuinely ambiguous multi-skill triage entries.

See skill-gen/references/skill-schema.md for the full canonical schema.

6. Semantic Context Layer — ~/.agents/knowledge/ (USER only)

Open Knowledge Format. File path = concept identity. Every file requires YAML frontmatter with type field. Markdown links form a knowledge graph. Shared across all agents and projects. Present in USER scope only — projects do NOT get a local knowledge/ directory.

7. Memories Layer — .agents/memories/ (PROJECT only)

Agent-authored files capturing learned context:

Each named profile has its own memories/ subdirectory.

8. Planning Layer — specs/ (PROJECT only, managed by Spec-kit)

Full SDD lifecycle artifacts from Spec-kit. One subdirectory per feature. This directory lives at the repo root (not inside .agents/) and is fully managed by the specify CLI. DotAgents does not create, move, or override this directory.

Spec-kit Coexistence (PROJECT Scope)

Spec-kit is an independent tool that manages its own directories:

DotAgents and Spec-kit coexist as siblings, not parent-child:

./
├── .agents/      ← DotAgents (this skill)
├── .specify/     ← Spec-kit engine
└── specs/        ← Spec-kit output

No path overrides, no sed patches, no create-new-feature.sh wrappers. Spec-kit’s own integration system (specify init --integration <agent>) handles slash command installation. The only connection is the <!-- SPECKIT START/END --> markers in AGENTS.md that Spec-kit’s agent-context extension uses to write the active plan reference.

Evaluation

AgentFS enforces guardrails through prescriptive rules in AGENTS.md, but prescriptive rules alone are insufficient — they rely on the agent’s compliance, which is undermined by the very AI model flaws (hallucination, stochasticity, sycophancy) the guardrails aim to control. The agentfs-eval skill closes this gap with assertive verification.

Challenges

Safe Agent Actions:

AI Model Flaws:

Three-Layer Verification Architecture

The eval uses three progressively deeper verification layers, each with a fundamentally different paradigm:

Layer Paradigm LLM? Assertions
L1: Structural Filesystem assertions No Link integrity, log monotonicity, index completeness, frontmatter validity, scope correctness, changelog monotonicity, orphan detection
L2: Behavioral Forensic evidence correlation No Action-log correlation, log-git timestamp alignment, scope leakage, idempotency spot-check, rule-in-memory heuristic
L3: Semantic Constrained LLM classification Yes Memory content classification, reference verification, sycophancy detection, skill accuracy

Key design choices:

Maturity Levels

Level Name Requirements
L0 Absent No .agents/ directory
L1 Scaffolded .agents/ exists with basic structure
L2 Structurally Sound All Layer 1 assertions pass
L3 Behaviorally Safe Layer 1 + Layer 2 assertions pass
L4 Semantically Accurate All three layers pass
L5 Self-Correcting Agent detects and fixes its own violations

Git as Audit Infrastructure

agentfs-setup initializes git in the project directory (parent of .agents/) by default in PROJECT scope. The .gitignore tracks everything under .agents/ including memories/ — privacy is the user’s decision at push time, not gitignore time. Git provides:

L3 → L2 Graduation

Over time, patterns observed in Layer 3 semantic results can be codified as Layer 2 deterministic heuristics (e.g., a grep check for imperative language in MEMORY.md). This graduation is human-driven — the eval skill is updated manually after a human observes recurring patterns in eval reports. Eval never modifies itself.

Eval-Driven Guardrails

The evaluation work motivated three additional guardrails (now numbered #6 Idempotency, #7 Anti-Sycophancy, #9 Checkpoints & Resumability after the v3.3 consolidation from 13 → 9 guardrails, later expanded to 10 with #8 Anti-Daydreaming):

Scopes: USER, PROJECT, and LITE

AgentFS operates in three scopes. USER and PROJECT are the original two; LITE was added in v4.19.0 for small-context models.

Scope Root Target Use AGENTS.md
USER ~/.agents/ Machine-wide shared library None
PROJECT ./.agents/ (CWD) Full per-repo workspace Full (~3,750 tokens)
LITE ./.agents/ (remote path) Minimal per-repo workspace Lite (~850 tokens)

LITE Scope

LITE is a constrained form of PROJECT scope, designed for projects consumed by small-context models (e.g., Granite 3B at 16K context).

What’s different from PROJECT:

Inference rule: When the agent invokes setup/sync with an explicit target directory that does NOT resolve to CWD, the scope is LITE. No explicit path or path resolving to CWD = PROJECT.

Metadata: <!-- agentfs-template-version: X.Y agentfs-scope: lite -->

Detection pattern:

AGENTFS_SCOPE=$(grep -oP 'agentfs-scope: \K\w+' "$TARGET/AGENTS.md" 2>/dev/null || echo "project")

LITE Scope — File Structure

<target-project>/
├── AGENTS.md
└── .agents/
    ├── index.md
    ├── log.md
    ├── SOUL.md
    └── memories/
        ├── USER.md
        └── MEMORY.md

Lifecycle Model

LITE projects are provisioned and maintained by normal-capability sessions (with skills extension), then consumed by lite sessions (developer-only). A lite session cannot sync or scaffold — it can only read AGENTS.md, follow the rules, and write to memories/log.

Mode Switching

Sync preserves scope — it never auto-switches. To convert a project from LITE to PROJECT scope, explicitly re-seed with --scope project and re-scaffold with --scope project.

Changelog

Updated Change
2026-08-13 12:40 v3.11 — SKILL.md Frontmatter Schema: description field redefined as signal phrases (Command/Query patterns); metadata.signals removed; added Signal Phrase Rules, Opening Paragraph requirement; updated Signal Routing architecture (signals now in description, skills index Description column as defense-in-depth)
2026-07-31 21:42 v3.8 — Added Guardrail #8 Anti-Daydreaming (ephemeral session canary name for context-drift detection); renumbered Checkpoints → #9, Git Push Safety → #10; clarified Index Currency trigger to include metadata-only changes; updated all cross-references
2026-07-27 18:30 v3.7 — Added Signal Routing architecture (LLM-direct in AGENTS.md, skill signals in SKILL.md frontmatter, skills index as lookup table); added template versioning and --sync mechanism; added template-owned vs project-owned section markers; added SKILL.md Frontmatter Schema with metadata.signals field; added README sync rule (hard requirement); renamed Guardrail #2 to Memory Scope (Signal Routing promoted to standalone section)
2026-07-14 17:49 v3.3 — Consolidated guardrails from 13 to 9 (reordered by usage frequency); merged Memory Scope + Signal Routing; merged Link/Log/Changelog/Index into Filesystem Integrity; Quick Orientation now includes SOUL.md and knowledge index; updated eval-driven guardrails section numbering
2026-07-13 15:45 v3.1 — Added Evaluation section: three-layer verification architecture, maturity levels L0–L5, git as audit infrastructure, L3→L2 graduation, guardrails #10–12; git init now default in PROJECT mode; memories/ no longer excluded from .gitignore
2026-07-10 18:07 v3.0 — Added canonical Scope Definitions section (USER=~/.agents/, PROJECT=./.agents/); added Installation Paths section (Full vs Minimal USER setup); PROJECT is now the primary skill workflow
2026-07-10 16:10 v2.11 — Added Guardrail #9 (Memory Signal Routing): NL signal → route decision table with Executor column; two-layer override architecture (agent-agnostic AGENTS.md + agent-specific instructions.md); skill creation defaults to USER scope; harvest signal routes to skill-harvest or okf-bundle-harvest; priority-based runtime resolution via tool availability check
2026-07-08 13:38 v2.10 — Memory redesign: knowledge USER-only, memories PROJECT-only, 8 guardrails, MEMORY.md=”experiences”, removed .agents/knowledge/ from PROJECT tree
2026-06-30 23:49 v2.7 — Expanded guardrail §2: explicit USER/PROJECT/sub-bundle scope; mandatory skill/concept change logging; standardized log.md format
2026-06-30 23:36 v2.6 — Changelog tables now use Updated header and YYYY-MM-DD HH:MM timestamps, aligned with guardrail §3
2026-06-30 23:31 v2.5 — Renamed index column Added → Updated; timestamp precision increased to YYYY-MM-DD HH:MM; log.md headings now use timestamp format
2026-06-30 23:16 v2.4 — Added Index Currency guardrail (§6); expanded Profiles Layer narrative with dual-purpose (multi-agent hub + ROLE-based specialization); added Hermes compatibility table; profiles/index.md schema now includes Identity + Memories + Updated columns; skills/index.md uses Updated column; all entries sorted newest-first
2026-06-30 18:30 v2.3 — Added profiles/index.md; fixed profiles/ and memories/ link targets across all trees and examples
2026-06-30 17:30 v2.2 — Idempotent re-run: verify --fix mode repairs missing files/dirs without overwriting; link integrity checks; profile completeness checks; skills/index.md replaces .gitkeep
2026-06-30 15:30 v2.1 — Added Agent Profiles table to AGENTS.md workspace layer; agent-agnostic profile discovery
2026-06-30 14:00 v2.0 — Renamed USER mode → USER mode; memory/ → memories/; roles/ → profiles/; added SOUL.md, USER.md, MEMORY.md; removed constitution.md (Spec-kit owns it); added multi-agent collaboration design; added prompt stacking order; introduced agentfs-profile companion skill
2026-06-26 22:00 v1.1 — Added optional git/spec-kit init; verify script opt-in flags; fixed index.md links; fixed ((PASS++)) bash arithmetic bug
2026-06-26 14:00 v1.0 — Initial design: USER/PROJECT dual-mode, Spec-kit coexistence