📋 Task
The fundamental unit of work. Every feature, bug fix, research, and idea flows through the Task entity.
Schema
D1 tasks table
Source of truth for all portal work items.
idTEXT PK — e.g. A66, A82. Draft
IDs use d-prefix.
nameTEXT — Human-readable task
title
descriptionTEXT — Detailed
description (markdown)
statusTEXT — draft | idea | ready
| backlog | active | done | archived
workspaceTEXT — agentic | dev |
work | life
projectTEXT — Groups related tasks
(e.g. system-redesign)
priorityTEXT — urgent | high |
normal | low
depsTEXT — Dependency task IDs
(comma-separated)
parent_idTEXT — Parent task ID for
sub-tasks
created_atTEXT — ISO
timestamp
updated_atTEXT — ISO
timestamp
Lifecycle
draft
→
idea
→
ready
→
active
→
done
→
archived
| Status | Meaning | Who Sets It |
|---|---|---|
draft |
Half-baked idea. d-prefix IDs. Own editor in Inbox → Drafts tab. | Human (portal) |
idea |
Formed idea, not yet sized or prioritized. | Clara (from inbox) |
ready |
Scoped, sized, ready to pick up. In backlog. | Human / Clara |
backlog |
Legacy alias for ready. Both treated the same. |
— |
active |
Currently being worked on. /task start sets this. |
Agent (workflow) |
done |
Work complete. /task done sets this. |
Agent (workflow) |
archived |
Soft-deleted. Hidden from active views but preserved in D1. | Clara (archive mode) |
API
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/tasks |
List tasks. Filter: ?status=active, ?workspace=agentic, ?id=A82,
?project=system-redesign |
POST |
/api/tasks |
Create task. Body: { id, name, status, workspace, ... } |
PATCH |
/api/tasks?id=A82 |
Update fields. Body: { status: "done" } |
DELETE |
/api/tasks?id=A82 |
Hard delete (use PATCH to archive instead) |
⚠️ Prefer PATCH over DELETE: The
no-delete-d1 rule mandates soft-delete via
status PATCH. Hard DELETE exists in the API but should never be used except to fix migration errors.
Design Decisions
ID format: Sequential auto-incrementing IDs like A66, A82. Drafts use d-prefix
(d-1741234567890). The "A" prefix is Agentic workspace — other workspaces use W (Work), L (Life), D (Dev).
Project is a label, not an entity: Projects group tasks via a text field, not a foreign key.
This keeps the schema flat and avoids project CRUD overhead. May be promoted to a first-class entity in the
future.
Sub-tasks via parent_id: Tasks can nest one level deep using
parent_id. The
portal renders sub-tasks inline within their parent in the tech tree.