v1.4.0: set up without a terminal, safer setup, novice-first README

Built for people who have never opened a terminal. Compabob now installs and
sets up entirely from the Claude desktop app or VS Code, the README walks each
path step by step, and setup can no longer leave a half-finished workspace behind.

Before you update: .claude/settings.json changes in two small ways (saving
to vault/, memory/, .tmp/ and config/user.config.yaml no longer asks for
permission; a skill-listing budget key). If you edited that file, update.sh will ask you to merge it.
Setup now stops before creating anything when Python 3 is missing.

Added

• /setup skill: the whole setup from inside the chat. It asks the questions
  in plain words, runs setup.sh with the answers (one permission box), and
  confirms from the files it wrote. No terminal needed.
• setup.sh options: --assistant, --user, --role, --language,
  --persona, --focus, --integrations / --no-integrations,
  --non-interactive, --help. Without options it asks the same seven questions
  as before. CI now uses the options instead of piped newlines.
• Session-start notices: when setup has not run or did not finish, the
  assistant says so and offers /setup; once after setup it greets you by name and
  suggests a first task; it notes when the kit was updated since the last session
  and which kit files you have edited.
• skeptic agent: checks a claim or finding against the files before anyone
  acts on it; read-only, never edits or sends.
• /design-precheck skill: the pre-mortem the plan gate asks for, run by three
  advisors in parallel and folded into the plan. The plan gate's message now
  points to it, and it accepts numbered lists as well as bullets.
