noetic tasks

What is a task?

A task is the top-level unit of work. It has an immutable id (T-<10 chars>), a source (manual or worktree), state axes (reviewStatus × lifecycleStatus × archivedAt × paused), and an optional hierarchy/ subdirectory that turns a leaf task into a "structured" task (milestones → slices → features → assertions, with validator runs and fix lineage).

Single concept. Single verb namespace (noetic tasks). Single agent-tool prefix (task_*). Single slash command (/tasks).

Storage lives at <projectRoot>/.noetic/tasks/ and is FS-only — JSON for canonical records, append-only *.jsonl for audit and event feeds. The full storage layout, atomicity guarantees, and runner contract are documented in specs/21-tasks.md in the source repo.

CLI verbs

noetic tasks <verb> dispatches to a small handler per verb. Run noetic tasks --help for the live verb table.

Output is JSON on stdout for scriptability. Errors land on stderr; unknown verbs exit 1.

Common flows

Create and inspect a leaf task

noetic tasks create --title "Refactor auth middleware"
# → prints the new Task JSON, including its T-<id>

noetic tasks list
# → array of tasks; each has a derived kanban column

noetic tasks show <T-id>
# → full record + recent log entries + hierarchy summary if present

noetic tasks log <T-id> "Tried approach A — too brittle"
noetic tasks logs <T-id> --n 20

Plan a structured task

tasks plan opens the live interview. It runs inside the TUI (the headless CLI surfaces a "use the TUI" error) because the interview asks the user multiple-choice questions through the harness's AskUserService.

noetic tasks create --title "Migrate billing to Stripe Tax"
# → returns T-<id>

# In the TUI:
/tasks                       # flips to kanban view
# focus the new card → press p (plan)
# answer the interview → hierarchy is persisted under
#   <projectRoot>/.noetic/tasks/T-<id>/hierarchy/

After planning, the task carries milestones, slices, features and assertions you can inspect with:

noetic tasks show <T-id>

Run autopilot end-to-end

Autopilot is a per-task flag the daemon consults to decide whether to autonomously plan, build, and validate the work. When enabled, the daemon's autopilot tick orchestrates a three-phase pipeline:

1. Plan — for a manual task with no hierarchy, the daemon spawns the planner runner (packages/cli/src/tasks/runtime/planner-runner.ts). It interviews itself via an LLM and persists a milestones → slices → features → assertions hierarchy. Task autopilotState flips inactive → planning → watching; hierarchyStatus lands at active on success.
2. Build — for triaged features whose linked leaf task has no worktree yet, the daemon spawns the implementer runner (packages/cli/src/tasks/runtime/implementer-runner.ts). It provisions a worktree (wt switch -c <branch> with git worktree add fallback), drives a react() agent loop with full coding tools rooted at the worktree, and on success flips the feature's loopState: implementing → validating.
3. Validate — features in validating are dispatched to a Step-graph validator (adversarial-validator-flow.ts). The flow runs agent-ci and an LLM-driven adversarial code review in parallel (via fork({mode: 'all'})) and merges their outcomes. agent-ci pass + no adversarial issues → loopState: passed; otherwise → needs_fix (which the existing fix-feature flow re-triages with the failing assertion outcomes attached).

noetic tasks create --title "Add scripts/qa-hello.ts"
# → returns T-<id>

noetic tasks autopilot on <T-id>
# → flips autopilotEnabled=true; the daemon's plan-pass spawns the planner
#   on its next tick. Watch progress with:

tail -f .noetic/tasks/_events.jsonl

You can still drive each phase manually if you prefer: noetic tasks plan <id> runs the live TUI interview without autopilot, and noetic tasks activate-slice --task <id> --slice <SL-id> triages a slice's features by hand. Autonomous and manual workflows can be mixed.

Flip autopilot back off at any time:

noetic tasks autopilot off <T-id>

Move and merge

noetic tasks move <T-id> --column ready_to_merge
noetic tasks merge <T-id>
# → tries `wt merge <branch>`; falls back to `git merge` if `wt` is missing.
#   On success the task lands in the `done` column.

Slash command

/tasks flips the TUI's view mode to the kanban board. Inside the board:

• The board renders all eight derived columns: triage, in_progress, needs_changes, ready_to_merge, done, cleanup_blocked, removed, archived.
• Each card shows a source badge: [m] for manual, [w] for worktree-backed.
• Structured tasks (those with a hierarchy/ directory) show a ▾ glyph after the title.
• Enter on a focused card drills in: structured → hierarchy view (milestones → slices → features tree); leaf → detail (description, log tail, attachments).
• c opens the create form. m opens the move picker on the focused card. Escape returns to the board.

There is no /mission command. There is no alias.

Agent tools

The task_* tool prefix mirrors the CLI verb table 1:1. Tools are registered by the harness factory and are default-on; opt out via tools.tasks: false in noetic.config.ts.

// noetic.config.ts
export default {
  tools: {
    tasks: false, // opt out of all task_* tools
  },
};

A read-only variant exposes only task_show, task_list, task_logs — used in planning mode and other contexts where the agent should observe the kanban without mutating it.

The 23 tools are: task_create, task_show, task_list, task_move, task_merge, task_log, task_logs, task_attach, task_comment, task_steer, task_pause, task_unpause, task_archive, task_unarchive, task_delete, task_duplicate, task_plan, task_add_milestone, task_add_slice, task_add_feature, task_add_assertion, task_activate_slice, task_autopilot.

See the agent-builder skill reference for full input schemas.

Storage at a glance

<projectRoot>/.noetic/tasks/
├── _events.jsonl                ← cross-process change feed
├── _state.json                  ← {schemaVersion, lastEventId}
└── T-<id>/
    ├── task.json                ← canonical record
    ├── description.md
    ├── log.jsonl                ← append-only audit
    ├── steering.md              ← optional, surfaced to in-task agent runs
    ├── _runner.json             ← agent-ci runner sidecar
    ├── _planner.json            ← planner runner sidecar (autopilot plan-pass)
    ├── _implementer.json        ← implementer runner sidecar (autopilot implement-pass)
    ├── attachments/
    └── hierarchy/               ← only on structured tasks
        ├── milestones/ML-<id>.json
        ├── slices/SL-<id>.json
        ├── features/F-<id>/feature.json
        ├── features/F-<id>/validator-runs/V-<id>.json
        ├── features/F-<id>/fix-lineage.jsonl
        ├── assertions/A-<id>.json
        └── interview-sessions/IV-<id>.json

Every mutable JSON is written via temp+rename (atomic on POSIX). Every append-only *.jsonl uses O_APPEND with a 3 KiB per-line cap so a single write() syscall publishes the entry atomically. Multi-step writes are ordered audit → state → event.

Migration from the legacy systems

Both the legacy worktree-only tasks modal and the legacy mission//mission strategic-task system are gone. There are no aliases, no shims. Any scripts that called noetic mission ... should be ported to noetic tasks .... Any UI that opened the old tasks-modal.tsx should switch to /tasks to flip into the kanban board.

The on-disk format is a clean break — there is no migration path from the legacy SQLite. Existing local task data is discarded.