taskchef 0.0.1 → 1.0.0

package/.agents/skills/taskchef-bootstrap/SKILL.md

@@ -0,0 +1,50 @@
+---
+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."
+---
+
+# TaskChef Bootstrap
+
+Initialize or refresh a data-only TaskChef dispatcher workspace.
+
+Resolve this linked skill with `realpath`. The TaskChef source root is three
+parents above the skill directory. Invoke `<source-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.
+- 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.
+
+## Initialize and repair
+
+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.
+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.
+3. Report the actions or failed checks. End without dispatching unless the user
+   separately requested work.
+
+## Configure projects
+
+1. List native Codex projects once when discovery is necessary. Configure only
+   projects local to the TaskChef workspace's execution host. Remote connection
+   projects are outside the v1 contract.
+2. Add one project with `project add <path>`, normally supplying `--name` and a
+   curated `--description`. The CLI detects Git status, exact Git root, and a
+   canonical GitHub `origin`; use `--no-github` or `--github-repo` only to
+   override detection.
+3. Bulk import with `project import <file|-> --json`. Input is a JSON array of
+   objects containing `path` plus optional `name`, `description`, and
+   `githubRepo`. Import merges by canonical path and preserves an existing name
+   or description when omitted. Use `--replace` only when the user explicitly
+   requests replacement.
+4. Inspect configured projects with `project list --json`. Remove by name with
+   `project remove`; require explicit user intent before `--force` when task
+   records reference the project.

package/.agents/skills/taskchef-bootstrap/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Bootstrap"
+  short_description: "Bootstrap TaskChef dispatcher workspaces"
+  default_prompt: "Use $taskchef-bootstrap to initialize or refresh this TaskChef dispatcher workspace."

package/.agents/skills/taskchef-delegate/SKILL.md

@@ -0,0 +1,43 @@
+---
+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."
+---
+
+# 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 three
+parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` 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.
+- 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.
+- Never collect transcripts or hidden reasoning.
+
+## Dispatch
+
+1. Run `project list --json` 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.
+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`.
+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/.agents/skills/taskchef-delegate/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Delegate"
+  short_description: "Dispatch work into visible Codex tasks"
+  default_prompt: "Use $taskchef-delegate to route this request into independently openable Codex tasks."

package/.agents/skills/taskchef-reconcile/SKILL.md

@@ -0,0 +1,35 @@
+---
+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."
+---
+
+# 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 three
+parents above the skill directory. Invoke `<source-root>/bin/taskchef.js` for
+all deterministic record operations.
+
+## Reconcile
+
+1. Run `task reconcile-candidates --json` once. It returns only `running` and
+   `blocked` tasks with thread IDs. Do not scan pending or finished records.
+2. Query every returned thread exactly once using immediate native snapshots,
+   with no more than eight targets per call.
+3. Do not wait for future activity and do not poll.
+4. Map an active attempt to `running`, a user-input or external dependency to
+   `blocked`, and any concluded attempt to `finished`, including failed or
+   partial attempts.
+5. Preserve an existing result unless the thread provides a meaningful newer
+   report. Results contain exactly `message`, `githubPRs`, and `githubIssues`.
+6. Update each changed record once with `task update`.
+7. Report a concise snapshot and continue with the user's request. If there
+   were no candidates or changes, say so briefly.
+
+Use `task reconcile-candidates --include-finished --json` only when the user
+explicitly requests a full refresh or says a finished executor received new
+work. A finished task with a new active attempt becomes `running` again.
+
+The native thread is authoritative between reconciliations. Executor reports
+are evidence, not independently verified completion guarantees.

package/.agents/skills/taskchef-reconcile/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Reconcile"
+  short_description: "Reconcile visible TaskChef task state"
+  default_prompt: "Use $taskchef-reconcile to refresh active TaskChef task statuses and results once."

package/BACKLOG.md

@@ -0,0 +1,67 @@
+# 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
+
+- Add event-driven, scheduled, or background reconciliation only if interactive
+  reconciliation proves insufficient.
+- 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.
+
+## 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.
+- 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
+  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
+
+- 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.

package/README.md

@@ -1,7 +1,160 @@
-# taskchef
+# TaskChef
 
-A tiny placeholder package for 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.
+
+The canonical contract is [SPEC.md](SPEC.md). Deferred ideas are in
+[BACKLOG.md](BACKLOG.md).
+
+## Installation
+
+TaskChef requires Node.js 18 or newer and Git.
+
+Install the CLI and its bundled skills from npm:
+
+```sh
+npm install --global taskchef
+```
+
+Then initialize a dispatcher workspace. Initialization links the three bundled
+TaskChef skills into that workspace; no separate skill installation is needed.
 
 ```sh
-npx taskchef
+taskchef workspace init --workspace <workspace>
+taskchef doctor --workspace <workspace>
 ```
+
+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`.
+
+## Workspace
+
+```text
+AGENTS.md
+taskchef.json
+.agents/skills/taskchef-bootstrap -> <source>/.agents/skills/taskchef-bootstrap
+.agents/skills/taskchef-delegate -> <source>/.agents/skills/taskchef-delegate
+.agents/skills/taskchef-reconcile -> <source>/.agents/skills/taskchef-reconcile
+tasks/<task-id>/task.json
+```
+
+Create or repair the managed scaffold without supplying configuration:
+
+```sh
+taskchef workspace init --workspace <workspace>
+taskchef doctor --workspace <workspace>
+```
+
+Initialization is idempotent. It creates an empty configuration when missing
+and preserves existing configured projects.
+
+## Projects
+
+Add one project. Git status, the exact Git root, and a canonical GitHub origin
+are detected automatically:
+
+```sh
+taskchef project add /workspace/payments \
+  --name payments \
+  --description "Owns payment authorization, capture, and refunds." \
+  --workspace <workspace>
+```
+
+Import a JSON array from a file or stdin:
+
+```sh
+taskchef project import projects.json --workspace <workspace>
+taskchef project import - --workspace <workspace> < projects.json
+```
+
+Import merges by canonical path. Existing names and descriptions are preserved
+when omitted. `--replace` explicitly replaces the configured project set.
+
+```sh
+taskchef project list --workspace <workspace>
+taskchef project remove payments --workspace <workspace>
+```
+
+Removal refuses to orphan existing task records unless `--force` is supplied.
+
+## Tasks
+
+Task creation and update read JSON from stdin:
+
+```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>
+
+printf '%s\n' '{"status":"running","threadId":"019f..."}' |
+  taskchef task update t1 --json --workspace <workspace>
+```
+
+Inspection commands:
+
+```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>
+```
+
+`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.
+
+## Complete CLI
+
+```text
+taskchef help
+taskchef doctor
+taskchef workspace init
+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 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.
+
+## Release
+
+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:
+
+```text
+fix: correct task reconciliation
+feat: add a new CLI command
+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`.
+
+## Development
+
+```sh
+npm test
+npm pack --dry-run
+npx -y -p semantic-release@25 -p @semantic-release/git semantic-release --dry-run
+```
+
+## Boundaries
+
+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.