spec-rules-init — Coding Rules Generator

Extract project conventions and generate a unified coding-rules.md for use as a quality gate during implementation.

Language Rules

Auto-detect input language → output in the same language
Japanese input → Japanese output, use references/rules-template.ja.md
English input → English output, use references/rules-template.md
Explicit override takes priority (e.g., "in English", "日本語で")

Execution Flow

Step 0: Initial Context Check

BEFORE any interaction, execute these checks:

Check current directory:
```
pwd
ls -la
```

Detect convention files (parallel where possible):

# Convention files
ls CLAUDE.md src/CLAUDE.md AGENTS.md test/CLAUDE.md 2>/dev/null
ls -d .claude/ 2>/dev/null

# Config files
ls package.json go.mod requirements.txt Cargo.toml 2>/dev/null
ls .eslintrc* biome.json tsconfig.json .prettierrc* 2>/dev/null

Detect existing source code:

find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \) 2>/dev/null | head -30

Scan installed skills:

ls ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null

Check for existing coding-rules.md:

find . -name "coding-rules.md" -type f 2>/dev/null

Step 1: Rule Extraction from Convention Files

Read detected convention files and extract rules by category.

Detection targets (by priority):

| File | Content to Extract | Priority | |------|-------------------|----------| | CLAUDE.md (root) | Project-wide rules | High | | src/CLAUDE.md | Source-specific rules | High | | AGENTS.md | Agent-oriented rules | High | | .claude/ contents | Project settings | Medium | | package.json | lint/test script presence | Medium | | test/CLAUDE.md | Test-specific rules | Medium | | .eslintrc* / biome.json | Lint rules | Low | | tsconfig.json | TypeScript strict settings | Low | | .prettierrc* | Format settings | Low |

Extraction categories and keywords:

Testing Standards: "coverage", "test", "spec", "E2E", "カバレッジ", "テスト"
Code Quality: "lint", "typecheck", "strict", "import", "naming", "命名"
Error Handling: "try/catch", "Logger", "error", "throw", "例外"
Documentation: "JSDoc", "TSDoc", "@ApiProperty", "comment", "コメント"
Security: "secret", "password", "hash", "HTTPS", "ログに出力しない"
Git: "commit", "branch", "コミットメッセージ", "feature branch"

For each extracted rule, record:

Category (one of the 6 above)
Content (the rule text)
Severity: [MUST] (explicit requirement), [SHOULD] (recommended), [MAY] (optional)
Source file and line reference

Rules from CLAUDE.md / AGENTS.md are Priority 1 and default to [MUST].

Step 2: Codebase Analysis

If source code exists, analyze the codebase to detect implicit conventions. Skip this step entirely if no source files are found (new project).

2a. Directory structure analysis:

Scan directory tree (up to 3 levels deep)
Detect patterns: feature-based (modules/{feature}/), layer-based (controllers/, services/), co-located tests vs separate tests/ directory

2b. File naming convention detection:

Collect file names under src/ (or primary source directory)
Classify each name: kebab-case, camelCase, PascalCase, snake_case
If one pattern is 60%+ of files → propose as [MUST]
Minority patterns → propose as [SHOULD] for unification

2c. Library analysis:

Read dependency file (package.json, go.mod, requirements.txt, etc.)
Identify major libraries:
- Frameworks: NestJS, Next.js, Express, Fastify, Django, Flask, Gin, etc.
- Testing: Jest, Vitest, Playwright, pytest, etc.
- Validation: Zod, class-validator, Joi, etc.
- ORM: Prisma, TypeORM, Drizzle, SQLAlchemy, GORM, etc.
- Linters: ESLint, Biome, ruff, golint, etc.
Add library-specific best practice recommendations as [SHOULD] rules
- Example: Prisma detected → [SHOULD] Use Prisma Client for all DB access
- Example: Zod detected → [SHOULD] Use Zod for runtime validation

