Task Monki
Overview

Product Workflow

Date: 2026-08-29

Task Monki is a local task execution and evidence system for AI coding work. It is not just an AI chat UI.

Product model#

  1. User creates a task in one repository with a goal, model, and reasoning effort.
  2. Task Monki prepares an isolated Git worktree.
  3. The selected coding-agent runtime runs in that worktree.
  4. Task Monki records provider activity, approvals, Git evidence, GitHub delivery evidence, and audit history.
  5. User reviews, requests changes, follows up, continues unfinished runs, retries, forks alternatives, commits, opens a draft PR, or marks done.

Repository context#

Each repository has a stable Task Monki ID. Tasks and worktrees reference that ID; the checkout path is a mutable repository attribute. Moving or reconnecting a checkout updates the repository record without changing task identity.

The sidebar repository selector sets the default for new tasks and provides repository lifecycle controls. It does not filter global workflow views, counts, or task detail. Adding a repository opens the local folder picker, validates the selected Git checkout, and stores a new repository record. Refresh can mark a checkout missing or invalid. Disconnect preserves every task and evidence record, while repository-dependent actions stay unavailable until the same repository ID is reconnected to a valid path.

On first launch, when no repository has been configured, the main workflow area shows setup instead of an empty board. Adding a repository completes only the repository step. The setup surface puts the default model above the tool checks that it controls. It stays open until the user explicitly finishes setup before entering the board and creating tasks. A user can enter Designs without a source repository because standalone Designs use Task Monki-managed storage. Finishing setup re-checks required Git and the selected default agent runtime before the completion flag is saved; GitHub CLI remains optional because it only affects PR delivery. A passively discovered on-demand runtime is startable but is not labeled Ready until its runtime-owned live check succeeds. Authentication, account incompatibility, and protocol failure remain distinct states with explicit next actions.

New tasks default to the selected sidebar repository. The composer selects a repository by ID and never accepts a repository path as task identity. Capturing a text-only task is a local operation and remains available when the selected agent runtime is unavailable; live model resolution is deferred until Start. Attachment-backed creation still requires a runtime/model with an enabled delivery path for each selected content type. Task Monki validates the model input types before it adopts the draft.

The New Task composer is a parallel workspace panel rather than a modal decision. Closing it preserves title and description text for the current app session, while unsubmitted attachment batches are still discarded. A successful Create clears the preserved text draft. The Profile dropdown inside the task and Design composers selects reusable instructions at creation. Existing tasks and Designs keep their saved instructions when the library changes.

Refine is a reversible proposal, not an automatic append or overwrite. One short-lived read-only agent run receives the current title and description. It also receives the selected downstream model capabilities and supported staged attachments. The prompt tells the agent not to modify files. The adapter also applies its provider-native restriction when one is available. Task Monki grants only the exact selected attachments. It does not grant app-owned web, MCP, app, dynamic-tool, or approval access for the turn. An ACP provider can still expose its own tools when its native policy permits them. The provider process can still use its model transport. The agent first decides whether repository or attachment inspection can materially improve the request. Clear, small tasks may use no repository tools; ambiguous or cross-cutting tasks start in the likely relevant area and broaden only when inspected dependencies justify it. The run returns a standalone rewrite plus path-free inspection evidence. Core accepts repository paths and attachment observations only when they match files that were actually made available to that run. Task Monki compares repository state before and after the turn. If the repository changes, Task Monki rejects the result and leaves the changes as evidence. If refinement cannot be validated, the original request remains unchanged with a visible warning.

The composer locks refinement inputs while that run is active, cancels the run when the panel closes, and accepts a proposal only while its repository, title, description, target model, and attachment revision still match. Project and Task Monki instructions remain downstream instructions; refinement does not copy their generic rules into every task prompt.

Runtime and model configuration#

First-launch defaults, New Task, and Settings use the same runtime/model selector. Implementation defaults can use every enabled runtime. Prompt refinement, review, and Discourse use one shared read-only support projection. All ready runtimes and models can use this path. Preview recipe generation normally uses that path. An adapter can instead use the app-owned disposable evidence copy, which contains no source repository path. An unavailable or unauthenticated runtime remains visible with its exact readiness reason. Reasoning choices come from the selected model's native catalog.

