Skip to content

Latest commit

 

History

History
436 lines (292 loc) · 10.1 KB

HELP.md

File metadata and controls

436 lines (292 loc) · 10.1 KB

🛠️ Developer Setup Checklist

Use the following to-do list to get awesome-agentic-patterns up and running on your local machine. Tick each checkbox as you complete the step.

1. Clone & Prepare the Repository

  • Fork the repository (optional). If you plan to contribute patterns or push changes, fork nibzard/awesome-agentic-patterns to your own GitHub account.

  • Clone the repository to your local machine.

    git clone https://github.com/<your-username>/awesome-agentic-patterns.git
# OR, if you’re working from the upstream repo directly:
git clone https://github.com/nibzard/awesome-agentic-patterns.git

  • Enter the project directory.

    cd awesome-agentic-patterns

  • (Recommended) Create a Python virtual environment.

    python3 -m venv .venv
# On Windows:
# python -m venv .venv

    • Activate the virtual environment:

      • macOS/Linux:

        source .venv/bin/activate

      • Windows (PowerShell):

        .\.venv\Scripts\Activate.ps1

2. Install Dependencies

  • Install project requirements.

    pip install --upgrade pip
pip install -r requirements.txt

    • This will install:

      • mkdocs==1.0.4
      • mkdocs-material==4.0.2

  • Verify that MkDocs is installed correctly.

    mkdocs --version

    • You should see output similar to:

      mkdocs, version 1.0.4 from ... (Python 3.x)

3. Link README to MkDocs

  • Ensure README.md is symlinked to docs/index.md. The Makefile provides a shortcut to create this link:

    make site_link

    • This runs:

      ln -sf $(CURDIR)/README.md $(CURDIR)/docs/index.md

    • You can verify that docs/index.md points to the same content as README.md.

4. Explore Directory Structure

  • Review the top-level files:

    • CONTRIBUTING.md – Contribution guidelines.
    • LICENSE – Apache 2.0 license.
    • Makefile – Common targets for building/deploying the site.
    • mkdocs.yaml – MkDocs configuration.
    • requirements.txt – Python libraries required.
    • scripts/build_readme.py – Regenerates README tables and MkDocs nav.

  • Inspect the main folders:

    • patterns/ (create if missing) – where individual pattern .md files will live.
    • scripts/ – helper scripts (e.g., build_readme.py to regenerate the README and nav).
    • docs/ – MkDocs site content (note: docs/index.md is auto-symlinked to the README).
    • overrides/ – MkDocs theme overrides (includes inline badge styling).

