Manager

Manager is a local-first WorkItem graph for project planning, agent coordination, review, and closure.

It gives humans and agents one small planning object, WorkItem, and lets that object nest into a tree with mirrored blocker relationships. A large change can be split into product, design, development, security, QA, documentation, and release work. Each item carries the information an agent needs to understand the work: definition, goal, scope, boundary, priority, status, assignee, blockers, children, and closing context.

The result is a simple project-management system that can act like a checklist, a dependency graph, a review queue, and an agent work ledger.

What It Is For

Manager is useful when work needs more structure than a flat issue list:

• Agent-driven projects where workers and reviewers need explicit task boundaries.
• Large changes that must be broken into small reviewable units.
• Review workflows where findings become child WorkItems that block closure.
• Local project planning where state should live in a simple JSON file.
• Teams that want a dense web view, HTTP API, and MCP service over the same work graph.

Core Idea

Every item in the system is a WorkItem.

WorkItem
  WorkItem
    WorkItem
  WorkItem

A parent represents a larger goal. Children represent the work required before that parent can close. Leaf WorkItems are the usual execution queue for workers.

Blockers are graph edges:

SEC-1 Security review
  blocks -> OPS-2 Release go/no-go

OPS-2 Release go/no-go
  blockedBy -> SEC-1 Security review

The service mirrors blocks and blockedBy automatically. Adding either side creates the other side.

Quick Start

Prerequisites

• Node.js 18 or newer
• npm
• Encore CLI

Install the Encore CLI on macOS:

brew install encoredev/tap/encore

For Windows, Linux, and current platform-specific instructions, use the Encore TypeScript installation guide.

Update an existing Encore CLI:

encore version update

Run Locally

Install dependencies:

npm install

Check local prerequisites and ports:

npm run doctor

Start the backend and web app:

npm run dev

Open the web UI:

http://localhost:3000

The backend listens on:

http://127.0.0.1:4000

Use alternate ports when needed:

MANAGER_BACKEND_PORT=4100 MANAGER_WEB_PORT=3100 npm run dev

Create Your First WorkItems

The web UI is for visibility and inspection. Create and update WorkItems through the HTTP API, MCP service, or your own tooling.

Create a root WorkItem:

curl -sS -X POST http://localhost:4000/work-items \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "release-readiness",
    "name": "Release readiness",
    "type": "OPS",
    "priority": "high",
    "scope": "Prepare the project for a release decision.",
    "boundary": "Covers release readiness only. Implementation changes belong in child WorkItems.",
    "goal": "Reach an evidence-backed release decision.",
    "definition": "Create and close all product, development, security, QA, and documentation work required for release readiness."
  }'

Create a child WorkItem:

curl -sS -X POST http://localhost:4000/work-items \
  -H 'Content-Type: application/json' \
  -d '{
    "parentId": "release-readiness",
    "id": "security-review",
    "name": "Perform security review",
    "type": "SEC",
    "priority": "critical",
    "scope": "Review attacker-controlled inputs, trust boundaries, failure behavior, and sensitive output.",
    "boundary": "Review only the release candidate surface. Remediation work belongs in child FIND WorkItems.",
    "goal": "Identify confirmed security issues that block release.",
    "definition": "Complete a source-backed security review and create precise child FIND WorkItems for confirmed issues."
  }'

Create another child and block it on security review:

curl -sS -X POST http://localhost:4000/work-items \
  -H 'Content-Type: application/json' \
  -d '{
    "parentId": "release-readiness",
    "id": "release-go-no-go",
    "name": "Perform release go/no-go",
    "type": "OPS",
    "priority": "critical",
    "scope": "Review all release readiness evidence.",
    "boundary": "Decision only. Follow-up implementation belongs in child WorkItems.",
    "goal": "Record the final release decision.",
    "definition": "Close only after required child work is closed and the release decision has clear closing context."
  }'

curl -sS -X POST http://localhost:4000/work-items/security-review/blocks \
  -H 'Content-Type: application/json' \
  -d '{ "targetId": "release-go-no-go" }'

Ask for the next workable item:

curl -sS http://localhost:4000/work-items/next

WorkItem Model

Each WorkItem has these fields:

Field	Purpose
id	Stable API and MCP identifier.
name	Human-readable item title.
type	Short work category such as PRD, TDD, DEV, SEC, FIND, QA, DOC, or OPS.
caseNumber	Type-scoped display number such as DEV-1 or SEC-3.
expanded	Persisted tree expansion state for the web UI.
assignee	Current owner, or null.
priority	String priority label. Known labels are ranked by the service.
status	Stored workflow state.
definition	The work and completion standard. This is the main task contract.
goal	Intended outcome.
scope	Work included in this item.
boundary	Ownership limit for this item.
closingContext	Final closure record with evidence or review rationale.
blocks	WorkItems blocked by this item.
blockedBy	WorkItems that block this item.
children	Nested WorkItems required before this item can close.

