era2c - The ERA Mothership

The era2c repository is the operational center for the Eco-Restoration Alliance's membership management, autonomous AI collaboration, and community data systems.

How Work Gets Done

All work flows through GitHub Issues on the ERA Development project board. A listener script runs every 3 minutes and automates the pipeline end-to-end.

The Board

Five columns:

Backlog → In Progress → Testing → Merged → Deployed → Retired

Happy Path (auto-merge)

For routine work (bug fixes, docs, infra cleanup) labeled auto-merge:

1. Issue lands in Backlog — created by Jon, CTO, or the file watcher
2. Listener picks it up → moves to In Progress, spawns a Claude worker (Sonnet)
3. Worker writes code → opens a PR on branch issue/NNN
4. Listener spawns a reviewer (Opus) to evaluate the PR
5. Reviewer PASS → listener auto-merges, waits for Render deploy, runs smoke tests
6. Card moves to Deployed — Jon's review queue
7. Jon comments "retire" → listener moves to Retired and closes the issue

Happy Path (normal review)

For features or anything needing Jon's sign-off (no auto-merge label):

Steps 1-4 are the same, then:

5. Reviewer PASS → listener posts "Ready for Review" comment with PR link and live URL
6. Card moves to Testing — waiting for Jon
7. Jon comments "approved" (or "lgtm", "ship it") → listener merges, deploys, smoke tests
8. Card moves to Deployed → Jon comments "retire" when satisfied

Labels

Label	Effect
auto-merge	Skip Jon's approval, merge on reviewer PASS
needs-discussion	Listener skips entirely — blocked on Jon's input
(no label)	Normal flow with Jon's approval gate in Testing

Jon's Touch Points (phone-friendly)

1. Create issues — describe what you want
2. Add auto-merge if it's safe to ship without review
3. Comment "approved" on Testing items to trigger deploy
4. Comment "retire" on Deployed items to clear them
5. Add needs-discussion to pause anything

Everything else is automated.

Housekeeping (automatic, every 3 min)

The listener also runs cleanup sweeps each cycle:

• Orphaned issues (not on board) → added to Backlog
• Closed issues in active columns → moved to Deployed
• Merged/closed PRs in active columns → moved to Deployed/Retired
• Duplicate PR entries (backing issue already tracked) → removed
• needs-discussion issues in In Progress → demoted to Backlog
• OPEN issues in Retired → moved back to Backlog

What's in the Repo

era2c/
├── CLAUDE.md                     ← CTO instructions (read this first)
├── era2/                         ← Membership engine (attendees → members → donors)
│   ├── lib/                      ← Core libraries (db, email, docs, sheets)
│   ├── scripts/                  ← Operational scripts (followups, sync, search)
│   ├── data/                     ← SQLite database (gitignored)
│   ├── website/                  ← Static site deployed to Render
│   └── bigmap2/                  ← BigMap2 source (synced to website/)
├── claude_collaborator/          ← CLCL autonomous email assistant
│   ├── startup.py                ← Check email/docs on startup
│   └── clcl_email_listener.py    ← Wake listener (launchd)
├── dashboard/                    ← Web UI for monitoring
│   ├── server.py                 ← Python API server (port 8080)
│   └── xterm/server.js           ← Browser terminal (port 3000)
├── scripts/                      ← System scripts
│   ├── gh_listener.py            ← GitHub Issues listener (the pipeline)
│   ├── board_view.py             ← Quick board state viewer
│   ├── boot_check.sh             ← Post-reboot health check
│   └── issue_from_download.py    ← File watcher: markdown → GitHub issues
├── docs/                         ← Architecture docs and guides
│   └── knowledge/                ← Strategic context (from Claude.ai analysis)
└── .claude/                      ← Session state and hooks
    ├── hooks/                    ← SessionStart, SessionEnd, PreCompact
    └── handoff/                  ← Session handoff notes

Archived code: Retired components (Dispatcher, Narrator, beads, ERA_Landscape, historical data) are preserved at jonschull/era2c-archive.

