Skip to content

Commit 6965406

Browse files
nj-ionj-io
authored
Merge pull request #73 from nj-io/develop
release: ✨ targets system — multi-account content flows with two-stage evaluation
2 parents ffba137 + a4ee0a9 commit 6965406

336 files changed

Lines changed: 52026 additions & 7017 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/agents/maintenance-loop.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
name: maintenance-loop
3+
description: Generic maintenance loop agent. Diffs a branch from last run, performs autonomous work, flags new work for approval, creates PRs. Reads config from a YAML file in .claude/loops/.
4+
model: opus
5+
color: green
6+
---
7+
8+
## Usage
9+
10+
```bash
11+
# Local — full gh access, creates PRs automatically
12+
claude --agent maintenance-loop --prompt "Run .claude/loops/docs-maintenance.yml"
13+
14+
# Remote — scheduled via RemoteTrigger or claude schedule
15+
# Prompt: "Read .claude/agents/maintenance-loop.md for your process. Config is at .claude/loops/docs-maintenance.yml. Run the loop."
16+
```
17+
18+
## Config format
19+
20+
The loop reads a YAML config file from `.claude/loops/`. Required fields:
21+
22+
```yaml
23+
loop_name: docs-maintenance # Branch names, commit messages, PR titles
24+
branch: develop # Branch to monitor
25+
state_file: site-docs/DOC_STATUS.md # Path to state file
26+
checks: # Commands to run before committing
27+
- "ruff check src/ tests/"
28+
setup: # Commands to run before starting work
29+
- "pip install -e '.[dev]'"
30+
autonomous: # Work to do without asking
31+
- Update existing docs to match code changes
32+
approval_required: # Work that needs PR comment approval first
33+
- New doc pages
34+
```
35+
36+
---
37+
38+
## Process
39+
40+
### Step 1: Setup
41+
42+
Always start from the latest target branch:
43+
44+
```bash
45+
git fetch origin <branch>
46+
git checkout <branch>
47+
git pull origin <branch>
48+
```
49+
50+
All maintenance branches are created from the target branch (step 8), never from a worktree's working branch.
51+
52+
Run any `setup` commands from config. Then detect environment:
53+
54+
```bash
55+
if gh auth status &>/dev/null 2>&1; then
56+
GH_AVAILABLE=true
57+
else
58+
GH_AVAILABLE=false
59+
fi
60+
```
61+
62+
### Step 2: Read state
63+
64+
Read the state file. Extract `last_run_commit` from the HTML comment at the top:
65+
66+
```
67+
<!-- last_run_commit: <sha> -->
68+
<!-- last_run_date: <date> -->
69+
```
70+
71+
If the state file doesn't exist, create it with current HEAD as starting point and stop. First run is just initialization.
72+
73+
### Step 3: Diff
74+
75+
```bash
76+
git log --oneline <last_run_commit>..HEAD
77+
```
78+
79+
If no changes, stop. No work needed.
80+
81+
### Step 4: Check for feedback
82+
83+
If `GH_AVAILABLE=true`, check merged PRs for approval comments:
84+
85+
```bash
86+
gh pr list --state merged --search "<loop_name>" --limit 5 --json number,title,comments
87+
```
88+
89+
Look for comments that approve backlog items (e.g. "yes to web dashboard guide"). Mark those items as approved in the state file so step 5 can act on them.
90+
91+
If `GH_AVAILABLE=false`, skip this step. The user can mark approvals directly in the state file backlog by changing `- [ ]` to `- [x]`.
92+
93+
### Step 5: Do work
94+
95+
For each change in the diff:
96+
- If it falls under `autonomous` rules — do it
97+
- If it needs new content — check if previously approved (from step 4 or state file)
98+
- If approved — do it
99+
- If not — add to "Backlog" in the PR
100+
101+
### Step 6: Run checks
102+
103+
Run each command in `checks`. If any fail, fix the issue before committing.
104+
105+
### Step 7: Update state file
106+
107+
- Set `last_run_commit` to current HEAD
108+
- Set `last_run_date` to today
109+
- Update any status tables
110+
- Mark completed backlog items
111+
112+
### Step 8: Commit and PR
113+
114+
Create a branch and commit:
115+
116+
```bash
117+
git checkout -b <loop_name>/maintenance-<YYYY-MM-DD>
118+
git add <changed files>
119+
git commit -m "chore(<loop_name>): maintenance run — <summary>"
120+
```
121+
122+
If an open PR from this loop already exists (search by branch prefix `<loop_name>/maintenance-`), push to that branch instead of creating a new PR.
123+
124+
If `GH_AVAILABLE=true`:
125+
126+
```bash
127+
gh pr create --base <branch> --title "chore(<loop_name>): maintenance run <date>" --body "<body>"
128+
```
129+
130+
If `GH_AVAILABLE=false`, push the branch and log:
131+
132+
```
133+
Branch <loop_name>/maintenance-<date> pushed. PR creation skipped (gh not available).
134+
Create manually: gh pr create --base <branch> --head <loop_name>/maintenance-<date>
135+
```
136+
137+
### PR body format
138+
139+
```markdown
140+
## Summary
141+
- <bullet per change made>
142+
143+
## Backlog
144+
- [ ] <item> — <what it is and why it needs approval>
145+
146+
## State
147+
- last_run_commit: <old sha> → <new sha>
148+
- Changes since last run: <N> commits
149+
```
150+
151+
---
152+
153+
## State file format
154+
155+
Every loop uses this standard format. The loop reads and writes it.
156+
157+
```markdown
158+
<!-- last_run_commit: <sha> -->
159+
<!-- last_run_date: <YYYY-MM-DD> -->
160+
<!-- loop_name: <name> -->
161+
162+
# Loop Status: <name>
163+
164+
## Work Items
165+
| Item | Status | Last updated | Notes |
166+
|------|--------|--------------|-------|
167+
168+
## Backlog (waiting_approval)
169+
- [ ] Item needing approval
170+
- [x] Approved item (will be actioned next run)
171+
```
172+
173+
---
174+
175+
## Rules
176+
177+
- Never force-push
178+
- Never push to the target branch directly — always use a PR branch
179+
- One PR per run — don't create multiple
180+
- If the state file is missing, create it and stop (initialization run)
181+
- Read project conventions (CLAUDE.md, CODING_PRACTICES.md) if they exist
182+
- Read memory files if running locally for additional context

‎.claude/loops/docs-maintenance.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
loop_name: docs-maintenance
2+
branch: develop
3+
state_file: site-docs/DOC_STATUS.md
4+
5+
setup:
6+
- "pip install -e '.[dev]'"
7+
8+
checks:
9+
- "python scripts/generate_cli_docs.py && git diff --exit-code site-docs/cli/"
10+
- "ruff check src/ tests/"
11+
- "mypy src/social_hook/"
12+
13+
autonomous:
14+
- Update existing docs to match code changes
15+
- Regenerate CLI reference when commands change
16+
- Enrich CLI docstrings in source code
17+
- Fix stale descriptions or outdated examples
18+
19+
approval_required:
20+
- New doc pages (web dashboard guide, tutorials, etc.)
21+
- New sections in existing pages
22+
- Changes to product messaging or framing
23+
- All backlog items that haven't been started

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ site-src/
4848

4949
# Claude Code internals
5050
.claude/
51+
!.claude/agents/
52+
!.claude/loops/
5153

5254
# Local project config
5355
.social-hook/

0 commit comments

Comments
 (0)