BALDART — private agent framework

Private framework for coordinating Claude Code, Codex and human developers. Repository, CLI, payload, issues and bat-beacon transcripts are private.

What Is This?

BALDART provides a portable system for:

• Agent Coordination: Clear protocols (AGENTS.md) defining how AI agents and humans work together
• AI Agents: Pre-built specialized agents (coder, code-reviewer, doc-reviewer, etc.)
• Commands: Batch orchestration (/new), design reviews, issue analysis
• Templates: Backlog cards, PRDs, specs, breaking change checklists
• Documentation Structure: Standard layouts for API docs, data models, UI specs

Quick Start

Bootstrap

Requirements: Node.js >=18, npm, GitHub CLI (gh) and access to antbald/BALDART.

Existing users of the final public bridge:

baldart private-bootstrap

New machines:

gh auth login --hostname github.com
gh auth setup-git --hostname github.com
tmp_dir="$(mktemp -d)"
gh release download --repo antbald/BALDART --pattern 'baldart-cli-*.tgz' --dir "$tmp_dir"
gh release download --repo antbald/BALDART --pattern SHA256SUMS --dir "$tmp_dir"
(cd "$tmp_dir" && grep 'baldart-cli-' SHA256SUMS | shasum -a 256 -c -)
npm install -g "$tmp_dir"/baldart-cli-*.tgz
baldart auth status

Then in any project directory just run:

baldart

That's it. baldart with no arguments runs the smart doctor: it auto-detects the repo state and proposes the next sensible action with a Y/n prompt. You don't need to remember add vs update vs configure vs migrate — it picks the right one.

| Repo state | What baldart proposes | |---|---| | No .framework/ | "Install BALDART framework" → runs add | | Legacy bulk-symlink (pre-v3.8.0) | "Migrate legacy layout" → runs migrate | | Missing baldart.config.yml | "Generate baldart.config.yml" → runs configure | | New config keys in this framework version | "Refresh baldart.config.yml" → runs configure | | framework-edit-gate hook not registered | "Register hook" | | New private release available | "Install verified release" → runs update | | Local framework changes ready to share | "Open private contribution PR" → runs push |

If several conditions hold, actions are presented in priority order (e.g. update before push).

Upgrade the CLI later:

baldart private-bootstrap

Commands

baldart            # same smart entry point
baldart auth status
baldart add        # explicit subcommands
baldart update
baldart configure
baldart capabilities  # enable/disable capability clusters (interactive menu)
baldart push
baldart version
baldart status

What add (first install) does

• Refuses a verified public consumer before writing private payload bytes
• Downloads the latest private payload release into staging and verifies SHA-256 + the per-file manifest
• Atomically installs the tracked .framework/ directory
• Creates a symlink for the cross-tool agents/ reference dir
• Generates the root-file primitives AGENTS.md (cross-tool SSOT) + CLAUDE.md (Claude entry) from versioned skeletons — filling project facts from baldart.config.yml and merging .baldart/overlays/{AGENTS,CLAUDE}.md
• Per-item-merges framework agents/commands/skills into .claude/ (real directories where your own files coexist)
• Detects Codex on the machine and mirrors skills into .agents/skills/ if found
• Copies customizable templates (hooks, UI guidelines, backlog cards)
• Registers the framework-edit-gate hook in .claude/settings.json
• Runs configure interactively to populate baldart.config.yml

No additional activation steps needed — once installed, Claude Code (and Codex) automatically pick up the agents, commands, skills, and protocols.

Tip: During installation, BALDART offers git aliases (fw-version, fw-update, fw-push) for shorter project-local commands.

Features

Core Protocol

• AGENTS.md: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
• agents/: 33 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, runtime-portability-protocol, component-manifest-schema, research-protocol, etc.)
• Routing: If you touch X, read Y - minimize context loading

Capabilities (new in v6.0.0)

The payload (skills, agents, commands, routines, workflows, external tools, MCP servers) is grouped into selectable capability clusters — core (always on), development, design, website, creative-media, machine-learning, gamification, psychology. Pick per project via capabilities.enabled in baldart.config.yml (absent = ALL, full backwards compatibility); per-item extra_*/exclude overrides; shared credentials in the user-level ~/.baldart/secrets.yml; MCP servers wired into .mcp.json (BALDART-owned entries only). See framework/docs/CAPABILITIES.md.

AI Agents (36 specialized agents)

Core (required for every project)

