feat: add Go engineering skills and linter

Author: lemon-mint

.gitignore

@@ -7,6 +7,7 @@
 *.dll
 *.so
 *.dylib
+/bin/
 
 # Test binary, built with `go test -c`
 *.test
@@ -27,6 +28,9 @@ go.work.sum
 # env file
 .env
 
+# Generated crawler output
+best_practices/
+
 # Editor/IDE
 # .idea/
 # .vscode/

AGENTS.md

@@ -0,0 +1,46 @@
+# AI Agent Guidelines (Engineering Best Practices)
+
+This repository provides provider-neutral engineering practices and deterministic Go analysis. As an AI agent working in this repository or producing changes, follow these rules.
+
+---
+
+## 1. Top 8 Golden Rules (Always Active)
+
+1. **Small & Hermetic Tests**: Keep unit tests fast (<100ms), single-process, deterministic, and isolated. **Never use `time.Sleep()`** for test synchronization.
+2. **Favor Real/Fakes over Mocks**: Use real objects or high-fidelity in-memory fakes. Only use mocks when unavoidable, and only verify **state-changing** method calls.
+3. **Flat Control Flow & Early Returns**: Minimize nesting depth. Use guard clauses and return early. Never use redundant `else` blocks after a terminal statement (`return`/`panic`/`throw`).
+4. **One Map Key, One Lookup**: Pay the map lookup / hashing cost exactly once. Never check existence and immediately index into the map again.
+5. **Positive Booleans**: Name flags and boolean functions with positive semantics (`isValid`, `isEnabled`) to avoid confusing double-negatives (`!isNotDisabled`).
+6. **Construct with Collaborators, Call with Work**: Pass persistent services/clients into constructors; pass per-request data into methods.
+7. **Let Code Speak for Itself**: Do not write comments that describe *what* the code does. Reserve comments strictly for explaining *why* (non-obvious trade-offs, external constraints).
+8. **Small & Focused Changes (Prefactoring)**: Refactor first to make the change easy, then add the new feature in a separate commit/PR.
+
+---
+
+## 2. On-Demand Skill Routing
+
+When performing specialized tasks, consult the corresponding Skill documentation:
+
+| Task / Context | Skill to Activate | Key Topics |
+| :--- | :--- | :--- |
+| **Writing / Fixing Tests** | [`testing-practices`](skills/testing-practices/SKILL.md) | Test sizing, Fake vs Mock, Flakiness, Narrow Assertions, SMURF |
+| **Refactoring & Clean Code** | [`code-health`](skills/code-health/SKILL.md) | Nesting reduction, Positive booleans, Functional core, Map lookup |
+| **API & Architecture Design** | [`api-design`](skills/api-design/SKILL.md) | Hard-to-misuse APIs, Collaborators vs Work, Premature DRY, Value objects |
+| **PR & Code Review** | [`code-review`](skills/code-review/SKILL.md) | Small PRs, Prefactoring, Commit context, Review etiquette |
+
+---
+
+## 3. Automated Tooling & Deterministic Enforcement (`gojgp`)
+
+Whenever writing or refactoring Go code:
+1. Run `go run cmd/gojgp/main.go check` (or `./bin/gojgp check`) to run unit tests and verify compliance with all Best Practices.
+2. Run `go run cmd/gojgp/main.go lint ./...` to check specific files/packages with the native Go AST analyzer.
+3. Fix any reported linter violations deterministically before completing your task.
+
+---
+
+## 4. Metadata Registry Reference
+
+For the full index of all 147 cataloged Best Practices, inspect:
+- [Category Definitions](registry/categories.json)
+- [Rules Registry Database](registry/rules_registry.json)

README.md