Stored statuses:

open
active
review
in_review
closed

blocked is computed from unresolved blockers. It is reported as an effective status and never stored as the item status.

Known priorities, highest to lowest:

critical
urgent
high
normal
medium
low
none

Unknown priority labels are allowed and sort below known labels.

Agent Workflow

Manager is designed around a small, repeatable agent loop:

1. Create a top-level WorkItem for the requested change.
2. Split large work into child WorkItems with clear definitions, goals, scopes, and boundaries.
3. Add blocker relationships for real sequencing or closure dependencies.
4. Let worker agents claim unblocked leaf WorkItems.
5. Workers set their item to active while working.
6. Workers set their item to review when they believe the definition is satisfied.
7. Reviewers set the item to in_review while actively reviewing.
8. Reviewers close complete work with closingContext.
9. Reviewers create child FIND, SEC, QA, or other WorkItems for confirmed gaps.
10. Open child findings dynamically block the parent until they close.
11. Parent WorkItems close after descendants close and parent-level review is complete.

This keeps work small at the leaf level while preserving the full path from a large change to every item needed for closure.

Queue Semantics

GET /work-items/next returns the highest-ranked open, unblocked leaf item.

Queue ranking:

1. FIND and SEC WorkItems first.
2. Larger active unblock impact first.
3. Known priority order.
4. Tree depth, creation time, case number, and name.

Dashboard queues:

• workableItems: open, unblocked leaf WorkItems.
• reviewItems: stored-review WorkItems with resolved blockers.
• inReviewItems: stored-in_review WorkItems with resolved blockers.
• blockedItems: WorkItems with unresolved explicit blockers or unresolved child work.

HTTP API

The backend exposes these local endpoints:

GET  /dashboard
POST /reset
POST /work-items
POST /work-items/:workItemId
POST /work-items/:workItemId/status
POST /work-items/:workItemId/blocks
POST /work-items/:workItemId/blocks/remove
POST /work-items/:workItemId/blocked-by
POST /work-items/:workItemId/blocked-by/remove
GET  /work-items/next

POST /reset clears local state. Use it only for experiments or fresh local starts.

MCP Server

Run the MCP server:

npm --workspace @manager/backend run mcp

MCP tools:

• manager.dashboard
• workitem.create
• workitem.update
• workitem.set_status
• workitem.add_blocks
• workitem.remove_blocks
• workitem.add_blocked_by
• workitem.remove_blocked_by
• workitem.next

MCP resources:

• manager://dashboard
• manager://work-items
• manager://work-items/queue
• manager://work-item/{workItemId}

Codex Skill

This repository includes an installable Codex skill for Manager WorkItem operations at skills/manager.

Example Codex prompt:

Use $skill-installer to install the Manager skill from https://github.com/jmillpps/manager-web/tree/main/skills/manager

Restart Codex after installing the skill.

Web UI

The web app is a dense nested table for visibility and inspection. It shows:

• WorkItem case label and name.
• Assignee.
• Priority.
• Effective status.
• Child counts.
• Items blocked by this item.
• Items blocking this item.
• Persisted expand and collapse state.
• Detail modal with definition, goal, scope, boundary, dependencies, children, timestamps, and closing context for closed items.

Project Layout

apps/backend       Encore.ts API, MCP server, and JSON file store
apps/web           Next.js nested WorkItem table
packages/contracts Shared TypeScript records and API payloads
.data              Local runtime state generated by the backend

Development

Run checks:

npm run typecheck
npm test

Build the web app:

npm run build:web

Run only the backend:

npm run dev:backend

Run only the web app:

npm run dev:web

The web app reads the backend URL from NEXT_PUBLIC_MANAGER_API_BASE. The default is http://localhost:4000. Copy .env.example when you need to override it.

Local State

Manager stores runtime data in:

.data/manager.json

Set MANAGER_DATA_FILE to use a different JSON file during tests or experiments:

MANAGER_DATA_FILE=/tmp/manager.json npm run dev:backend

Security Scope

Manager currently targets local-first use. Run it on localhost or behind controls you trust.

Current scope:

• Local JSON file storage.
• No authentication or authorization layer.
• No multi-tenant isolation.
• No hosted deployment hardening.
• Destructive local reset endpoint for development workflows.

Contributing

Before submitting changes, run:

npm run typecheck
npm test
npm run build:web

Keep WorkItem behavior small and explicit. Changes to status, blocker, closure, queue, or persistence behavior should include focused backend tests.

License

Manager is released under the MIT License.