| name | workspaced |
| description | Mental models, subsystems, and gotchas for using workspaced (declarative environment / modules / templates / tools / drivers / plan-apply). Reference- centric: not a --help mirror, not for implementing workspaced internals. Triggers: workspaced, workspaced.cue, modules, templates, tool with, shims, home apply, codebase apply, mod lock/tidy, drivers, init, self-install.
|
Workspaced (usage)
When debugging someone's setup, read their workspaced.cue and modules first.
Init and this skill are orientation; their file is the local dialect.
Sources of truth
One home per class of fact. Link or say "see X" instead of pasting the same fact
into two references.
| Fact class | Canonical place | Not here |
|---|
| Flags, arg shapes, invocation examples | workspaced … --help (and Example/Long on the command) | Skill body, tables of every subcommand |
| Mental model, when/why, cross-subsystem gotchas | This skill (SKILL.md + references/) | Duplicating help Examples blocks |
| Template kinds, functions, pitfalls | references/templates.md only | A second template guide elsewhere in the repo |
CUE language (unify, lattice, defs, ?/!, defaults) | skills/cue-language/ | Re-teaching CUE in this skill's cue.md |
| Workspaced host contracts for CUE (roots, evaluated keys, merge edges) | references/cue.md + modules.md | cue-language skill (it points here instead) |
| Hard contributor rules (CUE schema order, preludes) | AGENTS.md / CODEMAP.md | This skill (usage only) |
| User's real config | Their workspaced.cue + modules on disk | Assuming init shape is universal |
This skill owns what each subsystem is, how pieces connect, and surprises agents
hit even with correct flags.
CLI help owns how to invoke a given command today.
If help is thin on a command, improve that command's Long/Example in Go
rather than growing the skill. High-value targets when editing code: tool with,
home apply/plan, mod lock, init — one paragraph on role plus 2–4 examples.
The skill should only add cross-cutting bits (ephemeral vs shims, plan vs apply).
How much to load
This file alone covers universals and is usually enough for triage.
Load an essential reference when the task touches that subsystem. Read Model and
Gotchas (plus any section titled Essential), then stop unless you are authoring.
Load deep material only while actively authoring or debugging that area (full
function lists, generator fast-path, inspect internals, every practical example).
| Tier | Question | Open | Default depth |
|---|
| Essential | What is this / how pieces fit? | references/overview.md | Whole file is short |
| Essential | Wrong config / wrong tree? | references/config-and-roots.md | Whole file |
| Essential | Plan vs apply; home vs codebase | references/plan-and-apply.md | Whole file |
| Essential | Modules / inputs / lock | references/modules.md | Model + lock + gotchas |
| Essential | Tools / PATH / tool with meaning | references/tools-and-access.md | Access modes + gotchas; not help examples |
| Essential | Drivers vs apply | references/drivers.md | Whole file is short |
| Deep | Workspaced + CUE host contracts | references/cue.md | When writing/refactoring workspaced cue |
| Deep | CUE language mechanics | ../cue-language/ (sibling skill) | Unify/`_ |
| Deep | Writing/editing templates | references/templates.md | Kinds table first; functions/examples/internal/generator only if authoring |
| Optional | Demos / experiments | references/demos-and-experiments.md | Only if exploring experiments/utils demo |
Paths are relative to skills/workspaced/ unless noted. Usually one essential
ref is enough; add deep material only when editing that subsystem.
With cue-language (sibling skill)
Both may trigger on workspaced.cue. Order matters:
- Product / ops first (this skill): wrong root, modules, lock, plan/apply,
tools, drivers, templates — even if the file extension is
.cue.
- Language when the obstacle is CUE (
skills/cue-language/): unification
fails, _|_, defaults (*), definitions (#…), optional/required (?/!),
closedness, comprehensions as language.
- Both when authoring non-trivial workspaced config: cue-language (legal CUE),
then this skill's
references/cue.md + modules.md (usable for this host).
Prefer the user's on-disk cue over either skill's examples.
Skip cue-language for apply/lock/tools/drivers-only tasks. Do not use
cue-language answers as a stand-in for which workspaced.cue loads or whether
to plan/apply.
Not this skill
- Implementing workspaced internals:
AGENTS.md / CODEMAP.md.
- Argv encyclopedias:
workspaced [path…] --help.
- CUE language textbook:
skills/cue-language/ (see above).
Universals
Elsewhere in references, link "see SKILL universals" instead of restating
paragraphs.
- Cue is intent; lock is pins. Edit cue/modules;
mod lock / mod tidy
(tidy ≡ lock) refreshes lock. Lock is not primary human config.
- Plan before apply.
home/codebase plan, then apply; apply mutates.
- Three jobs: converge (modules+apply), binaries (tools), live OS (drivers).
- CLI help is live. This skill does not mirror flags or examples.
Command map (names only; help for details)
| Area | Role |
|---|
init / self-install | Bootstrap |
home / codebase | Plan/apply (+ home sync/backup; codebase lint/format) |
mod | Lock refresh |
tool | Install/search/with |
open / driver | Launch / imperative OS |
experiments / some utils demo | Not daily path (demos-and-experiments.md) |
Goal to read (essential first)
- Orient:
overview.md, then modules.md (essential), then plan-and-apply.md
- Change dotfiles: user's cue +
modules.md essential; if editing files under
config/, then templates.md (deep as needed) + plan/apply
- One-shot tool:
tools-and-access.md essential; tool with --help for specs
- Non-trivial cue for workspaced:
skills/cue-language/ for mechanics, then
references/cue.md + modules.md for host contracts
- CUE unify/
_|_/defs only (not workspaced behavior): skills/cue-language/
alone; add this skill only if apply/lock/roots/modules are in play
- Demos only:
demos-and-experiments.md
