Manifest Walkthrough

A line-by-line walkthrough of the agentic-to-do APP.md manifest explaining every field and design decision.

The agentic-to-do package ships with a complete APP.md manifest that covers every part of the Agent Applications v1 contract. This walkthrough steps through each section and explains the “why” behind each field and design decision.

Source: davetist/agentapplications

1. YAML frontmatter

The frontmatter is the first thing a runtime reads. It is machine-readable metadata that a catalog can index without loading the full APP.md body.

schema: agentapplications/v1
kind: app
slug: agentic-to-do
name: Agentic To-Do
description: Self-contained persistent to-do list operated through a JSON-first CLI
version: 0.1.0
entry:
  command: node app/cli.js
commands:
  - add
  - list
  - get
  - update
  - complete
  - remove
skills:
  - agentic-to-do-usage
scheduling: supported
confirmationRequired:
  - remove

schema: agentapplications/v1 Declares the package format version. A runtime uses this to determine which fields and behaviors to expect. Pinning to v1 makes compatibility explicit.

kind: app Distinguishes an application package from other kinds a future schema version might define, such as a pure skill package.

slug: agentic-to-do A stable, lowercase, hyphenated identifier. A runtime can use the slug to reference the package unambiguously even if the human-readable name changes.

name: Agentic To-Do The display name shown in catalogs and agent responses.

description A short, concrete summary written for both humans and runtimes. It says what the application does and how it works — “JSON-first CLI” — without marketing language.

version: 0.1.0 Semantic versioning lets runtimes and agents track whether they are operating against the expected contract.

entry.command: node app/cli.js The exact shell command a runtime should run to invoke the application. Keeping this explicit means the package does not depend on a globally installed binary or an alias. Any runtime with Node.js can run it.

commands An enumerated list of the supported operations. A runtime can surface these to an agent without reading the full body, and an agent can quickly check whether a desired operation exists before loading the skill.

skills References the local skill by its slug. When a runtime activates the package, it knows to load skills/agentic-to-do-usage/SKILL.md alongside APP.md to give the agent operating guidance.

scheduling: supported A boolean-style flag that tells a runtime the application accepts scheduling inputs — specifically the --due-at flag on add and update. Declaring this at the manifest level means runtimes do not have to parse the command descriptions to discover it.

confirmationRequired: [remove] Lists commands that require explicit confirmation before execution. Publishing this in the frontmatter lets a runtime enforce the rule or surface it to an agent without reading the full body.

2. Purpose section

## Purpose

Agentic To-Do is a minimal Agent Applications v1 example that gives agents a stable CLI
for managing a persistent to-do list. The application owns its own JSON state under
`app/state/todos.json` and does not depend on chat history or prompt memory.

The Purpose section is the first prose an agent reads after the frontmatter. It answers two questions immediately:

1. What is this? A minimal v1 reference example — agents know the scope is intentionally small.
2. How does state work? The application owns its state in a file; it does not depend on chat history or prompt memory.

The second point is important. Agents that understand this cannot make the mistake of trying to recall previous interactions instead of querying the CLI. The application is the source of truth.

3. CLI section

## CLI

- Entrypoint: `node app/cli.js`
- Default output: JSON on stdout for both success and failure cases
- State override for tests or isolated runs: `AGENTIC_TODO_STATE_FILE=/tmp/todos.json`

This section gives an agent everything it needs to start issuing commands:

Entrypoint repeats entry.command from the frontmatter in a human-readable context. Agents do not have to look back at the frontmatter to know what to type.

Default output establishes the contract upfront: JSON on stdout, always, including failures. An agent that knows this does not need to handle different output formats depending on whether a command succeeded.

State override exposes the AGENTIC_TODO_STATE_FILE environment variable. This is not just a developer convenience — it is a documented part of the contract that lets automated tests or isolated runs point at a different file without touching the package’s default state.

4. Commands section

Each command gets its own subsection with a signature showing the required positional argument and all optional flags.

add

### `add <title> [--description <text>] [--due-at <iso-date>]`
Create an open to-do item.

<title> is required and positional. --description and --due-at are optional. Items are always created with status: "open".

list

### `list [--status all|open|completed]`
List items filtered by status. Defaults to `all`.

The --status flag is optional. Documenting the default (all) means an agent does not have to pass the flag to get a complete list.

get

### `get <id>`
Fetch a single to-do item.

Takes a single stable ID. The short description is intentional — get has no optional flags and the behavior is self-evident from the signature.

update

### `update <id> [--title <text>] [--description <text>] [--due-at <iso-date>] [--clear-due-at]`
Update one or more mutable fields.

All fields after <id> are optional, but at least one must be provided or the command returns a validation error. The --clear-due-at flag handles the specific case of removing an existing due date — passing --due-at with an empty string would be ambiguous, so the manifest defines a dedicated flag for this operation.

