claudboard

claudboard

A Claude Code plugin that deep-analyzes brownfield projects and generates production-ready .claude/ onboarding artifacts — so Claude Code can work effectively on any existing codebase from the first prompt.

What it does

Run /claudboard on any project and get:

• CLAUDE.md — Architecture overview, build/test/lint commands, critical rules, skill/rule index
• .claude/rules/*.md — Auto-loaded rules with paths: frontmatter, conventions extracted from actual code (not generic templates)
• .claude/skills/*/ — Full-scope skills: each has SKILL.md (workflow orchestrator), references/ (templates, annotated examples from your code), and scripts/scaffold.sh (boilerplate generator) — tailored to detected patterns, not generic stubs

The skill answers three questions about your project:

• What — what does it do, what value does it provide
• How — what architecture, patterns, and design decisions are in use
• Why — what constraints drove those decisions

It also identifies good patterns to preserve, anti-patterns to avoid, and tech debt to address.

Installation

claude plugin install github:lukovicperisa/claudboard

Or add manually: clone this repo, then reference the skills/claudboard/ directory.

Usage

Onboarding is a two-step process. Run each step separately for best results.

# Step 1: Analyse the project (read-only)
/analyse
/analyse ~/projects/my-app

# Step 2: Generate artifacts from the analysis (recommend fresh session)
/generate

The /analyse command scans, detects patterns, and writes:

• .claudboard/catalog.json — the primary artifact consumed by /generate (structured JSON, versioned schema)
• .claude/reports/claudboard-analysis.md — a thin human-readable summary for review before generating

By default, /analyse runs a reference-service deep pass per detected stack — cheap enough for large monorepos and multi-repo workspaces. Pass --audit for full per-service analysis (Watch findings, quality scores, cross-service graphs written to .claudboard/audits/<svc>.md).

Workspace and monorepo modes share one pipeline. Whether your project is a monorepo (N services, one .git/) or a multi-repo workspace (N repos, each with .git/), /analyse produces a single catalog at the umbrella root. Per-service .claude/ directories (skills, rules, memories) are not generated — service-specific content lives in rules with paths: globs, a single ecosystem.md at the umbrella root, and dispatcher skills (Pattern A) where needed.

The /generate command reads .claudboard/catalog.json and creates .claude/ artifacts. Best run in a fresh Claude Code session. If you have artifacts from a prior claudboard version (.claude/reports/cloudboard-analysis.md only), /generate auto-migrates to the catalog format on first run.

Filesystem layout

<project>/
  .claudboard/         ← build state; not loaded by Claude Code at runtime
    catalog.json       ← primary artifact for /generate and /refresh
    audits/            ← per-service reports (--audit only)
      <svc>.md
  .claude/             ← runtime context (auto-loaded by Claude Code)
    reports/
      claudboard-analysis.md   ← thin summary, human review
    rules/, skills/, memories/ ← generated artifacts
  CLAUDE.md            ← generated project overview

.claudboard/ is build state — consider adding it to .gitignore (or commit it to share the catalog across team members; see catalog-format.md for trade-offs).

Additional commands:

• /refresh — Delta updates for projects that already have .claude/ artifacts
• /techdebt — Deep tech debt analysis with module-grouped, ticket-ready reports
• /claudboard-workflow — Generates a complete .claude/skills/feature-workflow/ skill into any project (opt-in, run after /generate)
• /claudboard-workspace-init — Bootstrap a workspace meta-repo for multi-repo workspaces (run once by the first developer)
• /claudboard-workspace-link — Teammate bootstrap: clones the workspace meta-repo and wires up the symlink

Migration from older claudboard

If you've previously run /analyse without the catalog architecture (older versions produced only .claude/reports/claudboard-analysis.md), no action is required. On your next /generate run, claudboard automatically:

1. Detects the missing .claudboard/catalog.json
2. Parses your existing legacy report(s) and synthesises a catalog
3. Writes .claudboard/catalog.json (log line confirms the migration)
4. Proceeds with normal generation

Your legacy report files are left in place — only the new catalog is written. Subsequent /generate runs use the catalog directly and skip migration.

If migration fails (incompatible older format), the error message names the offending file and instructs you to run /analyse for a fresh catalog.

Migration from older claudboard (workspace mode)