clauderc 1.0.4 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clauderc",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Setup Claude Code with best practices - agents, skills, commands, and templates",
   "type": "module",
   "bin": {

package/src/detector.js

@@ -40,6 +40,9 @@ const ANALYSIS_FILES = [
   'vite.config.*',
   'next.config.*',
   'nuxt.config.*',
+  'commitlint.config.js',
+  '.releaserc',
+  'release.config.js',
 ];
 
 /**
@@ -299,6 +302,68 @@ function getRunCommand(pm) {
   return commands[pm] || '';
 }
 
+/**
+ * Detect commit convention tools
+ */
+function detectCommitConvention(projectPath) {
+  const commitlintConfigs = [
+    'commitlint.config.js',
+    'commitlint.config.cjs',
+    'commitlint.config.mjs',
+    'commitlint.config.ts',
+    '.commitlintrc.js',
+    '.commitlintrc.json',
+    '.commitlintrc.yml',
+  ];
+
+  const semanticReleaseConfigs = [
+    'release.config.js',
+    'release.config.cjs',
+    'release.config.mjs',
+    '.releaserc',
+    '.releaserc.json',
+    '.releaserc.js',
+    '.releaserc.yml',
+  ];
+
+  const commitlint = commitlintConfigs.some(f => existsSync(join(projectPath, f)));
+  const husky = existsSync(join(projectPath, '.husky/commit-msg'));
+  const semanticRelease = semanticReleaseConfigs.some(f => existsSync(join(projectPath, f)));
+
+  let commitizen = false;
+  let commitlintDep = false;
+  let conventionalChangelog = false;
+  let standardVersion = false;
+  let semanticReleaseDep = false;
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf-8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    commitizen = !!deps['commitizen'];
+    commitlintDep = !!deps['@commitlint/cli'];
+    conventionalChangelog = !!deps['conventional-changelog'];
+    standardVersion = !!deps['standard-version'];
+    semanticReleaseDep = !!deps['semantic-release'];
+  } catch {
+    // no package.json or parse error
+  }
+
+  const hasCommitlint = commitlint || commitlintDep;
+  const hasSemanticRelease = semanticRelease || semanticReleaseDep;
+  const hasCommitizen = commitizen;
+
+  if (!hasCommitlint && !husky && !hasSemanticRelease && !hasCommitizen && !conventionalChangelog && !standardVersion) {
+    return null;
+  }
+
+  return {
+    commitlint: hasCommitlint,
+    husky,
+    semanticRelease: hasSemanticRelease,
+    commitizen: hasCommitizen,
+  };
+}
+
 /**
  * Detect project stack from current directory
  */
@@ -376,6 +441,9 @@ export function detectStack(projectPath = process.cwd()) {
   // Detect CI
   result.ci = detectCI(projectPath);
 
+  // Detect commit convention
+  result.commitConvention = detectCommitConvention(projectPath);
+
   return result;
 }
 

package/src/project.js