5. Build & Preview the MkDocs Site Locally

  • Build the site (optional).

    python scripts/build_readme.py
    • This generates static files in the site/ directory but does not serve them.

  • Preview the site in “live-reload” mode.

    make site_preview
    • This runs mkdocs serve and opens a local server (usually at http://127.0.0.1:8000/).
    • Tip: As you edit README.md or any patterns/*.md, the site will automatically reload.

  • (Optional) Test the generated HTML. In a separate terminal (or after stopping mkdocs serve), run:

    make site_build

    Then open site/index.html in your browser to verify the static output.

6. Add Your First Pattern

If you’re just exploring, skip to “Finalize Setup.” If you want to verify that the automation works, do the following:

  • Create a new Markdown file under patterns/.

    mkdir -p patterns
touch patterns/my-first-pattern.md

    • Use this minimal front-matter template inside patterns/my-first-pattern.md:

      ---
title: My First Pattern
status: 🔬 validated-in-production
authors: ["Your Name"]
source: "https://example.com/my-first-pattern"
tags: [example, agentic, demo]
---

## Problem
Describe the real-world problem that multiple teams encounter…

## Solution
Explain the core idea of how an AI agent solves it…

## Example (pseudo-flow)
```mermaid
sequenceDiagram
  User->>Agent: "Do something important"
  Agent->>Tool: run `some-tool`
  …

      References

      • Blog: My Demo of Agentic Patterns – Published on 2025-05-30

  • Run the build script to regenerate the README & nav. If the repository already contains scripts/build_readme.py, execute:

    python scripts/build_readme.py

    • What this does:

      • Scans all .md files in patterns/
      • Extracts their YAML front-matter (title, status, tags, source)
      • Updates the “Quick Tour of Categories” tables in README.md
      • Syncs the nav: section in mkdocs.yaml so your new pattern appears in the site nav automatically

  • Confirm that your new pattern shows up in the README & site.

    • Re-run:

      make site_preview

    • Visit http://127.0.0.1:8000/ and verify that:

      1. Your pattern title appears in the appropriate category table.
      2. A new item was added to the left-hand navigation (via MkDocs Material).

7. Finalize Setup & Create a Branch

  • Ensure you are on a clean main (or master) branch.

    git checkout main
git pull origin main

  • Create a feature branch for your work.

    git checkout -b my-feature-branch

    • For example, if you plan to add multiple patterns or scripts, name the branch accordingly:

      git checkout -b add-inversion-of-control-pattern

  • Commit your local changes.

    git add .
git commit -m "feat: add my first agentic pattern"

  • Push your branch to GitHub.

    git push origin my-feature-branch

8. (Optional) Regenerate README & MkDocs Nav

The README tables and MkDocs nav are auto-generated from patterns/ via scripts/build_readme.py.

  • Regenerate the docs.

    python scripts/build_readme.py
    • This will:
      • Update the auto-generated sections in README.md
      • Refresh the mkdocs.yaml nav block
      • Apply NEW/UPDATED badges based on git history

  • Review the changes:

    git diff README.md mkdocs.yaml

  • If everything looks correct, commit the updates:

    git add README.md mkdocs.yaml
git commit -m "chore: regenerate README + mkdocs nav"

9. Verify & Deploy

  • Run a final preview to ensure no build errors.

    make site_preview
    • Fix any Markdown warnings or broken links that MkDocs reports.

  • Lint pattern front-matter (recommended).

    make lint_front_matter

  • (If you have write access) Trigger the GitHub Action.

    • Pushing to main (or merging your branch via a PR) should invoke the “Build & Deploy” workflow:

      • python scripts/build_readme.py
      • mkdocs gh-deploy --clean

    • Check the Actions tab in GitHub to verify a successful deploy to https://agentic-patterns.com.

  • Review the live site at https://agentic-patterns.com to confirm your changes are published.

10. (Optional) Set Up Tag Index & Search

This step is optional but recommended if you plan to aggregate patterns by tag.

  • Create a docs/tags.md file.

    touch docs/tags.md

    • Populate it with a short heading, e.g.:

      # All Tags

This page will list every tag and link to patterns in that category.

  • Write or reuse a script to generate “tags index.” Example pseudocode logic:

    1. Parse all front-matter from patterns/*.md.

    2. Build a dictionary: { tag_name: [ (pattern_title, pattern_slug), … ] }.

    3. Render Markdown sections:

      ## orchestration
- [Inversion of Control](patterns/inversion-of-control.md)
- [Sub-Agent Spawning](patterns/sub-agent-spawning.md)

## memory
- [Sliding-Window Curation](patterns/sliding-window-curation.md)

    4. Write the combined output back to docs/tags.md.

    5. Update mkdocs.yaml to include:

      nav:
  - "Life is short, you need patterns.": "index.md"
  - Tags: "tags.md"
  # … other auto-generated entries …
    • Run the tag-generation script (if implemented) and verify docs/tags.md visually.

11. Pattern Badge System (Git-Based)

The repository labels patterns as NEW or UPDATED based on git history.

How It Works

  • NEW: Pattern created within the last 7 days
  • UPDATED: Pattern created >7 days ago but modified within the last 14 days
  • Source of truth: Git commit history (no tracker files)

Commands

  • View current labels:

    make show_labels

  • Debug a specific pattern:

    make debug_pattern

  • Regenerate docs with badges:

    python scripts/build_readme.py

Notes

  • Patterns must be committed for labels to appear.
  • Labels expire automatically based on commit dates.

12. Housekeeping & Maintenance

  • Clean up untracked files.

    git status
git clean -fd

  • Ensure .gitignore is up to date. Typical entries:

    .venv/
__pycache__/
site/
*.pyc
*.pyo
.DS_Store
    • If missing, add .gitignore in the project root and commit it.

  • Review open issues and pull requests.

    • Identify any unmerged patterns or build errors reported by CI.
    • Triage issues by applying labels: proposal, needs-example, ready, duplicate.

  • Schedule periodic cleanup.

    • Decide on a cadence (e.g., every quarter) to:

      • Deprecate or archive stale patterns (tag them as ❌ deprecated in front-matter).
      • Merge similar patterns (to avoid duplication).
      • Audit broken links or outdated sources.

🎉 Congratulations! You now have a fully working local copy of awesome-agentic-patterns.

  • Feel free to add new patterns, refine existing ones, and enjoy a live preview of the MkDocs site at each step.
  • When you’re ready, open a Pull Request—our GitHub Actions will regenerate and deploy the site automatically.

Happy pattern hunting! 🚀