claude-code-starter 0.12.2 → 0.14.0

package/README.md

@@ -48,9 +48,9 @@ Automatically detects and configures for:
 | -------------- | ------------------------------------------------------------------- |
 | **Languages**  | TypeScript, JavaScript, Python, Go, Rust, Java, Ruby, Swift, Kotlin |
 | **Frameworks** | Next.js, React, Vue, Svelte, FastAPI, Django, NestJS, Express, etc. |
-| **Tools**      | npm, yarn, pnpm, bun, pip, cargo, go modules                       |
+| **Tools**      | npm, yarn, pnpm, bun, pip, cargo, go modules                        |
 | **Testing**    | Jest, Vitest, Pytest, Go test, Rust test                            |
-| **Linting**    | ESLint, Biome, Ruff, Pylint                                        |
+| **Linting**    | ESLint, Biome, Ruff, Pylint                                         |
 
 ## Generated Configurations
 
@@ -64,13 +64,13 @@ Based on your stack, creates:
 
 ## Commands
 
-| Command           | Description                              |
-| ----------------- | ---------------------------------------- |
-| `/task <desc>`    | Start a new task                         |
-| `/status`         | Show current task                        |
-| `/done`           | Mark task complete                       |
-| `/analyze <area>` | Deep dive into code                      |
-| `/code-review`    | Review changes for quality and security  |
+| Command           | Description                             |
+| ----------------- | --------------------------------------- |
+| `/task <desc>`    | Start a new task                        |
+| `/status`         | Show current task                       |
+| `/done`           | Mark task complete                      |
+| `/analyze <area>` | Deep dive into code                     |
+| `/code-review`    | Review changes for quality and security |
 
 ## CLI Options
 
@@ -179,41 +179,41 @@ flowchart LR
 
 ### Artifact Generation
 
-| Artifact Type | Generation Method |
-|---------------|-------------------|
-| **CLAUDE.md** | Claude CLI deep analysis of your actual source files |
-| **settings.json** | Generated with safe default permissions |
-| **Skills** | Core skills + framework-specific patterns (if detected) |
-| **Agents** | Code reviewer and test writer agents |
-| **Rules** | Language-specific conventions + general code style |
-| **Commands** | Task workflow commands (/task, /status, /done, /analyze) |
+| Artifact Type     | Generation Method                                        |
+| ----------------- | -------------------------------------------------------- |
+| **CLAUDE.md**     | Claude CLI deep analysis of your actual source files     |
+| **settings.json** | Generated with safe default permissions                  |
+| **Skills**        | Core skills + framework-specific patterns (if detected)  |
+| **Agents**        | Code reviewer and test writer agents                     |
+| **Rules**         | Language-specific conventions + general code style       |
+| **Commands**      | Task workflow commands (/task, /status, /done, /analyze) |
 
 ### Conflict Resolution
 
 When running on an existing project with `.claude/` configuration:
 
-| Scenario | Behavior |
-|----------|----------|
-| **New file** | Created |
-| **Existing file** | Skipped (preserved) |
-| **With `-f` flag** | Overwritten |
-| **state/task.md** | Always preserved |
+| Scenario           | Behavior            |
+| ------------------ | ------------------- |
+| **New file**       | Created             |
+| **Existing file**  | Skipped (preserved) |
+| **With `-f` flag** | Overwritten         |
+| **state/task.md**  | Always preserved    |
 
 ### Framework-Specific Patterns
 
 When a framework is detected, additional skills are generated:
 
