zzstoatzz.io
+195
-75
.github/workflows/status-maintenance.yml
+195
-75
.github/workflows/status-maintenance.yml
···
1
-
# status maintenance via letta-backed agent
2
#
3
# two-phase workflow:
4
-
# 1. workflow_dispatch: runs letta-backed script to archive, generate audio, open PR
5
# 2. on PR merge: uploads audio to plyr.fm
6
-
#
7
-
# the letta agent maintains persistent memory across runs, remembering:
8
-
# - previous status updates and their content
9
-
# - architectural decisions and patterns
10
-
# - recurring themes in development
11
#
12
# required secrets:
13
-
# LETTA_API_KEY - letta cloud API key (for persistent memory)
14
-
# ANTHROPIC_API_KEY - anthropic API key (for claude)
15
# GOOGLE_API_KEY - gemini TTS (for audio generation)
16
# PLYR_BOT_TOKEN - plyr.fm developer token (for audio upload)
17
···
27
description: "skip audio generation"
28
type: boolean
29
default: false
30
-
dry_run:
31
-
description: "dry run (no file changes)"
32
-
type: boolean
33
-
default: false
34
pull_request:
35
types: [closed]
36
branches: [main]
37
38
jobs:
39
-
# phase 1: run letta-backed maintenance script + open PR
40
maintain:
41
if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
42
runs-on: ubuntu-latest
43
permissions:
44
contents: write
45
pull-requests: write
46
47
steps:
48
- uses: actions/checkout@v4
···
51
52
- uses: astral-sh/setup-uv@v4
53
54
-
- name: Run letta-backed status maintenance
55
-
id: maintenance
56
-
run: |
57
-
ARGS=""
58
-
if [ "${{ inputs.skip_audio }}" = "true" ]; then
59
-
ARGS="$ARGS --skip-audio"
60
-
fi
61
-
if [ "${{ inputs.dry_run }}" = "true" ]; then
62
-
ARGS="$ARGS --dry-run"
63
-
fi
64
65
-
uv run scripts/status_maintenance.py $ARGS
66
67
-
# check if files were modified
68
-
if [ -f .modified_files ]; then
69
-
echo "files_modified=true" >> $GITHUB_OUTPUT
70
-
else
71
-
echo "files_modified=false" >> $GITHUB_OUTPUT
72
-
fi
73
-
env:
74
-
LETTA_API_KEY: ${{ secrets.LETTA_API_KEY }}
75
-
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
76
-
GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
77
78
-
- name: Create PR
79
-
if: steps.maintenance.outputs.files_modified == 'true' && inputs.dry_run != true
80
-
run: |
81
-
# generate unique branch name
82
-
BRANCH="status-maintenance-$(date +%Y%m%d-%H%M%S)"
83
84
-
# configure git
85
-
git config user.name "github-actions[bot]"
86
-
git config user.email "github-actions[bot]@users.noreply.github.com"
87
88
-
# create branch and commit
89
-
git checkout -b "$BRANCH"
90
-
git add .status_history/ STATUS.md update.wav 2>/dev/null || true
91
-
git add -A # catch any other changes
92
93
-
# check if there are changes to commit
94
-
if git diff --cached --quiet; then
95
-
echo "No changes to commit"
96
-
exit 0
97
-
fi
98
99
-
git commit -m "chore: status maintenance (letta-backed)
100
101
-
🤖 Generated with letta-backed status agent
102
-
"
103
104
-
git push -u origin "$BRANCH"
105
106
-
# create PR
107
-
gh pr create \
108
-
--title "chore: status maintenance - $(date +'%B %d, %Y')" \
109
-
--body "## automated status maintenance
110
111
-
this PR was generated by the letta-backed status maintenance agent.
112
113
-
### what's included
114
-
- STATUS.md updates (if any changes were detected)
115
-
- archived content moved to .status_history/ (if needed)
116
-
- update.wav podcast audio (if audio generation was enabled)
117
118
-
### letta memory
119
-
the agent maintains persistent memory across runs, improving context
120
-
and consistency over time.
121
122
-
---
123
-
🤖 generated by status-maintenance workflow" \
124
-
--label "ai-generated" || gh label create "ai-generated" --description "Generated by AI" && gh pr create \
125
-
--title "chore: status maintenance - $(date +'%B %d, %Y')" \
126
-
--body "automated status maintenance PR" \
127
-
--label "ai-generated"
128
env:
129
-
GH_TOKEN: ${{ github.token }}
130
131
# phase 2: upload audio after PR merge
132
upload-audio:
···
1
+
# status maintenance via claude code
2
#
3
# two-phase workflow:
4
+
# 1. workflow_dispatch: archives old STATUS.md sections, generates audio, opens PR
5
# 2. on PR merge: uploads audio to plyr.fm
6
#
7
# required secrets:
8
+
# ANTHROPIC_API_KEY - claude code
9
# GOOGLE_API_KEY - gemini TTS (for audio generation)
10
# PLYR_BOT_TOKEN - plyr.fm developer token (for audio upload)
11
···
21
description: "skip audio generation"
22
type: boolean
23
default: false
24
pull_request:
25
types: [closed]
26
branches: [main]
27
28
jobs:
29
+
# phase 1: archive + generate audio + open PR
30
maintain:
31
if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
32
runs-on: ubuntu-latest
33
permissions:
34
contents: write
35
pull-requests: write
36
+
id-token: write
37
38
steps:
39
- uses: actions/checkout@v4
···
42
43
- uses: astral-sh/setup-uv@v4
44
45
+
- uses: anthropics/claude-code-action@v1
46
+
with:
47
+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
48
+
claude_args: |
49
+
--model opus
50
+
--allowedTools "Read,Write,Edit,Bash,Fetch,Task"
51
+
prompt: |
52
+
you are maintaining the plyr.fm (pronounced "player FM") project status file.
53
+
54
+
## critical rules
55
+
56
+
1. STATUS.md MUST be kept under 500 lines. this is non-negotiable.
57
+
2. archive content MUST be moved to .status_history/, not deleted
58
+
3. podcast tone MUST be dry, matter-of-fact, slightly sardonic - NOT enthusiastic or complimentary
59
60
+
## task 1: gather temporal context
61
62
+
CRITICAL: you must determine the correct time window by finding when the LAST status maintenance PR was MERGED (not opened).
63
+
64
+
run these commands:
65
+
```bash
66
+
date
67
+
# get the most recently merged status-maintenance PR (filter by branch name, sort by merge date)
68
+
gh pr list --state merged --search "status-maintenance" --limit 20 --json number,title,mergedAt,headRefName | jq '[.[] | select(.headRefName | startswith("status-maintenance-"))] | sort_by(.mergedAt) | reverse | .[0]'
69
+
git log --oneline -50
70
+
ls -la .status_history/ 2>/dev/null || echo "no archive directory yet"
71
+
wc -l STATUS.md
72
+
```
73
+
74
+
determine:
75
+
- what is today's date?
76
+
- when was the last status-maintenance PR MERGED? (use the mergedAt field from the jq output - it's the most recent PR with a branch starting with "status-maintenance-")
77
+
- what shipped SINCE that merge date? (this is your focus window - NOT "last week")
78
+
- does .status_history/ exist? (this implies whether or not this is the first episode)
79
+
- how many lines is STATUS.md currently?
80
81
+
IMPORTANT: the time window for this maintenance run is from the last merged status-maintenance PR until now. if the last PR was merged on Dec 2nd and today is Dec 8th, you should focus on everything from Dec 3rd onwards, NOT just "the last week".
82
83
+
## task 2: archive old sections (MANDATORY if over 250 lines)
84
85
+
if STATUS.md > 500 lines:
86
+
1. create .status_history/ directory if it doesn't exist
87
+
2. identify section boundaries (look for "---" separators and "### " headers with dates)
88
+
3. move OLDEST sections to .status_history/YYYY-MM.md (grouped by month)
89
+
4. compact the meaning of the original entire STATUS.md into about 500 lines or less
90
+
5. generally preserve the document structure (keep "## recent work" header, "## immediate priorities", etc)
91
+
6. do NOT summarize archived content - move it verbatim and organize it chronologically
92
93
+
ARCHIVE FILE NAMING - CRITICAL:
94
+
- archive files are organized BY MONTH: .status_history/YYYY-MM.md
95
+
- if today is December 2025, archived December content goes to .status_history/2025-12.md
96
+
- if today is January 2026, archived January content goes to .status_history/2026-01.md
97
+
- check what files already exist in .status_history/ and ADD to the appropriate month file if it exists
98
+
- each month gets ONE file - append to existing month files, don't create duplicates
99
100
+
so STATUS.md is the living overview, slightly recency biased, but a good general overview of the project.
101
102
+
.status_history/ is the archive of temporally specific sections of STATUS.md that are worth preserving for historical context, but not significant enough to be stated literally in STATUS.md in perpetuity.
103
104
+
VERIFY: run `wc -l STATUS.md` after archiving. it MUST be under 500 lines.
105
106
+
## task 3: generate audio overview (if skip_audio is false)
107
108
+
skip_audio input: ${{ inputs.skip_audio }}
109
110
+
if skip_audio is false:
111
112
+
### deep investigation phase
113
114
+
before writing anything, you need to deeply understand what happened in the time window.
115
+
use subagents liberally to investigate in parallel:
116
+
117
+
1. **get the full picture of PRs merged in the time window**:
118
+
```bash
119
+
gh pr list --state merged --search "merged:>={mergedAt date}" --limit 50 --json number,title,body,mergedAt,additions,deletions,files
120
+
```
121
+
122
+
2. **for each significant PR, read its body and understand the design decisions**:
123
+
- what problem was being solved?
124
+
- what approach was taken and why?
125
+
- what are the key files changed?
126
+
127
+
3. **read the actual code changes** for the top 2-3 most significant PRs:
128
+
- use `gh pr diff {number}` or read the changed files directly
129
+
- understand the architecture, not just the commit messages
130
+
131
+
4. **read background context**:
132
+
- STATUS.md (the current state)
133
+
- docs/deployment/overview.md if it exists
134
+
- Fetch https://atproto.com/guides/overview to understand ATProto primitives
135
+
- Fetch https://atproto.com/guides/lexicon to understand NSIDs and lexicons
136
+
137
+
### identify the narrative structure
138
+
139
+
after investigating, categorize what shipped:
140
+
141
+
**big ticket items** (1-3 major features or architectural changes):
142
+
- these get the most airtime (60-70% of the script)
143
+
- explain HOW they were designed, not just WHAT they do
144
+
- discuss interesting technical decisions or tradeoffs
145
+
146
+
**smaller but notable changes** (3-6 fixes, improvements, polish):
147
+
- these get rapid-fire coverage (20-30% of the script)
148
+
- one or two sentences each
149
+
- acknowledge they happened without belaboring them
150
+
151
+
### write the podcast script
152
+
153
+
write to podcast_script.txt with "Host: ..." and "Cohost: ..." lines.
154
+
155
+
**CHRONOLOGICAL NARRATIVE STRUCTURE** (CRITICAL):
156
+
157
+
the script must tell a coherent story of the time period, structured as:
158
+
159
+
1. **opening** (10 seconds): set the scene - what's the date range, what was the focus?
160
+
161
+
2. **the main story** (60-90 seconds): the biggest thing that shipped
162
+
- what problem did it solve?
163
+
- how was it designed? (explain the architecture accessibly)
164
+
- what's interesting about the implementation?
165
+
- the hosts should have a back-and-forth discussing the design
166
+
167
+
3. **secondary feature** (30-45 seconds, if applicable): another significant change
168
+
- lighter treatment than the main story
169
+
- still explain the "why" not just the "what"
170
+
171
+
4. **rapid fire** (20-30 seconds): the smaller changes
172
+
- "we also saw..." or "a few other things landed..."
173
+
- quick hits: bug fixes, polish, minor improvements
174
+
- don't dwell, just acknowledge
175
+
176
+
5. **closing** (10 seconds): looking ahead or wrapping up
177
+
178
+
the narrative should flow like you're telling a friend what happened on the project this week.
179
+
use transitions: "but before that landed...", "meanwhile...", "and then to tie it together..."
180
+
181
+
### tone requirements (CRITICAL)
182
+
183
+
the hosts should sound like two engineers who:
184
+
- are skeptical, amused and somewhat intrigued by the absurdity of building things
185
+
- acknowledge problems and limitations honestly
186
+
- don't over-use superlatives ("amazing", "incredible", "exciting")
187
+
- explain technical concepts through analogy, not hypey jargon
188
+
- genuinely find the technical details interesting (not performatively enthusiastic)
189
+
190
+
avoid excessive phrasing:
191
+
- "exciting", "amazing", "incredible", "impressive", "great job"
192
+
- "the team has done", "they've really", "fantastic work"
193
+
- any variation of over-congratulating or over-sensationalizing the project
194
+
195
+
### pronunciation (CRITICAL - READ THIS CAREFULLY)
196
+
197
+
the project name "plyr.fm" is pronounced "player FM" (like "music player").
198
+
199
+
**in your script, ALWAYS write "player FM" or "player dot FM" - NEVER write "plyr.fm" or "plyr".**
200
+
201
+
the TTS engine will mispronounce "plyr" as "plir" or "p-l-y-r" if you write it that way.
202
+
write phonetically for correct pronunciation: "player FM", "player dot FM".
203
+
204
+
### identifying what actually shipped
205
+
206
+
read the commit messages and PR bodies carefully to understand what changed.
207
+
208
+
- if something is completely NEW (didn't exist before), say it "shipped" or "launched"
209
+
- if something existing got improved or fixed, call it what it is: fixes, improvements, polish
210
+
211
+
don't rely on commit message prefixes like `feat:` or `fix:` - they're not always accurate.
212
+
read the actual content to understand the scope of what changed.
213
+
214
+
### time references (CRITICAL)
215
+
216
+
NEVER say "last week", "this week", "recently", or vague time references.
217
+
218
+
ALWAYS use specific date ranges based on the mergedAt date from task 1:
219
+
- "since December 2nd" or "from December 3rd to today"
220
+
- "in the past six days" (if that's accurate)
221
+
- "since the last update"
222
+
223
+
the listener doesn't know when "last week" was - be specific.
224
+
225
+
target length: 2-3 minutes spoken (~300-400 words) (it should be 4-5 if its the first episode)
226
+
227
+
### generate audio
228
+
229
+
run: uv run scripts/generate_tts.py podcast_script.txt update.wav
230
+
then: rm podcast_script.txt
231
+
232
+
## task 4: open PR
233
+
234
+
if any files changed:
235
+
1. first, generate a unique branch name: BRANCH="status-maintenance-$(date +%Y%m%d-%H%M%S)"
236
+
2. git checkout -b $BRANCH
237
+
3. git add .status_history/ STATUS.md update.wav
238
+
4. git commit -m "chore: status maintenance"
239
+
5. git push -u origin $BRANCH
240
+
6. gh pr create with a title and body you craft:
241
+
- title should be descriptive of what this status update covers (e.g. "chore: status maintenance - playlist fast-follow fixes" or "chore: status maintenance - December updates")
242
+
- make it clear this is an automated status maintenance PR from the GitHub Action
243
+
- body should summarize what changed (archival, audio generation, etc.)
244
+
245
+
add a label like "ai-generated" to the PR (create the label if it doesn't exist)
246
+
if nothing changed, report that no maintenance was needed.
247
+
248
env:
249
+
GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
250
251
# phase 2: upload audio after PR merge
252
upload-audio:
+3
-3
STATUS.md
+3
-3
STATUS.md
-257
scripts/letta_status_agent.py
-257
scripts/letta_status_agent.py
···
1
-
#!/usr/bin/env -S uv run --script --quiet
2
-
# /// script
3
-
# requires-python = ">=3.12"
4
-
# dependencies = [
5
-
# "agentic-learning>=0.4.0",
6
-
# "anthropic>=0.40.0",
7
-
# "pydantic-settings>=2.0.0",
8
-
# ]
9
-
# [tool.uv]
10
-
# prerelease = "allow"
11
-
# ///
12
-
"""proof of concept: letta-powered status agent with persistent memory.
13
-
14
-
this script demonstrates using letta's learning SDK to give an LLM
15
-
persistent memory across runs. the agent will remember context about
16
-
plyr.fm's codebase and recent work.
17
-
18
-
usage:
19
-
# first run - agent learns about the project
20
-
uv run scripts/letta_status_agent.py "what is plyr.fm?"
21
-
22
-
# second run - agent remembers previous context
23
-
uv run scripts/letta_status_agent.py "what did we discuss last time?"
24
-
25
-
# ask about recent work
26
-
uv run scripts/letta_status_agent.py "summarize recent commits"
27
-
28
-
# manage agent
29
-
uv run scripts/letta_status_agent.py --create # create the agent
30
-
uv run scripts/letta_status_agent.py --delete # delete the agent
31
-
uv run scripts/letta_status_agent.py --status # check agent status
32
-
33
-
environment variables (in .env):
34
-
LETTA_API_KEY - letta cloud API key
35
-
ANTHROPIC_API_KEY - anthropic API key
36
-
"""
37
-
38
-
import asyncio
39
-
import subprocess
40
-
import sys
41
-
from pathlib import Path
42
-
43
-
from pydantic import Field
44
-
from pydantic_settings import BaseSettings, SettingsConfigDict
45
-
46
-
AGENT_NAME = "plyr-status-agent"
47
-
MEMORY_BLOCKS = ["project_context", "recent_work"]
48
-
49
-
50
-
class AgentSettings(BaseSettings):
51
-
"""settings for the letta status agent."""
52
-
53
-
model_config = SettingsConfigDict(
54
-
env_file=Path(__file__).parent.parent / ".env",
55
-
case_sensitive=False,
56
-
extra="ignore",
57
-
)
58
-
59
-
letta_api_key: str = Field(validation_alias="LETTA_API_KEY")
60
-
anthropic_api_key: str = Field(validation_alias="ANTHROPIC_API_KEY")
61
-
62
-
63
-
def get_recent_commits(limit: int = 10) -> str:
64
-
"""get recent commit messages for context."""
65
-
result = subprocess.run(
66
-
["git", "log", "--oneline", f"-{limit}"],
67
-
capture_output=True,
68
-
text=True,
69
-
cwd=Path(__file__).parent.parent,
70
-
)
71
-
return result.stdout.strip()
72
-
73
-
74
-
def get_open_issues(limit: int = 5) -> str:
75
-
"""get open issues for context."""
76
-
result = subprocess.run(
77
-
["gh", "issue", "list", "--limit", str(limit)],
78
-
capture_output=True,
79
-
text=True,
80
-
cwd=Path(__file__).parent.parent,
81
-
)
82
-
return result.stdout.strip()
83
-
84
-
85
-
async def create_agent(settings: AgentSettings) -> None:
86
-
"""create the letta agent."""
87
-
from agentic_learning import AsyncAgenticLearning
88
-
89
-
letta_client = AsyncAgenticLearning(api_key=settings.letta_api_key)
90
-
91
-
# check if already exists
92
-
existing = await letta_client.agents.retrieve(agent=AGENT_NAME)
93
-
if existing:
94
-
print(f"agent '{AGENT_NAME}' already exists (id: {existing.id})")
95
-
return
96
-
97
-
# create
98
-
agent = await letta_client.agents.create(
99
-
agent=AGENT_NAME,
100
-
memory=MEMORY_BLOCKS,
101
-
model="anthropic/claude-sonnet-4-20250514",
102
-
)
103
-
print(f"✓ created agent '{AGENT_NAME}' (id: {agent.id})")
104
-
print(f" memory blocks: {MEMORY_BLOCKS}")
105
-
106
-
107
-
async def delete_agent(settings: AgentSettings) -> None:
108
-
"""delete the letta agent."""
109
-
from agentic_learning import AsyncAgenticLearning
110
-
111
-
letta_client = AsyncAgenticLearning(api_key=settings.letta_api_key)
112
-
113
-
deleted = await letta_client.agents.delete(agent=AGENT_NAME)
114
-
if deleted:
115
-
print(f"✓ deleted agent '{AGENT_NAME}'")
116
-
else:
117
-
print(f"agent '{AGENT_NAME}' not found")
118
-
119
-
120
-
async def show_status(settings: AgentSettings) -> None:
121
-
"""show agent status and memory."""
122
-
from agentic_learning import AsyncAgenticLearning
123
-
124
-
letta_client = AsyncAgenticLearning(api_key=settings.letta_api_key)
125
-
126
-
agent = await letta_client.agents.retrieve(agent=AGENT_NAME)
127
-
if not agent:
128
-
print(f"agent '{AGENT_NAME}' not found")
129
-
print("run: uv run scripts/letta_status_agent.py --create")
130
-
return
131
-
132
-
print(f"agent: {AGENT_NAME}")
133
-
print(f" id: {agent.id}")
134
-
print(f" model: {agent.model}")
135
-
136
-
# show memory blocks
137
-
if hasattr(agent, "memory") and agent.memory:
138
-
print(" memory blocks:")
139
-
for block in agent.memory.blocks:
140
-
preview = (
141
-
block.value[:100] + "..." if len(block.value) > 100 else block.value
142
-
)
143
-
print(f" - {block.label}: {preview}")
144
-
145
-
146
-
def run_agent_sync(user_message: str) -> None:
147
-
"""run the status agent with letta memory (sync version)."""
148
-
import os
149
-
150
-
settings = AgentSettings()
151
-
152
-
# SDK's capture() reads from os.environ, so we need to set it
153
-
os.environ["LETTA_API_KEY"] = settings.letta_api_key
154
-
155
-
# import after settings validation
156
-
import anthropic
157
-
from agentic_learning import AgenticLearning, learning
158
-
159
-
# initialize clients - use SYNC clients for sync context
160
-
letta_client = AgenticLearning(api_key=settings.letta_api_key)
161
-
anthropic_client = anthropic.Anthropic(api_key=settings.anthropic_api_key)
162
-
163
-
# ensure agent exists (sync)
164
-
existing = letta_client.agents.retrieve(agent=AGENT_NAME)
165
-
if not existing:
166
-
print(f"creating agent '{AGENT_NAME}'...")
167
-
try:
168
-
letta_client.agents.create(
169
-
agent=AGENT_NAME,
170
-
memory=MEMORY_BLOCKS,
171
-
model="anthropic/claude-sonnet-4-20250514",
172
-
)
173
-
print(f"✓ agent '{AGENT_NAME}' created")
174
-
except Exception as e:
175
-
print(f"✗ failed to create agent: {e}")
176
-
sys.exit(1)
177
-
178
-
# gather context
179
-
recent_commits = get_recent_commits()
180
-
open_issues = get_open_issues()
181
-
182
-
system_prompt = f"""you are a status agent for plyr.fm, a decentralized music streaming
183
-
platform built on AT Protocol.
184
-
185
-
your role is to:
186
-
1. understand what's happening in the codebase
187
-
2. remember context across conversations
188
-
3. help maintain STATUS.md and track project progress
189
-
190
-
current context:
191
-
- recent commits:
192
-
{recent_commits}
193
-
194
-
- open issues:
195
-
{open_issues}
196
-
197
-
be concise and technical. use lowercase aesthetic.
198
-
"""
199
-
200
-
print(f"user: {user_message}\n")
201
-
print("agent: ", end="", flush=True)
202
-
203
-
# wrap the anthropic call with letta learning context (SYNC)
204
-
# this automatically captures the conversation and injects relevant memory
205
-
with learning(
206
-
agent=AGENT_NAME,
207
-
client=letta_client,
208
-
memory=MEMORY_BLOCKS,
209
-
):
210
-
response = anthropic_client.messages.create(
211
-
model="claude-sonnet-4-20250514",
212
-
max_tokens=1024,
213
-
system=system_prompt,
214
-
messages=[{"role": "user", "content": user_message}],
215
-
)
216
-
217
-
# print response
218
-
for block in response.content:
219
-
if hasattr(block, "text"):
220
-
print(block.text)
221
-
222
-
print("\n✓ conversation saved to letta memory")
223
-
224
-
225
-
def main() -> None:
226
-
"""main entry point."""
227
-
if len(sys.argv) < 2:
228
-
print("usage: uv run scripts/letta_status_agent.py <message>")
229
-
print("\nexamples:")
230
-
print(' uv run scripts/letta_status_agent.py "what is plyr.fm?"')
231
-
print(' uv run scripts/letta_status_agent.py "what did we discuss last time?"')
232
-
print(' uv run scripts/letta_status_agent.py "summarize recent work"')
233
-
print("\nagent management:")
234
-
print(" uv run scripts/letta_status_agent.py --create")
235
-
print(" uv run scripts/letta_status_agent.py --delete")
236
-
print(" uv run scripts/letta_status_agent.py --status")
237
-
sys.exit(1)
238
-
239
-
settings = AgentSettings()
240
-
241
-
# handle management commands
242
-
if sys.argv[1] == "--create":
243
-
asyncio.run(create_agent(settings))
244
-
return
245
-
elif sys.argv[1] == "--delete":
246
-
asyncio.run(delete_agent(settings))
247
-
return
248
-
elif sys.argv[1] == "--status":
249
-
asyncio.run(show_status(settings))
250
-
return
251
-
252
-
user_message = " ".join(sys.argv[1:])
253
-
run_agent_sync(user_message)
254
-
255
-
256
-
if __name__ == "__main__":
257
-
main()
···
-505
scripts/status_maintenance.py
-505
scripts/status_maintenance.py
···
1
-
#!/usr/bin/env -S uv run --script --quiet
2
-
# /// script
3
-
# requires-python = ">=3.12"
4
-
# dependencies = [
5
-
# "agentic-learning>=0.4.0",
6
-
# "anthropic>=0.40.0",
7
-
# "pydantic-settings>=2.0.0",
8
-
# ]
9
-
# [tool.uv]
10
-
# prerelease = "allow"
11
-
# ///
12
-
"""letta-backed status maintenance for plyr.fm.
13
-
14
-
this script replaces the claude-code-action in the status maintenance workflow.
15
-
it uses letta's learning SDK to maintain persistent memory across runs.
16
-
17
-
the memory is about PROJECT UNDERSTANDING (architecture, patterns, context),
18
-
NOT about processing history. github is the source of truth for what needs
19
-
processing (last merged PR date → now).
20
-
21
-
usage:
22
-
# full maintenance run (archive, generate script, create audio)
23
-
uv run scripts/status_maintenance.py
24
-
25
-
# skip audio generation
26
-
uv run scripts/status_maintenance.py --skip-audio
27
-
28
-
# dry run (no file changes)
29
-
uv run scripts/status_maintenance.py --dry-run
30
-
31
-
environment variables:
32
-
LETTA_API_KEY - letta cloud API key
33
-
ANTHROPIC_API_KEY - anthropic API key
34
-
GOOGLE_API_KEY - gemini TTS (for audio generation)
35
-
"""
36
-
37
-
import argparse
38
-
import json
39
-
import os
40
-
import subprocess
41
-
import sys
42
-
from datetime import datetime
43
-
from pathlib import Path
44
-
45
-
from pydantic import BaseModel, Field
46
-
from pydantic_settings import BaseSettings, SettingsConfigDict
47
-
48
-
AGENT_NAME = "plyr-status-maintenance"
49
-
# memory blocks are about PROJECT UNDERSTANDING, not processing history
50
-
# the agent should remember architecture, patterns, and context - NOT what it processed
51
-
MEMORY_BLOCKS = [
52
-
"project_architecture", # how plyr.fm is built, key design decisions
53
-
"atproto_context", # understanding of ATProto, lexicons, NSIDs
54
-
"recurring_patterns", # themes that come up repeatedly in development
55
-
]
56
-
PROJECT_ROOT = Path(__file__).parent.parent
57
-
58
-
59
-
class Settings(BaseSettings):
60
-
"""settings for status maintenance."""
61
-
62
-
model_config = SettingsConfigDict(
63
-
env_file=PROJECT_ROOT / ".env",
64
-
case_sensitive=False,
65
-
extra="ignore",
66
-
)
67
-
68
-
letta_api_key: str = Field(validation_alias="LETTA_API_KEY")
69
-
anthropic_api_key: str = Field(validation_alias="ANTHROPIC_API_KEY")
70
-
google_api_key: str = Field(default="", validation_alias="GOOGLE_API_KEY")
71
-
model: str = Field(
72
-
default="claude-opus-4-5-20251101", validation_alias="ANTHROPIC_MODEL"
73
-
)
74
-
75
-
76
-
class MaintenanceReport(BaseModel):
77
-
"""structured output for status maintenance report."""
78
-
79
-
archive_needed: bool = Field(
80
-
description="true if STATUS.md > 400 lines and old content should be archived"
81
-
)
82
-
archive_content: str = Field(
83
-
description="content to move to .status_history/YYYY-MM.md (verbatim, oldest sections). empty string if no archival needed."
84
-
)
85
-
status_updates: str = Field(
86
-
description="new content to add to the '## recent work' section of STATUS.md"
87
-
)
88
-
podcast_script: str = Field(
89
-
description="2-3 minute podcast script with 'Host:' and 'Cohost:' lines following the tone and structure guidelines"
90
-
)
91
-
92
-
93
-
def run_cmd(cmd: list[str], capture: bool = True) -> str:
94
-
"""run a command and return output."""
95
-
result = subprocess.run(cmd, capture_output=capture, text=True, cwd=PROJECT_ROOT)
96
-
return result.stdout.strip() if capture else ""
97
-
98
-
99
-
def get_last_maintenance_date() -> str | None:
100
-
"""get the merge date of the last status-maintenance PR.
101
-
102
-
this is the SOURCE OF TRUTH for what time window to process.
103
-
NOT the agent's memory - github is authoritative.
104
-
"""
105
-
try:
106
-
result = run_cmd(
107
-
[
108
-
"gh",
109
-
"pr",
110
-
"list",
111
-
"--state",
112
-
"merged",
113
-
"--search",
114
-
"status-maintenance",
115
-
"--limit",
116
-
"20",
117
-
"--json",
118
-
"number,title,mergedAt,headRefName",
119
-
]
120
-
)
121
-
if not result:
122
-
return None
123
-
124
-
prs = json.loads(result)
125
-
# filter to status-maintenance branches and sort by merge date
126
-
maintenance_prs = [
127
-
pr
128
-
for pr in prs
129
-
if pr.get("headRefName", "").startswith("status-maintenance-")
130
-
]
131
-
if not maintenance_prs:
132
-
return None
133
-
134
-
# sort by mergedAt descending
135
-
maintenance_prs.sort(key=lambda x: x.get("mergedAt", ""), reverse=True)
136
-
return maintenance_prs[0].get("mergedAt", "").split("T")[0]
137
-
except Exception:
138
-
return None
139
-
140
-
141
-
def get_recent_commits(since: str | None = None, limit: int = 50) -> str:
142
-
"""get recent commits, optionally since a date."""
143
-
cmd = ["git", "log", "--oneline", f"-{limit}"]
144
-
if since:
145
-
cmd.extend(["--since", since])
146
-
return run_cmd(cmd)
147
-
148
-
149
-
def get_merged_prs(since: str | None = None, limit: int = 30) -> str:
150
-
"""get merged PRs with details."""
151
-
search = f"merged:>={since}" if since else ""
152
-
cmd = [
153
-
"gh",
154
-
"pr",
155
-
"list",
156
-
"--state",
157
-
"merged",
158
-
"--limit",
159
-
str(limit),
160
-
"--json",
161
-
"number,title,body,mergedAt,additions,deletions",
162
-
]
163
-
if search:
164
-
cmd.extend(["--search", search])
165
-
return run_cmd(cmd)
166
-
167
-
168
-
def get_status_md_line_count() -> int:
169
-
"""get current line count of STATUS.md."""
170
-
status_file = PROJECT_ROOT / "STATUS.md"
171
-
if status_file.exists():
172
-
return len(status_file.read_text().splitlines())
173
-
return 0
174
-
175
-
176
-
def read_status_md() -> str:
177
-
"""read current STATUS.md content."""
178
-
status_file = PROJECT_ROOT / "STATUS.md"
179
-
if status_file.exists():
180
-
return status_file.read_text()
181
-
return ""
182
-
183
-
184
-
def check_status_history_exists() -> bool:
185
-
"""check if .status_history/ directory exists (implies not first episode)."""
186
-
return (PROJECT_ROOT / ".status_history").exists()
187
-
188
-
189
-
def generate_maintenance_report(
190
-
settings: Settings,
191
-
last_maintenance: str | None,
192
-
dry_run: bool = False,
193
-
) -> MaintenanceReport:
194
-
"""generate the maintenance report using letta-backed claude with structured outputs.
195
-
196
-
uses anthropic's structured outputs beta for guaranteed schema compliance.
197
-
"""
198
-
# SDK's capture() reads from os.environ
199
-
os.environ["LETTA_API_KEY"] = settings.letta_api_key
200
-
201
-
import anthropic
202
-
from agentic_learning import AgenticLearning, learning
203
-
204
-
# initialize clients
205
-
letta_client = AgenticLearning(api_key=settings.letta_api_key)
206
-
anthropic_client = anthropic.Anthropic(api_key=settings.anthropic_api_key)
207
-
208
-
# ensure agent exists
209
-
existing = letta_client.agents.retrieve(agent=AGENT_NAME)
210
-
if not existing:
211
-
print(f"creating letta agent '{AGENT_NAME}'...")
212
-
letta_client.agents.create(
213
-
agent=AGENT_NAME,
214
-
memory=MEMORY_BLOCKS,
215
-
model=f"anthropic/{settings.model}",
216
-
)
217
-
print(f"✓ agent created with memory blocks: {MEMORY_BLOCKS}")
218
-
219
-
# gather context - read the FULL STATUS.md, not truncated
220
-
today = datetime.now().strftime("%Y-%m-%d")
221
-
today_human = datetime.now().strftime("%B %d, %Y")
222
-
commits = get_recent_commits(since=last_maintenance)
223
-
prs = get_merged_prs(since=last_maintenance)
224
-
status_content = read_status_md()
225
-
line_count = get_status_md_line_count()
226
-
has_history = check_status_history_exists()
227
-
is_first_episode = not has_history
228
-
229
-
if last_maintenance:
230
-
time_window = f"since {last_maintenance}"
231
-
time_window_human = f"from {last_maintenance} to {today}"
232
-
else:
233
-
time_window = "all time (first run)"
234
-
time_window_human = f"up to {today}"
235
-
236
-
system_prompt = f"""you maintain STATUS.md for plyr.fm (pronounced "player FM"), a decentralized
237
-
music streaming platform on AT Protocol.
238
-
239
-
## memory usage
240
-
241
-
your letta memory persists across runs. remember:
242
-
- architecture and design decisions
243
-
- ATProto concepts (lexicons, NSIDs, PDS)
244
-
- recurring development patterns
245
-
246
-
do NOT track what you processed - github determines the time window.
247
-
248
-
## rules
249
-
250
-
- STATUS.md must stay under 500 lines
251
-
- archive old content to .status_history/, never delete
252
-
- podcast tone: dry, matter-of-fact, sardonic - never enthusiastic
253
-
254
-
## context
255
-
256
-
today: {today_human}
257
-
last maintenance PR: {last_maintenance or "none (first run)"}
258
-
time window: {time_window_human}
259
-
STATUS.md lines: {line_count}
260
-
first episode: {is_first_episode}
261
-
262
-
focus on what shipped {time_window}. if last PR merged Dec 2nd and today is Dec 8th,
263
-
cover Dec 3rd onwards - not "the last week".
264
-
265
-
## commits ({time_window}):
266
-
{commits}
267
-
268
-
## merged PRs ({time_window}):
269
-
{prs}
270
-
271
-
## STATUS.md:
272
-
{status_content}
273
-
274
-
## tasks
275
-
276
-
1. **archival**: if > 400 lines, move oldest sections to .status_history/YYYY-MM.md (by month)
277
-
2. **status_updates**: new content for "## recent work" - concise, technical, what shipped and why
278
-
3. **podcast_script**: "Host:" and "Cohost:" dialogue, 2-3 min (4-5 min if first episode)
279
-
280
-
## podcast requirements
281
-
282
-
**pronunciation**: ALWAYS write "player FM" - never "plyr.fm" or "plyr" (TTS will mispronounce it)
283
-
284
-
**time references**: use specific dates ("since December 2nd"), never "last week" or "recently"
285
-
286
-
**structure**: tell a coherent story
287
-
- opening: set the date range and focus
288
-
- main story: biggest thing that shipped, design discussion between hosts
289
-
- secondary: other significant changes (lighter treatment)
290
-
- rapid fire: bug fixes, polish, minor improvements
291
-
- closing: wrap up
292
-
293
-
**tone**: two engineers who are skeptical, amused by the absurdity of building things.
294
-
acknowledge limitations honestly. explain through analogy, not jargon.
295
-
avoid: "exciting", "amazing", "incredible", "great job", any over-congratulating.
296
-
297
-
**what shipped**: read commits/PRs carefully. new things "shipped", improvements are "fixes" or "polish".
298
-
don't trust commit prefixes - read the actual content.
299
-
"""
300
-
301
-
print(f"generating maintenance report for {time_window}...")
302
-
303
-
with learning(agent=AGENT_NAME, client=letta_client, memory=MEMORY_BLOCKS):
304
-
# use structured outputs beta for guaranteed schema compliance
305
-
response = anthropic_client.beta.messages.parse(
306
-
model=settings.model,
307
-
max_tokens=8192,
308
-
betas=["structured-outputs-2025-11-13"],
309
-
system=system_prompt,
310
-
messages=[
311
-
{
312
-
"role": "user",
313
-
"content": f"""analyze what shipped {time_window} and generate the maintenance report.
314
-
315
-
remember key architectural insights and patterns for future runs - but do NOT
316
-
remember "what you processed" since github is the source of truth for that.""",
317
-
}
318
-
],
319
-
output_format=MaintenanceReport,
320
-
)
321
-
322
-
# structured outputs gives us the parsed model directly
323
-
report = response.parsed_output
324
-
325
-
print("✓ report generated")
326
-
print(f" archive needed: {report.archive_needed}")
327
-
print(f" status updates: {len(report.status_updates)} chars")
328
-
print(f" podcast script: {len(report.podcast_script)} chars")
329
-
330
-
return report
331
-
332
-
333
-
def apply_maintenance(report: MaintenanceReport, dry_run: bool = False) -> list[str]:
334
-
"""apply the maintenance report to files.
335
-
336
-
returns list of modified files.
337
-
"""
338
-
modified_files = []
339
-
340
-
# handle archival
341
-
if report.archive_needed and report.archive_content:
342
-
archive_dir = PROJECT_ROOT / ".status_history"
343
-
archive_file = archive_dir / f"{datetime.now().strftime('%Y-%m')}.md"
344
-
345
-
if dry_run:
346
-
print(f"[dry-run] would archive to {archive_file}")
347
-
else:
348
-
archive_dir.mkdir(exist_ok=True)
349
-
# append to existing month file or create new
350
-
mode = "a" if archive_file.exists() else "w"
351
-
with open(archive_file, mode) as f:
352
-
if mode == "a":
353
-
f.write("\n\n---\n\n")
354
-
f.write(report.archive_content)
355
-
modified_files.append(str(archive_file))
356
-
print(f"✓ archived content to {archive_file}")
357
-
358
-
# update STATUS.md
359
-
if report.status_updates:
360
-
status_file = PROJECT_ROOT / "STATUS.md"
361
-
if dry_run:
362
-
print(f"[dry-run] would update {status_file}")
363
-
else:
364
-
# read current content
365
-
current = status_file.read_text() if status_file.exists() else ""
366
-
367
-
# find "## recent work" section and insert after it
368
-
if "## recent work" in current:
369
-
parts = current.split("## recent work", 1)
370
-
# find the next section or end
371
-
after_header = parts[1]
372
-
# insert new content after the header line
373
-
lines = after_header.split("\n", 1)
374
-
new_content = (
375
-
parts[0]
376
-
+ "## recent work"
377
-
+ lines[0]
378
-
+ "\n\n"
379
-
+ report.status_updates
380
-
+ "\n"
381
-
+ (lines[1] if len(lines) > 1 else "")
382
-
)
383
-
status_file.write_text(new_content)
384
-
else:
385
-
# no recent work section, append to end
386
-
with open(status_file, "a") as f:
387
-
f.write(f"\n## recent work\n\n{report.status_updates}\n")
388
-
389
-
modified_files.append(str(status_file))
390
-
print(f"✓ updated {status_file}")
391
-
392
-
# write podcast script
393
-
if report.podcast_script:
394
-
script_file = PROJECT_ROOT / "podcast_script.txt"
395
-
if dry_run:
396
-
print(f"[dry-run] would write {script_file}")
397
-
else:
398
-
script_file.write_text(report.podcast_script)
399
-
modified_files.append(str(script_file))
400
-
print(f"✓ wrote podcast script to {script_file}")
401
-
402
-
return modified_files
403
-
404
-
405
-
def generate_audio(settings: Settings, dry_run: bool = False) -> str | None:
406
-
"""generate audio from podcast script.
407
-
408
-
returns path to audio file or None.
409
-
"""
410
-
script_file = PROJECT_ROOT / "podcast_script.txt"
411
-
audio_file = PROJECT_ROOT / "update.wav"
412
-
413
-
if not script_file.exists():
414
-
print("no podcast script found, skipping audio generation")
415
-
return None
416
-
417
-
if not settings.google_api_key:
418
-
print("GOOGLE_API_KEY not set, skipping audio generation")
419
-
return None
420
-
421
-
if dry_run:
422
-
print(f"[dry-run] would generate audio: {audio_file}")
423
-
return None
424
-
425
-
print("generating audio...")
426
-
result = subprocess.run(
427
-
["uv", "run", "scripts/generate_tts.py", str(script_file), str(audio_file)],
428
-
capture_output=True,
429
-
text=True,
430
-
cwd=PROJECT_ROOT,
431
-
env={**os.environ, "GOOGLE_API_KEY": settings.google_api_key},
432
-
)
433
-
434
-
if result.returncode != 0:
435
-
print(f"audio generation failed: {result.stderr}")
436
-
return None
437
-
438
-
# cleanup script file
439
-
script_file.unlink()
440
-
print(f"✓ generated {audio_file}")
441
-
return str(audio_file)
442
-
443
-
444
-
def main() -> None:
445
-
"""main entry point."""
446
-
parser = argparse.ArgumentParser(description="letta-backed status maintenance")
447
-
parser.add_argument(
448
-
"--skip-audio", action="store_true", help="skip audio generation"
449
-
)
450
-
parser.add_argument("--dry-run", action="store_true", help="don't modify files")
451
-
args = parser.parse_args()
452
-
453
-
print("=" * 60)
454
-
print("plyr.fm status maintenance (letta-backed)")
455
-
print("=" * 60)
456
-
457
-
# load settings
458
-
try:
459
-
settings = Settings()
460
-
except Exception as e:
461
-
print(f"error loading settings: {e}")
462
-
print("\nrequired environment variables:")
463
-
print(" LETTA_API_KEY")
464
-
print(" ANTHROPIC_API_KEY")
465
-
print(" GOOGLE_API_KEY (optional, for audio)")
466
-
sys.exit(1)
467
-
468
-
# determine time window from GITHUB (source of truth), not agent memory
469
-
last_maintenance = get_last_maintenance_date()
470
-
if last_maintenance:
471
-
print(f"last maintenance PR merged: {last_maintenance}")
472
-
else:
473
-
print("no previous maintenance PR found - first run")
474
-
475
-
# generate report
476
-
report = generate_maintenance_report(settings, last_maintenance, args.dry_run)
477
-
478
-
# apply changes
479
-
modified_files = apply_maintenance(report, args.dry_run)
480
-
481
-
# generate audio
482
-
if not args.skip_audio:
483
-
audio_file = generate_audio(settings, args.dry_run)
484
-
if audio_file:
485
-
modified_files.append(audio_file)
486
-
487
-
print("\n" + "=" * 60)
488
-
if args.dry_run:
489
-
print("[dry-run] no files modified")
490
-
elif modified_files:
491
-
print(f"modified files: {len(modified_files)}")
492
-
for f in modified_files:
493
-
print(f" - {f}")
494
-
else:
495
-
print("no changes needed")
496
-
497
-
# output for CI
498
-
if modified_files and not args.dry_run:
499
-
# write modified files list for CI
500
-
with open(PROJECT_ROOT / ".modified_files", "w") as f:
501
-
f.write("\n".join(modified_files))
502
-
503
-
504
-
if __name__ == "__main__":
505
-
main()
···