2d. Code pattern analysis (if code intelligence tools are available):

Import style: relative (./) vs path alias (@/)
Export style: named exports vs default exports
Error handling patterns in use

2e. Shared utility and library detection:

Scan the codebase for shared utility modules, helper functions, and internal libraries:
- Look for directories named utils/, helpers/, lib/, shared/, common/
- Identify frequently imported internal modules
Cross-reference with dependency file to identify commonly used libraries

Present a summary of detected shared utilities and libraries to the user:

Detected shared utilities and libraries:
  Internal: utils/logger.ts, lib/validation.ts, helpers/date.ts
  External: Zod (validation), Prisma (DB), date-fns (dates)

For each detected shared utility or library, generate a [SHOULD] rule:
- Example: [SHOULD] Use lib/validation.ts for input validation
- Example: [SHOULD] Use Zod for runtime validation
- Example: [SHOULD] Use utils/logger.ts instead of console.log
Include the detected list in the generated coding-rules.md under a "Shared Utilities" section

Codebase analysis results are Priority 2 and assigned [MUST] (for 60%+ majority patterns) or [SHOULD].

Step 3: Installed Skills Analysis

Scan installed skills for framework-specific best practices.

3a. Skill detection:

Scan ~/.claude/skills/ (global skills)
Scan .claude/skills/ (project skills)
Read each SKILL.md frontmatter description and body

3b. Framework match: Compare detected project tech stack (from Steps 1-2) with skill keywords:

| Project Tech | Matching Keywords | |-------------|-------------------| | Next.js | next, next.js, vercel, react, RSC, server component | | NestJS | nest, nestjs, express, fastify, typescript backend | | React | react, hooks, component, jsx, tsx | | Go | go, golang, goroutine | | Python | python, django, flask, fastapi |

3c. User confirmation (if matching skills found):

Use AskUserQuestion:

question: "The following installed skills were detected. Use them for rule extraction?" / "以下のインストール済みスキルが検出されました。ルール抽出に使用しますか？"
header: "Skills"
multiSelect: true
options:
  - "{skill-name} — {description} (Recommended)" / "{skill-name} — {説明}"

3d. Priority mapping:

Skill-derived rules are Priority 3 → [SHOULD] or [MAY]
If a skill rule contradicts Priority 1 or 2 rules → keep higher priority, show warning
Record source as Source: skill/{skill-name} in coding-rules.md

3e. No matching skills: If no matching skills are installed, optionally inform the user:

"Matching skills may be available on skills.sh for your tech stack.
Install and re-run to incorporate best practices."
/ "技術スタックに適合するスキルが skills.sh にある可能性があります。
インストール後に再実行すると、ベストプラクティスを取り込めます。"

Step 4: Interactive Dialogue

4a. Present extraction results:

Display detected rules summary by category:

Extraction Results:
  Testing Standards:    {n} rules
  Code Quality:         {n} rules
  Error Handling:       {n} rules
  Documentation:        {n} rules
  Security:             {n} rules
  Git:                  {n} rules
  Total:                {total} rules (Priority 1: {n}, Priority 2: {n}, Priority 3: {n})

If any category has 0 rules, highlight it for user attention.

4b. Output path selection (AskUserQuestion):

question: "Where to save coding-rules.md?" / "coding-rules.md の出力先は？"
header: "Output"
options:
  - "docs/coding-rules.md (Recommended)" / "docs/coding-rules.md（推奨）"
  - "docs/development/coding-rules.md"

If user selects "Other", accept any valid file path.

4c. Rule supplementation (AskUserQuestion):

For categories with missing or insufficient rules, ask targeted questions:

question: "Any additional testing rules?" / "テスト基準について追加ルールはありますか？"
header: "Testing"
options:
  - "Require 80%+ coverage (Recommended)" / "カバレッジ80%以上を必須にする"
  - "Specify E2E test patterns" / "E2Eテストパターンを指定する"
  - "No additions needed" / "追加不要"

