@llodev/pm-tasks-asana 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @llodev/pm-tasks-asana
+
+## 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,57 @@
+# @llodev/pm-tasks-asana
+
+Asana adapter for the `@llodev/pm-tasks-*` family. Convert implementation plans into Asana parent tasks + subtasks (paste-ready or published via MCP) and operate them (`checklist.check`, `task.close`, `task.comment.add`, etc.).
+
+## 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-core
+npx skills add llodev/skills/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 — no extra step.
+
+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. Other agents have their own listing commands; see your agent's MCP docs.
+
+## 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. Output: `.asana.json` (repo) or `~/.config/llodev/pm-tasks/asana.json` (global).
+
+The PAT is **only** used by `init`. The MCP itself uses OAuth — never put tokens in the JSON.
+
+## Use
+
+- `"publish this plan as Asana tasks"` → publish flow (parent + subtasks)
+- `"check subtask 3 on task X in Asana"` → CRUD op
+- `"close task Y"` → close
+- `"comment on task X: ..."` → comment
+- `"[autonomous] create task in asana from plan @docs/plans/X.md"` → autonomous (requires `autonomous.enabled: true` in config)
+
+## Asana-specific notes
+
+- **Subtasks are one level deep** — the adapter flattens nested checklists into a single subtask layer.
+- **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.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SKILL.md

@@ -0,0 +1,157 @@
+---
+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 6 CRUD verbs
+  (task.create, 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.0.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)                               |
+
+## 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.
+
+## 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).
+
+## 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                                         |
+| `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                                      |
+
+`<task-ref>` resolution: accept Asana permalinks (`https://app.asana.com/0/<project>/<task>`), bare GIDs, or aliases from `.asana.json` `taskAliases[]`.
+
+## 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[]? }` |
+| `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`).

package/anti-patterns/asana.md

