claudenv 1.0.1

package/scaffold/.claude/skills/doc-generator/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: doc-generator
+description: Generates and updates project documentation including CLAUDE.md, rules, and hooks. Use when the user asks about documentation, project setup, CLAUDE.md, or when detecting that documentation is missing or outdated.
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(node:*)
+---
+
+# Documentation Generator Skill
+
+## When to use
+- User mentions documentation, CLAUDE.md, or project setup
+- User asks to configure Claude Code for their project
+- New files detected that change the tech stack (new framework, test runner, etc.)
+- After major refactoring that changes directory structure
+- When CLAUDE.md references files or directories that no longer exist
+
+## Process
+
+### 1. Detect Tech Stack
+Scan the project root for manifest files, framework configs, and tooling:
+
+@.claude/skills/doc-generator/templates/detection-patterns.md
+
+### 2. Cross-Reference Existing Documentation
+If CLAUDE.md already exists, read it and identify:
+- Outdated commands or directory references
+- Missing entries for new tools/dependencies
+- Stale @imports pointing to removed files
+
+### 3. Generate or Update
+- For new documentation: generate CLAUDE.md, _state.md, .claude/rules/code-style.md, .claude/rules/testing.md, .claude/rules/workflow.md
+- For updates: propose specific changes and wait for user approval
+- Always present generated content for review before writing
+- NEVER create .md files beyond the ones listed above unless the user explicitly asks
+
+### 4. Validate
+After writing, run the validation script:
+```
+bash .claude/skills/doc-generator/scripts/validate.sh
+```
+
+Fix any errors before completing.
+
+## Output Format
+Generated CLAUDE.md should follow this structure:
+- `# CLAUDE.md` heading
+- `## Project overview` — one-sentence description with stack
+- `## Commands` — all dev/build/test/lint commands
+- `## Architecture` — key directories with descriptions
+- `## Conventions` — @imports to code-style.md and testing.md
+- `## Workflow` — @import to workflow.md (Claude Code best practices)
+- `## Memory` — reference to _state.md for session persistence
+- `## Rules` — project-specific rules as bullet points
+
+Additionally generate:
+- `_state.md` — project state tracking (decisions, focus, known issues)
+- `.claude/rules/workflow.md` — Claude Code workflow best practices

package/scaffold/.claude/skills/doc-generator/scripts/validate.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# Documentation validation script for Claude Code hooks.
+# Exit 0 = success, Exit 2 = block action (sends stderr to Claude).
+# POSIX-compatible for macOS and Linux.
+set -euo pipefail
+
+ERRORS=0
+WARNINGS=0
+
+error() {
+  echo "ERROR: $1" >&2
+  ERRORS=$((ERRORS + 1))
+}
+
+warn() {
+  echo "WARN: $1" >&2
+  WARNINGS=$((WARNINGS + 1))
+}
+
+ok() {
+  echo "OK: $1"
+}
+
+# --- Required files ---
+
+if [ -f "CLAUDE.md" ] && [ -s "CLAUDE.md" ]; then
+  ok "CLAUDE.md exists and is non-empty"
+else
+  error "CLAUDE.md is missing or empty"
+fi
+
+# --- Required sections in CLAUDE.md ---
+
+if [ -f "CLAUDE.md" ]; then
+  for section in "## Commands" "## Architecture"; do
+    if grep -q "^${section}" CLAUDE.md 2>/dev/null; then
+      ok "CLAUDE.md has ${section}"
+    else
+      error "CLAUDE.md is missing required section: ${section}"
+    fi
+  done
+
+  # Check that ## Commands has at least one backtick-quoted command
+  # Use awk instead of head -n -1 for macOS compatibility
+  COMMANDS_SECTION=$(sed -n '/^## Commands/,/^## /p' CLAUDE.md | awk 'NR>1{print prev} {prev=$0}')
+  if echo "$COMMANDS_SECTION" | grep -q '`'; then
+    ok "## Commands section contains command examples"
+  else
+    warn "## Commands section has no inline code examples"
+  fi
+
+  # Check @import references
+  while IFS= read -r line; do
+    # Skip lines inside code blocks
+    case "$line" in
+      '```'*) continue ;;
+    esac
+    # Match bare @path lines (not emails, not inline)
+    if echo "$line" | grep -qE '^@[^@[:space:]]+$'; then
+      IMPORT_PATH=$(echo "$line" | sed 's/^@//')
+      # Resolve ~ to HOME
+      case "$IMPORT_PATH" in
+        '~/'*) IMPORT_PATH="${HOME}/${IMPORT_PATH#\~/}" ;;
+      esac
+      if [ -f "$IMPORT_PATH" ]; then
+        ok "@import ${IMPORT_PATH} resolves"
+      else
+        error "@import reference '${IMPORT_PATH}' does not resolve to a file"
+      fi
+    fi
+  done < CLAUDE.md
+fi
+
+# --- Optional structure checks ---
+
+if [ -d ".claude" ]; then
+  ok ".claude/ directory exists"
+else
+  warn ".claude/ directory not found"
+fi
+
+if [ -f ".claude/settings.json" ]; then
+  # Validate JSON syntax (requires python or node)
+  if command -v node >/dev/null 2>&1; then
+    if node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf-8'))" 2>/dev/null; then
+      ok ".claude/settings.json is valid JSON"
+    else
+      error ".claude/settings.json is not valid JSON"
+    fi
+  elif command -v python3 >/dev/null 2>&1; then
+    if python3 -c "import json; json.load(open('.claude/settings.json'))" 2>/dev/null; then
+      ok ".claude/settings.json is valid JSON"
+    else
+      error ".claude/settings.json is not valid JSON"
+    fi
+  fi
+fi
+
+# --- Summary ---
+
+echo ""
+echo "Validation complete: ${ERRORS} error(s), ${WARNINGS} warning(s)"
+
+if [ "$ERRORS" -gt 0 ]; then
+  exit 2
+fi
+
+exit 0

