If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tmrts/go-patterns shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 13 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 74% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tmrts/go-patterns repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tmrts/go-patterns.

What it runs against: a local clone of tmrts/go-patterns — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tmrts/go-patterns | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 755 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tmrts/go-patterns. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tmrts/go-patterns.git
#   cd go-patterns
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tmrts/go-patterns and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tmrts/go-patterns(\\.git)?\\b" \\
  && ok "origin remote is tmrts/go-patterns" \\
  || miss "origin remote is not tmrts/go-patterns (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "SUMMARY.md" \\
  && ok "SUMMARY.md" \\
  || miss "missing critical file: SUMMARY.md"
test -f "behavioral/observer/main.go" \\
  && ok "behavioral/observer/main.go" \\
  || miss "missing critical file: behavioral/observer/main.go"
test -f "creational/builder.md" \\
  && ok "creational/builder.md" \\
  || miss "missing critical file: creational/builder.md"
test -f "concurrency/bounded_parallelism.go" \\
  && ok "concurrency/bounded_parallelism.go" \\
  || miss "missing critical file: concurrency/bounded_parallelism.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 755 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~725d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tmrts/go-patterns"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

go-patterns is a curated reference collection of 20+ idiomatic Go design patterns, concurrency idioms, and architectural recipes documented with Markdown explanations and working Go code examples. It covers creational patterns (Builder, Factory, Singleton, Object Pool), structural patterns (Decorator, Proxy), behavioral patterns (Observer, Strategy), concurrency primitives (fan-in/out, bounded parallelism, generators), and stability patterns (circuit-breaker). This is a teaching and reference resource, not a library. Topic-focused directory structure: behavioral/, creational/, structural/ folders each contain .md docs and optional subdirectories with runnable .go examples (e.g., behavioral/observer/main.go). Additional categories include concurrency/, messaging/, synchronization/, idiom/, profiling/, and stability/. Root SUMMARY.md and README.md provide navigation; book.json suggests GitBook integration for publishing.

Go developers learning design patterns and idioms—particularly junior engineers new to Go who need clear, code-first examples of how to structure applications idomatically. Also intermediate developers looking to understand Go-specific concurrency patterns and anti-patterns to avoid.

Actively maintained reference material with passing CI (Travis), Apache 2.0 license, and complete markdown documentation for ~20 patterns. The repo structure is stable and focused on documentation + examples rather than a single evolving codebase, making it a reliable learning resource. Status indicators in README show ~12 patterns fully documented (✔) and ~8 pending (✘), indicating honest curation rather than abandonment.

Very low risk for a documentation/examples repo—no runtime dependencies, no CI configuration drift, no production code to break. Single maintainer (tmrts) is the main risk factor for response time on PRs/issues, and some patterns remain unimplemented (Bridge, Composite, Chain of Responsibility). No version constraints, security surface, or breaking change risk since this is educational content.

The repo maintains curated pattern documentation with clear completion status in the README. Recent activity likely focuses on adding missing patterns (marked ✘) and improving existing examples. No specific PR/issue data visible, but the structure and CI setup suggest ongoing maintenance rather than active feature development.

Clone and read: git clone https://github.com/tmrts/go-patterns.git && cd go-patterns. No install step needed—patterns are documented in .md files and runnable Go examples. Open README.md to see the pattern index, then navigate to specific pattern directories like creational/builder.md to read explanation + code examples.

Daily commands: This is a documentation repo, not an executable project. Individual pattern examples can be run: go run behavioral/observer/main.go or go run structural/proxy/main.go. Some patterns are code-only in .go files; others pair .md explanation with /main.go example in subdirectories.

• README.md — Entry point documenting all design patterns, their status, and the repository's scope and goals.
• SUMMARY.md — Table of contents for the documentation structure; essential for navigating pattern categories.
• behavioral/observer/main.go — Reference implementation of the Observer pattern; demonstrates the repository's code example conventions.
• creational/builder.md — Marked as complete (✔); exemplary pattern documentation that contributors should follow.
• concurrency/bounded_parallelism.go — Core concurrency pattern showing Go-idiomatic goroutine management; critical for async pattern understanding.
• idiom/functional-options.md — Foundational Go idiom pattern; essential for understanding configuration and flexibility conventions.
• book.json — GitBook configuration; controls documentation build, styling, and navigation structure.

• Pattern Documentation (.md files) (Markdown, Git) — Explain intent, benefits, trade-offs, and Go-specific considerations for each pattern.

