Packs

Packs store information that should be reused. They are not task lists and they are not one-off notes. A good pack is something a person or agent can discover later and use as context, a procedure, or a template for future work.

Pack types

Use a workflow pack when order matters. Use a context pack when the content is reference material that can be read in sections.

Workflow packs

Workflow packs describe how to do something. Each step has a required title and optional content, dueDate, dependsOn, parentId, and assignee.

{
	"type": "workflow",
	"title": "Release review",
	"scope": { "type": "projects", "ids": ["project-id"] },
	"steps": [
		{ "title": "Summarize changes", "content": "List merged PRs." },
		{ "title": "Check migrations", "content": "Confirm database impact." }
	]
}

Workflow step dueDate is a relative offset from the workflow run, represented as a numeric string such as "7". It is not a calendar date. Use task dueDate when you need an absolute YYYY-MM-DD deadline.

Workflow step assignees are either human or an agent ID. Workspace user IDs are not valid workflow-step assignees. If the system cannot resolve an assignee name or the name is ambiguous, it is saved as empty.

Running a workflow pack

Packs are reusable; tracks are executable. A pack run connects the two: it expands a workflow pack into a track — one root goal plus one todo task per step — in a single operation (CLI epismo pack run, MCP epismo_pack_run, API POST /v1/packs/run).

The run resolves everything a manual conversion would require:

• The root goal is the run's objective and retrieval anchor. Its title/content come from the run request, defaulting to the pack's. Every task links to it via goalId, so the whole run is fetchable later with a track search filtered by the goal id.
• Relative step due dates (days from run start) become absolute YYYY-MM-DD dates counted from the run's start date (default: today).
• Step dependsOn/parentId ids are resolved to the created track UUIDs.
• Pack assignee tokens are mapped to track assignees (human needs a user-id mapping; agent ids resolve as-is).
• Every created track carries a workflow:<pack-id> source, and referenced context packs are recorded as context: sources on the goal — provenance stays queryable, and the pack itself is never modified by a run.

Context packs

Context packs are collections of named blocks. They work well for onboarding material, policies, and reusable research: anything an agent or teammate should read as background before acting.

{
	"type": "context",
	"title": "Team onboarding",
	"scope": { "type": "personal" },
	"blocks": [
		{
			"title": "Where things live",
			"content": "Docs in Notion, code in GitHub, designs in Figma."
		},
		{
			"title": "How we work",
			"content": "Weekly planning on Mondays; ship behind feature flags."
		}
	]
}

For large context packs, read the outline first and then fetch selected blockIds. This keeps agent context smaller and avoids hydrating content the client does not need.

Overview content

Both workflow and context packs have top-level content. Use it for a short overview of what the pack is for, not for the full reusable material. Put reusable step-by-step material in workflow steps, and reusable reference material in context blocks.

Update operations

Nested pack content is updated with operation arrays. Omitting steps or blocks keeps them unchanged. Passing an empty array is a no-op. To remove all nested items, send one remove operation for each ID.

References

Packs can be referenced by UUID, alias, share URL, or hub URL. Aliases are the most readable form for humans and agents:

epismo alias upsert @repo-onboarding --reference $PACK_REFERENCE
epismo pack get @repo-onboarding --full

Visibility and categories

visibility controls public discovery. scope controls who can see a private pack.

Keep packs focused. A pack that mixes process, background, and current task status usually becomes hard to reuse.