Discourse#

Discourse is a global technical conversation workspace beside task workflow. It supports human-only notes, one-agent Direct replies, independent two- or three-agent Panels, and a bounded Team sequence in which Lead answers, Skeptic and Verifier review exact claims, and Lead may append one attributable correction. It never creates a hidden task or treats an agent response as Git, test, GitHub, workflow, or acceptance evidence.

Task and repository context is explicit per message or explicitly pinned. Agent turns use immutable context snapshots and a clear instruction not to modify files. Adapters also apply their provider-native restrictions when available. Task Monki grants no app-owned external tools for these turns and compares repository state after the turn. Provider-owned tools remain subject to the selected native policy. Runtime and model identity remain frozen in participant revisions. A reply is never silently rerouted to the current default runtime. All ready runtimes and models are offered. Unavailable runtimes remain visible with their reason instead of falling back.

See docs/workflows/GENERAL_AGENT_DISCOURSE_LIFECYCLE.md for response policies, waiting, review/correction, stale context, cancellation, recovery, and limits.

Provider catalogs keep their native scope. Cursor model discovery begins only after the user selects Cursor and its current ACP process has no cached catalog. Loading, failure, and retry remain inside the selector. The adapter reuses the catalog for that process and invalidates it when the executable configuration, process identity, or observed authentication state changes.

Saved views#

All tasks is the global workflow view. A board is only a named saved filter over current tasks, using zero or more repository IDs and workflow phases. Empty filter lists mean all repositories or all phases. Boards never store task IDs, own task membership, or carry workflow state. A board color is presentation metadata used to distinguish saved views in navigation; it does not affect the filter. Editing or deleting a board does not mutate any task.

The new-task attachment flow accepts a bounded set of PNG, JPEG, and still WebP images plus UTF-8 text, data, configuration, and source-code files. Picked, pasted, and dropped files are copied into an app-managed local task directory only when Create is pressed; Task Monki never stores their original paths or places them in the repository worktree. The composer uses Chromium's native decoder to re-encode images before submission so embedded metadata is not copied. PDFs, Office files, video, audio, archives, databases, and arbitrary binaries are not supported. Codex uses verified local-image inputs and managed path references. OpenCode uses bounded native file parts. Qualified ACP profiles use their native text or image blocks. The composer uses the effective runtime and model projection for each content type. Negotiated ACP support is the default. A tested provider-local exception can correct one false capability flag and must show a diagnostic. Task Monki does not provide a generic extraction pipeline.

Provider delivery is runtime-specific and fail-closed. A restricted Codex session uses a complete permission profile for the exact worktree and verified files. The task's network and full-access settings do not change only because the task has attachments. These settings define provider access, not file delivery eligibility. In the packaged app, the user's Codex web search, MCP server, and app choices remain in effect. Enabling those integrations means trusting them with the task content the agent can provide. Browser development keeps its separate rule that forces those integrations off.

Files stay renderer-local during editing and cross the trusted boundary in one bounded batch. A successful task create atomically adopts that batch as one private immutable task directory. The composer reuses one task-creation token across retries: if the response is lost after a durable create, the same request resolves to the already-created task instead of failing on the consumed draft or creating a duplicate. Changing the request while reusing that token is a conflict. Only an ambiguous response preserves the staged batch for an unchanged retry; ordinary failure or cancel discards it. Task detail shows durable attachment metadata; Debug can show path-free evidence that the verified bytes were submitted with a provider turn, but never presents that as proof that the model read or used the file. See docs/architecture/ATTACHMENT_LIFECYCLE.md for limits, delivery, portability, cleanup, and privacy semantics.

Task records remain bound to exactly one repository ID. Runs, worktrees, Git evidence, GitHub delivery, and provider sessions resolve through task and iteration records rather than the current sidebar default or a saved view. Switching the default repository never closes or mutates an open task.

UI priority#

Screens should prioritize:

  1. user action required: approvals, input, permission requests;
  2. safety or recovery risk: runtime lost, ambiguous mutation, stale request;
  3. verified delivery evidence: Git, PR, checks, reviews, merge;
  4. available user actions: start, follow up, continue, retry, fork alternative, review, commit, PR;
  5. provider telemetry: plans, items, usage, raw protocol.

