Agent Workflows & Living Docs

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 agentdocs

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

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

agent.md — Define your agent's behavior

If you're building an AI-powered feature (chatbot, copilot, assistant), 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 agentdocs

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

The update loop

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

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

Or use the agentdocs API from a CI job:

# .github/workflows/docs-sync.yml
name: Sync docs
on:
  push:
    branches: [main]
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 agentdocs
          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 agentdocs
2. Team gets a notification
3. Someone reviews, adds context, fixes details
4. Version history shows the collaboration

Attribution

Every update through the agentdocs 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
└── .github/
    └── copilot-instructions.md → @team/ai-conventions

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

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 agentdocs
agentdoc push

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

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