taskchef 1.0.1 → 2.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "taskchef",
+  "version": "2.0.0",
+  "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
+  "author": {
+    "name": "Favo Yang",
+    "url": "https://github.com/favoyang"
+  },
+  "homepage": "https://github.com/favoyang/taskchef#readme",
+  "repository": "https://github.com/favoyang/taskchef",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "delegation",
+    "dispatcher",
+    "tasks"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "TaskChef",
+    "shortDescription": "Dispatch work to the right Codex project task.",
+    "longDescription": "Create a data-only dispatcher workspace, route actionable requests to independently openable Codex project tasks, and reconcile saved task states on demand.",
+    "developerName": "Favo Yang",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/favoyang/taskchef",
+    "defaultPrompt": [
+      "$taskchef-bootstrap Set up TaskChef in this folder.",
+      "$taskchef-delegate Dispatch this request to the right project.",
+      "$taskchef-reconcile Fix outdated TaskChef task states."
+    ],
+    "brandColor": "#D97706"
+  }
+}

package/BACKLOG.md

@@ -17,14 +17,35 @@ This document contains capabilities intentionally excluded from the v1 MVP.
 
 ## Reconciliation and continuity
 
-- Add event-driven, scheduled, or background reconciliation only if interactive
-  reconciliation proves insufficient.
+- Prototype one standalone Codex Scheduled Task per dispatcher workspace. Run
+  it in the local project, not an isolated worktree, so updates reach the
+  canonical `tasks/*/task.json` records. Default to every 15 minutes and let the
+  user choose another cadence when enabling it.
+- Use a durable prompt that explicitly invokes `$taskchef-reconcile`, names the
+  dispatcher workspace, processes every candidate in sequential batches of at
+  most eight thread snapshots, and reports only changed, blocked, finished, or
+  failed records. An unchanged run produces one concise no-change result.
+- Add an atomic per-workspace reconciliation lease before enabling schedules.
+  One run acquires it, releases it on completion, and skips when another run
+  holds it. Treat a lease older than 30 minutes as stale and report its recovery.
+- Do not retry failed snapshots within the same run. Report the affected task
+  IDs and let the next scheduled run retry them.
+- Keep the scheduled task active when there are no candidates so later
+  delegations are discovered without re-enabling it. Only the user pauses or
+  deletes the schedule. Test the durable prompt manually before enabling it.
+- Keep scheduled reconciliation opt-in. Ordinary delegation must not wait for
+  or invoke `$taskchef-reconcile`; users can request it explicitly to refresh
+  outdated states.
 - Evaluate heartbeat behavior, restart recovery, and recovery after the
   dispatcher task is deleted.
 - Add a reconciliation cursor only when repeated full snapshots become costly
   or incorrect.
 - Determine whether thread status alone is sufficient after Codex or machine
   restarts.
+- Decide whether `$taskchef-bootstrap` should be renamed to
+  `$taskchef-workspace` or split into setup and project-management skills.
+  Until then, keep project listing and configuration in `$taskchef-bootstrap`
+  rather than mixing workspace administration into delegation.
 
 ## Grouping and history
 
@@ -63,5 +84,5 @@ This document contains capabilities intentionally excluded from the v1 MVP.
 
 - Add GitHub automation beyond storing PR and issue URLs.
 - Evaluate automatic project discovery instead of an explicit configured list.
-- Consider npm registry publication only after the GitHub-source installation
-  and local managed-checkout workflows are stable.
+- Evaluate marketplace discovery and update automation after the shared plugin
+  catalog has real usage.

package/README.md

@@ -11,33 +11,52 @@ The canonical contract is [SPEC.md](SPEC.md). Deferred ideas are in
 
 TaskChef requires Node.js 18 or newer and Git.
 
-Install the CLI and its bundled skills from npm:
+Add the shared Favo Yang plugin marketplace, then install TaskChef:
 
 ```sh
-npm install --global taskchef
+codex plugin marketplace add favoyang/codex-plugins
+codex plugin add taskchef@favoyang-plugins
 ```
 
