Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (84 loc) · 5.84 KB

AGENTS.md

File metadata and controls

109 lines (84 loc) · 5.84 KB

Repository Agent Instructions

This repository is a Just the Docs Jekyll site for the practical GenAI coding guide. Treat the Markdown content as the primary product and preserve the site structure unless a task explicitly requires a reorganization.

Codex Workflow Files

This repo uses the current Codex project structure:

  • AGENTS.md for repository instructions.
  • .codex/config.toml for project-level Codex settings.
  • .codex/agents/ for project-scoped custom subagents.
  • .agents/skills/ for reusable repo-specific skills.
  • .github/copilot-instructions.md for GitHub/Copilot editing contexts.

Agent Routing

Use these working modes for future agent tasks:

Agent mode Use for Required checks
docs-site-maintainer Jekyll configuration, navigation, GitHub Pages workflow, dependencies, build failures bundle exec jekyll build
content-editor Chapters, appendices, references, prose cleanup, broken links Build the site and inspect changed Markdown for front matter and link paths
template-curator Prompt templates, project plans, and R code template docs under docs/templates/ Keep prompt bodies in fenced code blocks when the page is meant for copy/paste
mermaid-designer Mermaid and non-Mermaid visual explanations Use the diagram decision matrix first; choose prose, tables, code blocks, screenshots, static figures, or other diagram tools when Mermaid is not the clearest medium
deep-research-content-updater Current/latest evidence gathering for GenAI coding, prompt, documentation, reproducibility, and tooling updates Browse current sources, cite links, and produce an evidence memo before editing
reference-auditor Citation integrity, source availability, link rot, and claim-source alignment Verify URLs and source content; report support status before editing
script-maintainer scripts/ changes, especially simulate_ehr_data.R Run a narrow script smoke test when R and required packages are available
release-verifier Final pre-merge checks, Pages deployment readiness, repository hygiene Build locally, check git status --short, and verify generated files stay ignored

Project-scoped custom subagents are defined in .codex/agents/:

  • docs-site-maintainer: Jekyll, Just the Docs, GitHub Pages, dependency, navigation, build, and preview work.
  • content-reviewer: read-only review of prose, links, front matter, and template rendering.
  • mermaid-designer: visual-selection and Mermaid/non-Mermaid diagram design work.
  • mermaid-reviewer: read-only review of Mermaid diagrams, visual-format selection, and accessibility.
  • deep-research-content-updater: read-only current-source research for evidence-backed content updates.
  • reference-auditor: read-only citation, link-health, and claim-support audit work.

Reusable repo skills are defined in .agents/skills/:

  • just-the-docs-site
  • prompt-template-curation
  • mermaid-workflow-diagrams
  • deep-research-content-updates
  • reference-source-audit

For current-source research, the deep research agent should produce a research memo first. Do not let "latest tips and tricks" turn into unsourced content churn. For reference audits, the reference auditor should report evidence issues first and leave content rewrites to a content editor unless explicitly asked.

Project Conventions

  • Build the documentation site from the repository root.
  • Keep README.md GitHub-facing and index.md site-facing.
  • Keep the manuscript in the existing chapters/, docs/, docs/templates/, and scripts/ paths so existing links continue to work.
  • Add rendered Markdown pages with this front matter pattern:
---
layout: default
title: "Page Title"
parent: Parent Page
nav_order: 1
---
  • Use nav_exclude: true for raw templates that should not clutter the sidebar.
  • Use has_toc: false on parent landing pages when Just the Docs' automatic child list duplicates hand-curated page links.
  • Do not add manual bottom-of-page navigation blocks unless the page needs a non-sidebar reading path.
  • Keep prompt templates copy/paste friendly by rendering the prompt body as a fenced markdown code block.
  • For Mermaid diagrams:
    • First decide whether a diagram is better than prose, an ordered list, a table, a fenced code block, screenshot, static figure, R-generated chart, Graphviz/DOT, D2, Structurizr/C4, or hand-authored SVG.
    • Use the diagram repository in .agents/skills/mermaid-workflow-diagrams/SKILL.md before choosing a syntax.
    • Check _config.yml for the pinned Mermaid version before using newer diagram types or syntax.
    • Use flowchart TB for long, branch-heavy, or feedback-loop diagrams.
    • Use flowchart LR only for compact linear pipelines that fit comfortably in the content column.
    • Include accTitle and accDescr in every Mermaid diagram.
    • Keep diagrams explanatory; do not add them as decoration.

Toolchain

The site uses:

  • Ruby 3.3, declared in .ruby-version
  • Jekyll ~> 4.4.1
  • just-the-docs 0.12.0
  • jekyll-relative-links
  • GitHub Pages Actions via .github/workflows/pages.yml

Use Bundler rather than installing unpinned global Jekyll gems:

bundle install
bundle exec jekyll build
bundle exec jekyll serve --host 127.0.0.1 --port 4000

On machines where Conda or Miniforge exports compiler variables, native gem builds may fail. Run Bundler/Jekyll with those variables unset:

env -u CC -u CXX -u LD -u LDFLAGS -u CPPFLAGS -u CFLAGS PATH=/opt/homebrew/opt/ruby@3.3/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin bundle exec jekyll build

Git Hygiene

  • Do not commit _site/, .jekyll-cache/, .bundle/, vendor/bundle/, or .DS_Store.
  • Do not revert unrelated user changes.
  • Preserve Gemfile.lock after dependency changes.
  • Prefer rg for search.
  • Keep edits scoped to the task and avoid broad prose rewrites unless requested.