task-delegate 0.1.0

package/AGENTS.md

@@ -0,0 +1,29 @@
+# TaskDelegate Agent Instructions
+
+TaskDelegate is designed to keep the orchestrator context small while delegating bounded coding tasks to CLI coding agents.
+
+## Current backend policy
+
+- `opencode`: stable/default backend.
+- `codex`: experimental/manual backend.
+- `claude`: experimental/manual backend.
+
+## Commit boundary
+
+Delegate agents must not commit, push, reset, clean, or rewrite history. The orchestrator or human reviewer owns the final diff review and commit.
+
+## Low-context policy
+
+- Prefer 40-80 line briefs.
+- Maximum brief length: 120 lines by default.
+- Do not paste full conversation history into delegated prompts.
+- Do not paste large files unless the backend cannot read the repository.
+- Retry with a delta brief, not a full duplicate brief.
+
+## Safety policy
+
+- Do not read `.env`, secret, key, certificate, or credential files.
+- Do not write outside the selected project directory.
+- Do not install packages unless the brief explicitly allows it.
+- Do not run destructive commands.
+- Re-run tests/lint/build before accepting delegated changes.

package/GITHUB_PROFILE_SETUP.md

@@ -0,0 +1,59 @@
+# GitHub Profile Setup for MOHJRNL/task-delegate
+
+This repo is personalized for the GitHub profile:
+
+```text
+MOHJRNL
+```
+
+Expected repository URL:
+
+```text
+https://github.com/MOHJRNL/task-delegate
+```
+
+## Option A — create and push with GitHub CLI
+
+From the repo root:
+
+```bash
+git init
+git add .
+git commit -m "Initial release: TaskDelegate v0.1"
+./scripts/create-github-repo.sh
+```
+
+## Option B — create empty repo manually, then push
+
+Create an empty public GitHub repo named `task-delegate` under `MOHJRNL`, then run:
+
+```bash
+git init
+git add .
+git commit -m "Initial release: TaskDelegate v0.1"
+git branch -M main
+git remote add origin https://github.com/MOHJRNL/task-delegate.git
+git push -u origin main
+```
+
+## Public install commands after push
+
+As an Agent Skill:
+
+```bash
+npx skills add MOHJRNL/task-delegate --skill task-delegate
+```
+
+As a GitHub-backed npx package before npm publish:
+
+```bash
+npx github:MOHJRNL/task-delegate --help
+npx github:MOHJRNL/task-delegate doctor
+```
+
+After npm publish:
+
+```bash
+npx task-delegate --help
+npx task-delegate doctor
+```

package/LICENSE

@@ -0,0 +1,52 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on or derived from the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link or bind by name to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding notices that do not pertain to any part of the Derivative Works.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory shall any Contributor be liable to You for damages arising from use of the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer support, warranty, indemnity, or other liability obligations. However, You may do so only on Your own behalf and on Your sole responsibility.
+
+END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,7 @@
+TaskDelegate
+Copyright 2026 TaskDelegate contributors.
+
+TaskDelegate is an original low-context delegation skill/package.
+If you fork, redistribute, or publish a derivative package, please preserve this NOTICE file and clearly indicate that your work is based on TaskDelegate.
+
+This product includes no bundled OpenCode, Codex, Claude Code, Kimi, Qwen, Gemini, or other third-party backend CLI binaries. Adapters are lightweight wrappers only.

package/PUBLISHING.md

