taskchef 1.0.2 → 3.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "taskchef",
+  "version": "3.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": "Route actionable requests to independently openable Codex project tasks, keep an append-only task history, and query live reports 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-report Report on work in the TaskChef task history."
+    ],
+    "brandColor": "#D97706"
+  }
+}

package/BACKLOG.md

@@ -1,88 +1,41 @@
 # TaskChef backlog
 
-This document contains capabilities intentionally excluded from the v1 MVP.
-`SPEC.md` is the canonical v1 contract.
-
-## Task activity and automatic reporting
-
-- Determine whether Codex hook `session_id` reliably maps to a recorded task
-  `threadId`.
-- Evaluate task-specific hooks without inferring ownership from project path.
-- Evaluate an explicit executor callback such as `taskchef task report`.
-- Decide how delegated tasks can safely update the data workspace across Codex
-  filesystem boundaries.
-- Add automatic finish signals only after task attribution is proven reliable.
-- Design event ordering, deduplication, cursors, and replay semantics before
-  introducing `events.jsonl`.
-
-## Reconciliation and continuity
-
-- 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
-
-- Add dispatch or run records only when batch cancellation, aggregate status,
-  replay, or decomposition history has a concrete use case.
-- Decide whether and how to retain the original broad prompt.
-- Add archival and retention policies for old task records.
-
-## V2: remote connection projects
-
-- Import remote connection projects returned by the native project-list tool.
-- Persist the native `projectId` and `hostId` needed to distinguish identical
-  paths on different hosts and route task creation.
-- Re-resolve stored native identities against the project list before every
-  dispatch instead of assuming they remain valid indefinitely.
-- Validate remote paths and Git state through native host-aware project data;
-  do not run local filesystem validation against a remote path.
-- Persist enough host context with delegated tasks to reconcile remote threads
-  reliably without arbitrary task discovery.
+`SPEC.md` is the current contract. These ideas need a concrete user case and a
+clear data model before implementation.
+
+## Task history views
+
+- Add date ranges and title search if the task log becomes difficult to
+  browse.
+- Consider export formats for personal activity reports.
+- Define archival or retention only when real logs become large enough to need
+  it.
+- Consider grouping entries created from one broad request without storing the
+  full original prompt.
+
+## Optional reports
+
+- Consider user-scheduled, read-only digests that query recorded Codex tasks
+  and publish a report without writing status or results to the TaskChef
+  workspace.
+- Define batching and partial-read behavior for large task histories.
+- Decide whether inaccessible or deleted Codex tasks need a separate report
+  category.
+
+## Remote projects
+
+- Import remote connection projects returned by native project discovery.
+- Persist the native project and host identity needed to distinguish identical
+  paths on different hosts.
+- Re-resolve remote identities before dispatch.
 - Define unavailable-host, renamed-project, moved-path, and stale-identity
-  behavior before enabling remote dispatch.
-- Evaluate worktrees and isolated execution for concurrent tasks in one
+  behavior.
+- Evaluate isolated worktrees and conflict handling for concurrent tasks in one
   project.
-- Define conflict handling when several tasks modify the same checkout.
-
-## Data model extensions
-
-- Add richer result fields only when real integrations require them.
-- Evaluate structured verification, artifacts, commits, and completion outcome
-  fields.
-- Support multiple executor threads for one logical task if needed.
-- Define schema migrations and compatibility rules after the first persisted
-  v1 records exist.
 
-## Integrations and distribution
+## Integrations
 
-- 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.
+- Add GitHub automation only when task history alone is insufficient.
+- Evaluate automatic project discovery rules and exclusions.
+- Consider multiple executor threads for one logical assignment if a real
+  workflow requires it.

package/README.md

@@ -1,115 +1,208 @@
 # TaskChef
 
