Workspace
One aspect that is orthogonal, but important to consider is how workspaces are structured, discovered, and identified when it comes to collections of action files.
In particular, we want it to be ergonomic to manage multiple “containers” whether you call them stories or projects, by leveraging the filesystem.
While the file specification defines how individual action files are structured, this specification defines how those files should be organized and named within a workspace.
They are separate, because different implementors may choose to work with the format, but choose to avoid these conventions which is fine, this way implementors can absorb specifications a-la-carte and take on the complexity they want to consider.
Scoping
For our work we generally have 3 scopes to consider:
- Machine-Wide Scope: Config
- User Scope: Data + Config
- Project Scope: Data + Config
As is standard, each level is less prioritized than the next, so project scope overrides user scope which overrides machine-wide scope.
The user-scope data is for data that belongs to the user of that actual machine but is not generally attached to a given project and its location is configured via the XDG_DATA_HOME environment variable, with a default of ~/.local/share/ for unix systems and %APPDATA% for windows systems.
This defined by the presence of a .clearhead directory. This may be empty as to only express a desire for this to be designated a project-local scope
- while the default will be that this is in the root of the git directory, the algorithm itself will simply look for the nearest
.clearheaddirectory and designate that as the project root, this way we can have multiple projects within a single git repository if desired, or even have a project that is not attached to a git repository at all
Workspace Structure
All action files/folders should be organized into a directory that conforms with the standards of the given operating system.
Please see Configuration for details on locating the global workspace location and how to configure it.
In general the data should reside in XDG_DATA_HOME/clearhead/. The workspace root is a container for parallel top-level concepts — not a dump of mixed files:
<workspace>/
├── archive/ ← closed history, as plaintext; mirrors charters/ layout
├── charters/ ← acts (.actions), markdown (.md), json sidecars
├── plans/ ← vdir calendars; one subdirectory per charter
├── objectives/ ← objectives live here
└── templates/ ← act templates live here
This scoping makes discovery trivial: implementors scan charters/ for charter content and plans/ for schedule data, without needing exclusion lists. The archive/ region is a sibling of charters/, so it falls outside the default read for free, while staying plaintext and parseable when something needs to look into it.
The root charter’s charters/next.actions (see The Root Charter) is the default location for uncategorized acts: capture lands at the top of the tree, and filing into a child charter is a later step. No other file is special. A charters/inbox.actions, where one exists, is an ordinary child charter named inbox.
Recovered source is quarantined from semantics
A relaxed parser may return a document containing recovery diagnostics so doctor, the linter, and editor tooling can explain malformed input. Such a document is not eligible for semantic workspace lowering: generic parser recovery can attach a later field or UUID to the wrong action. The affected action file is omitted from the domain model until it parses with clean integrity, while a structured finding remains visible. Formatting and mutation likewise require the clean source capability; they must never reserialize recovered actions. Sidecar orphan cleanup is also deferred while any action source is quarantined, because absence from the semantic model is not proof that its provenance is stale.
Example
So if we go over the structure of the work we can see this as an example with a global and project workspace at the examples directory.
this shows both the project and user scope for examples of mixed layouts that would be representative of real world usage
Objectives
Objectives are all located in an objectives directory within the workspace where all objectives of the file format: <objective-alias>.md - a markdown file containing the description of the objective, its purpose, and any other relevant information as per the objective spec
objectives/README.md is the root objective, mirroring the root charter’s charters/README.md: what the workspace as a whole is for. The root charter names it in its objectives (see The Root Objective).
in a project-local scope, this should reside within <project-root>/.clearhead/objectives/ while in a user-wide scope, this should reside within objectives/ folder within the user workspace
Sub Objectives
objective files within the objectives directory are assumed to be a group of objectives,
with:
<objective-alias>/README.md- a markdown file containing the description of the objective group, its purpose, and any other relevant information as per the objective spec<objective-alias>/<subobjective-alias>.md- a markdown file containing the description of the subobjective, its purpose, and any other relevant information as per the objective spec
this allows implementors to organize subobjectives within the directories without worrying about namespace colisions as the alias is scoped within the parent objective alias
Charters
charters belong in the dedicated charters directory within the workspace, where each charter is represented as a markdown file or a directory containing a README.md file.
While the action specification allows for charters to be defined within the files themselves, it can often feel natural to break these files into separate files/folders for organization.
To this end, we support the following conventions, with the assumption implementors will leverage these structures to provide better user experiences.
- we can also designate
<charter>.mdfiles for charters that are primarily prose and not action-focused, but still want to be linked to actions within the platform- please see the charter spec for more details on how to structure these files
- This allows for sub-projects through the combination of directories and files.
$workspace/charters/<charter-name>/README.md- A file containing a description of the charter, its purpose, and any other relevant information as per the charter spec
all closed charters are moved into the archive/ region along with their children to keep a complete record — as their original plaintext files, not a serialized form
All charters and subcharters live within the charters/ directory. Users are free to symlink README files from the project root into .clearhead/charters/ if desired, but the canonical location is always within charters/.
The root charter declares its alias in charters/README.md frontmatter, like every other charter. It is never inferred from the directory name at load time; see The Root Charter.
Hierarchy
While actions express hierarchy through the file format, charters express hierarchy through placement.
Specifically, while we do support parent as front matter, the primary way that lineage is created is by placing subcharters and their plans in the directory of its parent.
In this way, we can structure charters and subcharters
The Root Charter
Every workspace, project or user, has exactly one root charter, and every other charter descends from it: flat charters in charters/ are its direct children, and nested placement expresses deeper lineage. Scope changes how a workspace is discovered and which name init seeds, never the shape of the root.
The root is the charters/ directory itself, anchored by reserved file roles:
charters/README.md— the root’s prose and identity anchor; its frontmatter carriesidandaliasexactly as any charter’s doescharters/next.actions— the root’s action anchor, the same stem every directory-form charter uses for its own actions (charters/<charter>/next.actions)charters/.next.json— the root’s sidecar, mirroring the frontmatteridplans/next/— the root’s plan collection (vdir directory)
next names a file role, not a charter: there is no charter entity named next, so a named charter can never collide with the root. Unlike a directory-form charter, the root cannot take its name from its directory, which is always charters/; its name is its frontmatter alias.
Root identity is charter identity and follows the concept identity rules: minted once, persisted in charters/README.md, read from there. It is distinct from workspace identity: workspace_name seeds the root’s alias at init, after which the two are independent facts. Neither is ever recomputed from the working directory or the environment.
A root without charters/README.md or without its id still loads as the single root. Like a workspace without a workspace_id, it gets an ephemeral identity that is never persisted and never derived from a path, and its display name falls back to workspace_name. A root with no README, or a README that omits state, is New like any charter without a declared state; because engagement requires every ancestor to be Active, nothing in the workspace is admitted for engagement until the root is activated. clearhead init fills in missing root files and writes the root as New, since a workspace starts in planning; doctor reports the gap; loading never writes identity or state. When the README and sidecar disagree, the README wins: doctor --fix mirrors its id into the sidecar only when nothing references the replaced id, and otherwise reports a violation to reconcile by hand.
Sidecar for data
we can also add the .<charter-name>.json sidecar file that allows users to place data that is relevant to the charter but not something that should be kept in the files themselves.
This will cover all the pieces we will be going over and has various properties to link different objects together at a data level without cluttering the core files themselves
please review the charter sidecar schema for more details on how to use this file and its properties.
Notes
Any entity can carry notes: a charter, an Action, a Habit. Notes are the one uniform log of the workspace, kept in the sidecar of the charter whose file holds the entity, under a top-level notes map keyed by the entity’s UUID: notes.<uuid> is an array of notes, oldest first. A note is {at, by, text}:
at: an ISO 8601 date-time with its UTC offset, the instant the note was written.by: who wrote it, in the convention the docs’ front matter uses:human:Darrion,agent:<role>. Optional only for notes migrated from a legacy log.text: plain text.
The tools treat notes as an append-only log. clearhead jot is the single verb that writes one and takes any entity’s id; a correction is a new note, and no tool edits or deletes one. The JSON can still be edited by hand, so readers accept what they find (unordered notes, a missing by) rather than refusing it; they order by at, ties by position.
Appending is not a mutation of the entity. It works in any state, closed and archived included, never touches the .actions line or the charter document, and so cannot disturb a description. Appends are serialized, by a lock or by compare-and-retry: two writers appending at once never lose a note.
Notes follow the entity. Readers take the union of every sidecar keyed by UUID, so a note reaches its entity wherever the line now lives. doctor --fix therefore relocates rather than prunes: a notes entry whose entity lives in another charter moves to that charter’s sidecar, and an entry whose entity exists nowhere is reported and kept, never deleted. (Other orphaned sidecar entries remain prunable.) Archiving moves the sidecar whole, notes included.
Descriptions that already carry dated additions are not migrated automatically.
Note: we use the hidden file convention here to indicate that this is a sidecar file meant to be read and written by tools as a companion to the charter, but should not be directly interacted with by users.
Plans
A workspace’s <data_root>/plans/ directory stays a charter-scoped iCalendar vdir (Decision 31). A one-off Plan projects an Action’s @ block; a recurring Plan projects a Habit held in a habits file. Unscheduled Actions have no Plan resource.
Every constructed charter owns one calculated collection path even when its directory does not exist. This relative path is derived from the charter’s canonical workspace anchor and is not written into charter Markdown or sidecars. The vdir’s location is part of the workspace layout, not configuration, and it belongs to exactly one workspace; transport tooling points at it where it is. Calendar resources attach to charters by exact collection ownership, never by mutable alias or title matching.
Each .ics file contains one VCALENDAR with a VEVENT master and same-UID recurrence overrides. VTODO is not part of this calendar integration. ClearHead-created filenames use UID, but readers identify resources by UID because transport may rename files.
This one-component-per-file vdir layout is directly compatible with tools such as vdirsyncer and does not assume a particular CalDAV server or any transport at all.
Any charter with plans requires directory form. The plans/ directory itself signals that a workspace has schedule data.
All paths are relative to <data_root>/plans/. An example:
-
next/<uid>.ics -
work/<uid>.ics -
work-feature/<uid>.ics -
subproject/<uid>.icswhich maps to charters:
-
the root charter (
nextis its reserved plan collection) -
workcharter -
work/featuresub-charter (hierarchy encoded with-) -
subprojectcharter
Multi-component .ics files are an import format, not a storage format. Implementations should provide an import path that splits them into individual resources within the target charter’s plans/ directory.
An immediate collection directory with no charter owner is invalid workspace state, not an alternate way to create a charter. Its resources must not be silently adopted; the ownership problem remains visible for explicit resolution.
Be sure to review the reference syntax for guidance on working with sub charters and sub plans.
For recurring Plan, standalone Action, identity, and synchronization semantics, see the ICS Schedule Spec.
Actions
Per the Ontology specification, actions are the actual executable work items in the system, whether they are generated from plans or created directly.
Actions are stored in the .actions files within the workspace and represent the lowest atomic unit of work within the system.
Ordinary .actions files hold executable Actions, including occurrences and one-offs, not recurrence. All these files use the same actions syntax: R: parses regardless of file role, but has recurrence meaning only on Habit roots in a habits file. R: on an ordinary Action or template child is a semantic lint, not a parse error; see Linting. Calendar event object semantics belong to the .ics projections and semantic sidecars, not these action lines. A charter’s <charter>.habits.actions holds Habit roots, their R: rules and optional template children. Directory-form charters and the root use next.habits.actions, beside next.actions, sharing .next.json. Habits and their template children must never be lowered as live executable Actions or inferred as extra charters.
Moving a line between an ordinary actions file and a habits file, adding or removing R:, retains its UUID. The moved entity changes kind; it does not remain in both files or become its own generated occurrence. See kind-change outcomes.
All paths are relative to charters/:
charters/<charter>.actions— unarchived Actions for that charter, including closed lines and every arrived Habit occurrencecharters/<charter>.habits.actions— Habit definitions and their template childrencharters/next.actions— root charter acts (project or user workspace root)charters/<charter>.completed.actions— archived whole root trees for that charter; closed lines are not moved here merely by closing (see Archival)charters/<charter>/next.actions— root acts for a folder-form charter
When a charter is archived, its known files (charters/<charter>.actions, .completed.actions, .habits.actions, the charter .md, and its .json sidecar) and every other charter-local supporting file in a directory-form charter (notes, inventories, and future formats) are moved verbatim into the archive/ region, at the path they held under charters/. Nothing is serialized: the archived form is the same plaintext, just relocated out of the default read set.
Readers classify .habits.actions and .completed.actions before the general .actions suffix, removing the entire known suffix to find the charter stem. Discovery, parsing, lowering, mutation, archive, lint/doctor, RDF publication and editor navigation must all use that classification. The same files must neither be discovered twice nor leak template children or archived occurrences into the live Action index. Test root, flat and directory charters, archive moves and unrelated supporting files. Archive-aware duplicate suppression still reads terminal occurrence lineage.
Charter stem derivation follows the same rules as plan name inference: next.actions in a directory-form charter uses that directory’s name; charters/next.actions is the root’s reserved anchor and takes its name from charters/README.md (see The Root Charter); all other .actions files use the file stem.
Concept Identity
Every concept in a workspace — the workspace itself, its charters, its plans, and its actions — carries a durable identity that survives renames, moves, and edits. Identity belongs to the concept, never to its file path or title, so a reference resolves to the same thing after the target is renamed, reordered, or moved (including into an archive).
One lifecycle governs all four:
mint or derive once → persist to the concept’s anchor → read from persistence →
doctorreconciles drift
They differ only in where the identity is persisted:
| Concept | Anchor | Specified in |
|---|---|---|
| Workspace | workspace_id in <data_root>/workspace.json | Workspace Identity |
| Charter | frontmatter id, mirrored in the sidecar | Charters |
| Plan | transport VEVENT UID, linked to native identity in sidecars | [ICS Schedule Spec] |
| Habit | inline #uuid in the habits file, retained on kind moves | [Action File Format], [ICS Schedule Spec] |
| Action | inline id; its sidecar records the UID of any realized Plan | [Action File Format], [ICS Schedule Spec] |
Three rules keep this honest:
-
Tool-managed, not typed. Humans never write a UUID;
init, the CLI, and the LSP mint and maintain them. “Invisible” means unobtrusive, not absent — a mutable action line carries its id quietly rather than re-deriving one on every read. -
Derivation is a bootstrap, never a live recompute. An identity may be derived once to fill a gap and then persisted as truth. Recomputing an id from mutable content — from a title, from a path — is forbidden: change the content and you silently change the identity, orphaning every reference to it. A broken reference must fail loudly, into a dangling id that
doctorcan report, rather than rebinding silently to a different concept. -
A missing anchor is a reportable gap, not a write. A concept whose anchor has not been written yet — a charter document with no
id, like the root README above, or a workspace with noworkspace_id— still loads: the reader supplies an ephemeral identity that is never persisted and never derived from content or path, anddoctorreports the gap. Loading never writes identity, and no ordinary edit stamps one as a side effect. A durable id is minted only by a deliberate identity-minting pass, or when a whole new document is created. Anything that would persist an identity — an archive file name, a sidecar record — requires a declared one, and refuses otherwise.
Actions carry their charter
An action may record its charter’s id alongside its own, denormalizing the action→charter link so it survives independently of which file the action currently sits in. The embedded charter id is authoritative when present; the file’s location is the fallback when it is absent. doctor reconciles the two on conflict.
Named Graph Isolation
Each workspace maps 1-1 to an RDF named graph. This enables querying a single workspace in isolation or spanning multiple configured workspaces without data coalescing into a single undifferentiated graph. See Decision 28 for the rationale.
Workspace Identity
A workspace’s identity is its workspace_id, stored in its own <data_root>/workspace.json manifest — deliberately separate from config.json. The data root is the directory holding charters/ and plans/: <project>/.clearhead/ for a project workspace, and the resolved data_dir (default $XDG_DATA_HOME/clearhead/) for the user workspace. The manifest’s location follows that one rule in both scopes:
{
"workspace_id": "019e43e4-...",
"workspace_name": "platform",
"created_at": "2026-05-31"
}
The manifest and config.json are split because they are different in kind. config.json holds behavior — human-authored preferences that layer through the precedence chain (global → project → project.local → env → args). Identity is a tool-managed fact about one workspace that must not layer: a workspace_id in a global config, or a CLEARHEAD_WORKSPACE_ID env override, is meaningless. Keeping identity in a non-layered manifest keeps the config precedence rules honest. The manifest is near-static — it changes on init and rename, essentially never otherwise — and carries workspace-level facts only; per-charter, per-action, and per-plan metadata live in their co-located sidecars, never here. See the manifest schema.
The named graph URI is derived from it as urn:clearhead:workspace:<workspace_id>.
workspace_id is assigned once by clearhead init and remains stable for the life of the workspace — it is the durable handle for the workspace’s named graph, so any consumer that names the graph URI resolves it to the same workspace across sessions. It is never regenerated in normal operation.
That stability is a convenience, not a correctness requirement. A workspace without a workspace_id is fully queryable: the read side mints an ephemeral graph identity per load — distinct per workspace, never persisted, and never derived from the root path. Such a workspace answers queries correctly; its graph URI simply is not stable across sessions. init is how a workspace earns a durable URI — offered, never forced.
workspace_name is the display name used in multi-workspace output and cross-workspace reference syntax (name:charter/action). init persists it once: --name when given, otherwise the project directory name for a project workspace or the current username for the user workspace. Readers use the persisted value and never recompute it from the directory or environment; it can be edited manually afterwards.
created_at records when the workspace was initialized. Informational only.
Query Scope
Query scope is determined by the additional_workspaces configuration:
- Single workspace (default): Only the current workspace’s named graph is loaded and queried.
- Multi-workspace: When
additional_workspaceslists additional workspace paths, all of them are loaded into the same store alongside the current workspace — each in its own named graph. Queries span all loaded named graphs.
The scope is declared in config, not per-command. A user who configures additional workspaces intends cross-workspace visibility by default. This means the platform repository, which lists all submodule workspaces as additional_workspaces, queries across all of them without any additional flags.
Initialization
clearhead init bootstraps a project workspace at <cwd>/.clearhead/; clearhead init --user bootstraps the user workspace at the resolved data_dir. Both accept --name and perform the same steps against their data root:
- Generates a UUIDv7 and writes
workspace_id,workspace_name,created_atto<data_root>/workspace.json(skipped ifworkspace_idalready present). If an older project workspace still carries these fields in.clearhead/config.json,initanddoctormigrate them into the manifest and drop them fromconfig.json. - Creates the
charters/directory structure and bootstraps the root charter (each file skipped if already present):charters/README.mdwith a mintedidand analiasseeded fromworkspace_name,charters/next.actions, and thecharters/.next.jsonsidecar mirroring thatid. These files are structural: they let flat named charters resolve as children of the root and keep their plan-vdir slugs routable. - Bootstraps the root objective (skipped if already present):
objectives/README.mdwith a mintedidand analiasseeded fromworkspace_name. When step 2 createscharters/README.md, itsobjectivesnames that alias; an existing root charter is never edited, anddoctorreports it if it names no objective.
init is idempotent — rerunning it on an already-initialized workspace is safe and never overwrites existing data or identity. It may restore a missing root-charter scaffold. Pass --force to regenerate identity fields. This assigns a new graph URI, so any consumer that referenced the old one no longer resolves to this workspace; the workspace’s plaintext data is untouched.
Workflows
Now, its one thing to speak on the concrete file formats for each record type but the other piece to cover is the workflow that actually handled these various structures and dictates what happens when and where. for this, we are going to go a little more over the workflows that allow this format to be updated automatically or manually based on what people prefer
Templates
Templates are a list of actions in the form of <name>.actions files that are stored in a templates/ directory at the root of the workspace. these are meant to be used as templates for generating actions either through schedules or on demand.
it is assumed that the filename will be the reference for the template, so if we have a weekly-review.actions file in the templates/ directory, then the reference for that template will be weekly-review and this is used in a Habit’s description as template: weekly-review, projected to the recurring VEVENT DESCRIPTION (first line of calendar notes)
this will also allow for on demand generation of actions either as a side-effect to charter creation or through a command like apply template which will allow users to generate actions from templates on demand without needing to wait for the schedule to trigger them
Archival
One concept that is very important to the workspace format is the process of “archiving” things. weve covered the names above but its working from a reference point lets go from the beginning
- At the lowest level, we have the actions that are implementations of their optional parent plans.
- Closing an action changes only that line’s state and stamps its completion date in place; it does not close descendants, detach a parent link, or move the line. Closed lines in
<charter>.actionsare ordinary active-file records. Only archive and unarchive move action lines between<charter>.actionsand<charter>.completed.actions, always as a whole root tree (a root and everything below it). Archive accepts a closed root only when its whole tree is closed, and transfers that tree to the completed file. Unarchive accepts a root in the completed file and returns its whole tree to the active file without changing states. Both operations refuse a child target and name its root instead. Parent links within an archived tree are kept. Reopening is a separate in-place state change: it sets only the named action tonot_startedand clears its completion date. Reopen is allowed only in the active file; an archived action must be unarchived first. - Habits have their own state: completing or cancelling the Habit ends generation without closing its open occurrences. Their definitions move with the charter’s known files; calendar projections have no independent work lifecycle.
- Finally, like plans, the charters themselves at
charters/<charter>.mdcan be archived after they are closed. Archival is a move, not a translation: the archived form is data, not a projection, so no Turtle or JSON-LD is written. Any RDF view of archived data is regenerated from the loaded domain model by Core’s publication adapter, exactly like live data. - archiving a parent charter archives its whole subtree as one unit; the open-actions precondition is recursive too — it refuses if any descendant still holds open actions
- the subtree’s known files (
.actions,.completed.actions,.habits.actions, the charter.md, and its.jsonsidecar) plus all supporting files owned by directory-form charters are moved into thearchive/region together, preserving their path undercharters/so the subtree’s internal structure survives. The sidecar moves with the files rather than folding itscreated_at/external_schedule_idinto the lines. An implementation must make the move safe to interrupt and retry: a file may transiently exist in bothcharters/andarchive/, but it is never removed fromcharters/without already existing inarchive/— redundant, never an orphaned or lost record - any charter subdirectory left empty by the move is collapsed
Because archive/ is a sibling of charters/, the moved files leave the default read set automatically, but reference resolution can still look into them: an archived < target resolves to one of three states — satisfied (target Completed), abandoned (target Cancelled), or dangling (resolves nowhere). Keeping archives as readable plaintext is the whole reason that three-way signal is possible.
The .ics files in plans/<charter-name>/ are not touched by archival. Per decision 31, the plans vdir is a shared projection boundary and archival must not infer that its resources should be deleted. Archived Action records retain history while the vdir remains independently manageable through calendar tooling. A collection left without a live charter owner is invalid workspace state and must remain visible for explicit resolution; it is never silently adopted as an implicit charter.
REMEMBER, per the process spec it is assumed that all child plans are completed/cancelled which is why the open files above are expected to be empty or atleast emptyable before being moved into archive/
this is how we maintain a format that is able to evolve gracefully
See Also
- [Action File Format] — DSL syntax
- Charters — Charter structure and frontmatter
- Configuration — XDG paths and config settings
- [ICS Schedule Spec] — VEVENT projection, synchronization, and schedule semantics
- Ontology — Domain model and RDF contract
- Process — Workflow including recurring action behavior
- [Reference Syntax] — Sub-charter and sub-plan references