@@ -0,0 +1,41 @@
+# Asana ingestion anti-patterns
+
+Apply when Phase 4 / Phase 5 / Phase 5b target Asana. Authoritative formatting + publish detail lives in [`../SKILL.md`](../SKILL.md).
+
+---
+
+## Paste health and fallbacks
+
+| Healthy paste                                                                                                       | If it degrades → fallback                                                                            |
+| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Prefer `**Section**` in task descriptions when `##` headings are unreliable; **only one** nesting level for subtasks. | Swap heading hierarchy for bold labels; split deep trees into sibling tasks. See [`../SKILL.md`](../SKILL.md) §Asana model. |
+
+**Switching tools mid-thread:** re-load the new tool's adapter; do not carry Asana rules into Trello / Jira / Linear (see **Cross-tool** below).
+
+---
+
+## Asana
+
+**NEVER** rely on `## Heading` hierarchy alone in descriptions for teams that proved **headings don't render**. **Why:** Asana rich-text inconsistency across clients; bold section labels (`**Deliverables**`) are safer fallback per [`../SKILL.md`](../SKILL.md) §Asana model.
+
+**NEVER** model **multiple nesting levels** of subtasks beyond what Asana supports (one level of subtasks natively). **Why:** falsely implies hierarchy; flatten or split tasks.
+
+**NEVER** put **Out of scope** or **Next step** into published Asana descriptions. **Why:** deferred work stays in the plan file, not in the task body.
+
+**NEVER** call `create_tasks` / `create_task_preview_v4` before the user confirms the Phase 5 preview. **Why:** creates real workspace objects without approval.
+
+**NEVER** use `create_task_preview_v4` as the default path for a full phase card with many checklist lines. **Why:** inline subtasks cap at 5; use parent + batched `create_tasks` with `parent` instead.
+
+**NEVER** pass custom field **display names** (e.g. `"Discovery"`, `"Medium"`) in `custom_fields` to MCP — only **field GID → option GID** pairs resolved from `.asana.json`. **Why:** the API returns 400; display names drift between Asana UI edits and the config file.
+
+**NEVER** guess `project.id`, `section.id`, or custom field GIDs when `.asana.json` exists. **Why:** stale or invented GIDs silently create tasks in the wrong project or column; always read the file or refresh via `get_project`.
+
+**NEVER** send `custom_fields` as an **object** on `create_tasks` — it must be a **JSON string**; object form is only valid for `update_tasks`. **Why:** the tool schemas differ; wrong format causes silent failure or a 400 error.
+
+**NEVER** set `section_id` without also setting `project_id` / `default_project`. **Why:** Asana API requires project context for section placement.
+
+---
+
+## Cross-tool
+
+**NEVER** apply Asana's quirks to another adapter after switching targets mid-chat. **Why:** the user said "actually use Trello" — re-load that adapter and apply only its rules.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@llodev/pm-tasks-asana",
+  "version": "1.0.0",
+  "description": "Asana adapter for the @llodev/pm-tasks-* family. Use when the user mentions Asana (create Asana task, publish to Asana, post to Asana, add comment in Asana, --publish-asana, close task, check subtask) or wants to publish a plan as Asana tasks with subtasks. Modes: paste-ready (no MCP needed), MCP publish (via claude.ai Asana MCP), autonomous (sentinel [autonomous] / --auto). Implements 6 CRUD verbs from @llodev/pm-tasks-core/references/contract.md mapped to Asana (parent task + subtasks, custom fields, sections, multi-assignee). REQUIRES: @llodev/pm-tasks-core installed (skillpm / Claude Code marketplace cascade auto; Vercel CLI users install manually).",
+  "license": "MIT",
+  "homepage": "https://github.com/llodev/skills/tree/main/pm-tasks/pm-tasks-asana",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/llodev/skills.git",
+    "directory": "pm-tasks/pm-tasks-asana"
+  },
+  "files": [
+    "SKILL.md",
+    "schemas",
+    "references",
+    "anti-patterns",
+    "scripts",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "agent-skill",
+    "asana",
+    "plan-to-tasks",
+    "pm-tools",
+    "asana-mcp"
+  ],
+  "type": "module",
+  "bin": {
+    "pm-tasks-asana-init": "./scripts/init.mjs"
+  },
+  "dependencies": {
+    "@llodev/pm-tasks-core": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/schemas/config.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://llodev.github.io/skills/schemas/pm-tasks-asana.json",
+  "title": "pm-tasks-asana config",
+  "type": "object",
+  "required": ["version", "projects", "sections"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": "1" },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 4 },
+        "name": { "type": "string" }
+      }
+    },
+    "projects": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "alias"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 4 },
+          "name": { "type": "string" },
+          "alias": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "url": { "type": "string", "format": "uri" }
+        }
+      }
+    },
+    "sections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["projectAlias", "id", "alias"],
+        "additionalProperties": false,
+        "properties": {
+          "projectAlias": { "type": "string" },
+          "id": { "type": "string", "minLength": 4 },
+          "name": { "type": "string" },
+          "alias": { "type": "string", "pattern": "^[a-z0-9-]+$" }
+        }
+      }
+    },
+    "customFields": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["projectAlias", "id", "name", "type", "alias"],
+        "additionalProperties": false,
+        "properties": {
+          "projectAlias": { "type": "string" },
+          "id": { "type": "string", "minLength": 4 },
+          "name": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": ["text", "number", "enum", "multi_enum", "date", "people"]
+          },
+          "alias": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id", "name"],
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string", "minLength": 4 },
+                "name": { "type": "string" },
+                "alias": { "type": "string", "pattern": "^[a-z0-9-]+$" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "subtaskDefaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "inheritParentFields": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 4 },
+          "description": "Custom field IDs whose values flow from parent to subtask at create time."
+        },
+        "inheritAssignee": { "type": "boolean" }
+      }
+    },
+    "members": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "alias"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 4 },
+          "name": { "type": "string" },
+          "email": { "type": "string", "format": "email" },
+          "alias": { "type": "string", "pattern": "^[a-z0-9-]+$" }
+        }
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "projectAlias": { "type": "string" },
+        "sectionAlias": { "type": "string" },
+        "closeSectionAlias": { "type": "string" },
+        "assigneeAlias": { "type": "string" }
+      }
+    },
+    "taskAliases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["alias", "id"],
+        "additionalProperties": false,
+        "properties": {
+          "alias": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+          "id": { "type": "string" },
+          "url": { "type": "string", "format": "uri" }
+        }
+      }
+    },
+    "autonomous": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "allow": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "task.create",
+              "checklist.check",
+              "task.close",
+              "task.due-date.set",
+              "task.assignee.add",
+              "task.comment.add"
+            ]
+          }
+        },
+        "scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "projects": { "type": "array", "items": { "type": "string" } },
+            "sections": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "rateLimit": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "writesPerMinute": { "type": "integer", "minimum": 1, "maximum": 600 },
+            "commentsPerMinute": { "type": "integer", "minimum": 1, "maximum": 600 }
+          }
+        },
+        "auditLog": { "type": "string" }
+      }
+    }
+  }
+}