-| Framework | Generated Skill |
-|-----------|-----------------|
-| Next.js | `nextjs-patterns.md` - App Router, Server Components |
-| React | `react-components.md` - Hooks, component patterns |
-| FastAPI | `fastapi-patterns.md` - Async endpoints, Pydantic |
-| NestJS | `nestjs-patterns.md` - Modules, decorators, DI |
-| SwiftUI | `swiftui-patterns.md` - Declarative UI patterns |
-| UIKit | `uikit-patterns.md` - View controller patterns |
-| Vapor | `vapor-patterns.md` - Server-side Swift |
-| Jetpack Compose | `compose-patterns.md` - Compose UI patterns |
-| Android Views | `android-views-patterns.md` - XML views |
+| Framework       | Generated Skill                                      |
+| --------------- | ---------------------------------------------------- |
+| Next.js         | `nextjs-patterns.md` - App Router, Server Components |
+| React           | `react-components.md` - Hooks, component patterns    |
+| FastAPI         | `fastapi-patterns.md` - Async endpoints, Pydantic    |
+| NestJS          | `nestjs-patterns.md` - Modules, decorators, DI       |
+| SwiftUI         | `swiftui-patterns.md` - Declarative UI patterns      |
+| UIKit           | `uikit-patterns.md` - View controller patterns       |
+| Vapor           | `vapor-patterns.md` - Server-side Swift              |
+| Jetpack Compose | `compose-patterns.md` - Compose UI patterns          |
+| Android Views   | `android-views-patterns.md` - XML views              |
 
 ## Requirements
 
@@ -228,14 +228,14 @@ This project uses GitHub Actions for continuous integration and automated releas
 
 Every pull request targeting `main` runs:
 
-| Check | Description |
-|-------|-------------|
-| **Lint** | Biome lint and format validation |
-| **Type Check** | TypeScript compilation check |
-| **Unit Tests** | Full test suite with Bun |
+| Check            | Description                                        |
+| ---------------- | -------------------------------------------------- |
+| **Lint**         | Biome lint and format validation                   |
+| **Type Check**   | TypeScript compilation check                       |
+| **Unit Tests**   | Full test suite with Bun                           |
 | **Code Quality** | Checks for console.log, `any` types, skipped tests |
-| **Build** | Verifies package builds successfully |
-| **Package Size** | Reports bundle size (warns if > 500KB) |
+| **Build**        | Verifies package builds successfully               |
+| **Package Size** | Reports bundle size (warns if > 500KB)             |
 
 ### Automated Releases (`.github/workflows/release.yml`)
 
@@ -252,24 +252,25 @@ When code is merged to `main`, semantic-release automatically:
 
 Use these prefixes for automatic versioning:
 
-| Prefix | Version Bump | Example |
-|--------|--------------|---------|
-| `feat:` | Minor | `feat: add dark mode support` |
-| `fix:` | Patch | `fix: resolve memory leak` |
-| `perf:` | Patch | `perf: optimize image loading` |
-| `BREAKING CHANGE:` | Major | `feat!: redesign API` |
-| `docs:`, `chore:`, `ci:` | No release | `docs: update README` |
+| Prefix                   | Version Bump | Example                        |
+| ------------------------ | ------------ | ------------------------------ |
+| `feat:`                  | Minor        | `feat: add dark mode support`  |
+| `fix:`                   | Patch        | `fix: resolve memory leak`     |
+| `perf:`                  | Patch        | `perf: optimize image loading` |
+| `BREAKING CHANGE:`       | Major        | `feat!: redesign API`          |
+| `docs:`, `chore:`, `ci:` | No release   | `docs: update README`          |
 
 ### Required Secrets
 
 Configure these in your GitHub repository settings:
 
-| Secret | Description | Required For |
-|--------|-------------|--------------|
-| `NPM_TOKEN` | npm authentication token | Publishing to npm |
-| `GITHUB_TOKEN` | Auto-provided by GitHub | Creating releases |
+| Secret         | Description              | Required For      |
+| -------------- | ------------------------ | ----------------- |
+| `NPM_TOKEN`    | npm authentication token | Publishing to npm |
+| `GITHUB_TOKEN` | Auto-provided by GitHub  | Creating releases |
 
 To create an npm token:
+
 1. Go to [npmjs.com](https://npmjs.com) -> Access Tokens
 2. Generate a new "Automation" token
 3. Add it as `NPM_TOKEN` in GitHub repo -> Settings -> Secrets
@@ -298,4 +299,4 @@ bun run typecheck
 
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE) for details.

package/dist/cli.js

