Task Agent

Task Agent is a small, forkable workspace for task-first autonomous-agent workflows.

It is intentionally generic: no private task history, no local data, and no bundled personal integrations. Project-level operating rules live in AGENTS.md.

History Rewritten On 2026-08-06

Every commit before this date was rewritten to remove deployment-specific host paths and private project, task, and trip names that the earlier commits still carried in examples. Only those strings changed: the tree at the tip is byte-identical to what it was before the rewrite. Commit hashes did change, so a clone made before 2026-08-06 has no commit in common with origin/main.

If you have such a clone, discard its local history:

git fetch --all && git reset --hard origin/main

Commit anything you want to keep to a separate branch first; the reset discards uncommitted and unpushed work. One merged leftover branch was renamed in the same change and is now port-generic-agent-workspace-work; prune stale remote-tracking refs with git fetch --prune.

What Is Included

• tasks/ skeleton for durable task artifacts
• tasks/USER_PREFERENCES.example.md as a starting point for durable user defaults
• data/projects/ skeleton for multi-task project records
• data/local-projects.example.md as a starting point for local repository/path indexes
• AGENTS.md, .cursor/rules/, and CLAUDE.md as one shared rule set for Codex, Cursor, and Claude Code
• skills/task-creator/ for creating task directories and updating the index
• skills/task-runner/ for parent-child CLI agent execution, detached-run supervision, and the dev-pipeline workflow
• skills/task-artifacts/ for keeping task artifacts current during work
• skills/project-organizer/ for durable project records
• skills/repo-health/ for restore, publication, deliverables, and pre-push checks
• skills/skill-maintainer/ for creating or changing skills
• docs/ for architecture, task execution, Claude Code setup, and self-development workflows

Quick Start

Prerequisites are Python 3.11+, Git, network access, and an installed and authenticated Codex, Claude, or Cursor CLI for the dev-pipeline owner. Clone the repository, then from its directory create the environment and install the pinned public dependency together with the test tools:

git clone https://github.com/rdudov/task-agent.git
cd task-agent
python3 -m venv .venv
.venv/bin/pip install -r requirements.lock

Create a task:

skills/task-creator/scripts/create_task.sh "Example task" "Try the task-agent workflow"

Run health checks:

.venv/bin/python skills/repo-health/scripts/check_repo_health.py --allow-empty-tasks
PYTHONPATH=skills/task-runner/scripts .venv/bin/python -m pytest skills/task-runner/tests skills/task-creator/tests skills/repo-health/tests

Before pushing a source change from this workspace, run:

.venv/bin/python skills/repo-health/scripts/check_pre_push.py --remote origin

To block deployment-specific project/task/trip names without publishing them, put one literal per line in ignored .state/private-history-markers, or point TASK_AGENT_PRIVATE_HISTORY_MARKERS at another local file. The guard also refuses foreign remote and unknown ref namespaces while allowing ordinary local branches, tags, notes, and stash.

An empty marker list is not a pass. A fresh clone has no .state/, so the name check has nothing to compare against; both check_pre_push.py and check_repo_health.py now say so on stderr instead of reporting a clean run. Pass --require-private-history-markers to check_pre_push.py to turn that notice into a failure.

Agent Entry Points

The same rules reach Codex, Cursor, and Claude Code without being copied. AGENTS.md holds the project rules, .cursor/rules/*.mdc hold the always-on rules, and CLAUDE.md imports both rather than restating them; .claude/ contains only symlinks into the canonical files. Adding a Cursor rule means adding its .claude/imports/ symlink and its CLAUDE.md import line — see docs/claude-code-setup.md.

Delegating To A Child Agent

.venv/bin/python skills/task-runner/scripts/task_runner.py start tasks/001-example

The child runner follows the parent CLI agent, so a Codex session delegates to Codex and a Claude session to Claude. Pass --runner codex|claude|agent to decide explicitly, or set TASK_AGENT_CHILD_RUNNER. All three drive both workflows: under dev-pipeline the agent runner becomes the core's cursor owner runtime. Every run records which rule decided.

Access level is expressed once through --sandbox-mode (read-only, workspace-write, danger-full-access) and mapped per runner. TASK_AGENT_WORKSPACE_ROOT sets how far full access reaches; it defaults to the parent of this checkout.

For the standard workflow, --repo /path/to/target-repo makes that repository an additional workspace/access root for Codex, Claude, or Cursor Agent while the task-agent checkout remains the primary workspace. Write modes verify writability before launch and record the result.

start returns once the run is confirmed; the watcher and the child keep running in their own sessions, so closing the terminal does not end the work. On a host systemd machine the watcher gets its own transient scope; elsewhere the recorded boundary says it inherits the caller cgroup. Both processes are recorded by kernel start-time identity and PID namespace rather than by pid alone. An observer in another namespace reports liveness as unknown and cannot replace, stop, or reattach the host run. reattach restores a lost watcher and refuses when the pid was recycled or a watcher is already live.

Dev-Pipeline Workflow

--workflow dev-pipeline runs a task through the standalone dev-pipeline CLI, which drives an evidence-gated Codex, Claude, or Cursor owner session:

.venv/bin/python skills/task-runner/scripts/task_runner.py start tasks/001-example \
  --workflow dev-pipeline --repo /path/to/target-repo

The workflow dependency is the separate public repository rdudov/dev-pipeline. It is pinned in requirements.txt and requirements.lock, so the Quick Start installs the tested revision. To develop both repositories locally instead, replace it in the active virtual environment with an editable checkout:

.venv/bin/pip install -e /path/to/dev-pipeline

The adapter is transport-neutral. It builds the owner instruction, calls the public CLI, validates the neutral lifecycle events it emits, and projects them into the task's status.json, trace.md, and progress.json. It binds no recipient and delivers no messages; skills/task-runner/scripts/pipeline_notify.py is the documented, deliberately inert seam where an application with a real transport attaches its own delivery and replay rules.

By default the runner resolves the CLI installed at .venv/bin/dev-pipeline, then falls back to PATH. TASK_AGENT_DEV_PIPELINE_BIN or --dev-pipeline-bin can select another executable explicitly; an unresolved CLI fails before an owner process is started. The same resolver is used by normal runs, direct adapter invocation, and review-candidate.

The owner closes task frontmatter through tasks_index.py, completes every plan step, and records passing live evidence. A completion reported without those durable gates is blocked. For a contract with mandatory prose policy families, run the bounded reviewer over the final committed candidate:

.venv/bin/python skills/task-runner/scripts/task_runner.py review-candidate \
  tasks/001-example --repo /path/to/target-repo

Documentation

• docs/architecture.md
• docs/task-execution.md
• docs/self-development.md

License

Task Agent is released under the MIT License.

Local State

tasks/ and data/ are durable local artifacts. This template tracks only skeleton and example files; real task history, tasks/INDEX.md, and reusable data should be backed up by your own local backup flow.