-Then initialize a dispatcher workspace. Initialization links the three bundled
-TaskChef skills into that workspace; no separate skill installation is needed.
+Open or create the folder that will hold TaskChef's dispatcher data, start a
+new Codex task there, and ask:
+
+```text
+$taskchef-bootstrap Set up TaskChef in this folder and help me choose projects.
+```
+
+The plugin provides all three TaskChef skills and its deterministic CLI runtime;
+dispatcher workspaces do not install or link skills themselves.
+
+For headless CLI use, install the npm package with
+`npm install --global taskchef`. Contributors can run `node bin/taskchef.js`
+directly from a source checkout.
+
+## Updating
+
+Refresh the marketplace and reinstall TaskChef:
 
 ```sh
-taskchef workspace init --workspace <workspace>
-taskchef doctor --workspace <workspace>
+codex plugin marketplace upgrade favoyang-plugins
+codex plugin add taskchef@favoyang-plugins
 ```
 
-Contributors working from a source checkout can run `node bin/taskchef.js`
-directly; this managed skills workspace installs the checkout CLI and skills
-with symlinks. To install an unreleased revision, use
-`npm install --global github:favoyang/taskchef`.
+Start a new Codex task to load the updated skills.
+
+### Migrating from 1.x
+
+TaskChef 2.x moves skill ownership from dispatcher-workspace symlinks to the
+installed plugin. Run `$taskchef-bootstrap` once in an existing workspace to
+remove the three legacy TaskChef links; unrelated `.agents` content is
+preserved. The deprecated `ensureWorkspaceSkills()` export remains available
+for compatibility but reports plugin-provided skills instead of creating
+workspace links.
 
 ## Workspace
 
 ```text
 AGENTS.md
 taskchef.json
-.agents/skills/taskchef-bootstrap -> <source>/skills/taskchef-bootstrap
-.agents/skills/taskchef-delegate -> <source>/skills/taskchef-delegate
-.agents/skills/taskchef-reconcile -> <source>/skills/taskchef-reconcile
 tasks/<task-id>/task.json
 ```
 
@@ -49,7 +68,9 @@ taskchef doctor --workspace <workspace>
 ```
 
 Initialization is idempotent. It creates an empty configuration when missing
-and preserves existing configured projects.
+and preserves existing configured projects. When upgrading from the earlier
+workspace-linked distribution, initialization removes the three legacy
+TaskChef skill symlinks and preserves unrelated `.agents` content.
 
 ## Projects
 
@@ -106,6 +127,9 @@ taskchef task reconcile-candidates --json --workspace <workspace>
 thread IDs. Pass `--include-finished` only for an explicit full refresh or when
 a finished executor is known to have received new work.
 
+Delegation does not reconcile task states first. Ask the dispatcher to refresh
+or fix outdated task states when you want it to run `$taskchef-reconcile`.
+
 ## Complete CLI
 
 ```text
@@ -142,15 +166,22 @@ feat!: change the workspace data contract
 
 Publishing uses npm trusted publishing from `.github/workflows/release.yml`.
 The workflow runs the test suite, validates the npm tarball, publishes the
-calculated version, creates the GitHub release, and commits the updated
-`package.json` version back to `main`.
+calculated version after synchronizing the plugin manifest, creates the GitHub
+release, commits the synchronized version files back to `main`, and pins the TaskChef entry
+in `favoyang/codex-plugins` to that exact npm version.
+
+The release job requires an Actions secret named `MARKETPLACE_DEPLOY_KEY`.
+Store the private half of a dedicated SSH deploy key there, and add its public
+half to `favoyang/codex-plugins` with write access. The key must be scoped only
+to that catalog repository; the workflow's repository-scoped `GITHUB_TOKEN`
+cannot update another repository.
 
 ## Development
 
 ```sh
 npm test
 npm pack --dry-run
-npx -y -p semantic-release@25 -p @semantic-release/git semantic-release --dry-run
+npx -y -p semantic-release@25 -p @semantic-release/exec -p @semantic-release/git semantic-release --dry-run
 ```
 
 ## Boundaries

package/SPEC.md

@@ -21,10 +21,11 @@ TaskChef is not an agent runtime, scheduler, or background service.
 6. TaskChef records the returned `threadId`, changes the status to `running`,
    and returns immediately without waiting.
 7. The user may open and prompt any delegated task directly.
-8. The next user prompt in the dispatcher triggers one bounded reconciliation
-   of active `running` and `blocked` threads.
+8. When the user asks to refresh or fix outdated task states, TaskChef performs
+   one bounded reconciliation of active `running` and `blocked` threads.
 9. Reconciliation updates each task's current status and result, then returns
