NextCorrectness · Robustness
Atomic, corruption-safe lock-file writes
read() returns an empty skeleton on any JSON error and write() is a bare write_text at core/lockfile.py:55. An interrupted or concurrent write truncates the lock — the next set_skill() then permanently drops every prior install record while store dirs linger as orphans. Write to a temp file + os.replace(), and tell "empty" apart from "corrupt".
Complexity M
Impact High
Wow ★★★★
ShippedPerformance
Memoize config.load() in-process
Every config.get() re-reads config.json and runs a recursive deepcopy of DEFAULTS (core/config.py:80–102). It's called all over hot paths — ai.enabled, per-skill enabled_agents in sync loops, log-level and policy checks — so one command triggers dozens of full reads + deep-copies. Cache the load, invalidate on save.
Complexity S
Impact Med-High
Wow ★★★
PlannedRobustness
Atomic skill install (temp-dir swap)
_copy_skill does rmtree(dest) then copytree() (core/store.py:108–131); an interrupt between the two leaves a missing or half-copied skill, and the lock is written afterward — so a mid-copy failure leaves store and lock disagreeing. Copy to a temp dir and atomically swap into place.
Complexity M
Impact Med
Wow ★★★
PlannedRobustness
One shared atomic-write helper
journal._maybe_rotate is a racy read-modify-write that concurrent appends can truncate mid-line; rag._save and config.save repeat the non-atomic pattern (journal.py:63 · rag.py:252 · config.py:93). Factor a single atomic_write into core and route all four through it.
Complexity S
Impact Med
Wow ★★
ShippedCorrectness
Unify _tilde() — two copies have a boundary bug
Eight command modules each define _tilde; the quality and intelligence versions use startswith(home) with no separator check (quality.py:78), so /Users/bob-backup wrongly contracts to ~-backup. Collapse to one helper in core/paths.
Complexity S
Impact Med
Wow ★★
PlannedPerformance
Cache the catalog entry-set across RAG queries
rag.retrieve() calls all_entries(), which reads & json.loads every tap cache on every search to build the live map (rag.py:323 · catalog.py:166–181) — the BM25 index is mtime-cached, the entry set is not. Memoize the entry set on cache mtime the same way.
Complexity M
Impact Med
Wow ★★★
ShippedPerformance
Stop re-serializing entry meta on every search
catalog.search computes json.dumps(meta).lower() for every entry on every query just to substring-match (catalog.py:222). Precompute a lowercased search blob at index time, or match structured fields directly.
Complexity S
Impact Med
Wow ★★
ShippedPerformance
Prune ignored dirs during scan_dir walk
Two full rglob passes descend into .git/node_modules and only filter afterward, and the skill-dir membership test is O(files × skill_dirs) (catalog.py:106,119–123). Switch to an os.walk that prunes ignored dirs in place; index skill dirs in a set.
Complexity M
Impact Low-Med
Wow ★★
PlannedTech-debt
Single tech-stack prober
Stack detection exists three times — discovery.detect_stack, intelligence._local_stack, quality._STACK_MARKERS (discovery.py:74 · intelligence.py:359 · quality.py:55) — and two already import detect_stack yet still carry a parallel marker table "as a fallback". Consolidate into one core prober.
Complexity M
Impact Med
Wow ★★
PlannedTech-debt
Single imperative-rule extractor
Three separate regexes scan SKILL.md bodies for "Always / Never / Must / Do not" lines across cmd_explain, simulate and conflict (info.py:363 · intelligence.py:254 · quality.py:822) — same concept, three implementations. Extract one shared core extractor.
Complexity M
Impact Med
Wow ★★
PlannedMaintainability
Split oversized command modules
quality.py (14 cmds / 1,051 lines) mixes audit regexes, conflict NLP, decay scoring, fingerprinting and a health dashboard; intelligence.py and configuration.py are similarly overloaded. Split along cohesive seams to shrink blast radius and sharpen mutation-gate targeting.
Complexity L
Impact Med
Wow ★★
ShippedMaintainability
Robust tag argument parsing
Because -tag looks like an option, cmd_tag calls parse_known_args then re-walks raw argv to reorder tokens (info.py:575–584) — fragile enough that the comment calls it "defensive". Replace with a positional-only sub-parser or an explicit --add/--remove design.
Complexity M
Impact Med
Wow ★★
PlannedTech-debt · RAG
Localize the stored BM25 snippet
_make_docs stores piece[:200] — the head of the best chunk — and retrieve surfaces it verbatim (rag.py:154–172,337–341), yet the docstrings promise the "best-matching passage". Center the snippet on the matched terms to improve display and the rerank context sent to the LLM.
Complexity M
Impact Low
Wow ★★★
PlannedCorrectness
Frontmatter scalar over-coercion
_scalar turns no/on/off/null into bool/None (core/frontmatter.py:32–53), so a tag or name literally equal to one of those parses to the wrong type and leaks into search/ranking meta. Restrict boolean coercion to true/false.
Complexity S
Impact Low
Wow ★★
PlannedTech-debt
Reuse helpers; kill minor dead work
cmd_migrate re-implements agent validation instead of calling _check_agents; _user() is copy-pasted between configuration and team; cmd_simulate parses the same frontmatter twice (pkg.py:38,577 · configuration.py:39 · team.py:30). Small, satisfying cleanups.
Complexity S
Impact Low
Wow ★
PlannedInstall engine · Rules
Rule install — materialize rules into each agent's native format
Today store.install refuses every non-skill kind
("rules and workflows show up in boost search/boost taps
for now"), so rules are indexed for discovery but land nowhere —
there is no boost install path for a rule. Add one that
writes each rule into the form the target agent actually reads, since
there is no single cross-agent "rules folder": Cursor/Windsurf/Cline
consume a rules directory (.cursorrules /
.windsurfrules / .clinerules / .mdc),
but Claude Code has no rules folder — its standing
rules are CLAUDE.md. So installing a rule for Claude means
merging it into CLAUDE.md (a managed, idempotent block),
while for the others it means dropping the file into their rules dir.
Needs a store/lock model for rules (uninstall must cleanly remove the
merged block), mirroring how skills symlink into enabled_agents().
Complexity L
Impact High
Wow ★★★★
rules are indexed but never installed
PlannedInstall engine · Scope
Workspace scope — boost install --local into the project
boost is user-global only: the store is ~/.agents/skills and every
install symlinks into home-level agent dirs (~/.claude/skills,
~/.cursor/skills, ~/.windsurf/skills). There is
no per-project scope — install takes --agent
(which agents) but no --global/--local. Add a
workspace paradigm mirroring npm (local vs
-g): boost install <skill> --local writes
into the current repo's .claude/skills/ (and the other
agents' project dirs), and — paired with rule install — merges a rule
into the project's ./CLAUDE.md rather than the global one,
so a team can commit its skills and rules with the repo. Needs a
per-scope store/lock, scope resolution (walk up for the nearest
project root), and list/sync/uninstall
that understand both scopes.
Complexity L
Impact High
Wow ★★★★
--global vs --local, project .claude/