claude-code-autoconfig 1.0.0

package/.claude/.mcp.json

@@ -0,0 +1,3 @@
+{
+  "mcpServers": {}
+}

package/.claude/commands/autoconfig.md

@@ -0,0 +1,176 @@
+<!-- @description The command you just ran. Analyzes your project and populates CLAUDE.md with real context. Re-run anytime your stack changes. -->
+
+# Autoconfig
+
+Analyze this project and configure Claude Code with real context.
+
+## Step 1: Detect Environment
+
+**Operating System:**
+Check the platform and note it for command syntax:
+- Windows → use `del`, `rmdir`, backslashes, `.cmd`/`.ps1` scripts
+- macOS/Linux → use `rm`, `mkdir -p`, forward slashes, `.sh` scripts
+
+Include this in CLAUDE.md so all commands use the correct syntax.
+
+## Step 2: Scan the Project
+
+Look for these indicators to understand the project:
+
+**Package/Config Files:**
+- `package.json` → Node.js, npm scripts, dependencies
+- `requirements.txt` / `pyproject.toml` / `setup.py` → Python
+- `Cargo.toml` → Rust
+- `go.mod` → Go
+- `Gemfile` → Ruby
+- `pom.xml` / `build.gradle` → Java
+- `*.csproj` / `*.sln` → .NET
+- `composer.json` → PHP
+
+**Framework Indicators:**
+- `next.config.*` / `app/` directory → Next.js
+- `vite.config.*` → Vite
+- `angular.json` → Angular
+- `svelte.config.*` → Svelte
+- `remix.config.*` → Remix
+- `nuxt.config.*` → Nuxt
+- `django` in imports → Django
+- `flask` in imports → Flask
+- `fastapi` in imports → FastAPI
+- `express` in dependencies → Express
+- `rails` / `Gemfile` with rails → Rails
+- `laravel` → Laravel
+
+**Testing Frameworks:**
+- `jest.config.*` / `@jest` in deps → Jest
+- `vitest.config.*` → Vitest
+- `pytest.ini` / `conftest.py` → Pytest
+- `*_test.go` files → Go testing
+- `*_spec.rb` files → RSpec
+- `cypress/` or `playwright/` → E2E testing
+
+**Infrastructure:**
+- `Dockerfile` / `docker-compose.*` → Docker
+- `*.tf` files → Terraform
+- `k8s/` or `kubernetes/` → Kubernetes
+- `.github/workflows/` → GitHub Actions
+- `serverless.yml` → Serverless Framework
+
+## Step 3: Populate CLAUDE.md
+
+Focus on what Claude Code actually needs to work effectively. Claude can explore the codebase itself — don't document what it can discover.
+
+**Wrap content in markers** so `/sync-claude-md` knows what's auto-generated:
+
+```markdown
+<!-- AUTO-GENERATED BY /autoconfig — Do not edit. Use .claude/feedback/ for corrections. -->
+
+# Project Name
+...content...
+
+<!-- END AUTO-GENERATED -->
+```
+
+**Always include:**
+- **Project name + one-liner**: What is this thing?
+- **Tech stack**: Runtime, framework, database, key services (so Claude uses correct patterns)
+- **Commands**: How to run, test, build, deploy — Claude needs these to execute tasks
+- **Non-obvious conventions**: Multi-schema databases, monorepo structure, unusual patterns Claude wouldn't infer
+
+**Include if relevant:**
+- **Deployment flow**: If non-standard or involves multiple steps
+- **Key architectural decisions**: Only if Claude would make wrong assumptions without them
+
+**Skip these — Claude can discover them:**
+- Detailed project structure trees (Claude can run `ls` or `tree`)
+- Exhaustive route/endpoint lists (Claude can grep)
+- File-by-file descriptions (Claude can read files)
+- Database model lists (Claude can read schema files)
+
+**Keep it tight.** A 30-line CLAUDE.md that hits the essentials beats a 200-line doc Claude has to parse every session.
+
+**Always end with:**
+```markdown
+## Team Feedback
+See `.claude/feedback/` for corrections and guidance from the team.
+```
+
+This pointer persists across autoconfig runs and directs Claude to team-maintained content.
+
+## Step 4: Create Rules Directory
+
+Create an empty `.claude/rules/` directory. Do not create any subdirectories or rule files.
+
+Rules are path-scoped context files that load automatically when Claude works on matching files. Effective rules require deep understanding of your codebase patterns, team conventions, and quality goals — they should be crafted intentionally, not auto-generated.
+
+## Step 5: Configure Settings
+
+Update `.claude/settings.json` using the official schema.
+
+### Deny Patterns (files Claude shouldn't read/write)
+
+Use `Read()` for blocking reads, `Edit()` for blocking writes:
+
+**Always deny (security):**
+```
+Read(./.env)
+Read(./.env.*)
+Read(./secrets/**)
+Edit(./.env)
+Edit(./.env.*)
+```
+
+**Often deny (generated/vendor):**
+```
+Edit(./node_modules/**)
+Edit(./dist/**)
+Edit(./.git/**)
+```
+
+### Allow Patterns (auto-approve without prompting)
+
+Use `Bash()` patterns with prefix matching:
+
+```
+Bash(npm run test:*)
+Bash(npm run lint:*)
+Bash(npm run build)
+```
+
+### Environment Variables
+
+Set session-level env vars:
+
+```json
+{
+  "env": {
+    "NODE_ENV": "development"
+  }
+}
+```
+
+**Keep it minimal** — only include patterns that actually exist in this project.
+
+## Guidelines
+
+- Replace ALL placeholder content with real values from THIS project
+- Delete sections that don't apply — no empty stubs
+- Optimize for Claude's efficiency, not human documentation
+- When uncertain, leave it out — Claude can ask or explore
+
+## Step 6: Update the Guide
+
+After populating CLAUDE.md, update the guide's file preview to show the actual content:
+
+1. Open `.claude/guide/autoconfig.guide.html`
+2. Find the `fileContents` JavaScript object (search for `'claude-md':`)
+3. Replace the `content` value with the actual CLAUDE.md content you just generated
+4. Use template literal syntax and escape any backticks in the content
+
+This ensures double-clicking CLAUDE.md in the guide shows the real generated content.
+
+## After Completion
+
+Once autoconfig is complete, prompt the user:
+
+**Run `/show-guide` for an interactive walkthrough of your new Claude Code project setup.**