package/scaffold/.claude/skills/doc-generator/templates/detection-patterns.md

@@ -0,0 +1,76 @@
+# Tech Stack Detection Patterns
+
+Use these patterns to identify the project's tech stack by scanning for files.
+
+## Language / Runtime Detection (check manifest files first)
+
+| File | Language | Runtime |
+|------|----------|---------|
+| `package.json` | JavaScript/TypeScript | Node.js |
+| `pyproject.toml`, `setup.py`, `requirements.txt` | Python | Python |
+| `go.mod` | Go | Go |
+| `Cargo.toml` | Rust | Rust |
+| `Gemfile` | Ruby | Ruby |
+| `composer.json` | PHP | PHP |
+| `pom.xml`, `build.gradle`, `build.gradle.kts` | Java/Kotlin | JVM |
+| `*.csproj`, `*.sln` | C# | .NET |
+
+**TypeScript override**: If `tsconfig.json` exists alongside `package.json`, the language is TypeScript.
+
+## Framework Detection (check config files)
+
+| File | Framework |
+|------|-----------|
+| `next.config.js/mjs/ts` | Next.js |
+| `nuxt.config.ts/js` | Nuxt |
+| `vite.config.js/ts/mts` | Vite |
+| `svelte.config.js` | SvelteKit |
+| `astro.config.mjs/ts` | Astro |
+| `angular.json` | Angular |
+| `manage.py` | Django |
+| `config/routes.rb` | Rails |
+| `artisan` | Laravel |
+| `application.properties/yml` | Spring Boot |
+
+## Package Manager Detection (check lockfiles)
+
+| File | Package Manager |
+|------|----------------|
+| `package-lock.json` | npm |
+| `yarn.lock` | Yarn |
+| `pnpm-lock.yaml` | pnpm |
+| `bun.lockb`, `bun.lock` | Bun |
+| `poetry.lock` | Poetry |
+| `Pipfile.lock` | Pipenv |
+| `uv.lock` | uv |
+
+## Test Framework Detection
+
+| File | Framework |
+|------|-----------|
+| `vitest.config.*` | Vitest |
+| `jest.config.*` | Jest |
+| `playwright.config.*` | Playwright |
+| `cypress.config.*` | Cypress |
+| `pytest.ini`, `conftest.py` | pytest |
+| `.rspec` | RSpec |
+
+Also check dependencies in `package.json` or `pyproject.toml`.
+
+## CI/CD Detection
+
+| Path | System |
+|------|--------|
+| `.github/workflows/*.yml` | GitHub Actions |
+| `.gitlab-ci.yml` | GitLab CI |
+| `Jenkinsfile` | Jenkins |
+| `.circleci/config.yml` | CircleCI |
+
+## Monorepo Detection
+
+| File | Tool |
+|------|------|
+| `turbo.json` | Turborepo |
+| `nx.json` | Nx |
+| `lerna.json` | Lerna |
+| `pnpm-workspace.yaml` | pnpm workspaces |

package/src/constants.js

