Agent Workflows & Living Docs

Looking for "how do I install AgentDoc into my agent"? Every agent has a one-line install (technical or non-technical) at agentdoc.com/connect. For custom agents and REST API workflows, see below and skill.md.

The files that matter

Most teams need a handful of key markdown documents. Each one serves a different purpose and benefits from both human and agent authorship.

design.md — Your design system as markdown

A design.md file gives AI tools context about your visual language. Without it, AI generates generic-looking UI. With it, AI generates components that match your system.

What to include

# Design System

## Colors
- Primary: `#12A8FF` (agentdoc-blue) — actions, links, active states
- Secondary: `#8B5CF6` (violet) — accents, tags, secondary actions
- Destructive: `#EF4444` — errors, delete actions
- Background: `#FFFFFF` (light) / `#09090B` (dark)
- Muted: `#71717A` — secondary text, borders

## Typography
- Headings: Inter, semibold
- Body: Inter, regular, 16px/1.6
- Code: JetBrains Mono, 14px

## Components
- Buttons: rounded-lg, h-10 default, h-9 sm, h-12 lg
- Cards: rounded-2xl, border border-border/60, bg-card, shadow-soft
- Inputs: rounded-lg, border border-input, h-10
- No colored left/right border bars on cards
- No heavy gradients — use clean accents

## Spacing
- Section padding: py-16 sm:py-24
- Card padding: p-6 or p-7
- Stack gap: space-y-4
- Grid gap: gap-4 or gap-5

## Patterns
- Use shadcn/ui components as the base
- Dark mode via next-themes (class strategy)
- Transitions on interactive elements (200ms)
- Glass morphism for overlays (backdrop-blur-sm)

Store on AgentDoc

agentdoc track design.md --slug design-system
agentdoc push

Now every AI tool (Claude Code, Cursor, Codex) that reads your design.md generates UI that matches your system. And your team can update the design system on AgentDoc — the changes flow to every repo.

agent.md — Define your agent's behavior

If you're building an AI-powered feature (chatbot, assistant, coding agent), agent.md defines what it does and how it behaves.

Structure

# Support Agent

## Identity
You are a support agent for Acme. You help customers with account
issues, billing questions, and product guidance.

## Capabilities
- Look up customer accounts by email
- Check order status and shipping
- Process refunds up to $50
- Schedule callbacks with human agents
- Search the knowledge base

## Tone
- Friendly and professional
- Concise — answer the question without over-explaining
- Empathetic when customers are frustrated
- Never defensive

## Boundaries
- Cannot access internal tools beyond what's listed above
- Cannot make promises about future features
- Cannot share internal pricing or discount policies
- Must escalate to human agent for: account deletion, charges
  over $50, legal questions

## Conversation flow
1. Greet and identify the issue
2. Ask clarifying questions if needed
3. Resolve or escalate
4. Confirm resolution and ask if anything else is needed

## Examples
[Include 2-3 example conversations showing ideal behavior]

Why AgentDoc

Your agent.md is a living document:

• Product team defines capabilities and tone
• Engineering adds tool definitions and constraints
• Support team contributes example conversations and edge cases
• Version history tracks how the agent's behavior evolves

agentdoc track agent.md --slug support-agent-spec
agentdoc push

architecture.md — Let agents keep it current

Architecture docs go stale faster than any other document. Agents are good at reading code and generating descriptions of what exists. Humans are good at explaining why.

Agent-generated sections

Have your agent produce these sections automatically:

## Service map
[Agent reads package.json, Dockerfiles, infra config and generates this]

## Database schema
[Agent reads Prisma schema / migrations and generates this]

## API endpoints
[Agent reads route definitions and generates this]

## Dependencies
[Agent reads package.json and generates this with version info]

Human-written sections

These require judgment that agents can't provide:

## Design decisions
- Why we chose PostgreSQL over MongoDB
- Why we use Yjs instead of OT for collaboration
- Why the CLI uses Commander instead of oclif

## Trade-offs
- We chose consistency over availability for the API
- We chose server-side rendering over client-side for SEO

## Known technical debt
- The collab server needs connection pooling
- Search is basic — needs full-text indexing

Workflow

# Agent generates the factual sections
agentdoc push architecture.md

# Humans add and maintain the decision sections
# Edit at agentdoc.com/@team/architecture

Building agent workflows

Project and tag routing

When an agent creates durable markdown, it should also organize it. For work tied to an initiative, client, system, or folder, reuse an AgentDoc project or pass a clear project slug so AgentDoc can create it, and add concise tags at creation time.

agentdoc create --file docs/architecture.md --project platform -t architecture -t platform
agentdoc track docs/api-reference.md --project platform -t api -t reference

The CLI and MCP create missing private projects automatically when --project / project_slug names a project that does not exist yet. Use explicit project creation only when you need a project before any docs exist or need custom visibility/description.

For local tracking folders, set defaults once so future agent-created docs land in the right project automatically:

agentdoc init
agentdoc config set project platform
agentdoc config set tags platform,api
agentdoc track docs/api-reference.md

Good tags describe the doc type, system, and workflow: runbook, incident, research, api, billing, migration, release. Avoid broad labels like doc, notes, or misc.

The update loop

The most powerful pattern is an agent that periodically reads your codebase and updates docs on AgentDoc:

# Agent watches for changes and updates docs
agentdoc watch docs/api-reference.md api-reference

Or use the AgentDoc API from a CI job:

# .github/workflows/docs-sync.yml
name: Sync docs
on:
  push:
    branches: [master]
jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate and push docs
        run: |
          # Your agent script generates updated docs
          node scripts/generate-docs.js
          
          # Push to AgentDoc
          npm install -g @agentdoc/cli
          agentdoc login --key ${{ secrets.AGENTDOC_API_KEY }}
          agentdoc push docs/api-reference.md

The review loop

Agents write drafts. Humans review and refine. The doc improves over time:

1. Agent creates/updates a doc on AgentDoc
2. Team gets a notification
3. Someone reviews, adds context, fixes details
4. Version history shows the collaboration

Attribution

Every update through the AgentDoc API or CLI is automatically attributed to the API key name:

# CLI
agentdoc push

# API
curl -X PATCH https://api.agentdoc.com/v1/docs/my-doc \
  -H "Authorization: Bearer ad_sk_xxx" \
  -d '{"content": "...", "message": "Updated API endpoints"}'

The version history shows which agent (identified by API key name) made which changes, alongside human edits. Name your API keys after the agent or tool using them for clear attribution.

Recommended file structure

project/
├── CLAUDE.md              → @team/claude-md-{project}
├── design.md              → @team/design-system
├── agent.md               → @team/agent-{name}-spec
├── architecture.md        → @team/architecture-{project}
├── docs/
│   ├── api-reference.md   → @team/api-reference
│   ├── runbook.md         → @team/runbook-{project}
│   └── changelog.md       → @team/changelog-{project}
├── .cursorrules           → @team/ai-conventions
└── .windsurfrules         → @team/ai-conventions

Each file is tracked on AgentDoc. Shared files (conventions, design system) map to the same AgentDoc document across repos. Project-specific files (architecture, runbook) have their own AgentDoc document.

Quick start

# 1. Initialize tracking
agentdoc init

# 2. Track your key docs
agentdoc track design.md --slug design-system
agentdoc track agent.md --slug support-agent-spec
agentdoc track architecture.md --slug architecture-api

# 3. Push to AgentDoc
agentdoc push

# 4. Your team edits on AgentDoc, you pull updates
agentdoc pull

Your docs are now living documents that agents draft, humans refine, and both keep current.