# 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 (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`](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).

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

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