@@ -177,6 +177,38 @@ Use Plan Mode (Shift+Tab 2x) for:
 - NEVER skip tests without explicit approval
 `;
 
+  content += `
+## Conventions
+
+### Commits (Conventional Commits)
+- Format: \`<type>(<scope>): <subject>\`
+- Types: \`feat\` | \`fix\` | \`docs\` | \`style\` | \`refactor\` | \`perf\` | \`test\` | \`chore\` | \`ci\`
+- Subject: imperative mood, max 72 chars, no period
+- Breaking changes: add \`!\` after type or \`BREAKING CHANGE:\` in footer
+
+### Semantic Versioning
+- \`feat\` → MINOR (1.x.0)
+- \`fix\`, \`docs\`, \`refactor\`, \`perf\`, \`style\` → PATCH (1.0.x)
+- \`BREAKING CHANGE\` or \`!\` → MAJOR (x.0.0)
+- \`test\`, \`chore\`, \`ci\` → no version change
+
+### Pull Requests
+- PR title: same Conventional Commits format
+- PR body: Summary (why), Changes (what), Test Plan
+- Run \`/verify\` before every PR
+`;
+
+  if (config.stack.commitConvention) {
+    const tools = [];
+    if (config.stack.commitConvention.commitlint) tools.push('commitlint');
+    if (config.stack.commitConvention.husky) tools.push('husky');
+    if (config.stack.commitConvention.semanticRelease) tools.push('semantic-release');
+    if (config.stack.commitConvention.commitizen) tools.push('commitizen');
+    if (tools.length > 0) {
+      content += `> This project uses ${tools.join(', ')} — follow its configured rules.\n\n`;
+    }
+  }
+
   if (customRules && customRules.length > 0) {
     content += `
 ## Project Rules
@@ -351,19 +383,70 @@ ${commands.setup || '# No setup command detected - configure in CLAUDE.md'}
 \`\`\`
 `,
 
-    pr: `# Create Pull Request
+    pr: `# Create a Semantic Pull Request
+
+Create a PR following Conventional Commits with structured description.
+
+## PR Title
+\`\`\`
+<type>(<scope>): <description>
+\`\`\`
 
-Commit, push, and create a PR.
+## PR Body Template
+- **Summary**: 1-3 bullets explaining WHAT and WHY
+- **Type of Change**: feat / fix / docs / refactor / perf / test / chore / breaking
+- **Changes**: Detailed list
+- **Breaking Changes**: If applicable, what breaks and migration steps
+- **Test Plan**: How it was tested
 
 ## Steps
-1. Stage all changes
-2. Commit with descriptive message
-3. Push to remote
-4. Create PR with \`gh pr create\`
+1. Run \`/verify\` to ensure all checks pass
+2. Analyze all commits on branch since base
+3. Determine PR type (highest-impact: breaking > feat > fix > others)
+4. Generate title in Conventional Commits format (max 72 chars)
+5. Generate structured body
+6. Push branch and create PR with \`gh pr create\`
 
 ## Prerequisites
 - \`gh\` CLI installed and authenticated
 - All tests passing (\`/verify\`)
+- Changes committed with \`/commit\`
+`,
+
+    commit: `# Create a Semantic Commit
+
+Create a well-structured commit following Conventional Commits.
+
+## Format
+\`\`\`
+<type>(<scope>): <subject>
+\`\`\`
+
+## Types
+| Type | Description | Version Impact |
+|------|-------------|----------------|
+| feat | New feature | MINOR |
+| fix | Bug fix | PATCH |
+| docs | Documentation | PATCH |
+| refactor | Code restructuring | PATCH |
+| perf | Performance improvement | PATCH |
+| test | Tests | No release |
+| chore | Build/CI/tooling | No release |
+
+## Rules
+- Imperative mood ("add" not "added")
+- Max 72 chars subject line
+- No period at end
+- Breaking changes: \`!\` after type or \`BREAKING CHANGE:\` footer
+- Reference issues: \`Fixes #123\` in footer
+
+## Steps
+1. Analyze staged changes with \`git diff --staged\`
+2. Determine type from nature of changes
+3. Identify scope (module/component affected)
+4. Write subject in imperative mood
+5. Add body if change needs explanation
+6. Execute \`git commit -m "<message>"\`
 `,
   };
 
