baldart 3.6.2

package/README.md

@@ -0,0 +1,566 @@
+# 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
+
+### Installation
+
+```bash
+# In your project directory
+npx baldart add
+```
+
+> Available on npm as [`baldart`](https://www.npmjs.com/package/baldart). If you need to pin a specific version (or you're hitting an old cached npx tarball), use `npx baldart@3.6.1 <cmd>` (or any other version). The legacy form `npx -y github:antbald/BALDART <cmd>` still works for unreleased commits on `main`.
+
+That's it! The `add` command handles everything automatically:
+- Downloads the framework via Git subtree into `.framework/`
+- Creates symlinks for auto-updateable files (AGENTS.md, agents/, .claude/agents/, .claude/commands/)
+- Copies customizable templates (hooks, UI guidelines, backlog cards)
+- Creates required directories (docs/, templates/, backlog/)
+
+No additional activation steps needed — once installed, Claude Code will automatically pick up the agents, commands, and protocols.
+
+### Usage
+
+```bash
+# Smart entry point: diagnose install state and propose next action.
+# `npx baldart` with no arguments runs this; equivalent to `baldart doctor`.
+npx baldart
+
+# Show version + install date + drift from remote
+npx baldart version
+
+# Check status (symlinks, config, overlay drift)
+npx baldart status
+
+# (Re)generate baldart.config.yml — interactive prompts + autodetection
+npx baldart configure
+
+# Update framework
+npx baldart update
+
+# Contribute improvements upstream (auto bump + CHANGELOG + tag)
+npx baldart push
+```
+
+> **Tip**: During installation, BALDART offers to configure git aliases (`fw-version`, `fw-update`, `fw-push`) so you can skip the `npx baldart` prefix after the first install.
+
+## Features
+
+### Core Protocol
+
+- **AGENTS.md**: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
+- **agents/**: 17 domain modules (architecture, workflows, testing, security, etc.)
+- **Routing**: If you touch X, read Y - minimize context loading
+
+### AI Agents (24 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/`) with auto-learning loop
+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 (Quick/Full/Deep profiles) — 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
+
+**Product & Marketing**
+18. **onboarding-architect-lead**: User onboarding flow design and experimentation
+19. **marketing-conversion-strategist**: High-converting copy and messaging
+20. **seo-analytics-strategist**: SEO strategy, metadata, GA4/GTM event planning
+21. **email-deliverability-architect**: Transactional/informational email design + SPF/DKIM/DMARC
+22. **website-orchestrator**: Multi-agent website development coordination
+
+**Specialized**
+23. **hybrid-ml-architect**: ML/DL system design (recommenders, ranking, embeddings)
+24. **legal-counsel-gdpr**: GDPR compliance, privacy policies, data governance
+25. **deep-human-insight**: Psychological / sociological analysis for B2C UX and adoption
+26. **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.
+
+### 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 (new in v2.0.0 — 22 portable skills)
+
+Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
+Bundled skills:
+
+- **Workflow**: `new`, `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
+- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`
+- **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`
+- **Product**: `seo-audit`, `copywriting`, `api-design-principles`
+- **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
+- **Integration**: `kie-ai`, `remotion-best-practices`
+
+### 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/`) with an auto-learning
+loop: RAG telemetry → synthesis candidates → `/capture` skill → new wiki
+pages. 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 auto-learning and
+drift-detection loops actually run. Ship-bundled routines:
+
+| Routine | Cadence | Agent | Purpose |
+|---------|---------|-------|---------|
+| `wiki-review` | nightly 02:00 UTC | wiki-curator | Drives the LLM-wiki auto-learning loop |
+| `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 |
+| `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
+
+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
+│   └── 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/`
+
+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.
+
+- Shows changelog
+- Creates backup tag
+- Updates via Git subtree
+- Verifies symlinks
+
+### `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.
+
+### `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

package/VERSION

@@ -0,0 +1 @@
+3.6.2