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

```bash
npm i -g baldart
```

Then in any project directory just run:

```bash
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:
```bash
npm i -g baldart@latest
```

### Without the global install

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

```bash
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 baldart@3.8.0 <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.

```bash
# 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`](framework/docs/PROJECT-CONFIGURATION.md).

### Skills (33 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), `toolchain-bootstrap` (v4.41.0 — curated dev toolchain), `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`](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](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)), (b) **Definition of Done machine-readable** ([Policy Cards, arXiv 2510.24383](https://arxiv.org/abs/2510.24383)), (c) **Playwright MCP + Vision** as the canonical browser+vision combo ([Playwright MCP](https://playwright.dev/mcp/introduction)).

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`](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`](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`](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](https://github.com/safishamsi/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`](framework/agents/code-graph-protocol.md) and [`framework/docs/CODE-GRAPH-LAYER.md`](framework/docs/CODE-GRAPH-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`](framework/agents/toolchain-protocol.md) and [`framework/docs/TOOLCHAIN-LAYER.md`](framework/docs/TOOLCHAIN-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:

```bash
# 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`](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:

```bash
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

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

# Edit card with your requirements
```

### 2. Implement with Framework

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

### 3. Update Framework

```bash
# Check for updates
npx baldart status

# Update to latest
npx baldart update
```

### 4. Contribute Back

```bash
# 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:**
```bash
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 `.gitignore`d 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, 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.

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.

```bash
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:

```bash
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`](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](https://semver.org/):

- **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:
```bash
npx baldart version
```

## Troubleshooting

### "Framework not installed" error

```bash
# Install framework first
npx baldart add
```

### Symlinks broken after update

```bash
# Reinstall to recreate symlinks
npx baldart add
```

### Conflicts during update

```bash
# 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

```bash
# 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](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](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](CHANGELOG.md)
- **Maintenance Protocol**: See [MAINTAINING.md](MAINTAINING.md)
- **Check Status**: `npx baldart status`
- **Check Version**: `npx baldart version`
- **Issues**: https://github.com/antbald/BALDART/issues
