Skip to content

Commit 080ab2c

Browse files
claudeclaude
committed
Add context files agent, MkDocs docs, and repo AGENTS.md
Context files agent: - prompts/context_files_prompt.md — verbatim prompt for generating / updating AGENTS.md and CLAUDE.md; uses $ARGUMENTS substitution for mode (auto/quick-start/update/evaluate) and scope - .github/workflows/context_files_agent.yml — reusable workflow_call; accepts agent_args (mode+scope) and prompt_override; needs contents: write to commit context files back to PR branches - .github/workflows/context_files_pr.yml — caller workflow triggered on pull_request opened + ready_for_review MkDocs documentation site: - mkdocs.yml — Material theme, nav covering all pages - .github/workflows/docs.yml — build-check on PRs, gh-deploy on main - docs/index.md — overview and architecture diagram - docs/user-stories.md — solo dev, team lead, DevEx engineer stories - docs/using.md — step-by-step setup, trigger table, prompt override guide - docs/contributing.md — three-file pattern for adding a new agent - docs/agents/index.md — agent catalog and shared design principles - docs/agents/pr-review.md — review agent triggers, caller snippet, prompt - docs/agents/context-files.md — context agent modes, agent_args, permissions Repo context files (generated via context files prompt logic): - AGENTS.md — WHY/WHAT/HOW, repo map, validated commands, gotchas - CLAUDE.md — symlink to AGENTS.md (Claude Code auto-discovery) - .gitignore — remove CLAUDE.md exclusion so symlink is tracked https://claude.ai/code/session_018moumKtzZQiSiyGxVUFGdS
1 parent d02f7d0 commit 080ab2c

15 files changed

Lines changed: 1335 additions & 1 deletion

‎.github/workflows/context_files_agent.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Context files agent (AGENTS.md / CLAUDE.md)
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
agent_args:
7+
description: >
8+
Arguments passed to the context files prompt (mode + scope).
9+
Defaults to "auto ." which runs in auto mode on the repo root.
10+
type: string
11+
required: false
12+
default: "auto ."
13+
prompt_override:
14+
description: >
15+
Full prompt text to use instead of the default context files prompt.
16+
Overrides agent_args when set.
17+
type: string
18+
required: false
19+
default: ""
20+
secrets:
21+
ANTHROPIC_API_KEY:
22+
required: true
23+
24+
jobs:
25+
context-files:
26+
runs-on: ubuntu-latest
27+
permissions:
28+
contents: write
29+
pull-requests: write
30+
issues: write
31+
32+
steps:
33+
# Checkout the *target repository* so Claude can read the codebase.
34+
- name: Checkout target repo
35+
uses: actions/checkout@v4
36+
37+
# Checkout this workflow repo to read the prompt template.
38+
- name: Checkout workflow repo (for prompt)
39+
uses: actions/checkout@v4
40+
with:
41+
repository: safurrier/python-collab-template
42+
path: _ai_workflows
43+
44+
- name: Load prompt
45+
id: prompt
46+
shell: bash
47+
run: |
48+
if [ -n "${{ inputs.prompt_override }}" ]; then
49+
echo "text<<EOF" >> "$GITHUB_OUTPUT"
50+
printf "%s\n" "${{ inputs.prompt_override }}" >> "$GITHUB_OUTPUT"
51+
echo "EOF" >> "$GITHUB_OUTPUT"
52+
else
53+
ARGS="${{ inputs.agent_args }}"
54+
echo "text<<EOF" >> "$GITHUB_OUTPUT"
55+
sed "s|\$ARGUMENTS|${ARGS}|g" \
56+
_ai_workflows/prompts/context_files_prompt.md >> "$GITHUB_OUTPUT"
57+
echo "EOF" >> "$GITHUB_OUTPUT"
58+
fi
59+
60+
- name: Run context files agent
61+
uses: anthropics/claude-code-action@v1
62+
with:
63+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
64+
prompt: ${{ steps.prompt.outputs.text }}

