Re-analyze the current project, update the full Claude Code configuration, propagate `.claude/`
From claude-code-expertnpx claudepluginhub markus41/claude --plugin claude-code-expert/cc-syncSync Claude Code config between ~/.claude/ and ~/cc-setup repo — backup, restore, diff, install
Re-analyze the current project, update the full Claude Code configuration, propagate .claude/
into sub-repositories, scaffold the docs/context/ knowledge base, and ensure README.md and
CLAUDE.md are comprehensive and interlinked. Safe to run repeatedly — merges without overwriting
user customizations.
/cc-sync # Full sync — update everything
/cc-sync --dry-run # Preview changes without writing
/cc-sync --docs-only # Only sync docs/context/ structure
/cc-sync --subrepos-only # Only propagate .claude to sub-repos
/cc-sync --readme-only # Only update README.md + CLAUDE.md
/cc-sync --lsp-only # Only detect and install LSPs
/cc-sync --rules-only # Only sync .claude/rules/
/cc-sync --force # Overwrite existing files (careful!)
/cc-sync --depth 2 # Sub-repo scan depth (default: 2)
/cc-sync --verbose # Show detailed diff of changes
| Aspect | /cc-setup | /cc-sync |
|---|---|---|
| Purpose | First-time deployment | Ongoing maintenance |
| Writes | Creates from scratch | Merges into existing |
| User edits | May overwrite | Preserves user sections |
| Sub-repos | Ignored | Discovered and configured |
| docs/context/ | Not created | Full knowledge base scaffold |
| README | Basic | Comprehensive nested structure |
| CLAUDE.md | Routing OS | Routing OS + cross-references |
| Idempotent | No | Yes — safe to re-run |
| LSP install | Recommends | Installs missing ones |
Re-scan the project using the same detection maps as /cc-setup Phase 1, but compare
against the existing configuration to compute a delta.
# Build current fingerprint
FINGERPRINT=(
languages: [detected]
frameworks: [detected]
infrastructure: [detected]
databases: [detected]
services: [detected]
test_frameworks: [detected]
package_manager: detected
monorepo: detected | none
scale: small | medium | large
)
# Load previous fingerprint if saved
PREV_FINGERPRINT=".claude/sync-state.json"
{
"added": ["Prisma", "Redis"],
"removed": ["Knex"],
"unchanged": ["TypeScript", "Next.js", "Docker", "PostgreSQL"],
"config_drift": {
"rules_missing": ["security.md"],
"skills_stale": ["db-ops"],
"hooks_orphaned": ["auto-knex.sh"],
"agents_missing": ["security-auditor"]
}
}
After sync completes, write .claude/sync-state.json for future delta comparisons:
{
"lastSync": "2026-03-19T12:00:00Z",
"fingerprint": { ... },
"version": "6.1.0",
"syncCount": 4
}
Scan for nested git repositories and ensure each has a .claude/ directory with
appropriate configuration inherited from the root.
# Find sub-directories that are git repos (up to --depth levels)
# Skip: node_modules, .git, vendor, dist, build, coverage, __pycache__
EXCLUDE_DIRS="node_modules|\.git|vendor|dist|build|coverage|__pycache__|\.next|\.nuxt|\.cache"
find . -maxdepth ${DEPTH:-2} -name ".git" -type d \
| grep -vE "$EXCLUDE_DIRS" \
| while read gitdir; do
REPO_DIR=$(dirname "$gitdir")
if [ "$REPO_DIR" != "." ]; then
echo "SUB_REPO: $REPO_DIR"
fi
done
For each discovered sub-repository:
| What | Action | Override? |
|---|---|---|
.claude/ directory | Create if missing | No |
CLAUDE.md | Create with sub-project context if missing, merge if exists | Merge only |
.claude/rules/ | Copy root rules, skip if sub-repo has its own | No overwrite |
.claude/rules/lessons-learned.md | Create empty if missing | No overwrite |
.claude/rules/self-healing.md | Copy from root | No overwrite |
.claude/settings.json | Inherit root permissions + sub-repo specific | Merge |
.claude/hooks/ | Copy session-init.sh and error capture only | No overwrite |
# {Sub-Repo Name}
> Part of the {root_project_name} workspace.
> Root instructions: see `../../CLAUDE.md`
## Purpose
{auto_detected_from_package_json_or_directory_name}
## Build & Test
- Install: `{detected_install_cmd}`
- Build: `{detected_build_cmd}`
- Test: `{detected_test_cmd}`
## Tech Stack
{detected_from_sub_repo_files}
## Key Paths
- Source: {src_dir}
- Tests: {test_dir}
## Conventions
- Follow root project conventions unless overridden here
- {any_sub_repo_specific_conventions}
## Don't Touch
- {auto_generated_files}
=== Sub-Repository Sync ===
packages/api/ ✓ .claude/ exists, updated rules
packages/web/ ✓ .claude/ created (new), 4 files written
packages/shared/ ✓ .claude/ exists, no changes needed
tools/cli/ ✓ .claude/ created (new), 3 files written
services/worker/ ⚠ .claude/ exists, 2 rules outdated → updated
Total: 5 sub-repos, 3 updated, 2 created, 0 skipped
Generate a comprehensive docs/context/ knowledge base. Each file is created with
a starter template if it doesn't exist. Existing files are never overwritten.
docs/
context/
project-overview.md # What this system is, for whom, capabilities, non-goals
vision-and-roadmap.md # Where it's going next; informs suggestions and refactors
domain-glossary.md # Canonical definitions for domain terms, entities, statuses
personas-and-use-cases.md # Key user types and primary use cases
architecture.md # Top-level diagram and narrative (systems, boundaries)
architecture-runtime.md # Runtime view (calls, queues, batch jobs, external services)
architecture-deployment.md # Environments, regions, scaling, feature flags
data-model.md # Main entities, relationships, invariants
data-migrations.md # How to evolve data safely (playbooks, patterns)
api-contracts.md # Important endpoints, request/response, status codes
api-guidelines.md # REST/GraphQL patterns, pagination, errors, idempotency
ux-flows.md # Main flows as step-by-step narratives
ux-principles.md # Design/interaction principles to protect during code changes
security-rules.md # Authz rules, PII handling, tenant isolation
compliance.md # HIPAA/GDPR/other obligations, logging/retention rules
testing-strategy.md # How tests are organized, what must be tested
test-inventory.md # Pointers to major test suites, contracts, golden tests
constraints.md # Platform support, tech choices, SLAs/SLOs
performance.md # Budgets, hotspots, benchmarks, perf-related gotchas
ops-and-runbooks.md # Key operational procedures, incident handling
changelog.md # Human-readable record of important changes
plan.md # Current work plan / scratchpad (Claude can maintain)
decisions/ # Architecture Decision Records
adr-template.md # Starter template for new ADRs
Each file gets a starter template with clear section headers. Templates are only written when the file does not exist. Example:
# Project Overview
> Auto-generated by /cc-sync on {date}. Fill in the sections below.
## What Is This?
<!-- One paragraph: what the system does and who it serves -->
## Core Capabilities
<!-- Bulleted list of primary features/services -->
## Non-Goals
<!-- What this project explicitly does NOT do -->
## Tech Stack Summary
{auto_detected_stack_from_fingerprint}
## Repository Structure
```text
{auto_generated_tree_of_top_level_dirs}
#### architecture.md template
```markdown
# Architecture
> Auto-generated by /cc-sync on {date}. Fill in the sections below.
## System Diagram
<!-- Paste or describe the high-level architecture diagram -->
## Components
| Component | Purpose | Tech | Location |
|-----------|---------|------|----------|
{auto_detected_components}
## Boundaries
<!-- What is internal vs external? Where are the trust boundaries? -->
## Data Flow
<!-- How does data flow through the system? -->
## Key Design Decisions
<!-- Link to docs/context/decisions/ for ADRs -->
# ADR-NNNN: {Title}
**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** {date}
**Deciders:** {names}
## Context
<!-- What is the issue that we're seeing that motivates this decision? -->
## Decision
<!-- What is the change that we're proposing and/or doing? -->
## Consequences
<!-- What becomes easier or harder because of this change? -->
## Alternatives Considered
<!-- What other options were evaluated? Why were they rejected? -->
When creating templates, auto-populate what we can from the project fingerprint:
| Template Field | Source |
|---|---|
| Tech Stack Summary | Phase 1 detected languages/frameworks |
| Repository Structure | ls top-level directories |
| Components table | Detected services (Docker Compose, package.json workspaces) |
| Build commands | Detected package manager + scripts |
| Test strategy | Detected test frameworks |
Ensure the .claude/ directory has the full recommended structure. Create missing
directories and starter files without overwriting existing ones.
.claude/
CLAUDE.local.md # Personal overrides (gitignored)
settings.json # Project settings
settings.local.json # Personal settings (gitignored)
rules/
coding.md # Language/framework conventions
testing.md # Test types, locations, coverage targets
security.md # Authn/z, secrets, PII, dependency policies
infra.md # Terraform/Helm/Docker conventions
review.md # PR checklist, what "good" changes look like
product.md # Product principles preserved in code
git-workflow.md # Commit format, branch strategy
architecture.md # Module boundaries, import rules
self-healing.md # Error capture and learning loop
lessons-learned.md # Auto-growing error/fix knowledge base
memory-profile.md # Project identity, team info, domains
memory-preferences.md # User workflow preferences, tool choices
memory-decisions.md # Architecture Decision Records
memory-patterns.md # Recurring code patterns and solutions
memory-sessions.md # Recent session summaries (auto-rotated)
skills/
code-review/
SKILL.md # Structured review workflow
checklist.md # Review checklist
template.md # Review output template
examples.md # Example reviews
release-notes/
SKILL.md # Changelog generation from diffs/PRs
template.md # Release note template
examples.md # Example release notes
migration-planner/
SKILL.md # Safe schema/API migration planning
playbook.md # Step-by-step migration playbook
bug-triage/
SKILL.md # Bug categorization and prioritization
heuristics.md # Triage decision heuristics
templates/
pr-description.md # PR template Claude fills in
design-doc.md # Small RFC/ADR skeleton
test-plan.md # Test description template
incident-report.md # Postmortem template
agents/
backend-architect.md # Backend/infra heuristics persona
frontend-specialist.md # UI/UX specialist persona
infra-guardian.md # Conservative, safety-first infra persona
qa-analyst.md # Test design and bug-hunting focus
hooks/
security-guard.sh # Block destructive commands
auto-format.sh # Format on save
lessons-learned-capture.sh # Capture errors
inject-context.sh # Dynamic context injection
session-init.sh # Session startup
on-stop.sh # Session end
For each file in the target structure:
IF file does not exist:
→ Create from template
→ Log: "CREATED: {path}"
ELSE IF file exists AND --force flag:
→ Backup to {path}.bak
→ Overwrite with template
→ Log: "OVERWRITTEN: {path} (backup at {path}.bak)"
ELSE:
→ Skip
→ Log: "SKIPPED: {path} (already exists)"
---
description: "Structured code review — auto-invoke for PR reviews and /review commands"
model: claude-opus-4-6
allowed-tools:
- Read
- Grep
- Glob
- Bash
---
# Code Review
## Workflow
1. Read the diff or changed files
2. Run through checklist.md categories
3. Generate structured review using template.md
4. Flag security, performance, and correctness issues
5. Suggest improvements with code examples
## Inputs
- File paths, diff, or PR number
## Outputs
- Structured review (see template.md)
---
description: "Bug triage and prioritization — auto-invoke for bug reports and issue analysis"
model: claude-sonnet-4-6
allowed-tools:
- Read
- Grep
- Glob
- Bash
---
# Bug Triage
## Workflow
1. Reproduce or verify the bug report
2. Categorize: crash, data loss, UX, performance, cosmetic
3. Assess severity × frequency = priority score
4. Identify root cause area using heuristics.md
5. Recommend fix approach and effort estimate
## Inputs
- Bug description, error logs, screenshots
## Outputs
- Priority: P0-P4, Category, Root cause area, Fix estimate
Generate or update README.md with a comprehensive, nested structure:
# {Project Name}
> {One-line description from package.json or auto-detected}
## Table of Contents
- [Overview](#overview)
- [Getting Started](#getting-started)
- [Architecture](#architecture)
- [Development](#development)
- [Testing](#testing)
- [Deployment](#deployment)
- [Claude Code Integration](#claude-code-integration)
- [Documentation](#documentation)
- [Contributing](#contributing)
## Overview
{Auto-generated from docs/context/project-overview.md if exists, else from fingerprint}
### Tech Stack
| Layer | Technology |
|-------|-----------|
{auto_detected_stack_table}
### Repository Structure
```text
{auto_generated_directory_tree_depth_2}
{auto_detected_from_engines_field_and_stack}
{detected_install_command}
{detected_dev_command}
{point_to_env_example_or_list_required_vars}
{Summary from docs/context/architecture.md or auto-detected component list}
See docs/context/architecture.md for full details.
{detected_from_eslint_prettier_editorconfig}
{detected_from_git_history_or_conventions}
type(scope): description
Types: feat, fix, refactor, test, docs, chore, perf, ci
{detected_test_command}
{detected_test_framework_info}
See docs/context/testing-strategy.md for full strategy.
{summary_from_detected_infra}
See docs/context/architecture-deployment.md.
This project is configured for Claude Code with the full 4-layer extension stack:
| Layer | Status | Files |
|---|---|---|
| CLAUDE.md | {status} | CLAUDE.md + .claude/rules/*.md |
| Skills | {status} | .claude/skills/*/SKILL.md |
| Hooks | {status} | .claude/settings.json + .claude/hooks/*.sh |
| Agents | {status} | .claude/agents/*.md |
/cc-setup — Full repo analysis and initial deployment/cc-sync — Update configuration after project changes/cc-intel — Deep code analysis for complex tasks.claude/settings.json.mcp.json.claude/rules/.claude/rules/lessons-learned.mdAll project documentation lives in docs/context/:
| Document | Purpose |
|---|---|
| Project Overview | What, who, why |
| Architecture | System design |
| Data Model | Entities and relationships |
| API Contracts | Endpoints and formats |
| Security Rules | Auth and compliance |
| Testing Strategy | Test approach |
| ADRs | Architecture decisions |
| Changelog | Change history |
main{detected_test_command}.claude/templates/pr-description.md
### 5.2 README Merge Strategy
The README uses **section-aware merging**:
FOR each section in template: IF section exists in current README: → SKIP (preserve user content) ELSE: → APPEND section at appropriate position → Log: "ADDED section: {heading}"
User-written sections are never deleted or overwritten.
### 5.3 CLAUDE.md Cross-Reference Update
Update the root `CLAUDE.md` to reference all generated assets:
```markdown
# Project Instructions
## Build & Test
{detected_commands}
## Tech Stack
{detected_stack_summary}
## Key Paths
- Source: {src_dir}
- Tests: {test_dir}
- Docs: docs/context/
- Rules: .claude/rules/
- Skills: .claude/skills/
- Agents: .claude/agents/
- Templates: .claude/templates/
## Reference Documents
Read these files for deep context before making major changes:
- Architecture: `@docs/context/architecture.md`
- Data Model: `@docs/context/data-model.md`
- Security: `@docs/context/security-rules.md`
- API: `@docs/context/api-contracts.md`
- Testing: `@docs/context/testing-strategy.md`
- Glossary: `@docs/context/domain-glossary.md`
## Rules
- Code style: `@.claude/rules/coding.md`
- Testing: `@.claude/rules/testing.md`
- Security: `@.claude/rules/security.md`
- Git: `@.claude/rules/git-workflow.md`
- Infrastructure: `@.claude/rules/infra.md`
## Skills
- Code review: `@.claude/skills/code-review/SKILL.md` (uses checklist.md + template.md)
- Release notes: `@.claude/skills/release-notes/SKILL.md`
- Bug triage: `@.claude/skills/bug-triage/SKILL.md`
- Migration planning: `@.claude/skills/migration-planner/SKILL.md`
## Templates
- PR descriptions: `.claude/templates/pr-description.md`
- Design docs: `.claude/templates/design-doc.md`
- Test plans: `.claude/templates/test-plan.md`
- Incident reports: `.claude/templates/incident-report.md`
## Decision Trees
- Auth/identity tasks → check `{auth_dir}` + `docs/context/security-rules.md`
- Database/migration tasks → check `{db_dir}` + `docs/context/data-model.md`
- Infrastructure tasks → check `{infra_dir}` + `docs/context/architecture-deployment.md`
- API changes → check `{api_dir}` + `docs/context/api-contracts.md`
- Performance concerns → check `docs/context/performance.md`
## Conventions
{detected_conventions}
## Don't Touch
{auto_generated_files}
{vendor_directories}
{lock_files}
For each detected language, check if the LSP is installed and install if missing:
LSP_MATRIX=(
# "language:lsp_binary:install_command"
"TypeScript:typescript-language-server:npm i -g typescript-language-server typescript"
"Python:pyright:npm i -g pyright"
"Go:gopls:go install golang.org/x/tools/gopls@latest"
"Rust:rust-analyzer:rustup component add rust-analyzer"
"Ruby:solargraph:gem install solargraph"
"PHP:intelephense:npm i -g intelephense"
"Svelte:svelte-language-server:npm i -g svelte-language-server"
"Vue:vue-language-server:npm i -g @vue/language-server"
"Tailwind:tailwindcss-language-server:npm i -g @tailwindcss/language-server"
"GraphQL:graphql-language-service-cli:npm i -g graphql-language-service-cli"
"Prisma:prisma-language-server:npm i -g @prisma/language-server"
"YAML:yaml-language-server:npm i -g yaml-language-server"
"Dockerfile:dockerfile-language-server:npm i -g dockerfile-language-server-nodejs"
"Bash:bash-language-server:npm i -g bash-language-server"
"SQL:sql-language-server:npm i -g sql-language-server"
"Terraform:terraform-ls:# Install from HashiCorp releases"
"C#:omnisharp:# Install via VS Code extension or dotnet tool"
"Elixir:elixir-ls:# Install via Mix"
)
for entry in "${LSP_MATRIX[@]}"; do
LANG="${entry%%:*}"
REST="${entry#*:}"
BINARY="${REST%%:*}"
INSTALL="${REST#*:}"
if is_detected "$LANG"; then
if ! command -v "$BINARY" &>/dev/null; then
echo " INSTALLING: $BINARY for $LANG"
eval "$INSTALL" 2>/dev/null
else
echo " OK: $BINARY already installed"
fi
fi
done
=== LSP Status ===
TypeScript: ✓ typescript-language-server (installed)
Python: ✓ pyright (installed)
Bash: ✗ bash-language-server → installing... ✓ done
YAML: ✗ yaml-language-server → installing... ✓ done
Dockerfile: ✗ dockerfile-language-server → installing... ✓ done
Installed: 3 new LSPs
Already present: 2
Ensure .gitignore includes Claude Code local files:
GITIGNORE_ENTRIES=(
"# Claude Code local files"
".claude/settings.local.json"
".claude/CLAUDE.local.md"
".claude/rules/memory-sessions.md"
)
for entry in "${GITIGNORE_ENTRIES[@]}"; do
if ! grep -qF "$entry" .gitignore 2>/dev/null; then
echo "$entry" >> .gitignore
fi
done
╔══════════════════════════════════════════════════════╗
║ Claude Code Sync Report ║
╠══════════════════════════════════════════════════════╣
Fingerprint: TypeScript · Next.js · Prisma · Docker · PostgreSQL
Previous sync: 2026-03-15 (4 days ago)
Changes detected: +Redis, -Knex
┌─── Root Project ───────────────────────────────────┐
│ CLAUDE.md ✓ Updated (3 new references) │
│ README.md ✓ Updated (added 2 sections) │
│ .claude/rules/ ✓ 10/10 files present │
│ .claude/skills/ ✓ 4 skills (1 new: redis-ops) │
│ .claude/agents/ ✓ 4 agents present │
│ .claude/hooks/ ✓ 6 hooks configured │
│ .claude/templates/ ✓ 4 templates present │
│ docs/context/ ✓ 15/22 files populated │
│ LSPs ✓ 5 installed (2 new) │
│ MCP Servers ✓ 3 configured │
└────────────────────────────────────────────────────┘
┌─── Sub-Repositories ───────────────────────────────┐
│ packages/api/ ✓ .claude/ synced │
│ packages/web/ ✓ .claude/ created (new) │
│ packages/shared/ ✓ no changes needed │
└────────────────────────────────────────────────────┘
┌─── Recommendations ────────────────────────────────┐
│ ⚠ docs/context/architecture.md is empty — fill in │
│ ⚠ docs/context/data-model.md is empty — fill in │
│ ⚠ 3 ADRs recommended for key decisions │
│ ℹ Consider adding Redis MCP server to .mcp.json │
└────────────────────────────────────────────────────┘
Score: 82/100 → Advanced Setup
Previous: 74/100 (+8 improvement)
╚══════════════════════════════════════════════════════╝
| Category | Weight | Criteria |
|---|---|---|
| CLAUDE.md quality | 15 | Cross-references, routing, under 150 lines |
| README.md completeness | 10 | All sections populated with real content |
| .claude/rules/ coverage | 15 | Files for each detected concern area |
| .claude/skills/ relevance | 10 | Stack-matched skills present |
| .claude/agents/ coverage | 10 | Personas for key project areas |
| .claude/hooks/ events | 10 | Security + format + error capture minimum |
| .claude/templates/ | 5 | PR, design doc, test plan present |
| docs/context/ coverage | 10 | Populated docs for architecture, data, API |
| Sub-repo propagation | 5 | All sub-repos have .claude/ |
| LSP installation | 5 | All detected languages have LSPs |
| MCP servers | 5 | Appropriate servers configured |
Save the sync state for future runs:
// .claude/sync-state.json
{
"version": "6.1.0",
"lastSync": "2026-03-19T12:00:00Z",
"syncCount": 4,
"fingerprint": {
"languages": ["TypeScript", "Python"],
"frameworks": ["Next.js"],
"infrastructure": ["Docker", "GitHub Actions"],
"databases": ["PostgreSQL", "Redis"],
"services": ["Prisma", "Stripe"],
"testFrameworks": ["Vitest", "Playwright"],
"packageManager": "pnpm",
"monorepo": "pnpm workspaces",
"scale": "medium"
},
"generated": {
"rules": ["coding.md", "testing.md", "security.md", "git-workflow.md"],
"skills": ["code-review", "release-notes", "bug-triage"],
"agents": ["backend-architect", "frontend-specialist"],
"templates": ["pr-description.md", "design-doc.md", "test-plan.md"],
"docs": ["project-overview.md", "architecture.md", "data-model.md"],
"hooks": ["security-guard.sh", "auto-format.sh", "lessons-learned-capture.sh"],
"lsps": ["typescript-language-server", "pyright", "bash-language-server"]
},
"subRepos": [
{ "path": "packages/api", "hasClaudeDir": true, "lastSync": "2026-03-19T12:00:00Z" },
{ "path": "packages/web", "hasClaudeDir": true, "lastSync": "2026-03-19T12:00:00Z" }
],
"score": {
"current": 82,
"previous": 74,
"history": [45, 62, 74, 82]
}
}
When /cc-sync is invoked:
| Flag | Description |
|---|---|
--dry-run | Preview all changes without writing any files |
--docs-only | Only sync docs/context/ structure |
--subrepos-only | Only propagate .claude/ to sub-repositories |
--readme-only | Only update README.md and CLAUDE.md |
--lsp-only | Only detect and install LSPs |
--rules-only | Only sync .claude/rules/ files |
--skills-only | Only sync .claude/skills/ |
--agents-only | Only sync .claude/agents/ |
--templates-only | Only sync .claude/templates/ |
--force | Overwrite existing files (creates .bak backups) |
--depth N | Sub-repo scan depth (default: 2) |
--verbose | Show detailed diff of each change |
--no-lsp | Skip LSP installation |
--no-subrepos | Skip sub-repo discovery |
--no-docs | Skip docs/context/ scaffolding |
--score-only | Only run scoring, don't modify anything |
--force with .bak backup)