baldart

library4.14.0jsnpmunverified

BALDART is a portable framework for coordinating AI agents (like Claude Code, Codex) and human developers in software projects. It provides a standardized AGENTS.md protocol, 27 pre-built specialized agents (coder, code-reviewer, architect, security-reviewer), batch orchestration commands (/new, /design-review), and templates for backlog cards, PRDs, specs, and breaking-change checklists. The framework is installed via npm (no bash scripts) and integrates automatically with Claude Code and Codex via .claude/ directory agents/commands/skills. Current version is 4.14.0, released roughly monthly. Key differentiators: zero-config smart doctor CLI (single 'baldart' command auto-detects repo state), per-item-merge agent installation (preserves custom files), and a framework-edit-gate hook that prevents accidental edits to framework files. Requires Node.js >= 18.

devops

npm install baldart

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BALDART

baldart

devopsjavascriptv4.14.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (CLI usage)

✓ npx baldart

✗ npm run baldart

Run directly via npx. If installed globally, just run 'baldart'. Do not add to npm scripts unless you understand path resolution.

subcommands (add, update, configure, push, version, status)

✓ npx baldart add

✗ npx baldart --add

Subcommands are positional, not flags. 'baldart add' installs framework; 'baldart update' pulls upstream changes.

npx pinned version

✓ npx baldart@4.14.0 add

✗ npx -p baldart@4.14.0 -c 'baldart add'

Simplest to use '@version' after the package name. Older npx may require different syntax.

Global install and first-run setup using the smart doctor CLI. Shows how to install, initialize, and update the framework.

npm i -g baldart # Or without global install: npx baldart # The smart doctor will propose actions based on repo state. # For a new project: cd my-project git init npx baldart # It will detect no .framework/ directory and propose installation. # Accept to install framework agents/commands/skills. # Follow the interactive configure prompt to set up baldart.config.yml. # After install, agents are active in Claude Code / Codex. # To update later: npx baldart update # Or pin version: npx baldart@4.14.0 add

Debug

Known issues

breakingPre-v3.8.0 used bulk-symlinks for framework files. Running 'baldart' auto-detects legacy layout and proposes migration to per-item-merge. Manual migration steps if 'baldart' fails: remove .framework/ and .claude/, then run 'baldart add'.

fix

Run 'baldart' (no args) which will prompt to migrate. Or manually remove legacy directories and re-run 'baldart add'.

affects: <3.8.0

gotchaDo not manually edit files inside .framework/ — these are overwritten on update. The framework-edit-gate hook (registered during install) blocks edits in Claude Code. To customize agents, place files in .claude/agents/ (not .framework/agents/). The per-item-merge preserves your custom files.

fix

Use .claude/agents/ for custom agents. If you must edit a framework agent, copy it to .claude/agents/ first, then modify.

affects: >=3.8.0

deprecatedThe legacy syntax 'npx -y github:antbald/BALDART <cmd>' still works but is deprecated. Use 'npx baldart' or 'npx baldart@version' instead. The @version syntax pins exact versions and is faster.

fix

Replace 'npx -y github:antbald/BALDART add' with 'npx baldart add' or 'npx baldart@4.14.0 add'.

affects: >=4.0.0

gotchaIf using global install, the 'baldart' command may be overshadowed by another global tool named 'baldart'. Check with 'which baldart' or 'npm ls -g'. The official package name is 'baldart' on npm.

fix

Use 'npx baldart' to bypass global ambiguity, or uninstall conflicting packages.

affects: >=1.0.0

breakingbaldart.config.yml format changed between v3 and v4. The 'configure' subcommand (or smart doctor) will regenerate it with new keys. If you have customizations, backup before upgrading.

fix

Run 'npx baldart configure' after upgrading to regenerate config with new defaults. Migrate custom fields manually.

affects: >=4.0.0

gotchaThe framework-edit-gate hook is registered in .claude/settings.json during installation. If you overwrite this file (e.g., via Claude Code settings sync), the hook may be removed and you'll lose protection against accidental framework edits.

fix

Re-run 'npx baldart' to re-register hooks, or manually add the hook entry to .claude/settings.json.

affects: >=3.8.0

Errors

Common errors & fixes

Error: Cannot find module 'baldart'

Global install failed or npm prefix not in PATH.

fix

Run 'npm i -g baldart' again, or use 'npx baldart' without global install.

zsh: command not found: baldart

Global npm binaries directory not in PATH.

fix

Run 'npx baldart' or add npm global prefix to PATH: export PATH=$(npm root -g)/bin:$PATH

Error: Legacy layout detected. Run 'baldart migrate' or 'baldart add' to upgrade.

Project has pre-v3.8.0 bulk-symlink framework installation.

fix

Run 'npx baldart' (no args) to auto-migrate, or 'npx baldart add' to reinstall fresh.

Error: Failed to register framework-edit-gate hook. Is .claude/settings.json writable?

Permissions issue or .claude directory missing.

fix

Ensure .claude/ exists and is writable. Run 'mkdir -p .claude && chmod u+w .claude'. Then re-run 'npx baldart'.

Error: Incompatible Node.js version. Requires >=18.0.0

Node.js version is too old.

fix

Upgrade Node.js to v18 or later (e.g., via nvm: nvm install 18).

Upgrade

Version history

4.14.0latest on npm

Audit

Dependencies

noderequiredRuntime requirement: Node.js >= 18.0.0

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/antbald/BALDART ↗

packagebaldart ↗

homepagehttps://github.com/antbald/BALDART#readme ↗