Date: 2026-11-15 Status: approved by owner 2026-11-15. Nothing is built yet; phase 1 is planned.
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.
work_item (sprint, estimate), with no rework of items,
events, the board query or the policy. A builder choice that would make that hard
is wrong.com.wikantik.jdbc.Jdbc; schema changes are numbered
idempotent migrations under bin/db/migrations/; database tests run against
PostgresTestDb. Multi-statement writes get a rollback test.work_event is a functional input
and stays here.wikantik.* keys are declared in wikantik.properties first.web.xml and SpaRoutingFilter).git push. The hard guarantee
for merges comes from branch protection on the code host, configured to match. The
deployment gate is different: the deploy script can ask this system and refuse.PLAT) used in item keys (PLAT-15).software | docs | admin. A label and a filter.work_member grants a principal (a login or a wiki group) a role on a project:
| Role | May |
|---|---|
viewer | Read everything in the project |
member | Create, edit, comment, move, assign, hand off |
lead | Manage 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:
work_event is strictly append-only.work_event from_value/to_value only.draft ─▶ refining ─▶ ready ─▶ in_progress ─▶ review ─▶ done
(cancelled from any state)
draft | in_progress | done | cancelled; an epic's progress is derived from its children.CHECK constraint.ready work is claimable. An item with an open blocked_by link is not.review is assignable work in its own right, to a person or a queue.done or cancelled; each move is an event.
The gates in the autonomy table restrict agents. A human member is never locked out
of a gate, so phase 3 adds no restriction on what people could do in phase 1.work_event is append-only and written in the same transaction as the change it
records. Every change produces one: created, edited, status, assigned, claimed,
released, handed off, commented, linked, due date, membership, settings.work_item_revision holds every version of an item's title and body.work_event.implementer, reviewer, writer, …).
People are assigned directly; agent work goes to a queue.work_agent registers each agent: name (codex@docker2), vendor, runtime, the API
key it uses, and the queues it serves. Every event and claim records the agent.ready and unclaimed.
The claim names the agent and expires. An expired claim returns the item to its
queue with any open change still attached, so the next agent resumes the branch.work scope. The MCP surface is
its own endpoint, /work-mcp, so an agent does not need admin MCP rights.work_agent row bound to exactly one API key. A request is an
agent's if its key is bound to a work_agent; any other request, including one
made with an unbound work-scope key, acts as the key's or session's human owner.
actor_kind is derived this way and never supplied by the caller.work_agent. Each vendor or runtime gets its own key.work_member with
principal_kind = agent). It does not inherit the access of the person who owns
its key. An agent's role is viewer or member, never lead.wiki_cluster name, so the
agent can ask the knowledge MCP for a briefing itself.A change is a branch of work against one product, attached to one item.
open | in_review | merged | abandoned.work/PLAT-15-spa-route).done while it has a change that is open or in_review.One setting with three levels, defined by who holds each gate:
| Level | Approves as ready | Reviews | Merges | Closes |
|---|---|---|---|---|
supervised | Human | Agent or human | Human | Human |
delegated (default) | Human | A different agent, or a human | The reviewer | Agent |
autonomous | Agent | A different agent | The reviewer | Agent, then a human acknowledges |
allow_direct), set on the epic and inherited like autonomy, or set on
a single item.autonomous. An agent can never grant it.requested | approved | running | verified | failed | rolled_back.deploy_gate on the product is human or agent. With human, an agent can only
request; the request waits in the owner's lane. The gate holds inside an autonomous
epic: autonomy covers the path to merged, the product decides who releases.verified requires attached evidence (health and smoke-test output).done_means on the epic is merged (default) or in_production. Ordinary items
close at merged and later receive a "shipped in" marker from the deployment that
carried them. Items under an in_production epic cannot close until a deployment
containing them is verified.OPS-1 Production incidents) with autonomy: autonomous and
done_means: in_production. Agents may create, approve, claim and merge under it.
Each item closed with no human in the path is flagged and sits in a "done without
you" lane until a human acknowledges it. A jakemon alert reaching the on-call
automation (SimpleAgilityOnCallAutomation) is the intended trigger.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.
wikantik-work — new module shaped like wikantik-insights: the domain, the
policy and the JDBC store. Depends on neither wikantik-api nor wikantik-main.
Identity, group membership and rendering arrive through small ports.wikantik-rest — /api/work/* resources.wikantik-work-mcp (phase 2) — the /work-mcp endpoint, on wikantik-mcp-core.wikantik-frontend — the /work views.wikantik.work.enabled, default false; the feature ships dark and is
switched on per deployment. When off, migrations still apply, the module is in the
WAR but its services are not started, /api/work/* and /work-mcp return 404, and
the SPA routes stay registered while the navigation entry is hidden.| Service | How it is used |
|---|---|
| Identity | Logins, display names, groups, SSO, API keys and scopes |
| Rendering | Item bodies and comments render through the Markdown pipeline: wikilinks, Mermaid, PlantUML, math |
| Mentions | The 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 |
| Diff | The existing diff viewer over work_item_revision |
| Plumbing | wikantik-jdbc, migrations, PostgresTestDb, MCP substrate, SPA shell and shared UI components |
| Observability | Instance-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:
page link shows the page name as the author typed it. It does no
lookup of the target's title, summary or existence; the page's own access rules
apply when the link is followed. 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 ││ │
└──────────────────┘└──────────────────┘└───────────────────┘└──────────────┘└──────┘
Each phase is usable when it lands.
work scope, the
/work-mcp endpoint and tools. All four handoff directions work.PostgresTestDb; rollback tests with
FaultInjectingDataSource for every multi-statement write.Source of record: docs/superpowers/specs/2026-11-15-work-management-design.md in the Wikantik repository.