package/.claude/commands/commit-and-push.md

@@ -0,0 +1,20 @@
+<!-- @description Stages all changes, generates a conventional commit message from the diff, commits, and pushes. One command, full workflow. -->
+
+# Commit and Push
+
+Stage all changes, create a commit with a good message, and push to the current branch.
+
+## Steps
+
+1. Stage all changes (`git add -A`)
+2. Generate a conventional commit message based on the diff
+3. Commit the changes
+4. Push to the current branch
+
+## Commit Message Format
+
+Use conventional commits: `type(scope): description`
+
+Types: feat, fix, docs, style, refactor, test, chore
+
+Keep the subject line under 50 chars. Add body if the change needs explanation.

package/.claude/commands/enable-retro.md

@@ -0,0 +1,54 @@
+<!-- @description (Experimental) Enable Claude to log tech debt it encounters into .claude/retro. -->
+
+# Enable Retro
+
+Enable the experimental Retro feature, which lets Claude log tech debt and improvement opportunities as structured story files.
+
+## What This Does
+
+1. Creates `.claude/retro/` directory with a README
+2. Creates `.claude/agents/create-retro-item.md` agent
+3. Adds Retro instructions to CLAUDE.md
+
+## Step 1: Create Retro Directory
+
+Create `.claude/retro/README.md` with:
+
+```markdown
+# Retro Items
+
+Tech debt and improvement opportunities identified during development.
+
+Each item is a structured story file with:
+- Problem description
+- Acceptance criteria
+- Suggested approach
+- Priority & effort sizing
+- Files involved
+
+## Working with Retro Items
+
+- "Fix retro #001" — Work on a specific item
+- "What's in the retro backlog?" — List pending items
+- Items are numbered sequentially (001, 002, etc.)
+```
+
+## Step 2: Create Retro Agent
+
+Create `.claude/agents/create-retro-item.md` with the standard retro item agent that:
+- Scans for highest existing ID
+- Creates numbered story files (001-title.md, 002-title.md)
+- Uses structured format: Problem, Acceptance Criteria, Approach, Priority, Effort, Files
+
+## Step 3: Update CLAUDE.md
+
+Add the following section to CLAUDE.md (before Team Feedback if present):
+
+```markdown
+## Retro
+After completing tasks, if you encountered friction, tech debt, or improvement opportunities worth revisiting, use the create-retro-item agent to log it in `.claude/retro/`. Use your judgment on what's worth capturing — not everything needs a retro item.
+```
+
+## Step 4: Confirm
+
+Output: "Retro enabled. Claude will now log tech debt to .claude/retro/ when appropriate."