• Constitution: the plain requests a non-technical user will make ("update the
  kit", "run the health check") mapped to the kit's scripts; two routing rules for
  when two agents seem to apply; an approved plan is not approval to send its
  draft; a declined permission gets narrower options, never a workaround.
• README: rebuilt around three paths (desktop app, VS Code, terminal) with
  exact clicks, a "what you will see the first time" section (trust question,
  permission boxes, style notes, where your files live), and one honest time budget.
• tests/test-setup-noninteractive.sh (38 cases) and tests/test-session-start.sh
  (17 cases).

Fixed

• Setup left placeholders behind forever when Python was missing: it copied
  the seed files, failed while filling them in, and a re-run then skipped them as
  "already exists". It now stops before creating anything, and a re-run fills any
  blank it finds, so an older half-finished setup repairs itself.
• Re-running setup printed the name you just typed, not the one on disk. It
  now says "Already set up" and shows what is stored.
• The style check read the previous reply. Claude Code can run the Stop hook
  before the transcript holds the final reply; the hook now reads the reply from
  its input (last_assistant_message).
• Every fresh clone showed a modified kit file: modules/dictation/install.sh
  was tracked without its executable bit, so setup's chmod changed it and
  update.sh had to set it aside on every run.
• update.sh on a conflict told you to run git stash pop in the middle of a
  merge, which fails. It now shows git's message, the files that need a decision,
  and git merge --abort to put everything back.
• The walkthrough never installed uv, which two of the integrations need.
• The demo image showed five personas and a username default that no longer exist.
• Docs: the update description, the pre-mortem hook listed as "optional" although it
  ships, and a stale model ID example (claude-sonnet-5-5).

Removed

• docs/qa-findings-2026-05-24.md, the May QA log (every item was fixed in 1.1.1;
  it stays in the git history).

v1.3.0: style system, tests, hybrid search, /council, pre-mortem gate

The style system, a test suite, and three features from the setup this kit is
distilled from: hybrid memory search, /council, and a pre-mortem gate for
high-stakes plans.

Before you update: the new style check runs after every reply. It starts in
warn mode, which only shows a one-line note; set style_gate: block or off
in config/user.config.yaml (the update adds the key for you). Most kit text
files changed in this release, because every em dash was removed from them, so
update.sh will ask you to merge any kit file you edited yourself.
git diff --stat v1.2.0 v1.3.0 lists them.

Added

• Style check hook (hooks/hook-style-gate.py, runs when a reply ends):
  flags em dashes used as connectors and paragraphs over about 700 characters
  in long replies. Code, blockquotes, and dialogue dashes are ignored.
  style_gate: warn | block | off.
• /council skill: two advisors and a dissenter assigned to argue the
  other side, in parallel; the recommendation must answer each objection. For
  decisions that are hard to reverse.
• Pre-mortem gate (hooks/hook-plan-premortem.py): when you approve a plan
  that is irreversible, touches many people, or commits weeks of work, it asks
  for a pre-mortem from strategy-advisor first.
• Hybrid memory search: keyword search always, plus search by meaning when
  Ollama is running, merged into one ranking. Results show the heading path
  they came from. Rebuild the index once with /index-memory after updating.
• Session-start notices: today's scheduled brief, scheduled-run failures
  from the last week, a MEMORY.md over 12KB, and config keys a kit update
  added.
• Test suite: bash tests/run-all.sh runs everything CI runs (syntax,
  shellcheck, hook behaviour, frontmatter, docs versus tree). CI adds a macOS
  job.

Changed

• Direct output style rewritten with what the upstream setup learned about
  brevity: cut whole categories of content, a filler test for every sentence,
  bullet-first reports, floors for outward messages and corrections. It now
  keeps Claude Code's built-in coding instructions (keep-coding-instructions).
• The constitution is shorter: style rules live only in the output style,
  the data-quality checklist only in the analyst agent. Adds a stopping rule:
  keep going until the task's finish line unless you need the user.
• Prompt-injection defender also scans MCP tool output (mail, browser,
  search) and skips the kit's own files.
• Handover notes older than a week are no longer loaded into every new
  session; the assistant is told the note exists instead.
• Scheduled runs tell the assistant nobody is watching, so it does not stop
  to ask questions.
• Skill descriptions name their neighbour both ways (for example
  /morning-brief and /tasks), so the right one gets picked.
• /reflect records unapproved memory proposals in today's daily note in
  the format /memory-debt reads, so the two skills finally connect.
• /chart-tufte is a grader that /visual-explainer calls after building
  a chart.
• No em dashes anywhere in the kit.

Fixed

• comms-guard blocked reading modules/telegram/send.sh, not just
  running it.
• Two skill descriptions were invalid YAML (an unquoted colon).

Full changelog: v1.2.0...v1.3.0

v1.2.0: fixes, Claude Code drift, simpler kit

Maintenance release: the modules and skills that shipped since 1.1.1, fixes
for bugs found in a full audit, the Claude Code changes since June, and a
smaller kit. Safe to pull with ./update.sh: your vault/, memory/,
config/user.config.yaml, .mcp.json, and .env are untouched, and any new
config flags are added for you.

If you edited kit files, update.sh may ask you to merge the ones this
release also changed: every agent in .claude/agents/, .claude/settings.json,
CLAUDE.md, the add-agent, mcp-debug, and memory-debt skills, setup.sh,
update.sh, everything in scripts/ and docs/, and the proactive, telegram,
transcribe, dictation, and integrations modules. git diff --stat v1.1.1 v1.2.0
lists them all. Personas and the other skills are unchanged.

Added

• dictation module: a cleanup endpoint your dictation app (e.g. Handy)
  posts to. It fixes punctuation and fillers, and rewrites words it keeps
  getting wrong using a glossary that grows itself from recurring corrections.
  OpenAI-compatible upstream (Groq by default, Ollama for fully local).
• /weekly-review skill: end-of-week review of what got done, what
  slipped, decisions, commitments, and next week's top three (#16).
• researcher persona preset for academia and R&D (#19).
• Spanish README intro at docs/i18n/README.es.md (#23).
• Linux and WSL troubleshooting section in the README (#14).
• scripts/migrate-config.sh: adds config keys a kit update introduces,
  inside the right block, with a .bak; never changes a value you set.
  update.sh runs it, and scripts/init.sh warns when keys are missing.
• scripts/lib/common.sh: shared output helpers and set_config_flag.
• transcribe module (highly encouraged) — one-hotkey local call recording +
  transcription. A toggle script drives ffmpeg to capture audio and
  mlx-whisper to transcribe it on-device: first run records, second run stops,
  transcribes, copies the text to your clipboard, and files a markdown transcript
  (with frontmatter) into vault/raw/meetings/ for your notes pipeline. Defaults
  to an aggregate device so both sides of a call are captured. No cloud service,
  no API key, audio never leaves the machine. Device names are overridable via
  TRANSCRIBE_DEVICE_* env vars (record.py devices lists yours); optional
  Hammerspoon/Raycast hotkey binding documented. Opt-in via transcribe: true.
• crm-merge module + /merge-contacts skill — folds Google Contacts (Takeout
  vCards), a LinkedIn data export (Connections + messages), and your vault
  People/ notes into one local source of truth: a SQLite DB, a JSON file, and a
  self-contained offline HTML browser. Identity resolution uses union-find on
  three keys (verified email, LinkedIn slug, normalized name) with a common-name
  collision guard, so duplicates collapse without over-merging generic names.
  Relationship strength (LinkedIn message count) ranks records. No credentials,
  all stdlib, idempotent. Outputs are git-ignored.
• lead-pipeline module + /build-list skill — turns a raw candidate list
  into a ranked, CRM-aware outbound list through staged steps that write one CSV
  per stage (discover → clean → dedup-against-CRM → enrich → score → top-N).
  The deterministic stages (clean, dedup, score) run as a stdlib script;
  discovery and enrichment run as assistant steps over optional MCP servers (exa
  free tier minimum; an enrichment provider optional). Dedup tags each lead
  proceed (cold), warm (you already know someone at the account, route the
  intro), or skip (already a known contact), so you never enrich or cold-email
  a relationship. ICP scoring is a tunable JSON rubric (icp.example.json).
• /chart-tufte skill — self-grade rubric for any quantitative chart,
  grounded in Edward Tufte's Visual Display of Quantitative Information.
  Nine criteria, ten genres, seven remedies, plus a 114-line
  references/vdqi-catalogue.md with named failures (NYT MPG 14.8, TIME
  barrel 59.4) and named exemplars (Minard, Marey, Snow, Playfair). Designed
  to run as the final pass inside /visual-explainer whenever the output is
  a chart.
• /mcp-debug skill — health-check, trace, or audit your configured MCP
  servers when tools fail silently. Three modes: status (per-server
  reachability), trace <tool> (likely failure mode for one tool), audit
  (recommendations for unused / high-error / duplicate servers). Reads
  ~/.claude.json and ./.mcp.json; redacts secrets in every output.
• /memory-debt skill — review and apply memory updates that earlier
  sessions proposed but never wrote. Scans vault/Daily/, vault/Reflections/,
  and vault/Journal/ for - [ ] proposals from /reflect, classifies each
  as PENDING / STALE / OBSOLETE / APPLIED, then in apply mode walks through
  approvals one by one. Closes the loop between /reflect (proposes) and
  memory/.

Changed

• Agents follow your model. Every agent uses model: inherit instead of
  sonnet, so switching models in Claude Code switches the agents too. On a
  Pro plan, see the README for pinning them back to Sonnet. Scheduled modules
  still run on Sonnet.
• Install Claude Code with the native installer
  (curl -fsSL https://claude.ai/install.sh | bash); npm stays documented as a
  fallback (Node 22+). Docs links point at code.claude.com.
• README model section rewritten (closes #9): Claude Code's default is now
  Opus 5.5 on every paid plan; how to change it per session, per project, or
  globally.
• Integrations: pins bumped (@playwright/mcp 0.0.82, scrapling-fetch-mcp
  0.2.4, mcp-server-time 2026.8.18, exa-mcp-server 3.4.1, which needs
  Node 20+). Gmail and Calendar now point at Claude's own connectors.
• SessionStart hook also runs after /clear and in forked sessions.
• Config template: flags for crm_merge and lead_pipeline; persona list
  shows all six.
• transcribe and dictation install their Python dependency into a
  module venv (Homebrew Python refuses a global pip install); record.py
  switches to its venv on its own, so hotkeys keep working.
• update.sh says what to do on a local-only branch or detached HEAD
  instead of blaming the network.
• scripts/init.sh checks for Python 3.10+ and counts only real agents.

Removed

• Tool-scope guard hook (never released): it was not wired into
  settings.json, needed jq, and matched no context the kit sets.
• Stub modules extra-agents, team, and whatsapp, which were README
  files only. Their reasoning now lives in the "Not built" section of
  modules/README.md; the roadmap is issue #12.
• mcp-server-fetch from the integrations catalog (Claude Code's built-in
  WebFetch covers it) and the empty google category.
• Dead config keys: preferences.timezone, extra_agents, team. Existing
  configs keep them; nothing reads them.

Fixed

• Weekly review ran on Saturday on macOS: launchd counts Sunday as 0, so
  Weekday 6 was Saturday. Now Friday.
• Scheduled runs could not find claude under launchd's minimal PATH
  (proactive, telegram).
• The agent template registered as a real agent. It is now
  .claude/agents/_agent-template.md.template.
• install-integrations.sh left an empty .mcp.json on runs that added
  nothing.
• Docs claimed config/ is git-ignored; only config/user.config.yaml is.
• /add-agent and the customization guide pointed at
  _orchestrator-reference.md as an agent registry; routing lives in
  CONSTITUTION.md.
• Telegram README said the hook "blocks until you approve"; the hook always
  blocks, and you send with send.sh yourself.

Full changelog: v1.1.1...v1.2.0

v1.1.1 — QA pass bug fixes

Same-day follow-up to v1.1.0. Ran a full QA pass across 5 personas × 10 input edge cases × idempotency × update.sh × integrations × init.sh × a pristine Docker Ubuntu run × a headless claude -p smoke. 11 findings, all fixed in this release.

Full QA report: docs/qa-findings-2026-05-24.md.

What's fixed

P1 — silent data loss on re-run

• setup.sh re-run silently overwrote memory/topics/role-and-priorities.md if the user started with the generalist persona and edited the file. The "untouched template" guard treated [the most important thing] as a marker, but that string also lived in config/personas/generalist.md, so user edits were wrongly classified as untouched and overwritten. Marker tightened to [fill in], which only appears in the shipped template. The other four personas (consultant, engineer, sales, founder) were never affected.

P2 — confusing or imprecise behavior

• whoami default for "Your name" leaked the OS account name (e.g. root inside Docker) into memory/MEMORY.md if the user hit Enter. Default removed; setup re-prompts.
• Persona seeding ran before placeholder replacement, so seeded personas could ship with {{USER_NAME}} still on disk. Order flipped.
• Piped-mode setup (printf ... | ./setup.sh) swallowed the final newline and the integrations prompt collided with EOF. Newline guard added.
• install-integrations.sh printed "Done." on no-op runs (unknown category, empty selection). Now exits non-zero with a clear "nothing installed" message.
• .mcp.json was created eagerly even when no integrations were selected, leaving an empty file. Creation deferred until at least one integration writes to it.
• init.sh warned instead of failing when integrations were enabled but .mcp.json was missing.

P3 — polish

• update.sh now shows the list of pulled commits and a clearer "your data lives here" banner.
• README — clarified which paths are "yours" vs. tracked kit content, corrected the walkthrough prompt count, added a YAML-escape note for names with apostrophes.

Upgrade

cd /path/to/your/compabob
./update.sh

Your vault/, memory/, config/user.config.yaml, .mcp.json, and .env are untouched. If you started with the generalist persona and edited memory/topics/role-and-priorities.md before this release, please check that file once after upgrading.

Full diff

v1.1.0 → v1.1.1

v1.1.0 — Post-launch hygiene

Four days after launch. Pure hygiene release — no module changes. The aim is to make the kit feel as alive on day 30 as on day 1, before the silence sets in.

What's new

CI

• Weekly fresh-clone smoke test at .github/workflows/smoke.yml. Runs on every push, every PR, every Monday 06:00 UTC, and on-demand. Each run: bash -n on all shell scripts, ./setup.sh non-interactive, scripts/init.sh, integrations-catalog JSON validation. Bit-rot from upstream Claude Code changes will surface here, not in someone's first ten minutes with the kit.
• CI badge now visible at the top of the README.

README

• Badges row: CI, License, Stars, Last commit.
• New "How this differs" section comparing Compabob to raw Claude Code, awesome lists, multi-agent dev-team frameworks, and rolling your own from scratch.
• memory-search module status fixed: was "Roadmap" in the modules table, but ships available (keyword FTS5 by default, semantic via Ollama if installed).

Community + signals

• .github/FUNDING.yml surfaces a Sponsor button (LinkedIn — no Sponsors listing). Visible maintenance cue.
• CHANGELOG.md in Keep-a-Changelog format. Past + future releases will have a home.
• 5 good first issue tickets seeded (#7–#11): researcher persona, /weekly-review skill, model-swap docs, Spanish README intro, Linux troubleshooting hints. Pick one if you've been looking for an excuse.
• Pinned roadmap at #12.
• Show-and-tell discussion at #13: "Show me your daily-copilot prompt — the one tweak that made it click."

Full diff

v1.0.0 → v1.1.0

Compabob v1.0.0

First tagged release of Compabob.

A customizable Claude Code setup for knowledge workers. Clone it, run ./setup.sh, name your assistant, and in about ten minutes you have a working AI work partner: it knows your role, remembers what you tell it, routes work to specialized agents, and never sends anything without your sign-off.

What's in the box

• Specialized agents selected by description-driven routing, not by name.
• Safety hooks, including a draft-never-auto-send guard on anything that leaves your machine.
• Skills as slash-command workflows you can copy and extend.
• A memory system of one-fact-per-file notes the assistant maintains over time.
• An Obsidian-ready knowledge base scaffold for notes, meetings, and research.
• setup.sh / update.sh for a guided install and rolling updates that never touch your vault, memory, or config.

Getting started

git clone https://github.com/chacosoldier/compabob.git
cd compabob
./setup.sh

See the README for the quickstart and a full no-terminal-experience walkthrough. It runs entirely on your own machine under your own Claude subscription. No signup, no telemetry.