@llodev/pm-tasks-core 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @llodev/pm-tasks-core
+
+## 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`.
+
+## 0.1.0 (unreleased)
+
+- Initial extraction from `plan-to-task-cards` v0.

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,31 @@
+# @llodev/pm-tasks-core
+
+Core skill shared by every `@llodev/pm-tasks-<tool>` adapter (Trello, Asana, Jira, Linear, Notion, ClickUp, Monday, Bitrix24, Todoist).
+
+This package alone is not useful. Install at least one adapter:
+
+```
+npm i @llodev/pm-tasks-core @llodev/pm-tasks-trello
+# or
+npx skills add llodev/skills/pm-tasks-core llodev/skills/pm-tasks-trello
+```
+
+## What lives here
+
+- The extraction phases (plan → generic card).
+- The canonical CRUD vocabulary every adapter implements.
+- The autonomous-mode contract (sentinels, allowlist, guardrails).
+- The init UX shared by all adapter `init` commands.
+- The audit log format.
+
+## Optional cron — rotate audit log
+
+```cron
+# Daily at 04:00, keep 90 days of audit log for Trello + Asana
+0 4 * * * /path/to/pm-tasks-core/scripts/rotate-audit.sh trello
+0 4 * * * /path/to/pm-tasks-core/scripts/rotate-audit.sh asana
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: pm-tasks-core
+description: >-
+  Core extraction + vocabulary for the @llodev/pm-tasks-* family. Use when
+  working with any pm-tasks-<tool> adapter (Trello, Asana, etc.) — provides
+  Phases 1–3 (identify input, extract structure, build the generic card) plus
+  the canonical CRUD vocabulary (task.create, checklist.check, task.close,
+  task.due-date.set, task.assignee.add, task.comment.add) consumed by adapters.
+  Also defines autonomous-mode contract (sentinels, allowlist, scope, audit log)
+  and the shared init UX. Triggered indirectly by any prompt that an adapter
+  handles (e.g. "create Trello card", "publish plan to Asana", "[autonomous]
+  create task"). Do NOT activate alone — it has no tool-specific formatting.
+license: MIT
+metadata:
+  version: 1.0.0
+  tags:
+    - agent-skill
+    - plan-to-tasks
+    - pm-tools
+  family: pm-tasks
+  role: core
+compatibility:
+  agents:
+    - claude-code
+    - cursor
+    - codex
+    - windsurf
+    - cline
+    - roo-code
+---
+
+# pm-tasks-core
+
+Shared core for all `pm-tasks-<tool>` adapters. Defines the extraction phases, the generic-card structure, the CRUD vocabulary, the autonomous-mode contract, the configuration lookup rules, and the audit-log format. Adapters reference this skill by path — no formal dependency mechanism in the spec.
+
+## Routing
+
+Adapters invoke this skill BEFORE applying their tool-specific formatting. The exact pointer is documented in [`references/contract.md`](references/contract.md).
+
+## Phases
+
+| Phase | Purpose                                                      | Reference                                                  |
+| ----- | ------------------------------------------------------------ | ---------------------------------------------------------- |
+| 1     | Identify the input (plan file vs inline paste vs implicit)   | [`references/contract.md`](references/contract.md) § 1     |
+| 2     | Extract sections by intent (goal, prereqs, tasks, done-when) | [`references/contract.md`](references/contract.md) § 2     |
+| 2.5   | Anti-patterns gate                                           | [`anti-patterns/core.md`](anti-patterns/core.md)           |
+| 3     | Build the generic card                                       | [`references/generic-card.md`](references/generic-card.md) |
+
+Adapters then execute Phases 4+ per their own SKILL.md.
+
+## CRUD vocabulary (verbs adapters implement)
+
+See [`references/crud-vocabulary.md`](references/crud-vocabulary.md). Six verbs, all idempotent (with `clientToken` rules for non-natural cases).
+
+## Autonomous mode
+
+See [`references/autonomous-mode.md`](references/autonomous-mode.md). Activated only by sentinel `[autonomous]` / `--auto` / env `LLODEV_PM_TASKS_AUTONOMOUS=1`. Requires explicit allowlist + scope + rate limit in the tool's config. Never inferred.
+
+## Configuration
+
+Lookup order: `<git-root>/.<tool>.json` → `~/.config/llodev/pm-tasks/<tool>.json` → abort. Secrets NEVER in JSON (env vars / OS keychain only).
+
+## Audit log
+
+Append-only JSONL at `~/.local/share/llodev/pm-tasks/<tool>/audit.log`. Schema in [`references/audit-log-format.md`](references/audit-log-format.md). Doubles as the lookup index for `<task-ref>` resolution.
+
+## Init helper
+
+Adapters expose `npx @llodev/pm-tasks-<tool> init`. Shared UX in [`references/init-ux.md`](references/init-ux.md). Implementation library at `./scripts/init-lib.mjs`.
+
+## Standalone fallback
+
+This skill is not useful without an adapter. If activated alone, tell the user to install at least one `pm-tasks-<tool>` package.

package/anti-patterns/core.md

@@ -0,0 +1,55 @@
+# Card & workflow anti-patterns (core)
+
+Expert guardrails — violating these wastes board space, breaks paste targets, or misleads reviewers.
+
+---
+
+## Structure & granularity
+
+**NEVER** create one checklist item per micro-step from the plan (e.g. "open file", "run linter", "save"). **Why:** the card mirrors **tasks/outcomes**, not every keystroke; noise hides real progress.
+
+**NEVER** duplicate the entire plan verbatim into description or checklist. **Why:** defeats the purpose of a summary; links to plan/spec suffice.
+
+**NEVER** merge multiple phases into a single card without explicit user consent. **Why:** timelines, ownership, and "done" blur; violates one-card-one-phase default.
+
+**NEVER** bury **Pre-flight / prerequisites** inside a random block. **Why:** skipped baselines cause false "blocked" churn; baseline always tops the checklist.
+
+---
+
+## Honesty about sources
+
+**NEVER** present **inferred** goals, prerequisites, verification, or out-of-scope as if they appeared in the plan. **Why:** teammates act on fiction. Tag with `(inferred)` or state in conversational wrapper: "Plan had no Done when — verification derived from tasks."
+
+**NEVER** invent file paths or spec links not present in the plan. **Why:** stale links wreck trust; use placeholders only if unavoidable: `[link TBD]` and say why.
+
+---
+
+## Paste-ready output
+
+**NEVER** put meta-commentary (**"I'll now…"**, rationale paragraphs) **inside** the titled blocks (`TITLE`, `DESCRIPTION`, checklist sections meant for paste). **Why:** pollutes tooling fields. Keep prose **before or after** the paste blocks only.
+
+**NEVER** use vague verification lines like `"tests pass"` without naming **which** command or scope. **Why:** unmeasurable; use concrete commands (`pnpm test`, `pytest apps/api/...`) from the plan or mark `(add command)`.
+
+---
+
+## Estimates & sizing
+
+**NEVER** report a single point estimate as certainty (e.g. "4h exactly"). **Why:** AI-assisted variance is wide; stick to optimistic — realistic range and optional buffer narrative.
+
+**NEVER** apply the tier table blindly to spikes, migrations, or "unknown-unknown" chunks. **Why:** those need **XL** or explicit `"too uncertain — spike first"` flag in timeline notes.
+
+---
+
+## Scale
+
+**NEVER** put **100+** checkbox items on one card when blocks exist. **Why:** defeats tracking; split by block per SKILL.md parent/child guidance.
+
+---
+
+## Conflicting or missing input
+
+**NEVER** silently pick a phase when multiple plan files apply. **Why:** wrong scope. Prefer: list candidates, recommend one default, confirm.
+
+**NEVER** output an empty checklist because the plan "reads like prose". **Why:** salvage with inferred task bullets or ask one clarifying question before shipping empty.
+
+**NEVER** invent a **Goal** or **Done when** for task-only plans (no Goal / verification section) without tagging **`(inferred)`** in the conversational wrapper. **Why:** prose-only plans look complete but aren't; teammates treat invented goals as authoritative. Derive from dominant theme / last tasks and say so explicitly.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@llodev/pm-tasks-core",
+  "version": "1.0.0",
+  "description": "Core skill for the pm-tasks-* family: extracts implementation plans into structured task content, defines the CRUD vocabulary (task.create, checklist.check, task.close, task.due-date.set, task.assignee.add, task.comment.add), specifies the autonomous-mode contract, and provides the shared init UX library for tool adapters. Use when an adapter (pm-tasks-trello, pm-tasks-asana, etc.) needs the canonical generic-card structure or when running the init helper for any tool.",
+  "license": "MIT",
+  "homepage": "https://github.com/llodev/skills/tree/main/pm-tasks/pm-tasks-core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/llodev/skills.git",
+    "directory": "pm-tasks/pm-tasks-core"
+  },
+  "files": [
+    "SKILL.md",
+    "references",
+    "anti-patterns",
+    "scripts",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "codex",
+    "windsurf",
+    "plan-to-tasks",
+    "pm-tools"
+  ],
+  "type": "module",
+  "exports": {
+    "./init-lib": "./scripts/init-lib.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/audit-log-format.md

@@ -0,0 +1,44 @@
+# Audit log format
+
+Append-only JSONL at `~/.local/share/llodev/pm-tasks/<tool>/audit.log` (configurable via `autonomous.auditLog`).
+
+## Required fields (every entry)
+
+| Field     | Type    | Notes                                                                   |
+| --------- | ------- | ----------------------------------------------------------------------- |
+| `ts`      | string  | ISO 8601 with timezone                                                  |
+| `verb`    | string  | one of the 6 CRUD verbs                                                 |
+| `tool`    | string  | `trello`, `asana`, etc.                                                 |
+| `ok`      | boolean | success of the operation                                                |
+| `session` | string  | caller-provided session id (defaults to a random short id when missing) |
+
+## Verb-dependent fields
+
+| Verb                | Additional                                                |
+| ------------------- | --------------------------------------------------------- |
+| `task.create`       | `id`, `url`, `name`, `clientToken?`, `scope.{board,list}` |
+| `checklist.check`   | `id`, `item`                                              |
+| `task.close`        | `id`                                                      |
+| `task.due-date.set` | `id`, `due`                                               |
+| `task.assignee.add` | `id`, `userAlias`                                         |
+| `task.comment.add`  | `id`, `commentId`, `clientToken?`                         |
+
+## Example
+
+```jsonl
+{"ts":"2026-06-11T18:00:00Z","verb":"task.create","tool":"trello","ok":true,"id":"abc123","url":"https://trello.com/c/abc123/...","name":"Implementar feature X","clientToken":"ct-xyz","scope":{"board":"proj-x","list":"backlog"},"session":"sess-001"}
+{"ts":"2026-06-11T18:05:00Z","verb":"checklist.check","tool":"trello","ok":true,"id":"abc123","item":"build endpoint","session":"sess-001"}
+{"ts":"2026-06-11T18:10:00Z","verb":"task.close","tool":"trello","ok":true,"id":"abc123","session":"sess-001"}
+```
+
+## Concurrency
+
+Single-line JSON writes < 4KB are atomic at OS level on Linux/macOS. Multiple agents in parallel do not corrupt. No locks.
+
+## Rotation
+
+`pm-tasks/pm-tasks-core/scripts/rotate-audit.sh` purges entries older than 90 days. Suggested cron entry in this file's README.
+
+## Lookup usage
+
+The log doubles as the lookup index for `<task-ref>` resolution steps 4–5. Adapter implementations scan from newest to oldest, filter by `scope.boards`, match `clientToken` or name partial.

package/references/autonomous-mode.md

@@ -0,0 +1,61 @@
+# Autonomous mode
+
+Operations executed without a human reviewing each step. Designed for invocation by AI agents during task execution.
+
+## Activation (three signals)
+
+1. **Prompt sentinel** — caller includes `[autonomous]` or `--auto` literally.
+2. **Env var** — `LLODEV_PM_TASKS_AUTONOMOUS=1` (for CI / cron).
+3. **Never inferred.** Without sentinel or env, preview + human approval is mandatory.
+
+## Allowlist gate (in tool config)
+
+Autonomous mode requires an `autonomous` block in `.<tool>.json` (or its global counterpart):
+
+```json
+{
+  "autonomous": {
+    "enabled": true,
+    "allow": ["task.create", "checklist.check", "task.close", "task.due-date.set", "task.assignee.add", "task.comment.add"],
+    "scope": {
+      "boards": ["<board-or-project-id>"],
+      "lists": ["<list-or-section-id>"]
+    },
+    "rateLimit": { "writesPerMinute": 30, "commentsPerMinute": 10 },
+    "auditLog": "~/.local/share/llodev/pm-tasks/<tool>/audit.log"
+  }
+}
+```
+
+Block missing OR `enabled: false` → autonomous aborts with `{ ok: false, code: "INVALID_CONFIG" }`.
+Verb not in `allow` → `{ code: "ALLOWLIST_VIOLATION" }`.
+Target outside `scope` → `{ code: "OUT_OF_SCOPE" }`.
+Rate exceeded → `{ code: "RATE_LIMITED" }`.
+
+## Hard-coded forbidden verbs (v1)
+
+Regardless of allowlist:
+
+- `task.delete`, `task.archive`
+- `task.rename`
+- `task.description.replace`
+- `task.assignee.remove`, any `member.remove`
+- Any operation outside `scope`
+
+Returns `{ code: "FORBIDDEN_VERB" }` without touching MCP.
+
+## Write-through flow
+
+- Skip Phase 5.x preview & approval.
+- Run allowlist + scope + rate-limit checks.
+- Call MCP write tool.
+- Emit structured envelope to caller (JSON, not human-formatted).
+- Append entry to audit log per [`audit-log-format.md`](audit-log-format.md).
+
+## Failure handling
+
+Any failure → structured envelope. Skill does NOT auto-retry. Caller decides retry/abort/escalate. If the verb supports `clientToken`, caller can safely retry the exact same call (will be deduped).
+
+## Forensics
+
+The audit log is the source of truth for "what happened in this autonomous session". Also serves as the lookup index for `taskRef` step 4–5 in [`crud-vocabulary.md`](crud-vocabulary.md).

package/references/contract.md

@@ -0,0 +1,90 @@
+# pm-tasks-core ↔ adapter contract
+
+> **Versioning:** Renaming or removing a field below is a **MAJOR** bump for `@llodev/pm-tasks-core`. Adding optional fields is a minor bump. CI `contract-check.yml` enforces this.
+
+This document is the single source of truth that every `pm-tasks-<tool>` adapter consumes. Adapters MUST execute Phases 1–3 (defined here) before applying their tool-specific formatting.
+
+## Phase 1 — Identify the input
+
+Resolve which plan text to analyze:
+
+1. `@path` in the prompt → read that file (full file, no range limits).
+2. Inline pasted text → use as-is.
+3. "this plan" / implicit → most recently opened plan file in the workspace.
+
+Multiple plausible candidates → list them, recommend one default, confirm before proceeding.
+
+## Phase 2 — Extract sections by intent
+
+Map sections by intent (labels vary across languages and authoring styles):
+
+| Concept       | Common labels                                              |
+| ------------- | ---------------------------------------------------------- |
+| Goal          | `Goal`, `Objective`, `Purpose`                             |
+| Spec refs     | `Spec:`, `Design doc`, links to spec files                 |
+| Prerequisites | `Pre-flight`, `Requirements`, `Baseline check`             |
+| File map      | `File map`, `Files created/modified`, `Deliverables`       |
+| Tasks         | `## Task N`, `### Task N`, numbered blocks                 |
+| Task groups   | `## Block A`, thematic headers grouping tasks              |
+| Done criteria | `Done when`, `Self-review checklist`, `Final verification` |
+| Out of scope  | `Out of scope`, `What comes after`                         |
+| Next step     | `What comes after`, `Phase N+1`, `Next phase`              |
+
+Implicit sections → infer from structure. Tasks-only inputs → derive goal from first block, derive verification from last tasks, tag everything inferred with `(inferred)`.
+
+## Phase 3 — Build the generic card
+
+Produce blocks in the order defined in [`generic-card.md`](generic-card.md):
+
+1. `title` — single line, ≤120 chars by default
+2. `description` — goal + context + spec ref
+3. `implementationChecklist` — task-line verbatim or compressed per `fidelity` decision
+4. `verificationChecklist` — derived from done-when or last tasks
+5. `timeline` — AI-assisted estimate
+6. `labels` — derived from tags in the plan
+
+## Decisions emitted by the core
+
+The core resolves and exposes these decisions before Phase 4 begins. Adapters reference them by name:
+
+| Decision   | Values                                                 | Default              |
+| ---------- | ------------------------------------------------------ | -------------------- |
+| `scope`    | `one-card-per-phase`, `parent+children`, `single-card` | `one-card-per-phase` |
+| `audience` | `solo`, `squad`, `dense-board`                         | `solo`               |
+| `fidelity` | `verbatim`, `compressed`                               | `compressed`         |
+| `language` | `pt`, `en`, `mixed`                                    | detected from plan   |
+
+## CRUD verb vocabulary
+
+The 6 verbs of v1, with their semantic invariants and idempotency rules, live in [`crud-vocabulary.md`](crud-vocabulary.md). Adapters map each verb to one or more MCP tool calls.
+
+## Result envelope
+
+Every CRUD operation returns:
+
+```json
+{
+  "ok": true,
+  "verb": "<verb>",
+  "tool": "<tool>",
+  "ref": { "id": "<native-id>", "url": "<full-url>", "alias": "<alias-or-null>" },
+  "details": { /* verb-specific */ }
+}
+```
+
+Failures:
+
+```json
+{ "ok": false, "code": "<CODE>", "verb": "<verb>", "message": "<human>", "details": { } }
+```
+
+Stable error codes: `FORBIDDEN_VERB`, `OUT_OF_SCOPE`, `ALLOWLIST_VIOLATION`, `RATE_LIMITED`, `REF_NOT_RESOLVED`, `MCP_ERROR`, `INVALID_CONFIG`.
+
+## Standalone fallback
+
+Adapters MUST include a short fallback section in their own `SKILL.md` (~10 lines) for when this core is not installed: ask user for minimum input (title + checklist), skip extraction.
+
+## Compatibility notes for adapters
+
+- Reference this file by relative path: `pm-tasks/pm-tasks-core/references/contract.md`.
+- Declare `"@llodev/pm-tasks-core"` in `dependencies` for skillpm + Claude Code marketplace cascade. Vercel CLI users must install core manually — note this in the adapter description.

