@llodev/pm-tasks-asana 0.0.0-pr-22-9002a06

package/CHANGELOG.md

@@ -0,0 +1,282 @@
+# @llodev/pm-tasks-asana
+
+## 1.6.0
+
+### Minor Changes
+
+- [#20](https://github.com/llodev/skills/pull/20) [`78106ab`](https://github.com/llodev/skills/commit/78106ab42ed317ba865906d25701ade4532396ec) Thanks [@lloliveiradev](https://github.com/lloliveiradev)! - **pm-tasks v1.9.0 — Headless runtime + Plan-execution mode (Option E)**
+
+  Three coordinated minor bumps shipping the agent-agnostic headless runtime
+  and the F15 plan-execution mode. Skill-driven flows are unchanged; this
+  release adds a programmatic entry point and a new mode the calling agent
+  can opt into when it has a plan file to execute.
+
+  **`@llodev/pm-tasks-core@1.8.0 → 1.9.0`** (minor)
+
+  - New: `@llodev/pm-tasks-core/runtime` subpath exposes `createCoreRuntime`,
+    the `Transport` interface, 7 verb handlers, `RuntimeContext`, and the
+    full set of request/response types. Pure: no MCP imports, no transport
+    implementation — adapters provide the wiring.
+  - New: `@llodev/pm-tasks-core/plan-execution` module exports
+    `requireConfig` + `ConfigRequiredError`, `discoverPlanTasks` +
+    `resolvePlanRef` + `parseH3Titles` + `filenameToSlug` (discovery
+    helpers — `PlanRef` accepts `string[]` titles, a `.md` path with H3
+    parsing, or a bare slug), `onTaskStart` + `onTaskComplete` (boundary
+    hooks with best-effort dispatch, `ALREADY_IN_STATE` → skipped
+    classification, process-local idempotency memo keyed by
+    `${taskId}|${commitSha}`), and `__resetHookCacheForTests` (test escape
+    hatch).
+  - New: `pm-tasks-core/references/plan-execution.md` documents the full
+    contract (triggers, discovery semantics, hook classification table,
+    failure modes, `ConfigRequiredError` shape).
+  - New: `pm-tasks-core/references/agent-agnostic-lint.md` + a stand-alone
+    `scripts/checks/agent-agnostic-lint.mjs` that bans `superpowers`,
+    `sdd`, `Claude Code`, `Claude-only`, `Claude assumes` in SKILL body
+    content while allowlisting `claude-code` in `compatibility.agents`
+    frontmatter, vendor product names (`claude.ai Asana`,
+    `claude-ai-asana-mcp`), and other context-aware exemptions.
+  - Internal: tarball size budget raised 14.1 → 18.5 kB across Phase 4
+    and Phase 5 (covering the plan-execution module + hook helpers + full
+    JSDoc on every exported symbol).
+
+  **`@llodev/pm-tasks-asana@1.5.0 → 1.6.0`** (minor)
+
+  - New: `@llodev/pm-tasks-asana/adapter` subpath exposes
+    `createAdapter({ configPath, mcp, session?, language? })` returning a
+    `Runtime`. The `mcp: McpCaller` callback is the caller's only
+    obligation — receives a fully-qualified `mcp__claude_ai_Asana__*` tool
+    name + args object, returns the MCP server's raw response.
+  - New: `pm-tasks-asana/src/transport-asana.ts` implements the
+    `Transport` interface against `mcp__claude_ai_Asana__*` tools.
+    Asana-specific deltas: `closeListOrSectionId` ignored at the transport
+    layer (Asana has no list-on-close concept), ISO-8601 → `YYYY-MM-DD`
+    conversion via `isoToDueOn` helper for `taskDueDateSet`,
+    `INVALID_REQUEST` short-circuit BEFORE the MCP call on malformed
+    `dueAt`, single-assignee model for `taskAssigneeAdd`.
+  - SKILL.md routing table gained a Plan-execution row; Phase 7 narrative
+    section forward-references the new `references/plan-execution.md`
+    doc in `pm-tasks-core`.
+
+  **`@llodev/pm-tasks-trello@1.5.0 → 1.6.0`** (minor)
+
+  - New: `@llodev/pm-tasks-trello/adapter` subpath exposes
+    `createAdapter({ configPath, mcp, session?, language? })` returning a
+    `Runtime`. Same shape and contract as the Asana adapter.
+  - New: `pm-tasks-trello/src/transport-trello.ts` implements the
+    `Transport` interface against `mcp__trello__*` tools. Trello-specific
+    behavior: `taskClose` archives the card AND optionally moves it to
+    `closeListOrSectionId` when provided (Trello's "Done" list pattern).
+  - SKILL.md routing table gained a Plan-execution row mirroring the
+    Asana adapter; identical Phase 7 narrative section.
+
+  **Skill-judge gate**
+
+  Modified `pm-tasks-asana/SKILL.md` and `pm-tasks-trello/SKILL.md`
+  (Phase 4.3) added the Plan-execution mode routing row + Phase 7 section.
+  Measured drift sits within the documented noise band ([-2, +2]); the
+  agent-agnostic-lint rule shipped in this release codifies the
+  allowlist that earlier scoring assumed. If drift is within tolerance,
+  bypass with `SKIP_SKILL_JUDGE_GATE=1 make release-version`.
+
+  **Breaking changes**
+
+  None. All Phase 1-5 additions are pure surface area additions:
+
+  - `/runtime` and `/adapter` subpaths are NEW exports (no prior consumers)
+  - `/plan-execution` helpers are NEW exports
+  - Existing skill-driven flows + the 7-verb CRUD contract on the autonomous
+    path are unchanged
+
+  **Migration**
+
+  No migration needed. Existing consumers continue to import from the
+  package root. New code can opt into the runtime by importing from
+  `@llodev/pm-tasks-{trello,asana}/adapter` or the helpers from
+  `@llodev/pm-tasks-core/runtime` and `@llodev/pm-tasks-core/plan-execution`.
+
+### Patch Changes
+
+- Updated dependencies [[`78106ab`](https://github.com/llodev/skills/commit/78106ab42ed317ba865906d25701ade4532396ec)]:
+  - @llodev/pm-tasks-core@1.9.0
+
+## 1.5.0
+
+### Minor Changes
+
+- 1200b4e: v1.8.0 — Observability v1. pm-tasks-core-doctor CLI validates workspace config / autonomous allowlist / audit writability / (when probes are injected) MCP & network reach BEFORE the first publish attempt fails noisily. Adapter init bins expose `--doctor` for per-tool checks (C-TRL-1..3 + C-ASN-1..3, gated by auth env). Smart audit-log rotation (size + age + multi-tool, atomic, idempotent, gzipped archives, keep-N) replaces the rudimentary shell script; new `rotate-audit.mjs` CLI emits structured JSON status. Pre-release gate now blocks on doctor errors. Closes roadmap §2.4 O1 + O3.
+
+### Patch Changes
+
+- Updated dependencies [1200b4e]
+  - @llodev/pm-tasks-core@1.8.0
+
+## 1.4.0
+
+### Minor Changes
+
+- v1.5.0 — Adapters TypeScript migration, @llodev/pm-tasks-testkit, 7th canonical verb `task.move`, E2E canary.
+
+  **Core (`@llodev/pm-tasks-core` 1.4.0 → 1.5.0)** — adds the 7th canonical verb `task.move` to the public contract.
+
+  - New verb `task.move({ cardId, targetList })` formalizes the WIP transition that the autonomous-mode lifecycle has always required but no canonical verb expressed. `targetList` accepts the enum `"open" | "wip" | "done"` plus raw list IDs.
+  - `task.move` is INDEPENDENT of `task.close`: move only repositions, close moves AND sets the completion flag. Useful in adapters where the visual transition and the closed-flag are separate operations (Asana section change vs. `completed: true`).
+  - Schema regex updated to recognize `task.move` as canonical (no namespace prefix required).
+  - `pm-tasks-core/schemas/adapter-manifest.schema.json` + `references/contract.md` + `references/crud-vocabulary.md` + `references/autonomous-mode.md` updated.
+  - Contract-check (`scripts/checks/contract-check.mjs`) `CANONICAL_VERBS` Set updated; regression test added.
+  - Additive only — existing consumers calling the original 6 verbs continue to work unchanged.
+
+  **Adapters (`@llodev/pm-tasks-asana` 1.3.1 → 1.4.0, `@llodev/pm-tasks-trello` 1.3.1 → 1.4.0)** — full TypeScript migration mirroring core's v1.4.0 pattern.
+
+  - Source moved from `scripts/init.mjs` to `src/bin/init.ts` (strict TS).
+  - Build pipeline: `tsc` produces `dist/bin/init.{js,d.ts,js.map,d.ts.map}`. `dist/bin/init.js` is `chmod +x` so the bin works on install.
+  - `package.json` exports map points at compiled `dist/`; `bin` field exposes `npx @llodev/pm-tasks-<tool> init`.
+  - i18n parity tests migrated from `node:test` to Vitest 2.x (2/2 tests per adapter).
+  - Both adapters now declare `task.move` in their `manifest.json` `verbs` array (7 canonical verbs) and document the MCP mapping in `references/operations.md`:
+    - Trello: `mcp__trello__move_card({ cardId, idList })` resolving `"wip"`/`"done"`/`"open"` from `lists.<alias>` in `.trello.json`.
+    - Asana: `mcp__claude_ai_Asana__update_tasks` with `memberships: [{ project, section }]` resolving via `defaults.<state>SectionAlias` in `.asana.json`.
+  - Trello autonomous overlay (`pm-tasks-trello/references/autonomous.md`) updated to invoke canonical `task.move` at task start and before task close.
+  - Backwards compatibility: consumers keep importing `@llodev/pm-tasks-core/init-lib` via the subpath; resolution now hits the v1.5.0 dist.
+
+  **Testkit (`@llodev/pm-tasks-testkit` 0.0.0 → 0.1.0)** — new package, first release.
+
+  - Pure TypeScript library. 7 in-memory fakes covering every canonical verb: `task.create`, `task.move`, `task.close`, `task.comment.add`, `task.due-date.set`, `task.assignee.add`, `checklist.check`.
+  - `createFakeAdapter({ idGenerator?, clock? })` returns an adapter-shaped object with all 7 verbs plus introspection (`getTask`, `getAllTasks`, `reset`).
+  - `peerDependencies`: `@llodev/pm-tasks-core ^1.4.0`.
+  - Useful for testing custom skills/adapters without hitting real MCP servers; 14/14 vitest tests cover each fake's behavior and idempotency.
+
+  **Pipeline hardening — E2E canary** — `scripts/checks/canary-e2e.mjs` packs all 4 packages, npm-installs them in a clean sandbox, and exercises core/asana/trello/testkit smoke checks. Wired into `make e2e`, a new `.github/workflows/e2e.yml` (PR + manual dispatch), and as a gate in `release.yml`. Runs in ~3.4 s; catches tarball drift the snapshot test alone misses.
+
+  **Skill-judge:** non-functional change (TS migration of adapter source + additive task.move documentation in SKILL.md verb lists). Expect Δ ≈ 0; ratchet baseline with updated `capturedAt` per v1.5.0 release per NOISE_BAND policy.
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @llodev/pm-tasks-core@1.5.0
+
+## 1.3.1
+
+### Patch Changes
+
+- chore: reorganize repo structure
+
+  Pure chore release. Zero runtime change. Splits across:
+
+  - Reorganized root `scripts/` into `checks/`, `snapshots/`, `shell/` subfolders.
+  - Dropped `SKILL.{pt-BR,es-ES}.md` translations (agents read canonical EN-only per agentskills.io spec).
+  - Moved localized READMEs to `docs/i18n/` in root + each package (anticipates 5+ locales without cluttering package roots).
+  - Updated validators (`validate-localized-paths.mjs`) and tarball snapshot for new paths.
+
+  Skill-judge: bypassed with `SKIP_SKILL_JUDGE_GATE=1` — only SKILL.md change was decorative readme-selector block removal; expected delta = 0 (cosmetic-only). Per NOISE_BAND policy [-2, +2] bypass allowed.
+
+  Meta package `@llodev/pm-tasks` not bumped — no tarball content changes, only peerDeps inheritance.
+
+- Updated dependencies []:
+  - @llodev/pm-tasks-core@1.3.2
+
+## 1.3.0
+
+### Minor Changes
+
+- Introduce adapter `manifest.json` + custom-verbs extension API. Each adapter now declares which canonical verbs it implements plus any tool-specific verbs under a `<tool>.*` namespace. `contract-check.mjs` validates the manifest against `adapter-manifest.schema.json`, enforces the `<tool>.<verb>` namespace prefix, and cross-checks each declared verb against the adapter's `SKILL.md`. The same gate now permits additive-only changes to `contract.md` as non-major (deletions still require major). No runtime behaviour changes for existing consumers.
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @llodev/pm-tasks-core@1.3.0
+
+## 1.2.1
+
+### Patch Changes
+
+- [`9f14fe0`](https://github.com/llodev/skills/commit/9f14fe099d8e44fdc01aeb96cdde24aa4fa14527) - CI: release workflow now runs `validate` + `contract:check` + `pre-release` (skill-judge gate) before publish, and a new `scripts/tarball-snapshot.test.mjs` (wired into `pnpm validate`) detects regressions in each package's `files` field. npm publishes use `NPM_CONFIG_PROVENANCE=true` for supply-chain attestation (requires `id-token: write` permission in the workflow). No runtime changes.
+
+- Updated dependencies [[`9f14fe0`](https://github.com/llodev/skills/commit/9f14fe099d8e44fdc01aeb96cdde24aa4fa14527)]:
+  - @llodev/pm-tasks-core@1.2.1
+
+## 1.2.0
+
+### Minor Changes
+
+- [`d8da409`](https://github.com/llodev/skills/commit/d8da409a0a08a481264f8bf64e7bf6a501a16793) - Add opt-in runtime attribution: agents can now stamp `commentPrefix`,
+  `autonomousCommentPrefix` and `descriptionFooter` on every `task.create` and
+  `task.comment.add`, with strings sourced from `pm-tasks-core/i18n` — fully
+  locale-aware. Disabled by default; enable via `attribution.enabled: true` in
+  config.json. Closes the v1.0 "Phase C" design item that was deferred from v1.1.
+
+  Skill-judge gate: measured drift is within the documented noise band
+  ([-2, +2]). Asana: 83 → 84 (Δ +1). Trello: 80 → 81 (Δ +1). No baseline
+  ratchet required; gate bypassed via `SKIP_SKILL_JUDGE_GATE=1`.
+
+### Patch Changes
+
+- Updated dependencies [[`d8da409`](https://github.com/llodev/skills/commit/d8da409a0a08a481264f8bf64e7bf6a501a16793)]:
+  - @llodev/pm-tasks-core@1.2.0
+
+## 1.1.2
+
+### Patch Changes
+
+- Document recurring gotchas observed during v1.0.x dogfood: Asana subtasks not inheriting custom fields, MCP `get_task` missing activity stories (UI is the source of truth), Trello query-string concat bug class, `create_card` ignoring `idMembers`, and `add_member_to_card` false-error returns.
+
+## 1.1.1
+
+### Patch Changes
+
+- Ship pt-BR and es-ES translations of SKILL.md and README.md alongside the existing English originals. Adapters keep en-US as the canonical version; localized files follow the `<basename>.<lang-code>.md` convention. The package tarballs now include the localized files via the `files` field.
+
+- Updated dependencies []:
+  - @llodev/pm-tasks-core@1.1.1
+
+## 1.1.0
+
+### Minor Changes
+
+- Localize init prompts in en-US, pt-BR, es-ES. The first prompt of `npx @llodev/pm-tasks-{asana,trello} init` is now a language picker, and every subsequent prompt is rendered in the chosen locale. The selected locale is recorded as `locale` at the root of the config JSON. New helpers in `@llodev/pm-tasks-core/init-lib`: `promptLocale`, `loadStrings`, `interpolate`, `listLocales`, `registerI18nRoot`. JSON Schemas updated to accept `locale` as an enum. No breaking changes — existing configs without `locale` continue to validate and adapters keep emitting en-US prompts if the strings table is omitted.
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @llodev/pm-tasks-core@1.1.0
+
+## 1.0.2
+
+### Patch Changes
+
+- Allow `defaults.escalateToAlias` (and `defaults.assigneeAlias` on Trello) in the config schemas. The v1.0.1 init scripts emit these keys, but the JSON Schemas still had `additionalProperties: false` rejecting them — making `npx @llodev/pm-tasks-{asana,trello} init` fail at the validate step with "must NOT have additional properties". Trello init also now emits `assigneeAlias: "me"` for parity with Asana.
+
+## 1.0.1
+
+### Patch Changes
+
+- Fix `npx @llodev/pm-tasks-asana init` silently doing nothing. Two bugs collapsed the init flow: (a) the `bin` entry was named `pm-tasks-asana-init` (not matching the package name), so npx never resolved the binary; (b) the script's `import.meta.url === file://${process.argv[1]}` guard failed under npx's symlinked bin shim, so even when invoked the `run()` entry-point was skipped. The bin is now `pm-tasks-asana` and the entry-point runs unconditionally.
+- Cross-platform global config path. The init prompt now honors `LLODEV_PM_TASKS_CONFIG_HOME` first, then `XDG_CONFIG_HOME` (macOS/Linux), then `%APPDATA%` (Windows), then `~/.config` as the last fallback. The prompt prints the absolute path before asking, so the destination is always visible.
+- Slug aliases are now Unicode-aware (via `@llodev/pm-tasks-core@1.0.1`): `"Em execução"` → `"em-execucao"`, `"Média"` → `"media"` (was `"em-execu-o"` / `"m-dia"`).
+- Drop the language-specific regex for inferring the "closed" section. The init now explicitly asks: "Which section is the default for newly-created tasks?" and "Which section means 'closed / done'?" with sensible defaults (first / last picked) and a skip option.
+- Add an explicit escalation prompt. After the member list is collected, the init asks: "Pick the escalation contact (will receive escalation comments + add_member on critical cards)" and stores it as `defaults.escalateToAlias`. The chosen member is re-aliased to `"owner"` if no other member already holds that alias.
+- Fallback for empty membership lists: if the PAT's scope didn't return any project members beyond `me`, the init now offers a manual entry (gid + name + alias) so single-collaborator projects can still wire an escalation contact.
+- `multiSelect`: empty input now means "select all" instead of "select none".
+- README clarifies the per-OS defaults and the env override.
+
+## 1.0.0
+
+### Major Changes
+
+- [`a571ab1`](https://github.com/llodev/skills/commit/a571ab1537ea7d3fe61c7b89c5be0f08d01f3838) - First stable release of the pm-tasks-\* family.
+
+  - `@llodev/pm-tasks-core` — Phases 1–3 extraction pipeline (input → sections → generic card), 6 CRUD verbs (`task.create`, `checklist.check`, `task.close`, `task.due-date.set`, `task.assignee.add`, `task.comment.add`), autonomous-mode contract (allowlist + scope + rate-limit + audit log), shared init UX library.
+  - `@llodev/pm-tasks-trello` — Trello adapter on the canonical generic card. Paste-friendly output, MCP-driven publish, autonomous mode against a board allowlist.
+  - `@llodev/pm-tasks-asana` — Asana adapter with workspace/project/section + custom-field + subtask-inheritance support. Paste, MCP-driven publish, autonomous mode.
+
+  Architecture, contract, and CRUD vocabulary documented in `docs/specs/2026-06-11-pm-tasks-design.md` and `docs/plans/2026-06-11-pm-tasks-v1.md`.
+
+### Patch Changes
+
+- Updated dependencies [[`a571ab1`](https://github.com/llodev/skills/commit/a571ab1537ea7d3fe61c7b89c5be0f08d01f3838)]:
+  - @llodev/pm-tasks-core@1.0.0
+
+## 0.1.0 (unreleased)
+
+- Initial extraction from `plan-to-task-cards` Phase 5b (Asana).
+- 6 CRUD verbs (create, checklist.check, close, due-date.set, assignee.add, comment.add).
+- Parent task + subtasks model with custom-field inheritance.
+- Autonomous mode behind `[autonomous]` sentinel + allowlist.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LLDev Information Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+<!-- readme-selector:start -->
+<p align="center">
+  <a href="https://github.com/llodev/skills/blob/main/pm-tasks/pm-tasks-asana/README.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/usa.svg" width="30" alt="English"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/pm-tasks/pm-tasks-asana/docs/i18n/README.pt-BR.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/brazil.svg" width="30" alt="Português"></a>&nbsp;&nbsp;
+  <a href="https://github.com/llodev/skills/blob/main/pm-tasks/pm-tasks-asana/docs/i18n/README.es-ES.md"><img src="https://raw.githubusercontent.com/lloliveiradev/public-assets/main/images/spain.svg" width="30" alt="Español"></a>
+</p>
+<!-- readme-selector:end -->
+
+# @llodev/pm-tasks-asana
+
+> Asana adapter for the `@llodev/pm-tasks-*` family — turn implementation plans into Asana parent tasks + subtasks and operate them via paste, MCP publish, or autonomous write-through.
+
+[![npm](https://img.shields.io/npm/v/@llodev/pm-tasks-asana?label=npm&color=cb3837&logo=npm)](https://www.npmjs.com/package/@llodev/pm-tasks-asana)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-43853d?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Agent Skills spec](https://img.shields.io/badge/Agent_Skills-spec-7c5cff)](https://agentskills.io)
+
+What you get:
+
+- **Paste-ready output** — agent renders a generic card; you paste into Asana manually.
+- **MCP publish** via the `claude.ai Asana` MCP server (OAuth, no PATs in JSON). Parent task + flat subtasks + custom fields + section placement in one batch.
+- **CRUD operations** on existing tasks: `checklist.check`, `task.close`, `task.comment.add`, `task.due-date.set`, `task.assignee.add`.
+- **Autonomous mode** — `[autonomous]` / `--auto` sentinel for write-through under allowlist + scope + rate limits. Multi-task loops mirror state to Asana in real time.
+
+## Install
+
+```bash
+# npm (with skillpm or Claude Code marketplace)
+npm i @llodev/pm-tasks-core @llodev/pm-tasks-asana
+
+# Vercel CLI (install core manually too)
+npx skills add llodev/skills/pm-tasks/pm-tasks-core
+npx skills add llodev/skills/pm-tasks/pm-tasks-asana
+```
+
+## Setup the MCP
+
+Asana uses OAuth via the `claude.ai Asana` MCP. If you've already connected your Asana account in Cursor or Claude Code settings, you're done.
+
+For any MCP-capable agent (Claude Code, Cursor, Codex, Windsurf, Cline, Roo Code):
+
+1. Open the agent's MCP settings.
+2. Enable / register `claude.ai Asana` (or your agent's equivalent Asana MCP).
+3. Approve the OAuth flow in your browser.
+
+In Claude Code, verify with `claude mcp list` — `claude.ai Asana` should appear as authenticated.
+
+## Setup the config
+
+The `init` script runs **outside** the MCP, so it needs a Personal Access Token to enumerate your workspaces / projects / sections / custom fields. Generate one at https://app.asana.com/0/my-apps, then:
+
+```bash
+export LLODEV_PM_TASKS_ASANA_PAT=...
+npx @llodev/pm-tasks-asana init
+```
+
+Walk through the prompts. Pick where the config should live:
+
+- **local** → `./.asana.json` (recommended for project-scoped configs, can be committed).
+- **global** → a platform default, customizable. Defaults:
+  - macOS / Linux (XDG): `$XDG_CONFIG_HOME/llodev/pm-tasks/asana.json`, falling back to `~/.config/llodev/pm-tasks/asana.json`.
+  - Windows: `%APPDATA%\llodev\pm-tasks\asana.json`.
+  - Override on any OS with `LLODEV_PM_TASKS_CONFIG_HOME=/your/path` — the file lands at `$LLODEV_PM_TASKS_CONFIG_HOME/asana.json`.
+
+The `init` prompt prints the absolute path it will write to, so you always see exactly where the file goes.
+
+> [!IMPORTANT]
+> The PAT is **only** used by `init`. The MCP itself uses OAuth — never put tokens in the JSON.
+
+## Use
+
+| Prompt example                                                   | What the agent does                                                   |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `"publish this plan as Asana tasks"`                             | Phase 5 publish — parent + subtasks + custom fields in one batch      |
+| `"check subtask 3 on task X in Asana"`                           | Phase 6 CRUD — `checklist.check` on the subtask                       |
+| `"close task Y"`                                                 | Phase 6 CRUD — `task.close` (moves to close section + sets completed) |
+| `"comment on task X: shipped"`                                   | Phase 6 CRUD — `task.comment.add`                                     |
+| `"[autonomous] create task in asana from plan @docs/plans/X.md"` | Phase 5b autonomous (requires `autonomous.enabled: true`)             |
+
+## Asana-specific notes
+
+> [!NOTE]
+> **Subtasks are one level deep** — the adapter flattens nested checklists into a single subtask layer.
+
+> [!WARNING]
+> **Custom fields do NOT inherit by default** — list field IDs in `subtaskDefaults.inheritParentFields` so the adapter copies them from parent to subtasks at create time.
+
+- **Assignee is a single field** — use `task.assignee.add` to add followers; the primary assignee replaces on conflict.
+- **MCP `get_task` doesn't return activity stories** — the Asana UI activity feed is the source of truth for attribution audits. See [`anti-patterns/asana.md`](./anti-patterns/asana.md).
+
+## Documentation
+
+- [`SKILL.md`](./SKILL.md) — phase routing + CRUD vocabulary.
+- [`schemas/config.json`](./schemas/config.json) — `.asana.json` JSON Schema.
+- [`anti-patterns/asana.md`](./anti-patterns/asana.md) — recurring gotchas.
+- [`../pm-tasks-core/references/autonomous-mode.md`](../pm-tasks-core/references/autonomous-mode.md) — autonomous-mode contract.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: pm-tasks-asana
+description: >-
+  Asana adapter for the @llodev/pm-tasks-* family. Use when the user mentions
+  Asana, asks to "create Asana task", "publish to Asana", "post to Asana",
+  "publish", "add comment in Asana", or uses --publish-asana; OR for CRUD on
+  existing tasks (check subtask, close task, change due-date, assign person,
+  comment); OR when invoked autonomously by another agent with [autonomous] /
+  --auto sentinel. Asana hierarchy: workspace > project > section > parent task
+  > subtasks (one level), with custom fields and multi-assignee support. Modes:
+  paste-ready (no MCP needed), MCP publish (via claude.ai Asana MCP), autonomous
+  (write-through with allowlist). Implements 7 CRUD verbs (task.create,
+  task.move, checklist.check, task.close, task.due-date.set, task.assignee.add,
+  task.comment.add) from pm-tasks/pm-tasks-core/references/contract.md. Requires
+  @llodev/pm-tasks-core installed.
+license: MIT
+metadata:
+  version: 1.6.0
+  tags:
+    - agent-skill
+    - asana
+    - plan-to-tasks
+    - pm-tools
+  family: pm-tasks
+  role: adapter
+  tool: asana
+compatibility:
+  agents:
+    - claude-code
+    - cursor
+    - codex
+    - windsurf
+    - cline
+    - roo-code
+---
+
+# 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
+
+| Mode           | Trigger                                                                                                          | Path                                                                                                                  |
+| -------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Paste-only     | "format as Asana task" without MCP intent                                                                        | Phase 3 (core) → Phase 4 (this skill, format only) → output paste blocks                                              |
+| MCP publish    | "publish to Asana", "create on Asana", "--publish-asana"                                                         | Phase 3 → Phase 4 → Phase 5 (publish via MCP)                                                                         |
+| Autonomous     | `[autonomous]` or `--auto` in prompt OR `LLODEV_PM_TASKS_AUTONOMOUS=1`                                           | Phase 3 → Phase 4 → Phase 5b (write-through, no preview)                                                              |
+| CRUD ops       | "check subtask N on task X", "close task Y", "assign Alice to task Z", "comment on task X"                       | Phase 6 (operations, direct verb dispatch)                                                                            |
+| Plan-execution | Plan file path in prompt (`docs/plans/*.md`), OR `--plan-exec` flag, OR plan reference paired with `.asana.json` | Phase 7 (discover existing cards via `discoverPlanTasks`; calling agent dispatches per-task verbs at task boundaries) |
+
+## 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; the adapter sets them explicitly per `subtaskDefaults.inheritParentFields` in `.asana.json`.
+- **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`](../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[]`).
+- Due date → `due_on` (YYYY-MM-DD).
+- 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}`).
+2. **Subtasks** — `create_tasks` per subtask with `parent: parentGid`, `name`, `assignee` (inherited or per-subtask), `custom_fields` matching `subtaskDefaults.inheritParentFields`.
+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](../pm-tasks-core/references/attribution.md) (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`](../pm-tasks-core/references/autonomous-mode.md). Audit log entries per [`../pm-tasks-core/references/audit-log-format.md`](../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`](../pm-tasks-core/references/autonomous-mode.md) § **Continuous operation across multi-task loops** for the full contract and anti-patterns.
+
+Asana-specific verb mapping:
+
+| Transition              | Canonical verb + MCP call(s)                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Task start              | `task.move(cardId, "wip")` → `mcp__claude_ai_Asana__update_tasks { task: <gid>, memberships: [{ project: <projectGid>, section: <wipSectionGid> }] }`                                                                                                                                                                                                                                                            |
+| Step complete (subtask) | `checklist.check` → `mcp__claude_ai_Asana__update_tasks { task: <subtaskGid>, completed: true }`                                                                                                                                                                                                                                                                                                                 |
+| Task complete (full)    | `task.move(cardId, "done")` → `mcp__claude_ai_Asana__update_tasks { task: <parentGid>, memberships: [{ project: <projectGid>, section: <doneSectionGid> }] }` then `task.comment.add` → `mcp__claude_ai_Asana__add_comment { task_id: <parentGid>, text: "🤖 [agent] Task complete. Commit: <SHA>. <branch>." }` then `task.close` → `mcp__claude_ai_Asana__update_tasks { task: <parentGid>, completed: true }` |
+| Task failed             | `task.comment.add` → `mcp__claude_ai_Asana__add_comment` with failure mode + `mcp__claude_ai_Asana__update_tasks { task: <gid>, add_followers: ["<escalateToAliasGid>"] }` for human escalation. Do NOT call `task.move(_, "done")` or `task.close`.                                                                                                                                                             |
+
+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`.
+
+**Asana caveat (per [`anti-patterns/asana.md`](./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:
+
+| Core verb           | Asana MCP tool                 | Notes                                                                                                                                                                                                                                   |
+| ------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `task.create`       | `create_tasks`                 | parent + subtasks per Phase 5                                                                                                                                                                                                           |
+| `task.move`         | `update_tasks`                 | `memberships: [{ project, section: <resolvedGid> }]`. Resolve `"wip"` / `"done"` / `"open"` via `defaults.wipSectionAlias` / `defaults.doneSectionAlias` / `defaults.openSectionAlias` in `.asana.json`. Raw section GIDs pass through. |
+| `checklist.check`   | `update_tasks`                 | for subtasks: `completed: true`; emulates checklist via subtask model                                                                                                                                                                   |
+| `task.close`        | `update_tasks`                 | `completed: true` on parent                                                                                                                                                                                                             |
+| `task.due-date.set` | `update_tasks`                 | `due_on: "YYYY-MM-DD"`                                                                                                                                                                                                                  |
+| `task.assignee.add` | `update_tasks` + `addFollower` | primary assignee replaces; additional are followers                                                                                                                                                                                     |
+| `task.comment.add`  | `add_comment` (story)          | adds a comment story to the task; apply attribution prefix if enabled                                                                                                                                                                   |
+
+`<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 [`pm-tasks/pm-tasks-core/references/plan-execution.md`](../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`](../pm-tasks-core/references/contract.md) §Result envelope):
+
+```json
+{
+  "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:
+
+| Verb                | `details` fields                                                         |
+| ------------------- | ------------------------------------------------------------------------ |
+| `task.create`       | `{ parentGid, subtaskGids[], projectGid, sectionGid?, customFields[]? }` |
+| `task.move`         | `{ taskGid, sectionGid, targetList }`                                    |
+| `checklist.check`   | `{ subtaskGid, completed: true }`                                        |
+| `task.close`        | `{ parentGid, completed: true }`                                         |
+| `task.due-date.set` | `{ taskGid, due_on }`                                                    |
+| `task.assignee.add` | `{ taskGid, assignee, followers[]? }` (primary vs follower split)        |
+| `task.comment.add`  | `{ taskGid, storyGid }`                                                  |
+
+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`](../pm-tasks-core/references/contract.md) §Partial-create recovery).
+
+## Anti-patterns
+
+See [`anti-patterns/asana.md`](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`](schemas/config.json). Secrets NEVER in JSON — Asana MCP holds OAuth; `init` uses `LLODEV_PM_TASKS_ASANA_PAT` env var only.
+
+## Init
+
+```
+npx @llodev/pm-tasks-asana init
+```
+
+See [`../pm-tasks-core/references/init-ux.md`](../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:
+
+```sh
+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 [`pm-tasks/pm-tasks-core/references/doctor.md`](../pm-tasks-core/references/doctor.md).