teamcraft-jcg:sync-claude-md

---
name: teamcraft-jcg:sync-claude-md
description: Audit and update CLAUDE.md, .claude/rules/, and .teamcraft/project.md to reflect the current state of the project. Run anytime — mid-ticket, end of sprint, pure maintenance, or first-time setup for a project with none of these files. Developer drives what changes; skill provides the analysis.
argument-hint: "(no arguments — you'll describe your intent at the start)"
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Glob
  - Bash
  - mcp__sooperset-mcp-atlassian__jira_get_all_projects
  - mcp__sooperset-mcp-atlassian__confluence_search
  - mcp__sooperset-mcp-atlassian__confluence_get_page
---

## Goal

Keep CLAUDE.md, `.claude/rules/`, and `.teamcraft/project.md` accurate and lean. Remove entries that are now discoverable from the codebase. Add new non-obvious things the team has learned. Incorporate lessons from recent work, newly established conventions, or developer input. Works for any project at any point — including projects with none of these files.

## Hard Constraints

- No presuppositions about project state. None of these files may exist. All of them may exist. Some may be hand-crafted with no prior teamcraft history. Work with what's there.
- Never write anything without showing proposed changes and getting developer confirmation.
- Additions to CLAUDE.md must pass the test: would Claude Code get this wrong, and can it not discover it from the environment? If the answer is no — it does not belong.
- Removals from CLAUDE.md are for entries that are now discoverable from the codebase — things visible in config files, code patterns, or README that Claude Code can now see for itself.
- `.teamcraft/project.md` stays minimal. If it doesn't exist, offer to create it. If Confluence page IDs or GitHub repo reference have changed, update them.
- `CLAUDE.md` starts with `@.teamcraft/project.md` — verify this import is present.

## Orient to Current State

Establish what the developer wants to accomplish. The common scenarios: capturing lessons learned from a recent ticket, recording newly established team conventions, a periodic audit to trim stale entries, or initial setup for a project that has none of these files.

Read what exists: `.teamcraft/project.md`, `CLAUDE.md`, `.claude/rules/*.md`. Read key project config files to understand what the codebase now reveals — dependencies, structure, patterns. This is the basis for identifying what in CLAUDE.md has become redundant.

If Confluence artifacts are referenced in project.md (tech decisions page ID, conventions page ID), offer to load them as context using `mcp__sooperset-mcp-atlassian__confluence_get_page`. The developer may also have input that doesn't come from any document — lessons learned during recent work, gotchas discovered, architectural changes made.

## Produce the Analysis

Assess CLAUDE.md and rules files against the current codebase and developer input:

**Candidates for removal:** entries that are now visible in the code, config files, or README — things Claude Code can discover for itself.

**Candidates for addition:** lessons learned from recent work, newly established conventions, non-obvious constraints discovered, architectural decisions that look wrong without context, anything the developer reports Claude Code keeps getting wrong.

**Candidates for update:** entries that are partially correct but need refinement as the project has evolved.

Present additions and removals separately. The developer confirms, amends, or overrides each. Nothing is written until confirmed.

If none of these files exist, offer to create them — this skill functions as a first-time setup in that case. To create `.teamcraft/project.md`, identify the GitHub repo from git remote: `git remote -v` via Bash. For the Jira project, use `mcp__sooperset-mcp-atlassian__jira_get_all_projects` to surface available projects and ask the developer to confirm which one. Never assume. See `references/example-project-manifest.md` for the correct jcg manifest format. See `references/example-claude-md.md` for correct CLAUDE.md format and content.

## Done

Confirm what was written. Remind the developer this is a living system — run this skill whenever lessons are learned or the codebase evolves significantly enough that CLAUDE.md entries may have become stale or new ones are warranted.