package/references/crud-vocabulary.md

@@ -0,0 +1,63 @@
+# CRUD vocabulary (v1)
+
+Six verbs. Each adapter maps every verb to one or more MCP tool calls.
+
+## task.create
+
+Create a new task/card/issue from a generic-card spec.
+
+- **Inputs:** `genericCard` (per `generic-card.md`), `targetList` (alias from config), `clientToken?` (opaque idempotency key).
+- **Idempotency:** Before creating, search the target scope for any task with matching `clientToken`. If found, return existing ref. Token persistence per tool documented in adapter `operations.md`.
+- **Returns:** envelope with `ref.{id,url}`.
+
+## checklist.check
+
+Mark a checklist item / subtask as complete.
+
+- **Inputs:** `taskRef`, `item` (text or index), `checklistName?` (when task has multiple).
+- **Idempotency:** natural (no-op if already checked).
+- **Returns:** envelope.
+
+## task.close
+
+Close / move to done.
+
+- **Inputs:** `taskRef`.
+- **Adapter semantics:** Trello → move to `closeListAlias`. Asana → `completed: true`. Linear → state `completed`. Notion → status `Done`. Bitrix24 → status `5`. Todoist → `close`.
+- **Idempotency:** natural.
+
+## task.due-date.set
+
+Set or change due date.
+
+- **Inputs:** `taskRef`, `due` (ISO 8601 date or `null` to clear).
+- **Idempotency:** no-op if value matches.
+
+## task.assignee.add
+
+Add an assignee/member to a task. v1 NEVER removes.
+
+- **Inputs:** `taskRef`, `userAlias` (from config `members`).
+- **Idempotency:** adapter checks current assignees before MCP call.
+
+## task.comment.add
+
+Post a comment / note / story.
+
+- **Inputs:** `taskRef`, `body`, `clientToken?`.
+- **Idempotency:** body is prefixed with `[ct:<clientToken>]` if provided. Adapter scans recent comments for matching token before posting.
+
+## Verbs forbidden in autonomous mode (v1, hard-coded)
+
+`task.delete`, `task.archive`, `task.rename`, `task.description.replace`, `task.assignee.remove`, any `member.remove`, and any operation targeting a board/project outside the declared autonomous `scope`.
+
+## `<task-ref>` resolution order
+
+Adapters resolve `taskRef` in this order, stopping at first success:
+
+1. Full task URL.
+2. Native ID.
+3. Alias in config `taskAliases`.
+4. `clientToken` match in audit log (most recent).
+5. Name partial match in audit log scoped to `autonomous.scope` (most recent).
+6. Otherwise → `{ ok: false, code: "REF_NOT_RESOLVED", candidates: [...] }`.