package/.claude/commands/gls.md

@@ -0,0 +1,21 @@
+Get the latest screenshot(s) from the Screenshots folder and display them.
+
+Usage:
+- `/gls` - Get and display the most recent screenshot
+- `/gls-2` - Get and display the 2 most recent screenshots
+- `/gls-3` - Get and display the 3 most recent screenshots
+- `/gls-N` - Get and display the N most recent screenshots
+
+Screenshot directory: `C:\Users\andre\OneDrive\Pictures\Screenshots 1`
+
+Workflow:
+1. List all files in the screenshots directory sorted by modification time (newest first)
+2. If command is `/gls`, get the most recent screenshot (1 file)
+3. If command is `/gls-N` (e.g., `/gls-2`), get the N most recent screenshots
+4. Use the Read tool to display each screenshot
+5. Wait for the user to tell you what to do with the screenshot(s)
+
+Important:
+- Always use the Read tool to display screenshots (not Bash cat/echo)
+- Display screenshots in order from newest to oldest
+- After displaying, wait for user instructions - don't make assumptions about what they want done with the screenshots

package/.claude/commands/show-guide.md

@@ -0,0 +1,52 @@
+<!-- @description Opens the interactive guide in your browser. -->
+
+# Show Guide
+
+Open the interactive guide for Claude Code Autoconfig.
+
+## Step 1: Check for Changes
+
+Compare modification times of files in `.claude/` against `.claude/guide/autoconfig.guide.html`.
+
+If any files or folders in `.claude/` have a newer modification time than the guide HTML:
+1. Output: "Syncing guide with latest changes..."
+2. Proceed to Step 2
+
+If the guide is already current, skip to Step 3.
+
+## Step 2: Delta Sync
+
+For each file in `.claude/` that is newer than the guide HTML:
+
+1. Map the file to its `fileContents` key in the guide HTML:
+   - `CLAUDE.md` → `claude-md`
+   - `settings.json` → `settings`
+   - `commands/autoconfig.md` → `autoconfig`
+   - `commands/show-guide.md` → `guide-cmd`
+   - `commands/sync-claude-md.md` → `sync-claude-md`
+   - `commands/commit-and-push.md` → `commit-and-push`
+   - `commands/enable-retro.md` → `enable-retro`
+   - `commands/test.md` → `test`
+   - `feedback/FEEDBACK.md` → `feedback-template`
+   - `agents/create-retro-item.md` → `create-retro-item` (only if `.claude/retro/` exists)
+
+2. Read the current content of the changed file
+
+3. Update only that entry's `content` value in the `fileContents` object in the guide HTML
+
+4. After all deltas are applied, the guide HTML's modification time will naturally update
+
+## Step 3: Open Guide
+
+Open the guide in the default browser using the appropriate command for the OS:
+
+```bash
+# macOS
+open .claude/guide/autoconfig.guide.html
+
+# Linux
+xdg-open .claude/guide/autoconfig.guide.html
+
+# Windows
+start .claude/guide/autoconfig.guide.html
+```

package/.claude/commands/sync-claude-md.md