@@ -0,0 +1,237 @@
+/**
+ * Detection maps and constants for the documentation generator.
+ */
+
+// Maps manifest filenames to language/platform
+export const MANIFEST_MAP = {
+  'package.json': { language: 'javascript', runtime: 'node' },
+  'pyproject.toml': { language: 'python', runtime: 'python' },
+  'setup.py': { language: 'python', runtime: 'python' },
+  'requirements.txt': { language: 'python', runtime: 'python' },
+  'go.mod': { language: 'go', runtime: 'go' },
+  'Cargo.toml': { language: 'rust', runtime: 'rust' },
+  'Gemfile': { language: 'ruby', runtime: 'ruby' },
+  'composer.json': { language: 'php', runtime: 'php' },
+  'pom.xml': { language: 'java', runtime: 'jvm' },
+  'build.gradle': { language: 'java', runtime: 'jvm' },
+  'build.gradle.kts': { language: 'kotlin', runtime: 'jvm' },
+  '*.csproj': { language: 'csharp', runtime: 'dotnet' },
+  '*.sln': { language: 'csharp', runtime: 'dotnet' },
+};
+
+// TypeScript override — detected via tsconfig.json presence alongside package.json
+export const TYPESCRIPT_INDICATORS = ['tsconfig.json', 'tsconfig.base.json'];
+
+// Maps config filenames to frameworks
+export const FRAMEWORK_MAP = {
+  'next.config.js': 'next.js',
+  'next.config.mjs': 'next.js',
+  'next.config.ts': 'next.js',
+  'nuxt.config.ts': 'nuxt',
+  'nuxt.config.js': 'nuxt',
+  'vite.config.js': 'vite',
+  'vite.config.ts': 'vite',
+  'vite.config.mts': 'vite',
+  'svelte.config.js': 'sveltekit',
+  'astro.config.mjs': 'astro',
+  'astro.config.ts': 'astro',
+  'remix.config.js': 'remix',
+  'angular.json': 'angular',
+  'vue.config.js': 'vue-cli',
+  'gatsby-config.js': 'gatsby',
+  'gatsby-config.ts': 'gatsby',
+  'manage.py': 'django',
+  'config/routes.rb': 'rails',
+  'artisan': 'laravel',
+  'symfony.lock': 'symfony',
+  'application.properties': 'spring-boot',
+  'application.yml': 'spring-boot',
+};
+
+// Maps lockfiles to package managers
+export const PACKAGE_MANAGER_MAP = {
+  'package-lock.json': 'npm',
+  'yarn.lock': 'yarn',
+  'pnpm-lock.yaml': 'pnpm',
+  'bun.lockb': 'bun',
+  'bun.lock': 'bun',
+  'poetry.lock': 'poetry',
+  'Pipfile.lock': 'pipenv',
+  'uv.lock': 'uv',
+  'Gemfile.lock': 'bundler',
+  'composer.lock': 'composer',
+  'go.sum': 'go-modules',
+  'Cargo.lock': 'cargo',
+};
+
+// Maps test config files or dependency names to test frameworks
+export const TEST_FRAMEWORK_MAP = {
+  // Config file indicators
+  'jest.config.js': 'jest',
+  'jest.config.ts': 'jest',
+  'jest.config.mjs': 'jest',
+  'vitest.config.js': 'vitest',
+  'vitest.config.ts': 'vitest',
+  'vitest.config.mts': 'vitest',
+  '.mocharc.yml': 'mocha',
+  '.mocharc.json': 'mocha',
+  'cypress.config.js': 'cypress',
+  'cypress.config.ts': 'cypress',
+  'playwright.config.js': 'playwright',
+  'playwright.config.ts': 'playwright',
+  'pytest.ini': 'pytest',
+  'conftest.py': 'pytest',
+  'setup.cfg': 'pytest', // often contains [tool:pytest]
+  '.rspec': 'rspec',
+  'phpunit.xml': 'phpunit',
+  'phpunit.xml.dist': 'phpunit',
+};
+
+// Dependency names that indicate test frameworks (for package.json/pyproject.toml parsing)
+export const TEST_DEPENDENCY_MAP = {
+  jest: 'jest',
+  vitest: 'vitest',
+  mocha: 'mocha',
+  ava: 'ava',
+  tap: 'tap',
+  cypress: 'cypress',
+  playwright: 'playwright',
+  '@playwright/test': 'playwright',
+  pytest: 'pytest',
+  unittest: 'unittest',
+  nose2: 'nose2',
+};
+
+// CI/CD file patterns
+export const CI_PATTERNS = [
+  { glob: '.github/workflows/*.yml', name: 'github-actions' },
+  { glob: '.github/workflows/*.yaml', name: 'github-actions' },
+  { glob: '.gitlab-ci.yml', name: 'gitlab-ci' },
+  { glob: 'Jenkinsfile', name: 'jenkins' },
+  { glob: '.circleci/config.yml', name: 'circleci' },
+  { glob: 'bitbucket-pipelines.yml', name: 'bitbucket-pipelines' },
+  { glob: '.travis.yml', name: 'travis-ci' },
+  { glob: 'azure-pipelines.yml', name: 'azure-devops' },
+];
+
+// Linter config files
+export const LINTER_MAP = {
+  '.eslintrc': 'eslint',
+  '.eslintrc.js': 'eslint',
+  '.eslintrc.json': 'eslint',
+  '.eslintrc.yml': 'eslint',
+  'eslint.config.js': 'eslint',
+  'eslint.config.mjs': 'eslint',
+  'eslint.config.ts': 'eslint',
+  'biome.json': 'biome',
+  'biome.jsonc': 'biome',
+  '.pylintrc': 'pylint',
+  'ruff.toml': 'ruff',
+  '.rubocop.yml': 'rubocop',
+  '.golangci.yml': 'golangci-lint',
+  '.golangci.yaml': 'golangci-lint',
+  'clippy.toml': 'clippy',
+};
+
+// Formatter config files
+export const FORMATTER_MAP = {
+  '.prettierrc': 'prettier',
+  '.prettierrc.js': 'prettier',
+  '.prettierrc.json': 'prettier',
+  '.prettierrc.yml': 'prettier',
+  'prettier.config.js': 'prettier',
+  'prettier.config.mjs': 'prettier',
+  '.editorconfig': 'editorconfig',
+  'rustfmt.toml': 'rustfmt',
+  '.style.yapf': 'yapf',
+  'pyproject.toml': null, // checked separately for [tool.black] or [tool.ruff.format]
+};
+
+// Monorepo indicators
+export const MONOREPO_MAP = {
+  'turbo.json': 'turborepo',
+  'nx.json': 'nx',
+  'lerna.json': 'lerna',
+  'pnpm-workspace.yaml': 'pnpm-workspaces',
+  'rush.json': 'rush',
+};
+
+// Infrastructure files
+export const INFRA_MAP = {
+  'Dockerfile': 'docker',
+  'docker-compose.yml': 'docker-compose',
+  'docker-compose.yaml': 'docker-compose',
+  'terraform/': 'terraform',
+  '*.tf': 'terraform',
+  'cdk.json': 'aws-cdk',
+  'serverless.yml': 'serverless',
+  'serverless.ts': 'serverless',
+  'fly.toml': 'fly-io',
+  'vercel.json': 'vercel',
+  'netlify.toml': 'netlify',
+  'render.yaml': 'render',
+  'railway.json': 'railway',
+  'Procfile': 'heroku',
+};
+
+// Required sections in CLAUDE.md for validation
+export const REQUIRED_SECTIONS = ['## Commands', '## Architecture'];
+
+// Suggested commands by framework
+export const SUGGESTED_COMMANDS = {
+  'next.js': {
+    dev: '{pm} next dev',
+    build: '{pm} next build',
+    test: '{pm} vitest run',
+    lint: '{pm} next lint',
+  },
+  vite: {
+    dev: '{pm} vite',
+    build: '{pm} vite build',
+    test: '{pm} vitest run',
+  },
+  django: {
+    dev: 'python manage.py runserver',
+    test: 'python manage.py test',
+    migrate: 'python manage.py migrate',
+  },
+  rails: {
+    dev: 'bin/rails server',
+    test: 'bin/rails test',
+    migrate: 'bin/rails db:migrate',
+  },
+  'spring-boot': {
+    dev: './mvnw spring-boot:run',
+    build: './mvnw package',
+    test: './mvnw test',
+  },
+  laravel: {
+    dev: 'php artisan serve',
+    test: 'php artisan test',
+    migrate: 'php artisan migrate',
+  },
+  go: {
+    build: 'go build ./...',
+    test: 'go test ./...',
+    lint: 'golangci-lint run',
+  },
+  rust: {
+    build: 'cargo build',
+    test: 'cargo test',
+    lint: 'cargo clippy',
+  },
+};
+
+// Framework choices by language for cold-start prompts
+export const FRAMEWORKS_BY_LANGUAGE = {
+  typescript: ['Next.js', 'Vite + React', 'Vite + Vue', 'SvelteKit', 'Astro', 'Express', 'Fastify', 'NestJS', 'None'],
+  javascript: ['Next.js', 'Vite + React', 'Vite + Vue', 'Express', 'Fastify', 'None'],
+  python: ['Django', 'FastAPI', 'Flask', 'None'],
+  go: ['Gin', 'Echo', 'Fiber', 'Chi', 'Standard library', 'None'],
+  rust: ['Actix Web', 'Axum', 'Rocket', 'None'],
+  ruby: ['Rails', 'Sinatra', 'None'],
+  php: ['Laravel', 'Symfony', 'None'],
+  java: ['Spring Boot', 'Quarkus', 'Micronaut', 'None'],
+  kotlin: ['Spring Boot', 'Ktor', 'None'],
+  csharp: ['ASP.NET Core', 'Blazor', 'None'],
+};