devflow-kit 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to DevFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+---
+
+## [1.2.0] - 2026-03-05
+
+### Added
+- **Polyglot language skills** — Go, Java, Python, and Rust skill plugins with comprehensive patterns
+  - Go: error handling, interfaces, concurrency (errgroup, worker pools, fan-out/fan-in)
+  - Java: records, sealed classes, streams, composition over inheritance
+  - Python: type hints, protocols, dataclasses, async patterns
+  - Rust: ownership, error handling (`thiserror`/`anyhow`), type system, concurrency
+  - Skills: 26 → 30, Plugins: 9 → 17
+- **Optional plugin architecture** — Language/ecosystem plugins (`optional: true`) not installed by default
+  - Install selectively: `devflow init --plugin=go --plugin=python`
+  - Existing skills (typescript, react, accessibility, frontend-design) moved to optional plugins
+  - `devflow-core-skills` no longer bundles language-specific skills
+- **Conditional language reviews** in `/code-review` command
+  - Spawns language-specific Reviewer agents when matching files are in the diff
+  - Skill availability check: skips review if optional plugin not installed
+- **Dynamic skill loading in Coder agent** — Reads language skills at runtime based on DOMAIN hint instead of static frontmatter dependencies
+
+### Changed
+- **`devflow-core-skills`** no longer includes typescript, react, accessibility, or frontend-design skills (moved to optional plugins)
+- **Coder agent** frontmatter trimmed from 14 skills to 6 core skills; language skills loaded dynamically
+
+### Fixed
+- **Deprecated `grpc.WithInsecure()`** in Go concurrency examples → replaced with `grpc.WithTransportCredentials(insecure.NewCredentials())`
+- **Deprecated `datetime.utcnow`** in Python dataclass example → replaced with `datetime.now(timezone.utc)`
+- **SQL injection** in Python async streaming example → replaced raw query with parameterized query
+- **Deprecated `<Context.Provider>`** in React examples → replaced with `<Context>` (React 19+)
+- **Deprecated `useRef<T>()`** without argument in React patterns → replaced with `useRef<T | undefined>(undefined)` (React 19+)
+- **Non-portable `NodeJS.Timeout`** in TypeScript debounce/throttle → replaced with `ReturnType<typeof setTimeout>`
+- **Unsafe `Function` type** in TypeScript type guard → replaced with `(...args: unknown[]) => unknown`
+- **Go test file exclusion** removed from go skill activation (test files are valid Go code)
+
+---
+
 ## [1.1.0] - 2026-03-04
 
 ### Added
@@ -749,6 +787,7 @@ devflow init
 
 ---
 
+[1.2.0]: https://github.com/dean0x/devflow/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/dean0x/devflow/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/dean0x/devflow/compare/v0.9.0...v1.0.0
 [0.9.0]: https://github.com/dean0x/devflow/releases/tag/v0.9.0

package/README.md

@@ -24,7 +24,7 @@ DevFlow adds structured commands that handle the full lifecycle: specify feature
 - **Full-lifecycle implementation** — spec, explore, plan, code, validate, refine in one command
 - **Automatic session memory** — survives restarts, `/clear`, and context compaction
 - **Parallel debugging** — competing hypotheses investigated simultaneously
-- **26 quality skills** — 12 auto-activating, plus specialized review and agent skills
+- **30 quality skills** — 8 auto-activating core, 8 optional language/ecosystem, plus specialized review and agent skills
 
 ## Quick Start
 
@@ -81,7 +81,7 @@ Creates a PR when complete.
 Multi-perspective code review with specialized reviewers:
 
 - **Core**: Security, Architecture, Performance, Quality
-- **Conditional** (activated when relevant): TypeScript, React, Accessibility, Database, Dependencies, Documentation
+- **Conditional** (activated when relevant): TypeScript, React, Accessibility, Go, Python, Java, Rust, Database, Dependencies, Documentation
 - Findings classified as must-fix, should-fix, or nit with severity and confidence levels
 
 Provides actionable feedback with specific file locations and suggested fixes.