package/references/generic-card.md

@@ -0,0 +1,143 @@
+---
+description: Tool-agnostic card blocks (title, description, checklists, timeline, labels) for pm-tasks-core Phase 3. Read entire file before building paste blocks.
+---
+
+# Generic card blocks (Phase 3)
+
+> This file is referenced by every `pm-tasks-<tool>` adapter. Changes here may affect all adapters — coordinate via Changesets.
+
+Produce the following blocks **in order**. Adapt section names in Phase 4 per tool (see the adapter's `references/format.md`).
+
+For **paste/rendering** when a named tool is chosen, apply the adapter's paste-health rules during Phase 4 — not while drafting generic blocks.
+
+---
+
+## Title
+
+Pattern: `[System/Area] — [Phase N] ([short summary of what's built])`
+
+Max 80 characters. Examples:
+
+- `API Scaffold — Phase 1 (NestJS + shared wiring)`
+- `Celebrations BC — Phase 3 (domain + contracts + HTTP)`
+
+---
+
+## Description
+
+```
+**Goal:** [one sentence from the plan's goal, translated to plain language]
+
+**Spec:** [file or document reference]
+**Plan:** [file or document reference]
+**Prerequisite:** [phase or condition that must be true before starting]
+
+---
+
+**Deliverables**
+• [artifact 1]
+• [artifact 2]
+(group by layer/area if more than 7 items)
+
+---
+
+**Out of scope**
+• [explicitly deferred item 1]
+• [item 2]
+
+**Next step**
+**[Phase N+1 or follow-up name]** — [one sentence]
+```
+
+- Use `**Section**` labels (not `##`) when formatting for tools that flatten Markdown headings on paste.
+- **Publish flows (Phase 5+):** the adapter decides whether to omit **Out of scope** / **Next step** from `desc` / `html_notes` — see the adapter's `references/format.md`.
+- **Generic paste:** include Out of scope and Next step unless the user asks to drop them.
+
+---
+
+## Implementation checklist
+
+Structure:
+
+```
+### Pre-flight
+- [ ] [prerequisite check 1]
+- [ ] [prerequisite check 2]
+
+### [Block or Group name] (Tasks N–M)
+- [ ] Task N — [action verb] + [artifact] [(skill or note if relevant)]
+- [ ] Task N+1 — ...
+
+### [Next block]
+...
+```
+
+Rules:
+
+- One checkbox per task, not per step. Steps live inside the plan, not the card.
+- If a task includes a skill invocation, note it: `(skill: ts-ddd-entity)`
+- If a plan has no explicit blocks, group tasks by layer: setup, domain, application, infra, http, docs.
+- Pre-flight (baseline verification) always comes first.
+
+---
+
+## Verification checklist
+
+Draw from the plan's `Done when` / `Self-review checklist` / `Final verification` section.
+
+```
+### Verification
+
+- [ ] [test command] — passes
+- [ ] [build command] — exits 0
+- [ ] [runtime check] (e.g. curl localhost:3001/health returns expected payload)
+- [ ] [security/quality check] (e.g. no secrets staged, no forbidden imports)
+- [ ] [git hygiene check] (e.g. N commits, one per task)
+```
+
+---
+
+## Timeline estimate
+
+Estimate calendar time for a developer using AI assistance (Claude, Cursor, Copilot, etc.).
+
+**Complexity tiers per task:**
+
+| Tier               | Description                                  | AI-assisted estimate |
+| ------------------ | -------------------------------------------- | -------------------- |
+| S — Setup/config   | Files, manifests, workspace wiring           | 10–20 min            |
+| M — Standard TDD   | Write test → implement → pass                | 20–45 min            |
+| L — Complex domain | Entity/aggregate with invariants, many tests | 45–90 min            |
+| XL — Large block   | 4+ related tasks sharing the same fixture    | 1.5–3 h              |
+| Docs               | README, inline docs, layout updates          | 10–20 min            |
+
+**Estimation formula:**
+
+1. Classify each task by tier.
+2. Sum the estimates.
+3. Add 20% buffer for integration, context-switching, and debugging.
+4. Round to a practical unit (hours or days).
+5. Present a range: `optimistic — realistic`.
+
+**Format:**
+
+```
+### Estimated timeline (AI-assisted)
+
+| Scope                                       | Estimate                |
+| ------------------------------------------- | ----------------------- |
+| Optimistic (focused session, no blockers)   | Xh                      |
+| Realistic (normal day, some back-and-forth) | Xh / X days             |
+| Task count                                  | N tasks across N blocks |
+
+> Timeline assumes a developer with AI assistance (Claude/Cursor/Copilot).
+> Solo (no AI): multiply by 3–5×.
+```
+
+Generic output may keep the timeline **as Markdown table**. Adapters may flatten or relocate the table during Phase 4 per their paste-health rules in the adapter's `references/format.md`.
+
+---
+
+## Labels / Tags
+
+Suggest **3–6** from plan context: phase, domain/layer (`api`, `web`, …), status, size tier from timeline tiers. Apply the adapter's label palette and caps (defined in the adapter's `references/format.md`).