package/scripts/init.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+// pm-tasks-asana init — interactive config bootstrapper
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import {
+  promptScope,
+  promptYesNo,
+  multiSelect,
+  writeConfig,
+  validateConfig,
+  probeMCP,
+  printInstructions,
+} from "@llodev/pm-tasks-core/init-lib";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+async function loadSchema() {
+  const raw = await readFile(path.join(ROOT, "schemas", "config.json"), "utf8");
+  return JSON.parse(raw);
+}
+
+async function asanaProbe() {
+  // The MCP runs in a different process. To probe within this script, call the
+  // Asana REST API directly with a Personal Access Token.
+  // Used only to enumerate workspaces / projects / sections / custom fields / members.
+  const TOKEN = process.env.LLODEV_PM_TASKS_ASANA_PAT;
+  if (!TOKEN) throw new Error("auth: LLODEV_PM_TASKS_ASANA_PAT missing");
+  const j = async (p) => {
+    const r = await fetch(`https://app.asana.com/api/1.0${p}`, {
+      headers: { Authorization: `Bearer ${TOKEN}` },
+    });
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    const body = await r.json();
+    return body.data;
+  };
+  return {
+    getMe: () => j("/users/me?opt_fields=gid,name,email"),
+    getWorkspaces: () => j("/workspaces?opt_fields=name"),
+    getProjects: (workspaceGid) =>
+      j(`/projects?workspace=${workspaceGid}&opt_fields=name&limit=100`),
+    getSections: (projectGid) =>
+      j(`/projects/${projectGid}/sections?opt_fields=name&limit=100`),
+    getCustomFields: (projectGid) =>
+      j(
+        `/projects/${projectGid}/custom_field_settings?opt_fields=custom_field.name,custom_field.gid,custom_field.resource_subtype,custom_field.enum_options.name,custom_field.enum_options.gid&limit=100`,
+      ),
+    getMembers: (projectGid) =>
+      j(`/projects/${projectGid}/members?opt_fields=user.name,user.gid&limit=100`),
+  };
+}
+
+function aliasOf(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function mapResourceType(subtype) {
+  switch (subtype) {
+    case "enum":
+      return "enum";
+    case "multi_enum":
+      return "multi_enum";
+    case "number":
+      return "number";
+    case "date":
+      return "date";
+    case "people":
+      return "people";
+    default:
+      return "text";
+  }
+}
+
+async function run() {
+  console.log("\n@llodev/pm-tasks-asana init\n");
+
+  const { path: outPath } = await promptScope("asana");
+
+  const probe = await probeMCP({
+    tool: "asana",
+    probeCommand: async () => {
+      const api = await asanaProbe();
+      await api.getMe();
+      return api;
+    },
+  });
+
+  if (probe.unauthenticated) {
+    printInstructions([
+      "Asana MCP detected, but credentials missing for init probe.",
+      "Generate a Personal Access Token at https://app.asana.com/0/my-apps,",
+      "then set it in your shell and re-run:",
+      "  export LLODEV_PM_TASKS_ASANA_PAT=...",
+      "(The token is used only by this init script; the MCP itself uses OAuth.)",
+    ]);
+    return;
+  }
+
+  if (!probe.mcpAvailable) {
+    printInstructions([
+      "Asana MCP not available. Connect your Asana account first:",
+      "  In Cursor / Claude Code settings → MCP → enable 'claude.ai Asana'.",
+      "Then re-run this init.",
+    ]);
+    return;
+  }
+
+  const api = probe.result;
+  const me = await api.getMe();
+  const workspaces = await api.getWorkspaces();
+
+  const pickedWorkspaces = await multiSelect(
+    "Available workspaces (select 1):",
+    workspaces.map((w) => ({ label: `${w.name} (${w.gid})`, value: w })),
+  );
+  if (!pickedWorkspaces.length) {
+    console.error("no workspace selected, aborting");
+    process.exit(1);
+  }
+  const workspace = pickedWorkspaces[0];
+
+  const projects = await api.getProjects(workspace.gid);
+  const pickedProjects = await multiSelect(
+    `Projects in "${workspace.name}" (select 1+):`,
+    projects.map((p) => ({ label: `${p.name} (${p.gid})`, value: p })),
+  );
+  if (!pickedProjects.length) {
+    console.error("no project selected, aborting");
+    process.exit(1);
+  }
+
+  const out = {
+    $schema: "https://llodev.github.io/skills/schemas/pm-tasks-asana.json",
+    version: "1",
+    workspace: { id: workspace.gid, name: workspace.name },
+    projects: [],
+    sections: [],
+    customFields: [],
+    members: [{ id: me.gid, name: me.name, email: me.email, alias: "me" }],
+    defaults: {},
+  };
+
+  const inheritFieldIds = new Set();
+
+  for (const p of pickedProjects) {
+    const alias = aliasOf(p.name);
+    out.projects.push({ id: p.gid, name: p.name, alias });
+
+    const sections = await api.getSections(p.gid);
+    const pickedSections = await multiSelect(
+      `Sections in "${p.name}":`,
+      sections.map((s) => ({ label: s.name, value: s })),
+    );
+    for (const s of pickedSections) {
+      out.sections.push({
+        projectAlias: alias,
+        id: s.gid,
+        name: s.name,
+        alias: aliasOf(s.name),
+      });
+    }
+
+    const cfSettings = await api.getCustomFields(p.gid);
+    const fields = cfSettings.map((cs) => cs.custom_field).filter(Boolean);
+    if (fields.length) {
+      const pickedFields = await multiSelect(
+        `Custom fields in "${p.name}" (select fields to expose to the adapter):`,
+        fields.map((f) => ({ label: `${f.name} [${f.resource_subtype}]`, value: f })),
+      );
+      for (const f of pickedFields) {
+        const entry = {
+          projectAlias: alias,
+          id: f.gid,
+          name: f.name,
+          type: mapResourceType(f.resource_subtype),
+          alias: aliasOf(f.name),
+        };
+        if (Array.isArray(f.enum_options) && f.enum_options.length) {
+          entry.options = f.enum_options.map((opt) => ({
+            id: opt.gid,
+            name: opt.name,
+            alias: aliasOf(opt.name),
+          }));
+        }
+        out.customFields.push(entry);
+      }
+
+      if (pickedFields.length) {
+        const inheritPicked = await multiSelect(
+          `Of those, which should subtasks inherit from the parent?`,
+          pickedFields.map((f) => ({ label: f.name, value: f })),
+        );
+        for (const f of inheritPicked) inheritFieldIds.add(f.gid);
+      }
+    }
+
+    try {
+      const memberships = await api.getMembers(p.gid);
+      const users = memberships.map((m) => m.user).filter(Boolean);
+      for (const u of users) {
+        if (u.gid === me.gid) continue;
+        if (out.members.find((m) => m.id === u.gid)) continue;
+        out.members.push({ id: u.gid, name: u.name, alias: aliasOf(u.name) });
+      }
+    } catch (e) {
+      // Project membership listing may require additional scopes; skip silently.
+    }
+  }
+
+  if (out.projects.length === 1) {
+    out.defaults.projectAlias = out.projects[0].alias;
+    const backlog = out.sections.find((s) => /backlog|todo|to.do|inbox/i.test(s.name));
+    const done = out.sections.find((s) => /done|completed|published|conclu/i.test(s.name));
+    if (backlog) out.defaults.sectionAlias = backlog.alias;
+    if (done) out.defaults.closeSectionAlias = done.alias;
+    out.defaults.assigneeAlias = "me";
+  }
+
+  if (inheritFieldIds.size) {
+    out.subtaskDefaults = {
+      inheritParentFields: [...inheritFieldIds],
+      inheritAssignee: true,
+    };
+  }
+
+  const wantAuto = await promptYesNo(
+    "Enable autonomous mode? (adds an autonomous block with conservative defaults)",
+  );
+  if (wantAuto) {
+    out.autonomous = {
+      enabled: false,
+      allow: ["task.create", "checklist.check", "task.close", "task.comment.add"],
+      scope: {
+        projects: out.projects.map((p) => p.id),
+        sections: out.sections.map((s) => s.id),
+      },
+      rateLimit: { writesPerMinute: 30, commentsPerMinute: 10 },
+      auditLog: "~/.local/share/llodev/pm-tasks/asana/audit.log",
+    };
+    printInstructions([
+      "autonomous block added with enabled:false.",
+      "Review scope.projects and scope.sections in the JSON before enabling.",
+    ]);
+  }
+
+  const schema = await loadSchema();
+  const valid = await validateConfig(out, schema);
+  if (!valid.ok) {
+    console.error("invalid config:", JSON.stringify(valid.errors, null, 2));
+    process.exit(1);
+  }
+
+  await writeConfig(outPath, out);
+  printInstructions([
+    `Config written to ${outPath}.`,
+    "Try it in Claude Code: 'create an Asana task from this plan'.",
+    "Reminder: the Asana MCP holds OAuth — never put tokens in this JSON.",
+    "The LLODEV_PM_TASKS_ASANA_PAT env var is only used by this init script.",
+  ]);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}