Provider telemetry is useful, but it should not visually dominate pending user decisions or verified local evidence.

Import existing work#

The task composer can attach an existing primary checkout or registered linked worktree. Import keeps its named branch, files, index, Git configuration, and external agent sessions unchanged. It creates an idle In Progress task without starting an agent. A duplicate checkout or repository-and-branch selection opens the existing task, including an archived task. Separate clones remain distinct.

The composer filters checkouts by branch or folder and keeps the selected checkout visible. Import uses a branch-derived title without requiring a description. New work still requires a description. Each mode keeps its own text draft.

The comparison preview reads Git without changing the checkout or creating a task. It shows commit and uncommitted-file counts, with up to 50 commits and 100 file paths in the change list. Local branch uses the local counterpart of origin/HEAD, then main, master, or the registered repository branch. Users can instead choose HEAD or enter a local branch or commit. Clean checkouts remain importable. Git conflicts and unfinished operations block import. Import resolves the comparison again and rechecks checkout identity and Git evidence before saving the task.

The selected comparison includes committed, staged, unstaged, and untracked work. HEAD at import time gives a dirty-only starting comparison. Ordinary refresh keeps that resolved base. Change comparison in Evidence, beside the diff, to rebuild evidence and make the previous review stale. Older evidence keeps its original comparison.

Run agent review starts detached review directly before the first coding run. Task Monki checks Git and runtime readiness before entering Review. Start implementation requires an explicit instruction and warns that coding changes the original imported checkout. Address findings and Investigate checks supply that instruction through the same first-run path. Later unsuccessful runs still require retry or continuation before review. Retry retains the original instruction from the runtime prompt artifact; it does not rewrite the source task description or provider-native goal.

A new PR requires a separate target branch. A HEAD or commit comparison can remain unchanged. An existing PR keeps its target branch.

Task Monki observes external work on task open, app focus, and manual refresh. It does not watch files or poll Git. Focus observation pauses during actions, dialogs, and native pickers. Other editors can change files after observation; Task Monki rechecks identity and evidence at action boundaries.

Reconnect checkout selects the same repository and branch at a new registered path. It never creates a missing checkout. Old runs retain their historical paths, and subsequent coding uses a fresh session after a move.

Local preview#

Preview is independent of task workflow phase and provider-run state. The Overview card presents the current Preview decision and stable primary route; the full workspace presents capability approval, selected data scenario, application/setup evidence, bounded logs, routes, owned data, external attachments, private-input readiness, cleanup authority, and recovery actions.

Native replacement preserves the current route while a candidate starts and makes cancellation candidate-only. Compose replacement is a serialized stable project update with an explicit route-downtime window after activation begins. Stop Preview & Delete Data and managed-resource Reset are intentionally destructive only for exact Task-Monki-owned runtime/data. Attached dependencies, producer tasks, external Compose objects, images, build cache, repository files, and user-owned secret files are never included in that authority.

The Preview Guide is the public behavior and recipe reference. Preview Architecture is the canonical lifecycle, security, storage, ownership, shutdown, and recovery source. Keep product copy and action rules consistent with those documents rather than adding a second Preview lifecycle here.

Activity Timeline#

The Overview may show Activity Timeline below PR Status. It is a curated task history, not a log viewer.

Activity Timeline should answer what changed, who or what caused it, whether anything is blocked or stale, and what the next useful action is likely to be. It is derived from stored Task Monki domain events, task projections, run records, Git evidence, and GitHub delivery rollups. It must not treat raw provider text or raw GitHub responses as workflow truth.

The timeline shows the latest bounded window of useful activity in chronological order with stable absolute timestamps. It must not render relative labels such as "now" for stored events, because reopening a task should not imply the event just happened.

Tone is expressed by the row's single status dot. Timeline text stays neutral; do not add colored chips, tinted row backgrounds, colored borders, or repeated status labels. Supporting details should be collapsed behind an in-row disclosure only when they name concrete evidence and the decision it affects, such as the exact failed GitHub check that blocks PR readiness.

Main-history items should be consequence-bearing: terminal implementation or review outcomes, current active runs, Git state changes, delivery commits, branch publication results, first PR availability, check verdict changes, GitHub review decisions, merge outcomes, blocked transitions, stale agent review state, and recovery risks.

