feat(claude): add xdev workflow configuration

Global CLAUDE.md with dev principles, three xdev commands
(implement, draft, setup), and install script for symlinks.

diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md
new file mode 100644 (file)
index 0000000..eca1529
--- /dev/null
+++ b/claude/CLAUDE.md
@@ -0,0 +1,53 @@
+# Development Principles
+
+## Quality
+- Quality over speed. Skip uncertain tasks rather than deliver bad code.
+- Keep solutions minimal. No extra abstractions or "just in case" code.
+- Stay strictly within the scope of the task. Do not refactor or improve
+  surrounding code unless explicitly asked.
+
+## Decision Making
+- If multiple valid approaches exist, discuss with the user before choosing.
+  Do NOT pick one silently.
+- If a change involves new abstractions, new patterns, or structural changes
+  not explicitly requested in the task, discuss first.
+- When uncertain about any design decision, ask rather than guess.
+- Follow existing codebase patterns unless the task specifically requires
+  changing them. If you believe structural changes are needed beyond the
+  task scope, raise it as a separate concern.
+
+## Context Management
+- Complete the entire task within a single context window.
+- If a task is clearly too large for one context, suggest splitting it
+  into smaller tasks before starting.
+- When making incremental progress, commit working code frequently so
+  progress is preserved in git.
+
+# Git Commit Convention
+
+Follow Conventional Commits strictly:
+
+## Format
+```
+<type>(<scope>): <subject>
+```
+
+## Rules
+- type: feat/fix/refactor/docs/test/chore/perf/build
+- scope: optional, module or component name
+- subject: imperative mood, lowercase, no period, max 50 chars
+- English only
+- Focus on WHAT changed, not WHY or HOW you thought about it
+- Be concise and direct
+- No emoji, no AI markers, no co-author footer, no "Generated by" text
+
+## Good examples
+- `feat(order): add limit order support`
+- `fix(gateway): handle reconnection on market data timeout`
+- `refactor(engine): simplify order state machine`
+- `perf(matching): reduce memory allocation in hot path`
+
+## Bad examples
+- `feat: Added new feature for better user experience` (vague, past tense)
+- `fix: Fix the bug that was causing issues` (redundant)
+- `update code` (no type, meaningless)

diff --git a/claude/commands/xdev-draft.md b/claude/commands/xdev-draft.md
new file mode 100644 (file)
index 0000000..5549364
--- /dev/null
+++ b/claude/commands/xdev-draft.md
@@ -0,0 +1,28 @@
+Help the user draft a well-structured issue for their project's
+issue tracker.
+
+## Process
+
+1. Ask the user to describe what they want in their own words.
+2. Ask clarifying questions (one at a time) to understand:
+   - What is the problem or desired outcome?
+   - What is the current behavior vs expected behavior?
+   - Are there constraints or preferences?
+3. Draft a structured issue with:
+   - Title: `type(scope): concise description`
+   - Body:
+     - **Context**: why this is needed (1-2 sentences)
+     - **Goal**: what should change (concrete, testable)
+     - **Acceptance criteria**: how to verify it's done
+     - **Constraints** (if any): what NOT to do, what to preserve
+4. Present the draft to the user for review.
+5. If the user approves, submit using whatever tool is available
+   (gh, glab, MCP), or output the formatted text for manual submission.
+
+## Principles
+
+- Intent-driven: describe WHAT and WHY, not HOW to implement.
+- Give implementation space: do not over-specify the approach.
+- One issue = one change. If the idea is too big, suggest splitting
+  into multiple issues.
+- Include acceptance criteria so the implementer knows when it's done.

diff --git a/claude/commands/xdev-implement.md b/claude/commands/xdev-implement.md
new file mode 100644 (file)
index 0000000..61514ba
--- /dev/null
+++ b/claude/commands/xdev-implement.md
@@ -0,0 +1,45 @@
+You are handling an issue from the project's issue tracker.
+Follow this SOP strictly.
+
+## Step 1: Understand
+
+- Fetch the issue content (title, body, labels, comments).
+  Use whatever tool is available (gh, glab, MCP, or ask the user to provide).
+- Read the project's CLAUDE.md and understand the codebase structure.
+- Identify the scope: what files are likely affected, what tests exist.
+
+## Step 2: Assess Complexity
+
+Before writing any code, assess:
+- Is the issue clear enough to implement? If not, ask the user for clarification.
+- Are there multiple valid approaches? If yes, present them with trade-offs
+  and let the user choose. Do NOT pick one silently.
+- Is this too large for a single context? If yes, suggest splitting into
+  smaller issues before starting.
+
+## Step 3: Branch and Implement
+
+- Create a feature branch: `<type>/issue-<number>-<short-description>`
+- Implement the change following existing codebase patterns.
+- Write tests for the change (unless pure documentation).
+- Make small, focused commits using Conventional Commits format.
+
+## Step 4: Validate
+
+Before submitting:
+- All existing tests still pass.
+- New tests cover the changes.
+- Changes are limited to issue scope.
+- No unnecessary refactoring or additions.
+
+## Step 5: Submit
+
+- Push the branch and create a merge/pull request linking the issue.
+- Title: concise summary. Body: what changed and why.
+
+## Escape Hatch
+
+If at any point:
+- The issue is unclear → ask the user, do not guess.
+- The implementation risk is too high → explain the risk and stop.
+- The scope is larger than expected → suggest splitting into multiple issues.