@@ -120,10 +120,27 @@ The `devflow-core-skills` plugin provides quality enforcement skills that activa
 | `test-driven-development` | Implementing new features (RED-GREEN-REFACTOR) |
 | `test-patterns` | Writing or modifying tests |
 | `input-validation` | Creating API endpoints |
-| `typescript` | Working in TypeScript codebases |
-| `react` | Working with React components |
-| `accessibility` | Creating UI components, forms, interactive elements |
-| `frontend-design` | Working with CSS, styling, visual design |
+
+## Language & Ecosystem Plugins
+
+Optional plugins for language-specific patterns. Install only what you need:
+
+| Plugin | Skill | Triggers When |
+|--------|-------|---------------|
+| `devflow-typescript` | `typescript` | Working in TypeScript codebases |
+| `devflow-react` | `react` | Working with React components |
+| `devflow-accessibility` | `accessibility` | Creating UI components, forms |
+| `devflow-frontend-design` | `frontend-design` | Working with CSS, styling |
+| `devflow-go` | `go` | Working in Go codebases |
+| `devflow-python` | `python` | Working in Python codebases |
+| `devflow-java` | `java` | Working in Java codebases |
+| `devflow-rust` | `rust` | Working in Rust codebases |
+
+```bash
+# Install specific language plugins
+npx devflow-kit init --plugin=typescript,react
+npx devflow-kit init --plugin=go
+```
 
 ## Requirements
 

package/dist/plugins.js