No-op refreshes, repeated unchanged evidence captures, provider protocol details, raw item traffic, goal/plan/usage telemetry, PR body artifact creation, and healthy verification pings belong in Debug or supporting evidence surfaces, not in Activity Timeline.

PR Status remains the current GitHub delivery surface. Activity Timeline can summarize meaningful delivery verdict changes, but it must not duplicate PR actions or become a second source of delivery truth.

The renderer should derive both Overview Activity Timeline and Debug Task activity from the same task activity model. Overview is a compact projection of the canonical activity ledger; Debug may show the fuller curated ledger plus the raw domain-event audit. Do not maintain a second event-to-label switch for Debug, because delivery/review facts such as exact failed checks, stale evidence, blocked transitions, and merge state must be interpreted consistently across surfaces.

Workflow phases#

  • Backlog / Ready
    • Task exists and can be prepared or started.
  • In Progress
    • Implementation-side work is active, being corrected, or waiting for a retry after an unsuccessful run.
  • Review
    • Implementation-side work completed successfully and is ready for inspection, review gate, acceptance, commit, or PR creation.
  • In Review
    • A PR or external review process exists.
  • Done
    • Work is marked done locally, merged, or explicitly marked complete.

Other phases such as Blocked, Canceled, or Archived are exceptional states and should explain what action is needed to recover.

Main flow#

flowchart LR
  Ready["Ready"] --> Prepare["Prepare worktree"]
  Prepare --> Start["Start implementation"]
  Start --> Progress["In Progress"]
  Progress --> Terminal{"Run outcome?"}
  Terminal -->|Completed and locally ready| Review["Review phase"]
  Terminal -->|Completed but locally blocked| Recover["Continue or retry"]
  Terminal -->|Failed / interrupted / recovery| Recover
  Recover --> Progress
  Review --> Gate["Run agent review"]
  Gate --> Passed["Review passed"]
  Gate --> Changes["Needs changes"]
  Changes --> FollowUp["Request changes"]
  FollowUp --> Progress
  Passed --> Accept["Accept / commit / PR"]
  Accept --> Done["Done or In Review"]

Review workflow#

There are two separate review concepts:

  • Review phase
    • Task workflow state. The work is ready to inspect or ship.
  • Agent review gate
    • Detached AI quality check on the current diff.

Rules:

  • Running agent review keeps the task in Review.
  • Requesting changes starts follow-up implementation work and moves the task to In Progress.
  • The previous review becomes stale as soon as implementation changes continue.
  • A stale review can remain visible as context, but its findings are not current actions.
  • Delivery actions are paused while review-derived follow-up work is running.
  • After follow-up completes, the task returns to Review and needs a fresh review.

The detailed source of truth is docs/workflows/AGENT_REVIEW_WORKFLOW_LIFECYCLE.md.

Action rules#

Ready:

  • Prepare worktree.
  • Start implementation once the worktree exists.

In Progress:

  • Show the active implementation-side run.
  • In Overview, keep the provider plan as the primary progress structure. For a running run, a compact activity tail may summarize recent provider telemetry such as reads, searches, file changes, verification commands, tool calls, and approval waits. This tail is context only; completed, failed, interrupted, and recovery-required runs should return to the plan plus local-evidence footer. The detailed data flow and invariants are documented in docs/workflows/AGENT_PROGRESS_OVERVIEW.md.
  • Allow steering, approval/input responses, and interrupt controls.
  • A native structured question from Codex, OpenCode, or an ACP form puts the exact active run in Needs input and shows its choices or free-text fields. Submit one answer to that same run and keep the interaction visible as responding until the native protocol confirms delivery or lifecycle cleanup. A normal prose question is not a blocking interaction. Design agents must use structured questions or make a reasonable decision and continue.
  • After an interrupted, lost, or recovery-required implementation run, keep the task in progress and make Continue work the primary recovery action. After a definitive failure, make Retry implementation primary. Both actions and Fork alternative remain available; do not offer agent review.
  • A provider may finish its turn after the user declines an execution request. If Task Monki then observes the same Git HEAD and dirty fingerprint as before that run, keep the task in progress and make Retry implementation primary, with Continue work and Fork alternative also available. The provider turn remains completed telemetry, but the implementation is not review-ready. Persist this as a run-scoped implementation retry requirement; ordinary Git, GitHub, or workflow updates do not clear it. Starting replacement implementation work clears it.
  • Do not show review completion actions.