Add a New Design Pattern

1. Create a new markdown file in the appropriate category folder (e.g., creational/, behavioral/, structural/) (creational/builder.md)
2. Follow the documentation structure with pattern name, intent, benefits, trade-offs, and Go-specific notes (behavioral/observer.md)
3. Optionally create a reference implementation subdirectory with main.go demonstrating the pattern (behavioral/observer/main.go)
4. Update SUMMARY.md to add an entry linking to the new pattern documentation (SUMMARY.md)
5. Update README.md's pattern table to include the new pattern with a status indicator (✔ or ✘) (README.md)

Add a New Concurrency Pattern or Idiom

1. Create a .go file in the concurrency/ folder demonstrating the pattern with runnable code (concurrency/bounded_parallelism.go)
2. Create a corresponding .md file explaining the pattern, use cases, and Go-specific implementation details (concurrency/bounded_parallelism.md)
3. Ensure the Go code includes clear comments and follows the pattern shown in existing concurrency examples (concurrency/generator.md)
4. Add the pattern to SUMMARY.md under the Concurrency or Idiom section (SUMMARY.md)

Add Stability or Messaging Patterns

1. Create a new markdown file in stability/ or messaging/ with pattern documentation (stability/circuit-breaker.md)
2. Include Go code examples (inline in markdown or reference a separate .go file) demonstrating the pattern (messaging/publish_subscribe.md)
3. Explain the pattern's applicability, concurrency considerations, and error handling approach (messaging/fan_in.md)
4. Update SUMMARY.md to include the new pattern in the correct category (SUMMARY.md)

• Markdown + Go code files — Provides readable pattern documentation with executable reference implementations; integrates with Git and version control.
• GitBook (book.json) — Converts markdown into a polished, navigable online documentation site with a table of contents and search capabilities.
• Travis CI (.travis.yml) — Automatically validates Go code examples compile and run correctly on every commit; ensures pattern implementations are correct.
• GitHub (tmrts/go-patterns repo) — Provides collaborative version control, issue tracking, and pull request workflow for community contributions.

• Separate .md documentation files from .go implementation files

  • Why: Keeps explanation and code examples decoupled; allows documentation to be language-agnostic and code to be independently testable.
  • Consequence: Contributors must maintain consistency between docs and code; easier to update docs without breaking examples.

• Organize patterns by type (creational, behavioral, structural) rather than by use case

  • Why: Follows Gang of Four classification; provides a familiar taxonomy for developers.
  • Consequence: Some patterns span multiple categories (e.g., functional-options is both idiom and creational); requires cross-referencing.

• Use simple Go examples (main.go in pattern folders) without external dependencies

  • Why: Maximizes clarity and ease of copying patterns into user code; minimizes setup burden.
  • Consequence: Examples are minimal; real-world patterns may require additional tooling or context.

• Maintain ✔/✘ completion status in README

  • Why: Sets clear expectations for pattern maturity and contribution priorities.
  • Consequence: Incomplete patterns (✘) signal areas needing contributions but may not be suitable for critical production use.

• Provide production-ready libraries or frameworks—this is educational documentation, not a standard library.
• Cover all possible design patterns—scope limited to curated, idiomatic Go patterns.
• Address Go version compatibility or breaking changes—focuses on timeless, core patterns.
• Provide performance benchmarks or optimization guidance—examples prioritize clarity over speed.

No hidden traps. This is a static documentation repo with no runtime dependencies, configuration files, or required services. Go examples are self-contained and run directly with go run. Only note: some patterns are documented in .md only (no runnable code), while others have both .md + /main.go examples—check the file structure for each pattern.

• Observer Pattern — Core behavioral pattern implemented in behavioral/observer/ showing how to decouple event producers from consumers using callback registration—essential for event-driven Go applications
• Fan-In / Fan-Out Concurrency — Go-specific messaging patterns in messaging/fan_in.md and messaging/fan_out.md using channels to multiplex/demultiplex work across goroutines—fundamental Go concurrency idiom
• Bounded Parallelism — Concurrency pattern in concurrency/bounded_parallelism.go that limits goroutine count to prevent resource exhaustion—critical for production Go services handling unbounded work
• Builder Pattern — Creational pattern in creational/builder.md enabling fluent, readable construction of complex objects—Go idiomatic alternative to constructors with many optional parameters
• Circuit Breaker Pattern — Stability pattern in stability/circuit-breaker.md for preventing cascading failures by stopping requests to failing services—essential for resilient distributed Go applications
• Generator Pattern — Go concurrency idiom in concurrency/generator.md using goroutines + channels to produce sequences on-demand—enables lazy evaluation and memory efficiency in Go pipelines
• Object Pool — Creational pattern in creational/object-pool.md reusing expensive objects (DB connections, buffers) to reduce allocation overhead—performance optimization critical for high-throughput Go services

