BALDART - Claude Agent Framework

A comprehensive, reusable framework for coordinating AI agents and human developers in software projects. Install via npm/npx - no bash scripts needed.

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

One command for everything (recommended)

Install the CLI globally once:

npm i -g baldart

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" | | Remote framework is ahead | "Pull N commit(s) from upstream" → runs update | | Local framework changes ready to share | "Push local improvements upstream" → runs push |

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

Upgrade the CLI later:

npm i -g baldart@latest

Without the global install

If you don't want a global install, every command also works via npx:

npx baldart            # same smart entry point
npx baldart add        # explicit subcommands
npx baldart update
npx baldart configure
npx baldart push
npx baldart version
npx baldart status

The legacy npx -y github:antbald/BALDART <cmd> form still works if you need to install from an unreleased commit on main. For pinning a specific version: npx [email protected] <cmd>.

What add (first install) does

• Downloads the framework via Git subtree into .framework/
• Creates symlinks for auto-updateable files (AGENTS.md, agents/)
• 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 to configure git aliases (fw-version, fw-update, fw-push) — handy if you don't want the global install but find npx baldart … long.

Features

Core Protocol

• AGENTS.md: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
• agents/: 23 domain modules (architecture, workflows, testing, security, card-schema, etc.)
• Routing: If you touch X, read Y - minimize context loading

