task-delegate 0.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "task-delegate",
+  "version": "0.1.0",
+  "description": "Low-context multi-backend delegation for CLI coding agents through compact briefs, bundled adapters, and structured results.",
+  "type": "module",
+  "bin": {
+    "task-delegate": "bin/task-delegate.mjs"
+  },
+  "scripts": {
+    "check": "node --check skills/task-delegate/scripts/relay.mjs && find skills/task-delegate/scripts -name '*.mjs' -not -path '*/node_modules/*' -print0 | xargs -0 -n1 node --check",
+    "test": "node --test test/*.test.mjs",
+    "dry-run": "node bin/task-delegate.mjs run --backend opencode --mode plan --brief examples/brief.sample.md --cd . --dry-run --allow-dirty",
+    "start": "node bin/task-delegate.mjs --help",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm run check && npm test && npm run pack:dry-run",
+    "doctor": "node bin/task-delegate.mjs doctor",
+    "list-backends": "node bin/task-delegate.mjs list-backends",
+    "init-brief": "node bin/task-delegate.mjs init-brief --out task-delegate.brief.md --force"
+  },
+  "keywords": [
+    "agent-skills",
+    "delegation",
+    "opencode",
+    "codex",
+    "claude-code",
+    "low-context",
+    "coding-agent"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "devDependencies": {},
+  "main": "bin/task-delegate.mjs",
+  "files": [
+    "bin/",
+    "skills/",
+    "examples/",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "skills.sh.json",
+    "PUBLISHING.md",
+    "NOTICE",
+    "scripts/",
+    "GITHUB_PROFILE_SETUP.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MOHJRNL/task-delegate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MOHJRNL/task-delegate/issues"
+  },
+  "homepage": "https://github.com/MOHJRNL/task-delegate#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./bin/task-delegate.mjs",
+    "./skill": "./skills/task-delegate/SKILL.md",
+    "./relay": "./skills/task-delegate/scripts/relay.mjs",
+    "./package.json": "./package.json"
+  },
+  "author": "Noah Hendy"
+}

package/scripts/create-github-repo.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+OWNER="MOHJRNL"
+REPO="task-delegate"
+DESCRIPTION="Low-context multi-backend delegation for CLI coding agents through compact briefs, bundled adapters, and structured results."
+VISIBILITY="public"
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "GitHub CLI (gh) is required. Install it first: https://cli.github.com/" >&2
+  exit 1
+fi
+
+if ! gh auth status >/dev/null 2>&1; then
+  echo "Run: gh auth login" >&2
+  exit 1
+fi
+
+if gh repo view "$OWNER/$REPO" >/dev/null 2>&1; then
+  echo "Repository already exists: https://github.com/$OWNER/$REPO"
+else
+  gh repo create "$OWNER/$REPO" --$VISIBILITY --description "$DESCRIPTION" --source=. --remote=origin --push
+  echo "Created and pushed: https://github.com/$OWNER/$REPO"
+  exit 0
+fi
+
+if git remote get-url origin >/dev/null 2>&1; then
+  git remote set-url origin "https://github.com/$OWNER/$REPO.git"
+else
+  git remote add origin "https://github.com/$OWNER/$REPO.git"
+fi
+
+git branch -M main
+git push -u origin main

