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/dariubs/GoBooks 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 — Missing license — unclear to depend on

• Last commit 2w ago
• 50+ active contributors
• Distributed ownership (top contributor 16% of recent commits)
• CI configured
• ⚠ No license — legally unclear to depend on
• ⚠ 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 dariubs/GoBooks repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dariubs/GoBooks.

What it runs against: a local clone of dariubs/GoBooks — 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 dariubs/GoBooks | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | Last commit ≤ 44 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dariubs/GoBooks. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dariubs/GoBooks.git
#   cd GoBooks
#
# 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 dariubs/GoBooks and re-run."
  exit 2
fi

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 44 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~14d)"
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/dariubs/GoBooks"
  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).

GoBooks is a curated, community-driven directory of Go programming books organized by skill level and topic (starter, advanced, web development, etc.). It provides a centralized reference with book covers, publication dates, author names, and Amazon/Manning links to help developers find the right Go learning resource without sifting through generic lists. Simple flat structure: root README.md contains the main English catalog; gobooks/ subdirectory holds localized README files (README-{es,zh,pt,ru,de,fa}.md), a Makefile for validation, a .gitignore, and a covers/ folder with ~60 book cover images (PNG/JPG). The .github/workflows/validate.yml runs automated checks on README content.

Go developers at all levels (absolute beginners through senior engineers working on concurrency and system design) who need a vetted, filterable reading list; plus contributors who maintain and expand the book catalog across multiple languages (English, Spanish, Chinese, Portuguese, Russian, German, Farsi).

This is a stable, actively maintained reference project. It uses GitHub Actions CI/CD (validate.yml) to validate content, has translations in 6 languages (README-{es,zh,pt,ru,de,fa}.md), and follows semantic contribution guidelines (CONTRIBUTING.md). The minimal Go code (~8.9 KB) indicates it's a content + validation repo, not a production application.

Very low risk for a reference repo. No external runtime dependencies (only a lightweight validator in Go 1.21). Single maintainer (dariubs) with no visible open issue tracking in the snippet, but the curated nature means community contributions are the primary activity. No breaking changes expected since this is a documentation-style project.

The repository is in maintenance mode, focusing on keeping the book list current and accurate. The validate.yml workflow suggests active CI checks for README formatting/links. Based on the structured layout and multiple language translations, ongoing work likely includes adding newly published Go books and verifying links/cover images remain valid.

Clone and explore: git clone https://github.com/dariubs/GoBooks.git && cd GoBooks. To validate locally, navigate to the gobooks/ directory and run make (Makefile present). No build or install step required—this is a content repo you browse and contribute to via pull requests.

Daily commands: This is not a runnable application. To validate README integrity locally: cd gobooks && make. To view the content: open README.md in any Markdown viewer or GitHub web UI. To test link/cover image validity in CI: push changes and GitHub Actions (validate.yml) runs automated checks.

• gobooks/README.md: Primary book catalog in English; contains all book entries with covers, links, publication dates, and author names organized by difficulty level and topic.
• .github/workflows/validate.yml: CI/CD pipeline that automatically checks README formatting, links, and cover image validity on every push/PR to maintain catalog quality.
• gobooks/Makefile: Local validation entry point; developers run make here to test README integrity before committing.
• gobooks/covers/: Directory containing ~60 book cover images (PNG/JPG) displayed alongside each book entry in the README.
• CONTRIBUTING.md: Guidelines for contributors adding new books, translating content, or improving the project; ensures consistent format and quality.

For adding/editing Go books: edit gobooks/README.md (English) or gobooks/README-{es,zh,pt,ru,de,fa}.md (translations). Add book cover images to gobooks/covers/{book-slug}.{png|jpg}. For validation logic: modify gobooks/Makefile or the validator Go code (implied to be in gobooks/ but not shown in file list). Follow CONTRIBUTING.md guidelines before submitting PRs.

No hidden traps specific to this repo. It is a static content project with no runtime dependencies, environment variables, or service requirements. The only automation is GitHub Actions validation (validate.yml), which runs automatically. Local make validation is optional. Ensure book cover images are added to gobooks/covers/ with the correct naming convention (kebab-case slugs) to avoid broken links.

• Curated Content Management — Understanding how to organize, validate, and maintain a large, multi-language reference list is essential for scaling GoBooks as the Go ecosystem grows.
• GitHub Actions CI/CD for Content — This repo uses validate.yml to automate checks on Markdown and links; learning this pattern is crucial for maintaining documentation quality without manual review.
• Internationalization (i18n) via Markdown Duplication — GoBooks maintains 6 translations as separate README files (README-{es,zh,pt,ru,de,fa}.md) rather than using a dedicated i18n framework; understanding this trade-off between simplicity and scalability is valuable.
• Makefile-Based Automation — The gobooks/Makefile orchestrates local validation; Makefiles remain a standard tool in Go projects for build and test automation despite newer alternatives.
• Static Asset Management — Managing ~60 cover images across multiple formats (PNG/JPG) in a GitHub repo requires discipline around naming, sizing, and link integrity—critical for visual-heavy documentation.
• Affiliate Marketing Links (Amazon/Manning) — GoBooks uses affiliate links to monetize recommendations; understanding how to maintain affiliate URLs without breaking SEO or user trust is a consideration for content curators.