-TaskChef is a non-blocking interactive dispatcher for visible Codex tasks. It
-keeps a data-only workspace, routes independent assignments to real Codex
-tasks, records their latest reconciled state, and returns control immediately.
+Bring work for all your local Codex projects to one inbox. TaskChef reads each
+request, chooses the right project, and opens a normal Codex task there. It
+keeps a task history so you can find the work later. The created Codex tasks
+remain the source of truth for progress and results.
+
+If a request contains independent work for different projects, TaskChef can
+open several tasks. It returns as soon as they are created, so you can send the
+next request or open any executor and work with it directly.
+
+## The mental model
+
+- The **dispatcher workspace** is a small folder that stores project routes and
+  task history. A Codex task opened in this folder is the
+  **dispatcher**.
+- A **configured project** is a local repository or folder where TaskChef may
+  send work.
+- An **executor** is the normal Codex task that handles delegated work inside a
+  configured project.
+- A **task entry** records what TaskChef delegated, which project it chose, and
+  the executor's Codex task ID.
 
-The canonical contract is [SPEC.md](SPEC.md). Deferred ideas are in
-[BACKLOG.md](BACKLOG.md).
+```text
+request in dispatcher
+        |
+        +-- task entry --> executor in project A
+        +-- task entry --> executor in project B
+```
 
-## Installation
+TaskChef does not copy executor results into its workspace. When you ask for a
+report, it reads the recorded task IDs, checks those Codex tasks once, and
+shows their current state without saving another snapshot.
 
-TaskChef requires Node.js 18 or newer and Git.
+## Quickstart
 