@@ -5,6 +5,7 @@ import { execSync, spawn } from "child_process";
 import fs3 from "fs";
 import path3 from "path";
 import { fileURLToPath } from "url";
+import ora from "ora";
 import pc from "picocolors";
 import prompts from "prompts";
 
@@ -664,7 +665,8 @@ ${templateVars}
 7. Execute Phase 5 - generate agent files
 8. Execute Phase 6 - generate rule files
 9. Execute Phase 7 - generate command files
-10. Output a brief summary of what was generated and any gaps found
+10. Run the Anti-Redundancy Checklist one final time across ALL generated files \u2014 if any convention is restated or any rule lacks a \`paths:\` filter, fix it before proceeding
+11. Output a brief summary of what was generated and any gaps found
 
 Do NOT output file contents to stdout. Write all files to disk using the Write tool.
 Generate ALL files in a single pass \u2014 do not stop after CLAUDE.md.`;
@@ -806,6 +808,39 @@ something, omit that section entirely - do not fill in generic boilerplate.
 
 ---
 
+## Artifact Architecture
+
+Understanding the context cost of each artifact type is critical. Artifacts load at different
+frequencies, so place information where it costs the least while remaining accessible:
+
+| Artifact | When Loaded | Context Cost |
+|----------|-------------|--------------|
+| CLAUDE.md | Every turn | Highest \u2014 keep concise |
+| Rule without \`paths:\` | Every session | High \u2014 avoid generating these |
+| Rule with \`paths:\` | When matching files are open | Medium \u2014 use sparingly |
+| Skill / Command | On-demand (user invokes) | Low |
+| Agent | Spawned in subprocess | Zero main-context cost |
+
+### Placement Rules
+
+1. **CLAUDE.md is the single source of truth for conventions.** All naming, style, commit format, and project rules live here and ONLY here.
+2. **NEVER generate rules without \`paths:\` filters.** A rule without \`paths:\` loads every session and competes with CLAUDE.md for context. All general style information belongs in CLAUDE.md.
+3. **Rules must be concise, non-redundant supplements.** A language rule (e.g., \`typescript.md\` with \`paths: ["**/*.ts"]\`) should ONLY contain language-specific gotchas (compiler flags, import quirks, tooling-specific settings) that don't belong in CLAUDE.md.
+4. **Skills are for rich on-demand methodology.** Write "Follow conventions in CLAUDE.md" instead of restating conventions. Focus skills on HOW (methodology), not WHAT (conventions).
+5. **Agents have zero main-context cost.** Put detailed checklists and review criteria in agent files \u2014 they run in subprocesses and don't consume the user's context window.
+6. **Each piece of information must live in exactly ONE place.** If it's in CLAUDE.md, don't repeat it in rules, skills, or commands.
+
+### Anti-Redundancy Checklist
+
+Before writing EACH artifact, verify:
+- [ ] No convention from CLAUDE.md is restated (commit format, naming, import order, etc.)
+- [ ] No content from another artifact is duplicated
+- [ ] Cross-references are used instead of copies (e.g., "Follow conventions in CLAUDE.md")
+- [ ] All rules have a \`paths:\` filter
+- [ ] Information is placed at the lowest-cost tier that still makes it accessible
+
+---
+
 ## Phase 1: Discovery (Read Before You Write)
 
 Perform these analysis steps IN ORDER. Do not skip any step. Do not start writing
@@ -980,6 +1015,27 @@ Written for an AI assistant that needs to understand PURPOSE to make good decisi
 
 {What NOT to do based on codebase conventions}
 
+> **This Code Conventions section is the single source of truth.**
+> Rules and skills cross-reference this section \u2014 they do not repeat it.
+
+## Skills
+
+{List each generated skill with a one-line description}
+
+| Skill | Purpose |
+|-------|---------|
+| \`pattern-discovery\` | Discover and document codebase patterns |
+| ... | ... |
+
+## Agents
+
+{List each generated agent with a one-line description}
+
+| Agent | Purpose |
+|-------|---------|
+| \`code-reviewer\` | Reviews code for quality and security |
+| \`test-writer\` | Generates tests for code |
+
 ## Testing
 
 ### Running Tests
@@ -1022,19 +1078,30 @@ Before writing the CLAUDE.md, verify:
 
 - [ ] Every section contains PROJECT-SPECIFIC information (not generic boilerplate)
 - [ ] File paths referenced actually exist in the project
+- [ ] File references use \`path/to/file.ts (functionName)\` format, not line numbers
 - [ ] Commands listed are verified from package.json scripts or equivalent
 - [ ] Code conventions were observed from ACTUAL source files
 - [ ] The "Gotchas" section contains genuinely useful, non-obvious information
 - [ ] An AI reading this CLAUDE.md could add a new feature following existing patterns
 - [ ] Sections without real content have been omitted entirely
 
+### Cross-Artifact Deduplication Check
+
+Before writing ANY artifact (rule, skill, agent, command), verify:
+- [ ] No conventions from CLAUDE.md are restated (naming, commit format, import order, style)
+- [ ] No commit format description is restated outside CLAUDE.md
+- [ ] No content from one artifact is duplicated in another
+- [ ] Cross-references are used instead of copies (e.g., "Follow conventions in CLAUDE.md")
+- [ ] Every rule file has a \`paths:\` filter \u2014 no unfiltered rules
+- [ ] Single-language rules are justified (add genuine value beyond CLAUDE.md)
+
 ---
 
 ## Important Guidelines
 
 1. **Be specific, not generic.** "Uses React with hooks" is useless. "Uses React 18 with Server Components via Next.js App Router, client components in src/components/client/ with 'use client' directive" is useful.
 
-2. **Reference real files.** Every pattern should reference an actual file as an example. Use \`path/to/file.ts:lineNumber\` format.
+2. **Reference real files.** Every pattern should reference an actual file as an example. Use \`path/to/file.ts (functionName)\` format \u2014 NOT line numbers, which become stale as code changes.
 
 3. **Prioritize actionable information.** Focus on what helps an AI write correct code: where to put new code, what patterns to follow, what to avoid, how to test.
 
@@ -1053,6 +1120,12 @@ YAML frontmatter with \`name\`, \`description\`, and optionally \`globs\` for fi
 **Tailor ALL skills to this specific project** \u2014 use the actual test command, lint command,
 file patterns, and conventions discovered during Phase 1.
 
+### Skill Content Rules
+
+1. **Cross-reference, don't copy** \u2014 write "Follow conventions in CLAUDE.md" instead of restating naming, style, or commit conventions. Skills focus on methodology (HOW to do something), not conventions (WHAT the conventions are).
+2. **Use stable references** \u2014 reference code as \`path/to/file.ts (functionName)\`, not line numbers which become stale.
+3. **No convention duplication** \u2014 if CLAUDE.md already documents commit format, import order, or naming rules, the skill must not repeat them.
+
 ### 4.1 Core Skills (ALWAYS generate all 8)
 
 **\`.claude/skills/pattern-discovery.md\`**
@@ -1078,7 +1151,7 @@ file patterns, and conventions discovered during Phase 1.
 **\`.claude/skills/commit-hygiene.md\`**
 - Name: commit-hygiene
 - Description: Atomic commits, conventional format, size thresholds
-- Content: Size thresholds (\xB1300 lines per commit), when-to-commit triggers, conventional commit format. If the project uses commitlint or similar, reference its config.
+- Content: Size thresholds (\xB1300 lines per commit), when-to-commit triggers. For commit format, write "Follow the commit conventions in CLAUDE.md" \u2014 do NOT restate the format here. If the project uses commitlint or similar, reference its config.
 
 **\`.claude/skills/code-deduplication.md\`**
 - Name: code-deduplication
@@ -1189,19 +1262,21 @@ var RULES_PROMPT = `---
 
 Write rule files to \`.claude/rules/\`. Each rule file needs YAML frontmatter.
 
-### Always Generate:
+### Important: No Unfiltered Rules
 
-**\`.claude/rules/code-style.md\`** (no \`paths\` \u2014 applies to all files)
+Do NOT generate a \`code-style.md\` rule or any rule without a \`paths:\` filter. General style information (formatter, linter commands, comment style, error handling, commit conventions, import ordering) belongs in CLAUDE.md \u2014 not in a rule that loads every session and duplicates it.
 
-Content based on what was discovered in Phase 1:
-- Which formatter/linter to use and how (include actual commands)
-- Comment style: "why" not "what", keep comments current
-- Error handling patterns specific to this project
-- Git commit message conventions (conventional commits if commitlint is configured)
-- Import ordering conventions found in the codebase
+NEVER generate rules without \`paths:\` filters. Every rule must target specific file types.
 
 ### Conditional Rules (generate ONLY if the language was detected):
 
+**Constraints for all conditional rules:**
+- Every rule MUST have a \`paths:\` filter targeting language-specific file extensions
+- Keep rules concise: 5-15 lines of content maximum
+- Rules must NOT repeat conventions already in CLAUDE.md (naming, style, commit format, import order)
+- For single-language projects: only generate a language rule if it adds genuine value beyond CLAUDE.md (compiler flags, import quirks, tooling-specific gotchas)
+- Focus on: compiler/interpreter settings, language-specific gotchas, tooling-specific configuration \u2014 not general naming or style
+
 **TypeScript detected** \u2192 Write \`.claude/rules/typescript.md\`
 \`\`\`yaml
 ---
@@ -1297,10 +1372,11 @@ allowed-tools: ["Read", "Glob", "Grep", "Bash(git diff)", "Bash(git diff --cache
 description: "Review code changes for quality and security"
 ---
 \`\`\`
-Body: Review staged and unstaged changes. Check for: naming consistency,
-error handling, security issues, test coverage, import organization,
-code duplication. Run the project's linter. Provide a summary with
-severity levels (critical, warning, suggestion).`;
+Body: This command delegates to the code-reviewer agent for thorough review.
+1. Run \`git diff\` and \`git diff --cached\` to identify staged and unstaged changes
+2. Spawn the \`code-reviewer\` agent to perform the full review
+3. If the agent is unavailable, perform a lightweight review: run the linter and check for obvious issues
+Do NOT duplicate the code-reviewer agent's checklist here \u2014 the agent has the full review criteria.`;
 
 // src/cli.ts
 var __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