1. codebase-architect: MANDATORY before planning/implementation - understands codebase structure
2. coder: Writes production code with build/test/lint verification + Post-Approval Complexity Gate
3. code-reviewer: Reviews for bugs, security, quality, maintainability — confidence-based filtering + Findings Schema
4. code-simplifier: Dedicated reuse & simplicity reviewer — duplication, reuse-misses, dead code, wrong-altitude abstractions, missed optimizations; deterministic clone floor + simplify-protocol.md (quality only, partitioned from code-reviewer)
5. security-reviewer: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra — boundary-gate → repo-scoped threat-model → modern high-miss discovery-lens → class proof-tuples → structured attack-path → adversarial-refute (security-review-protocol.md)
6. doc-reviewer: Audits and writes documentation, SSOT sync, doc debt tracking, design-system drift detection
7. wiki-curator: Maintains the derived LLM wiki overlay (docs/wiki/) — synthesis candidates, anchor + frontmatter validation
8. doc-graph-aligner: Aligns documentation with the Graphify code knowledge graph — coverage gaps, stale docs, drift vs the SSOT registry
9. prd: Creates PRDs, implementation plans, and backlog cards with autonomous tech decisions
10. prd-card-writer: Generates atomic backlog cards with traceability + parallel groups from approved PRDs
11. plan-auditor: MANDATORY after planning — 4-persona plan review + High-Risk Path triggers + Specialist Auto-Spawn
12. senior-researcher: Evidence-based research with AI-readable retrieval-optimized reports
13. api-perf-cost-auditor: API performance and cost analysis with Findings Schema emission
14. qa-sentinel: SDET-grade gate runner (profile-driven: scoped-by-default, full on deep) — lint, tsc, test, build, audit
15. security-finder: READ-ONLY AppSec finder (analysis-only twin of security-reviewer) — powers the Codex-native /new review fan-out
16. doc-finder: READ-ONLY doc drift/coverage finder (analysis-only twin of doc-reviewer)

Design & UX 17. ui-expert: UI/UX design and review 18. visual-designer: Visual asset generation via image APIs 19. motion-expert: Animation specs, transitions, micro-interactions 20. hyper-gamification-designer: Game mechanics, retention loops, economy balance 21. remotion-animator-orchestrator: Video/motion graphics with Remotion 22. visual-fidelity-verifier (v3.18.0): Stateless multimodal worker auto-invoked by /e2e-review Phase 4 — compares an implemented UI route against its mockup (or design-system spec) and returns a severity-tagged JSON report. Never reads source code (anti assertion-fitting bias), never edits, never declares done 23. markup-fidelity-verifier (v4.78.0): Route-INDEPENDENT structural twin of visual-fidelity-verifier, auto-invoked by /e2e-review Phase 2.7 — compares the implementation's code structure against the mockup expressed as code (links.design HTML or links.design_src) with no browser/auth/data, catching the 2-column-mockup → 1-column-build class of divergence. READS code (mockup-vs-impl, no assertion-fitting risk); same canonical taxonomy + JSON output; fixes route to ui-expert 24. ui-quality-critic (v4.61.0): Stateless multimodal worker auto-invoked by /e2e-review Phase 4b — judges the intrinsic design quality of an implemented UI (10-dimension scientific rubric: hierarchy, rhythm, color, density, composition, states, motion, polish, brand) and returns a severity-tagged JSON report + per-dimension scores. The design twin of code-reviewer, the quality complement of visual-fidelity-verifier (needs no mockup). Never reads source, never grades its own design; fixes route to ui-expert in the bounded self-heal loop

Product & Marketing 25. onboarding-architect-lead: User onboarding flow design and experimentation 26. marketing-conversion-strategist: High-converting copy and messaging 27. seo-analytics-strategist: SEO strategy, metadata, GA4/GTM event planning 28. email-deliverability-architect (v2.0.0): Transactional/informational email design + SPF/DKIM/DMARC — field-verified invariants (DMARC staged progression, reply-to on-domain, mail-tester go-live gate) 29. email-copywriter (v6.34.0): Profile-driven email copy (PROFILE=<transactional|onboarding|retention|winback|announcement|digest>) — copy only, invoked by /email 30. website-orchestrator: Multi-agent website development coordination

Specialized 31. hybrid-ml-architect: ML/DL system design (recommenders, ranking, embeddings) 32. legal-counsel-gdpr: GDPR compliance, privacy policies, data governance 33. deep-human-insight: Psychological / sociological analysis for B2C UX and adoption 34. skill-improver: Weekly auto-improvement of skills/agents based on review/QA findings 35. i18n-translator (v4.52.0): Context-aware label translation into native locale files (Sonnet, low-effort, flag-not-guess) — invoked by /i18n + the i18n-align routine 36. merge-conflict-resolver (v4.64.0): Resolves the final-merge code conflicts OFF the orchestrator context — auto-spawned by /new Phase 6 / /mw only when the deterministic merge-worktree.sh pauses on a code/test conflict. Adjudicates additive-vs-semantic hunks (semantic → STOP), then lets the script land. Runs in a fresh isolated context so the conflict churn never re-enters the bloated end-of-batch orchestrator

REGISTRY.md is the single source of truth for agent routing and capabilities.

Real-time edit gate (new in v3.3.0)

A Claude Code PreToolUse hook (framework-edit-gate) is auto-registered in every BALDART consumer. It intercepts Edit/Write/MultiEdit whose target resolves (via symlink) to a path inside .framework/ and runs the contamination scanner on the new content. If project-specific tokens are detected (Neo-Brutalism, merchant, recharts, secrets, …), the call is blocked with a structured reason that tells Claude exactly what to do: reformulate generically with ${paths.X}/identity.X, move to .baldart/overlays/, or declare the file opt-out via the contamination-scan marker.

In practice: when Claude tries to write project-specific content into a framework skill, the hook stops it before the file is touched and Claude adapts in real time. No more "I forgot, sent merchant logic upstream by mistake".