diff --git a/claude/commands/xdev-setup.md b/claude/commands/xdev-setup.md
new file mode 100644 (file)
index 0000000..e54dff6
--- /dev/null
+++ b/claude/commands/xdev-setup.md
@@ -0,0 +1,98 @@
+Analyze the current project and generate a health report. Then guide
+the user through setting up CLAUDE.md if one doesn't exist.
+
+## Step 1: Project Analysis
+
+Scan the project root and report findings for each quality dimension.
+Do not assume any specific language or toolchain.
+
+### Build System
+Detect build files: CMakeLists.txt, Makefile, meson.build, package.json,
+pyproject.toml, setup.py, Cargo.toml, go.mod, build.gradle, pom.xml,
+or other build configuration.
+Report what was found, or note "no build system detected".
+
+### Testing
+Detect test directories: tests/, test/, __tests__/, spec/, or test
+files matching common patterns (*_test.*, test_*.*, *.spec.*, *_spec.*).
+Detect test runner config: pytest.ini, jest.config.*, .mocharc.*,
+CTestTestfile.cmake, Catch2/GoogleTest headers, etc.
+Report what was found.
+
+### Code Quality Tools
+Detect formatter/linter config: .clang-format, .clang-tidy, .eslintrc*,
+.prettierrc*, pyproject.toml [tool.ruff/black/flake8], rustfmt.toml,
+.editorconfig, .golangci.yml, or similar.
+Detect git hooks: .pre-commit-config.yaml, .husky/, .githooks/.
+Report what was found.
+
+### CI/CD
+Detect: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, .circleci/,
+.travis.yml, bitbucket-pipelines.yml, or similar.
+Report what was found.
+
+### Documentation
+Check: README.md and CLAUDE.md existence. If they exist, note whether
+they have meaningful content beyond just a title.
+
+## Step 2: Report
+
+Present findings as a concise checklist:
+
+```
+Project Health Report: <project-name>
+  Build system:    ✓ CMake (CMakeLists.txt)
+  Tests:           ✓ tests/ directory, GoogleTest
+  Code quality:    ✓ .clang-format, .clang-tidy, pre-commit
+  CI/CD:           ✗ No CI configuration found
+  README:          ✓ Exists with content
+  CLAUDE.md:       ✗ Missing
+```
+
+For each ✗ item, provide a brief, actionable suggestion.
+Do NOT mandate specific tools — suggest based on what fits the project.
+
+## Step 3: CLAUDE.md Creation (if missing or inadequate)
+
+If CLAUDE.md doesn't exist or is just a placeholder, guide the user:
+
+1. Ask about the project's purpose (one sentence).
+2. Document detected build/test commands.
+3. Ask about key code conventions or architectural constraints.
+4. Generate a minimal CLAUDE.md (under 50 lines) following this structure:
+
+```markdown
+# <Project Name>
+
+<One-sentence project description.>
+
+## Quick Reference
+
+\```bash
+# Build
+<build command>
+
+# Test
+<test command>
+\```
+
+## Code Conventions
+
+- <Convention 1>
+- <Convention 2>
+
+## Constraints
+
+- <Things Claude should NOT do>
+- <Protected files/directories>
+- <Dependency rules>
+```
+
+Do NOT over-generate. A 20-line CLAUDE.md with accurate info is better
+than a 100-line one with guesses.
+
+## Step 4: Hooks Suggestion (optional)
+
+If a code formatter is detected, suggest a PostToolUse hook configuration
+that auto-formats after edits. Present the suggestion and let the user
+decide whether to add it to `.claude/settings.local.json`.

diff --git a/install-claude.sh b/install-claude.sh
new file mode 100755 (executable)
index 0000000..55ba91f
--- /dev/null
+++ b/install-claude.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLAUDE_DIR="$HOME/.claude"
+
+echo "Installing Claude Code configuration..."
+
+# Backup existing CLAUDE.md if it exists and is not a symlink
+if [ -f "$CLAUDE_DIR/CLAUDE.md" ] && [ ! -L "$CLAUDE_DIR/CLAUDE.md" ]; then
+    echo "Backing up existing CLAUDE.md to CLAUDE.md.bak"
+    cp "$CLAUDE_DIR/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md.bak"
+fi
+
+# Symlink CLAUDE.md
+ln -sf "$SCRIPT_DIR/claude/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md"
+echo "  ✓ CLAUDE.md"
+
+# Symlink commands
+mkdir -p "$CLAUDE_DIR/commands"
+for cmd in "$SCRIPT_DIR"/claude/commands/xdev-*.md; do
+    [ -f "$cmd" ] || continue
+    ln -sf "$cmd" "$CLAUDE_DIR/commands/$(basename "$cmd")"
+    echo "  ✓ commands/$(basename "$cmd")"
+done
+
+echo "Done. Claude Code xdev workflow installed."