prompt-lib

Cabal

Agentic development configuration in one place. Cabal is the local control panel for managing a machine's Claude Code and Codex setup. It gives you one terminal UI for deploying global agent configuration, checking setup drift, restoring backups, managing MCP connections, initializing environment variables, scaffolding local project configuration, installing companion CLIs, and browsing the agent/skill knowledge map.

This repository is the versioned source Cabal deploys: agents, slash-command skills, hooks, rules, output styles, MCP server templates, project templates, Codex-compatible assets, OKF catalog data, and the supporting services that make multi-agent workflows easier to run across projects.

Visual tour: open docs/infographic.html in a browser — single A4 landscape sheet, no scrolling, every feature at a glance. The longer scrollable variant is at docs/infographic-v1.html.

What Cabal Is Used For

Need	How Cabal handles it
Domain expertise on demand	29 specialist subagents (@dotnet-architect, @python-tester, @react-architect, @tanstack-architect, @frontend-css, @frontend-designer, @ux-analyst, @unity-architect, @requirements-analyst, @api-designer, @db-architect, @data-analyst, @website-content-analyst, @git-repo-analyst, @code-plan-verifier, @gitignore-auditor, @secret-auditor, @owasp-security-reviewer, @code-cleaner, @init-project, @load-project, …) auto-invoked when the task matches their description
Repetitive workflows (commit, PR, review, scaffold)	29 slash-command skills under global/skills/ — /git, /pr, /react-init, /react-review, /react-test, /react-perf, /react-safe, /css, /css-guide, /lovable-cleanup, /skill-create, /executing-plans, /finishing-a-development-branch, /using-git-worktrees, /systematic-debugging, /design, /ui-component, /orchestrate, /tui, /cli-llm-app, /add-mcp, /dependency-audit, /docs, /git-restore-identity, /github-audit, /github-scaffold, /infographics-design, /change-summary, /dotnet-codegen
Loading project context on session start	SessionStart hook detects whether the cwd has a CLAUDE.md; if yes, invokes @load-project; if no, offers to scaffold one from a template (.NET, Python, frontend, monorepo, Unity, generic)
Always-on context bloat	Conditional rules in global/rules/ (csharp.md, typescript.md, react.md, tests.md) load only when Claude touches a matching file; rules without a paths: filter (communication.md) are always on
Response-mode switching	Four output styles — concise, technical, review, architect — picked per session via /output-style
External tool integrations	Eight pre-wired MCP servers: context7, github, figma, playwright, azure-devops, supabase, obsidian, docker (env vars resolved via ${VAR} substitution)
Multi-machine setup / deployment	Cabal, an interactive local agent control panel via the root launcher (./run on POSIX, .\run.cmd on Windows) — deploy, init env vars, show inline drift markers, restore from backup, local project scaffold, optional companion tools. The supported graphical workspace lives in apps/cabal-desktop/.
Install without cloning	/plugin marketplace add dwcy/prompt-lib + /plugin install prompt-lib@prompt-lib ships skills, agents, hooks, MCP servers, and output styles as a Claude Code plugin. The apply-script path remains the way to get the full setup (global CLAUDE.md, rules, permissions, theme). See docs/plugin-install.md.
Cross-agent delegation (Claude ↔ Gemini)	services/a2a-bridge — A2A protocol v1.0.0 implementation, Python 3.14 + FastAPI, 199 tests passing
Autonomous PR review	services/orchestrator — daemon that watches a GitHub repo, dispatches each PR to a peer Claude agent over the A2A bridge, posts the review back via gh, persists state to SQLite, pushes phone notifications via ntfy.sh, ships with a Textual dashboard
Spec-driven feature work	specs/ holds spec-kit feature trees (spec, plan, research, data-model, contracts, tasks, quickstart) — 001-a2a-bridge, 002-agent-orchestrator, 003-issue-triage, 004-github-plugin
Agent ecosystem knowledge graph	OKF (Open Knowledge Format) exports agents, skills, hooks, rules, templates, Codex assets, and specs into a portable catalog plus graph.json, so AI tools and reviewers can inspect routing, overlaps, unused concepts, and skill-agent connections. See docs/okf/README.md.
Tool-call safety	PreToolUse hooks (command_guard.py, file_write_guard.py, pretool_branch_guard.py, pretool_inflight_guard.py) and PostToolUse audit (write_audit.py) intercept risky operations — including editing a file that another session left uncommitted. See docs/hooks.md.
Authoring new skills	/skill-create — scaffolds, tests, and refines new slash commands

