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/objc-zen/objc-zen-book 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 5y ago

• 14 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• Other licensed
• ⚠ Stale — last commit 5y ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ 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 objc-zen/objc-zen-book repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/objc-zen/objc-zen-book.

What it runs against: a local clone of objc-zen/objc-zen-book — 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 objc-zen/objc-zen-book | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 3 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1783 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "scripts/make_toc.rb" \\
  && ok "scripts/make_toc.rb" \\
  || miss "missing critical file: scripts/make_toc.rb"
test -f "LICENSE" \\
  && ok "LICENSE" \\
  || miss "missing critical file: LICENSE"

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

Zen and the Art of the Objective-C Craftsmanship is a comprehensive style guide and best practices documentation for writing clean, maintainable Objective-C code. It codifies conventions for conditionals, naming, class design, properties, categories, protocols, blocks, and inter-object communication patterns specific to Objective-C development. Single-file documentation project: README.md is the main artifact containing the full style guide with a detailed table of contents. A single Ruby script (scripts/make_toc.rb) generates the TOC from the README. Assets (images/, including zen-logo and blocks_debugger diagram) support the documentation visually.

Objective-C developers—particularly those maintaining iOS/macOS codebases or leading teams—who need clear, debatable guidelines for writing consistent, readable code without dogmatic hard rules. Teams adopting a shared code standard also reference it during code reviews.