Review:

  • Show verified evidence prominently, with PR Status as the primary delivery surface.
  • Allow Run agent review when no implementation-side run is active.
  • Require the current implementation-side run to have completed successfully; unsuccessful or older superseded runs are not valid review sources.
  • Imported work in Review can start review before its first coding run.
  • Allow Request changes only when the current review result has actionable current findings.
  • Allow Mark done and Commit when not paused by an active run or review.
  • Keep Create draft PR and Push update in PR Status, not duplicated in Finish.
  • Treat Mark done anyway as an explicit owner override when review or Git evidence is missing, stale, failed, dirty, unavailable, canceled, inconclusive, or unresolved.

Post-run implementation controls:

  • Follow up
    • Normal next implementation action after a completed run when the owner wants another pass in the same task, worktree, branch, and provider session.
  • Continue work
    • Resumes unfinished work from the current state in the same task and worktree, reusing recoverable provider context. Additional continuation guidance is optional. It is primary after interruption, runtime loss, or ambiguous recovery.
  • Retry implementation
    • Makes another attempt at the authoritative original implementation goal after a definitive failure or locally blocked outcome. It inspects current Git and external state before acting and must not blindly repeat operations that may already have caused side effects. It may reuse the provider session and worktree internally, but it does not imply a clean reset.
  • Fork alternative
    • Creates a separate task with its own worktree, branch, iteration, run, and fresh provider session.

An ordinary successful completion offers Follow up and Fork alternative, not Retry implementation. A run proven active after reconnection exposes normal running controls, not Continue work or Retry implementation.

A RECOVERY_REQUIRED run also offers Abandon recovery. This explicitly closes the ambiguous run without resubmitting it; it does not delete the task, worktree, or independently verified results. Already terminal interrupted or lost runs do not need this separate resolution action.

In Review:

  • Prioritize PR Status: one linked PR identity, one headline, exact check rows when available, review line when delivery-affecting, merge line when known, and freshness.
  • For failed checks, show the Investigate failure action and expandable check rows instead of repeating a prose explanation of the failure.
  • Allow GitHub refresh actions.
  • Offer failing-CI investigation only when the selected PR Status state is Checks failed; stale, diverged, or locally unpublished work should surface its own next action instead. Investigation starts implementation-side work, not a GitHub state update.

Done:

  • Show final evidence and completion route.
  • Avoid active agent controls unless the task is explicitly reopened.

Archive and delete#

Task menus expose both archive and delete.

Archive is a non-destructive workflow transition to ARCHIVED. It removes the task from active workflow handling but keeps Task Monki records, evidence, worktree records, artifacts, provider session references, and source/alternative links. Archive is blocked while a task-owned run or provider request is active.

Delete is permanent and applies only to the selected task. It deletes the selected task record and Task Monki-owned records scoped to that task: task iterations, runs, domain events, artifacts, provider session/item/plan/usage records, interaction requests, Git snapshots, GitHub delivery snapshots, pull request/check/review/merge evidence, and worktree records. It also removes links in other tasks that point at the deleted task. Deleting a source task never deletes fork alternatives; deleting a fork alternative never deletes its source task or sibling alternatives. If task deletion publishes its store snapshot but parent-directory synchronization is ambiguous, managed artifact files are retained until startup reconciles them against durable artifact records. Reconciliation deletes only unreferenced files matching the strict Task Monki artifact filename contract; unknown files and directories are left untouched, while symbolic links and special entries fail closed.

Local worktree removal is explicit and separate from task deletion. It is never enabled by default, and Task Monki blocks removal when the worktree has uncommitted, untracked, or conflicted files. External checkouts cannot be removed through task deletion, even when clean. Deleting a task never deletes the original repository, remote branch, pull request, commits, Git history, merge history, or provider remote thread data.

