Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .beads/issues.jsonl

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions .relai/notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@
- 2026-11-04 — Go toolchain pinned to 1.26.10 in go.mod (govulncheck: 0 reachable vulnerabilities; 1.23.x is out of support).
- 2026-11-04 — Handoffs are computed on demand, not stored. Nothing runs when a task finishes: the session-start hook only exists in repos where `relai init` was run, and `scripts/sync-beads.sh` is manual. A git post-commit hook that refreshes the export was proposed, not built.

- 2026-11-04 — Product goal (owner): drive several LINKED repos from one central place, for teams. Relai discovers (`index build --scan`, `discover --links`) and the agent + engineer confirm; RELAI-TEAM is the central place (task RELAI-TEAM-9os). A mention is evidence, never a declared link. The scan must follow symlinks: the owner's projects are symlinks into `projets/` (a first version found 9 of 16).

### Pitfalls
<!-- Things that cost time once and will again: symptom → cause → what to do. -->
- `bd init` makes its own commit and edits AGENTS.md/.gitignore → use `--skip-agents --skip-hooks`, then `git reset --soft HEAD~1` and recommit.
Expand Down
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,25 @@ active projects are named without detail, then only counted.
`relai handoff` stays the answer for one project: it is the same idea at the scale of one repository, and it now asks `bd`
only when the project changed since the last time (the answers are cached in your user cache directory, never in the repo).

## Find your projects and how they relate

You do not have to write the list of your projects by hand:

```sh
relai index build --scan ~/projects # every git repo of the folder (symlinks included); says which need `relai init`
relai discover --links ~/projects # the mentions between them: who points at whom, and how strongly
relai discover --links ~/projects --prompt # instructions for your agent to check each mention with you
relai discover --links ~/projects --propose # a `links:` block per relai.yaml to check and paste yourself
```

The result is **evidence, not a verdict**. *Strong*: a repository holds the other's remote URL or a relative path to it (a
deployment manifest pointing at an application). *Weak*: its name appears as a word (it can be an ordinary word, and names
under four letters are not searched this way). Each line shows counts and up to three file paths, never content, and
generated files (`node_modules`, `vendor`, lock files, `graphify-out`) are ignored. Nothing is ever written: the intended
flow is that your agent verifies each mention against the files, shows you a table, and writes `links:` into `relai.yaml`
only once you agree. `links:` (ids of the repositories this one works with) is read by the index and shown by
`relai workspace`; `provides:`/`consumes:` still say *what*, `links:` says *who*.

## Check before you build

Before writing a new capability, check whether one of your other projects already provides it, using
Expand Down
61 changes: 54 additions & 7 deletions cmd/relai/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,14 @@ import (
"fmt"
"os"
"path/filepath"
"strings"

"github.com/ECG-Rudy-Glt/RELAI/internal/discover"
"github.com/ECG-Rudy-Glt/RELAI/internal/handoff"
"github.com/ECG-Rudy-Glt/RELAI/internal/index"
"github.com/ECG-Rudy-Glt/RELAI/internal/initrepo"
"github.com/ECG-Rudy-Glt/RELAI/internal/scaffold"
"github.com/ECG-Rudy-Glt/RELAI/internal/scan"
"github.com/ECG-Rudy-Glt/RELAI/internal/workspace"
)

