| name | automatic-features |
| description | How to use Automatic's feature tracking system — creating, progressing, and updating per-project work items via the Automatic MCP service. Activate when working on a project managed by Automatic that has feature tracking enabled. |
| authors | ["Automatic"] |
Automatic Features — Agent Guide
Automatic provides per-project feature tracking: a structured backlog of work items visible to the user in the Automatic UI and readable/writable by agents via MCP tools.
Features are the shared source of truth for what needs to be built. Users create and prioritise features; agents pick them up, progress them, and log updates as work proceeds.
Feature Model
Each feature has:
| Field | Values |
|---|
id | UUID (returned on create — store it for subsequent calls) |
title | Short description of the work |
description | Full markdown specification |
state | backlog · todo · in_progress · review · complete · cancelled |
priority | low · medium · high |
effort | xs · s · m · l · xl |
assignee | Agent id or name (free text) |
tags | List of strings for filtering |
linked_files | File paths in the project this feature relates to |
archived | true if archived — hidden from Kanban board; retrieve with include_archived: true |
updates | Append-only log of markdown progress notes |
Archived ≠ Cancelled. Archiving is a separate flag that hides a feature from normal views without changing its lifecycle state. An archived feature retains its state value and is restored to its original column when unarchived. Use cancelled when work is deliberately abandoned; use archive for features that are deferred or parked without being deleted.
MCP Tools
All tools require a project parameter matching the project name registered in Automatic. Use automatic_list_projects if you are unsure of the correct name.
automatic_list_features
List all features for a project, grouped by state. Active and archived sets are mutually exclusive — a single call returns one or the other, not both.
project: string — project name
state: string (opt) — filter to one state: backlog | todo | in_progress | review | complete | cancelled
include_archived: boolean (opt) — default false; pass true to list archived features instead of active ones
Returns titles, IDs, priorities, effort, and assignees. Always call this at session start with state: "todo" to see what is planned for you. Archived features are excluded automatically.
automatic_get_feature
Get full detail for a single feature, including its description and complete update history. Works for both active and archived features.
project: string — project name
feature_id: string — UUID from list_features
The response includes an Archived field so you know immediately whether the feature is in its normal state or archived. Read this before starting work so you understand the full specification and any prior progress notes.
automatic_create_feature
Create a new feature in the project backlog.
project: string — project name (required)
title: string — short title (required)
description: string (opt) — markdown specification
priority: string (opt) — low | medium | high (default: medium)
assignee: string (opt) — agent id or name
tags: string[] (opt) — searchable labels
linked_files: string[] (opt) — relevant file paths
effort: string (opt) — xs | s | m | l | xl
created_by: string (opt) — identifies which agent created it
Returns the created feature including its id. Save the id — you will need it for all subsequent calls.
When to use: When you discover work during implementation that is not yet tracked. Capture it rather than doing it silently.
automatic_update_feature
Update a feature's metadata fields. Omit any field to leave it unchanged.
project: string — project name
feature_id: string — UUID
title: string (opt)
description: string (opt)
priority: string (opt)
assignee: string (opt)
tags: string[] (opt)
linked_files: string[] (opt)
effort: string (opt)
When to use: To refine the description after investigating the codebase, or to correct priority/effort estimates.
automatic_set_feature_state
Transition a feature to a new lifecycle state.
project: string — project name
feature_id: string — UUID
state: string — backlog | todo | in_progress | review | complete | cancelled
When to use: Call this at the key transition points in your workflow (see below). Do not skip states — move through them in order so the user can follow progress in the UI.
automatic_archive_feature
Archive a feature, hiding it from the Kanban board and from default list_features results. The feature's state is preserved unchanged so it can be restored to its original column when unarchived.
project: string — project name
feature_id: string — UUID
When to use: When a feature is being deferred indefinitely, is no longer relevant, or is parked at the user's request — but should not be permanently deleted. Do not archive features as part of normal workflow progression; use set_feature_state for that.
automatic_unarchive_feature
Restore an archived feature to active status. It reappears on the Kanban board in its original state column.
project: string — project name
feature_id: string — UUID of an archived feature
When to use: When the user decides to resume work on a previously parked feature.
automatic_add_feature_update
Append a markdown progress note to a feature's update log.
project: string — project name
feature_id: string — UUID
content: string — markdown text (required)
author: string (opt) — agent id or name
Updates are append-only and timestamped. They appear in the Automatic UI so the user can follow what you are doing without asking.
When to use: After each significant unit of work — a decision made, a blocker found, a sub-task completed. Be specific. Bad: "Made progress." Good: "Implemented JWT validation in src/auth/middleware.ts. Chose HS256 over RS256 because no external verifier is needed."
automatic_delete_feature
Permanently delete a feature and all its updates.
project: string — project name
feature_id: string — UUID
This cannot be undone. Prefer archiving over deletion. Only delete features that were created by mistake or that contain no useful history.
Standard Agent Workflow
Follow this sequence for every feature-driven session:
1. Orient
automatic_list_features(project: "my-project", state: "todo")
Identify the highest-priority feature to work on. If nothing is in todo, check backlog and ask the user which to start. Archived features will not appear — that is intentional.
2. Read the specification
automatic_get_feature(project: "my-project", feature_id: "<id>")
Read the full description and all prior updates. Do not start work until you understand the full scope. Check the Archived field in the response — if true, confirm with the user before proceeding.
3. Claim it
automatic_set_feature_state(project: "my-project", feature_id: "<id>", state: "in_progress")
automatic_update_feature(project: "my-project", feature_id: "<id>", assignee: "claude-code")
Move to in_progress and set assignee to your agent identity before touching any code. This signals to the user (and other agents) that the work is active and who is responsible for it. Use the same identifier consistently across all calls in the session (e.g. "claude-code", "cursor", "gpt-4o").
4. Work and log
As you work, append updates after each meaningful step:
automatic_add_feature_update(
project: "my-project",
feature_id: "<id>",
content: "Investigated the auth module. The existing `TokenService` at `src/services/token.ts` handles issuance but not validation. Will extend it rather than creating a new class.",
author: "claude-code"
)
Log at minimum:
- After investigating the codebase (what you found, what approach you chose)
- When you hit a blocker
- After completing a significant sub-task
- Before any major decision point
5. Request review
automatic_set_feature_state(project: "my-project", feature_id: "<id>", state: "review")
automatic_add_feature_update(
project: "my-project",
feature_id: "<id>",
content: "Implementation complete. Changes: `src/auth/middleware.ts` (new validation), `src/routes/api.ts` (middleware applied), `tests/auth.test.ts` (6 new tests, all passing). Ready for review.",
author: "claude-code"
)
Always move to review, never to complete. The user marks features complete after they verify the work.
6. Capture discovered work
If you find additional work that was not part of the original feature:
automatic_create_feature(
project: "my-project",
title: "Refresh token expiry not enforced",
description: "Found during auth implementation. Refresh tokens are issued without an expiry check on use...",
priority: "high",
created_by: "claude-code"
)
Do not silently fix unscoped work. Create a feature for it so the user is aware.
Rules
- Always set assignee — when claiming a feature, immediately call
automatic_update_feature with your agent identity in assignee. Never leave a feature in_progress without an assignee.
- Never mark a feature
complete — that is the user's call after reviewing your work.
- Always log updates — the user should be able to read the update history and understand exactly what you did and why, without asking.
- One feature at a time — move a feature to
in_progress before starting it. Do not have multiple features in_progress simultaneously.
- Read before starting — always call
automatic_get_feature before beginning work so you have the full specification and prior context.
- Capture, don't silently fix — if you discover unscoped work, create a backlog feature for it rather than doing it without the user's knowledge.
- Archived features are excluded by default —
list_features never returns archived features unless include_archived: true is passed. Do not assume a missing feature has been deleted; it may be archived.