Registered automatically by baldart add and baldart update. Detected by baldart doctor and re-installed on demand. Disable by removing the entry from .claude/settings.json if you ever need to.

Centralized versioning (new in v3.1.0)

Every consumer repo gets a .baldart/state.json file that tracks: which framework version is installed, when it was installed, when it was last updated, when it was last pushed upstream, and a rolling history of the last 20 events. You always know exactly which version you are working on.

Run baldart version to see installed/private-latest versions, distribution, payload checksum, access status, local uncommitted-files count and last-push info. Use --offline to skip GitHub.

State updates happen automatically — no manual bookkeeping required.

Private CLI self-update

The CLI and tracked .framework/ payload are separate private release assets.

Every interactive run performs a cached best-effort check against the latest private GitHub Release. A newer release produces:

↑ baldart 3.13.0 available (you have 3.12.0)
  Update with: baldart private-bootstrap
  Suppress with: BALDART_NO_UPDATE_CHECK=1

The notifier never installs anything automatically — global installs can require sudo and affect every other project on your machine, so the choice stays with you. CLI drift also appears inline in baldart doctor (new CLI row) and in baldart version. Auto-suppressed in CI, in non-TTY runs, with --offline, with NODE_ENV=test, or via BALDART_NO_UPDATE_CHECK=1.

Project Configuration (new in v3.0.0)

BALDART skills are portable across projects. Instead of hard-coding paths (docs/design-system/INDEX.md), brand identity (Neo-Brutalism), audience segments (merchant/customer), or technology stacks (Recharts-only), skills now read these from baldart.config.yml at your repo root.

Three layers:

1. baldart.config.yml — structural facts (paths, identity, stack, feature flags). Populated by baldart configure with strong filesystem autodetection.
2. Skills — generic, reference ${paths.X} and identity.Y instead of literals.
3. .baldart/overlays/<skill>.md — your project-specific opinions (brand voice pillars, mandatory libraries, custom workflows). Frontmatter-versioned for drift detection.

# First-run (also invoked at the end of `baldart add`)
baldart configure

# Author overlays (optional; starter examples in .framework/templates/overlays/)
cp .framework/templates/overlays/ui-design.fidelity-example.md \
   .baldart/overlays/ui-design.md

Skills always-ask when required keys are missing — never silently default. baldart update warns when new framework versions add config keys but never overwrites your file. Full guide: framework/docs/PROJECT-CONFIGURATION.md.

Skills (46 portable skills)

Skills live under .claude/skills/ and are auto-discovered by Claude Code. Every skill is versioned (version: in frontmatter) and ships a per-skill CHANGELOG.md (v4.82.0 — see skill-structure.md). Bundled skills:

• Workflow: new (Codex Model B since v6.12.0: one-shot resident executor, append-only journal, strict broker/evidence/review/delivery receipts; Claude path unchanged), new2 (v4.16.0 — EXPERIMENTAL workflow-hosted /new, Claude-only, for A/B testing context economy), prd + prd-add (Codex-native Mode B since the /prd Codex-native program — the multi-turn conversation ships a native runtimes/codex/ package: native progress/decision surfaces, shared agent-execution adapter, docs-worktree + docs-mode merge scripts, deterministic audit fan-in; the Claude path is byte-unchanged behind {{#rt_codex}} branches), bug, simplify, codexreview (framework v5.20.0 — the deep multi-agent card-review pipeline as a portable skill; the /codexreview slash command is now a thin Claude wrapper, and Codex-hosted runs get a native fresh-context adversarial binding), worktree-manager, issue-review, context-primer
• Code quality: skill-creator, find-skills, webapp-testing, playwright-skill, lsp-bootstrap (v3.10.0), graphify-bootstrap (v4.21.0 — code knowledge graph), graph-align (v4.21.0 — doc↔graph alignment), toolchain-bootstrap (v4.41.0 — curated dev toolchain), e2e-review (v3.18.0)
• Design: ui-design (v2.0.0, framework v5.2.0 — the local design studio: Design Read & direction lock, 12-direction menu, deterministic anti-slop craft gate craft-check.mjs, dual-lens evaluation with ui-quality-critic; the internal twin of the Claude Design handoff), frontend-design (retired to a router since v5.2.0 — reroutes to ui-design / ui-implement / ui-expert), ui-implement (v4.82.0 — implement an approved mockup end-to-end + self-verify fidelity; the mockup→code playbook SSOT, delegated from /new), motion-design, gamification-design, design-system-init (v3.11.0 — bulk registry bootstrap/upgrade), ds-new (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of design-system-init), ds-edit (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), ds-render (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), design-sync (v4.76.0 — mirror the registry to its Claude Design satellite), ds-handoff (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from /prd)
• Product: seo-audit, copywriting, api-design-principles
• Knowledge: doc-writing-for-rag, capture (LLM wiki overlay), research (v5.1.0 — routed research over the reusable research library: profile + source-matrix routing, reuse pre-flight, senior-researcher fan-out, matrix growth loop)
• Internationalization: i18n (v4.52.0 — audit the context registry + context-aware translation into native locale files), i18n-adopt (v4.52.0 — one-shot migration that externalizes all hardcoded strings on an existing codebase); both gated on features.has_i18n
• Integration: kie-ai, remotion-best-practices
• Framework: baldart-push (upstream contribution), baldart-update (v3.21.0 — agent-driven framework update), overlay (v3.19.0 — guided overlay author), bat-beacon (v6.14.0 — il bat-segnale: raccolta deterministica del contesto di un problema del framework + invio come issue GitHub sulla repo upstream, con outbox offline; il lato consumer del loop di miglioramento autonomo), wrap (v6.21.0 — chiusura di sessione con retrospettiva terminale: auto-analisi della run + bat-beacon aggregato + recupero differito delle sessioni chiuse con exit secco)

Registry-First UI Protocol (new in v3.11.0)

When features.has_design_system: true, every UI-touching agent/skill/command (ui-expert, ui-design, ui-implement, code-reviewer, /design-review) follows the same BLOCKING cascade: read ${paths.design_system}/INDEX.md (Authority Matrix), tokens-reference.md (token contract), and components/<Name>.md for every primitive in scope — BEFORE producing or reviewing any UI. New components must reuse from the registry or ship their per-component spec in the same change. Hardcoded color/shadow/radius/spacing values are HIGH findings. The textual SSOT for the protocol lives in framework/agents/design-system-protocol.md. Projects without a registry can bootstrap one with /design-system-init, which inventories existing primitives, extracts tokens from global styles + Tailwind config, scaffolds the registry, and flips the flag.

Closed-Set Selection Policy (v4.68.0). The registry has a token layer and a component layer, but until now nothing asserted the boundary of a category — so an agent designing from a mockup could write a third "header" when two canonical ones already cover every case, and the duplicate was only caught (reactively) at review. The closed-set policy adds the missing third layer: each component spec declares the presentational role it is canonical for (canonical_for: [page-header@depth-0]) and whether that role family is closed (selection_closed), aggregated into a generated INDEX.md § "Selection Policy". A closed family means introducing a new canonical member is a governance decision, not an implementation act. Three layers enforce it: (1) /prd Component Reconciliation — a human-in-the-loop match-before-generate gate that binds each mockup region to an existing component (or a governed NEW one) and asks "this becomes the standard?" only on genuine ambiguity, persisting the decision into the card's component_bindings; (2) baldart ds-gate — a deterministic, zero-false-positive build-time gate that BLOCKS (DS_CLOSED_SET_VIOLATION) any change adding a new canonical in a closed family (wired into qa-sentinel / /new / code-reviewer, the design-system analogue of the i18n gate); (3) the existing review + weekly ds-drift safety net. Rides on features.has_design_system — no new config key; /design-system-init --upgrade derives the closed sets from your existing must_rules. This closes a gap no 2026 design-to-code vendor hard-gates (Figma Code Connect, Storybook MCP, shadcn are all advisory).

End-to-End Review BLOCKING Gate (new in v3.18.0)

When features.has_e2e_review: true, the /new orchestrator Phase 2.6 invokes the new /e2e-review skill on every UI card (auto-skipped on backend-only cards). The skill is a deterministic, BLOCKING orchestrator that combines functional E2E (Playwright spec written by coder, executed via playwright-skill) with visual fidelity diff (visual-fidelity-verifier multimodal agent) and aggregates findings under a strict severity gate. This replaces the legacy advisory pair (Phase 2.6 conditional E2E + Phase 2.7 non-blocking design review) that left the user manually re-verifying every screen.

The skill walks a 4-level mockup source cascade (Figma MCP → local PNG/JPG/PDF → design-system compliance-only → skip-with-warning) — Figma is opt-in, the framework remains portable. The aggregation gate uses a canonical severity taxonomy (Critical: layout/responsiveness/element-order/component-missing; Major: spacing/typography/color/token-bypass/interactive-state/a11y; Minor: border-radius/shadow/micro-misalignment). The gate enforces three pillars from the 2025–2026 agentic-testing literature: (a) implementer ≠ verifier (Anthropic — Effective Harnesses for Long-Running Agents), (b) Definition of Done machine-readable (Policy Cards, arXiv 2510.24383), (c) Playwright MCP + Vision as the canonical browser+vision combo (Playwright MCP).

Tuning lives under features.e2e_review in baldart.config.yml: fidelity_tolerance (strict | balanced | lenient, default strict), max_self_heal_iterations (default 2), pixel_diff_threshold (default 0.02 — pre-filter to skip Vision when implementation and mockup are pixel-identical, primary cost saver), require_override_reason (default true). When self-heal exhausts iterations, the gate exposes an override path with mandatory reason logged in the tracker's ## Issues & Flags for auditability. The weekly ds-drift routine remains as a complementary safety net for direct human edits that bypass /new.

UI Excellence + Post-Intervention Coherence Gate (new in v3.12.0)

The ui-expert agent is upgraded from a generic baseline to a world-class UI/UX reviewer/designer — UI States Taxonomy (8 states), Performance Gates (Core Web Vitals 2026 — LCP/INP/CLS), modern CSS surface (container queries, :has(), View Transitions, subgrid, logical properties), AI-era patterns (streaming UI, hallucination guardrails), and 60+ categorized red flags. Numeric reference tables (type scale, contrast targets WCAG+APCA, spacing scales, density tiers, motion durations/easings) are SSOT'd in framework/agents/design-system-protocol.md so agents cite values verbatim instead of inventing them. Crucially, the registry-first discipline now has a post-intervention coherence gate: every UI change introduced by ui-expert / ui-design / ui-implement (and verified by code-reviewer at merge) must reconcile INDEX.md + components/<Name>.md + tokens-reference.md in the same change — drift can no longer wait for the weekly ds-drift routine. Three layers now enforce coherence: per-task → per-merge → weekly safety net. Existing projects align their current graphic organization with the new discipline via framework/docs/UPGRADE-3.12-UI-COHERENCE.md (idempotent walkthrough: baseline scan → prioritized backlog → quick wins → gate verification).

LSP Symbol Search Layer (new in v3.10.0)

When features.has_lsp_layer: true, codebase-architect and the code-exploration skills (context-primer, bug, prd, new, simplify) prefer LSP find-references / go-to-definition over Grep for identifier-shaped queries — the filtering happens before Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at baldart configure; BALDART installs the matching language servers (global npm install for TypeScript/Python — the binary must be on $PATH because Claude Code's LSP tool spawns it by name; system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See framework/agents/code-search-protocol.md.

Code Knowledge Graph Layer (new in v4.21.0)

When features.has_code_graph: true, agents prefer the Graphify code knowledge graph (tree-sitter, local/offline, native Leiden communities) for structural / relational queries — "what connects X to Y", blast-radius of a change, which modules cluster — via graphify query/path/explain/affected. The same graph re-activates the LLM-wiki auto-learning loop (dormant since the RAG removal in v4.20.0): wiki-curator, /capture, and the nightly doc-graph-align routine feed synthesis candidates from Graphify's native GRAPH_REPORT.md (god nodes, communities, suggested questions) — entirely offline. Graphify is a single language-agnostic tool (pipx install graphifyy); install via baldart configure or /graphify-bootstrap (never silent in CI — baldart doctor backfills). Falls back silently to LSP→Grep→Git. See framework/agents/code-graph-protocol.md and framework/docs/CODE-GRAPH-LAYER.md.

Internationalization Layer (new in v4.52.0)

When features.has_i18n: true, BALDART makes consumers develop multi-language by default. Two ideas: (1) no user-facing string is ever hardcoded — every label goes through the stack's translation function, enforced by a deterministic anti-hardcoded gate (a BALDART-owned standalone eslint.i18n.config.mjs running eslint-plugin-i18next no-literal-string — works even on Biome-only projects, never touches your lint config) with code-reviewer as the semantic backstop; (2) a stack-agnostic context registry (docs/i18n/registry.yml) holds a hyper-brief context per key (what it is for / where it appears) + domain, so LLM translation is context-aware instead of blind — the 2026 "void of context" fix. Translations live in the stack's native locale files (i18next / next-intl / react-intl / lingui / vue-i18n); BALDART wraps the consumer's framework and best-in-class OSS rather than reimplementing i18n. The /i18n skill audits + translates on demand (via the i18n-translator agent — Sonnet, low-effort, bounded flag-not-guess); the weekly i18n-align routine keeps the maintained i18n.target_languages aligned and commits directly to the trunk. Ownership is strict: coder (STEP 9) externalizes + populates the registry, doc-reviewer curates it, i18n-translator translates. Opt-in at baldart configure; baldart doctor backfills the lint plugin + flags a missing registry. See framework/agents/i18n-protocol.md and framework/docs/I18N-LAYER.md.

Curated Toolchain Layer (new in v4.41.0)

When features.has_toolchain: true, BALDART becomes opinionated about the tools you build with, not just the workflow. On a JS/TS project baldart configure PRESELECTS and installs a curated set as devDependencies — Biome (format + lint + import organizer), Vitest, tsc, Lefthook (pre-commit) — and records literal gate commands in toolchain.commands.*. The quality-gate flows (/new, /new2, /qa, qa-sentinel, coder) then run those commands verbatim instead of hard-coding eslint/tsc/jest. Opinionated but askable (default Y, opt-out) and non-destructive: existing ESLint/Prettier/Jest/husky setups are detected and a migration is only ever PROPOSED, never automatic (.husky/ is never overwritten). Never silent in CI (baldart doctor backfills); each gate falls back silently to the project-standard default when its command is unset, so non-JS projects and consumers with their own toolchain are unaffected. Install via baldart configure or /toolchain-bootstrap. See framework/agents/toolchain-protocol.md and framework/docs/TOOLCHAIN-LAYER.md.

Commands

• /new: Batch orchestrator; Claude uses the established orchestration, Codex uses the one-shot resident Model B runtime with typed decision/terminal boundaries
• /codexreview: Deep multi-agent code review with mandatory false-positive validation and finding pooling across reviewers
• /check: Pre-development parallel quality audits using agent teams
• /design-review: UI/UX design review workflow
• /issue-review: GitHub issue analysis and context capture

LLM Wiki Overlay (new in v2.0.0)

A derived, non-canonical knowledge layer (docs/wiki/) maintained on two paths: a nightly wiki-curator sweep (synthesis candidates from recent ADRs/PRDs, anchor + frontmatter validation) and on-demand /capture from live conversations. See framework/agents/llm-wiki-methodology.md for the full methodology and adoption checklist.

Migrating an Existing Install (v1.x / v2.x → v3.x)

If you already have BALDART installed in an existing project:

# 1. Pull v3 framework
baldart update

# 2. (v2.0.x → v2.1.1 layout fix, if you skipped that train)
baldart migrate     # idempotent: converts legacy skills layout

# 3. v3 step — populate baldart.config.yml (paths/identity/stack/features)
baldart configure   # interactive prompts + filesystem autodetection

# 4. Confirm
baldart status      # config + overlays + drift
baldart version     # current version + last update / last push

Full migration guide (including the v2 → v3 cheat sheet and overlay authoring): framework/docs/PROJECT-CONFIGURATION.md § 9.

v3.0 → v3.1 requires no config changes — state.json is auto-seeded on the next CLI invocation (add / update / push).

baldart migrate (still available) handles legacy v2.0.x cases:

• Converts the legacy .claude/skills/ bulk symlink (v2.0.x) into a real directory.
• Re-merges framework skills as per-item symlinks alongside your personal skills.
• Restores .claude/skills.backup/ content into .claude/skills/, leaving name collisions in .backup/ for manual review.
• Logs unresolved collisions in .baldart/skill-conflicts.json.

Safe to re-run; if there's nothing to do, it reports so and exits.

Scheduled Routines (new in v2.1.0)

The framework now ships scheduled routines that make its maintenance and drift-detection loops actually run. Ship-bundled routines:

| Routine | Cadence | Agent | Purpose | |---------|---------|-------|---------| | wiki-review | nightly 02:00 UTC | wiki-curator | Maintains the LLM-wiki overlay (candidates, anchors, frontmatter) | | doc-review | nightly 00:00 UTC | doc-reviewer | Audits doc changes, flags SSOT drift | | code-review | nightly 01:00 UTC | code-reviewer | Reviews last-24h commits | | doc-graph-align | nightly 04:00 UTC | doc-graph-aligner | Aligns docs with the Graphify code graph — uncovered core code, stale docs, registry drift (optional, needs has_code_graph) | | skill-improve | weekly Sun 02:00 UTC | skill-improver | Refines skills/agents from review patterns | | ds-drift | weekly Mon 03:00 UTC | doc-reviewer | Design-system drift check (optional) | | full-sweep | weekly Sun 03:00 UTC | doc-reviewer | Full SSOT audit (optional) | | i18n-align | weekly Mon 04:00 UTC | i18n-translator | Translates target languages, lints, commits direct to trunk (optional, needs has_i18n) | | email-align | weekly Mon 04:30 UTC | doc-reviewer | Email-registry drift reconciliation (deterministic scan + curation; optional, needs has_email_layer, v6.34.0) | | bug-mine | weekly Mon 04:00 UTC | skill-improver | Mines the per-project bug registry (.baldart/bug-registry/) into classified process proposals + explicit one-off discards (MODE: bug-miner, v5.19.0, optional) | | finding-mine | monthly 1st 03:00 UTC | skill-improver | Deep 30-day mining of pooled findings/QA/trackers/reviewer memories into classified improvement proposals (MODE: miner, v5.0.0) |

Three backend adapters are bundled:

• claude-code-cloud — .claude/routines/<name>.json for RemoteTrigger
• github-actions — .github/workflows/baldart-<name>.yml
• cron — scripts/routines/<name>.sh + a crontab line

Review engine (v4.18.0+) — a review routine (e.g. code-review) may set review_engine: codex in its .routine.yml to shift the finding pass onto the OpenAI Codex companion (spend a Codex licence instead of Claude tokens). This is cron-only — it needs the Codex plugin + an authenticated ~/.codex/ in the cron user's home; the github-actions and claude-code-cloud backends fall back to the claude engine with a warning. On a BALDART consumer with Multi-agent v2 enabled, the Codex cron pass selects generated specialist roles through spawn_agent.agent_type; an explicit v2 opt-out degrades to the documented holistic single-pass fallback.

During baldart add and baldart update, BALDART surfaces routines the user has never reviewed and prompts to install them. Standalone command:

baldart routines list          # show status for every routine
baldart routines install wiki-review   # interactive install
baldart routines doctor        # verify installed routines are still healthy
baldart routines disable wiki-review   # remove the schedule

Templates

• feature-card.template.yml: Backlog card structure
• spec.template.md: Technical specifications
• breaking-change-checklist.md: API/schema migration checklist
• ui-guidelines.template.md: UI/UX guidelines template
• brand-guidelines.md: Brand identity template

What Gets Installed

your-project/
├── .framework/              # Verified private release payload (tracked)
├── AGENTS.md               # Generated from skeleton + config + overlay (cross-tool SSOT)
├── CLAUDE.md               # Generated Claude Code entry (Claude-native mechanics)
├── agents/                  # Symlink → .framework/agents/
├── .claude/
│   ├── agents/             # Symlink → .framework/.claude/agents/
│   ├── commands/           # Symlink → .framework/.claude/commands/
│   ├── skills/             # Per-item merge dir (v2.1.1+): framework symlinks alongside your own skills
│   ├── workflows/          # Per-item symlinks of framework dynamic workflows (v4.14.0+, Claude-only)
│   ├── output-styles/      # Per-item symlinks of framework output styles (v4.50.0+, Claude-only; latent — activate via /config)
│   └── hooks/              # Customizable copies
├── baldart.config.yml      # Project context: paths/identity/stack/features (v3.0.0+)
├── .baldart/
│   ├── state.json          # Centralized versioning ledger (v3.1.0+, managed by CLI)
│   └── overlays/           # Your per-skill project-specific overrides (v3.0.0+)
├── docs/references/
│   ├── ui-guidelines.template.md    # Customize for your project
│   └── brand-guidelines.md          # Customize for your project
└── templates/               # Customizable backlog/spec templates

Daily Workflow

1. Create Backlog Card

# Copy template
cp templates/feature-card.template.yml backlog/FEAT-001.yml

# Edit card with your requirements

2. Implement with Framework

# Framework guides agent coordination automatically
# Use /new command for batch implementation
/new FEAT-001

3. Update Framework

# Check for updates
baldart status

# Update to latest
baldart update

4. Contribute Back

# Made improvements? Share them!
baldart push

Customization

Files You SHOULD Customize

1. .claude/hooks/lint-before-commit.sh.template

   • Replace commands with your project's tools
   • Rename to lint-before-commit.sh
   • Make executable: chmod +x .claude/hooks/lint-before-commit.sh

2. docs/references/ui-guidelines.template.md

   • Define brand colors, typography, spacing
   • Document component patterns
   • Rename to ui-guidelines.md

3. docs/references/brand-guidelines.md

   • Add logo specifications
   • Define brand voice and tone
   • Document imagery guidelines

4. templates/*.yml

   • Adapt backlog card template
   • Add project-specific fields

5. baldart.config.yml (v3.0.0+)

   • Paths, identity, stack, feature flags for your project
   • Generated by baldart configure — re-run any time to refresh
   • Never overwritten by baldart update

6. .baldart/overlays/<skill>.md (v3.0.0+)

   • Per-skill project-specific extensions (brand voice, mandated stack, custom workflows)
   • Examples in .framework/templates/overlays/
   • Never overwritten by baldart update

Files You SHOULD NOT Modify

Files with symlinks auto-update when framework updates:

• AGENTS.md
• agents/
• .claude/agents/
• .claude/commands/
• .claude/workflows/ (v4.14.0+) — framework dynamic workflows, per-item symlinks (Claude-only; no Codex equivalent)
• .claude/output-styles/ (v4.50.0+) — framework output styles, per-item symlinks (Claude-only; latent — installs without activating, toggle via /config → Output Style)

Files managed by the CLI:

• .baldart/state.json (schema v2) — distribution, installed asset/checksum, source repo and event ledger. It never contains credentials.

Commands Reference

baldart add [repo]

Install framework in your project.

• repo: Optional. Default: antbald/BALDART
• --ack-private-storage: explicit acknowledgement when remote visibility cannot be verified. A verified public consumer is always refused.

Example:

baldart add              # Install from default repo
baldart add owner/repo   # Install from custom fork

baldart update

Update framework to latest version — seamless (v4.8.0+): one command, zero iterations. The job is always the same — update and preserve overlays — so the CLI does the whole thing in one shot:

• Resolves the latest private GitHub Release
• Downloads payload + SHA256SUMS into staging and verifies every manifest file
• Auto-stashes any non-framework work and re-applies it after (single blanket stash; handles tracked files inside .gitignored dirs)
• Creates a backup tag (git reset --hard <tag> to roll back)
• Refuses committed or uncommitted payload drift until it is preserved through baldart push or overlays
• Atomically swaps .framework/, reconciles Claude/Codex artifacts and updates the schema-v2 ledger

It stops once only when an edit cannot be captured+verified faithfully (a section deletion, a frontmatter/preamble change, a src/ change) — never a silent destructive action.

For agents / CI (v3.32.0+): baldart update --json --yes emits a single machine-readable result object on stdout ({schema:"baldart.update/1", ok, action, installed_after, backup_tag, blockers, next_command, …}) with all human output on stderr — no prose to scrape. ok:true ⟺ the framework is now at the remote version (action is updated, reset, or already-current). The escape hatches --reset --yes --i-know and --on-divergence pull|scaffold-overlays|abort still exist for power users, but the seamless default makes them unnecessary. --json requires --yes and rejects an explicit --reset.

baldart (no args) / doctor (v3.2.0+)

Smart diagnostic that detects the install state and proposes the next sensible action (install, migrate legacy layout, configure, refresh config schema, update, push, repair symlinks, reap orphaned Codex MCP servers, or "nothing to do"). Prints a status table then runs the proposed actions with confirmation per step.

Since v4.37.0 it also surfaces orphaned MCP-server processes left by Codex calls — every BALDART Codex finder call (/new, new2, /codexreview, the cron review engine) drives codex app-server, whose detached broker spawns the MCP servers from ~/.codex/config.toml (Playwright, …) and leaks them to init (ppid 1) when it dies, where they keep burning CPU. The doctor reaps the orphaned MCP servers (and their browser children) directly via syscall; the live codex app-server broker is never touched.

For projects with Codex enabled, install/update/migrate also opts the repository into Codex's stable native Multi-agent v2 backend through .codex/config.toml. Existing Codex project settings are merged additively; an explicit multi_agent_v2 = false remains authoritative. doctor compares file state with the effective CLI state, reports missing/disabled/untrusted-session drift, and can add a missing opt-in safely. Generated roles are selected with spawn_agent.agent_type; each work item uses a separate snake-case task_name. Portable orchestrator skills use the native v2 lifecycle directly. /prd is host-v2 first; /new keeps its resident Model B subprocess engine because v2 workers cannot yet join its atomic receipt, usage, worktree, cancellation, and cleanup transaction.

Since v4.38.0 it also checks external-tool version currency — BALDART pins none of the tools it installs (graphifyy via pipx, language servers via npm), and pipx/npm never auto-upgrade, so an old install silently misses upstream security/correctness fixes. The doctor probes the managed tools against their registries (PyPI / npm) and surfaces a non-blocking one-command upgrade for any confirmed behind upstream (e.g. Upgrade Graphify 0.8.36 → 0.8.39). Network-gated — skipped under --offline, silent when everything is current.

baldart            # diagnostic + interactive prompts
baldart --auto     # CI-friendly: skip y/n; error out on ambiguity
baldart --offline  # skip the upstream fetch
baldart doctor     # explicit alias (same behaviour)

baldart version

Show installed framework version, install date, drift from remote (commits ahead/behind), uncommitted-files count in .framework/, and last-push info. Use --offline to skip the upstream fetch when offline. Use --json (v3.32.0+) for a machine-readable object (schema:"baldart.version/1") on stdout — agents read installed_version / remote_version / aligned instead of scraping the human box.

baldart push / /baldart-push (v3.1.0+)

Contribute local framework improvements through a private pull request:

• Downloads the pristine asset matching installed_version and computes the payload diff.
• Runs contamination autofix/review and blocks credentials.
• Clones private BALDART into a temporary directory, maps .framework/framework/* to framework/*, creates codex/..., pushes it and opens a private PR.
• Deletes the temporary clone. Consumer files never enter the PR.

Either invoke via the slash command (conversational orchestration in Claude Code) or directly via CLI:

baldart push

baldart configure

Generate / update baldart.config.yml (project paths, identity, stack, feature flags). Interactive prompts with filesystem autodetection. Idempotent — re-running merges into the existing file without clobbering user values.

• --non-interactive: write autodetected values without prompts (for CI).

Full guide: framework/docs/PROJECT-CONFIGURATION.md.

baldart status

Check installation status:

• Framework version
• Symlink validity
• Customizable files presence
• Update availability

Architecture

Private release strategy

• Distribution: GitHub Release assets only; npm is a final bootstrap bridge.
• Consumer storage: .framework/ remains tracked so private clones work without hydration. Public consumers are refused.
• Authentication: BALDART_GH_TOKEN → GH_TOKEN → gh credential store; credentials are never persisted by BALDART.
• Updates: verified staging + atomic swap.
• Contributions: private patch branch and PR; no subtree operation.
• Bat-beacon: private issue plus gzip/base64 transcript comments; Issues write only.

Versioning

BALDART follows Semantic Versioning:

• MAJOR (X.0.0): Breaking changes (incompatible updates)
• MINOR (0.X.0): New features (backwards compatible)
• PATCH (0.0.X): Bug fixes (backwards compatible)

Check version:

baldart version

Troubleshooting

"Framework not installed" error

# Install framework first
baldart add

Symlinks broken after update

# Reinstall to recreate symlinks
baldart add

Conflicts during update

# Check conflicting files
git status

# Choose resolution
git checkout --ours <file>    # Keep your version
git checkout --theirs <file>  # Use framework version

# Complete merge
git add <resolved-files>
git commit -m "Resolved framework update conflicts"

Rollback after bad update

# Find backup tag (created by update)
git tag | grep backup/

# Rollback
git checkout backup/YYYY-MM-DD-HH-MM-SS
git checkout -b recovery-branch

Requirements

• Node.js: >= 18.0.0
• Git: >= 2.0.0
• npm: >= 8.0.0
• GitHub CLI: authenticated with access to private antbald/BALDART

Full access, CI, migration and recovery guide: framework/docs/PRIVATE-DISTRIBUTION.md.

License

MIT

Contributing

Contributions from authorized collaborators use private PRs. See MAINTAINING.md.

Quick process:

1. Make improvements in your project
2. Test thoroughly
3. Run baldart push and review the private PR
4. Maintainer classifies MAJOR/MINOR/PATCH and updates changelog/version
5. Maintainer tags; the private release workflow publishes verified assets

For agents: Follow the complete checklist in MAINTAINING.md to ensure proper versioning, documentation, and release process.

Repository

• GitHub: https://github.com/antbald/BALDART
• Install: baldart add
• Issues: https://github.com/antbald/BALDART/issues

Credits

Created for coordinating AI agents and humans in software development.

Support

• Current Version: cat VERSION
• Changelog: See CHANGELOG.md
• Maintenance Protocol: See MAINTAINING.md
• Check Status: baldart status
• Check Version: baldart version
• Issues: https://github.com/antbald/BALDART/issues