Pm Tasks Asana

pm-tasks-asana

Adapter for Asana within the @llodev/pm-tasks-* family. Use the core skill's extraction phases, then apply Asana formatting and optionally publish/operate via the claude.ai Asana MCP server.

Routing

Asana model

Asana tasks have:

• Name (title, ≤80 chars for board view).
• Description (rich text; prefer **Section** bold labels — ## headings render inconsistently).
• Subtasks — one level deep. Custom fields and assignee do NOT auto-propagate from parent. subtaskDefaults.inheritParentFields lists the fields auto-copied from the parent (a floor, not a whitelist); every subtask still gets its own domain fields (e.g. Competência, Módulo) and due date filled from what that subtask actually touches — never left blank, never inherited unless its ID is listed.
• Sections — group tasks within a project.
• Custom fields — per-project; API always uses option GIDs, never display names.
• Multi-assignee — Asana allows multiple followers; primary assignee is a single field. Use task.assignee.add to add followers.

Phase 4 — Asana formatting

Apply the generic card from core's ../pm-tasks-core/references/generic-card.md. Then map to Asana:

• Title → task name.
• Sections of the generic card → bold **Section** labels inside description (not ##).
• "Implementation Checklist" + "Verification Checklist" → subtasks (flatten any nested bullets; Asana supports one level only).
• Labels → custom field options (resolved via .asana.json customFields[]).
• Number custom fields with a unit (.asana.json customFields[].unit) → convert the source value to the field's native unit before writing. E.g. an effort of "12 h" into a minutes field is 720, not 12.
• Number custom fields with rollsUpFromSubtasks: true (e.g. Asana's built-in Estimated time) → write only on leaf tasks. A task that has subtasks gets the field left empty: Asana already sums the subtasks into it, so writing the parent's own total on top double-counts. A task with no subtasks is filled normally. Never place such a field in subtaskDefaults.inheritParentFields.
• Due date → due_on (YYYY-MM-DD). The typed transport taskCreate also maps the core TaskCreateRequest.dueDate to due_on — see references/operations.md § Temporal handling for the create/start/close split.
• Assignee → assignee GID resolved from .asana.json members[] or me at publish time.

Phase 5 — MCP publish

Prerequisites: Asana MCP server (claude.ai Asana) connected in your agent. The MCP handles OAuth; the adapter never sees tokens. Configuration steps differ per agent — register the same Asana MCP endpoint your agent supports:

• Claude Code: claude mcp add asana -s project -- npx -y claude-ai-asana-mcp (or follow Anthropic's setup for the hosted claude.ai Asana connector).
• Cursor / Windsurf / Cline / Roo Code: add an entry to that agent's MCP settings JSON pointing at the same claude-ai-asana-mcp command (envelope identical to the Trello example in pm-tasks-trello/references/mcp-config.md).
• Codex: TOML entry under [mcp_servers.asana] in ~/.codex/config.toml.
• Other MCP-capable agents: consult that agent's MCP docs; the server command and OAuth flow are constant.

Strict order: 5.1 read .asana.json (full file) → 5.2.5 resolve assignee + custom fields + per-subtask field map → 5.2 preview & approval → 5.3 publish via MCP → 5.4 error handling.

MCP publish sequence:

1. Parent task — create_tasks with name, notes (description), projects: [projectGid], memberships: [{ project, section }], assignee (resolved GID), due_on, custom_fields (JSON string of {fieldGid: optionGid}). Omit every rollsUpFromSubtasks field from this map when the card has subtasks — Asana fills them from the subtasks in step 2.
2. Subtasks — create_tasks per subtask with parent: parentGid, name, assignee (inherited or per-subtask), custom_fields = the parent values for the fields in subtaskDefaults.inheritParentFields (auto-copy floor) plus each subtask's own domain fields (Competência, Módulo) and due date resolved from what it actually touches. Never leave a domain/date field blank because it is absent from inheritParentFields. Subtasks are leaves, so this is where every rollsUpFromSubtasks field carries its per-subtask value.
3. Tags (optional) — addTag per tag GID.
4. Confirm — list parent + subtasks with permalinks.

Attribution (opt-in)

Before calling the MCP create tool, read config.attribution. If enabled === true, prefix the comment with the commentPrefix returned by getAttribution() and append the descriptionFooter to the end of description. In autonomous mode ([autonomous] sentinel), the commentPrefix automatically becomes the autonomousCommentPrefix. See references/attribution.md in pm-tasks-core (added in v1.2.0).

Phase 5b — Autonomous

Skip 5.2 preview & approval. Apply autonomous-mode contract from ../pm-tasks-core/references/autonomous-mode.md. Audit log entries per ../pm-tasks-core/references/audit-log-format.md.

Asana-specific autonomous scope: autonomous.scope.projects[] + autonomous.scope.sections[] must include the target GIDs. Any custom-field write must be in autonomous.allow (task.create covers create-time field set; ongoing field changes are out of scope for v1.x).

Continuous operation in multi-task loops

Mandatory when the controller is executing a plan with multiple tasks autonomously. Mirror each task transition on the corresponding Asana task in real time — NEVER batch state updates at end-of-loop. See ../pm-tasks-core/references/autonomous-mode.md § Continuous operation across multi-task loops for the full contract and anti-patterns.

Asana-specific verb mapping:

Resolve <wipSectionGid> / <doneSectionGid> from .asana.json using defaults.wipSectionAlias / defaults.doneSectionAlias to look up the matching entry in sections[] by alias. Both must already be in autonomous.scope.sections — otherwise the verb returns OUT_OF_SCOPE.

Close preserves the plan (lifecycle fidelity): task.close sets completed: true; Asana auto-stamps completed_at (the real completion). Leave due_on = the original plan — never overwrite it at close. See references/operations.md § Temporal handling and ../pm-tasks-core/references/lifecycle-fidelity.md.

Asana caveat (per anti-patterns/asana.md): the MCP get_task doesn't return activity stories, so verifying the lifecycle programmatically is incomplete. The UI activity feed IS the human's audit log — keep it dense and accurate.

Phase 6 — CRUD operations (existing tasks)

For verbs other than task.create, jump directly to the operation. Verb → MCP tool mapping:

<task-ref> resolution: accept Asana permalinks (https://app.asana.com/0/<project>/<task>), bare GIDs, or aliases from .asana.json taskAliases[].

Phase 7 — Plan-execution mode

When the calling agent passes a plan reference (a path to a markdown plan file, a plan slug, or an explicit list of expected task titles), this skill loads .asana.json via requireConfig and uses discoverPlanTasks (from @llodev/pm-tasks-core) to triage which tasks in the plan already exist as cards in scope. The skill returns the triage report { found, missing, ambiguous } — the calling agent decides how to act on each bucket (create missing cards via Phase 4 + 5; disambiguate by picking the right ambiguous card; proceed with existing).

The skill does not assume any particular implementation strategy. It does not drive the calling agent's task loop, does not depend on any specific orchestration framework, and does not require any markup beyond what is already documented for task.create and the autonomous-mode contract. When the calling agent finishes a task and asks the skill to record progress, it invokes the standard verbs (task.move, checklist.check, task.comment.add, task.close) directly — the same path used by Phase 5b autonomous mode.

Full contract: triggers, discovery semantics, ConfigRequiredError handling, failure modes table, and the hook contract for Phase 5 are documented in skills/pm-tasks-core/references/plan-execution.md (added in v1.9.0).

Result envelope

Every verb returns the core contract shape (see ../pm-tasks-core/references/contract.md §Result envelope):

{
  "ok": true,
  "verb": "task.create",
  "tool": "asana",
  "ref": { "id": "<gid>", "url": "https://app.asana.com/0/<project>/<gid>", "alias": "<optional>" },
  "details": {/* Asana-specific (see table below) */}
}

Asana-specific details per verb:

On failure: { ok: false, verb, tool, error: { code, message, retriable } }. Common codes: FORBIDDEN_VERB, OUT_OF_SCOPE, NOT_FOUND, RATE_LIMITED, PARTIAL_CREATE (subtask failed mid-create — see ../pm-tasks-core/references/contract.md §Partial-create recovery).

Anti-patterns

See anti-patterns/asana.md — paste health, custom-field rules, GID requirements, partial-create handling.

Standalone fallback

If @llodev/pm-tasks-core is not installed: ask the user for minimum input (title + subtask names) and produce a paste-ready Asana task body from this content alone. Quality is degraded — no scope/audience/fidelity inference. Print: "Install @llodev/pm-tasks-core for the full flow."

Config

Lookup order: <git-root>/.asana.json → ~/.config/llodev/pm-tasks/asana.json → abort with init instructions. Schema: schemas/config.json. Secrets NEVER in JSON — Asana MCP holds OAuth; init uses LLODEV_PM_TASKS_ASANA_PAT env var only.

Narration language. When .asana.json sets locale, agent-authored narration — comments the agent writes, autonomous commit/PR copy, code comments — MUST use it. The plan's language still governs task title/description/checklist text. pm-tasks-core-doctor C-LANG-1 warns if unset or set to a locale with no installed i18n bundle. See pm-tasks-core § Narration language.

Init

npx @llodev/pm-tasks-asana init

See ../pm-tasks-core/references/init-ux.md for the shared flow. Asana init reads workspaces / projects / sections / custom fields via the Asana REST API using a Personal Access Token (env LLODEV_PM_TASKS_ASANA_PAT).

Pass --doctor to run workspace health checks before prompting:

npx @llodev/pm-tasks-asana init --doctor

Runs core checks (C-FS-1..3, C-CFG-1..4) plus Asana-specific probes (C-ASN-1..3, gated on LLODEV_PM_TASKS_ASANA_PAT). Full check matrix in skills/pm-tasks-core/references/doctor.md.