package/references/init-ux.md

@@ -0,0 +1,62 @@
+# Init UX (shared across pm-tasks-<tool> adapters)
+
+Every `pm-tasks-<tool>` adapter exposes `npx @llodev/pm-tasks-<tool> init` and follows this four-step flow. Implementation library at `pm-tasks/pm-tasks-core/scripts/init-lib.mjs`.
+
+## Step 1 — Scope prompt
+
+```
+Where should the config live?
+  > local    → ./.{tool}.json (per-repo override)
+    global   → ~/.config/llodev/pm-tasks/{tool}.json
+```
+
+Default highlight: `local` if inside a git repo, `global` otherwise.
+
+## Step 2 — MCP auto-detect
+
+Adapter probes the tool's MCP with the lightest read operation:
+
+- Trello → `list_boards`
+- Asana → `list_workspaces`
+- Linear → `viewer`
+- Notion → `users.me`
+- ...
+
+Three outcomes:
+
+| Outcome                        | Action                                                                    |
+| ------------------------------ | ------------------------------------------------------------------------- |
+| MCP responded                  | Go to Step 3A (MCP-assisted).                                             |
+| MCP exists but unauthenticated | Print exact env var names (`LLODEV_PM_TASKS_<TOOL>_<NAME>`) to set, exit. |
+| MCP not configured             | Print MCP setup instructions for the adapter, go to Step 3B (scaffold).   |
+
+## Step 3A — MCP-assisted (happy path)
+
+Read-only MCP calls enumerate workspace → boards/projects → lists/sections → labels → members. User picks via interactive prompts (multi-select for arrays).
+
+Final prompt: *"Enable autonomous mode? (adds an `autonomous` block with conservative defaults: 6 verbs, rate 30/min, no hard-coded scope — you add it afterwards)"* — default `n`.
+
+Write the config; validate against `schemas/config.json`; exit.
+
+## Step 3B — Scaffold (fallback)
+
+Write `.{tool}.json` with placeholders and inline `// comments` showing where to find each ID. Print MCP setup instructions referencing the adapter's `references/mcp-config.md`. Exit.
+
+## Step 4 — Confirmation
+
+Print:
+
+- Path written
+- Schema validation result
+- Sample trigger prompt the user can paste (`"create a card on <tool> from this plan"`)
+- Reminder: secrets go in env vars or OS keychain, NEVER in this JSON.
+
+## Implementation API (consumed by adapters)
+
+Adapter `scripts/init.mjs` imports from `@llodev/pm-tasks-core/init-lib`:
+
+```javascript
+import { promptScope, promptYesNo, multiSelect, writeConfig, validateConfig, probeMCP, printInstructions } from "@llodev/pm-tasks-core/init-lib";
+```
+
+Each adapter implements its own MCP-probing logic and field-mapping; UX primitives are shared.