@@ -1 +1,59 @@
-# JustAGoodPractice
+# Go Engineering Practices
+
+A provider-neutral Agent Skills pack and Go AST linter for reliable Go code, tests, APIs, and reviews.
+
+## Install the skill
+
+Install the complete pack:
+
+```bash
+npx skills add gosuda/JustGoodPractices
+```
+
+Install only the primary Go skill:
+
+```bash
+npx skills add gosuda/JustGoodPractices --skill go-engineering-practices
+```
+
+The pack includes:
+
+- `go-engineering-practices`: end-to-end Go workflow and required lint gate.
+- `testing-practices`: deterministic tests, fakes, and synchronization.
+- `code-health`: control flow, naming, map access, and cleanup.
+- `api-design`: explicit APIs and dependency boundaries.
+- `code-review`: focused changes and actionable reviews.
+
+## Use the linter
+
+Go 1.25 or newer is required.
+
+```bash
+go install github.com/gosuda/JustGoodPractices/cmd/gojgp@latest
+gojgp lint ./...
+```
+
+Run tests and lint together:
+
+```bash
+gojgp check
+```
+
+Without installing the binary:
+
+```bash
+go run github.com/gosuda/JustGoodPractices/cmd/gojgp@latest lint ./...
+```
+
+## Develop
+
+```bash
+go test ./...
+go run ./cmd/gojgp lint ./...
+```
+
+All skill metadata follows the Agent Skills specification. Skill instructions are agent-neutral and use repository-relative paths only where appropriate.
+
+## License
+
+[MIT](LICENSE)

cmd/gojgp/main.go