package/skills/task-delegate/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: task-delegate
+description: Use this skill when the user wants to delegate a bounded coding task from Claude, Cursor, Codex, Gemini, or another orchestrator agent to CLI coding agents with low context usage. TaskDelegate creates a compact brief, runs a selected backend adapter, captures compact structured results, and keeps review/commit responsibility with the orchestrator. Use OpenCode as the stable default backend. Codex and Claude are experimental/manual backends in v0.1. Do not use for tiny inline edits, vague discovery, direct production changes without review, or tasks requiring GitHub PR automation.
+license: Apache-2.0
+metadata:
+  version: "0.1.0"
+  backends:
+    opencode: stable
+    codex: experimental
+    claude: experimental
+---
+
+# TaskDelegate
+
+You are the orchestrator. The backend CLI agent is the implementer.
+
+Your job is to compress the user's task into a small, complete brief, send it to the selected backend, collect the compact result, then review the diff and gates before accepting anything.
+
+## Use this skill when
+
+- The task is implementation-heavy.
+- The task is bounded enough to describe clearly.
+- The user wants efficient delegation with low context usage.
+- A backend CLI agent can work from the repository plus a compact brief.
+- The final decision should remain with the orchestrator or human reviewer.
+
+## Do not use this skill when
+
+- The edit is tiny and faster to do directly.
+- The task is vague, strategic, or product-discovery-only.
+- The task requires secrets, credentials, or private tokens.
+- The task requires GitHub PR automation.
+- The user expects the backend agent to commit or push.
+
+## Backend policy v0.1
+
+- `opencode` is stable and should be the default.
+- `codex` is experimental and should use `manual` unless the user explicitly accepts a different mode.
+- `claude` is experimental and should use `manual` or `plan` unless the user explicitly accepts a different mode.
+
+## Core rules
+
+- Backend agents must not commit.
+- Backend agents must not push.
+- Backend agents must not reset, clean, or rewrite git history.
+- Backend agents must not read `.env`, key, certificate, or secret files.
+- Backend agents must not modify files outside the project directory.
+- Backend agents must not install new packages unless explicitly allowed in the brief.
+- The orchestrator must review the final diff before accepting the result.
+- The orchestrator must re-run gates or clearly report that gates were not run.
+
+## Low-context rules
+
+- Preferred brief size: 40-80 lines.
+- Default maximum brief size: 120 lines.
+- Do not paste full chat history into the brief.
+- Do not paste large files unless necessary.
+- On retry, send a delta brief only.
+- Load backend-specific references only when needed.
+
+## Default process
+
+1. Decide whether delegation is appropriate.
+2. Select backend:
+   - simple/mechanical: `opencode`
+   - reasoning-heavy: `codex`
+   - architecture-sensitive: `claude`
+3. Write a compact brief using `references/brief-template.md`.
+4. Run the relay:
+
+```bash
+node skills/task-delegate/scripts/relay.mjs --backend opencode --mode safe-auto --brief /path/to/brief.md --cd /path/to/project
+```
+
+5. Read `result.json`.
+6. Inspect changed files and diff stat.
+7. Re-run tests/lint/build where practical.
+8. Summarize:
+   - what changed
+   - files changed
+   - gates run
+   - risks
+   - next action
+
+## References
+
+- `references/brief-template.md`
+- `references/backend-selection.md`
+- `references/permission-policy.md`
+- `references/result-schema.md`
+- `references/review-checklist.md`
+- `references/roadmap.md`
+
+
+## Public usage
+
+TaskDelegate can be used either as an installed Agent Skill or through the bundled npm CLI:
+
+```bash
+npx task-delegate run --backend opencode --mode safe-auto --brief brief.md --cd .
+```
+
+The OpenCode, Codex, and Claude adapter scripts are bundled with the skill. Backend CLIs themselves must be installed and authenticated separately.

package/skills/task-delegate/references/backend-selection.md

