Skip to content

v0.3.md

Latest commit

 

History

History
447 lines (342 loc) · 21 KB

v0.3.md

File metadata and controls

447 lines (342 loc) · 21 KB
Raw

v0.3 — candidate to-do list

Status: candidates, not locked. Source: comparison analysis vs. rohitg00/pro-workflow (2026-05-13) plus pre-existing v0.2 deferrals.

Each item below is a candidate to assess individually before v0.3 scope locks. Some may move to v0.4. Some may be rejected. The point of this file is to keep them all in one place so the v0.3 planning session has a starting set.

How to read this

Items are grouped by fit confidence (how cleanly they map to atom's identity as a project-starter template + cross-project memory). Tier 1 items are strong fits that align with shipped direction. Tier 2 items are interesting but require deliberate scoping — atom would grow into them, not just absorb them.

When v0.3 scope-locks, each item gets a yes/no/defer decision with a written reason, and the survivors graduate to their own per-feature plan files (same pattern as distribution.md, stack-presets.md).

Tier 1 — strong fit, low risk

These align with atom's stated direction (capture must not depend on Claude remembering; lessons should be retrievable across sessions).

#12 Hook-driven nucleus capture

What: ship a scaffold/.claude/hooks.json with a Stop hook that greps the last Claude response for a [NUCLEUS] marker convention and runs nucleus add on each match. Survives Claude forgetting to invoke the skill.

Why: today, the nucleus skill tells Claude to call nucleus add. That fails when Claude forgets, when the user switches tools, or when the session ends abruptly. A Stop hook is robust to all of those.

Inspiration: pro-workflow's Stop hook auto-captures [LEARN] blocks. Same shape.

Open questions:

  • Marker syntax: [NUCLEUS] ... single-line vs. [NUCLEUS]\n...\n[/NUCLEUS] block? Block is more flexible; single-line is more reliable.
  • How does this compose with the existing claude-managed mode? Probably: claude-managed becomes the default for the marker convention, and the hook is the safety net.
  • Project-tagging: hook needs to know $PROJECT_NAME — read from package.json or nucleus init state.
  • Compatibility: only fires in Claude Code. Other AI tools keep the manual nucleus add path.

Effort: small (~150 lines: one hook script + AGENTS.md doc update + nucleus skill update).

#13 UserPromptSubmit auto-injection of relevant nucleus + learnings

What: a hook that runs on every user prompt, searches nucleus + learnings for keyword matches, and prepends top-3 hits to the context.

Why: captured learnings only get into the session today if Claude proactively searches them. The README's whole pitch ("the lessons you learned are harder to recover") only pays off if the lessons are actually retrieved. Auto-injection closes that loop.

Inspiration: pro-workflow's UserPromptSubmit hook is the highest-leverage thing in their system.

Open questions:

  • Retrieval quality: ripgrep keyword match is the v0 path; semantic search (#14) would be the v1 path. Probably ship keyword first, layer semantic later.
  • Token budget: cap injection at N kb to avoid blowing context.
  • Filtering: only inject learnings whose applies_to tags match the project stack? Probably yes for learnings; nucleus stays project-scoped already.
  • Opt-out: env var or .atom-nuc-no-inject file for sessions where the user wants a clean context.

Effort: medium. Hook script is short; the indexing layer (which nucleus search already has) does the work. Tuning the relevance bar is the real cost.

Dependency: #12 should land first so the capture loop is closed before the inject loop matters.

#14 PreCompact / PostCompact hooks for nucleus

What: PreCompact runs nucleus add --auto-from-context to catch anything not yet captured. PostCompact re-injects critical context.

Why: when Claude compacts, anything not yet captured gets blurred. Long sessions in atom-bootstrapped projects routinely hit this.

Inspiration: pro-workflow's PreCompact/PostCompact.

Open questions:

  • What does --auto-from-context actually capture? Probably: ask Claude (via the hook) for a 5-bullet summary of unfinished decisions/learnings, then store those.
  • Re-injection content: probably the same set #13 would inject for the current task, scoped to the compact-triggering context.
  • Risk: a chatty hook that captures noise every compact. Tune the bar.

Effort: medium. The auto-capture path is the unknown.

#21 Universal seed learnings

What: ship a curated set of generalized, stack-agnostic seed learnings (applies_to: [universal]) that auto-copy into every project bootstrapped from atom. Same delivery mechanism v0.2 used for per-preset seed learnings, just without the stack filter.

Why: v0.2 proved the pattern — every Python/FastAPI project inherits "use Pydantic v2 over v1", every Rust/Axum project inherits "use cargo-chef for Docker builds". But the most valuable lessons aren't stack-specific: AGENTS.md as single source of truth with forwarders, constitution as small versioned law, agent ownership matrix, two-tier memory (nucleus + learnings), spec-first discipline, match-ceremony-to-cost-of-being-wrong heuristic, phase-gate single-dependency-trap mitigation. These currently live only in the maintainer's personal playbook (~/.atom/learnings/pattern/learnings-archive.md) and never travel to other users.

Source: 11 patterns extracted from ~/.atom/learnings/pattern/learnings-archive.md (148-line retrospective synthesizing atom-dev + cryenx-redesign + wallet-persona). Patterns 1–11 are the universal ones; the project-specific framing gets stripped during extraction.

Open questions:

  • Curation bar: 11 candidates is a lot. Which clear the bar of "would help every project, not just maintainer-adjacent projects"? Probably fewer than 11; possibly 5–7.
  • Voice: maintainer's voice is direct ("you built atom..."). Generic voice for shipped seeds needs to be third-person or imperative.
  • File layout: extras/learnings/universal/<slug>.md (sibling to extras/web/<preset>/learnings/)? Or scaffold/learnings/pattern/*.md so they land via scaffold-promotion rather than the learnings filter? Probably the former — keeps the existing filter pattern.
  • Override: a user with their own ~/.atom/learnings/<same-slug>.md should win. Confirm the existing copy step does last-write-wins, or add a skip-if-exists check.

Effort: small-to-medium. Extraction + rewrite is the work; the plumbing (filter, applies_to: [universal], copy step) already exists from v0.2.

Decision needed: is the maintainer comfortable shipping the distilled patterns as opinionated defaults that travel into every user's project? (Probably yes — atom is already opinionated; this is just making the opinions explicit.)

#15 atom doctor command

What: atom doctor checks PATH globals, nucleus directory health, sync repo connectivity (if configured), schema migration status, and prints a pass/fail line per check.

Why: cheap, high-value debugging surface. When a user reports "nucleus isn't working" we currently ask 5 follow-up questions. A doctor command answers them in one paste.

Inspiration: pro-workflow's /doctor. Standard CLI hygiene.

Open questions:

  • Subcommand on atom (atom doctor) vs. separate binary? Probably subcommand for one-place discovery.
  • Output shape: human-readable by default, --json for machine consumption (logs, bug reports).
  • Scope: just atom itself, or also probe Claude Code / Codex / Gemini install state? Probably just atom in v0.3.

Effort: small. Mostly file existence + version checks.

#23 /atom-new bootstrap skill

Status: built (shipped ahead of v0.3 scope-lock, see [Unreleased] in CHANGELOG.md). Lives in skills/atom-new/; linked into ~/.claude/skills/ by install.sh + atom upgrade. Locked decisions below held: conversational, Mode 1 only, thin launcher, symlink distribution. Open questions resolved during build: named atom-new; target dir is confirmed per-invocation; not-installed path points at install.sh. Released in 0.3.0 (2026-06-05) — opened the v0.3 line ahead of full scope-lock.

What: ship a global Claude Code skill (/atom-new) that drives the Mode 1 bootstrap flow conversationally from any directory or session — no cd ~/.atom/atom, no terminal round-trip. The skill is a thin launcher: it locates the installed atom (~/.atom/atom/), reads AGENTS.md Mode 1 + docs/ from there, and executes the conversational bootstrap against the current working dir. It does not restate the steps — AGENTS.md stays the single source of truth.

Why: today, to bootstrap you have to be inside atom — either cd ~/.atom/atom so CLAUDE.md → AGENTS.md auto-loads, or run the atom-setup wizard in a terminal. Both mean leaving wherever you actually are. A global skill removes that friction, and — the real unlock — its description makes Claude proactively offer it when a user says "let's start a new project" in any session. You stop having to remember atom exists. The atom-setup wizard already serves the terminal-first path; this is the in-Claude conversational counterpart.

Scope (locked): Mode 1 only. Modes 2 (maintain atom) and 3 (build atom features) are dev-facing — they only make sense inside the atom-dev repo. Folding them into a global skill makes it ambiguous ("start a project... or maintain the template?") for zero benefit. One focused skill = the bootstrap flow.

Flow (locked): conversational, not a wizard shell-out. The guided dialogue is atom's differentiator inside Claude; the deterministic 10-section wizard already exists for terminal lovers.

Distribution: piggyback on existing machinery, no new channel. The skill installs to ~/.claude/skills/atom-new/ as one more global symlink that install.sh creates and atom upgrade refreshes — consistent with the dev/use globals separation (atom_dev_use_separation_state memory) and the git-not-npm decision (atom_distribution_decision memory).

Open questions:

  • Name: /atom-new vs. /new-project vs. /atom. /atom is ambiguous against the atom CLI; lean /atom-new.
  • Where does the new project get created? The wizard handles target dir; the skill must ask (cwd vs. a named subdir) since it can fire from anywhere.
  • Thin-launcher contract: the skill reads AGENTS.md Mode 1 from the install at invoke time. Confirm it fails gracefully (points to install.sh) when atom isn't installed.
  • Discovery tuning: the skill description: is what makes Claude proactively offer it. Get the trigger phrasing right ("start a new project", "bootstrap from a template") without over-firing.
  • Compatibility: Claude Code only. Other AI tools keep the cd + AGENTS.md path and the atom-setup wizard.

Effort: small. A thin SKILL.md (~20–40 lines pointing at the installed AGENTS.md/docs) + one symlink wired into install.sh and atom upgrade. The risk is not effort — it's the fork-the-instructions trap, which the thin-launcher design kills.

Tier 2 — interesting, requires deliberate scoping

These could fit atom but only if v0.3 explicitly decides atom is willing to grow surface in that direction.

#16 Move nucleus to SQLite + FTS5

What: migrate nucleus storage from JSONL to SQLite with FTS5 full-text indexing. Schema-versioned migration runs on first invocation. nucleus export --jsonl exposes the legacy format for users who want cat-readable files.

Why: JSONL with keyword search is fine at current scale but won't scale past a few thousand entries. FTS5 gives ranked retrieval out of the box. Multi-process safety improves (Claude + you + sync daemon no longer fight over file locks).

Inspiration: pro-workflow uses SQLite + FTS5 throughout.

Open questions:

  • Migration path: nucleus migrate already exists from v0.2 #4. The JSONL → SQLite migration is the next migration.
  • Sync model: the GitHub sync repo currently stores JSONL files. SQLite is binary — does sync ship the DB file, or does it ship JSONL export + reimport? Probably JSONL-on-the-wire, SQLite-on-disk.
  • User-owned principle (atom_user_owned_principle memory): SQLite is still 100% local; principle holds.
  • Loss: cat ~/.atom/nucleus/projects/foo/learnings.jsonl stops working. Mitigation: nucleus export and nucleus dump.
  • v0.3 might just sequence #14 (semantic) on top of #16 — the embedding column belongs in the DB.

Effort: large. New storage layer, new query path, migration testing, sync changes.

Decision needed: is the JSONL-readability promise something we keep, or trade for retrieval quality?

#17 Research / wiki layer

What: a third ~/.atom/research/ directory (or a --kind=research flag on nucleus add) for research notes with citations — "here's everything I learned about Railway's pricing while building project X." Stored, searched, and optionally carried-forward separately from playbook patterns.

Why: nucleus is for raw session notes. Learnings is for curated playbook. Research is a third artifact pro-workflow's wiki layer revealed: notes-with-sources that aren't necessarily patterns to carry forward, but are reference material to retrieve later.

Inspiration: pro-workflow's wikis — 9 flavors (research, paper, domain, codebase, incident, …).

Open questions:

  • Is this a flag on nucleus, or a new tool? Probably a flag in v0.3, possibly a tool by v0.4 if it earns it.
  • Carry-forward semantics: does research auto-copy to new projects like learnings, or stay local? Probably local by default with an explicit --carry-forward flag.
  • Citation shape: free-form URL + title, or structured (source, accessed_at, claim)? Free-form for v0.3.
  • Auto-research loop (pro-workflow's killer feature here): explicitly out of scope — that's a different product.

Effort: medium. Storage is cheap; the question is whether it earns its keep vs. just dumping research into nucleus.

Decision needed: do we have evidence that research-with-citations is a real artifact users want, or is this a feature looking for a use case?

#18 Cost tracking surface

What: track tokens-per-session and cost-per-session, attribute to the model (claude/codex/gemini), alert on budget breach. Wizard's §1 already collects "cost envelope expectations" — this operationalizes that promise.

Why: atom-setup §1 asks the user for a per-request or monthly cost envelope. Today, that answer goes nowhere. A cost-tracker would make the question worth asking.

Inspiration: pro-workflow's cost-tracker skill + cost-analyst agent.

Open questions:

  • Source of truth for tokens: Claude Code emits cost in its session log; Codex/Gemini differ. Cross-tool parity is hard.
  • Where does the data live? Probably ~/.atom/nucleus/projects/<slug>/usage.jsonl (sibling to learnings.jsonl).
  • model-race overlap: model-race already scores model outputs; cost-per-race would belong there too. Probably ship cost-tracker as the general layer and have model-race consume it.
  • Alert mechanism: hook on Stop? CLI summary command?

Effort: medium-large. Cross-tool token attribution is the hard part.

Decision needed: is "cost envelope" a real promise atom makes, or wizard fluff? If real, this is v0.3. If fluff, drop the §1 question instead.

#22 Windows support (WSL2 callout now, native port conditional)

What: two-phase Windows story.

  • Phase A (v0.2.x stopgap, ~1hr): ship a one-paragraph WSL2 callout in INSTALL.md (and a README link). Tells Windows users explicitly: use WSL2 (or Git Bash for read-only commands); native PowerShell is not supported today. Closes the "does atom work on Windows?" question without committing to a port.
  • Phase B (v0.3+, demand-gated): native Windows port — but only if real user demand surfaces. Not speculative.

Why: today the README has a single line ("Windows users need Git Bash, WSL, or similar") buried at line 53. That's not enough for a Windows user to know whether to invest. The cheap callout fixes that. The native port is a different question that depends on demand.

Findings from 2026-05-18 evaluation session (nucleus session windows-port-eval-1779112103):

  • Runtime is portable. The 5 atom CLIs (atom, atom-setup, nucleus, learnings, model-race) are pure Node ESM using os.homedir() — ~/.atom resolves correctly on Windows already.
  • Bootstrap is where the cost lives. The bash atom-setup bootstrap (shebang + tr/grep/sed PATH-scan) and the symlink-based dev/use globals from the 2026-05-07 separation work are the real blockers. These need PowerShell equivalents or a Node rewrite.
  • Half-port is a trap. A native Windows port done halfway is worse UX than "use WSL2" — atom-setup installs cleanly, then the user hits Claude Code (officially macOS/Linux/WSL only), Multica, VHS, or Freeze and dead-ends two steps later. If committing to native, the full downstream chain must be validated on a real Windows box, not just atom itself.
  • Cross-platform porting framework. Separate bootstrap layer (bash/PowerShell — where Unix-isms like sudo/EACCES/PATH-scan/ symlinks/chmod/exec accumulate) from runtime layer (already portable via stdlib abstractions). Audit each independently.

Open questions (for Phase B only):

  • Is there real user demand, or is this maintainer speculation? Phase A is the demand-detection mechanism — if Windows users hit the WSL2 callout and complain, that's signal.
  • Downstream-chain validation: which of Claude Code / Codex / Gemini / Multica / VHS / Freeze actually work on native Windows? Without this audit, a native port is a trap (see above).
  • Bootstrap rewrite path: PowerShell port of atom-setup bash, or Node rewrite of the bootstrap so there's one implementation? Node rewrite probably wins long-term but is bigger work.
  • Symlink alternative: Windows symlinks need admin or Developer Mode. Replace with copy-on-install or .cmd shims?

Effort:

  • Phase A: small (~1hr — one paragraph in INSTALL.md + README link).
  • Phase B: large (bootstrap rewrite + downstream-chain validation + Windows CI). Don't size precisely until Phase A surfaces demand.

Decision: Phase A ships in v0.2.x as a cheap stopgap. Phase B is conditionally deferred — gated on real user demand, not speculative porting. Decision pattern: ship the cheap option to keep optionality open; the deep option only pays off if users actually exist.

Pre-existing v0.3 deferrals (locked decisions, build deferred)

These were locked during v0.2 planning with full design surface explored. They ship when v0.2 surface settles.

#19 model-race --auto

Cross-CLI parallel session orchestration via per-CLI adapter contract. Risky (three CLIs to maintain). See model-race-auto.md.

#20 nucleus --semantic

Local embeddings via @xenova/transformers. Risky (embedding-model choice, vector store, indexing strategy, quality bar against rg).

If #16 (SQLite migration) is in v0.3 scope, sequence #20 on top of it — the embedding column belongs in the DB.

Suggested triage order for the v0.3 planning session

  1. Decide on hooks (#12, #13, #14) as a bundle. They're cheap and reinforce each other. Ship together or not at all.
  2. Decide on #15 (doctor). Standalone; almost certainly yes.
  3. Decide on #21 (universal seed learnings). Standalone, source material already exists; the work is curation + voice rewrite. Almost certainly yes if the maintainer is comfortable shipping the distilled patterns as opinionated defaults.
  4. Decide on #23 (/atom-new skill). Standalone, cheap (thin launcher + one symlink), reinforces proactive discovery. Almost certainly yes — the only real risk is the fork-the-instructions trap, which the thin-launcher design already mitigates.
  5. Decide on #18 (cost tracking). The §1 wizard question forces the issue: ship the tracker, or drop the question.
  6. Decide on #16 (SQLite). Architectural; gate on whether #20 (semantic) is in scope and on whether scale demands it yet.
  7. Decide on #17 (research). Lowest urgency; defer to v0.4 if v0.3 already fills up.
  8. Ship #22 Phase A now (out-of-band v0.2.x). WSL2 callout is a ~1hr stopgap independent of the v0.3 wave. Phase B (native port) is demand-gated — re-evaluate after Phase A surfaces signal.
  9. #19, #20 ride along with whichever wave fits.

What's explicitly NOT on this list

These were considered and rejected during the comparison analysis. Documented so they don't get re-litigated.

  • Plugin marketplace distribution. Locked: atom is git+VERSION+curl, not a marketplace plugin. (atom_distribution_decision memory.)
  • Multi-provider LLM council. Too heavy. model-race covers "compare model outputs" from a different angle.
  • Auto-research BFS loop. Different product. Users who want it install pro-workflow into an atom-bootstrapped project.
  • 34 skills / 22 commands / 8 agents surface. Would balloon atom into a workflow framework. Out of identity.
  • Hosted "atom service". Permanently out of scope per the user-owned-data principle.