@@ -512,6 +595,7 @@ export async function runProjectWizard(options = {}) {
       log('    ├── commands/verify.md');
       log('    ├── commands/setup.md');
       log('    ├── commands/pr.md');
+      log('    ├── commands/commit.md');
       log('    ├── settings.json');
       log('    CLAUDE.md');
       if (useMerge) {
@@ -532,6 +616,7 @@ export async function runProjectWizard(options = {}) {
       { path: join(claudeDir, 'commands', 'verify.md'), content: generateCommandFile('verify', config), type: 'command file' },
       { path: join(claudeDir, 'commands', 'setup.md'), content: generateCommandFile('setup', config), type: 'command file' },
       { path: join(claudeDir, 'commands', 'pr.md'), content: generateCommandFile('pr', config), type: 'command file' },
+      { path: join(claudeDir, 'commands', 'commit.md'), content: generateCommandFile('commit', config), type: 'command file' },
     ];
 
     for (const file of files) {
@@ -549,7 +634,7 @@ export async function runProjectWizard(options = {}) {
     log('  Next steps:');
     log('    1. Review CLAUDE.md and adjust as needed');
     log('    2. Commit .claude/ to your repository');
-    log('    3. Run /test, /lint, /verify in Claude Code\n');
+    log('    3. Run /test, /lint, /verify, /commit, /pr in Claude Code\n');
 
     return config;
   } catch (error) {

package/templates/agents/project-setup-wizard.md

@@ -128,6 +128,16 @@ Create `CLAUDE.md` in project root. Requirements:
 
 ### settings.json Format
 
+**CRITICAL: Only use properties that exist in the official schema. DO NOT invent properties.**
+
+Valid top-level keys: `permissions`, `hooks`, `attribution`, `language`, `model`, `env`, `sandbox`, `respectGitignore`, `cleanupPeriodDays`
+
+- `permissions`: `allow`, `deny`, `ask`, `defaultMode`, `additionalDirectories`
+- `hooks`: `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`
+- `attribution`: `commit`, `pr`
+
+**NEVER use:** `version`, `project`, `description`, `defaults`, `quality_gates`, `design_system`, `conventions`, `context_optimization`, `deny_read`, `require_approval`, `auto_approve`. These DO NOT exist. Textual instructions go in CLAUDE.md.
+
 ```json
 {
   "permissions": {
@@ -140,7 +150,7 @@ Create `CLAUDE.md` in project root. Requirements:
     "PostToolUse": [
       {
         "matcher": "Edit|Write",
-        "hooks": ["{{LINT_FIX_COMMAND}}"]
+        "hooks": [{ "type": "command", "command": "{{LINT_FIX_COMMAND}}" }]
       }
     ]
   }

package/templates/commands/commit.md

@@ -0,0 +1,80 @@
+# Create a Semantic Commit
+
+Create a well-structured commit following Conventional Commits specification.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Types
+
+| Type | Description | Version Impact |
+|------|-------------|----------------|
+| feat | New feature | MINOR (0.x.0) |
+| fix | Bug fix | PATCH (0.0.x) |
+| docs | Documentation only | PATCH |
+| style | Formatting, no code change | PATCH |
+| refactor | Code restructuring | PATCH |
+| perf | Performance improvement | PATCH |
+| test | Adding or fixing tests | No release |
+| chore | Build, CI, tooling | No release |
+| ci | CI/CD configuration | No release |
+
+## Breaking Changes
+
+Add `!` after type or `BREAKING CHANGE:` in footer for MAJOR version bumps:
+
+```
+feat!: remove deprecated API endpoints
+
+BREAKING CHANGE: /v1/users removed. Use /v2/users instead.
+```
+
+## Steps
+
+1. Run `git diff --staged` to analyze staged changes
+2. Determine the appropriate type from the changes
+3. Identify the scope (module, component, or area affected)
+4. Write a concise subject (imperative mood, no period, max 72 chars)
+5. Add body if the change needs explanation (wrap at 72 chars)
+6. Add footer for breaking changes or issue references
+7. Execute `git commit -m "<message>"`
+
+## Rules
+
+- Subject MUST be imperative mood ("add feature" not "added feature")
+- Subject MUST NOT exceed 72 characters
+- Subject MUST NOT end with a period
+- Body separated from subject by blank line
+- Reference issues: `Closes #123` or `Fixes #456` in footer
+- Multiple logical changes = separate commits
+
+## Examples
+
+```bash
+# Simple feature
+git commit -m "feat(auth): add OAuth2 login support"
+
+# Bug fix with issue reference
+git commit -m "fix(api): handle null response from payment gateway
+
+The payment gateway returns null when the session expires.
+Added null check and automatic session refresh.
+
+Fixes #234"
+
+# Breaking change
+git commit -m "feat(api)!: migrate to v2 authentication flow
+
+BREAKING CHANGE: API key format changed from UUID to JWT.
+All existing API keys must be regenerated."
+
+# Chore (no release triggered)
+git commit -m "chore(deps): upgrade lodash to 4.17.21"
+```

package/templates/commands/pr.md

@@ -1,46 +1,77 @@
-# Create a Pull Request
+# Create a Semantic Pull Request
 
-Commit changes, push to remote, and create a PR with generated description.
+Create a PR following Conventional Commits with structured description.
 
-## Workflow
-1. Stage all changes
-2. Generate commit message from diff
-3. Push to current branch
-4. Create PR with description
+## PR Title Format
 
-## Prerequisites
-- `gh` CLI installed and authenticated
-- Changes ready to commit
+Use Conventional Commits format:
+
+```
+<type>(<scope>): <description>
+```
+
+Examples:
+- `feat(auth): add OAuth2 login flow`
+- `fix(api): resolve race condition in payment processing`
+- `docs(readme): add deployment instructions`
+
+## PR Body Template
+
+```markdown
+## Summary
+<!-- 1-3 bullet points: WHAT changed and WHY -->
+
+## Type of Change
+- [ ] feat: New feature (MINOR version bump)
+- [ ] fix: Bug fix (PATCH version bump)
+- [ ] docs: Documentation
+- [ ] refactor: Code restructuring
+- [ ] perf: Performance improvement
+- [ ] test: Test changes
+- [ ] chore: Build/CI/tooling
+- [ ] breaking: Contains breaking changes (MAJOR version bump)
+
+## Changes
+<!-- Detailed list of changes -->
+
+## Breaking Changes
+<!-- If applicable: what breaks and migration steps -->
+
+## Test Plan
+<!-- How was this tested? What should reviewers verify? -->
+```
+
+## Steps
+
+1. Verify all changes are committed and tests pass (`/verify`)
+2. Analyze all commits on the branch since diverging from base
+3. Determine PR type from commits (use highest-impact type: breaking > feat > fix > others)
+4. Generate title in Conventional Commits format (max 72 chars)
+5. Generate body using template above
+6. Push branch to remote
+7. Create PR with `gh pr create`
 
 ## Implementation
+
 ```bash
-# Get current branch
 BRANCH=$(git branch --show-current)
 
-# Check for changes
-if [ -z "$(git status --porcelain)" ]; then
-  echo "No changes to commit"
-  exit 0
+# Ensure clean state
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Uncommitted changes. Run /commit first."
+  exit 1
 fi
 
-# Stage changes
-git add -A
-
-# Show what will be committed
-echo "📝 Changes to commit:"
-git status --short
-
-# Commit (message should be provided by Claude)
-# git commit -m "..."
-
-# Push
+# Push and create PR
 git push -u origin $BRANCH
-
-# Create PR
-gh pr create --fill
+gh pr create --title "<type>(<scope>): <description>" --body "<generated body>"
 ```
 
-## Notes
-- Claude will generate an appropriate commit message
-- PR description is auto-generated from commits
-- Use `--draft` flag for draft PRs
+## Rules
+
+- PR title MUST follow Conventional Commits format
+- PR title MUST be under 72 characters
+- Summary explains WHY, not just WHAT
+- Breaking changes: title MUST include `!` after type
+- Always run `/verify` before creating a PR
+- Prefer small, focused PRs

package/templates/manifest.json

@@ -42,6 +42,11 @@
       "added": "1.0.0",
       "description": "Project setup and dependency installation"
     },
+    "commands/commit.md": {
+      "version": "1.0.0",
+      "added": "1.1.0",
+      "description": "Semantic commit command"
+    },
     "templates/project-setup/CLAUDE_MD_TEMPLATE.md": {
       "version": "1.0.0",
       "added": "1.0.0",
@@ -82,6 +87,7 @@
           "commands/verify.md - Verify command",
           "commands/pr.md - PR command",
           "commands/setup.md - Setup command",
+          "commands/commit.md - Commit command",
           "templates/project-setup/* - All project setup templates"
         ],
         "changed": [],

package/templates/project-setup/CLAUDE_MD_TEMPLATE.md

@@ -31,6 +31,13 @@ Use this template as base for generating project-specific CLAUDE.md files.
 - Always run `{{VERIFY_COMMAND}}` before commit
 - Parallel work OK for: independent modules, test files, docs
 
+## Conventions
+- Commits: [Conventional Commits](https://conventionalcommits.org) — `<type>(<scope>): <subject>`
+- Types: feat, fix, docs, style, refactor, perf, test, chore, ci
+- Breaking changes: `!` suffix or `BREAKING CHANGE:` footer
+- PRs: same title format, structured body (Summary, Changes, Test Plan)
+- Versioning: feat → MINOR, fix → PATCH, breaking → MAJOR
+
 ## Architecture
 {{ARCHITECTURE_NOTES}}
 

package/templates/skills/claude-code-templates/SKILL.md

@@ -131,7 +131,12 @@ Location: `.claude/settings.json`
     "PostToolUse": [
       {
         "matcher": "Edit|Write",
-        "hooks": ["npm run lint --fix || true"]
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npm run lint --fix || true"
+          }
+        ]
       }
     ]
   }
@@ -168,7 +173,7 @@ npm run lint && npm test && npm run build
   "hooks": {
     "PostToolUse": [{
       "matcher": "Edit|Write",
-      "hooks": ["npx eslint --fix ${file} || true"]
+      "hooks": [{ "type": "command", "command": "npx eslint --fix ${file} || true" }]
     }]
   }
 }
@@ -200,7 +205,7 @@ ruff check . && mypy . && pytest
   "hooks": {
     "PostToolUse": [{
       "matcher": "Edit|Write",
-      "hooks": ["ruff format ${file} || true"]
+      "hooks": [{ "type": "command", "command": "ruff format ${file} || true" }]
     }]
   }
 }