@@ -10,7 +10,7 @@ export const DEVFLOW_PLUGINS = [
         description: 'Auto-activating quality enforcement (foundation layer)',
         commands: [],
         agents: [],
-        skills: ['accessibility', 'core-patterns', 'docs-framework', 'frontend-design', 'git-safety', 'git-workflow', 'github-patterns', 'input-validation', 'react', 'test-driven-development', 'test-patterns', 'typescript'],
+        skills: ['core-patterns', 'docs-framework', 'git-safety', 'git-workflow', 'github-patterns', 'input-validation', 'test-driven-development', 'test-patterns'],
     },
     {
         name: 'devflow-specify',
@@ -24,14 +24,14 @@ export const DEVFLOW_PLUGINS = [
         description: 'Complete task implementation workflow',
         commands: ['/implement'],
         agents: ['git', 'skimmer', 'synthesizer', 'coder', 'simplifier', 'scrutinizer', 'shepherd', 'validator'],
-        skills: ['accessibility', 'agent-teams', 'frontend-design', 'implementation-patterns', 'self-review'],
+        skills: ['agent-teams', 'implementation-patterns', 'self-review'],
     },
     {
         name: 'devflow-code-review',
         description: 'Comprehensive code review',
         commands: ['/code-review'],
         agents: ['git', 'reviewer', 'synthesizer'],
-        skills: ['accessibility', 'agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'frontend-design', 'performance-patterns', 'react', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'],
+        skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'],
     },
     {
         name: 'devflow-resolve',
@@ -69,6 +69,70 @@ export const DEVFLOW_PLUGINS = [
         skills: [],
         optional: true,
     },
+    {
+        name: 'devflow-typescript',
+        description: 'TypeScript language patterns (type safety, generics, utility types)',
+        commands: [],
+        agents: [],
+        skills: ['typescript'],
+        optional: true,
+    },
+    {
+        name: 'devflow-react',
+        description: 'React framework patterns (hooks, state, composition, performance)',
+        commands: [],
+        agents: [],
+        skills: ['react'],
+        optional: true,
+    },
+    {
+        name: 'devflow-accessibility',
+        description: 'Web accessibility patterns (WCAG, ARIA, keyboard navigation)',
+        commands: [],
+        agents: [],
+        skills: ['accessibility'],
+        optional: true,
+    },
+    {
+        name: 'devflow-frontend-design',
+        description: 'Frontend design patterns (typography, color, spacing, motion)',
+        commands: [],
+        agents: [],
+        skills: ['frontend-design'],
+        optional: true,
+    },
+    {
+        name: 'devflow-go',
+        description: 'Go language patterns (error handling, interfaces, concurrency)',
+        commands: [],
+        agents: [],
+        skills: ['go'],
+        optional: true,
+    },
+    {
+        name: 'devflow-java',
+        description: 'Java language patterns (records, sealed classes, composition)',
+        commands: [],
+        agents: [],
+        skills: ['java'],
+        optional: true,
+    },
+    {
+        name: 'devflow-python',
+        description: 'Python language patterns (type hints, protocols, data modeling)',
+        commands: [],
+        agents: [],
+        skills: ['python'],
+        optional: true,
+    },
+    {
+        name: 'devflow-rust',
+        description: 'Rust language patterns (ownership, error handling, type system)',
+        commands: [],
+        agents: [],
+        skills: ['rust'],
+        optional: true,
+    },
 ];
 /**
  * Deprecated command names from old installations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Agentic Development Toolkit for Claude Code - Enhance AI-assisted development with intelligent commands and workflows",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "dev": "tsc --watch",
     "cli": "node dist/cli.js",
     "prepublishOnly": "npm run build",
+    "version:bump": "npx tsx scripts/bump-version.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },

package/plugins/devflow-accessibility/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "devflow-accessibility",
+  "description": "Web accessibility patterns - WCAG compliance, ARIA roles, keyboard navigation, focus management",
+  "author": {
+    "name": "DevFlow Contributors",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.2.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": ["accessibility", "wcag", "aria", "a11y"],
+  "agents": [],
+  "skills": ["accessibility"]
+}

package/plugins/devflow-ambient/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "devflow-ambient",
   "description": "Ambient mode — auto-loads relevant skills for every prompt",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "agents": [],
   "skills": ["ambient-router"]
 }

package/plugins/devflow-ambient/skills/ambient-router/SKILL.md

@@ -54,7 +54,7 @@ Based on classified intent, read the following skills to inform your response.
 
 | Intent | Primary Skills | Secondary (if file type matches) |
 |--------|---------------|----------------------------------|
-| **BUILD** | test-driven-development, implementation-patterns | typescript (.ts), react (.tsx/.jsx), frontend-design (CSS/UI), input-validation (forms/API), security-patterns (auth/crypto) |
+| **BUILD** | test-driven-development, implementation-patterns | typescript (.ts), react (.tsx/.jsx), go (.go), java (.java), python (.py), rust (.rs), frontend-design (CSS/UI), input-validation (forms/API), security-patterns (auth/crypto) |
 | **DEBUG** | test-patterns, core-patterns | git-safety (if git operations involved) |
 | **REVIEW** | self-review, core-patterns | test-patterns |
 | **PLAN** | implementation-patterns | core-patterns |

package/plugins/devflow-ambient/skills/ambient-router/references/skill-catalog.md

@@ -16,6 +16,10 @@ These skills may be loaded during STANDARD-depth ambient routing.
 | react | React components in scope | `*.tsx`, `*.jsx` |
 | frontend-design | UI/styling work | `*.css`, `*.scss`, `*.tsx` with styling keywords |
 | input-validation | Forms, APIs, user input | Files with form/input/validation keywords |
+| go | Go files in scope | `*.go` |
+| java | Java files in scope | `*.java` |
+| python | Python files in scope | `*.py` |
+| rust | Rust files in scope | `*.rs` |
 | security-patterns | Auth, crypto, secrets | Files with auth/token/crypto/password keywords |
 
 ### DEBUG Intent

package/plugins/devflow-audit-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "devflow-audit-claude",
   "description": "Audit CLAUDE.md files against Anthropic best practices",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "agents": [],
   "skills": []
 }

package/plugins/devflow-code-review/.claude-plugin/plugin.json

@@ -5,14 +5,13 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
   "keywords": ["review", "code-quality", "security", "architecture", "pr-review"],
   "agents": ["git", "reviewer", "synthesizer"],
   "skills": [
-    "accessibility",
     "agent-teams",
     "architecture-patterns",
     "complexity-patterns",
@@ -20,9 +19,7 @@
     "database-patterns",
     "dependencies-patterns",
     "documentation-patterns",
-    "frontend-design",
     "performance-patterns",
-    "react",
     "regression-patterns",
     "review-methodology",
     "security-patterns",

package/plugins/devflow-code-review/agents/reviewer.md

@@ -34,6 +34,10 @@ The orchestrator provides:
 | `react` | `~/.claude/skills/react/SKILL.md` |
 | `accessibility` | `~/.claude/skills/accessibility/SKILL.md` |
 | `frontend-design` | `~/.claude/skills/frontend-design/SKILL.md` |
+| `go` | `~/.claude/skills/go/SKILL.md` |
+| `java` | `~/.claude/skills/java/SKILL.md` |
+| `python` | `~/.claude/skills/python/SKILL.md` |
+| `rust` | `~/.claude/skills/rust/SKILL.md` |
 
 ## Responsibilities
 
@@ -117,3 +121,7 @@ Report format for `{output_path}`:
 | react | If .tsx/.jsx files changed |
 | accessibility | If .tsx/.jsx files changed |
 | frontend-design | If .tsx/.jsx/.css/.scss files changed |
+| go | If .go files changed |
+| java | If .java files changed |
+| python | If .py files changed |
+| rust | If .rs files changed |

package/plugins/devflow-code-review/commands/code-review-teams.md

@@ -42,10 +42,16 @@ Detect file types in diff to determine conditional reviews:
 | .tsx/.jsx files | react |
 | .tsx/.jsx files | accessibility |
 | .tsx/.jsx/.css/.scss files | frontend-design |
+| .go files | go |
+| .java files | java |
+| .py files | python |
+| .rs files | rust |
 | DB/migration files | database |
 | Dependency files changed | dependencies |
 | Docs or significant code | documentation |
 
+**Skill availability check**: Language/ecosystem reviews (typescript, react, accessibility, frontend-design, go, java, python, rust) require their optional skill plugin to be installed. Before adding a conditional perspective, check if `~/.claude/skills/{focus}/SKILL.md` exists (use Glob). If the skill file doesn't exist, **skip that perspective** — the language plugin isn't installed. Non-language reviews (database, dependencies, documentation) use skills bundled with this plugin and are always available.
+
 ### Phase 2: Spawn Review Team
 
 Create an agent team for adversarial review. Always include 4 core perspectives; conditionally add more based on Phase 1 analysis.
@@ -61,6 +67,10 @@ Create an agent team for adversarial review. Always include 4 core perspectives;
 - **React**: hooks, state, rendering, composition (if .tsx/.jsx changed)
 - **Accessibility**: ARIA, keyboard nav, focus management (if .tsx/.jsx changed)
 - **Frontend Design**: visual consistency, spacing, typography (if .tsx/.jsx/.css changed)
+- **Go**: error handling, interfaces, concurrency (if .go changed)
+- **Java**: records, sealed classes, composition (if .java changed)
+- **Python**: type hints, protocols, data modeling (if .py changed)
+- **Rust**: ownership, error handling, type system (if .rs changed)
 - **Database**: schema, queries, migrations, indexes (if DB files changed)
 - **Dependencies**: CVEs, versions, licenses, supply chain (if package files changed)
 - **Documentation**: doc drift, missing docs, stale comments (if docs or significant code changed)
@@ -238,7 +248,7 @@ Display results:
 │  ├─ Architecture Reviewer (teammate)
 │  ├─ Performance Reviewer (teammate)
 │  ├─ Quality Reviewer (teammate)
-│  └─ [Conditional: TypeScript, React, A11y, Design, DB, Deps, Docs]
+│  └─ [Conditional: TypeScript, React, A11y, Design, Go, Java, Python, Rust, DB, Deps, Docs]
 │
 ├─ Phase 3: Debate round
 │  └─ Reviewers challenge each other (max 2 rounds)

package/plugins/devflow-code-review/commands/code-review.md

@@ -42,13 +42,19 @@ Detect file types in diff to determine conditional reviews:
 | .tsx/.jsx files | react |
 | .tsx/.jsx files | accessibility |
 | .tsx/.jsx/.css/.scss files | frontend-design |
+| .go files | go |
+| .java files | java |
+| .py files | python |
+| .rs files | rust |
 | DB/migration files | database |
 | Dependency files changed | dependencies |
 | Docs or significant code | documentation |
 
+**Skill availability check**: Language/ecosystem reviews (typescript, react, accessibility, frontend-design, go, java, python, rust) require their optional skill plugin to be installed. Before spawning a conditional Reviewer for these focuses, check if `~/.claude/skills/{focus}/SKILL.md` exists (use Glob). If the skill file doesn't exist, **skip that review** — the language plugin isn't installed. Non-language reviews (database, dependencies, documentation) use skills bundled with this plugin and are always available.
+
 ### Phase 2: Run Reviews (Parallel)
 
-Spawn Reviewer agents **in a single message**. Always run 7 core reviews; conditionally add up to 4 more:
+Spawn Reviewer agents **in a single message**. Always run 7 core reviews; conditionally add more based on changed file types:
 
 | Focus | Always | Pattern Skill |
 |-------|--------|---------------|
@@ -63,6 +69,10 @@ Spawn Reviewer agents **in a single message**. Always run 7 core reviews; condit
 | react | conditional | react |
 | accessibility | conditional | accessibility |
 | frontend-design | conditional | frontend-design |
+| go | conditional | go |
+| java | conditional | java |
+| python | conditional | python |
+| rust | conditional | rust |
 | database | conditional | database-patterns |
 | dependencies | conditional | dependencies-patterns |
 | documentation | conditional | documentation-patterns |
@@ -123,7 +133,7 @@ Display results from all agents:
 │  ├─ Reviewer: consistency
 │  ├─ Reviewer: regression
 │  ├─ Reviewer: tests
-│  └─ Reviewer: [conditional: typescript, react, a11y, design, database, deps, docs]
+│  └─ Reviewer: [conditional: typescript, react, a11y, design, go, java, python, rust, database, deps, docs]
 │
 ├─ Phase 3: Synthesis (PARALLEL)
 │  ├─ Git agent (comment-pr)

package/plugins/devflow-core-skills/.claude-plugin/plugin.json

@@ -5,24 +5,20 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
   "keywords": ["skills", "quality", "patterns", "auto-activate", "enforcement", "foundation"],
   "agents": [],
   "skills": [
-    "accessibility",
     "core-patterns",
     "docs-framework",
-    "frontend-design",
     "git-safety",
     "git-workflow",
     "github-patterns",
     "input-validation",
-    "react",
     "test-driven-development",
-    "test-patterns",
-    "typescript"
+    "test-patterns"
   ]
 }

package/plugins/devflow-debug/.claude-plugin/plugin.json

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-frontend-design/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "devflow-frontend-design",
+  "description": "Frontend design patterns - typography, color systems, spacing, motion, responsive design",
+  "author": {
+    "name": "DevFlow Contributors",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.2.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": ["design", "typography", "color", "css"],
+  "agents": [],
+  "skills": ["frontend-design"]
+}

package/plugins/devflow-go/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "devflow-go",
+  "description": "Go language patterns - error handling, interfaces, concurrency, package design",
+  "author": {
+    "name": "DevFlow Contributors",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.2.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": ["go", "golang", "concurrency", "errors"],
+  "agents": [],
+  "skills": ["go"]
+}

package/plugins/devflow-go/skills/go/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: go
+description: This skill should be used when the user works with Go files (.go), asks about "error handling", "interfaces", "goroutines", "channels", "packages", or discusses Go idioms and concurrency. Provides patterns for error handling, interface design, concurrency, and package organization.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.go"
+  exclude:
+    - "vendor/**"
+---
+
+# Go Patterns
+
+Reference for Go-specific patterns, idioms, and best practices.
+
+## Iron Law
+
+> **ERRORS ARE VALUES**
+>
+> Never ignore errors. `if err != nil` is correctness, not boilerplate. Every error
+> return must be checked, wrapped with context, or explicitly documented as intentionally
+> ignored with `_ = fn()`. Silent error swallowing causes cascading failures.
+
+## When This Skill Activates
+
+- Working with Go codebases
+- Designing interfaces and packages
+- Implementing concurrent code
+- Handling errors
+- Structuring Go projects
+
+---
+
+## Error Handling
+
+### Wrap Errors with Context
+
+```go
+// BAD: return err
+// GOOD: return fmt.Errorf("reading config %s: %w", path, err)
+```
+
+### Sentinel Errors for Expected Conditions
+
+```go
+var ErrNotFound = errors.New("not found")
+
+func FindUser(id string) (*User, error) {
+    u, err := db.Get(id)
+    if err != nil {
+        return nil, fmt.Errorf("finding user %s: %w", id, err)
+    }
+    if u == nil {
+        return nil, ErrNotFound
+    }
+    return u, nil
+}
+// Caller: if errors.Is(err, ErrNotFound) { ... }
+```
+
+---
+
+## Interface Design
+
+### Accept Interfaces, Return Structs
+
+```go
+// BAD: func NewService(repo *PostgresRepo) *Service
+// GOOD: func NewService(repo Repository) *Service
+
+type Repository interface {
+    FindByID(ctx context.Context, id string) (*Entity, error)
+    Save(ctx context.Context, entity *Entity) error
+}
+```
+
+### Keep Interfaces Small
+
+```go
+// BAD: 10-method interface
+// GOOD: single-method interfaces composed as needed
+type Reader interface { Read(p []byte) (n int, err error) }
+type Writer interface { Write(p []byte) (n int, err error) }
+type ReadWriter interface { Reader; Writer }
+```
+
+---
+
+## Concurrency
+
+### Use Context for Cancellation
+
+```go
+func Process(ctx context.Context, items []Item) error {
+    g, ctx := errgroup.WithContext(ctx)
+    for _, item := range items {
+        g.Go(func() error {
+            return processItem(ctx, item)
+        })
+    }
+    return g.Wait()
+}
+```
+
+### Channel Direction
+
+```go
+// Declare direction in function signatures
+func producer(ch chan<- int) { ch <- 42 }
+func consumer(ch <-chan int) { v := <-ch; _ = v }
+```
+
+---
+
+## Package Design
+
+### Organize by Domain, Not by Type
+
+```go
+// BAD: models/, controllers/, services/
+// GOOD: user/, order/, payment/
+```
+
+### Export Only What's Needed
+
+```go
+// Internal helpers stay unexported (lowercase)
+func (s *Service) validate(u *User) error { ... }
+
+// Public API is exported (uppercase)
+func (s *Service) CreateUser(ctx context.Context, req CreateUserReq) (*User, error) { ... }
+```
+
+---
+
+## Zero Values
+
+```go
+// Use zero values as valid defaults
+var mu sync.Mutex     // Ready to use
+var buf bytes.Buffer  // Ready to use
+var wg sync.WaitGroup // Ready to use
+
+// Design types with useful zero values
+type Config struct {
+    Timeout time.Duration // zero = no timeout
+    Retries int           // zero = no retries
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Ignoring error | `val, _ := fn()` | `val, err := fn(); if err != nil { ... }` |
+| Naked return | `return` in named returns | Explicit `return val, err` |
+| init() abuse | Complex `init()` functions | Explicit initialization in `main()` or constructors |
+| Interface pollution | Defining interfaces before use | Define interfaces at the consumer site |
+| Goroutine leak | `go fn()` without lifecycle | Use context, errgroup, or done channels |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Common Go violations
+- `references/patterns.md` - Extended Go patterns
+- `references/detection.md` - Detection patterns for Go issues
+- `references/concurrency.md` - Advanced concurrency patterns
+
+---
+
+## Checklist
+
+- [ ] All errors checked or explicitly ignored with `_ =`
+- [ ] Errors wrapped with `fmt.Errorf("context: %w", err)`
+- [ ] Interfaces defined at consumer, not producer
+- [ ] Interfaces kept small (1-3 methods)
+- [ ] Context passed as first parameter
+- [ ] Goroutines have clear lifecycle/cancellation
+- [ ] Channel direction specified in signatures
+- [ ] Zero values are useful defaults
+- [ ] Packages organized by domain
+- [ ] No `init()` with side effects