docs: reusable agent brief — what Gluecron is + build specs for external agents #5476
1 changed file+135−0
Addeddocs/AGENT-BRIEF.md+135−0View fileUnifiedSplit
@@ -0,0 +1,135 @@
1# Gluecron — brief for building agents
2
3You are building a project whose canonical home is **Gluecron**
4(https://gluecron.com) — a self-hosted, AI-native git platform: git
5hosting over Smart HTTP, issues and pull requests, CI workflows, merge
6gates, a 60-tool MCP server, and a REST API. Gluecron hosts and develops
7itself on itself; treat it as you would GitHub, with the differences
8below.
9
10A live, repo-pinned version of this brief is served at
11`https://gluecron.com/connect-claude?repo=<owner>/<repo>` — prefer it
12when you know your repo, because it reflects current state.
13
14## Auth
15
16One personal access token does everything. The human operator mints it at
17**gluecron.com/settings/tokens** (choose **never expires**; scope `repo`).
18Access is resolved by repo ownership and collaborator rows — a PAT cannot
19reach repos its account was not granted, regardless of scope.
20
21Never commit the PAT. Never put it in a URL you might log.
22
23## Three ways in
24
25**1. MCP (recommended for agents).** Add to `.mcp.json` at the project
26root, with `GLUECRON_PAT` in the environment:
27
28```json
29{
30 "mcpServers": {
31 "gluecron": {
32 "type": "http",
33 "url": "https://gluecron.com/mcp",
34 "headers": { "Authorization": "Bearer ${GLUECRON_PAT}" }
35 }
36 }
37}
38```
39
4060 tools, `gluecron_`-prefixed. The daily set: `create_pr`, `merge_pr`,
41`close_pr`, `get_pr`, `list_prs`, `create_issue`, `comment_issue`,
42`close_issue`, `search_issues`, `read_file`, `write_file`,
43`atomic_multi_file_commit`, `create_branch`, `list_tree`, `repo_search`,
44`trigger_workflow`, `get_workflow_run`, `get_workflow_logs`.
45
46**2. REST.** `https://gluecron.com/api/v2` with
47`Authorization: Bearer <PAT>`. `GET /api/v2` returns the endpoint map.
48Create a repository: `POST /api/v2/repos` with
49`{"name": "...", "description": "...", "isPrivate": true}`.
50
51**3. Git.** Clone/push URL: `https://gluecron.com/<owner>/<repo>.git`.
52Prefer a named remote with a credential helper. Pushing a branch whose
53name matches an open PR updates that PR.
54
55## The build loop
56
571. Operator (or REST) creates the repo. Private unless told otherwise —
58 private repos never appear on public surfaces.
592. Push code to `main` (first push establishes it as the default branch).
603. Work on branches: branch → push → `gluecron_create_pr` →
61 `gluecron_merge_pr`. **Never update refs directly to merge** — the
62 merge tools carry safety (non-fast-forward protection, gates,
63 close-keywords, notifications) that a raw ref update bypasses.
644. `closes #N` in a PR title/body auto-closes issues on merge.
655. Long-running issues keep a `STATUS:` line at the top, updated as work
66 proceeds — the next agent reads it before doing anything.
67
68## Merge gates
69
70Every merge is evaluated against: secret scan, AI security scan (on the
71diff), mergeability check, AI review, and **CI**. A red or still-running
72CI run for the PR's head commit **blocks the merge** — the response tells
73you why (e.g. `"CI: CI still running — merge when green"`). Typical CI
74round-trip is ~1–2 minutes after a push; wait and retry the merge rather
75than working around it.
76
77## CI workflows
78
79Files in `.gluecron/workflows/*.yml`, a subset of GitHub Actions syntax:
80
81```yaml
82name: CI
83on:
84 push:
85 branches: [main] # omit `branches` to run on every branch
86 workflow_dispatch: {}
87 # schedule: [{cron: "0 3 * * *"}] also supported
88jobs:
89 ci:
90 runs-on: self
91 steps:
92 - name: Test
93 run: |
94 bun install --frozen-lockfile
95 bun test
96```
97
98Runner truths (they will bite you if assumed otherwise):
99
100- Steps execute on **Linux inside the platform's app container**, in a
101 fresh clone of your commit. Available: `bun`, `bash`, `git`, `wget`.
102 **No `curl`.**
103- The environment is **credential-free by design** — no `DATABASE_URL`,
104 no API keys, nothing credential-shaped is passed through. Tests that
105 need secrets don't belong in CI here.
106- Per-step timeout: 10 minutes. Logs are capped — print failure summaries,
107 not floods.
108- A platform deploy can restart the container mid-run; the platform
109 detects this on boot, marks the killed run `runner_restarted`, and
110 retries it once automatically. Don't panic at that conclusion — look at
111 the retry.
112- Workflows must not attempt deployments of the platform itself; verify,
113 don't deploy.
114
115## Conventions
116
117- Repo slugs resolve case-insensitively but store exact case — use the
118 exact stored casing in tool calls when you know it.
119- AI features that run on the platform's API budget are metered; don't
120 loop AI endpoints unnecessarily.
121- If gluecron.com is unreachable, stop and surface it to the operator —
122 do not silently fall back to another host.
123
124## Starting a brand-new project (e.g. a fresh platform build)
125
1261. Operator mints a never-expiring `repo`-scope PAT.
1272. `POST /api/v2/repos {"name": "<Project>", "isPrivate": true}` (or the
128 operator creates it in the UI).
1293. Add the `.mcp.json` above to the project; export `GLUECRON_PAT`.
1304. `git remote add origin https://gluecron.com/<owner>/<Project>.git`,
131 push `main`.
1325. Add `.gluecron/workflows/ci.yml` (template above) in the first PR —
133 the CI merge gate activates automatically once runs exist.
1346. File the build plan as issues; keep `STATUS:` lines current; work in
135 PR-sized increments through the merge gates.
0136
c comment · e edit title · m merge · a approve · r request changes · ? shortcuts