> ## Documentation Index > Fetch the complete documentation index at: https://agentapplications.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://github.com/davetist/agentapplications/tree/main/example/agentic-to-do) 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. ```yaml theme={null} 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. ```markdown theme={null} ## 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. ```markdown theme={null} ## 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. Each command gets its own subsection with a signature showing the required positional argument and all optional flags. ### add ```markdown theme={null} ### `add [--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 ```markdown theme={null} ### `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 ```markdown theme={null} ### `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 ```markdown theme={null} ### `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 ```markdown theme={null} ### `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 ```markdown theme={null} ### `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. </Accordion> <Accordion title="5. Output section"> ```markdown theme={null} ## Output Successful commands return structured JSON, for example: ``` ```json theme={null} { "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 } ] } ``` ```markdown theme={null} Failures return structured JSON with a non-zero exit code, for example: ``` ```json theme={null} { "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. </Accordion> <Accordion title="6. State section"> ```markdown theme={null} ## 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. </Accordion> <Accordion title="7. Scheduling section"> ```markdown theme={null} ## 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. <Tip> 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. </Tip> </Accordion> <Accordion title="8. Confirmations section"> ```markdown theme={null} ## 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: ```json theme={null} { "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. </Accordion> <Accordion title="9. Skills section"> ```markdown theme={null} ## 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. </Accordion> </AccordionGroup>