Storage Model
DevSpecs separates operational state from durable intent artifacts.
| Location | Role | Commit? |
|---|---|---|
~/.devspecs/devspecs.db | Local SQLite index, cache, and derived state. | No. |
~/.devspecs/hub.sqlite | Local authority for repo and opt-in home-global topics, publications, votes, subscription cursors, and cooperative leases; not rebuilt from the source index. | No. |
~/.devspecs/hub-prune-*.sqlite | Verified snapshot made before explicit hub-history pruning or compaction. | No. |
~/.devspecs/backups/index/ | Verified manual and automatic index recovery snapshots. | No. |
~/.devspecs/dispatches/<dispatch-id>/ | Frozen dispatch requests, provider handles, and normalized receipts. | No. |
.devspecs/config.yaml | Repo discovery configuration. | Usually yes. |
devspecs/tasks/<task-id>/ | Default generated task workspace. | Yes, when durable. |
.devspecs/tasks/<task-id>/ | Legacy or explicitly local task workspace. | No, unless you chose it deliberately. |
Repository ADR/RFC/PRD paths, such as docs/adr/, docs/rfcs/, and docs/prd/ | Canonical durable documents created or reused by ds compose. | Yes. |
devspecs/workspace.yaml and devspecs/changes/ | Experimental umbrella-workspace coordination records. | Yes, when used by the team. |
The index can be rebuilt. Source docs, specs, plans, task files, and result artifacts should remain the durable record.
Index backups and dispatch receipts are local operational state. Backups are retained until you remove them; dispatch state is not a substitute for the repo-owned task checkpoint and result artifacts. External orchestration providers continue to own their runtime state.
ds compose follows the same rule: it creates a normal repository Markdown
file and then captures derived index state. Default ds prune maintains only
the rebuildable index. Explicit ds prune --hub --before <RFC3339> separately
deletes eligible old local hub publications after a verified backup. Neither
mode deletes source files, composed documents, task artifacts, or workspace
records. ds scan --rebuild rediscovers documents in
configured or conventional ADR/RFC/PRD paths.
Hub is local coordination, not a Git-synchronized or rebuildable record.
Pinned messages and newer correction chains remain after hub pruning. Add
--vacuum to explicitly compact its file and report measured bytes reclaimed;
it can fail after the deletion batch commits. See Local Hub for the
10,000-publication batch and retained-metadata limits.
From an umbrella workspace, use ds compose ... --repo <child-repo> when a
child owns the decision. DevSpecs does not copy a durable document into both
workspace and child-repo storage.
Versioning guidance
By default, ds task writes generated task artifacts to a visible repo path:
ds task "..."
Commit task artifacts when they explain durable work, should be reviewed with a
change, or are useful to the next person or agent. If a task is scratch-only,
ignore devspecs/tasks/<task-id>/ yourself or use an alternate workspace path.
Lifecycle commands auto-detect legacy .devspecs/tasks/<task-id>/ workspaces
when the visible default path does not contain that task.
Future config may make the task workspace root easier to set per repo, workspace, or user. The current default stays simple and visible.
Series names
The default task series is an auto-incrementing alphabet counter:
A, B, C, ... Z, AA, AB, ... ZZ, AAA
Named prefixes may become useful for larger teams or ticket-linked work, but the default should stay simple until config demand is clearer.