Skip to content

Commit ba6eef3

Browse files
Antigravity Agentclaude
Antigravity Agent
and
claude
committed
feat(bridge): Bridge Manual skill — full reference for AI agents
/bridge status — quick health check /bridge test — send test command via bridge /bridge manual — full API reference (13 sections) Architecture, endpoints, whitelist, Protocol v2, Scholar, patterns, error handling, GitHub board, faculty, metrics, AGI loop. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b317527 commit ba6eef3

1 file changed

Lines changed: 310 additions & 0 deletions

File tree

‎.claude/skills/bridge/SKILL.md‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
---
2+
name: bridge
3+
description: Trinity Bridge manual — architecture, endpoints, commands, patterns for Perplexity-Railway-Mac-Claude Code channel. Reference for all AI agents.
4+
argument-hint: [status|test|manual]
5+
allowed-tools: Bash(curl *), Bash(pgrep *), Bash(tail *), Bash(cat *), Bash(echo *), Bash(date *), Read
6+
---
7+
8+
# TRINITY BRIDGE — Instruction for Claude Code Control
9+
## Reference for AI Agents (Perplexity, Scholar, MU, Swarm)
10+
11+
---
12+
13+
## 1. ARCHITECTURE
14+
15+
```
16+
AI Agent (Perplexity/other)
17+
|
18+
| GET /px/exec?cmd=<command>&token=<TOKEN>
19+
v
20+
Railway Server (trinity-production-a1d4.up.railway.app)
21+
| perplexity_bridge.zig -> creates job -> queue
22+
v
23+
Mac Bridge Agent (tri-bridge-agent.sh, PID on Mac)
24+
| poll every 3s -> picks up job
25+
| if cmd starts with "claude:" -> env -u CLAUDECODE claude --print "<prompt>"
26+
| else -> shell exec (diag, status, build, test...)
27+
v
28+
Claude Code (autonomous session, timeout 600s)
29+
| executes prompt -> stdout
30+
v
31+
Bridge Agent -> POST /px/done -> result saved
32+
v
33+
AI Agent -> GET /px/result?id=<job_id> -> reads result
34+
```
35+
36+
---
37+
38+
## 2. ENDPOINTS
39+
40+
### Base URL
41+
```
42+
https://trinity-production-a1d4.up.railway.app
43+
```
44+
45+
### Token
46+
```
47+
PX_BRIDGE_TOKEN=d9d42042ada98a9557c9cb5b1609edd88447d72ecda16f2ce723a6bca4718df5
48+
```
49+
50+
### API Reference
51+
52+
| Endpoint | Method | Description | Example |
53+
|----------|--------|-------------|---------|
54+
| `/px/status` | GET | Server health + queue | `?token=TOKEN` |
55+
| `/px/exec` | GET | Submit command | `?cmd=diag&token=TOKEN` |
56+
| `/px/jobs` | GET | List all jobs | `?token=TOKEN` |
57+
| `/px/result` | GET | Result of specific job | `?id=JOB_ID&token=TOKEN` |
58+
| `/px/done` | POST | Write result (bridge-agent) | body: raw text, id+exit in query |
59+
60+
---
61+
62+
## 3. COMMANDS (WHITELIST)
63+
64+
### Shell commands (instant, <5s)
65+
66+
| Command | What it does | When to use |
67+
|---------|-------------|-------------|
68+
| `diag` | zig build + compile rate + dirty files | Quick health check |
69+
| `status` | git status --short + git log -5 | What changed? |
70+
| `build` | zig build 2>&1 | Check compilation |
71+
| `test` | zig build test 2>&1 | Run tests |
72+
| `issues` | gh issue list --limit 20 | List open issues |
73+
| `log` | git log --oneline -20 | Recent commits |
74+
| `branch` | git branch --show-current | Current branch |
75+
| `help` | List available commands | Help |
76+
77+
### Claude commands (autonomous, up to 600s)
78+
79+
Format: `claude:<prompt>`
80+
81+
| Example | What it does |
82+
|---------|-------------|
83+
| `claude:Fix 5 broken specs` | Find and fix broken specs |
84+
| `claude:Run /scholar scan` | Launch Scholar research |
85+
| `claude:Run /scholar full` | Full Scholar cycle |
86+
| `claude:Run /scholar topic:"quantum computing"` | Deep research on topic |
87+
| `claude:Execute Protocol v2 on issue 79` | Full development cycle |
88+
| `claude:Run /tri` | Full system diagnostic |
89+
| `claude:git add -A && git commit -m "msg" && git push` | Commit and push |
90+
91+
---
92+
93+
## 4. PROTOCOL V2 (Development Management)
94+
95+
To create a feature via Claude Code:
96+
97+
```
98+
claude:Execute Protocol v2 on issue {N}.
99+
Create sub-issues RESEARCH PLAN IMPLEMENT TEST VERIFY.
100+
Implement code, run tests, close all sub-issues.
101+
```
102+
103+
Phases:
104+
1. **RESEARCH** — study the problem, gather context
105+
2. **PLAN** — create implementation plan
106+
3. **IMPLEMENT** — write code
107+
4. **TEST** — run tests
108+
5. **VERIFY** — final check, close issue
109+
110+
---
111+
112+
## 5. SCHOLAR SKILL (Research Agent)
113+
114+
| Command | Action |
115+
|---------|--------|
116+
| `/scholar scan` | Scan: open issues + broken specs + TODOs -> call perplexity_research MCP |
117+
| `/scholar eval` | Evaluate findings: HIGH (>0.8) / MEDIUM (>0.5) / LOW |
118+
| `/scholar apply` | HIGH -> gh issue create, MEDIUM -> MU DB, LOW -> archive |
119+
| `/scholar full` | scan -> eval -> apply sequentially |
120+
| `/scholar errors` | Focus on current compile failures |
121+
| `/scholar report` | Show cached results (no API calls) |
122+
| `/scholar topic:"query"` | Deep research on specific topic |
123+
124+
Via bridge:
125+
```
126+
/px/exec?cmd=claude:Run /scholar full&token=TOKEN
127+
```
128+
129+
---
130+
131+
## 6. USAGE PATTERNS
132+
133+
### Monitoring (every 30 min)
134+
```
135+
1. GET /px/exec?cmd=diag -> compile rate, dirty files
136+
2. GET /px/result?id=<id> -> read result
137+
3. If compile < 90% -> send fix command
138+
4. If dirty > 0 -> send commit command
139+
```
140+
141+
### Bug fixing (autonomous)
142+
```
143+
1. GET /px/exec?cmd=claude:Find and fix all zig ast-check failures. Commit fixes.
144+
2. Wait 5-10 min
145+
3. GET /px/result?id=<id> -> read what was fixed
146+
4. GET /px/exec?cmd=diag -> confirm new compile rate
147+
```
148+
149+
### Research loop (every 24h)
150+
```
151+
1. GET /px/exec?cmd=claude:Run /scholar full
152+
2. Wait 10-15 min
153+
3. GET /px/exec?cmd=issues -> see new research issues
154+
```
155+
156+
### Feature development (30-60 min)
157+
```
158+
1. GET /px/exec?cmd=claude:Execute Protocol v2 on issue {N}
159+
2. Wait 10-30 min
160+
3. GET /px/result?id=<id> -> status
161+
4. GET /px/exec?cmd=diag -> build health after changes
162+
```
163+
164+
---
165+
166+
## 7. ERROR HANDLING
167+
168+
| Error | Cause | Solution |
169+
|-------|-------|---------|
170+
| `{"error":"unknown command"}` | Command not in whitelist | Use `claude:` prefix |
171+
| `404` on /px/result | Job cleaned or doesn't exist | Job may have expired, resend |
172+
| `status: pending` | Bridge-agent not running on Mac | Start: `./deploy/tri-bridge-agent.sh` |
173+
| `nested session error` | CLAUDECODE env var not unset | In agent.sh: `env -u CLAUDECODE` |
174+
| `timeout` | Claude Code thinking >600s | Break task into smaller pieces |
175+
| `failed to post result` | Railway didn't accept POST | Check /px/done endpoint |
176+
| Empty `/px/jobs` | Railway redeploy cleared queue | Normal — send new job |
177+
178+
---
179+
180+
## 8. COMPONENT STATUS
181+
182+
### How to check everything works
183+
```
184+
GET /px/status -> {"status":"ok","queue_pending":N,"queue_running":N}
185+
```
186+
187+
| Component | Check | Expected |
188+
|-----------|-------|----------|
189+
| Railway Server | GET /px/status | `{"status":"ok"}` |
190+
| Bridge Agent | `pgrep -f tri-bridge-agent` on Mac | PID exists |
191+
| Claude Code | Send `claude:echo hello` | Result: "hello" |
192+
| Perplexity MCP | `claude:Run perplexity_search "test"` | Search results |
193+
| GitHub Board | https://github.com/users/gHashTag/projects/6 | Issues visible |
194+
195+
---
196+
197+
## 9. GITHUB INTEGRATION
198+
199+
### Repository
200+
```
201+
https://github.com/gHashTag/trinity
202+
```
203+
204+
### Project Board
205+
```
206+
https://github.com/users/gHashTag/projects/6/views/1
207+
```
208+
209+
### Board Columns
210+
| Column | Meaning |
211+
|--------|---------|
212+
| Backlog | New/pending issues |
213+
| Ready | P0/P1, ready to work |
214+
| In Progress | Currently in development |
215+
| In Review | Code written, needs review |
216+
| Done | Closed and verified |
217+
218+
### Labels
219+
| Label | Meaning |
220+
|-------|---------|
221+
| P0 | Critical priority |
222+
| P1 | High priority |
223+
| P2 | Medium priority |
224+
| agent:ralph | For Ralph Agent |
225+
| agent:mu | For MU Agent |
226+
| agent:swarm | For Swarm Agent |
227+
| research:high | Scholar finding, high relevance |
228+
229+
---
230+
231+
## 10. FACULTY (TRI UNIVERSITY)
232+
233+
| Agent | Role | How to invoke |
234+
|-------|------|--------------|
235+
| Ralph | Engineer — build, fix, implement | `claude:Execute Protocol v2 on issue N` |
236+
| Scholar | Researcher — search, analyze | `claude:Run /scholar scan` |
237+
| MU | Memory — error patterns, learning | `claude:Run /tri` (MU section) |
238+
| Oracle | phi-Analyst — metrics, harmony | `claude:Run /tri` (Oracle section) |
239+
| Swarm | Coordinator — task decomposition | `claude:tri swarm run N` |
240+
| Linter | QA — vibee check, ast-check | `claude:zig build 2>&1` |
241+
| Bridge | Comms — Perplexity <-> Trinity | `/px/status` |
242+
243+
---
244+
245+
## 11. KEY METRICS
246+
247+
| Metric | Command | Target |
248+
|--------|---------|--------|
249+
| Compile Rate | `diag` -> COMPILE:X/Y | >= 90% |
250+
| Build Status | `build` | EXIT:0 |
251+
| Dirty Files | `diag` -> DIRTY:N | 0 |
252+
| Open Issues | `issues` | Decreasing |
253+
| Task Success | `/tri` -> job success % | > 50% |
254+
| V (Oracle) | phi * (compile%)^2 | -> 1.618 (phi) |
255+
256+
---
257+
258+
## 12. URL ENCODING
259+
260+
Spaces in commands:
261+
- `+` -> space (preferred)
262+
- `%20` -> space
263+
- `%3A` -> `:` (for claude:)
264+
265+
Full URL example:
266+
```
267+
https://trinity-production-a1d4.up.railway.app/px/exec?cmd=claude:Fix+broken+specs&token=TOKEN
268+
```
269+
270+
---
271+
272+
## 13. AUTONOMOUS MODE (AGI LOOP)
273+
274+
```
275+
+-----------------------------------------------------+
276+
| AGI LOOP (24h) |
277+
| |
278+
| 06:00 UTC Scholar /scholar full |
279+
| | -> scan -> eval -> apply |
280+
| v |
281+
| 06:30 UTC New research issues on board |
282+
| | |
283+
| v |
284+
| 07:00 UTC Ralph: Protocol v2 on each HIGH issue |
285+
| | -> RESEARCH -> PLAN -> IMPLEMENT -> TEST |
286+
| v |
287+
| 12:00 UTC MU: analyze morning errors |
288+
| | -> update Learning DB |
289+
| v |
290+
| 18:00 UTC Scholar /scholar errors |
291+
| | -> fix what broke |
292+
| v |
293+
| 00:00 UTC Diag -> report -> Telegram |
294+
| | -> daily metrics |
295+
| v |
296+
| Repeat |
297+
+-----------------------------------------------------+
298+
```
299+
300+
---
301+
302+
## Skill Modes
303+
304+
If $ARGUMENTS is provided:
305+
306+
- `status` — Run quick bridge health check: curl /px/status, pgrep bridge-agent, show results
307+
- `test` — Send a test command (`claude:echo bridge test ok`) and poll for result
308+
- `manual` — Display this full manual
309+
310+
Default (no args): show `status`.

0 commit comments

Comments
 (0)