package/scripts/init-lib.mjs

@@ -0,0 +1,88 @@
+// @llodev/pm-tasks-core/init-lib
+// Shared init primitives. Node 20+ built-ins + Ajv for schema validation.
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { mkdir, writeFile, access, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+const rl = () => createInterface({ input, output });
+
+export async function promptScope(toolName) {
+  const r = rl();
+  try {
+    console.log(`\nWhere should the ${toolName} config live?\n  1) local   → ./.${toolName}.json\n  2) global  → ~/.config/llodev/pm-tasks/${toolName}.json`);
+    const a = (await r.question("Choose [1/2] (default 1): ")).trim() || "1";
+    if (a === "1") return { scope: "local", path: path.resolve(`.${toolName}.json`) };
+    if (a === "2") return { scope: "global", path: path.join(homedir(), ".config", "llodev", "pm-tasks", `${toolName}.json`) };
+    throw new Error(`invalid choice: ${a}`);
+  } finally { r.close(); }
+}
+
+export async function promptYesNo(question, defaultNo = true) {
+  const r = rl();
+  try {
+    const a = (await r.question(`${question} [y/N]: `)).trim().toLowerCase();
+    if (a === "y" || a === "yes") return true;
+    return false;
+  } finally { r.close(); }
+}
+
+export async function multiSelect(label, choices) {
+  const r = rl();
+  try {
+    console.log(`\n${label}`);
+    choices.forEach((c, i) => console.log(`  ${i + 1}) ${c.label}`));
+    const a = (await r.question("Select (comma-separated, e.g. 1,3,5): ")).trim();
+    const picks = a.split(",").map((x) => parseInt(x.trim(), 10) - 1).filter((i) => i >= 0 && i < choices.length);
+    return picks.map((i) => choices[i].value);
+  } finally { r.close(); }
+}
+
+export async function writeConfig(targetPath, data) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  try { await access(targetPath); throw new Error(`config already exists at ${targetPath}, aborting`); } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  await writeFile(targetPath, JSON.stringify(data, null, 2) + "\n");
+}
+
+export async function validateConfig(data, schema) {
+  // Adapter loads its own schemas/config.json and passes it here for validation.
+  const { default: Ajv2020 } = await import("ajv/dist/2020.js");
+  const { default: addFormats } = await import("ajv-formats");
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  if (!validate(data)) {
+    return { ok: false, errors: validate.errors };
+  }
+  return { ok: true };
+}
+
+export async function probeMCP({ tool, probeCommand }) {
+  // Caller-supplied async probe function; library only sequences UX.
+  try {
+    const result = await probeCommand();
+    return { mcpAvailable: true, result };
+  } catch (e) {
+    if (/^auth\b|\b(unauthorized|forbidden)\b|\b40[13]\b/i.test(e.message)) {
+      return { mcpAvailable: true, unauthenticated: true, error: e.message };
+    }
+    return { mcpAvailable: false, error: e.message };
+  }
+}
+
+export function printInstructions(lines) {
+  console.log(`\n${lines.join("\n")}\n`);
+}
+
+export async function readJsonIfExists(p) {
+  try {
+    const src = await readFile(p, "utf8");
+    return JSON.parse(src);
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}

package/scripts/rotate-audit.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Rotate audit log for a given tool. Keeps last 90 days.
+set -euo pipefail
+
+TOOL="${1:-}"
+if [[ -z "$TOOL" ]]; then
+  echo "usage: rotate-audit.sh <tool>"
+  echo "example: rotate-audit.sh trello"
+  exit 2
+fi
+
+LOG_DIR="${LLODEV_PM_TASKS_LOG_DIR:-$HOME/.local/share/llodev/pm-tasks}/$TOOL"
+LOG="$LOG_DIR/audit.log"
+KEEP_DAYS="${KEEP_DAYS:-90}"
+
+[[ ! -f "$LOG" ]] && { echo "(no log at $LOG, nothing to rotate)"; exit 0; }
+
+CUTOFF=$(date -u -v -"${KEEP_DAYS}"d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "${KEEP_DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ)
+TMP="$(mktemp)"
+
+awk -v cutoff="$CUTOFF" 'match($0, /"ts":"([^"]+)"/, m) { if (m[1] >= cutoff) print }' "$LOG" > "$TMP"
+
+mv "$TMP" "$LOG"
+echo "rotated $LOG (kept entries >= $CUTOFF)"