@@ -0,0 +1,60 @@
+<!-- @description Re-analyzes your project and updates CLAUDE.md to reflect current state. -->
+
+# Sync CLAUDE.md
+
+Re-analyze the project and update CLAUDE.md to reflect current state.
+
+Run this when your project has changed significantly:
+- Added a major framework or dependency
+- Changed npm scripts or build commands
+- Restructured the project
+- Switched databases or services
+
+## Step 1: Re-analyze the Project
+
+Scan for current project indicators:
+
+**Package/Config Files:**
+- `package.json` → dependencies, scripts
+- `requirements.txt` / `pyproject.toml` → Python deps
+- `Cargo.toml`, `go.mod`, `Gemfile`, etc.
+
+**Framework Indicators:**
+- Config files (next.config.*, vite.config.*, etc.)
+- Directory structure (app/, src/, etc.)
+
+**Infrastructure:**
+- Docker, Terraform, CI/CD configs
+
+## Step 2: Update CLAUDE.md
+
+CLAUDE.md uses markers to identify auto-generated content:
+
+```markdown
+<!-- AUTO-GENERATED BY /autoconfig — Do not edit. Use .claude/feedback/ for corrections. -->
+...content...
+<!-- END AUTO-GENERATED -->
+```
+
+**Only regenerate content between these markers.** If content exists outside the markers (user added it despite the warning), preserve it.
+
+Compare detected state with current CLAUDE.md and update:
+
+1. **Project name** — if changed
+2. **Tech stack** — new frameworks, languages, databases
+3. **Commands** — new/changed npm scripts, build commands
+4. **Conventions** — if project structure changed
+
+**Always include within markers:**
+- The `## Retro` section pointer
+- The `## Team Feedback` section pointer
+
+## Step 3: Confirm Changes
+
+Show the user what changed in CLAUDE.md before finishing.
+
+## Guidelines
+
+- **Respect markers**: Only regenerate content between AUTO-GENERATED markers
+- **Be conservative**: Only update sections that actually changed
+- **Keep it tight**: CLAUDE.md should stay concise

package/.claude/commands/test.md

@@ -0,0 +1,11 @@
+<!-- @description Runs your test suite. Auto-detects Jest, Vitest, Pytest, Go, RSpec, or falls back to npm test. -->
+
+# Run Tests
+
+Run tests for this project.
+
+**Scope:** $ARGUMENTS
+
+If no scope provided, run the full test suite. Otherwise run tests matching the scope (file, directory, or pattern).
+
+Detect the test command from project config (package.json scripts, pytest, go test, etc.) and execute it.

package/.claude/feedback/FEEDBACK.md

@@ -0,0 +1,28 @@
+<!-- @description Team-maintained corrections and guidance for Claude. Add notes here when Claude does something wrong — it learns for next time. This directory persists across /autoconfig runs. -->
+
+# Team Feedback
+
+Add corrections and guidance here when Claude does something wrong.
+Claude reads this directory and learns for next time.
+
+<!-- ╔══════════════════════════════════════════════════════════════════╗
+     ║                                                                  ║
+     ║   TEMPLATE BELOW — DELETE THIS BLOCK WHEN ADDING REAL FEEDBACK  ║
+     ║                                                                  ║
+     ╠══════════════════════════════════════════════════════════════════╣
+     ║                                                                  ║
+     ║   ## YYYY-MM-DD: Brief title                                     ║
+     ║                                                                  ║
+     ║   Describe what Claude did wrong and what to do instead.         ║
+     ║   Keep entries brief and actionable.                             ║
+     ║                                                                  ║
+     ║   Example:                                                       ║
+     ║                                                                  ║
+     ║   ## 2026-01-06: Don't use deprecated API                        ║
+     ║   Claude used `oldFunction()` instead of `newFunction()`.        ║
+     ║   Always use the v2 API for user endpoints.                      ║
+     ║                                                                  ║
+     ║   ## 2026-01-07: Test database naming                            ║
+     ║   Use `test_` prefix for test databases, not `dev_`.             ║
+     ║                                                                  ║
+     ╚══════════════════════════════════════════════════════════════════╝ -->