CLI Design

CLI Design

Making an agent edit structured files (JSON, frontmatter, LIFO-ordered lists) means it has to read the file, understand the format, reason about where the edit goes, make the change, and verify it didn't break anything. That is four or five operations and a lot of tokens for what should be one call.

The CLI handles structural operations in a single command:

dreamcontext tasks create auth-refactor     # Scaffolds task with frontmatter
dreamcontext tasks log auth-refactor "..."  # Appends log entry (LIFO)
dreamcontext tasks complete auth-refactor   # Updates status in frontmatter
dreamcontext core changelog add             # Adds entry with proper schema
dreamcontext features create payments       # Scaffolds feature PRD
dreamcontext features insert auth changelog "Added OAuth flow"  # LIFO section insert
dreamcontext knowledge create api-patterns  # Creates tagged knowledge doc

One CLI call replaces a Read + reason + Edit + verify cycle. That difference compounds over a session. The CLI handles frontmatter parsing, LIFO ordering, JSON schema enforcement, and section insertion. The agent does not need to think about any of that.

Direct content edits (rewriting a paragraph in soul.md, updating a decision in memory.md, adding detail to a knowledge doc) still use the agent's native Read/Edit/Write tools. The agent is good at content. It is wasteful at structure.

The split is simple: CLI for structure, native tools for content.

Optional Skill Packs

Beyond the core context management skill, dreamcontext ships curated skill packs for common workflows. Each pack contains a base skill (principles, sometimes always-active) and on-demand sub-skills or sub-agents that the agent loads only when the work matches.

Seven packs ship today: engineering (coding standards, security, testing, Firebase) and design (design systems, web/mobile UX, onboarding) — both always-on base principles — plus growth (retention, ads, analytics), brand-voice (enforcement, discovery, guideline generation), and three sub-agent orchestration packs: council (multi-persona debate), multi-review (router + niche code-review specialists), and goal-skill (plan → review → implement → validate execution). Six standalone skills install individually: system-prompts, business-idea-discovery, business-idea-validation, meta-marketing, excalidraw (~44 deterministic builders — charts, wireframes, real-proportion device mockups — driven from JS or a pure JSON spec, with a 3-check render audit), and video-watching (time-mapped video transcripts with on-screen visuals described inline). Several packs ship their own agents (e.g. a code reviewer for engineering, the council persona/synthesizer pair, the goal-skill orchestration agents).

The three orchestration packs share a shape: instead of one model doing everything in one pass, they decompose the work across isolated sub-agents — each with its own clean context, scoped prompt, and (often) a different model tier — then synthesize. Council debates a decision across persona sub-agents and rounds; multi-review fans a diff out to security/cloud-functions/frontend/edge-case specialists and re-ranks their findings; goal-skill runs a goal through a planner, an independent plan reviewer, an implementer, and a validator. The pattern is the same insight as the rest of dreamcontext — structure beats volume — applied to reasoning rather than memory.

The install interface has three modes:

• Interactive browser (install-skill --packs): a terminal checkbox UI showing all packs with descriptions, sub-skill counts, agent counts, installed status, and [always active] badges. Select what you want, confirm, done.
• Direct install (install-skill --packs engineering design): skip the UI, install specific packs by name.
• Individual skills (install-skill --skill firebase-firestore): install a single sub-skill without the full pack.

Cross-pack dependencies are warned at install time (e.g., engineering recommends design for UI work). Skills install flat to .claude/skills/{pack-name}/, agents to .claude/agents/. Sub-skills with reference files (like Firebase packs) carry their references along.

The catalog lives in skill-packs/catalog.json and ships with the npm package. The CLI reads it to discover available packs, resolve dependencies, and locate source files.

Core skills: bootstrap, refactor, deep-research, and maintain the brain

Four skills install with the core itself — not as optional packs — because every mature brain needs them: one to create it, one to keep it in shape, one to mine it deeply, and one to maintain a single task document. All four apply the same decompose-then-synthesize shape as the orchestration packs above, turned on the _dream_context/ directory itself.

• initializer turns existing material into a brain. It recognizes a missing or sparse _dream_context/ — or that you're migrating notes from another folder, or pointing a large new docs source at an existing brain — and ingests whatever you have (a docs folder, an Obsidian/Notion export, ADRs, an old wiki, or just the codebase) into the proper knowledge / feature / task hierarchy. The flow is scout → confirm hierarchy → progressive ingest → verify: a scout inventories the sources and proposes a folder map, you confirm the shape, ingestor sub-agents fan out to distill (never dump) each batch, and a verifier proves the result is real — no template placeholders, recall returns hits, no topic duplicated as both a feature and a knowledge file. It is the single bootstrap surface; the old standalone bootstrap agent was removed so there is exactly one path.
• curator is the periodic refactor pass the sleep cycle deliberately won't do. Sleep is conservative and additive — it polishes whatever shape already exists. The curator is allowed to MOVE, MERGE, SPLIT, RENAME, RE-TYPE, and RETIRE content to conform the whole brain to the conventions that are current at run time. It runs audit → confirm plan → execute → verify: auditor sub-agents (one per domain) return a concrete source → action → target reorg plan, you confirm it, worker sub-agents apply it — using a new atomic dreamcontext knowledge merge that folds near-duplicate knowledge files into one and repoints every inbound wikilink — and a verifier gates the outcome (doctor clean, zero duplicate-topic knowledge, no topic living as both a feature and knowledge, tags normalized, recall precision not regressed).
• dreamcontext-deep-research is the heavy read counterpart to the fast dreamcontext-explore searcher. Explore is one Haiku sub-agent, a tight budget, recall-then-grep, one answer — perfect for "where is X?" on one project, and it under-serves a question that needs synthesis across many files and many projects. Deep-research is the escalation: on a large or multi-project / federated corpus, the main agent decomposes the question, fans out parallel dreamcontext-explore searchers over the whole curated corpus and connected peer vaults, loops to close gaps (loop-until-dry), then runs an adversarial verification gate — each load-bearing claim is re-checked against its cited source before it's allowed into the answer — and finally the orchestrator itself writes a synthesized, cited report that surfaces cross-project provenance and contradictions rather than a raw hit dump. It reuses the tested explore agent as its searcher/verifier rather than introducing a new sub-agent, and it is strictly read-only (it may offer, on consent, to capture a finding as knowledge or file a feedback item — never auto-writes). Same fan-out shape as the sleep cycle, opposite direction: sleep writes memory, deep-research reads it; same shape as the generic deep-research web skill, different substrate — that one mines the open web, this one mines your brain.
• task-manager is the narrowest of the four and the only one scoped to a single document. A task drifts: its acceptance criteria stop describing the work, it quietly grows a second job, its status lies. The task-manager session maintains that one task — revise / summarize / split / reconcile — and explicitly does not write product code (that's the delegate flow). It exists as a shipped core skill rather than an optional pack for a load-bearing reason: the dashboard's Task Manager pane opens a Claude session that names this skill in its first message, so a project whose skills lag would open a curate session with no curate instructions and improvise markdown rewrites — desyncing the Workflow mermaid from the acceptance criteria, which is exactly what the skill exists to prevent.

---

Part of the dreamcontext deep dive — Home · README