• golang/go — Official Go language repository; provides the language specification and stdlib that every book on GoBooks teaches.
• avelino/awesome-go — Complementary Awesome list curating Go libraries, frameworks, and tools; while GoBooks focuses on books, awesome-go covers practical packages developers use.
• inancgumus/learngo — Hands-on Go tutorial repository with runnable examples; complements GoBooks by providing free, code-first learning alongside book-based study.
• syndbg/GolangCompilerConstruction — Specialized Go compiler and tooling resource; useful for developers seeking deep technical knowledge beyond introductory books.

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.

Create a validator tool to enforce README consistency across translations

The repo has 6 translated README files (README-de.md, README-es.md, README-fa.md, README-pt.md, README-ru.md, README-zh.md) but no automated tool to ensure they stay in sync with the main README.md. A validator in the existing gobooks/validator module would check that all translations have the same book entries and section structure, preventing outdated translations.

• [ ] Extend gobooks/validator module with a translation sync checker that compares book lists across all README files
• [ ] Add validation logic to detect missing books in translations and mismatched section headings
• [ ] Integrate the new validator into .github/workflows/validate.yml to run on every PR
• [ ] Document the validation rules in CONTRIBUTING.md for translators

Add a Makefile target to validate cover image integrity and metadata

The gobooks/covers/ directory contains 80+ image files (png, jpg, jpeg, avif, webp, svg) but there's no automated check to ensure: (1) every book listed in README has a corresponding cover image, (2) image files aren't corrupted, (3) file naming follows conventions. Extend gobooks/Makefile with validation targets.

• [ ] Add a 'make validate-covers' target in gobooks/Makefile that checks all README book entries have matching cover files
• [ ] Implement basic image file integrity checks (file exists, proper extension, minimal file size)
• [ ] Create a naming convention checker that validates cover filenames match kebab-case book titles
• [ ] Integrate this target into the CI workflow to catch missing covers in PRs

Build a structured book data schema validator for README.md

The README.md uses markdown list format but lacks structured validation. Create a validator that parses the markdown structure to ensure each book entry has required metadata (title, author, link, publication year). This prevents malformed entries and makes the data machine-parseable for future tools (cover image mapping, book database, etc).

• [ ] Create a schema definition in gobooks/validator for required book metadata fields
• [ ] Add a markdown parser that extracts book entries from all README files and validates against the schema
• [ ] Add error reporting showing line numbers and which metadata fields are missing
• [ ] Update .github/workflows/validate.yml to run this schema validator on PRs that modify README files

• Add missing book cover images for recently published Go books (e.g., titles in README.md that lack corresponding files in gobooks/covers/) to improve visual appeal and completeness.
• Create or update a translated README for an additional language (e.g., Japanese, Korean, Italian) by following the pattern of existing README-{es,zh,pt,ru,de,fa}.md files.
• Audit and fix dead or redirected Amazon/Manning affiliate links in the English and translated READMEs to ensure all book purchase URLs remain valid.

The GoBooks repository is primarily a documentation/curated list project with minimal security risk. The main concerns are maintenance-related: an outdated Go version (1.21) used in the validator module and missing governance files (CODEOWNERS). The codebase contains no evidence of hardcoded secrets, injection vulnerabilities, or misconfigurations. No complex dependencies are declared that could introduce supply chain risks. Recommendations focus on keeping dependencies current and establishing clear code review processes.

• Low · Outdated Go Version — gobooks/validator/go.mod. The go.mod file specifies Go 1.21, which is now outdated. Go 1.21 reached end-of-life on 2024-08-06. Using outdated Go versions may expose the project to known security vulnerabilities that have been patched in newer releases. Fix: Update to the latest stable Go version (1.22 or later). Modify go.mod to specify a recent Go version and test thoroughly.
• Low · Missing CODEOWNERS File — Repository root. The repository lacks a CODEOWNERS file. This could lead to unauthorized changes or difficulty in enforcing code review policies for security-sensitive files. Fix: Create a CODEOWNERS file to define who should review changes to critical files, especially the validator module and CI/CD workflows.
• Low · Incomplete GitHub Workflow Configuration — .github/workflows/validate.yml. The validate.yml workflow file is referenced but not fully visible. Validation workflows should include security checks, dependency scanning, and code quality checks to prevent vulnerable code from being merged. Fix: Ensure the CI/CD pipeline includes: dependency vulnerability scanning (go mod audit), SAST tools, and linting. Consider integrating GitHub's Dependabot for automated dependency updates.

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.