complete

### `complete <id>`
Mark an item as completed.

No optional flags. The operation sets status: "completed" and records completedAt. If the item is already completed, the command returns it unchanged rather than erroring.

remove

### `remove <id> --confirm`
Delete an item. The `--confirm` flag is required because the operation is destructive.

--confirm appears in the signature as required, not optional. The inline explanation — “because the operation is destructive” — is there so an agent reading the manifest knows exactly why the flag exists and does not try to omit it.

5. Output section

## Output

Successful commands return structured JSON, for example:

{
  "ok": true,
  "command": "list",
  "count": 1,
  "items": [
    {
      "id": "td_0001",
      "title": "Write docs",
      "description": "",
      "status": "open",
      "dueAt": "2026-04-05",
      "createdAt": "2026-04-01T00:00:00.000Z",
      "updatedAt": "2026-04-01T00:00:00.000Z",
      "completedAt": null
    }
  ]
}

Failures return structured JSON with a non-zero exit code, for example:

{
  "ok": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "remove requires --confirm."
  }
}

The Output section defines the contract an agent uses to interpret every response.

The ok field is the single top-level signal. An agent checks ok first, then reads the rest of the payload.

The command field in success responses echoes which command ran. This is useful when an agent is parsing output asynchronously or logging responses.

The error object on failure has two fields:

• code — a machine-readable string like CONFIRMATION_REQUIRED or NOT_FOUND that an agent can match without parsing the message text.
• message — a human-readable explanation an agent can surface directly.

Non-zero exit code on failure means a runtime or shell script can detect errors without parsing JSON at all. The combination of a non-zero exit code and structured error JSON means both automated pipelines and agents can handle failures reliably.

Including a real example for both success and failure removes ambiguity. An agent reading the manifest sees exactly what fields to expect before issuing any command.

6. State section

## State

The application stores data in `app/state/todos.json`. IDs are stable and increment as
`td_0001`, `td_0002`, and so on.

Two facts are stated here that matter to agents:

Where data lives — app/state/todos.json is a file path relative to the package root. An agent that needs to inspect raw state knows where to look, though the intended access path is always the CLI.

How IDs work — IDs like td_0001 are stable. Once an item is created, its ID never changes. The zero-padded four-digit format (0001, 0002) means IDs sort lexicographically in the same order they were created, which makes them predictable in list output.

This section deliberately does not document the internal structure of todos.json. The file format is an implementation detail. The manifest only documents what agents need to know to operate the CLI reliably.

7. Scheduling section

## Scheduling

Scheduling is supported through the optional `--due-at` field on `add` and `update`.

This section expands on the scheduling: supported frontmatter field with the concrete details agents need: which commands accept --due-at and that the field is optional.

The --due-at value must be an ISO-8601 date or datetime string. Passing a value that cannot be parsed as a date results in a VALIDATION_ERROR.

You can also remove a previously set due date on an existing item by passing --clear-due-at to update instead of a new date value.

Use --due-at with a date like 2026-04-05 for day-level precision, or with a full ISO-8601 datetime like 2026-04-05T09:00:00.000Z for time-level precision.

8. Confirmations section

## Confirmations

`remove` requires explicit confirmation via `--confirm`.

This section maps directly to confirmationRequired: [remove] in the frontmatter. It states the rule in plain prose so an agent reading the body gets the same information as one reading only the frontmatter.

The design choice here is intentional: remove is the only destructive operation in the package. Rather than asking an agent to infer which commands are safe, the manifest makes the requirement explicit in three places:

1. The frontmatter confirmationRequired field.
2. The command signature (remove <id> --confirm).
3. This dedicated Confirmations section.

If an agent calls remove without --confirm, the CLI returns a structured failure immediately:

{
  "ok": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "remove requires --confirm."
  }
}

The CONFIRMATION_REQUIRED error code lets a runtime or agent detect this specific failure and prompt for confirmation before retrying.

9. Skills section

## Skills

Load `skills/agentic-to-do-usage/SKILL.md` when an agent needs concise operating
guidance for the CLI.

This section tells an agent when and how to load the local skill. The path is relative to the package root and maps to the skills: [agentic-to-do-usage] entry in the frontmatter.

The skill (skills/agentic-to-do-usage/SKILL.md) contains safe operating rules and common command examples. It is deliberately separate from APP.md rather than embedded in it. This separation follows the same progressive disclosure model as Agent Applications overall:

• APP.md defines the boundary and CLI contract — read at activation.
• SKILL.md provides operating guidance — loaded when an agent needs to act.

Keeping them separate means a runtime can load the manifest for catalog purposes without also loading operating guidance it may not need yet. When an agent is ready to operate the application, it loads the skill and gets concise, actionable instructions without having to re-parse the full contract.