create-task-ops

create-task-ops is a Next.js-first scaffold generator for task docs and OrbitOps APIs.

Goals

• Start a new repo quickly
• Add task-ops structure to an existing repo
• Include tasks/*.md and the OrbitOps API contract by default

Usage

node packages/create-task-ops/bin/create-task-ops.js my-project
node packages/create-task-ops/bin/create-task-ops.js create my-project
node packages/create-task-ops/bin/create-task-ops.js add
node packages/create-task-ops/bin/create-task-ops.js add --target apps/server
node packages/create-task-ops/bin/create-task-ops.js add --print-targets
node packages/create-task-ops/bin/create-task-ops.js add --docs-only

After publishing, the intended usage is:

npx create-task-ops my-project
npx create-task-ops create my-project
npx create-task-ops add
npx create-task-ops add --target apps/server
npx create-task-ops add --print-targets
npx create-task-ops add --docs-only

Commands

• create-task-ops my-project Create a new Next.js-based task-ops project
• create-task-ops create my-project Same as above, but explicit
• create-task-ops add Add task docs and the OrbitOps API to the current repo. It scans app, src/app, apps/*/app, and packages/*/app to recommend a receiver target.
• create-task-ops add --target apps/server Keep docs and tasks at the repo root, but install the OrbitOps receiver under apps/server
• create-task-ops add --print-targets Print detected receiver target candidates and exit
• create-task-ops add --docs-only Add only the documentation and task-file conventions to the current repo

Internal Modes

• create Uses the full template internally
• add Selectively installs the api receiver files internally
• add --docs-only Uses the docs template internally

Files Added By add

add does not overwrite an existing repo wholesale. By default, it only adds:

• tasks/example-task.md
• CLAUDE.md
• AGENT.md
• .env.example
• docs/TASK_API_CONTRACT.md
• docs/DASHBOARD_CONNECTION.md
• docs/HEARTBEAT_SETUP.md
• docs/COMMAND_RUNNER_SETUP.md
• scripts/orbitops-agent.mjs
• scripts/orbitops-heartbeat.mjs
• scripts/orbitops-command-runner.mjs
• scripts/orbitops-dev.mjs
• If a package.json already exists, missing OrbitOps scripts are added without overwriting existing ones
• app/api/orbitops/health/route.ts
• app/api/orbitops/tasks/route.ts
• app/api/orbitops/tasks/[id]/route.ts
• app/api/orbitops/commands/[id]/log/route.ts
• lib/orbitops/auth.ts
• lib/orbitops/task-api.ts

It does not touch existing root files such as package.json, app/page.tsx, app/layout.tsx, or tsconfig.json.

For monorepos, --target is usually the right choice so the receiver lands in the real server app.

Example:

npx create-task-ops add --target apps/server

In that case:

• tasks/, CLAUDE.md, AGENT.md, and docs/* are created at the repo root
• scripts/orbitops-heartbeat.mjs is also created at the repo root
• scripts/orbitops-command-runner.mjs is also created at the repo root
• scripts/orbitops-agent.mjs is also created at the repo root
• scripts/orbitops-dev.mjs is also created at the repo root
• app/api/orbitops/*, lib/orbitops/auth.ts, and lib/orbitops/task-api.ts are created under apps/server

Existing operational docs such as CLAUDE.md, AGENT.md, tasks/*, and docs/* are skipped by default.

If the following receiver paths already exist, the command stops with a warning because the conflict is likely real:

• app/api/orbitops/health/route.ts
• app/api/orbitops/tasks/route.ts
• app/api/orbitops/tasks/[id]/route.ts
• lib/orbitops/auth.ts
• lib/orbitops/task-api.ts

Use --force only if you really want to replace those receiver files.

Local Testing

npm run create-task-ops -- my-project
npm run create-task-ops -- create my-project
npm run create-task-ops -- add
npm run create-task-ops -- add --target apps/server
npm run create-task-ops -- add --docs-only
cd packages/create-task-ops
npm run smoke:full

Runtime Token Flow

• The central dashboard heartbeat response returns a short-lived runtime token.
• scripts/orbitops-agent.mjs stores that token in .orbitops-runtime-token by default.
• The script loads .env through dotenv/config, and the generator also includes .env.example.
• The template now includes ORBITOPS_SOURCE_SNAPSHOT_URL so the remote repo can push task snapshots back to the central dashboard cache.
• The generator wires up orbitops:dev, orbitops:agent, orbitops:heartbeat, orbitops:commands, orbitops:online, orbitops:offline, and orbitops:paused when possible.
• orbitops:agent combines heartbeat and command polling in one sidecar process.
• orbitops:dev starts the app dev server, detects the actual local URL, then starts orbitops:agent automatically.
• The central dashboard no longer re-pulls remote task APIs during every UI refresh. Instead, orbitops:agent reads the local GET /api/orbitops/tasks response and pushes the current task snapshot to the central dashboard.
• The command runner starts Codex with codex exec --json, captures the session id, and reuses it with codex exec --json resume ... for the same task when available.
• The command runner starts Claude in non-interactive print mode by default: claude -p --output-format stream-json, captures the session id, and reuses it with --resume ... for the same task when available.
• ORBITOPS_CODEX_SKIP_GIT_REPO_CHECK=auto is enabled by default so Codex can still run from nested or non-trusted working directories when no .git directory is present in the cwd ancestry.
• ORBITOPS_CLAUDE_PRINT_MODE=true is the default. Set it to false only if your local Claude CLI wrapper does not support -p --output-format stream-json.
• When a command fails, the agent writes the log to .orbitops/commands/<commandId>.log and creates a queued follow-up task draft under tasks/.
• Generated GET /api/orbitops/tasks and GET /api/orbitops/tasks/:id routes read that file and validate Authorization: Bearer <runtimeToken>.
• GET /api/orbitops/health remains open for health checks.

Recommended Operating Modes

• npm run dev Start only the app server. Use this when OrbitOps integration is not needed.
• npm run orbitops:dev Start the app server, detect the actual runtime URL, then start orbitops:agent.
• npm run orbitops:agent Run only the OrbitOps sidecar. Use this when the app server is already managed elsewhere.
• npm run orbitops:online, npm run orbitops:offline, npm run orbitops:paused Send one-shot presence updates for debugging or manual control.