Skip to content

Commit 5008cbb

Browse files
gHashTaggHashTag
authored
Merge pull request #44 from gHashTag/ralph/swarm-constitution
docs: Rewrite agent governance — GitHub Issues = source of truth
2 parents 96f9507 + 2dcf8e6 commit 5008cbb

3 files changed

Lines changed: 162 additions & 129 deletions

File tree

‎.ralph/AGENTS.md‎

Lines changed: 59 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,83 @@
1-
# AGENTS.md — Agent Development Rules
1+
# AGENTS.md — Agent Work Rules (GitHub Issues = Source of Truth)
22

3-
## Parallel Documentation Rule
3+
## Core Principle
44

5-
**ALL agents MUST document website changes in parallel with code changes.**
5+
> Agents do NOT work without a GitHub Issue.
6+
> No issue = no task = no code = no PR.
67
7-
### The Golden Rule
8+
## Agent Lifecycle
89

9-
> "Code without website documentation is HALF-DONE."
10+
1. **IDLE** — Poll `gh issue list --label assign:ralph --label status:pending`
11+
2. **CLAIM** — Add `status:in-progress` label, assign self
12+
3. **BRANCH** — `git worktree add ../trinity-w{N} -b ralph/w{N}/{issue-slug} origin/main`
13+
4. **WORK** — VIBEE-first: spec → gen → test → bench → assess
14+
5. **PR** — `gh pr create --base main --body "Closes #N"` with ALL metadata (RULE #20)
15+
6. **REPORT** — Comment on issue with results, metrics, assessment
16+
7. **DONE** — General merges PR → issue auto-closes → board updates
1017

11-
### Every Agent Action Requires
18+
## Issue as Workspace
1219

13-
1. Code Change → Update `website/src/services/chatApi.ts`
14-
2. New Widget → Add to `website/src/components/sections/`
15-
3. New Feature → Create `docs/docs/features/<feature>.md`
16-
4. API Change → Update `docs/docs/api/`
20+
All communication happens ON THE ISSUE:
21+
- Progress updates → issue comments
22+
- Blockers → issue comment with warning
23+
- Benchmarks → issue comment with table
24+
- Questions → issue comment mentioning @gHashTag
25+
- Final report → issue comment with summary
1726

18-
### Checklist Before Commit
27+
## Rules
1928

20-
```bash
21-
cd website && npm run build
22-
cd ../docs && npm run build
23-
git add website/ docs/
24-
git commit "feat: <feature> + website docs"
25-
```
26-
27-
### Exit Criteria
28-
29-
A task is COMPLETE only when:
30-
31-
- [ ] Code works (tests pass)
32-
- [ ] `website/` updated (API functions, components)
33-
- [ ] `docs/docs/` updated (documentation pages)
34-
- [ ] Both sites build successfully
35-
- [ ] Changes committed together
29+
### RULE #19: Issue Metadata
30+
Every issue MUST have: assignee, labels (`assign:ralph` + `priority:P0-P3` + `status:*`), milestone, project (VIBECODER #6), relationship (linked to parent epic).
3631

37-
### Parallel Development Mapping
32+
### RULE #20: PR Metadata
33+
Every PR MUST have: assignee, labels (same as linked issue + `status:in-progress`), milestone, reviewer (gHashTag), linked issues (`Closes #N` in body), project (VIBECODER #6).
3834

39-
| Development Phase | Website Action |
40-
|-------------------|----------------|
41-
| **Spec** | Create draft doc in `docs/docs/` |
42-
| **Generate** | Add API to `chatApi.ts` |
43-
| **Implement** | Create/update feature component |
44-
| **Test** | Update benchmarks page |
45-
| **Document** | Update docs + sidebars |
46-
| **Commit** | Include both code and website |
35+
### RULE #21: No Work Without Issue
36+
Agent MUST NOT:
37+
- Write code without an assigned issue
38+
- Push commits without PR linked to issue
39+
- Create branches without issue number in name
40+
- Close issues manually (only via PR merge)
4741

48-
### Mandatory File Updates
42+
### RULE #22: GitHub Issues = Source of Truth
43+
- All tasks come from `gh issue list --label assign:ralph`
44+
- `fix_plan.md` is DEPRECATED as task source
45+
- If no pending issues exist, agent is IDLE
46+
- New work = new GitHub Issue first, then branch + code
4947

50-
For ANY feature addition:
48+
## Sub-agents
5149

50+
Parent agent creates sub-issues for sub-agents:
5251
```
53-
website/src/services/chatApi.ts # API functions
54-
website/src/components/sections/ # Feature widgets
55-
docs/docs/ # Technical docs
56-
docs/sidebars.ts # Navigation
52+
Parent Issue #38 (epic, label: swarm:parent)
53+
|- Sub-issue #39 -> Agent-W1
54+
|- Sub-issue #40 -> Agent-W2
55+
+- Sub-issue #41 -> Agent-W3
5756
```
5857

59-
### Deployment Rule
60-
61-
**ALWAYS deploy website and docs TOGETHER with code.**
62-
63-
See `CLAUDE.md` → "Deployment (GitHub Pages)" for full procedure.
64-
65-
---
66-
67-
## Quick Reference
68-
69-
### Add API Function
70-
71-
```typescript
72-
// website/src/services/chatApi.ts
73-
export async function myFeature(input: string): Promise<Result> {
74-
return fetchWithError('/api/my-feature', { input });
75-
}
76-
```
58+
Sub-agent follows same lifecycle: claim → branch → work → PR → done.
59+
Parent issue progress bar updates automatically via sub-issues.
7760

78-
### Add Widget
61+
## Forbidden
7962

80-
```tsx
81-
// website/src/components/sections/MyFeatureWidget.tsx
82-
export function MyFeatureWidget() {
83-
// Use glassStyle() + column colors
84-
}
85-
```
63+
- Working on main branch
64+
- Working without issue
65+
- Creating PR without "Closes #N"
66+
- Empty issue metadata (no labels, no milestone)
67+
- Manual issue close (only via PR merge)
68+
- Editing generated files (`trinity/output/`, `generated/`)
69+
- Pushing to main directly
70+
- Reporting "done" without confirmed push
8671

87-
### Add Documentation
72+
## Monitoring
8873

89-
```markdown
90-
# docs/docs/features/my-feature.md
91-
---
92-
title: My Feature
93-
sidebar_position: 10
94-
---
95-
```
74+
Oracle Watchdog monitors all agents 24/7:
75+
- Telegram alerts on commit, stop, circuit breaker
76+
- GitHub Projects board (VIBECODER #6) shows real-time status
77+
- `/god-mode` skill shows full dashboard
78+
- GitHub Actions auto-update board on PR merge / issue close
9679

9780
---
9881

9982
*This file is part of the Ralph Autonomous Development System.*
83+
*GitHub Issues = single source of truth. No exceptions.*

‎.ralph/RULES.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Ralph Development Rules (16 Sections)
1+
# Ralph Development Rules (22 Sections)
22

33
## 1. Source of Truth
44
- `specs/tri/*.vibee` governs ALL application code
@@ -124,3 +124,22 @@ Every PR created by agent MUST have:
124124
6. Project — same board as linked issue
125125

126126
PR without metadata = invisible work = violation.
127+
128+
## 21. No Work Without Issue (MANDATORY)
129+
Agent MUST NOT:
130+
1. Write code without an assigned GitHub Issue
131+
2. Push commits without a PR linked to an issue
132+
3. Create branches without issue number in name (`ralph/w{N}/{slug}`)
133+
4. Close issues manually — only via PR merge with `Closes #N`
134+
5. Report "done" without confirmed `git push` + GitHub API verification
135+
136+
No issue = no task = no code = no PR. Period.
137+
138+
## 22. GitHub Issues = Source of Truth (MANDATORY)
139+
- ALL tasks come from `gh issue list --label assign:ralph`
140+
- `fix_plan.md` is DEPRECATED as primary task source
141+
- If no pending issues exist → agent is IDLE (do not invent work)
142+
- New work requires: create GitHub Issue first → then branch → then code
143+
- GitHub Projects board (VIBECODER #6) is the canonical view of all work
144+
- GitHub Actions auto-add issues to project and auto-update status on merge
145+
- Oracle Watchdog monitors GitHub API and reports to Telegram 24/7

‎CLAUDE.md‎

Lines changed: 83 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -471,75 +471,97 @@ git push origin gh-pages --force
471471

472472
## Ralph Autonomous Development (MANDATORY)
473473

474-
**ALL development MUST go through Ralph.** This saves time by enforcing quality gates, tech tree navigation, memory consultation, and structured workflows automatically.
474+
### Single Source of Truth: GitHub Issues
475475

476-
### Why Ralph-Only
476+
ALL work flows through GitHub Issues. No internal task queues, no `fix_plan.md` as primary source.
477477

478-
| Without Ralph | With Ralph |
479-
|--------------|-----------|
480-
| Manual quality checks | Automated gates (build + test + format) |
481-
| Forget to update tech tree | Tree updated every cycle |
482-
| Repeat past mistakes | REGRESSION_PATTERNS.md consulted |
483-
| No structured progress | fix_plan.md + TECH_TREE.md tracking |
484-
| Commits to main | Feature branches enforced |
478+
| Component | Role |
479+
|-----------|------|
480+
| **GitHub Issues** | Task queue, status tracking, progress |
481+
| **GitHub Projects** | Board view (VIBECODER #6) |
482+
| **GitHub PRs** | Code delivery, auto-closes issues on merge |
483+
| **MCP Swarm** | Execution engine (Zig, 11+ tools) |
484+
| **Oracle Watchdog** | 24/7 monitoring → Telegram @vibee_dev_bot |
485+
486+
### How Work Happens
487+
488+
1. **Issue created** with `assign:ralph` label → appears on VIBECODER board
489+
2. **Agent picks issue** → `gh issue edit N --add-label status:in-progress`
490+
3. **Agent creates branch** → `ralph/w{N}/{slug}`
491+
4. **Agent works** → VIBEE-first: spec → gen → test → assess
492+
5. **Agent creates PR** → `Closes #N` in body, all metadata filled (RULE #20)
493+
6. **General reviews** → merge → issue auto-closes → board updates
494+
7. **Oracle reports** → Telegram notification of progress
495+
496+
### Issue Requirements (RULE #19)
497+
498+
Every issue MUST have:
499+
1. Assignee
500+
2. Labels: `assign:ralph` + `priority:P0-P3` + `status:pending`
501+
3. Milestone: current active milestone
502+
4. Project: VIBECODER (#6)
503+
5. Relationship: linked to parent epic
504+
505+
### PR Requirements (RULE #20)
506+
507+
Every PR MUST have:
508+
1. Assignee
509+
2. Labels (same as linked issue + `status:in-progress`)
510+
3. Milestone
511+
4. Reviewer: gHashTag
512+
5. Body: `Closes #N` for linked issues
513+
6. Project: VIBECODER (#6)
514+
515+
### Branch Strategy
516+
517+
- `main` — protected, merge only via PR
518+
- `ralph/w{N}/{issue-slug}` — agent worktree branches
519+
- Never push to main directly
520+
521+
### MCP Swarm Tools
522+
523+
| Tool | Purpose |
524+
|------|---------|
525+
| `swarm_task_add` | Creates GitHub Issue + links to parent |
526+
| `swarm_task_get` | Gets next pending issue |
527+
| `swarm_status` | Reads GitHub API, returns board state |
528+
| `swarm_heartbeat` | Comments progress on issue |
529+
| `swarm_register` | Register agent in swarm |
530+
| `swarm_agents` | List active agents |
531+
| `oracle_start/stop/status` | Control Telegram watchdog |
485532

486533
### Configuration
487534

488535
```
489536
.ralph/
490537
├── PROMPT.md # Autonomous work instructions
491538
├── AGENT.md # Build/test/run commands
492-
├── RULES.md # Universal development guardrails (16 sections)
493-
├── TECH_TREE.md # Tech tree navigation (35 nodes, 6 branches)
494-
├── fix_plan.md # Current sprint tasks with acceptance criteria
495-
├── SUCCESS_HISTORY.md # Working patterns + commit hashes
496-
├── REGRESSION_PATTERNS.md # Anti-patterns + root causes
539+
├── AGENTS.md # Agent work rules (GitHub Issues lifecycle)
540+
├── RULES.md # Universal development guardrails (22 rules)
541+
├── TECH_TREE.md # Tech tree navigation
542+
├── memory/
543+
│ ├── SUCCESS_HISTORY.md # Working patterns + commit hashes
544+
│ └── REGRESSION_PATTERNS.md # Anti-patterns + root causes
497545
├── specs/ # Ralph-specific specs
498-
├── examples/ # Workflow examples
499-
├── logs/ # Execution logs
500-
└── docs/generated/ # Auto-generated docs
546+
└── logs/ # Execution logs
501547
.ralphrc # Runtime settings (tools, timeouts, gates)
502548
```
503549

504-
### How to Use
505-
506-
```bash
507-
# 1. Add task to .ralph/fix_plan.md (with acceptance criteria)
508-
# 2. Start Ralph
509-
ralph --monitor
510-
511-
# Ralph will:
512-
# - Read TECH_TREE.md, fix_plan.md, SUCCESS_HISTORY.md, REGRESSION_PATTERNS.md
513-
# - Pick highest-priority task
514-
# - Create ralph/<task-slug> branch
515-
# - Implement via Golden Chain cycle (spec → gen → test → assess → tree → commit)
516-
# - Run quality gates (build + test + format)
517-
# - Update tech tree and memory files
518-
# - Loop until EXIT_SIGNAL = true
519-
```
520-
521-
### Commands
522-
523-
```bash
524-
ralph --monitor # Start with live monitoring dashboard
525-
ralph --help # Show options
526-
ralph-enable # Enable Ralph in project
527-
ralph-import prd.md # Convert PRD to Ralph tasks
528-
```
529-
530550
### Safeguards
531551

532-
- Rate limiting: 100 calls/hour (configurable)
533-
- Circuit breaker: 3 no-progress loops → cooldown
534-
- Branch safety: never commits to main
535-
- Quality gates: build + test + format before every commit
552+
- Circuit breaker: 5 no-progress loops → OPEN
553+
- Branch safety: hooks warn on main branch
554+
- Quality gates: build + test + format before commit
536555
- Memory: consults SUCCESS_HISTORY and REGRESSION_PATTERNS every loop
537-
- Dual-condition exit: heuristic indicators + explicit EXIT_SIGNAL
556+
- GOD MODE: `/god-mode` skill for full dashboard
557+
- Oracle: 24/7 Telegram monitoring
538558

539-
### Current Task (via Ralph)
559+
### Automation (GitHub Actions)
540560

541-
**VSA Mathematical Framework** — proofs + optimizations for bind/unbind/bundle, multilingual code gen.
542-
See `.ralph/fix_plan.md` and `.ralph/TECH_TREE.md` for details.
561+
| Workflow | Trigger | Action |
562+
|----------|---------|--------|
563+
| `project-auto-add.yml` | Issue/PR labeled | Auto-add to VIBECODER board |
564+
| `project-auto-status.yml` | PR merged / Issue closed | Auto-move to Done |
543565

544566
Repository: https://github.com/frankbria/ralph-claude-code
545567

@@ -599,6 +621,7 @@ Full Claude Code modernization: MCP servers, custom skills, automation hooks, pa
599621
| **trinity** | `zig-out/bin/trinity-mcp` | 35+ (codegen, math, git, sacred, omega) | `.mcp.json` |
600622
| **needle** | `zig-out/bin/needle-mcp` | 6 (structural_replace, search, quality_gates, preview, batch_edit, autonomous_refactor) | `.mcp.json` |
601623
| **zig-docs** | `npx @nichochar/zig-mcp` | 4 (list/get builtins, search/get std lib) | `.mcp.json` |
624+
| **railway** | `npx @railway/mcp-server` | deploy, logs, env vars, domains, services | `.mcp.json` |
602625
| **vibee** | `vibee/gleam/run_mcp.sh` | VIBEE compiler tools | `~/.claude/settings.json` |
603626
| **neon** | `npx @neondatabase/mcp-server-neon` | Database management | `~/.claude/settings.json` |
604627

@@ -610,6 +633,8 @@ Full Claude Code modernization: MCP servers, custom skills, automation hooks, pa
610633
| `/vsa-verify` | VSA mathematical proof verification | `.claude/skills/vsa-verify/SKILL.md` |
611634
| `/vibee-gen` | Generate Zig/Verilog from .vibee specs | `.claude/skills/vibee-gen/SKILL.md` |
612635
| `/trinity-test` | Run test suites with analysis | `.claude/skills/trinity-test/SKILL.md` |
636+
| `/god-mode` | Agent monitoring dashboard (GOD MODE) | `.claude/skills/god-mode/SKILL.md` |
637+
| `/railway-ssh` | Railway cloud server management | `.claude/skills/railway-ssh/SKILL.md` |
613638

614639
### Automation Hooks (6 events)
615640

@@ -641,7 +666,12 @@ Full Claude Code modernization: MCP servers, custom skills, automation hooks, pa
641666

642667
| Variable | Value | Purpose |
643668
|----------|-------|---------|
644-
| `TRINITY_PROJECT_ROOT` | `/Users/playra/trinity-w1` | Project root for hooks/scripts |
669+
| `GH_TOKEN` | (secret) | GitHub API for swarm tools |
670+
| `TELEGRAM_BOT_TOKEN` | (secret) | Oracle → Telegram |
671+
| `TELEGRAM_CHAT_ID` | `144022504` | Oracle chat target |
672+
| `ORACLE_ENABLED` | `true` | Auto-start Oracle on MCP init |
673+
| `GITHUB_OWNER` | `gHashTag` | Repo owner for swarm |
674+
| `GITHUB_REPO` | `trinity` | Repo name for swarm |
645675
| `ZIG_VERSION` | `0.15` | Zig version constraint |
646676
| `TRINITY_MCP_PORT` | `8899` | MCP server port |
647677

@@ -652,7 +682,7 @@ Trinity packaged as Claude Code plugin in `.claude-plugin/`:
652682
```
653683
.claude-plugin/
654684
plugin.json # trinity-vsa-framework v1.0.0
655-
skills/ # 4 custom skills
685+
skills/ # 6 custom skills
656686
hooks/hooks.json # 6 hook events (all synced with global)
657687
.mcp.json # trinity + needle + zig-docs servers
658688
```

0 commit comments

Comments
 (0)