-   control without waiting for future activity.
+   control without waiting for future activity. Ordinary delegation does not
+   trigger reconciliation first.
 
 Multiple ongoing tasks may target the same project.
 
@@ -34,11 +35,6 @@ Multiple ongoing tasks may target the same project.
 taskchef-workspace/
 ├── AGENTS.md
 ├── taskchef.json
-├── .agents/
-│   └── skills/
-│       ├── taskchef-bootstrap -> <TaskChef bootstrap skill>
-│       ├── taskchef-delegate -> <TaskChef delegate skill>
-│       └── taskchef-reconcile -> <TaskChef reconciliation skill>
 └── tasks/
     └── <task-id>/
         └── task.json
@@ -51,21 +47,24 @@ implementation utilities remain in the source repository.
 ## Dispatcher instructions
 
 TaskChef owns a marked block in the workspace `AGENTS.md`. The block tells
-Codex to use `taskchef-bootstrap` for workspace setup and repair, use
-`taskchef-reconcile` once for active work, then use
-`taskchef-delegate` for actionable requests without completing delegated work
-in the dispatcher thread.
+Codex to use `$taskchef-bootstrap` for workspace setup and administration and
+`$taskchef-delegate` for actionable requests without completing delegated work
+in the dispatcher thread. The final instruction reserves `$taskchef-reconcile`
+for user-requested refreshes or repairs of outdated task states.
 
 `workspace init` copies the canonical file when `AGENTS.md` does not exist. When it
 does exist, bootstrap preserves unrelated user content and adds or refreshes
 only the TaskChef managed block. Repeating the merge is idempotent. Malformed
 or duplicate TaskChef markers fail safely instead of overwriting the file.
-Initialization also installs all three TaskChef skill links. It is idempotent,
-takes no configuration input, creates `{ "schemaVersion": 1, "projects": [] }`
-when configuration is missing, and preserves existing configured projects.
+The installed TaskChef plugin provides all three skills outside the dispatcher
+workspace. Initialization is idempotent, takes no configuration input, creates
+`{ "schemaVersion": 1, "projects": [] }` when configuration is missing, and
+preserves existing configured projects. It removes only the three legacy
+TaskChef skill symlinks from earlier workspaces and preserves unrelated
+`.agents` content.
 
-`doctor` diagnoses configuration, task storage, managed instructions, skill
-links, project paths, and task records without modifying the workspace.
+`doctor` diagnoses configuration, task storage, managed instructions, project
+paths, and task records without modifying the workspace.
 
 ## Configuration
 
@@ -242,7 +241,8 @@ TaskChef does not wait for delegated tasks to finish.
 
 ## Reconciliation workflow
 
-The next user prompt in the dispatcher triggers reconciliation:
+When the user asks to refresh or fix outdated task states, TaskChef uses
+`$taskchef-reconcile` to perform one bounded pass:
 
 1. use `task reconcile-candidates --json` to load only `running` and `blocked`
    task records with executor thread IDs;
@@ -253,8 +253,8 @@ The next user prompt in the dispatcher triggers reconciliation:
 
 The native Codex thread is the live source of truth between reconciliations.
 `task.json` is only the latest reconciled snapshot. It may still say `running`
-after the executor has finished and before the user next prompts the
-dispatcher.
+after the executor has finished and until the user explicitly requests a
+reconciliation pass.
 
 Reconciliation must be safe to repeat. TaskChef has no reconciliation timestamp,
 event cursor, event log, callback, or automatic workspace update.
@@ -283,8 +283,9 @@ TaskChef is local, interactive, task-focused, and asynchronous. It does not incl
 - one-active-task-per-project restrictions;
 - transcript or hidden-reasoning collection;
 - arbitrary Codex task discovery;
-- npm registry publication; the supported distribution is a GitHub-source
-  global install or a managed source checkout.
+- bundled development-only runtimes in dispatcher workspaces. The Codex plugin
+  marketplace distributes the three skills, and the npm package provides the
+  supported headless CLI.
 
 See `BACKLOG.md` for deferred capabilities and experiments.
 
@@ -300,11 +301,11 @@ The MVP is successful when:
 4. Both `threadId` values are recorded.
 5. The dispatcher returns without waiting for execution.
 6. The user can open and prompt either delegated task directly.