-Install the CLI and its bundled skills from npm:
+### 1. Install the plugin
+
+You need Node.js 18 or newer, Git, and local access to each target project.
+
+Add the [Favo Yang plugin marketplace](https://github.com/favoyang/codex-plugins)
+and 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.
+### 2. Create the dispatcher workspace
+
+Create a folder wherever you keep local projects:
 
 ```sh
-taskchef workspace init --workspace <workspace>
-taskchef doctor --workspace <workspace>
+mkdir -p ~/taskchef
+cd ~/taskchef
 ```
 
-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`.
+Add `~/taskchef` as a project in Codex. Start a new task in that project and
+run the bootstrap skill:
+
+```text
+$taskchef-bootstrap Set up TaskChef in this folder.
+```
 
-## Workspace
+Bootstrap creates:
 
 ```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
+tasks.jsonl
 ```
 
-Create or repair the managed scaffold without supplying configuration:
+TaskChef scans eligible local Codex projects during setup and adds them to the
+managed project list in `taskchef.json`.
 
-```sh
-taskchef workspace init --workspace <workspace>
-taskchef doctor --workspace <workspace>
+`taskchef.json` defines the available routes. A project name or GitHub pull
+request URL in your request is usually enough for TaskChef to choose the right
+project. If a project needs more context, extend its optional `description`
+field with responsibilities and keywords that distinguish it from nearby
+projects.
+
+The generated `AGENTS.md` turns ordinary requests in this project into
+delegated work. You do not need to name the delegate skill each time.
+
+### 3. Delegate the first task
+
+Suppose bootstrap found a project named `payments-api`. This prompt delegates
+one task to it:
+
+```text
+In payments-api, fix the duplicate charge shown after a payment retry, add a regression test, and report what changed.
 ```
 
-Initialization is idempotent. It creates an empty configuration when missing
-and preserves existing configured projects.
+TaskChef replies with a link to the new Codex task. Open it to follow progress
+or give the executor more instructions. The dispatcher is ready for another
+request immediately.
 
-## Projects
+## Everyday workflows
 
-Add one project. Git status, the exact Git root, and a canonical GitHub origin
-are detected automatically:
+### Route work across projects
 
-```sh
-taskchef project add /workspace/payments \
-  --name payments \
-  --description "Owns payment authorization, capture, and refunds." \
-  --workspace <workspace>
+Suppose `storefront` is another configured project and owns the customer web
+interface. These two changes do not depend on each other, so they can run in
+separate tasks:
+
+```text
+In payments-api, add structured logs for failed payment retries and test them. Separately, in storefront, fix the checkout form's keyboard focus order and run the browser tests.
 ```
 
-Import a JSON array from a file or stdin:
+TaskChef opens one executor in each project. If several changes need close
+coordination, keep them in one task instead of splitting them just because
+they touch frontend and backend code. Multiple active executors may also use
+the same project.
 
-```sh
-taskchef project import projects.json --workspace <workspace>
-taskchef project import - --workspace <workspace> < projects.json
+### Follow up on delegated work
+
+Open an executor and prompt it like any other Codex task. Its thread is the
+live source of truth for progress, questions, and results.
+
+The dispatcher workspace keeps `tasks.jsonl`, an append-only history of
+successful delegations. It records what TaskChef sent, when it sent it, which
+project it selected, and which Codex task received the work.
+
+### Ask for a live report
+
+Ask the dispatcher when you want a current overview:
+
+```text
+Report on the work TaskChef has dispatched.
 ```
 
-Import merges by canonical path. Existing names and descriptions are preserved
-when omitted. `--replace` explicitly replaces the configured project set.
+This runs `$taskchef-report`. It reads the task history, checks the relevant
+Codex tasks once, and reports their current states and outcomes. Nothing is
+written back to the log, and TaskChef does not keep polling after the report.
 
-```sh
-taskchef project list --workspace <workspace>
-taskchef project remove payments --workspace <workspace>
+### Manage configured projects
+
+Use `$taskchef-bootstrap` to scan local Codex projects and refresh the managed
+list:
+
+```text
+$taskchef-bootstrap Scan my local Codex projects and update TaskChef's managed project list.
 ```
 
-Removal refuses to orphan existing task records unless `--force` is supplied.
+The same skill can diagnose the workspace and repair configuration errors that
+it can fix safely:
 
-## Tasks
+```text
+$taskchef-bootstrap Diagnose this TaskChef workspace and fix any repairable configuration errors.
+```
 
-Task creation and update read JSON from stdin:
+Project paths must exist when you add or dispatch to them. Configure the
+repository root for a Git project. TaskChef also accepts non-Git folders. It
+detects Git status and the canonical GitHub `origin` when adding or importing
+a project.
 
-```sh
-printf '%s\n' '{"id":"t1","project":"/workspace/payments","title":"Echo input","instruction":"Create and test echo_input.py."}' |
-  taskchef task create --json --workspace <workspace>
+Removing a project does not rewrite old task entries. Each entry keeps the
+project metadata that TaskChef used when it delegated the work.
+
+## Important boundaries
+
+- TaskChef is an interactive dispatcher. It is not a scheduler, daemon, hook
+  service, or background worker.
+- Executors are visible Codex tasks. The dispatcher does not supervise them or
+  wait for them to finish.
+- TaskChef routes only to projects on the same local execution host.
+- The task history contains successful delegations, not current task status or
+  task results.
+- TaskChef does not store executor transcripts, hidden reasoning, or `hostId`.
+- A live report is a one-time read of recorded Codex tasks. TaskChef discards
+  the fetched state after presenting it.
+
+## Updating
 
-printf '%s\n' '{"status":"running","threadId":"019f..."}' |
-  taskchef task update t1 --json --workspace <workspace>
+Refresh the marketplace snapshot, then reinstall TaskChef:
+
+```sh
+codex plugin marketplace upgrade favoyang-plugins
+codex plugin add taskchef@favoyang-plugins
 ```
 
-Inspection commands:
+## CLI reference
+
+The plugin has three skills:
+
+- `$taskchef-bootstrap` initializes, diagnoses, and configures a workspace
+- `$taskchef-delegate` routes requests and creates executor tasks
+- `$taskchef-report` reads the task history and reports live executor state once
+
+The CLI underneath these skills manages workspace data. Run it once with `npx`
+if you do not want a global installation:
 
 ```sh
-taskchef task show <task-id> --workspace <workspace>
-taskchef task list --workspace <workspace>
-taskchef task list --status running --status blocked --project payments --workspace <workspace>
-taskchef task summary --workspace <workspace>
-taskchef task reconcile-candidates --json --workspace <workspace>
+npx taskchef help
 ```
 
-`task reconcile-candidates` returns only `running` and `blocked` tasks with
-thread IDs. Pass `--include-finished` only for an explicit full refresh or when
-a finished executor is known to have received new work.
+For the shorter command used below, install it globally:
 
-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`.
+```sh
+npm install --global taskchef
+```
 
-## Complete CLI
+The npm package provides the data CLI. The Codex plugin provides the skills
+that create and inspect executor tasks. From a source checkout, use
+`node bin/taskchef.js`.
 
 ```text
 taskchef help
@@ -119,45 +212,83 @@ taskchef project add <path>
 taskchef project import [<file> | -]
 taskchef project list
 taskchef project remove <name>
-taskchef task create
-taskchef task update <task-id>
+taskchef task record
 taskchef task show <task-id>
 taskchef task list
 taskchef task summary
-taskchef task reconcile-candidates
 ```
 
-All commands accept `--workspace <path>`. Add `--json` for deterministic JSON
-output used by the TaskChef skills; otherwise the CLI prints human-readable
-output.
+Workspace and data commands accept `--workspace <path>` and default to the
+current directory. Data commands accept `--json` for machine-readable output.
+Run `taskchef help` for every option.
+
+### Project administration
 
-## Release
+```sh
+taskchef workspace init --workspace <workspace>
+taskchef doctor --workspace <workspace>
 
-Releases are automated with semantic-release from the `Release` GitHub Actions
-workflow on `main`. Use Semantic Commit Messages so the release type can be
-calculated:
+taskchef project add /workspace/payments \
+  --name payments \
+  --description "Owns payment authorization, capture, and refunds." \
+  --workspace <workspace>
 
-```text
-fix: correct task reconciliation
-feat: add a new CLI command
-feat!: change the workspace data contract
+taskchef project list --workspace <workspace>
+taskchef project remove payments --workspace <workspace>
 ```
 
-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`.
+Import projects as a JSON array from a file or standard input:
 
-## Development
+```sh
+taskchef project import projects.json --workspace <workspace>
+taskchef project import - --workspace <workspace> < projects.json
+```
+
+Import merges by canonical path and preserves an existing name or description
+when the imported object omits it. `--replace` replaces the configured project
+set.
+
+### Task history
+
+`task record` reads one successful delegation from standard input. The
+`project` value is the exact configured project path:
+
+```sh
+printf '%s\n' '{"id":"t1","project":"/workspace/payments","title":"Add retry logs","instruction":"Add structured logs for failed retries and test them.","threadId":"019f..."}' |
+  taskchef task record --json --workspace <workspace>
+```
+
+Inspect the task history without querying Codex tasks:
+
+```sh
+taskchef task show t1 --workspace <workspace>
+taskchef task list --workspace <workspace>
+taskchef task list --project payments --workspace <workspace>
+taskchef task summary --workspace <workspace>
+```
+
+The complete data contract is in [SPEC.md](SPEC.md). Deferred ideas are in
+[BACKLOG.md](BACKLOG.md).
+
+## Development and release
 
 ```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
+The `Release` GitHub Actions workflow runs semantic-release on `main`.
+Semantic Commit Messages determine the release type:
+
+```text
+fix: correct task log validation
+feat: add a new CLI command
+feat!: change the workspace data contract
+```
 
-TaskChef is not an agent runtime, scheduler, hook service, or background
-worker. Delegated work runs in real Codex tasks, never subagents.
-Reconciliation is a single immediate snapshot pass and never polls or waits.
+The workflow tests the package and validates the npm tarball before publishing
+through npm trusted publishing. It synchronizes version files, creates the
+GitHub release, and pins the TaskChef entry in `favoyang/codex-plugins` to the
+published npm version. Marketplace updates use the `MARKETPLACE_DEPLOY_KEY`
+Actions secret, a write-enabled deploy key scoped to the catalog repository.