taskpod - npm Package Compare versions

Comparing version 0.4.1 to 0.4.2

dist/cli/skill-content.js

@@ -1,12 +0,3 @@
-/**
- * Bundled TaskPod agent skill — the offline fallback for `taskpod agent-setup`.
- *
- * The setup command prefers the live copy at <apiBase>/skill.md (5s timeout);
- * when that fetch fails for any reason it falls back to this snapshot, so the
- * Claude Code skill install works offline and against self-hosted instances.
- *
- * Source of truth: SKILL.md in the TaskPod web repo (served at
- * https://taskpod.in/skill). Refresh this snapshot when that document changes.
- */
-/** Claude Code skill frontmatter for .claude/skills/taskpod/SKILL.md. */
+// Auto-generated from TaskPod/SKILL.md — regenerate on skill changes (MC-071).
+// The agent-setup fetch chain prefers the live taskpod.in/skill.md; this is the offline fallback.
 export const SKILL_FRONTMATTER = `---
@@ -17,2 +8,2 @@ name: taskpod
 /** The full skill body (markdown, no frontmatter). */
-export const BUNDLED_SKILL_BODY = "# Taskpod Agent Skill — the Central Mind Protocol\n\nYou are an AI agent (Claude Code, Codex, Cursor, or any MCP-capable tool) working in a codebase whose team runs on Taskpod (https://taskpod.in). Taskpod is the team's **central mind**: N developers and N agents work in parallel, and the board + its memory are the one place where everything they know converges. Your job is not just to write code — it is to **inherit the shared context before you start, mirror your work on the board while you work, and write back what you learned when you stop**, so the next agent or human starts smarter than you did.\n\nThis document is the working agreement. Every rule is imperative and testable. Follow it exactly.\n\n## The contract in one table\n\n| Phase | Obligation | Primary tool |\n|-------|-----------|--------------|\n| **Session start** | Pull the context digest and ingest it **before any work**; resume anything IN_PROGRESS | `sync_context` / `taskpod sync` · `resume_task` |\n| **During work** | Every status change is a checkpoint; progress is narrated; blockers become handoffs, never silence | `checkpoint_task` · `add_comment` · `handoff_to_human` |\n| **Session end / on discovery** | Record every non-obvious learning, decision, convention, or gotcha; then sync again so it propagates | `record_learning` · `sync_context` |\n\nA silent status change, an unrecorded gotcha, or an undocumented decision is a **bug in your behavior**, not a shortcut.\n\n---\n\n## Setup — connect your tool\n\nAll access uses one API key (Taskpod → **Settings → API Access**, keys look like `tp_live_...`). The MCP server ships in the `taskpod` npm package — no clone, no build. Self-hosting? Set `TASKPOD_API_URL` to your instance.\n\n### Claude Code\n\nOne command, run in the repo root:\n\n```bash\nnpx -y taskpod agent-setup\n```\n\nThis writes `.mcp.json` (registers the Taskpod MCP server) and appends a Taskpod protocol block to `CLAUDE.md` so every future session follows this skill automatically. Prefer manual control? Add this `.mcp.json` yourself:\n\n```json\n{\n  \"mcpServers\": {\n    \"taskpod\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"taskpod\", \"mcp\", \"--api-key\", \"tp_live_YOUR_KEY\"]\n    }\n  }\n}\n```\n\nIf you have run `taskpod login`, drop the `--api-key` pair — the server falls back to your stored token.\n\n### Cursor\n\nCreate `.cursor/mcp.json` in the repo (or `~/.cursor/mcp.json` for all projects):\n\n```json\n{\n  \"mcpServers\": {\n    \"taskpod\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"taskpod\", \"mcp\", \"--api-key\", \"tp_live_YOUR_KEY\"]\n    }\n  }\n}\n```\n\nThen enable the server in Cursor Settings → MCP.\n\n### Codex\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.taskpod]\ncommand = \"npx\"\nargs = [\"-y\", \"taskpod\", \"mcp\", \"--api-key\", \"tp_live_YOUR_KEY\"]\n```\n\n### Any other MCP client\n\nRegister a stdio server with the command:\n\n```bash\nnpx -y taskpod mcp --api-key tp_live_YOUR_KEY\n```\n\n### No MCP? Use REST\n\nEvery action below is also a plain REST call with the same key — full reference at https://taskpod.in/api-docs:\n\n```bash\ncurl -s https://taskpod.in/api/projects \\\n  -H \"X-API-Key: tp_live_YOUR_KEY\" \\\n  -H \"Content-Type: application/json\"\n```\n\n### Link the repo to its project\n\nIn a repo that isn't linked yet:\n\n```bash\nnpx -y taskpod init    # repo → workspace: creates/links the Taskpod project\nnpx -y taskpod sync    # pulls the context digest into .taskpod/\n```\n\n(Same thing from MCP: `init_workspace`, then `sync_context`.)\n\n---\n\n## 1. Session start (MANDATORY)\n\nDo these steps **in order, before reading or writing any code**:\n\n1. **Pull the digest.** Call `sync_context({ projectId })` — or run `taskpod sync` (or `taskpod pull`) in a linked repo. It returns a compact context digest: sprint state, the tasks you own, recent learnings, and the project's conventions.\n2. **Ingest it.** Read the digest end to end. Conventions and gotchas in it **constrain your work** — an agent that codes against a recorded convention is worse than one that never synced.\n3. **Resume, never restart.** If any task assigned to you is `IN_PROGRESS`, call `resume_task({ ticketId })` on it before anything else. It returns the last checkpoint, the last human comment, dependency state, and subtask progress.\n4. **Address humans first.** If `resume_task` reports `hasUnreadUserComments: true`, read and answer that feedback before doing anything else.\n5. **Then pick work.** Use `get_sprint_status({ projectId })` and its `nextRecommended` — the highest-priority unblocked task — not your memory of the project.\n\n> Starting work without `sync_context` is the protocol's cardinal sin: you will re-discover known gotchas, violate recorded conventions, and re-litigate settled decisions.\n\n## 2. During work\n\n### Every status change is a checkpoint\n\n**Never** change a task's status with a bare update. **Always** use `checkpoint_task` — it combines the status change with a mandatory comment saying *why* it moved and what happens next:\n\n```\ncheckpoint_task({\n  taskId: \"<id>\",\n  status: \"IN_PROGRESS\",\n  aiStep: \"IMPLEMENT\",\n  comment: \"Starting [AF-102]. Approach: extend lib/api-auth.ts with the refresh path; tests alongside. First step: stub the endpoint.\",\n  aiAuthor: \"<your-model-name>\"\n})\n```\n\nWhat the checkpoint comment must contain, per transition:\n\n| Transition | The comment must include |\n|-----------|--------------------------|\n| → `IN_PROGRESS` | Approach, first step, dependencies verified |\n| → `IN_REVIEW` | Work report: AC status table, changes, how verified, PR link |\n| → `DONE` | Every acceptance criterion verified with evidence + changes summary |\n| → `CANCELLED` | Why, and any follow-up task created |\n| → `WAITING_APPROVAL` / `WAITING_INPUT` | The exact ask, and your default if unanswered |\n\nAlways set `aiStep` (`PLAN` → `RESEARCH` → `IMPLEMENT`) alongside status.\n\n### Narrate progress\n\nPost an `add_comment` roughly **every 30 minutes of active work**, or at any meaningful event — files changed, a decision made, a blocker hit, a test suite going green. The board must never go quiet while work is happening. Lead each comment with its type so histories stay scannable:\n\n| Type | Trigger | Must contain |\n|------|---------|--------------|\n| `checkpoint` | Any status change | New status · why · what's next |\n| `progress` | ~30 min / meaningful change | Done since last · in progress · next · remaining |\n| `decision` | A non-obvious choice | Context · options · decision · consequence |\n| `blocker` | Work can't proceed | What's blocked · why · what's needed · who can unblock |\n| `handoff` | Ownership changes party | From → to · state summary · the exact ask · links |\n| `work-report` | On `IN_REVIEW` / `DONE` | AC verification table · changes · how verified · PR |\n| `question` | Input needed, non-blocking | The question · why it matters · your default if no reply |\n\nFrom the CLI: `taskpod comment AF-102 -t progress \"...\"`.\n\n### Blocked? Hand off — never stall, never guess\n\nWhen you hit a decision, a missing secret, or a judgment call only a human can make:\n\n1. Call `handoff_to_human({ taskId, needs })` — it moves the task to `WAITING_INPUT` with the human as owner — or checkpoint to `WAITING_APPROVAL` when a plan needs sign-off.\n2. The comment states the **precise ask** and **your default if no reply** (so silence still has a defined outcome).\n3. Acknowledge every inbound handoff with a comment before you start on it.\n\nA work-report checkpoint, the shape reviewers expect on `IN_REVIEW`/`DONE`:\n\n```markdown\n**[IN_REVIEW]** AF-102 complete.\n\n| Acceptance criterion | Status | Evidence |\n| --- | --- | --- |\n| Silent refresh before expiry | ✅ | `refresh()` + test `refreshes-before-expiry` |\n| Failing refresh logs the user out | ✅ | test `logout-on-refresh-fail` |\n\n**Changes:** `lib/api-auth.ts`, `__tests__/auth.test.ts`.\n**How verified:** `npm test` green (3 new), manual expiry simulation.\n**PR:** #214 (CI green).\n```\n\n### Reference tickets everywhere\n\nWrite ticket keys as `[KEY-123]` in commit messages, PR titles/descriptions, and comments (e.g. `fix: token refresh race [AF-102]`). This is what lets the board, the repo, and the humans cross-reference your work.\n\n## 3. Session end & on discovery — write back to the central mind\n\nThis is what makes Taskpod more than a task tracker. Everything you learned that isn't already written down **dies with your context window unless you record it**.\n\n### Record learnings the moment you discover them\n\nWhenever you discover something non-obvious — and again in a sweep before you end the session — call:\n\n```\nrecord_learning({\n  projectId: \"<id>\",\n  kind: \"gotcha\",          // learning | decision | convention | gotcha\n  title: \"Tailwind v4 classes unreliable under Turbopack\",\n  content: \"Layout-critical CSS must use inline style props; Tailwind utility classes intermittently drop under Turbopack dev builds. Bit AF-088 and AF-094.\"\n})\n```\n\n| Kind | Record when you… | Example title |\n|------|------------------|---------------|\n| `learning` | Discovered something non-obvious about the system or domain | \"Webhook retries are at-least-once — handlers must be idempotent\" |\n| `decision` | Made a choice with real alternatives | \"Chose file-based token storage over OS keychain\" |\n| `convention` | Found (or set) a pattern all future work must repeat | \"Every API route uses the dual-auth pattern from lib/api-auth.ts\" |\n| `gotcha` | Lost time to a trap the next agent would also hit | \"prisma db push required after schema change or dev server 500s\" |\n\n**Rules for a good learning:**\n\n- **One insight per entry.** Never batch three discoveries into one record.\n- **Titled and concise.** A short imperative title; content is the what + why-it-matters in a few lines. Not an essay, not a diff.\n- **Novel only.** Never record what the repo (README, CLAUDE.md, code comments) or the board (task descriptions, existing learnings) already says. Check the digest's recent learnings first — duplicates poison the digest.\n- **Actionable for a stranger.** Write for the next agent with zero context: name files, commands, and error messages.\n\n### Then sync again\n\nEnd every session with:\n\n1. **Board truth check** — every task you touched is in its true status with a checkpoint; anything mid-flight has a fresh `progress` comment. Never leave a task `IN_PROGRESS` and silent.\n2. **Learning sweep** — anything non-obvious from this session recorded via `record_learning` (one entry each).\n3. **`sync_context` again** (or `taskpod sync`, which pushes learnings up and pulls the fresh digest down). This confirms your write-back landed and hands the next agent — or the same developer's other agent, already running — the updated digest.\n\n> This loop is the point: N developers × N agents, one memory. What one agent learns at 10:04, another inherits at 10:05.\n\n---\n\n## Status lifecycle\n\n```\nBACKLOG → TODO → IN_PROGRESS → IN_REVIEW → DONE\n                      │              │\n                      └── CANCELLED ─┘\n```\n\n| Status | Meaning |\n|--------|---------|\n| `BACKLOG` | Created, not yet planned (AI-staged plans wait here) |\n| `TODO` | Planned, dependencies met, ready to start |\n| `IN_PROGRESS` | Actively being worked — must never go comment-silent |\n| `IN_REVIEW` | Delivered, awaiting human review (agents finish here, with a work report) |\n| `DONE` | All acceptance + exit criteria verified in the checkpoint |\n| `CANCELLED` | Descoped — the checkpoint says why |\n| `WAITING_APPROVAL` | Parked on a human decision (plans, agent asks) |\n| `WAITING_INPUT` | Handed back to a human; the ask + your default are in the comment |\n| `GRADING` | Agent-plane verification of finished work (set by the orchestrator, not by hand) |\n\nWhen completing a task unblocks others, checkpoint each newly unblocked task to `TODO` with a comment naming what unblocked it.\n\n## Creating new work\n\nEvery task you create gets a full description — no title-only tasks, ever:\n\n```markdown\n## Problem Statement\n[What needs to be built and why]\n\n## Proposed Solution\n[Specific implementation approach]\n\n## Acceptance Criteria\n- [ ] [Specific, testable criterion]\n- [ ] [Specific, testable criterion]\n\n## Exit Criteria\n- [ ] Code compiles with zero errors\n- [ ] Tests written and passing\n```\n\nThen: set a priority (`URGENT`/`HIGH`/`MEDIUM`/`LOW`), wire ordering with `add_dependency` (schema blocks API blocks UI…), and checkpoint the new task to `TODO` with a creation comment. A task without acceptance criteria cannot be handed to an agent — the checklist is what makes work specifiable.\n\n---\n\n## Tool & command reference\n\nThe MCP server registers 50+ tools. These are the ones the protocol turns on:\n\n### Central-mind tools (the protocol core)\n\n| Tool | When |\n|------|------|\n| `sync_context` | **Session start and end** — returns the compact context digest (sprint, owned tasks, recent learnings, conventions) |\n| `record_learning` | **On discovery / session end** — `{ projectId, kind: learning\\|decision\\|convention\\|gotcha, title, content }` |\n| `init_workspace` | Once per repo — link it to its Taskpod project |\n| `checkpoint_task` | **Every status change** — status + mandatory why-comment, atomically |\n| `resume_task` | **Before touching any existing task** — last checkpoint, unread human comments, dependency + subtask state |\n| `get_sprint_status` | Board overview + `nextRecommended` task |\n| `handoff_to_human` | Stuck → `WAITING_INPUT` with a precise ask; use instead of stalling or guessing |\n\n### CRUD tools (the other 40+)\n\n| Area | Tools |\n|------|-------|\n| Teams & members | `get_teams`, `create_team`, `update_team`, `delete_team`, `add_team_member`, `remove_team_member`, `list_team_members`, `list_users` |\n| Projects | `create_project`, `list_projects`, `get_project_structure`, `update_project`, `delete_project`, `export_project`, `add_project_member`, `remove_project_member`, `list_project_members` |\n| Folders | `create_folder`, `list_folders`, `update_folder`, `delete_folder` |\n| Tasks | `create_task`, `get_task`, `update_task`, `delete_task`, `list_tasks`, `search_tasks`, `create_subtask`, `log_time` |\n| Collaboration | `add_comment`, `get_recent_activity`, `add_dependency`, `remove_dependency`, `add_task_watcher`, `remove_task_watcher`, `list_task_watchers` |\n| Resources | `list_project_resources`, `add_project_resource`, `remove_project_resource` |\n\n### CLI\n\n| Command | Does |\n|---------|------|\n| `taskpod init` | Repo → workspace: create/link the project from the terminal |\n| `taskpod sync` | ↓ pull the context digest into `.taskpod/` · ↑ push recorded learnings |\n| `taskpod agent-setup` | Write `.mcp.json` + a `CLAUDE.md` protocol block into the repo |\n| `taskpod status` | Sprint status for the linked project |\n| `taskpod mine` | Your tasks — status, ETA, blockers |\n| `taskpod show AF-102` | Full task detail with comments |\n| `taskpod start AF-102` | Checkpoint to `IN_PROGRESS` |\n| `taskpod done AF-102` | Checkpoint to `DONE` (prompts for the work report) |\n| `taskpod comment AF-102 -t <type>` | Typed comment (see the taxonomy above) |\n| `taskpod handoff AF-102` | Hand ownership to a human or agent |\n| `taskpod pull` | Refresh the `.taskpod/` context bundle only |\n| `taskpod login` | Store your token (then `--api-key` is optional everywhere) |\n| `taskpod mcp` | Run the MCP server on stdio |\n\nIn a linked repo, read `.taskpod/` as normal repo context: `context.md` (project overview), `board.json` (every task), `mine.md` (your tasks), `deps.md` (what blocks what), `resources.md` (repos, docs, consoles), `SKILL.md` (this protocol).\n\n---\n\n## Never do\n\n- **Never** change a task's status without a checkpoint comment.\n- **Never** start work without `sync_context` — or on an existing task, without `resume_task`.\n- **Never** ignore unread user comments; address them before new work.\n- **Never** mark `DONE` without verifying every acceptance criterion, with evidence, in the checkpoint.\n- **Never** record a learning the repo or board already documents — check the digest first.\n- **Never** batch multiple insights into one `record_learning` entry.\n- **Never** leave a task `IN_PROGRESS` and silent at session end — checkpoint it or post a `progress` comment.\n- **Never** guess through a blocker — `handoff_to_human` with a precise ask and your default.\n- **Never** create a task without a description, acceptance criteria, and a priority.\n- **Never** end a session without the learning sweep + final `sync_context`.\n\n## Loading this skill\n\nGive your AI tool this prompt (works with MCP configured, or over plain REST with https://taskpod.in/api-docs):\n\n```\nRead https://taskpod.in/skill and follow it for all work. Taskpod is the\nteam's central mind. Non-negotiable: call sync_context at session start and\ningest the digest before any work; resume_task before touching any existing\ntask; checkpoint_task for EVERY status change; record_learning for every\nnon-obvious decision, convention, or gotcha you discover (one per entry,\nnever duplicating what's already recorded); and sync_context again before\nyou stop. API key: <your tp_live_... token>.\n```\n";
+export const BUNDLED_SKILL_BODY = "# Taskpod Agent Skill — the Central Mind Protocol\n\nYou are an AI agent (Claude Code, Codex, Cursor, or any MCP-capable tool) working in a codebase whose team runs on Taskpod (https://taskpod.in). Taskpod is the team's **central mind**: N developers and N agents work in parallel, and the board + its memory are the one place where everything they know converges. Your job is not just to write code — it is to **inherit the shared context before you start, mirror your work on the board while you work, and write back what you learned when you stop**, so the next agent or human starts smarter than you did.\n\nThis document is the working agreement. Every rule is imperative and testable. Follow it exactly.\n\n## The contract in one table\n\n| Phase | Obligation | Primary tool |\n|-------|-----------|--------------|\n| **Session start** | Pull the context digest and ingest it **before any work**; resume anything IN_PROGRESS | `sync_context` / `taskpod sync` · `resume_task` |\n| **During work** | Every status change is a checkpoint; progress is narrated; blockers become handoffs, never silence | `checkpoint_task` · `add_comment` · `handoff_to_human` |\n| **Session end / on discovery** | Record every non-obvious learning, decision, convention, or gotcha; then sync again so it propagates | `record_learning` · `sync_context` |\n\nA silent status change, an unrecorded gotcha, or an undocumented decision is a **bug in your behavior**, not a shortcut.\n\n---\n\n## Setup — connect your tool\n\n<!-- The commands and config snippets below are mirrored in lib/agent-snippets.ts\n     (rendered by AgentConnectCard). Change one, change both. -->\n\nAll access uses one API key (Taskpod → **Settings → API Access**, keys look like `tp_live_...`). The MCP server ships in the `taskpod` npm package — no clone, no build. Self-hosting? Set `TASKPOD_API_URL` to your instance.\n\n### Claude Code\n\nOne command, run in the repo root:\n\n```bash\nnpx -y taskpod agent-setup\n```\n\nThis writes `.mcp.json` (registers the Taskpod MCP server) and appends a Taskpod protocol block to `CLAUDE.md` so every future session follows this skill automatically. Prefer manual control? Add this `.mcp.json` yourself:\n\n```json\n{\n  \"mcpServers\": {\n    \"taskpod\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"taskpod\", \"mcp\", \"--api-key\", \"tp_live_YOUR_KEY\"]\n    }\n  }\n}\n```\n\nIf you have run `taskpod login`, drop the `--api-key` pair — the server falls back to your stored token.\n\n`agent-setup` installs the curated quality skill pack automatically — alongside the Taskpod skill it drops the core pack (clean-code, design-patterns, pr-craft, verify-your-work, decompose-to-plan) into the repo's `.claude/skills/`. Pass `--no-skills` to skip it, or `--with-skills=all` to upgrade to the full pack (adds uxloom-journeys, java-annotations, and coverage-first-review).\n\n### Cursor\n\nCreate `.cursor/mcp.json` in the repo (or `~/.cursor/mcp.json` for all projects):\n\n```json\n{\n  \"mcpServers\": {\n    \"taskpod\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"taskpod\", \"mcp\", \"--api-key\", \"tp_live_YOUR_KEY\"]\n    }\n  }\n}\n```\n\nThen enable the server in Cursor Settings → MCP.\n\n### Codex\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.taskpod]\ncommand = \"npx\"\nargs = [\"-y\", \"taskpod\", \"mcp\", \"--api-key\", \"tp_live_YOUR_KEY\"]\n```\n\n### Any other MCP client\n\nRegister a stdio server with the command:\n\n```bash\nnpx -y taskpod mcp --api-key tp_live_YOUR_KEY\n```\n\n### No MCP? Use REST\n\nEvery action below is also a plain REST call with the same key — full reference at https://taskpod.in/api-docs:\n\n```bash\ncurl -s https://taskpod.in/api/projects \\\n  -H \"X-API-Key: tp_live_YOUR_KEY\" \\\n  -H \"Content-Type: application/json\"\n```\n\n### Link the repo to its project\n\nIn a repo that isn't linked yet:\n\n```bash\nnpx -y taskpod init    # repo → workspace: creates/links the Taskpod project\nnpx -y taskpod sync    # pulls the context digest into .taskpod/\n```\n\n(Same thing from MCP: `init_workspace`, then `sync_context`.)\n\n---\n\n## 1. Session start (MANDATORY)\n\nDo these steps **in order, before reading or writing any code**:\n\n1. **Pull the digest.** Call `sync_context({ projectId })` — or run `taskpod sync` (or `taskpod pull`) in a linked repo. It returns a compact context digest: sprint state, the tasks you own, recent learnings, and the project's conventions.\n2. **Ingest it.** Read the digest end to end. Conventions and gotchas in it **constrain your work** — an agent that codes against a recorded convention is worse than one that never synced.\n3. **Resume, never restart.** If any task assigned to you is `IN_PROGRESS`, call `resume_task({ ticketId })` on it before anything else. It returns the last checkpoint, the last human comment, dependency state, and subtask progress.\n4. **Address humans first.** If `resume_task` reports `hasUnreadUserComments: true`, read and answer that feedback before doing anything else.\n5. **Then pick work.** Use `get_sprint_status({ projectId })` and its `nextRecommended` — the highest-priority unblocked task — not your memory of the project.\n\n> Starting work without `sync_context` is the protocol's cardinal sin: you will re-discover known gotchas, violate recorded conventions, and re-litigate settled decisions.\n\n## 2. During work\n\n### Every status change is a checkpoint\n\n**Never** change a task's status with a bare update. **Always** use `checkpoint_task` — it combines the status change with a mandatory comment saying *why* it moved and what happens next:\n\n```\ncheckpoint_task({\n  taskId: \"<id>\",\n  status: \"IN_PROGRESS\",\n  aiStep: \"IMPLEMENT\",\n  comment: \"Starting [AF-102]. Approach: extend lib/api-auth.ts with the refresh path; tests alongside. First step: stub the endpoint.\",\n  aiAuthor: \"<your-model-name>\"\n})\n```\n\nWhat the checkpoint comment must contain, per transition:\n\n| Transition | The comment must include |\n|-----------|--------------------------|\n| → `IN_PROGRESS` | Approach, first step, dependencies verified |\n| → `IN_REVIEW` | Work report: AC status table, changes, how verified, PR link |\n| → `DONE` | Every acceptance criterion verified with evidence + changes summary |\n| → `CANCELLED` | Why, and any follow-up task created |\n| → `WAITING_APPROVAL` / `WAITING_INPUT` | The exact ask, and your default if unanswered |\n\nAlways set `aiStep` (`PLAN` → `RESEARCH` → `IMPLEMENT`) alongside status.\n\n### Narrate progress\n\nPost an `add_comment` roughly **every 30 minutes of active work**, or at any meaningful event — files changed, a decision made, a blocker hit, a test suite going green. The board must never go quiet while work is happening. Lead each comment with its type so histories stay scannable:\n\n| Type | Trigger | Must contain |\n|------|---------|--------------|\n| `checkpoint` | Any status change | New status · why · what's next |\n| `progress` | ~30 min / meaningful change | Done since last · in progress · next · remaining |\n| `decision` | A non-obvious choice | Context · options · decision · consequence |\n| `blocker` | Work can't proceed | What's blocked · why · what's needed · who can unblock |\n| `handoff` | Ownership changes party | From → to · state summary · the exact ask · links |\n| `work-report` | On `IN_REVIEW` / `DONE` | AC verification table · changes · how verified · PR |\n| `question` | Input needed, non-blocking | The question · why it matters · your default if no reply |\n\nFrom the CLI: `taskpod comment AF-102 -t progress \"...\"`.\n\n### Blocked? Hand off — never stall, never guess\n\nWhen you hit a decision, a missing secret, or a judgment call only a human can make:\n\n1. Call `handoff_to_human({ taskId, needs })` — it moves the task to `WAITING_INPUT` with the human as owner — or checkpoint to `WAITING_APPROVAL` when a plan needs sign-off.\n2. The comment states the **precise ask** and **your default if no reply** (so silence still has a defined outcome).\n3. Acknowledge every inbound handoff with a comment before you start on it.\n\nA work-report checkpoint, the shape reviewers expect on `IN_REVIEW`/`DONE`:\n\n```markdown\n**[IN_REVIEW]** AF-102 complete.\n\n| Acceptance criterion | Status | Evidence |\n| --- | --- | --- |\n| Silent refresh before expiry | ✅ | `refresh()` + test `refreshes-before-expiry` |\n| Failing refresh logs the user out | ✅ | test `logout-on-refresh-fail` |\n\n**Changes:** `lib/api-auth.ts`, `__tests__/auth.test.ts`.\n**How verified:** `npm test` green (3 new), manual expiry simulation.\n**PR:** #214 (CI green).\n```\n\n### Reference tickets everywhere\n\nWrite ticket keys as `[KEY-123]` in commit messages, PR titles/descriptions, and comments (e.g. `fix: token refresh race [AF-102]`). This is what lets the board, the repo, and the humans cross-reference your work.\n\n## 3. Session end & on discovery — write back to the central mind\n\nThis is what makes Taskpod more than a task tracker. Everything you learned that isn't already written down **dies with your context window unless you record it**.\n\n### Record learnings the moment you discover them\n\nWhenever you discover something non-obvious — and again in a sweep before you end the session — call:\n\n```\nrecord_learning({\n  projectId: \"<id>\",\n  kind: \"gotcha\",          // learning | decision | convention | gotcha\n  title: \"Tailwind v4 classes unreliable under Turbopack\",\n  content: \"Layout-critical CSS must use inline style props; Tailwind utility classes intermittently drop under Turbopack dev builds. Bit AF-088 and AF-094.\"\n})\n```\n\n| Kind | Record when you… | Example title |\n|------|------------------|---------------|\n| `learning` | Discovered something non-obvious about the system or domain | \"Webhook retries are at-least-once — handlers must be idempotent\" |\n| `decision` | Made a choice with real alternatives | \"Chose file-based token storage over OS keychain\" |\n| `convention` | Found (or set) a pattern all future work must repeat | \"Every API route uses the dual-auth pattern from lib/api-auth.ts\" |\n| `gotcha` | Lost time to a trap the next agent would also hit | \"prisma db push required after schema change or dev server 500s\" |\n\n**Rules for a good learning:**\n\n- **One insight per entry.** Never batch three discoveries into one record.\n- **Titled and concise.** A short imperative title; content is the what + why-it-matters in a few lines. Not an essay, not a diff.\n- **Novel only.** Never record what the repo (README, CLAUDE.md, code comments) or the board (task descriptions, existing learnings) already says. Check the digest's recent learnings first — duplicates poison the digest.\n- **Actionable for a stranger.** Write for the next agent with zero context: name files, commands, and error messages.\n\n### Then sync again\n\nEnd every session with:\n\n1. **Board truth check** — every task you touched is in its true status with a checkpoint; anything mid-flight has a fresh `progress` comment. Never leave a task `IN_PROGRESS` and silent.\n2. **Learning sweep** — anything non-obvious from this session recorded via `record_learning` (one entry each).\n3. **`sync_context` again** (or `taskpod sync`, which pushes learnings up and pulls the fresh digest down). This confirms your write-back landed and hands the next agent — or the same developer's other agent, already running — the updated digest.\n\n> This loop is the point: N developers × N agents, one memory. What one agent learns at 10:04, another inherits at 10:05.\n\n---\n\n## Status lifecycle\n\n```\nBACKLOG → TODO → IN_PROGRESS → IN_REVIEW → DONE\n                      │              │\n                      └── CANCELLED ─┘\n```\n\n| Status | Meaning |\n|--------|---------|\n| `BACKLOG` | Created, not yet planned (AI-staged plans wait here) |\n| `TODO` | Planned, dependencies met, ready to start |\n| `IN_PROGRESS` | Actively being worked — must never go comment-silent |\n| `IN_REVIEW` | Delivered, awaiting human review (agents finish here, with a work report) |\n| `DONE` | All acceptance + exit criteria verified in the checkpoint |\n| `CANCELLED` | Descoped — the checkpoint says why |\n| `WAITING_APPROVAL` | Parked on a human decision (plans, agent asks) |\n| `WAITING_INPUT` | Handed back to a human; the ask + your default are in the comment |\n| `GRADING` | Agent-plane verification of finished work (set by the orchestrator, not by hand) |\n\nWhen completing a task unblocks others, checkpoint each newly unblocked task to `TODO` with a comment naming what unblocked it.\n\n## Creating new work\n\nEvery task you create gets a full description — no title-only tasks, ever:\n\n```markdown\n## Problem Statement\n[What needs to be built and why]\n\n## Proposed Solution\n[Specific implementation approach]\n\n## Acceptance Criteria\n- [ ] [Specific, testable criterion]\n- [ ] [Specific, testable criterion]\n\n## Exit Criteria\n- [ ] Code compiles with zero errors\n- [ ] Tests written and passing\n```\n\nThen: set a priority (`URGENT`/`HIGH`/`MEDIUM`/`LOW`), wire ordering with `add_dependency` (schema blocks API blocks UI…), and checkpoint the new task to `TODO` with a creation comment. A task without acceptance criteria cannot be handed to an agent — the checklist is what makes work specifiable.\n\n---\n\n## Tool & command reference\n\nThe MCP server registers 50+ tools. These are the ones the protocol turns on:\n\n### Central-mind tools (the protocol core)\n\n| Tool | When |\n|------|------|\n| `sync_context` | **Session start and end** — returns the compact context digest (sprint, owned tasks, recent learnings, conventions) |\n| `record_learning` | **On discovery / session end** — `{ projectId, kind: learning\\|decision\\|convention\\|gotcha, title, content }` |\n| `init_workspace` | Once per repo — link it to its Taskpod project |\n| `checkpoint_task` | **Every status change** — status + mandatory why-comment, atomically |\n| `resume_task` | **Before touching any existing task** — last checkpoint, unread human comments, dependency + subtask state |\n| `get_sprint_status` | Board overview + `nextRecommended` task |\n| `handoff_to_human` | Stuck → `WAITING_INPUT` with a precise ask; use instead of stalling or guessing |\n\n### CRUD tools (the other 40+)\n\n| Area | Tools |\n|------|-------|\n| Teams & members | `get_teams`, `create_team`, `update_team`, `delete_team`, `add_team_member`, `remove_team_member`, `list_team_members`, `list_users` |\n| Projects | `create_project`, `list_projects`, `get_project_structure`, `update_project`, `delete_project`, `export_project`, `add_project_member`, `remove_project_member`, `list_project_members` |\n| Folders | `create_folder`, `list_folders`, `update_folder`, `delete_folder` |\n| Tasks | `create_task`, `get_task`, `update_task`, `delete_task`, `list_tasks`, `search_tasks`, `create_subtask`, `log_time` |\n| Collaboration | `add_comment`, `get_recent_activity`, `add_dependency`, `remove_dependency`, `add_task_watcher`, `remove_task_watcher`, `list_task_watchers` |\n| Resources | `list_project_resources`, `add_project_resource`, `remove_project_resource` |\n\n### CLI\n\n| Command | Does |\n|---------|------|\n| `taskpod init` | Repo → workspace: create/link the project from the terminal |\n| `taskpod sync` | ↓ pull the context digest into `.taskpod/` · ↑ push recorded learnings |\n| `taskpod agent-setup` | Write `.mcp.json` + a `CLAUDE.md` protocol block into the repo |\n| `taskpod status` | Sprint status for the linked project |\n| `taskpod mine` | Your tasks — status, ETA, blockers |\n| `taskpod show AF-102` | Full task detail with comments |\n| `taskpod start AF-102` | Checkpoint to `IN_PROGRESS` |\n| `taskpod done AF-102` | Checkpoint to `DONE` (prompts for the work report) |\n| `taskpod comment AF-102 -t <type>` | Typed comment (see the taxonomy above) |\n| `taskpod handoff AF-102` | Hand ownership to a human or agent |\n| `taskpod pull` | Refresh the `.taskpod/` context bundle only |\n| `taskpod login` | Store your token (then `--api-key` is optional everywhere) |\n| `taskpod mcp` | Run the MCP server on stdio |\n\nIn a linked repo, read `.taskpod/` as normal repo context: `context.md` (project overview), `board.json` (every task), `mine.md` (your tasks), `deps.md` (what blocks what), `resources.md` (repos, docs, consoles), `SKILL.md` (this protocol).\n\n---\n\n## Never do\n\n- **Never** change a task's status without a checkpoint comment.\n- **Never** start work without `sync_context` — or on an existing task, without `resume_task`.\n- **Never** ignore unread user comments; address them before new work.\n- **Never** mark `DONE` without verifying every acceptance criterion, with evidence, in the checkpoint.\n- **Never** record a learning the repo or board already documents — check the digest first.\n- **Never** batch multiple insights into one `record_learning` entry.\n- **Never** leave a task `IN_PROGRESS` and silent at session end — checkpoint it or post a `progress` comment.\n- **Never** guess through a blocker — `handoff_to_human` with a precise ask and your default.\n- **Never** create a task without a description, acceptance criteria, and a priority.\n- **Never** end a session without the learning sweep + final `sync_context`.\n\n## Loading this skill\n\nGive your AI tool this prompt (works with MCP configured, or over plain REST with https://taskpod.in/api-docs):\n\n```\nRead https://taskpod.in/skill and follow it for all work. Taskpod is the\nteam's central mind. Non-negotiable: call sync_context at session start and\ningest the digest before any work; resume_task before touching any existing\ntask; checkpoint_task for EVERY status change; record_learning for every\nnon-obvious decision, convention, or gotcha you discover (one per entry,\nnever duplicating what's already recorded); and sync_context again before\nyou stop. API key: <your tp_live_... token>.\n```\n";

dist/server.js

@@ -27,3 +27,3 @@ /**
 export const SERVER_NAME = "taskpod";
-export const SERVER_VERSION = "0.4.1";
+export const SERVER_VERSION = "0.4.2";
 export const allTools = [
@@ -30,0 +30,0 @@ ...teamTools,

package.json

 {
   "name": "taskpod",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "The Taskpod developer CLI and MCP server — sync project context to your machine and AI, and manage teams, projects, and tasks from any MCP client.",
@@ -5,0 +5,0 @@ "type": "module",

New alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

536486

0.03%

Worsened metrics

Lines of code

4796

-0.17%

No dependency changes