---
title: Scrolls
scope: 3dmk
type: documentation
subject: scrolls
group: Systems
status: current
version: "2.1.3"
source: https://3dmk.com/documentation#scrolls
author: Nick Olson
contact:
  email: 3dmk@3dmk.com
  site: https://3dmk.com
license: CC BY 4.0
license_url: https://creativecommons.org/licenses/by/4.0/
attribution: Nick Olson, 3dmk.com
---

# Scrolls

Scrolls is the work-management system for the development environment. A large request is too vague to hand to an agent. Scrolls breaks it into initiatives, epics, stories, tasks, bugs, and subtasks. Each item carries its goal, context, order, and current state, so an agent receives a defined queue in place of an open request.

## Role

Scrolls sits between planning and execution. A project’s planning document in Seele seeds the initiative and its work items. Agents reach Scrolls through Core Model Context Protocol (MCP) tools. Each agent takes items from its queue. It marks each item complete after it finishes the work. Work can pause, resume, and move between agents without loss of context.

Scrolls replaced an earlier Jira integration. Its hierarchy follows the Jira model with one change: An initiative can hold stories, tasks, and bugs directly when an epic adds no value. Its context model and agent controls are purpose-built.

## Parts

Four parts make up the system.

| Part | Role |
|---|---|
| `core-scrolls-api` | Python and FastAPI service, and the only reader and writer of the Scrolls database |
| PostgreSQL | Stores every theme, work item, agent, and lookup value |
| Schema repository | Owns the database patches, apart from the service code |
| Core MCP tools | A set of 50 typed operations for the full lifecycle of a work item |

Inside the service, HTTP routing, business logic, and SQL sit in separate layers. Dataclasses mirror the database tables one to one. A write that spans several statements commits whole or not at all.

## Data

The hierarchy runs from theme down to subtask. Each level has a defined scope.

| Level | Holds | Scope |
|---|---|---|
| Theme | Initiatives | A product domain |
| Initiative | Epics, stories, tasks, and bugs | A cross-cutting objective within a theme |
| Epic | Stories, tasks, and bugs | A cohesive chunk of work within an initiative |
| Story | Subtasks | Documentation, process, or design work that fits one conversation |
| Task | Subtasks | Code, configuration, or infrastructure work that fits one conversation |
| Bug | Subtasks | One isolated, reproducible defect |
| Subtask | None | One atomic action inside a story, task, or bug |

Every row has a permanent universally unique identifier (UUID) key and a kebab-case name. Work items also carry a readable identifier such as `MCP-TASK-002-000003`. Its segments give the initiative code, the item type, the epic sequence, and the item sequence.

Lookup tables fix the allowed status, priority, size, and action values. Each size maps to a default agent: `small` to Haiku, `medium` to Sonnet, and `large` to Opus. List operations return lightweight fields only. The agent specification, document references, dependencies, and subtasks come back only from a detail read.

## Connections

Scrolls exchanges data with four systems.

| System | What passes between them |
|---|---|
| Core MCP | Agent calls, forwarded to the service after a fresh Consul lookup on each call |
| PostgreSQL | All Scrolls records |
| Seele | Planning documents, which an agent turns into initiatives, epics, and work items |
| NervHQ | Initiative progress, roadmap views, and work-item detail on the dashboard |