Statusline

The "tile bar" Claude Code renders at the bottom of the terminal. Script: global/statusline.py. Wired up via statusLine in global/settings.json. Two rows — row 1 is session state from the stdin JSON snapshot Claude Code passes per turn, row 2 is workspace state from cheap git + filesystem probes.

Codex uses its native TUI statusline rather than this script. Cabal's Statusline screen exposes all native Codex items from global/codex/statusline-segments.json, supports individual and enable-all/disable-all toggles, preserves ordering, and updates only [tui].status_line plus [tui].status_line_use_colors in ~/.codex/config.toml.

✦ Opus 4.7  │  ⬆ 2.1.158  │  ◐ 34%  │  💰 $0.42 · 12m  │  Δ +142 -38  │  📝 explanatory  │  ⏳ 5h:78%  │  ⊙ C:/projects/prompt-lib
⎇ 005-cabal-tools-polish  │  ↑3 ↓1  │  ±5f  │  ⚑ 2  │  🐳 docker  │  ✓ 47  │  🎯 P3 8/14  │  🤖 3 · 🛠 14

Row 1 — session state (from stdin JSON, zero I/O)

Segment	Source	What it shows	Hides when	Color logic
✦ <model>	model.display_name	Active model name (e.g. Opus 4.7)	never	cyan
⬆ <version>	~/.claude/.update_state.json (populated by hooks/check_claude_update.py — npm registry GET, 6-hour TTL cache)	Latest available Claude Code version on npm — shown only when a newer release exists	running version matches npm latest, or cache file not yet populated	orange
💰 $<usd> · <duration>	total_cost_usd, total_duration_ms	Session cost so far + wall-clock duration	cost field missing	green <$1 → yellow <$3 → orange <$10 → red ≥$10
Δ +<a> -<r>	total_lines_added, total_lines_removed	Lines added / removed across all edits this session	both counters 0	adds green, removes red
📝 <style>	output_style.name	Active output style — reminds you a non-default style is biasing responses	style is default	cyan
⏳ 5h:<%> 7d:<%>	five_hour, seven_day	% quota remaining before 5-hour / 7-day rate limits hit	both quotas have >90% headroom (nothing to worry about)	green >50% → yellow >25% → red ≤25%
⊙ <cwd>	workspace.current_dir	Project path rendered as a clickable VS Code link (OSC 8 hyperlink → vscode://file/<path>). Ctrl+Click to open in Windows Terminal	cwd missing	violet

Row 2 — workspace state (git + filesystem, 1s timeout-guarded)

Segment	Source	What it shows	Hides when	Color logic
⎇ <branch> (with 🌳 worktree: prefix)	git branch --show-current + git rev-parse --git-dir --git-common-dir	Current branch; worktree prefix appears when this checkout is a git worktree (not the main checkout)	not a git repo	gold; worktree prefix green
↑<a> ↓<b> or ↕ sync	git rev-list --count --left-right @{u}...HEAD	Commits ahead of / behind upstream — ↕ sync when both are 0	branch has no upstream	ahead green, behind orange
±<n>f	git status --porcelain	Number of dirty files (staged + unstaged)	working tree is clean	yellow
⚑ <n>	git stash list	Stash count	zero stashes	violet
🐳 docker	filesystem probe — Dockerfile, docker-compose.{yml,yaml}, compose.{yml,yaml}	Whether the project is dockerized	never (shows 🐳 N/A when absent)	bright cyan when present, gray when absent
✓ <n> / ✗ <f>/<n> / ◑ <pct>%cov	First detector that matches: .NET TestResults/*.trx → pytest .pytest_cache/v/cache/lastfailed+nodeids → Jest/Vitest coverage/coverage-summary.json → Playwright test-results/results.json or playwright-report/results.json	Pass count, failure ratio, or coverage % from the most recent test run	no detector matches (shows ✓ N/A)	green pass, red fail, yellow low coverage
🎯 P<n> <m>/<t> or 🎯 ✓ all	Parses specs/<branch>/tasks.md for the first non-✅ **Status**: …(M/N — T###–T###) line	Active speckit phase + M/N task progress; ✓ all when every phase is complete	not on a NNN-feature-name branch, or no tasks.md	gold mid-flow, green when complete
🤖 <a> · 🛠 <t>	~/.claude/.session_state.json written by the PostToolUse hook	Agents dispatched · tools called this session — proves work is happening even when output is quiet	hook hasn't fired yet, or session_id doesn't match	agents violet, tools gray

How it works

• Snapshot, not live. Claude Code invokes the statusline command once per turn boundary and passes session state on stdin per the statusline contract. There is no streaming or refresh — segments update on the next turn.
• Multi-row layout. Every \n printed becomes a new row; vertical spacing comes from settings.json → padding.
• Cheap reads only. Every git / filesystem call is timeout-guarded (1s) and falls back silently on error — the statusline never blocks the prompt.
• Activity counters. The 🤖 · 🛠 segment is driven by global/hooks/post_tool_use.py, a PostToolUse hook that increments per-session counters in ~/.claude/.session_state.json. Counters reset automatically when session_id changes.
• Update check. The ⬆ segment reads ~/.claude/.update_state.json, populated by global/hooks/check_claude_update.py. The statusline fire-and-forgets that script (detached subprocess, no console flash on Windows) whenever the cache is older than 6 hours, so the next render picks up a fresh result. Network call hits the public npm registry only — no Claude API traffic, no rate-limit cost.
• OSC 8 hyperlink. The cwd segment uses an ANSI OSC 8 escape with the SGR color codes wrapping the hyperlink (not nested inside it) so Windows Terminal hit-tests the link region correctly. If clicking does nothing, verify the URI handler with start vscode://file/C:/projects/prompt-lib in PowerShell.

Customize / disable

• Disable entirely: delete the statusLine block from global/settings.json and reapply.
• Configure interactively: open Cabal → StatusLine, choose Codex or Claude Code, toggle/reorder items, and save.
• Change Claude defaults: edit global/statusline-segments.json.
• Change Codex defaults/catalog: edit global/codex/statusline-segments.json.
• Add a segment: write a seg_* function returning a colored string (or None to hide), and append to row1 / row2. Falsy returns are filtered before the SEP.join.
• Change colors: every segment passes RGB tuples through the rgb() helper — no theme indirection, just edit the literal tuples.
• Change thresholds: color bands live in ctx_color(), cost_color(), headroom_color() near the top of the file.

Slash commands

Every command available in this project, grouped by purpose. Source links point at the SKILL/command file; docs links point at the relevant section in docs/.

Git workflow

Command	When to use	Links
/git	Full git workflow — branch safety, conventional commits, agent authorship, push guard	src · docs
/commit	Quick conventional commit without the full safety machinery — fixups inside a feature branch	src · docs
/pr	Draft a PR title + description from branch diffs, then create it with gh pr create	src · docs
/review	Structured branch review against main — Critical / Warning / Suggestion findings	src · docs
/finishing-a-development-branch	End-of-feature checklist — runs tests, builds, commits, offers PR/push	src · docs
/using-git-worktrees	Create/list/remove/prune git worktrees for parallel Claude Code sessions	src · docs
/standup	Generate a standup summary from recent git log	src · docs
/git-restore-identity	Clear a stuck --local agent git identity after a crashed commit	src · docs
/github-audit	Read-only audit of a repo's GitHub hygiene — settings, protections, workflows	src
/github-scaffold	Scaffold .github/ — CodeQL, CI, Dependabot, CODEOWNERS	src

Planning & implementation

Command	When to use	Links
/plan	Plan a non-trivial feature — classify, scope, contract (full-stack), task breakdown, spawn parallel agents with worktree isolation	src · docs
/executing-plans	Execute a written tasks.md plan with review checkpoints between phases	src · docs
/systematic-debugging	Root-cause-first debugging — reproduce, pattern, hypothesis, verified fix; three failed fixes stops and questions the design	src · docs
/adr	Create a numbered Architecture Decision Record under docs/adr/	src · docs
/cli-llm-app	Integrate Claude Code / Codex into an app via the CLI (subscription auth, no API key) — persistent-subprocess pattern, flag gotchas, stream-json schema	src
/orchestrate	Automatic subagent routing — analyse the task, dispatch specialists with worktree isolation, aggregate results	src · docs
/tui	Textual TUI lessons learned from the cabal wizard — Ctrl+C-is-copy, clipboard, Pilot tests, child-process lifecycle	src

Spec-kit feature flow

Command	When to use	Links
/speckit-constitution	Create or amend .specify/memory/constitution.md (principles, gates)	docs
/speckit-specify	Generate spec.md from a natural-language feature description	docs
/speckit-clarify	Resolve NEEDS CLARIFICATION markers in spec.md via up-to-5 targeted questions	docs
/speckit-plan	Produce plan.md + Phase 0 design artifacts; must clear Constitution Check gates	docs
/speckit-tasks	Generate tasks.md with Owner: @<agent> + Phase Status + Parallel: yes markers	docs
/speckit-analyze	Non-destructive cross-artifact consistency check across spec/plan/tasks	docs
/speckit-checklist	Generate a feature-specific QA checklist	docs
/speckit-implement	Execute tasks.md task-by-task, dispatching to named owners (with worktree isolation for Parallel: yes)	docs
/speckit-taskstoissues	Convert tasks.md into ordered GitHub issues via gh	docs
/speckit-git-*	Do not use — these auto-execute git commands without the /git safety machinery. Driven from the /git skill instead per global rules	docs

Frontend / React

Command	When to use	Links
/react-init	Scaffold a full current-stable React project — Vite + TS + Zustand + TanStack + Biome + Tailwind + Zod + MUI Icons	src · docs
/react-review	Code-quality review of a React file/feature — Critical / Warning / Suggestion	src · docs
/react-test	Scaffold or review Vitest + RTL tests for a component, hook, or feature	src · docs
/react-safe	Audit a React file for async correctness, error handling, security gaps	src · docs
/react-perf	Performance audit — re-renders, memoisation, bundle size, lazy-load opportunities	src · docs
/css	scaffold for globals.css, or <ComponentName> for <Name>.module.css next to the component	src · docs
/ui-component	Build a UI component on demand — design-language compliance, Preview, semantic HTML, Zustand+Zod forms	src · docs
/design	Load the Premium Digital Agency 2.0 design system into context before styling decisions	src · docs
/lovable-cleanup	Strip all Lovable / GPTEngineer scaffolding from a project	src · docs
/css-guide	CSS-first techniques & animations — prefer CSS over JS for hover/scroll/reveal effects, layout, state toggles	src
/infographics-design	Single-file HTML infographic or printable A4 visual overview with CSS-only data viz	src

.NET

Command	When to use	Links
/dotnet-class	Create or refactor a .NET class following Clean Architecture conventions	src · docs
/dotnet-test	Create or refactor a .NET integration test with TestContainers	src · docs

Documentation & memory

Command	When to use	Links
/docs	Generate a /docs folder for a project — index + architecture + per-component reference + workflows + learning path	src · docs
/readme	Drift-check the top-level README against the live repo state (skills, agents, hooks, MCP servers, statusline segments) and propose surgical patches	src
/self-improvement	Maintain project memory (lessons / mistakes / preferences / evals); stale-detect and remove obsolete entries	src · docs
/skill-create	Design, write, test, and refine a new skill — scaffolds the Agent Skill folder with scripts/, references/, assets/	src · docs

Meta / safety

Command	When to use	Links
/review-conflicts	Detect overlapping agent / skill descriptions that would cause routing collisions	src · docs
/prompt-injection-guard	Scan staged content for prompt-injection patterns before commit	src · docs
/dependency-audit	Audit project dependencies for known vulnerabilities — read-only, reports by severity with upgrade paths	src
/add-mcp	Register an MCP server the right way — scope precedence, Windows .cmd wrapping, env-var handling	src · docs
/xlsx	Read, edit, and recalculate Excel workbooks via LibreOffice + python-openpyxl	src · docs

Layout

prompt-lib/
├── run                  ← POSIX root launcher for the setup wizard, web UI, and Tauri app
├── run.cmd              ← Windows root launcher for the setup wizard, web UI, and Tauri app
├── global/              ← deploy target: ~/.claude/
│   ├── settings.json    ← MCP servers, hooks, theme, model
│   ├── CLAUDE.md        ← always-loaded global behaviour
│   ├── agents/          ← @-invocable specialist subagents
│   ├── skills/          ← /-invocable slash commands
│   ├── hooks/           ← SessionStart / PreToolUse / Stop scripts
│   ├── rules/           ← rules: path-conditional (`paths:`) or always-on
│   ├── output-styles/   ← response formatting profiles
│   └── project-templates/  ← templates used by @init-project
├── setup/               ← TUI installer (settings-configurator-ui.py)
├── services/
│   ├── a2a-bridge/      ← A2A protocol bridge
│   └── orchestrator/    ← PR-review daemon
└── specs/               ← spec-kit feature trees

Apply changes

# macOS / Linux / POSIX shells
./run

# Windows
.\run.cmd

The root launcher delegates to the platform-specific setup bootstrapper, which finds Python or offers to install it where supported. After applying, restart Claude Code.

Direct source fallback: python setup/settings-configurator-ui.py.

Fallback (non-interactive): bash setup/tools/apply-global-claude-settings.sh.

Web UI

The active overhaul is the Cabal desktop workspace: a Vite + React frontend, a local FastAPI backend, and a Tauri shell that spawns or adopts the backend as a sidecar. It covers the full 22-module control surface rather than the legacy read-only dashboard.

# Fast browser loop (backend + Vite with hot reload)
./run web                 # POSIX
.\run.cmd web             # Windows

# Desktop shell
./run tauri               # POSIX
.\run.cmd tauri           # Windows

# Production shape
uv run --with pyinstaller python setup/build/build_backend.py
cd apps/cabal-desktop
pnpm tauri build

The production bundle expects the sidecar at setup/build/dist/cabal-backend-<target-triple>[.exe]; Tauri launches it as cabal-backend and injects the per-launch bearer token into the webview.

Development validation

Run all test suites that are available on the current machine:

python scripts/test-all.py

For release readiness, require every suite runner to be present:

python scripts/test-all.py --strict-missing

Service integration tests that need real CLIs, GitHub auth, or live local daemons stay opt-in:

python scripts/test-all.py --include-integration --strict-missing

Alternative: install as a Claude Code plugin

You can install skills/agents/hooks/MCP servers without cloning the repo:

/plugin marketplace add dwcy/prompt-lib
/plugin install prompt-lib@prompt-lib

Plugin install ships the shareable surface (skills become /prompt-lib:*, agents become prompt-lib:*). Items the plugin model can't carry — global CLAUDE.md, global/rules/, global/project-templates/, permissions, theme, statusLine — stay on the apply path. Both paths coexist. Full guide at docs/plugin-install.md; design at specs/004-github-plugin/.

Further reading

Deep documentation (docs/)

• docs/README.md — index + reading order
• docs/architecture.md — 5-step session boot; how agents, skills, MCP tools, hooks, and rules fit together
• docs/settings.md — every field in global/settings.json explained (model, permissions, MCP servers, hooks)
• docs/agents.md — every subagent: purpose, tools, when triggered, composition partners
• docs/skills.md — every slash command: trigger, behaviour, allowed tools
• docs/hooks.md — SessionStart, PreToolUse, PostToolUse, Stop scripts and what they protect
• docs/rules-output-styles.md — file-pattern conditional rules, response styles, project-init templates
• docs/workflows.md — multi-agent recipes: spec-kit → worktree → plan → implement → verify → review → PR
• docs/parallel-isolation.md — when concurrent subagents must run in isolated git worktrees, why, and how
• docs/speckit.md — spec-kit configuration in this repo: constitution, gates, slash commands, templates, delegation roster, phase-status rule, git-extension override
• docs/services.md — a2a-bridge and orchestrator daemons in detail
• docs/plugin-install.md — install prompt-lib as a Claude Code plugin (no clone), scope split with the apply path
• docs/release-readiness.md — package-publishing prerequisites and release checklist
• docs/learning.md — 5-day learning path, mental shortcuts, debugging surprises

Other references

• global/README.md — full Claude Code behaviour walkthrough (how agents trigger, how skills resolve, how overlapping tools are picked)
• global/MCP.md — MCP server setup and token configuration
• setup/README.md — installer modes
• services/a2a-bridge/README.md, services/orchestrator/README.md — service docs
• specs/ — spec-kit feature trees