Agentic Markdown specification v0.1.0

1. Introduction

As AI agents become more prevalent in software development and general task automation, the need for a standardized, interoperable, and human-readable communication format is critical. Current methods are often vendor-specific and ephemeral—Anthropic uses XML tags, OpenAI uses JSON tool calls, and most frameworks store agent state only in-memory, losing it when a session ends.

Agentic Markdown (AMD) is a proposed extension to standard Markdown that provides a unified, durable syntax for agent reasoning, action execution, and state management.

AMD aims to be the "lingua franca" for agentic communication—a format that different agents (Claude, GPT, Gemini, etc.) can read and write to collaborate on the same task across sessions, machines, and model providers.

This version (v0.1.0) of the Agentic Markdown specification is specifically written to first and foremost define tasks for agents. The specification will evolve continuously to support other kinds of definitions in the future.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The Agentic Markdown specification has evolved and MAY continue to evolve in the future. The released versions of the specification can be found under the relevant GitHub tag.

2. Core design principles

AMD balances several competing requirements. When they conflict, the following priority order applies:

1. Context durability: State must survive session boundaries. AMD files MAY BE committed to version control depending on the requirement and SHOULD BE the ground truth for agent state.
2. Human readability: Must look like standard Markdown to a human observer. A developer reading TASK_LOG.md should understand the agent's work without special tooling.
3. Machine parsability: Must be reliably parsed using simple XML/YAML parsers. No ambiguous syntax.
4. Token efficiency: Minimize boilerplate. Every token in an AMD file competes with task content for context window space.
5. Interoperability: Translatable to and from model-specific tool-calling formats via a thin preprocessor layer.

3. File conventions

3.1. File extension

An agent definition file MUST use .agentic or .md extension. Along with that, hierarchical extensions .*.agentic ARE ALLOWED based on the workflow type (e.g., for task definitions the .task.agentic extension CAN BE used).

3.2. Placement

There are two supported approaches. Both are valid; teams should pick one and apply it consistently.

1. .agent-* directory: A hierarchical directory structure (e.g., .agent-task, .agent-skill, etc.) which can store files with either the .agentic or .md extension. Hierarchical extensions are NOT ALLOWED in this structure.

   my-project/
   ├── .agent-tasks/
   │   ├── add-auth-module.agentic
   │   ├── refactor-database-layer.agentic
   │   └── write-api-docs.agentic
   ├── src/
   └── README.md
   

2. Standalone .agentic or .*.agentic files: Place .agentic or (.*.agentic) files anywhere in the repository tree, co-located with the code they relate to.

   my-project/
   ├── src/
   │   ├── auth/
   │   │   ├── auth.service.ts
   │   │   └── refactor-auth-service.task.agentic   ← co-located with relevant code
   │   └── storage/
   │       ├── provider.ts
   │       └── migrate-to-object-storage.agentic
   └── README.md
   

3.3. Source control

The development team can decide whether to commit (or NOT commit) the AMD files. The rule of thumb is always to commit only a specific set of AMD definitions (ideally by using a hierarchical extension or hierarchical directory structure).

3.4. Filename

The filename is the task's unique identifier within the project. It must be: - kebab-case (e.g., add-auth-module.agentic) - Descriptive—the name should convey the task's intent at a glance

The slug used for cross-referencing is the filename stripped of its extension. Both add-auth-module.agentic and add-auth-module.md produce the slug add-auth-module.

4. Syntax overview

4.1. Basic structure

An agentic definition file—whether .agentic, .*.agentic or .md—has two parts: a frontmatter block and a body.

---
FRONTMATTER (YAML)  ← contains metadata about the agentic definition
---

BODY (Markdown)     ← contains the definition

4.2. Frontmatter

The frontmatter is a YAML block delimited by ---. It contains structured metadata about the agentic definition.

Required fields:

Field	Type	Description
title	string	A short, human-readable name for the task

Optional fields:

Field	Type	Description
task_type	enum	Task type (see §4.2.1.)
status	enum	Current task status (see §4.2.2.)
depends_on	list of slugs	Tasks that must be completed before this one
scope	list of paths	File/directory paths relevant to this task; agents should confine their changes to these paths unless the requirements explicitly direct otherwise
tools	list of strings	Tools the agent must support to execute this task (see §4.3.3.). Allows a runner to validate compatibility before starting.

Minimal example:

---
title: Add input validation to the user registration endpoint
---

Full example:

---
title: Add input validation to the user registration endpoint
task_type: feature
status: open
depends_on:
  - refactor-user-model
scope:
  - src/users/
  - tests/users/
tools:
  - filesystem
  - code_execution
---

4.2.1. Task types

Value	When to use
feature	Adding new functionality
refactor	Restructuring existing code without changing behavior
bugfix	Fixing a defect
docs	Writing or updating documentation
review	Reviewing existing work and improving it
chore	Maintenance tasks (renaming, cleanup, config changes)

4.2.2. Task status

Value	Meaning
open	Not yet started
in_progress	An agent is actively working on it
done	Completed
blocked	Cannot proceed—waiting on a dependency or external input

An agent SHOULD update the status field when it begins work (in_progress) and when it finishes (done or blocked). This is a convention, not a hard requirement—agents that do not support file mutation may skip this update.

4.2.3. Tool identifiers

The tools field declares which tool capabilities the task requires. These are abstract capability names, not agent-specific API names. A runtime maps these to the executing agent's native tool set.

Identifier	Capability required
filesystem	Read and write files in the repository
git	Read git history, diffs, and commit metadata
web_search	Search the web for information
web_fetch	Fetch and read the content of a specific URL
code_execution	Run shell commands or scripts
image_read	Read and interpret image files