• refactoring-guru/design-patterns-go — Alternative language-agnostic design patterns reference with Go code examples; good for comparing pattern implementations across languages
• grpc/grpc-go — Production Go framework that implements many patterns from this repo (factory, builder, decorator) in real distributed systems code
• golang-standards/project-layout — Companion resource on Go project structure and organization; helps learners scale patterns from examples to real applications
• eapache/go-patterns — Alternative curated Go patterns repo with different focus on concurrency and error handling patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Implement missing Abstract Factory pattern (creational/abstract_factory.md)

The README shows Abstract Factory is marked as incomplete (✘) in the Creational Patterns table. This is a fundamental design pattern that should have both documentation and working Go examples, similar to the existing builder.md and factory.md files.

• [ ] Create creational/abstract_factory.md with pattern explanation and use cases
• [ ] Create creational/abstract_factory/ directory with main.go implementation
• [ ] Add concrete example (e.g., UI factory for different OS themes)
• [ ] Update SUMMARY.md to include the new pattern
• [ ] Ensure code follows the style of existing patterns like builder.md and factory.md

Add runnable tests/examples for behavioral patterns (behavioral/observer/main.go validation)

The repo has behavioral/observer/main.go and behavioral/strategy.md but no corresponding test files or CI verification that examples compile and run correctly. This prevents bit-rot and ensures examples stay valid across Go versions.

• [ ] Create behavioral/observer/main_test.go with tests validating the observer pattern works
• [ ] Create behavioral/strategy/main.go and behavioral/strategy/main_test.go (strategy only has .md)
• [ ] Add go test commands to .travis.yml or create GitHub Actions workflow to verify all pattern examples compile
• [ ] Ensure tests run with go test ./behavioral/... pattern

Implement missing structural patterns with examples (structural/adapter, structural/bridge, structural/facade, structural/flyweight, structural/composite, structural/bridge)

The file list shows only decorator.md and proxy/ directory for structural patterns. Gang of Four structural patterns include 7 patterns; at least 5 are missing documented examples. This is a significant gap for a comprehensive patterns guide.

• [ ] Create structural/adapter.md with explanation and create structural/adapter/main.go
• [ ] Create structural/bridge.md and structural/bridge/main.go
• [ ] Create structural/facade.md and structural/facade/main.go
• [ ] Create structural/flyweight.md and structural/flyweight/main.go
• [ ] Create structural/composite.md and structural/composite/main.go
• [ ] Update SUMMARY.md with new structural patterns

• Implement and document the Bridge pattern (currently marked ✘ in README). Create structural/bridge.md with explanation and example code similar to decorator.md, then add a structural/bridge/main.go with runnable Go code.
• Add test files for existing runnable examples: create behavioral/observer/main_test.go and structural/proxy/main_test.go to demonstrate how to test observer and proxy pattern implementations.
• Document the remaining 8 unimplemented patterns (Chain of Responsibility, Command, Mediator, Memento, Registry, State, Composite, Facade, Flyweight) by creating .md files with explanations and simple Go examples in the appropriate category folder, then update README.md status.

This repository is a curated collection of Go design patterns and idioms with minimal security concerns. As an educational/documentation repository rather than a production application, it does not contain executable code with external dependencies, database connections, or infrastructure configurations that would typically introduce security vulnerabilities. No hardcoded secrets, injection risks, or misconfiguration issues were identified in the file structure. Recommendations focus on best practices for open-source repository governance. The absence of actual dependency files and production code significantly reduces the attack surface.

• Low · Missing SECURITY.md File — Repository root. The repository lacks a SECURITY.md file that typically outlines security policies, vulnerability disclosure procedures, and security contact information. This is a best practice for open-source projects. Fix: Create a SECURITY.md file following the GitHub security advisory guidelines to establish clear vulnerability reporting procedures.
• Low · Incomplete Content Verification — README.md. The README snippet appears truncated, making it difficult to verify all security-related documentation and disclaimers are properly included. Fix: Ensure the README includes security disclaimers and usage guidelines for educational patterns.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.