@@ -1828,6 +1904,14 @@ function runClaudeAnalysis(projectDir, projectInfo) {
       pc.gray("Claude will read your codebase and generate all .claude/ configuration files")
     );
     console.log();
+    const spinner = ora({
+      text: "Claude is analyzing your project...",
+      spinner: {
+        interval: 200,
+        frames: ["\xB7", "\u2722", "\u2733", "\u2736", "\u2733", "\u2722"]
+      },
+      color: "cyan"
+    }).start();
     const child = spawn(
       "claude",
       [
@@ -1845,22 +1929,21 @@ function runClaudeAnalysis(projectDir, projectInfo) {
       ],
       {
         cwd: projectDir,
-        stdio: ["pipe", "inherit", "inherit"]
+        stdio: ["pipe", "pipe", "pipe"]
       }
     );
     child.stdin.write(prompt);
     child.stdin.end();
     child.on("error", (err) => {
-      console.error(pc.red(`Failed to launch Claude CLI: ${err.message}`));
+      spinner.fail(`Failed to launch Claude CLI: ${err.message}`);
       resolve(false);
     });
     child.on("close", (code) => {
       if (code === 0) {
-        console.log();
-        console.log(pc.green("Claude analysis complete!"));
+        spinner.succeed("Claude analysis complete!");
         resolve(true);
       } else {
-        console.error(pc.red(`Claude exited with code ${code}`));
+        spinner.fail(`Claude exited with code ${code}`);
         resolve(false);
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-starter",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "A lightweight starter kit for AI-assisted development with Claude Code",
   "keywords": [
     "claude",
@@ -41,6 +41,7 @@
     "prepublishOnly": "bun run build && bun run test"
   },
   "dependencies": {
+    "ora": "^9.3.0",
     "picocolors": "^1.1.1",
     "prompts": "^2.4.2"
   },