Skip to content

Commit 458de74

Browse files
lukeocodeslukeocodes
committed
feat(init): scaffold autonomous agent-maintained examples repository
Sets up the full lifecycle for autonomous example creation, review, fix, and merge: - instructions/ — agent prompts for discover, create, review, fix - .github/workflows/ — scheduled discovery, daily creation, PR review, fix-on-label, per-language test runners (node/python/go), daily maintenance tests of all existing examples, README auto-update on merge - .github/ISSUE_TEMPLATE/ — queue new example, report broken example - examples/010-getting-started-node/ — seed example demonstrating the credential-check convention and full required file structure Agent workflows use claude-code-action with claude-opus-4-6. Test workflows are native CI (no AI spend on reliability gates). Auto-merge activates on passing checks; missing-credentials PRs stay open with a comment tagging @deepgram-devrel.
0 parents  commit 458de74

24 files changed

Lines changed: 2689 additions & 0 deletions

‎.github/ISSUE_TEMPLATE/queue-new-example.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: "Queue: New Example"
2+
description: Request a new example app to be built by the agent
3+
labels: ["queue:new-example"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
The agent will pick this up on its next daily run and build the example.
9+
Fill in as much detail as you can — more context produces better examples.
10+
11+
- type: input
12+
id: integration
13+
attributes:
14+
label: Integration
15+
description: What platform, framework, or ecosystem should this example use?
16+
placeholder: e.g. "Twilio Voice", "LangChain", "Next.js + Vercel AI SDK"
17+
validations:
18+
required: true
19+
20+
- type: dropdown
21+
id: language
22+
attributes:
23+
label: Language
24+
description: Which language should the example be in?
25+
options:
26+
- Node.js / TypeScript
27+
- Python
28+
- Go
29+
- Rust
30+
- .NET / C#
31+
- Java
32+
- Ruby
33+
- Other (describe below)
34+
validations:
35+
required: true
36+
37+
- type: checkboxes
38+
id: products
39+
attributes:
40+
label: Deepgram products
41+
description: Which Deepgram products should this example demonstrate?
42+
options:
43+
- label: Speech-to-text (STT)
44+
- label: Text-to-speech (TTS)
45+
- label: Voice agents
46+
- label: Audio intelligence
47+
48+
- type: textarea
49+
id: description
50+
attributes:
51+
label: What should this example do?
52+
description: Describe the use case. What does a developer build with this?
53+
placeholder: |
54+
e.g. "Transcribe incoming Twilio voice calls in real-time using Deepgram STT
55+
and display the live transcript in a browser dashboard."
56+
validations:
57+
required: true
58+
59+
- type: textarea
60+
id: references
61+
attributes:
62+
label: Reference links
63+
description: Links to the integration's docs, SDK, or relevant examples
64+
placeholder: |
65+
- https://www.twilio.com/docs/voice/media-streams
66+
- https://developers.deepgram.com/docs/getting-started-with-live-streaming-audio
67+
68+
- type: textarea
69+
id: env_vars
70+
attributes:
71+
label: Required credentials
72+
description: List any environment variables you know will be needed
73+
placeholder: |
74+
- DEEPGRAM_API_KEY
75+
- TWILIO_ACCOUNT_SID
76+
- TWILIO_AUTH_TOKEN

‎.github/ISSUE_TEMPLATE/report-broken-example.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: "Report: Broken Example"
2+
description: Report that an existing example is failing or outdated
3+
labels: ["queue:fix-example", "type:fix"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
The agent will investigate and fix this on its next run.
9+
10+
- type: input
11+
id: example
12+
attributes:
13+
label: Which example?
14+
description: The example directory name
15+
placeholder: "e.g. examples/010-getting-started-node"
16+
validations:
17+
required: true
18+
19+
- type: dropdown
20+
id: failure_type
21+
attributes:
22+
label: Type of failure
23+
options:
24+
- Test failing in CI
25+
- Outdated SDK version / deprecated API
26+
- Documentation is wrong or unclear
27+
- Code doesn't run locally
28+
- Other
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: description
34+
attributes:
35+
label: What's broken?
36+
description: Describe what's failing and any error messages
37+
placeholder: |
38+
The test fails with:
39+
```
40+
Error: Cannot find module '@deepgram/sdk'
41+
```
42+
validations:
43+
required: true
44+
45+
- type: textarea
46+
id: context
47+
attributes:
48+
label: Additional context
49+
description: Any other relevant information (Node.js version, OS, etc.)

‎.github/workflows/create-example.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Create Example
2+
3+
on:
4+
issues:
5+
types: [opened, labeled]
6+
schedule:
7+
- cron: '30 9 * * *' # Daily 09:30 UTC — drain the queue
8+
workflow_dispatch:
9+
inputs:
10+
integration:
11+
description: 'Integration to build (e.g. "Twilio Voice + Node.js")'
12+
required: false
13+
14+
concurrency:
15+
group: create-example
16+
cancel-in-progress: false
17+
18+
permissions:
19+
contents: write
20+
pull-requests: write
21+
issues: write
22+
23+
jobs:
24+
# Only run for issues with the right label (on issue events)
25+
check:
26+
runs-on: ubuntu-latest
27+
outputs:
28+
should_run: ${{ steps.check.outputs.should_run }}
29+
steps:
30+
- name: Check trigger
31+
id: check
32+
run: |
33+
EVENT="${{ github.event_name }}"
34+
LABEL="${{ github.event.label.name }}"
35+
ISSUE_LABEL=$(echo '${{ toJSON(github.event.issue.labels) }}' | jq -r '.[].name' | grep -c "queue:new-example" || true)
36+
37+
if [ "$EVENT" = "schedule" ] || [ "$EVENT" = "workflow_dispatch" ]; then
38+
echo "should_run=true" >> $GITHUB_OUTPUT
39+
elif [ "$EVENT" = "issues" ] && [ "$ISSUE_LABEL" -gt 0 ]; then
40+
echo "should_run=true" >> $GITHUB_OUTPUT
41+
else
42+
echo "should_run=false" >> $GITHUB_OUTPUT
43+
fi
44+
45+
create:
46+
needs: check
47+
if: needs.check.outputs.should_run == 'true'
48+
runs-on: ubuntu-latest
49+
steps:
50+
- uses: actions/checkout@v4
51+
with:
52+
fetch-depth: 0
53+
54+
- name: Configure git
55+
run: |
56+
git config user.name "dx-examples-bot"
57+
git config user.email "noreply@deepgram.com"
58+
59+
- name: Get date
60+
id: date
61+
run: echo "date=$(date -u +%Y-%m-%d)" >> $GITHUB_OUTPUT
62+
63+
- name: Run create agent
64+
uses: anthropics/claude-code-action@beta
65+
with:
66+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
67+
github_token: ${{ secrets.GITHUB_TOKEN }}
68+
mode: agent
69+
model: claude-opus-4-6
70+
allowed_tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch"
71+
direct_prompt: |
72+
Read and execute the instructions in `instructions/create-example.md`.
73+
74+
Context:
75+
- Today's date: ${{ steps.date.outputs.date }}
76+
- Repository: ${{ github.repository }}
77+
- Run ID: ${{ github.run_id }}
78+
- Trigger: ${{ github.event_name }}
79+
- Issue number (if triggered by issue): ${{ github.event.issue.number }}
80+
- Issue title (if triggered by issue): ${{ github.event.issue.title }}
81+
- Manual integration input: ${{ inputs.integration }}
82+
83+
Process up to 3 queued examples from open issues labelled `queue:new-example`.
84+
If no queue items exist and this is a scheduled run, pick a high-value integration
85+
from the discovery categories in `instructions/discover-examples.md`.

‎.github/workflows/discover-examples.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Discover Examples
2+
3+
on:
4+
schedule:
5+
- cron: '7 9 * * 1' # Monday 09:07 UTC — weekly
6+
workflow_dispatch:
7+
8+
concurrency:
9+
group: discover-examples
10+
cancel-in-progress: false
11+
12+
permissions:
13+
contents: write
14+
pull-requests: write
15+
issues: write
16+
17+
jobs:
18+
discover:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0
24+
25+
- name: Configure git
26+
run: |
27+
git config user.name "dx-examples-bot"
28+
git config user.email "noreply@deepgram.com"
29+
30+
- name: Get date
31+
id: date
32+
run: echo "date=$(date -u +%Y-%m-%d)" >> $GITHUB_OUTPUT
33+
34+
- name: Run discovery agent
35+
uses: anthropics/claude-code-action@beta
36+
with:
37+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
38+
github_token: ${{ secrets.GITHUB_TOKEN }}
39+
mode: agent
40+
model: claude-opus-4-6
41+
allowed_tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch"
42+
direct_prompt: |
43+
Read and execute the instructions in `instructions/discover-examples.md`.
44+
45+
Context:
46+
- Today's date: ${{ steps.date.outputs.date }}
47+
- Repository: ${{ github.repository }}
48+
- Run ID: ${{ github.run_id }}
49+
50+
After discovering new integrations, also read and execute
51+
`instructions/create-example.md` for the top 2 highest-priority
52+
integrations you identified.

‎.github/workflows/fix-pr.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Fix PR
2+
3+
on:
4+
pull_request:
5+
types: [labeled]
6+
7+
concurrency:
8+
group: fix-pr-${{ github.event.pull_request.number }}
9+
cancel-in-progress: false
10+
11+
permissions:
12+
contents: write
13+
pull-requests: write
14+
issues: write
15+
16+
jobs:
17+
fix:
18+
# Only trigger on the specific fix label
19+
if: github.event.label.name == 'status:fix-needed'
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
with:
24+
fetch-depth: 0
25+
ref: ${{ github.event.pull_request.head.ref }}
26+
27+
- name: Configure git
28+
run: |
29+
git config user.name "dx-examples-bot"
30+
git config user.email "noreply@deepgram.com"
31+
32+
- name: Get date
33+
id: date
34+
run: echo "date=$(date -u +%Y-%m-%d)" >> $GITHUB_OUTPUT
35+
36+
- name: Check fix attempt count
37+
id: attempt-check
38+
env:
39+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
40+
run: |
41+
PR_NUMBER=${{ github.event.pull_request.number }}
42+
# Count commits by the bot on this branch that are fixes
43+
FIX_COMMITS=$(git log --oneline --author="dx-examples-bot" | grep "^[a-f0-9]* fix(" | wc -l | tr -d ' ')
44+
echo "fix_attempts=$FIX_COMMITS" >> $GITHUB_OUTPUT
45+
if [ "$FIX_COMMITS" -ge 3 ]; then
46+
echo "max_reached=true" >> $GITHUB_OUTPUT
47+
gh pr comment $PR_NUMBER --body "@deepgram-devrel — the fix agent has made 3 repair attempts on this PR and tests are still failing. Manual intervention needed. Please review the test output and push a fix directly."
48+
else
49+
echo "max_reached=false" >> $GITHUB_OUTPUT
50+
fi
51+
52+
- name: Run fix agent
53+
if: steps.attempt-check.outputs.max_reached == 'false'
54+
uses: anthropics/claude-code-action@beta
55+
with:
56+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
57+
github_token: ${{ secrets.GITHUB_TOKEN }}
58+
mode: agent
59+
model: claude-opus-4-6
60+
allowed_tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch"
61+
direct_prompt: |
62+
Read and execute the instructions in `instructions/fix-example.md`.
63+
64+
Context:
65+
- PR_NUMBER: ${{ github.event.pull_request.number }}
66+
- PR_BRANCH: ${{ github.event.pull_request.head.ref }}
67+
- Today's date: ${{ steps.date.outputs.date }}
68+
- Repository: ${{ github.repository }}
69+
- Fix attempt: ${{ steps.attempt-check.outputs.fix_attempts }} of 3

‎.github/workflows/review-pr.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Review PR
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened]
6+
paths:
7+
- 'examples/**'
8+
9+
concurrency:
10+
group: review-pr-${{ github.event.pull_request.number }}
11+
cancel-in-progress: true
12+
13+
permissions:
14+
contents: read
15+
pull-requests: write
16+
issues: write
17+
18+
jobs:
19+
review:
20+
# Only review PRs that add examples (not fixes to existing ones from humans)
21+
if: contains(github.event.pull_request.labels.*.name, 'type:example') || contains(github.event.pull_request.labels.*.name, 'type:fix')
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
with:
26+
fetch-depth: 0
27+
ref: ${{ github.event.pull_request.head.sha }}
28+
29+
- name: Get date
30+
id: date
31+
run: echo "date=$(date -u +%Y-%m-%d)" >> $GITHUB_OUTPUT
32+
33+
- name: Run review agent
34+
uses: anthropics/claude-code-action@beta
35+
with:
36+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
37+
github_token: ${{ secrets.GITHUB_TOKEN }}
38+
mode: agent
39+
model: claude-opus-4-6
40+
allowed_tools: "Bash,Read,Glob,Grep"
41+
direct_prompt: |
42+
Read and execute the instructions in `instructions/review-example.md`.
43+
44+
Context:
45+
- PR_NUMBER: ${{ github.event.pull_request.number }}
46+
- PR_TITLE: ${{ github.event.pull_request.title }}
47+
- Today's date: ${{ steps.date.outputs.date }}
48+
- Repository: ${{ github.repository }}

0 commit comments

Comments
 (0)