‎.github/workflows/context_files_pr.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Context files agent (PR opened / Draft->Ready)
2+
3+
on:
4+
pull_request:
5+
types: [opened, ready_for_review]
6+
7+
concurrency:
8+
group: context-files-agent-${{ github.repository }}-${{ github.event.pull_request.number }}
9+
cancel-in-progress: true
10+
11+
jobs:
12+
context-files:
13+
if: ${{ github.event.pull_request.draft == false }}
14+
uses: safurrier/python-collab-template/.github/workflows/context_files_agent.yml@v1
15+
secrets:
16+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
17+
# Optional: pass explicit mode/scope or a full prompt override:
18+
# with:
19+
# agent_args: "auto src/"
20+
# prompt_override: |
21+
# <custom prompt text>

‎.github/workflows/docs.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- "mkdocs.yml"
9+
pull_request:
10+
branches: [main]
11+
paths:
12+
- "docs/**"
13+
- "mkdocs.yml"
14+
15+
jobs:
16+
deploy:
17+
if: github.event_name == 'push'
18+
runs-on: ubuntu-latest
19+
permissions:
20+
contents: write
21+
steps:
22+
- uses: actions/checkout@v4
23+
- uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.12"
26+
- run: pip install mkdocs-material
27+
- run: mkdocs gh-deploy --force
28+
29+
build-check:
30+
if: github.event_name == 'pull_request'
31+
runs-on: ubuntu-latest
32+
steps:
33+
- uses: actions/checkout@v4
34+
- uses: actions/setup-python@v5
35+
with:
36+
python-version: "3.12"
37+
- run: pip install mkdocs-material
38+
- run: mkdocs build --strict

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
.idea/
33
.vs_code/*
44
.aider*
5-
CLAUDE.md
65

76
# GitHub Actions local runner (act)
87
.actrc

‎AGENTS.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# AGENTS.md
2+
3+
## WHY — What this repo is
4+
5+
Central GitHub Actions workflow host for **Claude PR agents** — reusable, prompt-driven automation that attaches to pull requests. Instead of duplicating workflow logic across repos, any target repo references this one with a single `uses:` line and gets automated code review, context file generation, or any other Claude-powered task.
6+
7+
The repo is intentionally minimal: workflow YAML, prompt files, and documentation. No build system, no runtime dependencies.
8+
9+
---
10+
11+
## WHAT — Repo map
12+
13+
```
14+
.github/workflows/
15+
claude_pr_review.yml # Reusable: code review agent (workflow_call)
16+
context_files_agent.yml # Reusable: AGENTS.md / CLAUDE.md generator (workflow_call)
17+
ai_pr_review.yml # Caller example: code review for this repo
18+
context_files_pr.yml # Caller example: context files agent for this repo
19+
docs.yml # MkDocs build + GitHub Pages deploy
20+
21+
prompts/
22+
codex_code_review_prompt.md # Verbatim Codex Code Review prompt (OpenAI cookbook)
23+
context_files_prompt.md # Context files generator/updater prompt
24+
25+
docs/ # MkDocs documentation site source
26+
index.md # Overview and architecture
27+
user-stories.md # Who uses this and why
28+
using.md # Step-by-step setup for target repos
29+
contributing.md # How to add a new agent
30+
agents/
31+
index.md # Agent catalog
32+
pr-review.md # Code review agent docs
33+
context-files.md # Context files agent docs
34+
```
35+
36+
---
37+
38+
## HOW — How to work here
39+
40+
### Adding a new agent
41+
42+
1. Create `prompts/<name>.md` — the Claude instruction text
43+
2. Create `.github/workflows/<name>.yml` — copy an existing reusable workflow, swap the prompt filename, adjust permissions if the agent writes files
44+
3. Create `docs/agents/<name>.md` — trigger table, caller snippet, customization options
45+
4. Add entry to `docs/agents/index.md` and `mkdocs.yml` nav
46+
5. Tag a new release: `git tag vX.Y && git push origin vX.Y`
47+
48+
See `docs/contributing.md` for the full checklist.
49+
50+
### Updating a prompt
51+
52+
Edit the file in `prompts/`. Bump the version tag so target repos can opt in to the updated prompt on their own schedule.
53+
54+
### Working on docs
55+
56+
```bash
57+
# Preview locally (requires mkdocs-material)
58+
pip install mkdocs-material
59+
mkdocs serve
60+
```
61+
⏸️ Not executed — requires network install. Confirm `mkdocs.yml` exists: ✅
62+
63+
```bash
64+
# Strict build (catches broken links, missing pages)
65+
mkdocs build --strict
66+
```
67+
⏸️ Not executed — same prerequisite.
68+
69+
### Validating workflow YAML
70+
71+
```bash
72+
yamllint .github/workflows/
73+
```
74+
⏸️ Not executed — `yamllint` not confirmed in this environment. Workflows are validated by GitHub Actions on push.
75+
76+
---
77+
78+
## Common commands (validated)
79+
80+
| Command | Status | Notes |
81+
|---|---|---|
82+
| `mkdocs serve` | ⏸️ not executed | Requires `pip install mkdocs-material`; run from repo root |
83+
| `mkdocs build --strict` | ⏸️ not executed | Same prerequisite; used in CI (`docs.yml`) |
84+
| `git tag vX.Y && git push origin vX.Y` | ⏸️ not executed | Release process; target repos pin to these tags |
85+
86+
No test suite, linter, or build step for the workflows themselves — validation happens when GitHub Actions parses them on push.
87+
88+
---
89+
90+
## Progressive disclosure
91+
92+
- `docs/using.md` — full setup walkthrough for target repos
93+
- `docs/contributing.md` — step-by-step agent contribution guide
94+
- `docs/agents/pr-review.md` — code review agent: triggers, prompt override, permissions
95+
- `docs/agents/context-files.md` — context files agent: modes, `agent_args`, permissions
96+
- `.github/workflows/claude_pr_review.yml` — canonical source for reusable workflow structure
97+
- `prompts/context_files_prompt.md` — canonical source for context files prompt spec
98+
99+
---
100+
101+
## Gotchas
102+
103+
- **Repo rename breaks callers**: the reusable workflows hard-code `repository: safurrier/python-collab-template` to check out the prompt files. If this repo is renamed, update that field in every reusable workflow.
104+
- **Private repo access**: if this repo is private, target repos must be granted access via Settings → Actions → Access → "Accessible from repositories in your account".
105+
- **Tag before using**: target repos reference `@v1` (or another tag). Push a tag before pointing any repo at this one.
106+
- **`contents: write` scope**: the context files agent needs `contents: write` to commit `AGENTS.md` / `CLAUDE.md`. The review agent only needs `read`.
107+
- **`$ARGUMENTS` substitution**: the context files prompt uses a `$ARGUMENTS` placeholder that the workflow substitutes via `sed` at runtime. Do not treat it as a shell variable in the prompt file itself.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎docs/agents/context-files.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Context Files Agent
2+
3+
Keeps `AGENTS.md` and `CLAUDE.md` up to date in a repository. When these files are missing, Claude generates them from scratch. When they exist, Claude audits and updates them to reflect the current codebase.
4+
5+
## Files
6+
7+
| File | Path |
8+
|---|---|
9+
| Reusable workflow | `.github/workflows/context_files_agent.yml` |
10+
| Prompt | `prompts/context_files_prompt.md` |
11+
12+
## What it does
13+
14+
Claude reads the repo structure, config files, CI workflows, and any existing context docs, then:
15+
16+
1. **If no context files exist** (`auto` → `quick-start` mode): generates `AGENTS.md` with a WHY/WHAT/HOW structure and creates `CLAUDE.md` as a symlink
17+
2. **If files already exist** (`auto` → `update + evaluate` mode): validates commands, removes stale content, improves conciseness, and creates nested `AGENTS.md` files for subdirectories with distinct workflows
18+
3. **Commits the result** directly to the PR branch so the updated context files are part of the PR
19+
20+
The prompt follows a strict principle: **validate what you write**. Every command in the generated docs is confirmed to exist in Makefiles, CI configs, or package manifests before being included.
21+
22+
## Output files
23+
24+
| File | Role |
25+
|---|---|
26+
| `AGENTS.md` | Source of truth for agent onboarding — WHY/WHAT/HOW, validated commands, progressive disclosure pointers |
27+
| `CLAUDE.md` | Symlink to `AGENTS.md` (Claude Code auto-discovers `CLAUDE.md` files when navigating a repo) |
28+
| `ai_agent_docs/*.md` | Cross-cutting topic docs (architecture, conventions, etc.) created when content warrants it |
29+
| `<subdir>/AGENTS.md` | Nested docs for subdirectories with their own distinct tooling |
30+
31+
## Triggers
32+
33+
| Event | Runs? |
34+
|---|---|
35+
| PR first opened (non-draft) | Yes |
36+
| PR marked Ready for review | Yes |
37+
| New commits pushed to open PR | No (use review agent for that) |
38+
| Draft PR | No |
39+
40+
## Minimal caller workflow
41+
42+
```yaml
43+
name: Context files agent
44+
45+
on:
46+
pull_request:
47+
types: [opened, ready_for_review]
48+
49+
concurrency:
50+
group: context-files-${{ github.repository }}-${{ github.event.pull_request.number }}
51+
cancel-in-progress: true
52+
53+
jobs:
54+
context-files:
55+
if: ${{ github.event.pull_request.draft == false }}
56+
uses: safurrier/python-collab-template/.github/workflows/context_files_agent.yml@v1
57+
secrets:
58+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
59+
```
60+
61+
## Customizing scope or mode
62+
63+
Use `agent_args` to change which directory Claude targets or which mode it runs in:
64+
65+
```yaml
66+
with:
67+
agent_args: "auto src/" # scope to src/ only
68+
# agent_args: "quick-start ." # always generate fresh, never update
69+
# agent_args: "evaluate ." # audit and propose improvements, report in chat
70+
```
71+
72+
Modes:
73+
74+
| Mode | Behavior |
75+
|---|---|
76+
| `auto` (default) | Generate if missing; update + evaluate if present. No confirmation prompts. |
77+
| `quick-start` | Always generate from scratch. Asks before overwriting. |
78+
| `update` | Update existing files only. |
79+
| `evaluate` | Audit files against quality principles and propose improvements. |
80+
81+
## Full prompt override
82+
83+
To replace the entire prompt (e.g., for a simpler or domain-specific context file format):
84+
85+
```yaml
86+
with:
87+
prompt_override: |
88+
Look at this repo and create AGENTS.md with:
89+
1. A one-sentence description of what the repo does
90+
2. How to run tests
91+
3. How to run the linter
92+
Keep it under 30 lines.
93+
```
94+
95+
## Permissions
96+
97+
```yaml
98+
permissions:
99+
contents: write # needed to commit AGENTS.md / CLAUDE.md to the branch
100+
pull-requests: write
101+
issues: write
102+
```
103+
104+
Unlike the review agent, this one needs `contents: write` because it commits files.

‎docs/agents/index.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Agents
2+
3+
Each agent is a self-contained pair of files:
4+
5+
| File | Purpose |
6+
|---|---|
7+
| `prompts/<name>.md` | The instruction text sent to Claude |
8+
| `.github/workflows/<name>.yml` | The reusable `workflow_call` that loads the prompt and runs the action |
9+
10+
Target repos reference the reusable workflow with a `uses:` line and supply `ANTHROPIC_API_KEY`. The prompt loading, checkout, and Claude invocation all happen inside the reusable workflow here.
11+
12+
---
13+
14+
## Available agents
15+
16+
| Agent | Reusable workflow | Prompt file |
17+
|---|---|---|
18+
| [PR Code Review](pr-review.md) | `claude_pr_review.yml` | `codex_code_review_prompt.md` |
19+
| [Context Files](context-files.md) | `context_files_agent.yml` | `context_files_prompt.md` |
20+
21+
---
22+
23+
## Shared design principles
24+
25+
**Every agent:**
26+
27+
- Accepts a `prompt_override` input so any repo can swap in custom instructions without forking
28+
- Uses the same checkout pattern: target repo first, then this workflow repo for the prompt
29+
- Runs on `ubuntu-latest` with least-privilege permissions (only escalating `contents` to `write` when the agent needs to commit files)
30+
- Can be called independently — agents don't depend on each other
31+
32+
**Prompt files** live in `prompts/` and are loaded at runtime, not embedded in the workflow YAML. This means you can update a prompt and tag a new release without touching any workflow logic.

0 commit comments

Comments
 (0)