question: "Commit message language?" / "コミットメッセージの言語は？"
header: "Git"
options:
  - "Japanese only" / "日本語のみ"
  - "English only" / "英語のみ"
  - "Conventional Commits (English)" / "Conventional Commits（英語）"

Suggest project-type-specific rules based on detected frameworks. Refer to the Project-Type Recommendations section in the reference template.

4d. review_rules.md generation (AskUserQuestion):

Skip if --with-review-rules (auto-generate) or --no-review-rules (skip). Otherwise ask:

question: "Generate review_rules.md alongside coding-rules.md?" /
          "coding-rules.md と一緒に review_rules.md も生成しますか？"
header: "Review Rules"
options:
  - "Yes, generate both (Recommended)" / "はい、両方生成する（推奨）"
  - "No, coding-rules.md only" / "いいえ、coding-rules.md のみ"

Step 5: Existing File Detection and Idempotency

If an existing coding-rules.md was found in Step 0:

Read the existing file
Also check for existing review_rules.md: find . -name "review_rules.md" -type f 2>/dev/null
Compare with newly extracted rules (additions, changes, removals)

Use AskUserQuestion:

question: "Existing coding-rules.md found. How to proceed?" / "既存の coding-rules.md が見つかりました。どうしますか？"
header: "Existing File"
options:
  - "Overwrite" / "上書きする"
  - "Merge differences" / "差分のみマージ"
  - "Cancel" / "キャンセル"

If "Cancel" → exit without changes

Step 6: Generate coding-rules.md

Load the appropriate reference template (based on Language Rules)
Fill in extracted rules by category
Apply severity tags: [MUST], [SHOULD], [MAY]
Add source attribution for each rule
Include the Sources summary table at the end
Create output directory if it does not exist
Write the file

Step 6.5: Generate review_rules.md (if opted in)

Skip this step if user chose "No" in Step 4d or --no-review-rules was specified.

Input: Generated coding-rules.md content + project structure info from Steps 0-2.

Procedure:

Load review template (references/review-template.md or references/review-template.ja.md per Language Rules)
Extract [MUST] and [SHOULD] rules from coding-rules.md, summarize by review category:
- Security → §1
- Type safety → §2
- Framework patterns → §3
- Code quality → §4
- Testing → §5
Generate review exclusion patterns from project structure:
- Auto-generated files: **/*.generated.*
- Lock files (based on detected package manager)
- Build artifacts: dist/**, build/**
- Specs: .specs/**
- ORM migrations (if ORM detected): e.g., prisma/migrations/**
Apply template review output guidelines (§7) as-is from template
Apply documentation update check (§8) as-is from template. The template instructs the reviewer to dynamically discover documentation files at review time rather than using a fixed list.
Write to the same directory as coding-rules.md: {output_directory}/review_rules.md

Step 7: Update AGENTS.md / CLAUDE.md References

After generating coding-rules.md, append a reference to project convention files.

Procedure:

Check if AGENTS.md exists at project root
Check if CLAUDE.md exists (skip if it is a symlink to AGENTS.md)

Use AskUserQuestion:

question: "Add reference to coding-rules.md in AGENTS.md / CLAUDE.md?" / "AGENTS.md / CLAUDE.md に coding-rules.md の参照を追記しますか？"
header: "Update"
options:
  - "Yes, add reference (Recommended)" / "はい、追記する（推奨）"
  - "No, skip" / "いいえ、スキップ"

If approved, append to the end of each file (or after an existing "Coding Rules" section):

English version:

## Coding Rules

Follow the coding rules in these files during implementation:
- [{coding_rules_path}]({coding_rules_path}) — Quality rules generated by spec-rules-init
- [{review_rules_path}]({review_rules_path}) — Review criteria for code review and second opinion

Japanese version:

## コーディングルール

実装時のコーディングルールは以下のファイルに従ってください:
- [{coding_rules_path}]({coding_rules_path}) — spec-rules-init で生成された品質ルール集
- [{review_rules_path}]({review_rules_path}) — コードレビュー・セカンドオピニオン用のレビュー基準

If review_rules.md was not generated, omit the review_rules line.

If neither file exists → skip with a warning message:

"Warning: No AGENTS.md or CLAUDE.md found. Skipping reference update."
/ "警告: AGENTS.md も CLAUDE.md も見つかりません。参照追記をスキップします。"

Step 8: spec-series Integration Notice

After completing generation, inform the user about integration with other spec-series skills:

"coding-rules.md has been generated. The following spec-series skills now reference it:
- spec-generator: Uses coding-rules.md as design constraints during the design phase
- spec-inspect: Checks [MUST] rules in Check 13 (Project Rule Compliance)
- spec-implement: Uses coding-rules.md as a quality gate during implementation"
/ "coding-rules.md を生成しました。以下の spec-series スキルが参照するようになっています:
- spec-generator: design フェーズで coding-rules.md を設計制約として使用
- spec-inspect: Check 13（プロジェクトルール準拠）で [MUST] ルールをチェック
- spec-implement: 実装時の品質ゲートとして coding-rules.md を使用"

If review_rules.md was also generated, add:

"review_rules.md has also been generated. It will be used by:
- spec-implement: Review gate references review_rules.md
- spec-workflow-init: Workflow review phases reference review_rules.md
- cmux-second-opinion: Uses review_rules.md for second opinion reviews
- GitHub Actions: Can be referenced by claude-review.yml"
/ "review_rules.md も生成されました。以下で活用されます:
- spec-implement: レビューゲートで review_rules.md を参照
- spec-workflow-init: ワークフローのレビュー Phase で参照
- cmux-second-opinion: セカンドオピニオン実行時に参照
- GitHub Actions: claude-review.yml で参照可能"

Options

| Option | Description | |--------|-------------| | --force | Overwrite existing coding-rules.md without confirmation | | --category <name> | Generate rules for a specific category only (e.g., --category testing) | | --with-review-rules | Also generate review_rules.md (skip confirmation) | | --no-review-rules | Do not generate review_rules.md (skip confirmation) |

Error Handling

Convention file unreadable: Warn and skip the file, continue with remaining files

"Warning: Could not read {filename}. Skipping."
/ "警告: {filename} を読み取れません。スキップします。"

Output directory does not exist: Create it automatically
```
mkdir -p {output_directory}
```

Write permission denied: Show error and suggest an alternative path

"Error: Cannot write to {path}. Try a different location."
/ "エラー: {path} に書き込めません。別のパスを指定してください。"

No convention files found: Fall back to dialogue-only mode

"No convention files (CLAUDE.md, AGENTS.md, etc.) found. Proceeding with dialogue-only mode."
/ "規約ファイル（CLAUDE.md, AGENTS.md等）が見つかりません。対話のみモードで進みます。"

Usage Examples

# Generate coding rules from project conventions
"Generate coding rules"
「コーディングルールを生成して」

# Create coding-rules.md with forced overwrite
"Create coding-rules.md --force"
「coding-rules.md を作成 --force」

# Extract rules for a specific category
"Extract project rules --category testing"
「テストルールだけ抽出して」

# After generating, re-run to update
"Update coding-rules.md"
「coding-rules.md を更新して」

Post-Completion Actions

After generating coding-rules.md, suggest next actions with AskUserQuestion:

question: "Generation complete. What's next?" / "生成完了。次のアクションは？"
header: "Next"
options:
  - "Generate specifications (spec-generator)" / "仕様書を生成する（spec-generator）"
  - "Set up development workflow (spec-workflow-init)" / "開発ワークフローを設定する（spec-workflow-init）"
  - "Done for now" / "完了"