@@ -0,0 +1,245 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+
+	"github.com/gosuda/JustGoodPractices/internal/analyzer"
+
+	"golang.org/x/tools/go/analysis/singlechecker"
+)
+
+type Priority string
+
+const (
+	P0 Priority = "P0_BLOCKER"
+	P1 Priority = "P1_HIGH"
+	P2 Priority = "P2_MEDIUM"
+	P3 Priority = "P3_INFO"
+)
+
+type AgentRule struct {
+	ID              string   `json:"id"`
+	Title           string   `json:"title"`
+	SourceFile      string   `json:"source_file"`
+	SourceURL       string   `json:"source_url"`
+	PublishedDate   string   `json:"published_date"`
+	LanguageScope   string   `json:"language_scope"`
+	CategoryID      string   `json:"category_id"`
+	Priority        Priority `json:"priority"`
+	Summary         string   `json:"summary"`
+	Rationale       string   `json:"rationale"`
+	EnforcingPrompt string   `json:"enforcing_prompt"`
+	Dos             []string `json:"dos"`
+	Donts           []string `json:"donts"`
+	LinterRuleID    string   `json:"linter_rule_id,omitempty"`
+}
+
+type Registry struct {
+	Version        string         `json:"version"`
+	TotalRules     int            `json:"total_rules"`
+	GeneratedAt    string         `json:"generated_at"`
+	PriorityCounts map[string]int `json:"priority_counts"`
+	Rules          []AgentRule    `json:"rules"`
+}
+
+func loadRegistry() (*Registry, error) {
+	data, err := os.ReadFile("registry/rules_registry.json")
+	if err != nil {
+		return nil, fmt.Errorf("failed to read registry: %w", err)
+	}
+	var reg Registry
+	if err := json.Unmarshal(data, &reg); err != nil {
+		return nil, fmt.Errorf("failed to parse registry: %w", err)
+	}
+	return &reg, nil
+}
+
+func main() {
+	if len(os.Args) < 2 {
+		printUsage()
+		os.Exit(1)
+	}
+
+	command := os.Args[1]
+
+	switch command {
+	case "lint":
+		handleLint()
+	case "check":
+		os.Exit(handleCheck())
+	case "prompt":
+		handlePrompt()
+	case "list":
+		handleList()
+	case "sync":
+		handleSync()
+	case "help", "-h", "--help":
+		printUsage()
+	default:
+		// Default to singlechecker passing remaining args
+		handleLint()
+	}
+}
+
+func printUsage() {
+	fmt.Println(`gojgp - Go engineering practice linter
+
+Usage:
+  gojgp <command> [arguments]
+
+Commands:
+  lint [flags] [packages]    Run the Go AST analyzer
+  check                     Run tests and the analyzer in the current module
+  prompt [flags]            Generate rule instructions
+  list                      List cataloged rules
+  sync                      Refresh the rule registry
+
+Examples:
+  gojgp lint ./...
+  gojgp check
+  gojgp prompt --priority=P0`)
+}
+
+func handleLint() {
+	// Shift os.Args so singlechecker receives standard package arguments
+	os.Args = append([]string{os.Args[0]}, os.Args[2:]...)
+	singlechecker.Main(analyzer.Analyzer)
+}
+
+type commandRunner func(stdout, stderr io.Writer, name string, args ...string) error
+
+func handleCheck() int {
+	return runCheck(os.Stdout, os.Stderr, executeCommand)
+}
+
+func runCheck(stdout, stderr io.Writer, run commandRunner) int {
+	status := 0
+
+	fmt.Fprintln(stdout, "=== [gojgp] 1. Running unit tests ===")
+	if err := run(stdout, stderr, "go", "test", "./..."); err != nil {
+		fmt.Fprintf(stderr, "FAIL: go test: %v\n", err)
+		status = 1
+	} else {
+		fmt.Fprintln(stdout, "PASS: unit tests")
+	}
+
+	fmt.Fprintln(stdout, "\n=== [gojgp] 2. Running Go AST linter ===")
+	if err := run(stdout, stderr, os.Args[0], "lint", "./..."); err != nil {
+		fmt.Fprintf(stderr, "FAIL: gojgp lint: %v\n", err)
+		status = 1
+	} else {
+		fmt.Fprintln(stdout, "PASS: gojgp lint")
+	}
+
+	return status
+}
+
+func executeCommand(stdout, stderr io.Writer, name string, args ...string) error {
+	command := exec.Command(name, args...)
+	command.Stdout = stdout
+	command.Stderr = stderr
+	return command.Run()
+}
+
+func handlePrompt() {
+	fs := flag.NewFlagSet("prompt", flag.ExitOnError)
+	catFlag := fs.String("category", "", "Filter by category ID (e.g. control_flow, test_doubles)")
+	priFlag := fs.String("priority", "", "Filter by minimum priority (e.g. P0, P1)")
+	scopeFlag := fs.String("scope", "", "Filter by language scope (e.g. go, python, universal)")
+	fs.Parse(os.Args[2:])
+
+	reg, err := loadRegistry()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error loading registry: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println("### AGENT ENFORCING INSTRUCTIONS (gojgp: Go Just Good Practices) ###")
+	fmt.Println()
+	fmt.Println("When writing, modifying, or reviewing code, strictly comply with the following golden rules:")
+	fmt.Println()
+
+	count := 0
+	for _, rule := range reg.Rules {
+		if rule.Priority == P3 {
+			continue
+		}
+		if *catFlag != "" && rule.CategoryID != *catFlag {
+			continue
+		}
+		if *priFlag != "" && !matchesPriority(rule.Priority, *priFlag) {
+			continue
+		}
+		if *scopeFlag != "" && rule.LanguageScope != *scopeFlag && rule.LanguageScope != "universal" {
+			continue
+		}
+
+		count++
+		fmt.Printf("#### [%s] %s\n", rule.Priority, rule.Title)
+		fmt.Printf("**Rule**: %s\n", rule.Summary)
+		fmt.Printf("**Instruction**: %s\n", rule.EnforcingPrompt)
+		if len(rule.Dos) > 0 {
+			fmt.Printf("- **DO**: %s\n", strings.Join(rule.Dos, "; "))
+		}
+		if len(rule.Donts) > 0 {
+			fmt.Printf("- **DON'T**: %s\n", strings.Join(rule.Donts, "; "))
+		}
+		fmt.Println()
+	}
+
+	if count == 0 {
+		fmt.Println("No matching rules found for specified filter.")
+	}
+}
+
+func matchesPriority(p Priority, filter string) bool {
+	filter = strings.ToUpper(filter)
+	switch filter {
+	case "P0":
+		return p == P0
+	case "P1":
+		return p == P0 || p == P1
+	case "P2":
+		return p == P0 || p == P1 || p == P2
+	default:
+		return string(p) == filter
+	}
+}
+
+func handleList() {
+	reg, err := loadRegistry()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error loading registry: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("Total Rules Cataloged in gojgp: %d\n\n", reg.TotalRules)
+
+	currentPriority := Priority("")
+	for _, rule := range reg.Rules {
+		if rule.Priority != currentPriority {
+			currentPriority = rule.Priority
+			fmt.Printf("\n[%s]\n", currentPriority)
+			fmt.Println(strings.Repeat("-", 60))
+		}
+		fmt.Printf("  • %-50s [%s] (%s)\n", rule.Title, rule.CategoryID, rule.LanguageScope)
+	}
+}
+
+func handleSync() {
+	fmt.Println("Running Rule Engine to sync database...")
+	cmd := exec.Command("go", "run", "cmd/rule-engine/main.go")
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	if err := cmd.Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "Rule engine sync failed: %v\n", err)
+		os.Exit(1)
+	}
+	fmt.Println("✓ Rules database synced successfully.")
+}