@@ -0,0 +1,42 @@
+# Backend selection
+
+TaskDelegate v0.1 uses manual backend selection. Do not add a smart router yet.
+
+## Backend matrix
+
+| Backend | Status | Best for | Default mode |
+|---|---|---|---|
+| OpenCode | Stable | Mechanical edits, tests, simple features, repetitive implementation | `safe-auto` |
+| Codex | Experimental | Reasoning-heavy implementation, bug fixing, second pass | `manual` |
+| Claude | Experimental | Planning, architecture-sensitive changes, complex refactors | `manual` or `plan` |
+
+## Selection rules
+
+Use OpenCode when:
+
+- The task is clear and bounded.
+- The change is mostly implementation.
+- Cost/context efficiency matters most.
+- You want non-interactive execution with deny rules.
+
+Use Codex when:
+
+- The task needs deeper reasoning than a mechanical edit.
+- You want a second implementation or review pass.
+- OpenCode failed or produced a weak result.
+
+Use Claude when:
+
+- The task involves architecture tradeoffs.
+- The codebase is complex.
+- You want a high-quality plan before editing.
+- The change is sensitive enough to prefer manual permissions.
+
+## Do not route automatically in v0.1
+
+Automatic routing adds complexity and may waste tokens when it picks the wrong backend. The v0.1 design uses an adapter layer, not a smart router.
+
+Roadmap:
+
+- v0.3: `--backend auto` rule-based router
+- v0.5: `--profile cheap|balanced|best` cost-aware router

package/skills/task-delegate/references/brief-template.md

@@ -0,0 +1,87 @@
+# TaskDelegate brief template
+
+Use this template to create a compact backend prompt. Keep the brief self-contained, but not bloated.
+
+## Recommended size
+
+- Preferred: 40-80 lines.
+- Maximum default: 120 lines.
+- Never paste full chat history.
+- Never paste large files unless the backend cannot read the repo.
+
+## Template
+
+```markdown
+# Task
+
+Describe the exact implementation task in 3-6 lines.
+
+# Goal
+
+What should be true when the task is complete?
+
+# Scope
+
+Allowed:
+- 
+
+Not allowed:
+- Do not commit.
+- Do not push.
+- Do not reset, clean, or rewrite git history.
+- Do not read secrets, `.env`, keys, certificates, or credentials.
+- Do not modify unrelated files.
+- Do not install packages unless explicitly allowed.
+
+# Files / areas likely involved
+
+- 
+
+# Acceptance criteria
+
+- 
+- 
+- 
+
+# Gates to run
+
+```bash
+# examples
+npm test
+npm run lint
+npm run build
+```
+
+# Output required
+
+Return:
+- summary of changes
+- files changed
+- commands run
+- gate results
+- unresolved issues
+```
+
+## Retry template
+
+For retries, use a delta brief only:
+
+```markdown
+# Delta task
+
+Fix only the following issue from the previous run:
+
+# Failure / error
+
+Paste the exact failing command and short error.
+
+# Constraint
+
+Do not redo unrelated work. Do not change files outside the previously touched scope unless necessary.
+
+# Gate to re-run
+
+```bash
+...
+```
+```

package/skills/task-delegate/references/permission-policy.md

@@ -0,0 +1,74 @@
+# Permission policy
+
+TaskDelegate optimizes for efficient delegation without giving backend agents ownership of the repository.
+
+## Universal hard rules
+
+Backend agents must not:
+
+- commit
+- push
+- reset hard
+- clean files
+- rewrite history
+- read secrets
+- read `.env` files
+- write outside the project directory
+- install packages unless explicitly allowed
+
+## Modes
+
+| Mode | Description |
+|---|---|
+| `plan` | Analyze and propose a plan only. |
+| `manual` | Use conservative/manual backend permissions. |
+| `safe-auto` | Non-interactive execution with deny rules. Stable only for OpenCode in v0.1. |
+
+## OpenCode `safe-auto`
+
+OpenCode supports `--auto`, which auto-approves permission requests that are not explicitly denied. TaskDelegate sets `OPENCODE_PERMISSION` with restrictive deny/ask rules for `safe-auto`.
+
+Default OpenCode permission profile:
+
+```json
+{
+  "read": {
+    "*": "allow",
+    "*.env": "deny",
+    "*.env.*": "deny",
+    "*.pem": "deny",
+    "*.key": "deny",
+    "id_rsa*": "deny"
+  },
+  "edit": {
+    "*": "allow",
+    "*.env": "deny",
+    "*.env.*": "deny"
+  },
+  "bash": {
+    "*": "ask",
+    "git status*": "allow",
+    "git diff*": "allow",
+    "git log*": "allow",
+    "git show*": "allow",
+    "git add*": "deny",
+    "git commit*": "deny",
+    "git push*": "deny",
+    "git reset*": "deny",
+    "git clean*": "deny",
+    "rm *": "deny",
+    "rm -rf*": "deny"
+  },
+  "webfetch": "deny",
+  "websearch": "deny",
+  "external_directory": "deny"
+}
+```
+
+## Codex v0.1
+
+Codex is experimental/manual in v0.1. TaskDelegate does not use dangerous bypass modes. The adapter sends strong prompt-level boundaries and relies on Codex CLI sandbox/approval behavior.
+
+## Claude v0.1
+
+Claude is experimental/manual in v0.1. Use `plan` for planning and `manual` for implementation. Do not default to Claude auto mode.