Highly mature and stable. The repository was started in November 2013 and has accumulated substantial, well-organized documentation covering the Objective-C language deeply. There is no CI/test suite (it's a documentation project, not a library), and commit activity appears to have plateaued years ago, indicating the guide has reached a stable, complete state rather than being under active development.

Minimal technical risk for a documentation project, but the guide is now dated relative to modern iOS development (Swift adoption since 2014, modern Objective-C syntax and frameworks). It remains a valuable historical reference and is unlikely to receive breaking changes, though it is no longer actively maintained for contemporary best practices.

No active development. This is a completed, stable reference document. No indication of PRs, milestones, or recent commits in the provided data—it serves as a historical snapshot of Objective-C best practices circa 2013–2015.

Clone the repository: git clone https://github.com/objc-zen/objc-zen-book.git && cd objc-zen-book. Read README.md in your text editor or browser (GitHub renders it automatically). No build, install, or run steps needed—it is pure documentation.

Daily commands: No runtime. To regenerate the table of contents if you modify README.md: ruby scripts/make_toc.rb. Otherwise, open README.md in a text editor or GitHub to read the guide.

• README.md — Core documentation outlining Objective-C best practices and coding conventions that form the foundation of the entire guide.
• scripts/make_toc.rb — Build script that generates the table of contents from README.md, essential for maintaining documentation structure and navigation.
• LICENSE — Legal terms governing usage and contribution; essential reading for understanding project licensing constraints.

• README.md (Markdown, GitHub rendering) — Central documentation artifact containing all Objective-C best practices, guidelines, and conventions organized by topic
  • Failure mode: Outdated or inconsistent guidance if not kept in sync with Objective-C language evolution
• make_toc.rb (Ruby) — Build automation that keeps table of contents synchronized with README structure and heading anchors
  • Failure mode: Stale TOC with broken links if script is not run after adding new sections
• Image assets (PNG) — Visual references illustrating debugging techniques and coding patterns (Yoda conditions, blocks debugger view, zen logo)
  • Failure mode: Missing or broken image links degrade guide readability and learning effectiveness

• Developer contributions → README.md — New sections and best practices added to main documentation file
• README.md → make_toc.rb — Script parses markdown headers and anchors to generate navigation
• make_toc.rb → README.md (TOC section) — Generated table of contents updates the top of README for navigation
• README.md + images/ → GitHub rendering — Complete guide with visual aids rendered as web content for readers

Add a New Best Practice Section

1. Add new section heading to README.md with anchor link (e.g., ## Your Topic Name) (README.md)
2. Write subsections explaining the pattern, anti-patterns, and code examples (README.md)
3. Run make_toc.rb script to regenerate table of contents automatically (scripts/make_toc.rb)

Add Visual Reference for a Coding Pattern

1. Create or obtain PNG image illustrating the pattern (e.g., debugger output, diagram) (images/)
2. Reference the image in relevant section of README.md using markdown syntax (README.md)

• Markdown — Human-readable format ideal for technical guides and best practices documentation that can be version-controlled and published on GitHub
• Ruby — Simple scripting language for build automation; make_toc.rb parses markdown and generates table of contents with minimal dependencies
• PNG Images — Visual aids for explaining complex patterns and debugging techniques that benefit from screenshots and diagrams

• Documentation-only repository with no code examples

  • Why: Keeps the guide lightweight and focused on principles rather than specific implementations
  • Consequence: Readers must apply principles to their own codebases; no executable reference implementation

• Ruby script for TOC generation instead of manual updates

  • Why: Automates maintenance and reduces human error when adding new sections
  • Consequence: Requires Ruby runtime; adds minor build step to contribution workflow

• Does not provide executable code samples or a reference Objective-C project
• Does not cover Swift or modern iOS development frameworks
• Does not include automated testing or CI/CD for the documentation itself
• Does not track code metric analytics or style enforcement tools

• Avg cyclomatic complexity: ~2 — Repository contains primarily documentation and minimal scripting; no complex algorithms or business logic
• Largest file: README.md (1,200 lines)
• Estimated quality issues: ~0 — Repository is documentation-focused with minimal code; quality measured by content clarity and consistency rather than code metrics

• Manual TOC maintenance (Low) — README.md (before make_toc.rb automation): Risk of human error when manually updating table of contents anchors and links; script automation mitigates this

• README.md file size (Maintainability) — Single monolithic markdown file containing all topics; as guide grows, file becomes harder to navigate in editor
• make_toc.rb script reliability (Build automation risk) — Critical automation script; if parsing logic breaks with markdown changes, TOC generation fails silently

None significant for a documentation project. However, be aware that the guide's tone is prescriptive and opinionated (intentionally debatable, not dogmatic)—treat recommendations as guidelines, not absolute law. The Ruby TOC script depends on specific markdown header formatting; reformatting headers without updating the script will cause TOC misalignment. Also, this guide predates Swift by ~1 year and does not cover modern Objective-C or Swift interoperability.

• Yoda Conditions — This repo's flagship defensive coding pattern (e.g., if (5 == count) instead of if (count == 5))—a signature convention taught in the conditionals section to prevent accidental assignment in comparisons.
• Designated vs. Secondary Initializers — Core Objective-C pattern for initialization hierarchy; the guide details how to structure init methods, prevent infinite loops, and use -instancetype return type—critical for memory safety and API design.
• Blocks and Retain Cycles — Objective-C blocks are closures that capture self, creating memory leaks if not handled; this guide teaches __weak pattern and block debugging—essential for async code and avoiding crashes.
• Golden Path (Guard Clause Pattern) — Error-handling style emphasizing early returns to reduce nesting and improve readability; applied throughout the guide as a preferred alternative to deeply-nested if-else chains.
• Class Clusters — Abstract factory pattern in Objective-C where a public class vends private subclasses based on input; Apple uses this heavily (e.g., NSArray, NSString); the guide explains how to design and implement them.
• Lazy Loading — Deferred initialization pattern for expensive or conditional properties; the guide shows how to implement getter-based lazy loading with thread safety—improving app startup time and memory usage.
• Aspect-Oriented Programming (AOP) — Cross-cutting concerns like logging, caching, or analytics applied at method-call boundaries; Objective-C's dynamic runtime enables AOP via method swizzling—the guide introduces this advanced pattern.

• NYTimes/objective-c-style-guide — Peer Objective-C style guide from a major organization; useful for comparing conventions and understanding alternative perspectives on the same language.
• google/styleguide — Google's multi-language style guide includes Objective-C section; provides orthogonal best practices and conventions for comparison.
• raywenderlich/objective-c-style-guide — Ray Wenderlich's widely-adopted Objective-C style guide; complements Zen with tutorials and practical examples.
• realm/realm-swift — Modern Swift database library representing contemporary iOS development; shows how Objective-C principles evolved into Swift idioms.
• apple/swift-evolution — Swift's design rationale and roadmap; helps understand how Apple moved the ecosystem beyond Objective-C after this guide's creation.

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 automated Table of Contents generation in CI/CD

The repo contains scripts/make_toc.rb which appears to be a script for generating the table of contents, but there's no evidence of CI automation to validate or regenerate the README.md TOC. A new contributor could add a GitHub Action workflow that runs make_toc.rb on pull requests to detect when the TOC in README.md is out of sync with actual content sections, ensuring the extensive nested TOC (Conditionals, Case Statements, Naming, Class, etc.) stays current as the guide evolves.

• [ ] Create .github/workflows/validate-toc.yml GitHub Action
• [ ] Configure workflow to run scripts/make_toc.rb and compare output to README.md
• [ ] Add status check to fail PR if TOC is out of date
• [ ] Document the process in CONTRIBUTING.md (create if needed)

Add a comprehensive guide index/navigation page

The README shows a detailed table of contents with many nested sections (Conditionals → Yoda conditions, nil checks, Golden Path, etc.), but the actual content sections are truncated in the file listing. Create an index page or expand README with actual content anchors and brief summaries for each major section, making it easier for readers to jump to specific topics and for contributors to understand what content needs expansion.

• [ ] Audit README.md to identify all section headers and their current coverage
• [ ] Create index.md or expand README with clickable section summaries
• [ ] Ensure all section headers match the generated TOC from scripts/make_toc.rb
• [ ] Add cross-references between related sections (e.g., link nil checks to error handling)

Add image optimization and accessibility metadata

The images/ directory contains several assets (zen-logo-thumb.png, zen-logo-big.png, blocks_debugger.png, yoda.png) that are referenced in README.md. These images lack alt text attributes and may not be optimized for size/format. A new contributor could add proper alt text to all image references in README.md and create a script to validate and optimize PNG files, improving accessibility and page load performance.

• [ ] Audit all image references in README.md and add descriptive alt text to syntax
• [ ] Create scripts/optimize_images.sh to convert PNGs to WebP with fallbacks
• [ ] Add a pre-commit hook or CI check to validate alt text on all image references
• [ ] Document image guidelines in CONTRIBUTING.md

• Add a 'Swift Migration' or 'Objective-C ↔ Swift Interop' section to acknowledge the Swift era and guide developers maintaining mixed codebases (relevant since Swift 1.0 shipped in 2014).
• Expand the 'Error handling' subsection with more Real-World Examples: the current coverage is brief; add concrete NSError patterns, recovery suggestions, and modern error handling alternatives.
• Create a 'Quick Reference' cheat sheet (separate markdown file or appendix) summarizing the top 10 rules for developers who want a one-page summary instead of reading the full guide.

This is a documentation repository for Objective-C coding standards and best practices (Zen and the Art of the Objective-C Craftsmanship). The codebase contains no executable code, dependencies, or infrastructure components. No security vulnerabilities were identified. The repository consists primarily of markdown documentation and image assets. The minimal Ruby script for table of contents generation does not introduce security risks. This is a low-risk repository by nature.

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.