Authority Model

Jon (Captain) — sets direction, approves, retires
     │
     ▼
CTO (Claude) — architecture, triage, code review, merge authority
     │
     ▼
Listener — automated pipeline: pick up work, spawn workers, deploy
     │
     ▼
Workers (Sonnet) — implement one issue at a time on a branch

Key rule: Workers recommend, CTO merges. The listener has merge authority for auto-merge items. Normal items require Jon's explicit approval.

What's Running

Service	Mechanism	Schedule
GH Issues listener	launchd	Every 3 min
GH Issues watchdog	launchd	Every 15 min
CLCL email listener	launchd	Continuous
Agent mail poller	launchd	Every 3 min
Daily Documentarian	launchd	6am daily
Daily Doc Audit	launchd	7am daily
System health check	launchd	Every 15 min
Dashboard + xterm	pm2	Ports 8080, 3000
Database sync	cron	Daily 5am
Cloud backup	cron	Daily 6am
Fathom legacy sync	cron	Daily 4am (disabled)
Render health check	cron	Daily 8am

Render Deployments

All deploy from main on push:

Service	Type	URL
era2	Web service	https://era2.onrender.com
era-website	Static site	https://era-website.onrender.com
era-bigmap	Static site	https://bigmaptosavethefuture.net
era2-followup	Cron (daily 2pm)	—
era-cloud-agent	Web service	https://era-cloud-agent.onrender.com

Quick Commands

# Board and listener
python3 scripts/board_view.py                    # View project board
python3 scripts/gh_listener.py --dry-run         # Listener dry run
tail -50 ~/era2c-listener/scripts/gh_listener.log  # Listener logs (LIVE)
tail -50 scripts/gh_listener.log                 # Listener logs (dry-run only)

# GitHub
gh issue list                                    # Open issues
gh issue create --title "..." --body "..."       # New issue

# Services
pm2 list                                         # Dashboard status
~/era2c/scripts/boot_check.sh                    # Full health check

# ERA2 operations
cd ~/era2c/era2
python3 ../scripts/board_view.py                 # Board from anywhere

Data Architecture

• Local dev: era2/data/era2_dev.db (SQLite) — development and testing only
• Production (canonical): PostgreSQL on Render (via DATABASE_URL) — per issue #467
• Key tables: participants, events, event_attendance, event_instances, person_emails, profile_edits, auth_tokens, bigmap_entries
• Sync: scripts/sync_databases.py supports bidirectional sync but has no scheduled cron entry — sync must be run manually. See era2/docs/DATA_ARCHITECTURE.md for full sync status and access patterns.

Claude.ai Integration

Claude.ai (Jon's conversation partner with 2+ years of strategic context) can communicate with CTO sessions via tmux:

• Read: tmux capture-pane from the browser terminal
• Write: tmux send-keys with C-m (not Enter)
• File watcher: Claude.ai drops claude-ai-issue-*.md in ~/Downloads → launchd → GitHub issues

This bridges strategic conversation context with operational execution.

---

Documentation

Doc	What it covers
CLAUDE.md	CTO role, rules, all running services, quick commands
docs/SYSTEM_ARCHITECTURE.md	Master architecture doc — all agents, communication channels, infrastructure, services
docs/RALPH_PIPELINE.md	Worker/supervisor pipeline for complex issues
docs/COS_INTEGRATION.md	COS agent, .comms/ protocol, exec bridge
docs/HOOKS_REFERENCE.md	Session hooks, handoff format, context recovery
docs/DEVELOPMENT_LESSONS.md	War stories and anti-patterns
docs/DIRECTORY_STRUCTURE.md	File tree and data architecture
docs/HOW_TO_BE_AN_INTELLIGENT_ASSISTANT.md	Core AI collaboration philosophy
docs/WORKING_PRINCIPLES.md	System design principles
era2/CLAUDE.md	ERA2 membership system specifics

---

Last updated: 2026-04-05