package/skills/task-delegate/references/result-schema.md

@@ -0,0 +1,46 @@
+# Result schema
+
+TaskDelegate writes a compact `result.json` for every run. The orchestrator should read this first and open logs only when needed.
+
+## Schema v0.1
+
+```json
+{
+  "schemaVersion": "0.1",
+  "skill": "task-delegate",
+  "backend": "opencode",
+  "backendStatus": "stable",
+  "mode": "safe-auto",
+  "projectDir": "/path/to/project",
+  "runDir": "/path/to/project/.task-delegate/runs/...",
+  "startedAt": "2026-07-08T00:00:00.000Z",
+  "endedAt": "2026-07-08T00:00:00.000Z",
+  "durationMs": 12345,
+  "exitCode": 0,
+  "timedOut": false,
+  "brief": {
+    "path": "brief.md",
+    "lines": 48,
+    "maxLines": 120
+  },
+  "git": {
+    "dirtyBefore": false,
+    "dirtyAfter": true,
+    "changedFiles": ["src/example.ts"],
+    "diffStatPath": "diff-stat.txt",
+    "changedFilesPath": "changed-files.txt"
+  },
+  "artifacts": {
+    "promptPath": "prompt.md",
+    "stdoutPath": "stdout.log",
+    "stderrPath": "stderr.log"
+  },
+  "warnings": [],
+  "reviewRequired": true,
+  "commitAllowed": false
+}
+```
+
+## Design principle
+
+Keep `result.json` compact. Do not embed full stdout, stderr, or diff content. Store paths instead.

package/skills/task-delegate/references/review-checklist.md

@@ -0,0 +1,43 @@
+# Review checklist
+
+Use this after every delegated run.
+
+## Required checks
+
+- Read `result.json` first.
+- Check `exitCode` and `warnings`.
+- Review `changed-files.txt`.
+- Review `diff-stat.txt`.
+- Inspect the actual git diff.
+- Re-run gates from the brief where practical.
+- Confirm no secrets or `.env` files were touched.
+- Confirm no package/dependency changes unless allowed.
+- Confirm no unrelated files were changed.
+- Commit only after review. The backend agent must never commit.
+
+## Red flags
+
+Reject or retry with a delta brief if:
+
+- The backend changed unrelated files.
+- The backend skipped the requested gates without explanation.
+- The backend installed packages without permission.
+- The backend modified lockfiles unexpectedly.
+- The backend touched auth/payment/security/infra files without explicit scope.
+- The backend produced broad try/catch wrappers instead of fixing root cause.
+- Tests were faked, disabled, or weakened.
+
+## Acceptance summary template
+
+```markdown
+## Delegated run review
+
+Backend: 
+Mode: 
+Changed files: 
+Gates run: 
+Gates passed: 
+Gates failed/not run: 
+Risks: 
+Decision: accept / retry / reject
+```

package/skills/task-delegate/references/roadmap.md