Finish task actions#

  • Mark done
    • Moves the task to Done in Task Monki without creating another commit or PR. It is only available as the clean local-completion path when the task completion policy says the task is complete enough.
    • New tasks start as LOCAL_ACCEPTANCE. When Task Monki records a linked PR for the task, that task moves to the MERGED completion policy. This is a task-scoped policy transition, not a provider verdict.
    • PR evidence must not downgrade stricter or explicit policies such as MERGED_AND_VERIFIED or MANUAL.
    • LOCAL_ACCEPTANCE remains the local-only path. Mark done records local acceptance and does not reinterpret any separately observed PR evidence.
    • For MERGED tasks, GitHub merge evidence is a hard requirement. The Finish panel should show a Merge requirement and keep Mark done disabled until merge evidence is MERGED.
    • For MERGED_AND_VERIFIED tasks, GitHub merge evidence and passing GitHub checks for the same merged PR head are hard requirements before Done.
    • Merged PR evidence may move eligible merge-policy tasks to Done automatically. It must not auto-complete MANUAL tasks or MERGED_AND_VERIFIED tasks whose GitHub checks are missing, not passing, or passing for a different PR head than the merge evidence. It also must not bypass implementation work, a failed or retry-required implementation, or a running detached review.
  • Mark done anyway
    • Moves the task to Done in Task Monki despite missing or non-passing review, or Git evidence. It should be styled and confirmed as an owner override, not a review action. It must not override a MERGED completion policy that is still waiting on GitHub merge evidence.
  • Commit
    • Secondary/manual delivery step for users who want local Git control before publishing or opening a PR.

A Task Monki delivery commit records the current task worktree into Git. It is delivery progress, not follow-up implementation work. If the reviewed diff was still current immediately before the delivery commit, the commit does not make the agent review stale by itself.

If a review is running or a follow-up implementation run is active, finish actions should be disabled with a clear reason.

PR Status#

PR Status is the primary GitHub delivery surface. Task Monki creates or reuses one draft PR for the Task Monki-owned branch, then records PR identity, check details, GitHub review rollup, merge state, and whether the PR head is fresh against the local worktree.

Create draft PR and Push update are shown only here. Create draft PR opens a small confirmation dialog where the user can edit the default PR title before creation. The title is request metadata for a new PR only; if Task Monki finds an existing open PR for the task branch, it reuses the observed PR instead of renaming it. The action must be disabled with a clear reason when local Git evidence cannot satisfy the service publish guard, such as no task changes, missing worktree, unresolved conflicts, branch divergence, or a rejected remote push caused by newer remote commits. Recoverable publication failures, such as GitHub authentication or transient network errors, should be shown as the last failure while leaving the action retryable.

The UI should render one headline from those facts instead of separate competing badges. Headline priority is:

  1. Merged.
  2. Closed without merge.
  3. Branch diverged or stale.
  4. Local changes not pushed.
  5. PR has newer commits.
  6. Checks failed.
  7. Checks pending, canceled, or no required checks ran.
  8. GitHub changes requested.
  9. GitHub review waiting.
  10. Ready to merge.
  11. Draft PR.
  12. Open PR.
  13. Unknown.

Closed without merge is a terminal status for that PR snapshot, but it may still offer Create draft PR when the task branch remains publishable. Merged PRs do not offer Create draft PR or Push update.

GitHub checks are normalized into passed, failed, pending, skipped, and canceled buckets from gh pr checks. Canceled checks are distinct from failures, but they still block ready-to-merge status until GitHub reports merge readiness. Ready to merge requires explicit current PR, check, review, and merge evidence for the same PR head; absent check or review evidence must not be treated as success. The PR number is the link to GitHub; do not add a separate Open PR button when the number can be rendered as a link.

The detailed PR Status source of truth is docs/workflows/PR_STATUS_CARD_FLOW.md.

Fork alternatives#

Fork alternative creates a separate task and isolated worktree/branch for a fresh alternative attempt. The source task records the alternative task id, and the alternative task records its source task and source run. Provider session history does not need to be reused.

If alternative setup fails after the alternative task is created, the partial alternative remains visible as a blocked task with its worktree/setup error recorded. It must not be hidden behind only the source task's failed action.

After creation, the source and alternative tasks are independent execution units. Follow-up, retry, review, accept, commit, and PR actions on one task must not mutate the other task. The source/alternative links are traceability metadata only; comparison UI can use them later, but there is no shared workflow state between the tasks.

Was this page helpful?

Powered by Docsbook