-7. The next dispatcher prompt reconciles each active thread once without
-   reading finished executor threads.
+7. A user request to refresh outdated states reconciles each active thread once
+   without reading finished executor threads; ordinary delegation does not.
 8. Status and result snapshots are updated correctly.
 9. Two ongoing tasks may target the same project without data collisions.
-10. The workspace contains dispatcher instructions, configuration, task
-    records, and the three TaskChef skill links.
+10. The workspace contains only dispatcher instructions, configuration, and
+    task records; the installed plugin owns the TaskChef skills.
 11. Bootstrap creates or idempotently merges the TaskChef-managed `AGENTS.md`
     block without overwriting unrelated instructions.

package/assets/{AGENTS.md.template → taskchef-dispatcher-instructions.md}

@@ -3,16 +3,16 @@
 
 This repository is a TaskChef dispatcher workspace.
 
-- Use `taskchef-bootstrap` when initializing or refreshing this workspace,
+- Use `$taskchef-bootstrap` when initializing or refreshing this workspace,
   changing or listing its configured projects, running TaskChef doctor,
-  repairing its managed instructions, or upgrading its TaskChef skill links.
-- For every ordinary user prompt, use `taskchef-reconcile` first to refresh
-  active recorded work once.
-- For every actionable work request, then use `taskchef-delegate`
+  or repairing its managed instructions.
+- For every actionable work request, use `$taskchef-delegate`
   automatically, even when the user does not explicitly say "delegate" or
   mention TaskChef.
 - Do not perform delegated work directly in the dispatcher thread.
-- Return immediately after dispatch, as required by `taskchef-delegate`.
+- Return immediately after dispatch, as required by `$taskchef-delegate`.
 - Answer directly only when the user explicitly asks about TaskChef itself or
   explicitly says not to delegate.