Expand All @@ -30,9 +32,14 @@ Usage:
relai handoff [dir] print the current state of the work (≤ 2,000 tokens by default)
relai discover [dir] list what the project already gives agents (skills, hooks, specs, docs…);
--prompt prints instructions for your agent to draft .relai/notes.md
relai index build [-o <path>] <list-file>
read each repo path/URL in <list-file> and collect their relai.yaml
into an index (default: .relai/index.json)
relai index build [-o <path>] [--scan <folder>] [<list-file>]
read each repo path/URL in <list-file> (and/or every git repo in --scan <folder>)
and collect their relai.yaml into an index (default: .relai/index.json)
relai discover --links <folder> [--propose | --prompt] [--json]
mentions between the git repos of <folder> (strong: remote URL or relative path;
weak: the name as a word). Evidence, not verified links; --propose prints a
links: block per relai.yaml to check and paste yourself; --prompt prints instructions
for your agent to verify each mention with you (nothing is ever written)
relai find [--index <path>] <capability>
search the index for repos that already provide <capability>
relai workspace [--index <path>] [--max-tokens N]
Expand Down Expand Up @@ -95,12 +102,31 @@ func main() {
fs := flag.NewFlagSet("discover", flag.ExitOnError)
prompt := fs.Bool("prompt", false, "print instructions for an agent to draft .relai/notes.md from what was found")
asJSON := fs.Bool("json", false, "print the inventory as JSON")
links := fs.Bool("links", false, "treat the argument as a folder of repositories and print the mentions between them")
propose := fs.Bool("propose", false, "with --links: print a links: block for each relai.yaml to check and paste yourself")
_ = fs.Parse(reorderArgs(fs, os.Args[2:]))
target := dirArg(fs)
if st, err := os.Stat(target); err != nil || !st.IsDir() {
fmt.Fprintf(os.Stderr, "relai: %s is not a directory\n", target)
os.Exit(1)
}
if *links || *propose {
repos, err := scan.Find(target)
exitOn(err)
ls := scan.Links(repos)
switch {
case *asJSON:
b, _ := json.MarshalIndent(map[string]any{"repos": repos, "links": ls}, "", " ")
fmt.Println(string(b))
case *prompt:
fmt.Print(scan.Prompt(target, repos, ls))
case *propose:
fmt.Print(scan.Propose(repos, ls))
default:
fmt.Print(scan.Text(target, repos, ls))
}
return
}
inv := discover.Scan(target)
switch {
case *prompt:
Expand All @@ -122,13 +148,34 @@ func main() {
}
fs := flag.NewFlagSet("index build", flag.ExitOnError)
out := fs.String("o", defaultIndexPath, "write the index to this file")
scanDir := fs.String("scan", "", "find the git repositories in this folder instead of (or in addition to) a list file")
_ = fs.Parse(reorderArgs(fs, os.Args[3:]))
if fs.NArg() < 1 {
fmt.Fprintln(os.Stderr, "usage: relai index build [-o <path>] <list-file>")
if fs.NArg() < 1 && *scanDir == "" {
fmt.Fprintln(os.Stderr, "usage: relai index build [-o <path>] [--scan <folder>] [<list-file>]")
os.Exit(2)
}
sources, err := index.ReadList(fs.Arg(0))
exitOn(err)
var sources []string
if fs.NArg() >= 1 {
var err error
sources, err = index.ReadList(fs.Arg(0))
exitOn(err)
}
if *scanDir != "" {
repos, err := scan.Find(*scanDir)
exitOn(err)
var without []string
for _, r := range repos {
sources = append(sources, r.Path)
if !r.Relai {
without = append(without, r.Name)
}
}
fmt.Printf("scan: %d repositories in %s, %d with a relai.yaml", len(repos), *scanDir, len(repos)-len(without))
if len(without) > 0 {
fmt.Printf("; without one (skipped, run `relai init` there to include them): %s", strings.Join(without, ", "))
}
fmt.Println()
}
entries, skipped := index.Build(sources)
for _, sk := range skipped {
fmt.Fprintf(os.Stderr, "skipped %s: %s\n", sk.Source, sk.Reason)
Expand Down
2 changes: 1 addition & 1 deletion docs/HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ no central service, no Backstage, no federation or SSO.
| Area | State |
|---|---|
| Release | **v0.2.0** is published (6 platform archives + `checksums.txt`); `scripts/install.sh` verifies the SHA-256 before installing and never runs `sudo` on its own. `main` is ahead of it by the fixes below once they merge |
| CLI | Go, stdlib only, `cmd/relai`: `init` (AGENTS.md, relai.yaml, `.relai/notes.md`, and for Claude Code a `CLAUDE.md` plus a SessionStart hook; never overwrites; `--no-claude`), `handoff`, `discover`, `index build` / `find`, `workspace` (one budgeted overview of all indexed projects, files only), `new <template> <dir>`, `version`. Flags may come before or after the arguments. `init --hooks` adds a git pre-commit hook that keeps `.beads/issues.jsonl` current |
| CLI | Go, stdlib only, `cmd/relai`: `init` (AGENTS.md, relai.yaml, `.relai/notes.md`, and for Claude Code a `CLAUDE.md` plus a SessionStart hook; never overwrites; `--no-claude`), `handoff`, `discover`, `index build` / `find`, `index build --scan <folder>` and `discover --links <folder>` (find the repos of a folder and the mentions between them: evidence, never verdicts), `workspace` (one budgeted overview of all indexed projects, files only), `new <template> <dir>`, `version`. Flags may come before or after the arguments. `init --hooks` adds a git pre-commit hook that keeps `.beads/issues.jsonl` current |
| Handoff | Format **v0.5** (see `spec/handoff.md`, changelog at the end). Deterministic, about 2,000 tokens at most, degraded mode for repos with no harness, honest messages when `bd` or `openspec` cannot be read |
| Tests | `go test ./...`: handoff (budget, degraded mode, hygiene, large inputs), initrepo, discover, index (every `provides` list shape), scaffold (symlinks, binary files, token substitution), CLI args. CI runs gofmt, vet, test |
| Experiment E2 | `eval/README.md`. The gain is mostly in turns (1 instead of 4-30); in tokens it is 1.2x-3.4x in dollars, more in raw tokens, and nothing on repos with no tracker or notes. Do not quote the 56x figure (it is a size estimate, not an agent measurement) |
Expand Down
2 changes: 1 addition & 1 deletion docs/multi-repo.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ active changes, the `### Next` of the notes — plus *upstream changes* when a r
changed. Same rules as the single-repo handoff (deterministic, budgeted, pointers to
`relai handoff <repo>` for detail).

**What exists today.** A first slice ships as `relai workspace` (2026-11-04): from the index built by
**What exists today.** `relai index build --scan` and `relai discover --links` find the repositories of a folder and the mentions between them (evidence for a person or agent to confirm; `relai.yaml` gets an optional `links:`). A first slice of this view ships as `relai workspace` (2026-11-04): from the index built by
`relai index build` it prints one budgeted block per indexed project (last commit, open and in-progress
task counts, the top tasks, what it provides), reading files only and never running `bd`. Still planned
from the text above: the `### Next` of the notes, the `next:` of active changes, the *Check first* lines
Expand Down
12 changes: 12 additions & 0 deletions internal/index/find_reason_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,15 @@ func TestGitReason(t *testing.T) {
t.Error("empty stderr should give no reason")
}
}

func TestLinksAreParsedInAnyListShape(t *testing.T) {
for name, src := range map[string]string{
"block": "id: x\nlinks:\n - portfolio # strong: 3 files\n - shelfmark\n",
"inline": "id: x\nlinks: [portfolio, shelfmark]\n",
} {
m, warn := parseManifest([]byte(src))
if len(m.Links) != 2 || m.Links[0] != "portfolio" || m.Links[1] != "shelfmark" || len(warn) != 0 {
t.Errorf("%s: links = %v warn = %v", name, m.Links, warn)
}
}
}
13 changes: 13 additions & 0 deletions internal/index/index.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ type Manifest struct {
Owners []string `json:"owners,omitempty"`
Provides []Capability `json:"provides,omitempty"`
Consumes []Capability `json:"consumes,omitempty"`
// Links are the ids of the repositories this one works with, declared by a person after checking
// the mentions `relai discover --links` found. Capabilities say what; links say who.
Links []string `json:"links,omitempty"`
}

// Entry is one indexed repo: where it came from and its parsed manifest.
Expand Down Expand Up @@ -206,6 +209,16 @@ func parseManifest(b []byte) (Manifest, []string) {
if rest != "" {
m.Owners = inlineList(rest)
}
case "links":
var caps []Capability
var w []string
i, caps, w = capabilityList(lines, i, rest)
for _, x := range w {
warn = append(warn, "links: "+x)
}
for _, c := range caps {
m.Links = append(m.Links, c.Capability)
}
case "provides", "consumes":
var caps []Capability
var w []string
Expand Down
Loading
Loading