@@ -0,0 +1,118 @@
+# Publishing TaskDelegate
+
+TaskDelegate is prepared for two public distribution paths:
+
+1. GitHub skill distribution through `npx skills add`.
+2. npm CLI distribution through `npx task-delegate`.
+
+Official repository:
+
+```text
+https://github.com/MOHJRNL/task-delegate
+```
+
+## Before publishing
+
+Validate:
+
+```bash
+npm run check
+npm test
+npm run pack:dry-run
+npm run doctor
+```
+
+Confirm `package.json` points to:
+
+```text
+https://github.com/MOHJRNL/task-delegate
+```
+
+## GitHub skill installation path
+
+Users can install the skill directly from GitHub with:
+
+```bash
+npx skills add MOHJRNL/task-delegate --skill task-delegate
+```
+
+This installs the skill package from:
+
+```text
+skills/task-delegate/
+```
+
+The adapters are bundled under:
+
+```text
+skills/task-delegate/scripts/adapters/
+```
+
+Users do not install adapters separately.
+
+## GitHub-only npx usage before npm publish
+
+Users can run the CLI directly from the public GitHub repo:
+
+```bash
+npx github:MOHJRNL/task-delegate --help
+npx github:MOHJRNL/task-delegate doctor
+```
+
+## npm CLI publishing path
+
+Login:
+
+```bash
+npm login
+npm whoami
+```
+
+Publish unscoped if available:
+
+```bash
+npm publish
+```
+
+Users can then run:
+
+```bash
+npx task-delegate --help
+npx task-delegate doctor
+npx task-delegate run --backend opencode --mode safe-auto --brief brief.md --cd .
+```
+
+## Scoped package fallback
+
+If `task-delegate` is unavailable on npm, change `package.json`:
+
+```json
+{
+  "name": "@mohjrnl/task-delegate",
+  "bin": {
+    "task-delegate": "bin/task-delegate.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+Publish:
+
+```bash
+npm publish --access public
+```
+
+Users can then run:
+
+```bash
+npx @mohjrnl/task-delegate --help
+npx @mohjrnl/task-delegate doctor
+```
+
+## Attribution and forks
+
+TaskDelegate uses Apache-2.0 and ships a `NOTICE` file. Forks and derivative packages should keep the license and NOTICE attribution.
+
+GitHub forks created through GitHub will show the upstream fork relationship automatically. npm packages cannot force a visual fork relationship, so the license/NOTICE files are the portable attribution mechanism.

package/README.md

@@ -0,0 +1,333 @@
+# TaskDelegate
+
+**TaskDelegate** is a low-context delegation skill and CLI that lets coding agents hand off bounded implementation tasks to CLI coding agents through compact briefs, safe execution modes, bundled adapters, and structured results.
+
+The first version is intentionally lean:
+
+- **Language:** Node.js
+- **Stable backend:** OpenCode
+- **Experimental backends:** Codex, Claude Code
+- **Default OpenCode mode:** `safe-auto`
+- **Safety:** deny rules, no commit boundary, clean working tree preflight
+- **Output:** compact `result.json`
+- **Adapters:** bundled inside the package; users do not install adapters separately
+- **Roadmap:** GitHub, DevSecOps, Python reporting, Kimi/Qwen/Gemini adapters later
+
+## Why TaskDelegate exists
+
+Most orchestrator agents waste context when they try to inspect, implement, debug, and review everything inside one conversation. TaskDelegate moves implementation-heavy work into a separate CLI-agent run and returns only a compact result for review.
+
+```text
+orchestrator agent
+→ compact brief
+→ backend adapter
+→ CLI coding agent
+→ result.json + logs + diff metadata
+→ orchestrator review
+→ human/orchestrator commit
+```
+
+## Current backend matrix
+
+| Backend | Status | Default mode | Recommended use |
+|---|---|---|---|
+| OpenCode | Stable | `safe-auto` | Mechanical edits, small features, tests, refactors |
+| Codex | Experimental | `manual` | Reasoning-heavy implementation or second pass |
+| Claude Code | Experimental | `manual` | Complex refactor, architecture-sensitive work, planning/review |
+
+## Requirements
+
+- Node.js 18+
+- Git
+- At least one supported CLI backend installed and authenticated:
+  - `opencode`
+  - `codex`
+  - `claude`
+
+## Official repository
+
+```text
+https://github.com/MOHJRNL/task-delegate
+```
+
+## Installation
+
+TaskDelegate supports two public usage paths.
+
+### 1. Install as an Agent Skill
+
+Install the skill from this GitHub repository:
+
+```bash
+npx skills add MOHJRNL/task-delegate --skill task-delegate
+```
+
+This copies the `skills/task-delegate` package, including scripts, references, and adapters. No separate adapter install is required.
+
+### 2. Run as a CLI with npx
+
+Before npm publishing, run directly from GitHub:
+
+```bash
+npx github:MOHJRNL/task-delegate --help
+npx github:MOHJRNL/task-delegate doctor
+```
+
+After publishing to npm, users can run without a global install:
+
+```bash
+npx task-delegate --help
+npx task-delegate doctor
+npx task-delegate run --backend opencode --mode safe-auto --brief brief.md --cd .
+```
+
+Recommended pinned usage after release:
+
+```bash
+npx task-delegate@0.1.0 --help
+```
+
+## What is bundled vs external
+
+Bundled:
+
+- `task-delegate` CLI
+- `task-delegate` skill
+- OpenCode/Codex/Claude adapters
+- brief templates
+- permission/review references
+
+External prerequisites:
+
+- Node.js
+- Git
+- whichever backend CLI the user wants to run: `opencode`, `codex`, or `claude`
+- backend authentication/configuration
+
+Adapters are wrappers. They are intentionally bundled. Backend CLIs are not bundled because they have their own installation, authentication, permissions, model access, and release cadence.
+
+## Quick start for local development
+
+```bash
+npm test
+npm run check
+npm run pack:dry-run
+```
+
+Run the CLI locally from the repo:
+
+```bash
+node bin/task-delegate.mjs --help
+node bin/task-delegate.mjs doctor
+node bin/task-delegate.mjs list-backends
+```
+
+Dry run without launching a backend:
+
+```bash
+npm run dry-run
+```
+
+Delegate to OpenCode:
+
+```bash
+task-delegate run \
+  --backend opencode \
+  --mode safe-auto \
+  --brief examples/brief.sample.md \
+  --cd /path/to/project
+```
+
+Delegate to Codex manually:
+
+```bash
+task-delegate run \
+  --backend codex \
+  --mode manual \
+  --brief examples/brief.sample.md \
+  --cd /path/to/project
+```
+
+Delegate to Claude Code in plan mode:
+
+```bash
+task-delegate run \
+  --backend claude \
+  --mode plan \
+  --brief examples/brief.sample.md \
+  --cd /path/to/project
+```
+
+## Skill installation helper
+
+If a user wants to copy the skill directly from the npm package into a local agent project:
+
+```bash
+npx task-delegate install-skill --dest .claude/skills
+```
+
+This installs:
+
+```text
+.claude/skills/task-delegate/
+├── SKILL.md
+├── scripts/
+└── references/
+```
+
+The adapter scripts are included. No separate adapter package is needed.
+
+## Publishing to npm
+
+TaskDelegate is npm-ready. The package exposes a CLI binary through the `bin` field:
+
+```json
+{
+  "bin": {
+    "task-delegate": "bin/task-delegate.mjs"
+  }
+}
+```
+
+Before the first public release:
+
+```bash
+npm login
+npm run prepublishOnly
+npm publish
+```
+
+If the unscoped package name `task-delegate` is unavailable, switch to a scoped package name, for example:
+
+```json
+{
+  "name": "@mohjrnl/task-delegate",
+  "bin": {
+    "task-delegate": "bin/task-delegate.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+Then users can run:
+
+```bash
+npx @mohjrnl/task-delegate --help
+```
+
+## Output
+
+Each run writes to:
+
+```text
+.task-delegate/runs/<timestamp>-<backend>/
+├── result.json
+├── stdout.log
+├── stderr.log
+├── prompt.md
+├── git-before.txt
+├── git-after.txt
+├── diff-stat.txt
+└── changed-files.txt
+```
+
+`result.json` is intentionally compact so the orchestrator does not need to load long logs into context.
+
+## Modes
+
+| Mode | Meaning |
+|---|---|
+| `plan` | Ask the backend to analyze and propose a plan only. |
+| `manual` | Run with conservative/manual permissions where supported. |
+| `safe-auto` | Allow non-interactive execution with guardrails. Stable only for OpenCode in v0.1. |
+
+## Safety model
+
+TaskDelegate does not claim to make CLI agents safe by itself. It creates a safer operating loop:
+
+- no commits by backend agents
+- dirty working tree preflight
+- deny rules for OpenCode via `OPENCODE_PERMISSION`
+- compact output instead of full transcript loading
+- explicit review required
+- destructive command warnings
+
+## Troubleshooting
+
+### TaskDelegate requires a Git project
+
+TaskDelegate is designed to run inside a Git repository so it can capture:
+
+- Git status before and after the delegated run
+- changed files
+- diff stat
+- review metadata
+
+For a new test project:
+
+```bash
+git init
+echo ".task-delegate/" >> .gitignore
+git add .
+git commit -m "Initial project"
+```
+
+The `.task-delegate/` directory contains run outputs and should normally be ignored.
+
+### OpenCode fails with `Unexpected server error`
+
+First test OpenCode directly:
+
+```bash
+opencode run --pure --print-logs --log-level DEBUG "Say hello and do not edit files."
+```
+
+If the logs show `ProviderModelNotFoundError`, your default OpenCode model is invalid or no longer available.
+
+List available models:
+
+```bash
+opencode models
+```
+
+Then pass a valid model explicitly:
+
+```bash
+npx github:MOHJRNL/task-delegate run \
+  --backend opencode \
+  --mode safe-auto \
+  --brief brief.md \
+  --cd . \
+  --model zai-coding-plan/glm-4.7
+```
+
+The `--model` flag is optional, but useful when the default OpenCode model is not configured correctly.
+
+### Payment method errors
+
+Some OpenCode-hosted models may require billing. If you see a `No payment method` error, choose another available model or configure billing in OpenCode.
+
+### Duplicate skill warning
+
+If TaskDelegate is installed both globally and for Claude Code, OpenCode may warn about duplicate skill names, for example:
+
+```text
+duplicate skill name task-delegate
+```
+
+This is usually harmless. It means the same skill exists in more than one skill location, such as:
+
+```text
+~/.agents/skills/task-delegate
+~/.claude/skills/task-delegate
+```
+
+## Attribution and forks
+
+TaskDelegate uses Apache-2.0 with a `NOTICE` file. Forks and redistributed derivative packages should preserve the license and NOTICE attribution. GitHub forks will also show the upstream relationship automatically when created through GitHub.
+
+## Roadmap
+
+See [`skills/task-delegate/references/roadmap.md`](skills/task-delegate/references/roadmap.md).

package/bin/task-delegate.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// TaskDelegate CLI entrypoint.
+// Keeps the published npm bin stable even if the internal skill script moves later.
+import '../skills/task-delegate/scripts/relay.mjs';

package/examples/brief.sample.md

@@ -0,0 +1,34 @@
+# Task
+
+Add a tiny documentation note to the README explaining how to run the test suite.
+
+# Goal
+
+The README should clearly mention the command `npm test`.
+
+# Scope
+
+Allowed:
+- Edit README.md only.
+
+Not allowed:
+- Do not commit.
+- Do not push.
+- Do not read secrets.
+- Do not install packages.
+- Do not change source code.
+
+# Acceptance criteria
+
+- README includes the test command.
+- No unrelated files are changed.
+
+# Gates to run
+
+```bash
+npm test
+```
+
+# Output required
+
+Return a short summary, changed files, commands run, and unresolved issues.