+- Use `$taskchef-reconcile` only when the user asks to refresh or fix outdated
+  TaskChef task states.
 <!-- taskchef:dispatcher-instructions:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -18,6 +18,7 @@
     "taskchef": "bin/taskchef.js"
   },
   "files": [
+    ".codex-plugin",
     "assets",
     "BACKLOG.md",
     "bin",
@@ -31,6 +32,9 @@
   "engines": {
     "node": ">=18"
   },
+  "devDependencies": {
+    "yaml": "^2.9.0"
+  },
   "scripts": {
     "test": "node --test tests/taskchef.test.js"
   }

package/skills/taskchef-bootstrap/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: taskchef-bootstrap
-description: "Initialize, diagnose, or refresh TaskChef dispatcher workspaces, project configuration, managed AGENTS.md instructions, and TaskChef skill links. Use when creating a TaskChef workspace, adding, importing, listing, or removing configured projects, running TaskChef doctor, repairing dispatcher setup, or upgrading installed TaskChef skills. Do not dispatch user work or reconcile executor threads."
+description: "Initialize, diagnose, or refresh TaskChef dispatcher workspaces, project configuration, and managed AGENTS.md instructions. Use when creating a TaskChef workspace, adding, importing, listing, or removing configured projects, running TaskChef doctor, or repairing dispatcher setup. Do not dispatch user work or reconcile executor threads."
 ---
 
 # TaskChef Bootstrap
 
 Initialize or refresh a data-only TaskChef dispatcher workspace.
 
-Resolve this linked skill with `realpath`. The TaskChef source root is two
-parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
+Resolve this skill directory with `realpath`. The TaskChef plugin root is two
+parents above the skill directory. Invoke `<plugin-root>/bin/taskchef.js` for
 all deterministic workspace operations.
 
 ## Boundaries
 
 - Keep implementation, tests, and reports in the TaskChef source repository.
-- Keep only `AGENTS.md`, `taskchef.json`, `tasks/*/task.json`, and the three
-  TaskChef skill links in a dispatcher workspace.
+- Keep only `AGENTS.md`, `taskchef.json`, and `tasks/*/task.json` in a
+  dispatcher workspace.
 - Do not dispatch tasks or reconcile executor threads during bootstrap unless
   the user separately requests those actions.
 - Never use collaboration agents, hooks, schedules, polling, or daemons.
@@ -24,7 +24,8 @@ all deterministic workspace operations.
 
 1. Run `workspace init --json`. It takes no stdin, creates an empty
    configuration when missing, and idempotently creates or refreshes the task
-   directory, managed instructions, and all three skill links.
+   directory and managed instructions. The installed plugin provides all three
+   TaskChef skills outside the dispatcher workspace.
 2. Run `doctor --json` after setup or when the user asks to diagnose the
    workspace. Doctor is read-only; rerun `workspace init --json` to repair the
    managed scaffold.

package/skills/taskchef-delegate/SKILL.md

@@ -1,22 +1,21 @@
 ---
 name: taskchef-delegate
-description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, splitting work across projects, or retrying pending executor creation. Dispatch must return immediately and must never use subagents, hooks, schedules, or foreground waiting. Use taskchef-bootstrap instead for workspace setup or configuration changes."
+description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, splitting work across projects, or retrying pending executor creation. Dispatch must return immediately and must never use subagents, hooks, schedules, or foreground waiting."
 ---
 
 # TaskChef Delegate
 
 Create real Codex tasks from a TaskChef data workspace and return immediately.
-Use `taskchef-reconcile` first when the current prompt has active recorded tasks.
 
-Resolve this linked skill with `realpath`. The TaskChef source root is two
-parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
-all deterministic workspace and task-record operations.
+Resolve this skill directory with `realpath`. The TaskChef plugin root is two
+parents above the skill directory. Use the TaskChef executable under that root
+for all deterministic workspace and task-record operations.
 
 ## Boundaries
 
 - Keep implementation, tests, and reports in the TaskChef source repository.
-- Keep only `AGENTS.md`, `taskchef.json`, `tasks/*/task.json`, and the three
-  TaskChef skill links in a dispatcher workspace.
+- Keep only `AGENTS.md`, `taskchef.json`, and `tasks/*/task.json` in a
+  dispatcher workspace.
 - Use real Codex tasks, never collaboration or subagent tools.
 - Never use hooks, callbacks, schedules, polling, daemons, or event logs.
 - Never wait for delegated work after executor creation.
@@ -24,20 +23,28 @@ all deterministic workspace and task-record operations.
 
 ## Dispatch
 
-1. Run `project list --json` to load and validate the configured routing
-   targets. Use `taskchef-bootstrap` if the workspace is missing or unhealthy.
+1. Run
+   `<plugin-root>/bin/taskchef.js project list --json --workspace <workspace>`
+   to load and validate the configured routing targets. Use
+   `$taskchef-bootstrap` if the workspace is missing or unhealthy.
 2. Split the request into the smallest independently useful outcomes. Include
    constraints, expected testing, and reporting in every instruction.
 3. Classify against configured `name`, `githubRepo`, and `description`. Use
    `path` only as checkout identity. Ask when metadata does not produce one
    clear project match.
 4. Resolve native projects once and require the exact configured path.
-5. Reuse a matching pending record for an explicit retry; otherwise create one
-   pending record before executor creation.
+5. For an explicit retry, require the exact task ID and run
+   `<plugin-root>/bin/taskchef.js task show <task-id> --json --workspace <workspace>`.
+   Reuse the record only when its status is `pending`; ask for the task ID when
+   it is missing and reject retries of non-pending records. For new work, run
+   `<plugin-root>/bin/taskchef.js task create --json --workspace <workspace>`
+   with the task record JSON on stdin before executor creation.
 6. Create one real Codex task per record using the exact saved project and a
    local environment on its executor host.
-7. Immediately record every returned `threadId` with status `running`. Never
-   persist `hostId`.
+7. Immediately run
+   `<plugin-root>/bin/taskchef.js task update <task-id> --json --workspace <workspace>`
+   with the `running` status and returned `threadId` on stdin. Never persist
+   `hostId`.
 8. Leave a failed creation pending. Do not invent an ID or delete the record.
 9. Return immediately with a created-thread directive for every success. Do
    not read or wait for a newly created executor.

package/skills/taskchef-reconcile/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: taskchef-reconcile
-description: "Reconcile active TaskChef task records with their visible Codex executor threads. Use at the start of ordinary prompts in a TaskChef workspace, for TaskChef status or progress requests, after delegated work may have completed or blocked, or for an explicitly requested full refresh. Performs one bounded snapshot pass and never polls or waits for future activity."
+description: "Reconcile active TaskChef task records with their visible Codex executor threads. Use only when the user asks to refresh, fix, or repair outdated TaskChef task states. Performs one bounded snapshot pass and never polls or waits for future activity."
 ---
 
 # TaskChef Reconcile
 
 Refresh TaskChef's recorded task state from native Codex threads exactly once.
 
-Resolve this linked skill with `realpath`. The TaskChef source root is two
-parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
+Resolve this skill directory with `realpath`. The TaskChef plugin root is two
+parents above the skill directory. Invoke `<plugin-root>/bin/taskchef.js` for
 all deterministic record operations.
 
 ## Reconcile

package/src/cli.js

@@ -107,7 +107,7 @@ async function initialize(args) {
     `Workspace: ${value.workspace}`,
     `Configuration: ${value.config.action}`,
     `Instructions: ${value.instructions.action}`,
-    `Skills: ${value.skills.skills.map((skill) => `${skill.name}=${skill.action}`).join(", ")}`,
+    `Legacy skill links removed: ${value.legacySkills.removed.length}`,
   ].join("\n"));
   return 0;
 }

