Dossier — Automation Instructions for AI Agents

Stop writing brittle scripts. Start writing instructions that AI executes intelligently.

✅ Portable workflows that adapt to your project ✅ Built-in verification (checksums, signatures, success criteria) ✅ Works with Claude, ChatGPT, Cursor—any LLM

Quick Concept Dossier turns plain-text instructions into executable workflows with built-in verification. Like Dockerfiles for AI automation—structured, portable, verifiable.

New here? → 5-min Quick Start | Want to try now? → 30-sec demo

At a Glance

📝 What: Structured instruction files (.ds.md) that AI agents execute intelligently 🎯 Why: Replace brittle scripts with adaptive, verifiable automation that handles edge cases naturally ⚡ How: Create dossier → Run with your AI → Get validated results with evidence 🔒 Safety: Built-in checksums, cryptographic signatures, and CLI verification tools 🔗 Multi-registry: Configure multiple registries for teams and organizations 🌐 Works with: Claude, ChatGPT, Cursor, any LLM—no vendor lock-in

Status: Protocol v1.0 (stable spec) | CLI v0.8.0 | 15+ example templates | Active development

File conventions: Dossiers use .ds.md (immutable instructions) and .dsw.md (mutable working files). Frontmatter uses ---dossier (JSON) instead of --- (YAML) to avoid parser conflicts. Learn more

Try it Now

Option A — Claude Code Plugin (Recommended)

/plugin marketplace add imboard-ai/ai-dossier
/plugin install dossier-mcp-server@ai-dossier

That's it — the dossier MCP server is now available across all your projects with auto-updates.

Option B — Manual MCP Setup (Claude Code / Claude Desktop)

If you prefer manual configuration or need project-scoped setup:

# Claude Code (global)
claude mcp add dossier --scope user -- npx @ai-dossier/mcp-server

# Claude Code (project-only)
claude mcp add dossier -- npx @ai-dossier/mcp-server

Or add to ~/.claude/settings.local.json / claude_desktop_config.json:

{
  "mcpServers": {
    "dossier": {
      "command": "npx",
      "args": ["-y", "@ai-dossier/mcp-server"]
    }
  }
}

Option C — Command-Line Verification (Works Anywhere)

Verify dossier security before execution:

# Clone the repo and use the CLI verification tool
git clone https://github.com/imboard-ai/ai-dossier.git
cd ai-dossier
npx @ai-dossier/cli verify examples/git-project-review/atomic/readme-reality-check.ds.md

Option D — Try with Any LLM (Zero Installation)

Copy this into any LLM chat (Claude, ChatGPT, Gemini):

---dossier
{
  "title": "Hello World",
  "version": "1.0.0",
  "protocol_version": "1.0",
  "status": "stable",
  "objective": "Print a friendly greeting and verify success",
  "risk_level": "low"
}
---

# Hello World

## Actions
1. Print: "Hello from Dossier!"

## Validation
- Output contains "Hello from Dossier"

Expected result: The LLM will print "Hello from Dossier!" and confirm success.

Why Use Dossier?

"How is this different from AGENTS.md files?" Many projects already use files like AGENTS.md or .cursorrules for AI context. Here's the key distinction:

They're complementary: Use AGENTS.md to explain your project, use dossiers to automate workflows.

Examples Gallery

Real-world dossiers demonstrating the protocol across different domains:

Who should try these: Project maintainers, DevOps/SRE teams, ML engineers, frontend developers

Run the first one now:

Ask your LLM:

Analyze my project using the readme-reality-check dossier from:
https://raw.githubusercontent.com/imboard-ai/ai-dossier/main/examples/git-project-review/atomic/readme-reality-check.ds.md

Security & Verification

• Use the CLI tool (ai-dossier verify) to verify checksums/signatures before execution
• Prefer MCP mode for sandboxed, permissioned operations
• External reference declaration: Dossiers that fetch or link to external URLs must declare them in external_references with trust levels. The linter flags undeclared URLs, and the MCP server's read_dossier tool returns security_notices for any undeclared external URLs found in the body. This mitigates transitive trust risks from unvetted external content.
• See SECURITY_STATUS.md for current guarantees and limitations

Registry & Multi-Registry Support

The CLI supports multiple registries for discovering, publishing, and sharing dossiers across teams and organizations.

• Multi-registry: Configure multiple registries (public, internal, mirrors) queried in parallel
• HTTPS enforcement: All registry URLs must use HTTPS to protect credentials in transit
• Per-registry credentials: Each registry has isolated authentication — a compromised token cannot access other registries
• Project-level config: Add a .dossierrc.json to your project for team-shared registry settings

# Add a private registry
dossier config --add-registry internal --url https://dossier.company.com

# List configured registries
dossier config --list-registries

See the CLI documentation for full registry management options.

Adopter Playbooks

• Solo Dev: paste a .ds.md into your LLM and run via MCP or CLI
• OSS Maintainer: add /dossiers + a CI check that runs the Reality Check on your README
• Platform Team: start with init → deploy → rollback dossiers; wire secrets & scanners

👉 Detailed playbooks in docs/guides/adopter-playbooks.md

Documentation

Philosophy

"Agents need structure. Dossiers provide it."

Dossiers embody this philosophy - they give AI agents clear structure and guidance, enabling them to intelligently automate complex workflows that would be brittle to script.

The dossier standard enables:

• Adaptability: LLMs understand context and adjust behavior
• Maintainability: Markdown documentation instead of complex scripts
• Collaboration: Clear, readable instructions anyone can contribute to
• Continuous improvement: Self-improving through the protocol
• Universal adoption: Any project, any workflow, any implementation

🎯 Dossier: Universal LLM Automation Standard Structure your agents. Not your scripts.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). You are free to use, copy, modify, and distribute it, provided that any modified versions or network services using this software also make their source code available under the same license.

References

See REFERENCES.md for the full list of academic references and industry research supporting the dossier approach.