@@ -0,0 +1,76 @@
+# TaskDelegate roadmap
+
+## v0.1 — Multi-adapter MVP
+
+- OpenCode stable adapter
+- Codex experimental adapter
+- Claude experimental adapter
+- Node.js relay
+- compact brief format
+- compact `result.json`
+- no commit boundary
+- dirty working tree preflight
+- OpenCode safe-auto permission profile
+
+## v0.2 — Cost and context discipline
+
+- brief budget enforcement improvements
+- output budget warnings
+- delta retry helper
+- optional OpenCode `stats` capture
+- backend capability report
+
+## v0.3 — Router Lite
+
+- `--backend auto`
+- simple task classifier: simple / standard / complex / sensitive
+- backend recommendation before execution
+- allow human/orchestrator override
+
+## v0.4 — Efficient backend expansion
+
+Add experimental adapters:
+
+- Kimi Code / Kimi CLI
+- Qwen Code
+- Gemini CLI
+- Aider
+
+Potential later adapters:
+
+- Cursor CLI
+- Goose
+- Crush
+- Devin/Copilot if CLI/API workflow is appropriate
+
+## v0.5 — Cost-aware profiles
+
+- `--profile cheap`
+- `--profile balanced`
+- `--profile best`
+- fallback chain
+- token/cost summary where backend exposes usage
+
+## v0.6 — Review/guard layer
+
+- dependency change warning
+- suspicious file change detection
+- auth/payment/infra file warning
+- basic secret scan integration
+- generated review summary
+
+## v1.0 — Professional DevSecOps/Product workflow
+
+- GitHub issue to brief
+- branch and draft PR flow
+- CI result reader
+- PR review checklist
+- release readiness checklist
+- Python reporting layer
+
+## Out of scope for v0.x
+
+- Hugging Face model/dataset/Space delivery
+- fully autonomous GitHub PR merging
+- unrestricted auto execution
+- background task monitoring

package/skills/task-delegate/scripts/adapters/claude.mjs

@@ -0,0 +1,33 @@
+export const backend = {
+  name: 'claude',
+  status: 'experimental',
+  binary: 'claude',
+  defaultMode: 'manual',
+  supportedModes: ['plan', 'manual', 'safe-auto']
+};
+
+function permissionMode(mode) {
+  if (mode === 'plan') return 'plan';
+  if (mode === 'safe-auto') return 'acceptEdits';
+  return 'default';
+}
+
+export function buildInvocation({ prompt, mode, model }) {
+  const args = ['-p', prompt, '--permission-mode', permissionMode(mode)];
+  if (model) args.push('--model', model);
+
+  const warnings = [
+    'Claude adapter is experimental in TaskDelegate v0.1.'
+  ];
+
+  if (mode === 'safe-auto') {
+    warnings.push('Claude safe-auto maps to acceptEdits and is not recommended as default. Prefer manual or plan.');
+  }
+
+  return {
+    command: backend.binary,
+    args,
+    env: {},
+    warnings
+  };
+}

package/skills/task-delegate/scripts/adapters/codex.mjs

@@ -0,0 +1,27 @@
+export const backend = {
+  name: 'codex',
+  status: 'experimental',
+  binary: 'codex',
+  defaultMode: 'manual',
+  supportedModes: ['plan', 'manual']
+};
+
+export function buildInvocation({ prompt, mode, model }) {
+  const effectivePrompt = mode === 'plan'
+    ? `PLAN MODE ONLY. Do not edit files. Do not run destructive commands. Produce a concise implementation plan.\n\n${prompt}`
+    : prompt;
+
+  const args = ['exec'];
+  if (model) args.push('-m', model);
+  args.push(effectivePrompt);
+
+  return {
+    command: backend.binary,
+    args,
+    env: {},
+    warnings: [
+      'Codex adapter is experimental in TaskDelegate v0.1.',
+      'TaskDelegate does not use dangerous bypass/yolo modes for Codex.'
+    ]
+  };
+}