AI Agents (28 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. security-reviewer: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra
5. doc-reviewer: Audits and writes documentation, SSOT sync, doc debt tracking, design-system drift detection
6. wiki-curator: Maintains the derived LLM wiki overlay (docs/wiki/) — synthesis candidates, anchor + frontmatter validation
7. prd: Creates PRDs, implementation plans, and backlog cards with autonomous tech decisions
8. prd-card-writer: Generates atomic backlog cards with traceability + parallel groups from approved PRDs
9. plan-auditor: MANDATORY after planning — 4-persona plan review + High-Risk Path triggers + Specialist Auto-Spawn
10. senior-researcher: Evidence-based research with AI-readable retrieval-optimized reports
11. api-perf-cost-auditor: API performance and cost analysis with Findings Schema emission
12. qa-sentinel: SDET-grade gate runner (profile-driven: scoped-by-default, full on deep) — lint, tsc, test, build, audit

Design & UX 13. ui-expert: UI/UX design and review 14. visual-designer: Visual asset generation via image APIs 15. motion-expert: Animation specs, transitions, micro-interactions 16. hyper-gamification-designer: Game mechanics, retention loops, economy balance 17. remotion-animator-orchestrator: Video/motion graphics with Remotion 18. 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

Product & Marketing 19. onboarding-architect-lead: User onboarding flow design and experimentation 20. marketing-conversion-strategist: High-converting copy and messaging 21. seo-analytics-strategist: SEO strategy, metadata, GA4/GTM event planning 22. email-deliverability-architect: Transactional/informational email design + SPF/DKIM/DMARC 23. website-orchestrator: Multi-agent website development coordination

Specialized 24. hybrid-ml-architect: ML/DL system design (recommenders, ranking, embeddings) 25. legal-counsel-gdpr: GDPR compliance, privacy policies, data governance 26. deep-human-insight: Psychological / sociological analysis for B2C UX and adoption 27. skill-improver: Weekly auto-improvement of skills/agents based on review/QA findings

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 npx baldart version to see installed version + install date, drift from remote (n commits ahead/behind), local uncommitted-files count, and last-push info. Use --offline to skip the upstream fetch.

State updates happen automatically — no manual bookkeeping required.

CLI self-update notifier (new in v3.13.0)

The CLI binary (baldart, installed globally via npm i -g baldart) and the framework payload (.framework/ inside each repo, updated by baldart update) are two independent layers. Until now the CLI drifted silently — users on an old CLI never learned about new flags or new doctor checks.

Now every baldart run does a best-effort check against registry.npmjs.org (cached at ~/.baldart/cli-update-check.json with a 24h TTL, 1.5s network timeout, fire-and-forget). When a newer version is available, a one-shot banner appears at the top of the run:

↑ baldart 3.13.0 available (you have 3.12.0)
  Update with: npm i -g baldart@latest
  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 npx 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`)
npx 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. npx baldart update warns when new framework versions add config keys but never overwrites your file. Full guide: framework/docs/PROJECT-CONFIGURATION.md.

Skills (32 portable skills)

Skills live under .claude/skills/ and are auto-discovered by Claude Code. Bundled skills:

• Workflow: new, new2 (v4.16.0 — EXPERIMENTAL workflow-hosted /new, Claude-only, for A/B testing context economy), prd, prd-add, bug, simplify, 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), e2e-review (v3.18.0)
• Design: frontend-design, ui-design, motion-design, gamification-design, design-system-init (v3.11.0)
• Product: seo-audit, copywriting, api-design-principles
• Knowledge: doc-writing-for-rag, capture (LLM wiki overlay)
• 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)

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, frontend-design, 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.

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 / frontend-design (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.

Commands

• /new: Batch orchestrator with QA validation, production readiness checklist, and context recovery (also available as a skill)
• /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
npx baldart update

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

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

# 4. Confirm
npx baldart status      # config + overlays + drift
npx 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) |

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. Codex cannot spawn specialist subagents, so the Codex engine runs a holistic single-pass review (no security-reviewer / api-perf-cost-auditor split) — keep review_engine: claude (the default) when you need that depth.

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

npx baldart routines list          # show status for every routine
npx baldart routines install wiki-review   # interactive install
npx baldart routines doctor        # verify installed routines are still healthy
npx 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/              # Framework source (via Git subtree)
├── AGENTS.md               # Symlink → .framework/AGENTS.md
├── 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)
│   └── 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
npx baldart status

# Update to latest
npx baldart update

4. Contribute Back

# Made improvements? Share them!
npx 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 npx 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)

Files managed by the CLI:

• .baldart/state.json (v3.1.0+) — versioning ledger maintained by add/update/push. Editing by hand can confuse the drift report.

Commands Reference

npx baldart add [repo]

Install framework in your project.

• repo: Optional. Default: antbald/BALDART
• --branch: Branch to use. Default: main

Example:

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

npx 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:

• Shows the upstream CHANGELOG between your version and the remote
• 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)
• Resolves divergence automatically: edits already covered by an overlay → clean reinstall that re-applies the overlays; uncovered edits → auto-captured into overlays and verified (the merge must reproduce the edit) before reinstall
• Updates via Git subtree, verifies symlinks, and commits the BALDART-managed reconcile — leaving a clean tree

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+): npx 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.

npx 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, or "nothing to do"). Prints a status table then runs the proposed actions with confirmation per step.

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

npx 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.

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

Contribute local framework improvements upstream. Replaces the v1-v3.0 manual "next steps required" workflow with an automated, contamination-aware flow:

• Auto-pull: if remote is ahead, runs update first.
• Triage: separates pushable files from blocklisted (hooks, overlays) and surfaces new consumer-authored skills as contribution candidates.
• Contamination autofix: rewrites hardcoded paths automatically (docs/design-system/ → ${paths.design_system}/, etc.). For identity / stack tokens that cannot be safely auto-rewritten (Neo-Brutalism, merchant, recharts), asks per file: keep & force push, skip the file (drop from push), or abort. Hard-blocks on secrets (API keys, bearer/Slack/PAT/JWT tokens, PEM private keys).
• Auto version bump: suggests MAJOR/MINOR/PATCH from the diff shape.
• Auto CHANGELOG: writes the entry under the new version section, grouped Added/Changed/Removed from the file list.
• Auto-tag + subtree push.
• State update: writes last_pushed_version + history entry into .baldart/state.json.

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

npx baldart push

npx 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.

npx baldart status

Check installation status:

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

Architecture

Git Subtree Strategy

BALDART uses Git subtree for bidirectional sync:

• Pull updates: npx baldart update pulls new versions
• Push improvements: npx baldart push contributes back
• Local copy: Framework lives in .framework/ directory
• Symlinks: Auto-updated files link to .framework/
• Copies: Customizable files copied from .framework/

Why NPX?

• No global install: Use latest version every time
• Cross-platform: Works on Windows/Mac/Linux
• Standard: Familiar to all Node.js developers
• Simple: One command to rule them all

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:

npx baldart version

Troubleshooting

"Framework not installed" error

# Install framework first
npx baldart add

Symlinks broken after update

# Reinstall to recreate symlinks
npx 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

License

MIT

Contributing

Contributions welcome! See MAINTAINING.md for the complete protocol.

Quick process:

1. Make improvements in your project
2. Test thoroughly
3. Run npx baldart push
4. Classify change type (MAJOR/MINOR/PATCH)
5. Update VERSION and CHANGELOG.md
6. Create git tag and push

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: npx 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: npx baldart status
• Check Version: npx baldart version
• Issues: https://github.com/antbald/BALDART/issues