package/src/workspace.js

@@ -4,13 +4,12 @@ import {
   lstat,
   mkdir,
   readFile,
-  readlink,
   readdir,
   realpath,
   link,
   rename,
+  rmdir,
   stat,
-  symlink,
   unlink,
   writeFile,
 } from "node:fs/promises";
@@ -20,7 +19,10 @@ import path from "node:path";
 import { promisify } from "node:util";
 
 const execFile = promisify(execFileCallback);
-const DISPATCHER_INSTRUCTIONS_URL = new URL("../assets/AGENTS.md.template", import.meta.url);
+const DISPATCHER_INSTRUCTIONS_URL = new URL(
+  "../assets/taskchef-dispatcher-instructions.md",
+  import.meta.url,
+);
 const DISPATCHER_INSTRUCTIONS_START = "<!-- taskchef:dispatcher-instructions:start -->";
 const DISPATCHER_INSTRUCTIONS_END = "<!-- taskchef:dispatcher-instructions:end -->";
 const TASKCHEF_SKILL_NAMES = [
@@ -241,38 +243,73 @@ export async function ensureWorkspaceInstructions(workspaceRoot) {
   return { path: filePath, action };
 }
 
-async function ensureSkillLink(skillsDirectory, skillName) {
-  const source = path.join(SKILLS_SOURCE_ROOT, skillName);
-  const destination = path.join(skillsDirectory, skillName);
-  await canonicalDirectory(source);
-  const details = await lstat(destination).catch((error) => {
+async function findLegacySkillLinks(workspaceRoot) {
+  const agentsDirectory = path.join(workspaceRoot, ".agents");
+  const agentsDetails = await lstat(agentsDirectory).catch((error) => {
     if (error.code === "ENOENT") return null;
     throw error;
   });
-  if (details === null) {
-    await symlink(source, destination, "dir");
-    return { name: skillName, path: destination, action: "created" };
+  if (agentsDetails === null) return { agentsDirectory: null, skillsDirectory: null, links: [] };
+  if (agentsDetails.isSymbolicLink() || !agentsDetails.isDirectory()) {
+    return { agentsDirectory: null, skillsDirectory: null, links: [] };
   }
-  if (!details.isSymbolicLink()) {
-    throw new Error(`TaskChef skill path exists and is not a symlink: ${destination}`);
+
+  const skillsDirectory = path.join(agentsDirectory, "skills");
+  const skillsDetails = await lstat(skillsDirectory).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (skillsDetails === null) return { agentsDirectory, skillsDirectory, links: [] };
+  if (skillsDetails.isSymbolicLink() || !skillsDetails.isDirectory()) {
+    return { agentsDirectory, skillsDirectory: null, links: [] };
+  }
+
+  const links = [];
+  for (const skillName of TASKCHEF_SKILL_NAMES) {
+    const skillPath = path.join(skillsDirectory, skillName);
+    const details = await lstat(skillPath).catch((error) => {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    });
+    if (details === null) continue;
+    if (!details.isSymbolicLink()) {
+      throw new Error(`legacy TaskChef skill path is not a symlink: ${skillPath}`);
+    }
+    links.push({ name: skillName, path: skillPath });
+  }
+  return { agentsDirectory, skillsDirectory, links };
+}
+
+async function removeLegacySkillLinks(workspaceRoot) {
+  const legacy = await findLegacySkillLinks(workspaceRoot);
+  for (const link of legacy.links) await unlink(link.path);
+  const removedDirectories = [];
+  if (legacy.skillsDirectory && (await readdir(legacy.skillsDirectory)).length === 0) {
+    await rmdir(legacy.skillsDirectory);
+    removedDirectories.push(legacy.skillsDirectory);
   }
-  const linked = path.resolve(path.dirname(destination), await readlink(destination));
-  if (linked !== source) {
-    await unlink(destination);
-    await symlink(source, destination, "dir");
-    return { name: skillName, path: destination, action: "updated" };
+  if (legacy.agentsDirectory && (await readdir(legacy.agentsDirectory).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }))?.length === 0) {
+    await rmdir(legacy.agentsDirectory);
+    removedDirectories.push(legacy.agentsDirectory);
   }
-  return { name: skillName, path: destination, action: "unchanged" };
+  return { removed: legacy.links, removedDirectories };
 }
 
 export async function ensureWorkspaceSkills(workspaceRoot) {
   const root = await realpath(path.resolve(workspaceRoot));
-  const skillsDirectory = await ensureManagedDirectory(root, ".agents", "skills");
-  const skills = [];
-  for (const skillName of TASKCHEF_SKILL_NAMES) {
-    skills.push(await ensureSkillLink(skillsDirectory, skillName));
-  }
-  return { directory: skillsDirectory, skills };
+  const legacySkills = await removeLegacySkillLinks(root);
+  return {
+    directory: null,
+    skills: TASKCHEF_SKILL_NAMES.map((name) => ({
+      name,
+      path: path.join(SKILLS_SOURCE_ROOT, name),
+      action: "provided-by-plugin",
+    })),
+    legacySkills,
+  };
 }
 
 export async function canonicalGitRoot(projectPath) {
@@ -482,6 +519,7 @@ export async function initializeWorkspace(workspaceRoot) {
   const requestedRoot = path.resolve(workspaceRoot);
   await mkdir(requestedRoot, { recursive: true });
   const root = await realpath(requestedRoot);
+  const { legacySkills } = await ensureWorkspaceSkills(root);
   await ensureManagedDirectory(root, "tasks");
   const configPath = path.join(root, "taskchef.json");
   const configExists = await managedRegularFileExists(configPath);
@@ -493,16 +531,12 @@ export async function initializeWorkspace(workspaceRoot) {
     if (!configExists) await unlink(configPath).catch(() => {});
     throw error;
   });
-  const skills = await ensureWorkspaceSkills(root).catch(async (error) => {
-    if (!configExists) await unlink(configPath).catch(() => {});
-    throw error;
-  });
   return {
     workspace: root,
     config: { path: configPath, action: configExists ? "unchanged" : "created", value: config },
     tasks: { path: path.join(root, "tasks"), action: "ready" },
     instructions,
-    skills,
+    legacySkills,
   };
 }
 
@@ -831,18 +865,13 @@ export async function doctorWorkspace(workspaceRoot) {
     }
     return "managed AGENTS.md instructions current";
   });
-  for (const skillName of TASKCHEF_SKILL_NAMES) {
-    await check(`skill:${skillName}`, async () => {
-      const destination = path.join(root, ".agents", "skills", skillName);
-      const details = await lstat(destination);
-      if (!details.isSymbolicLink()) throw new Error("skill path is not a symlink");
-      const linked = path.resolve(path.dirname(destination), await readlink(destination));
-      const expected = path.join(SKILLS_SOURCE_ROOT, skillName);
-      if (linked !== expected) throw new Error(`unexpected target: ${linked}`);
-      await canonicalDirectory(expected);
-      return "skill link valid";
-    });
-  }
+  await check("legacy-skill-links", async () => {
+    const legacy = await findLegacySkillLinks(root);
+    if (legacy.links.length > 0) {
+      throw new Error("legacy TaskChef skill links remain; run workspace init to remove them");
+    }
+    return "no legacy TaskChef skill links";
+  });
   await check("task-records", async () => {
     const taskRoot = path.join(root, "tasks");
     const entries = await readdir(taskRoot, { withFileTypes: true });