Simple Agility Work Management Design

Date: 2026-11-15 Status: approved by owner 2026-11-15. Nothing is built yet; phase 1 is planned.

Why work management belongs in Wikantik

The Simple Agility stack needs a place where work is assigned and tracked, readable and writable by agents as easily as by people. The owner does not want JIRA or another heavy project-management tool. The work is software development with story refinement, documentation and admin work, and it moves in all four directions: human to agent, agent to agent, agent to human, human to human.

The owner is ramping up agent concurrency across several vendors and locally hosted models alongside their own work. Working directly on main will shrink to special cases, so the design must treat branches and review as the normal path.

Work management is a first-class part of Wikantik with its own tables and module. It reuses wiki services (identity, rendering, mentions, plumbing) but is not stored as wiki pages and is not an add-on glued to them.

Goals for agent-accessible work tracking

Non-goals: sprints, custom fields, multi-tenancy

Anti-goals: not JIRA, not a barnacle, no leaks

Constraints and the early human-driven assumption

Approaches considered: external tool, wiki pages, first-class tables

  1. Adopt an external tool (Vikunja, Kanboard, Plane, Beads, Backlog.md). Fastest to a board. Rejected: a second identity system and a second service, no shared rendering or cross-links with the wiki, and the agent model (queues, claims, autonomy, change tracking) would still have to be built on top.
  2. Tasks as wiki pages in a private cluster, state in frontmatter. Cheapest to start and history is free. Rejected by the owner: it is a barnacle. Every status change is a page save, concurrent agents collide like editors, activity has to be derived from version diffs, and isolation depends on every page-listing surface remembering to filter.
  3. First-class tables in a new module, wiki as a service provider. Chosen. Work items are rows; isolation is structural because items are never in the page store; events are recorded at the moment of change; the wiki supplies identity, rendering, mentions and plumbing.

The work model

Projects, products and items

Project membership and visibility

work_member grants a principal (a login or a wiki group) a role on a project:

RoleMay
viewerRead everything in the project
memberCreate, edit, comment, move, assign, hand off
leadManage members, project settings, and autonomy settings

Wiki Admins see and manage every project. For anyone else, a project they are not a member of does not exist: reads return 404, never 403, and lists omit it. Visibility is applied in one place, and every read goes through it.

Setup and administration:

Item lifecycle and handoffs

draft ─▶ refining ─▶ ready ─▶ in_progress ─▶ review ─▶ done
                                                        (cancelled from any state)

History and activity events

Assignment, agent registry and claims (phase 2)

Change tracking: branch, review, merge (phase 3)

A change is a branch of work against one product, attached to one item.

Autonomy levels: supervised, delegated, autonomous (phase 3)

One setting with three levels, defined by who holds each gate:

LevelApproves as readyReviewsMergesCloses
supervisedHumanAgent or humanHumanHuman
delegated (default)HumanA different agent, or a humanThe reviewerAgent
autonomousAgentA different agentThe reviewerAgent, then a human acknowledges

Deployments, the deploy gate and the autonomous incident path (phase 4)

Database schema by phase

Each phase ships its own migration. Phase 1 tables are shaped so later phases only add tables and columns and never rework existing ones.

-- phase 1
work_project        id, key, name, description, next_seq, default_autonomy,
                    created_at, archived_at
work_member         project_id, principal, principal_kind (user|group|agent), role
work_product        id, key, name, repo_url, default_branch, wiki_cluster,
                    autonomy_ceiling, deploy_gate, archived_at
work_item           id, project_id, seq, level (epic|story|task), parent_id,
                    product_id, kind, title, body, status, priority, rank,
                    due_on, assignee, reporter, autonomy, done_means, allow_direct,
                    version, created_at, updated_at, closed_at
work_item_revision  item_id, version, title, body, edited_by, edited_at
work_event          id, project_id, item_id (nullable), at, actor, actor_kind,
                    agent_id (nullable), type, from_value, to_value, note
work_comment        id, item_id, author, body, created_at, edited_at, removed_at
work_mention        id, item_id, comment_id (nullable), mentioned, created_at
work_link           id, item_id, kind (page|issue|url|blocked_by|commit), target

-- phase 2
work_queue          key, name, description
work_agent          id, name, vendor, runtime, api_key_id, created_at, retired_at
work_agent_queue    agent_id, queue_key
work_item           + claimed_by_agent, claimed_at, claim_expires_at

-- phase 3
work_change         id, item_id, product_id, branch, base_branch, head_sha,
                    review_url, state, merged_sha, opened_by, opened_at, closed_at

-- phase 4
work_deployment       id, product_id, environment, version, state, requested_by,
                      approved_by, started_at, verified_at, evidence
work_deployment_item  deployment_id, item_id
work_item             + ack_required, acknowledged_by, acknowledged_at

The policy columns (default_autonomy, autonomy_ceiling, deploy_gate, autonomy, done_means, allow_direct) exist from phase 1 with their defaults, and are inert until the phase that reads them.

Item keys come from work_project.next_seq, incremented in the transaction that creates the item. work_item.version is an optimistic lock: an update names the version it read and fails if the row has moved on.

Modules: wikantik-work and its surfaces

Wiki services that work management reuses

ServiceHow it is used
IdentityLogins, display names, groups, SSO, API keys and scopes
RenderingItem bodies and comments render through the Markdown pipeline: wikilinks, Mermaid, PlantUML, math
MentionsThe existing mention picker component only. Work mentions are stored in work_mention, the picker offers project members only, and they surface in the "waiting on you" lane, never on the wiki's mentions page
DiffThe existing diff viewer over work_item_revision
Plumbingwikantik-jdbc, migrations, PostgresTestDb, MCP substrate, SPA shell and shared UI components
ObservabilityInstance-wide counts by status, level and kind, and claim and gate outcomes, on /metrics. No project, product or item labels: a project's existence is confidential

Comments are a separate table from wiki comment threads, which are anchored to a passage of a page.

Rendering rules that keep the two sides apart:

Board, dates, activity and item views

 Work ▸ PLAT Platform        [Board] [Dates] [Activity]    product ▾  assignee ▾
┌ Waiting on you (2) ─────────────────────────────────────────────────────────┐
│ PLAT-15 review requested by codex@docker2 · PLAT-9 deployment needs approval │
└──────────────────────────────────────────────────────────────────────────────┘
┌─ Refining (2) ───┐┌─ Ready (3) ──────┐┌─ In progress (2) ─┐┌─ Review (1) ─┐┌ Done ┐
│ PLAT-21 story    ││ PLAT-15 task     ││ PLAT-13 story     ││ PLAT-14      ││  …   │
│ wikantik         ││ wikantik · P1    ││ claude@ws · 2d    ││ jakemon      ││      │
│ 3 comments       ││ due Nov 22       ││ 1 open change     ││ in review    ││      │
└──────────────────┘└──────────────────┘└───────────────────┘└──────────────┘└──────┘

Delivery phases

Each phase is usable when it lands.

  1. Core. Projects, members, products, items, revisions, events, comments, links; visibility; REST; the board, dates, activity, item and epic views. Human-to-human work is complete.
  2. Agents. Queues, agent registry, claims with expiry, the work scope, the /work-mcp endpoint and tools. All four handoff directions work.
  3. Changes and autonomy. Change records, the review and merge gates, the three levels and their inheritance.
  4. Deployments and incidents. Deployment records, the product gate, the deploy-script check, the "done without you" lane, the jakemon trigger.

Testing: visibility, leaks, concurrency, policy

See also

Source of record: docs/superpowers/specs/2026-11-15-work-management-design.md in the Wikantik repository.