Plan work as Tasks

The Factory only works on Tasks. A plan is a set of Tasks that share an epic label, connected by dependencies. You can create one in three ways:

All three end with the same browser review and the same Tasks.

What a good Task contains

Each Task should fit in one agent's context and carry its own proof. A worker reads only its Task, so put everything it needs in the Task.

Limits: 1–50 Tasks per plan. Keys are lowercase ([a-z][a-z0-9_-]*) and at most 31 characters. No cycles.

A. Ask the overseer

1. Start the Factory: archdev agents factory run (see Run the Factory).

2. Type your goal at the prompt:

   Paste into your agentCopy prompt

   Add CSV export to the results page. Exports must respect the active filters and
   the user's permissions. End-to-end tests for the API and the download.
   

3. The overseer drafts a Task graph and opens a review in your browser. Continue at Review and approve.

B. Ask your coding agent

In a session where you've already discussed the work (install the skill first with archdev setup --skills --skill tasks --scope repository, then restart the agent):

Use the tasks skill to turn this plan into ArchDev Tasks under epic "CSV export".

What happens:

1. The agent reads archdev tasks guide and archdev tasks graph schema.
2. It writes a plan file and checks each Task with a fresh subagent: wrong test paths, missing context, undefined config.
3. It runs archdev tasks review start --file <plan>.json, which opens the review page.

Continue at Review and approve.

C. Write the plan file yourself

Run these from the repository the work belongs to. Tasks are linked to the current checkout's GitHub repository, and the Factory only claims Tasks from its own repository.

1. Pick or create a project. It's optional, but recommended: it groups the epic on the Tasks page. Without a project_id, the epic label gets a suffix such as CSV export (ab12cd), and --epic "CSV export" won't match it.

archdev projects list --query "CSV export"
archdev projects create "CSV export" --description "Filtered CSV export from the results page"

Copy the prj_… ID.

2. Write plan.json:

{
  "action": "preview",
  "epic": "CSV export",
  "nodes": [
    {
      "key": "export-api",
      "title": "Export respects filters",
      "objective": "Add GET /api/export, which streams the filtered, authorized rows as CSV.",
      "implementation": ["1. Add GET /api/export using the existing filtered query.", "2. Stream rows as CSV."],
      "acceptance": ["Export returns exactly the rows the user can see under the active filters."],
      "verification": ["tests/export-api.e2e.test.ts: 'filtered export returns only authorized rows'"],
      "risk": { "grade": "low", "notes": "New read-only endpoint." },
      "project_id": "prj_0123456789abcdef01234567"
    },
    {
      "key": "export-ui",
      "title": "Users can download filtered results",
      "objective": "Wire the Download button to /api/export with the current filters.",
      "implementation": "1. Call /api/export with the active filters from the results page.",
      "acceptance": ["The downloaded file matches the active filters."],
      "verification": ["tests/export-ui.e2e.test.ts: 'download matches filters' (browser download, file inspected)"],
      "risk": { "grade": "low" },
      "project_id": "prj_0123456789abcdef01234567",
      "depends_on": ["export-api"],
      "dependency_reasons": { "export-api": "Needs the endpoint." }
    }
  ]
}

Replace prj_0123456789abcdef01234567 with your project ID. "action": "preview" is required. Every depends_on entry needs a matching dependency_reasons entry.

3. Open the review:

archdev tasks review start --file plan.json

Or, to create the Tasks without a review:

archdev tasks graph import --file plan.json

Imported 2 tasks in 2 dependency waves
Plan: <hash>

graph import creates the Tasks immediately; it has no dry run. Use review start to see the plan before anything is created.

Review and approve

archdev tasks review start runs a local review server and opens it in your browser. Over SSH it prints an encrypted relay link instead. The URL contains a private token, so don't share it. The command keeps running and streams feedback events until you stop it, so leave that terminal open and use another one.

On the review page:

1. Read each Task, its dependencies and the major decisions the planner raised (each with a recommended option).
2. Leave comments or request changes. Your agent (or the overseer) receives them, revises the plan and updates the page.
3. Click Approve & save. The Tasks are created with their dependency edges. The status changes to saved; only saved means the save succeeded.
4. Stop the review server: archdev tasks review stop <session-file>, using the session file path from the ready event review start printed.

Approving the same plan again later updates the same Tasks, and Tasks removed from the plan are closed. This depends on the receipt file review start keeps for that plan path. If the receipt is lost, a new review creates duplicates.

Plan checks

Before saving, the plan is checked for problems a worker can't solve before merge:

To accept a blocking finding anyway, pass --allow-lint <check> to graph import, or add it to allow_lint in the plan file.

Check what's ready

archdev tasks ready --explain --epic "CSV export"

For the example plan, export-api is ready and export-ui is blocked (open_blockers). When export-api merges and closes, export-ui becomes ready on its own.

You can also see the plan at archdev.ai/tasks: use the Epics tab for progress per epic and Graph for the dependency chains.

Why a Task isn't picked up

A worker claims a Task only when all of these are true:

• It is open and has no open blockers.
• It is assigned to you, in your organization's tasks. Plans you save are assigned to you. Tasks saved with review start --team go to a collection the Factory doesn't read.
• It belongs to the repository the Factory runs in.
• It isn't kind: human or kind: post_deploy.
• No other in-flight Task is changing the same files.
• In --dispatch manual mode, you released it (see Run the Factory).

Next: Run the Factory.