Additional tool identifiers may be defined as the spec evolves. Unknown identifiers SHOULD be treated as warnings, not errors, to preserve forward compatibility.

4.3. Body

The body is free-form Markdown. It is the natural language description of the task and contains everything the agent needs to understand and execute it.

The body is organized using the following named sections. All sections are optional, but when present they must appear in this order:

1. ## Context
2. ## Requirements
3. ## Constraints
4. ## Acceptance criteria

An agentic definition with a simple, self-contained description may omit section headings and use a flat prose/list structure—this is valid for short tasks.

4.3.1. Context

Background information the agent needs before starting the task. Use this section to: - Point to related files, commits, or external references - Explain the motivation or history behind the task - Describe the current state that the task is changing

## Context

The current password reset flow sends a token directly in the URL query string.
Security review flagged this as a risk—tokens should be short-lived and
invalidated after first use.

Prior discussion: @task:security-audit-findings
Related commit: @commit:a3f9c21
Design notes: @file:docs/design/auth-improvements.md

4.3.2. Requirements

What the agent must do. This is the core of the task. Use: - Numbered lists for ordered, sequential steps - Bullet lists for unordered requirements - Nested lists for sub-requirements or clarifications - Blockquotes for hints, examples, or verbatim content to include

## Requirements

1. Replace the query-string token with a one-time token stored in the database
2. Tokens must expire after 15 minutes
3. Invalidate the token immediately after it is used
4. Update the password reset email template to use the new URL format
   > New URL format: `/reset-password?token=<opaque-token>`
5. Add unit tests covering expiry and single-use enforcement

4.3.3. Constraints

Explicit boundaries on what the agent must NOT do, or rules it must follow. These are the guardrails. When constraints exist, they must be respected even if requirements appear to conflict with them.

## Constraints

- Do not modify the login or registration flows—only the password reset flow
- Do not introduce a new database table; extend the existing `auth_tokens` table
- The public API contract for `POST /auth/reset-password` must not change

4.3.4. Acceptance criteria

How the agent (or a human reviewer) can verify the task is complete. These are testable conditions, not descriptions of work.

## Acceptance criteria

- [ ] `POST /auth/request-reset` stores a token in `auth_tokens` and sends an email
- [ ] A token older than 15 minutes is rejected with a 400 response
- [ ] A token that has already been used is rejected with a 400 response
- [ ] All existing auth tests continue to pass

Use a Markdown checklist (- [ ]) so the agent can check items off as it verifies them.

4.3.5. Cross-reference syntax

Tasks regularly reference other artifacts in and around the repository. AMD defines a consistent @scheme:value syntax for these references so they are unambiguous to both humans and agents, regardless of the executing agent's native mention syntax.

Reference type	Syntax	Example
File in the repo	@file:<path>	@file:src/auth/auth.service.ts
Another task	@task:<slug>	@task:refactor-user-model
Git commit	@commit:<hash>	@commit:a3f9c21
External URL	Standard Markdown link	[RFC 6749](https://www.rfc-editor.org/rfc/rfc6749)

Why not bare @filename? The bare @ mention syntax is vendor-specific—Claude Code uses it to attach files, while other agents may interpret it differently or ignore it. The explicit @scheme: prefix is unambiguous across all agents.

Cross-references may appear anywhere in the body—inline in prose, in list items, or in blockquotes. When an agent encounters a cross-reference, it SHOULD resolve it (read the file, look up the commit, fetch the URL) before proceeding with the section where the reference appears.

5. Examples

5.1. Complete example

---
title: Migrate local file storage to object storage
task_type: feature
status: open
depends_on:
  - add-storage-abstraction-layer
scope:
  - src/storage/
  - config/
  - tests/storage/
tools:
  - filesystem
  - code_execution
  - web_fetch
---

## Context

User-uploaded files are currently written directly to the local filesystem under
`/var/uploads`. This breaks in multi-instance deployments because each instance
has its own disk. We need to move to an object storage backend (e.g., S3-compatible).

The storage abstraction layer introduced in @task:add-storage-abstraction-layer
defines the `StorageProvider` interface all new backends must implement.

Interface definition: @file:src/storage/provider.ts
Prior spike notes: @file:docs/spikes/object-storage-options.md

## Requirements

1. Implement a `S3StorageProvider` class that satisfies the `StorageProvider` interface
2. Read configuration (bucket name, region, credentials) from environment variables
   > Use the names defined in @file:config/storage.env.example
3. Replace all direct `fs.*` calls in `src/storage/local.ts` with the new provider
4. Add integration tests that run against a local S3-compatible server (e.g., MinIO)
5. Update `README.md` with setup instructions for the new environment variables

## Constraints

- Do not remove the `LocalStorageProvider` — it must remain available for local development
- Do not hardcode credentials anywhere in the codebase
- Keep the `StorageProvider` interface unchanged

## Acceptance criteria

- [ ] `S3StorageProvider` compiles and satisfies the `StorageProvider` interface
- [ ] File upload, download, and delete operations work against a MinIO instance
- [ ] The existing local storage tests continue to pass
- [ ] No AWS credentials appear in any committed file
- [ ] README documents the required environment variables

5.2. Minimal valid task

For simple tasks, all optional structure may be omitted. A task with only a title and a plain-prose body is valid:

---
title: Add a CONTRIBUTING guide to the repository
---

Write a CONTRIBUTING.md at the repository root.

1. Explain how to set up the local development environment
2. Describe the branching and pull request workflow
3. Document the commit message convention
   > We follow Conventional Commits: https://www.conventionalcommits.org
4. List the code style tools and how to run them

The spec does not REQUIRE ALL sections to be present—it only defines what they mean when they are.