Skip to content

docs: add AGENTS.md to orient AI coding agents - #622

Merged
fortuna merged 1 commit into
masterfrom
docs/agents-md
Sep 15, 2026
Merged

fortuna merged 1 commit into
masterfrom
docs/agents-md

Conversation

@fortuna

@fortuna fortuna commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

What

Adds an AGENTS.md at the repository root describing the project for AI coding
agents (and, incidentally, for new human contributors).

Why

Intra is a hybrid Java + Go project with a few conventions that are easy to get
wrong and are only discoverable by reading the code and the Gradle build:

  • The Go module is named localhost/Intra and lives at the repo root, while the
    Go sources are under Android/app/src/go/. Imports look like
    localhost/Intra/Android/app/src/go/doh, which looks like a mistake but isn't.
  • Only backend, intra, intra/split and intra/protect are passed to
    gomobile bind (goSourcePackages in Android/app/build.gradle), and
    anything exported from backend must respect gomobile's type restrictions
    (hence workarounds like the comma-separated ipsStr in NewDoHServer).
  • Any Go code opening an external socket must go through
    protect.MakeDialer / protect.MakeListenConfig, or traffic loops back into
    the VPN.
  • debug.SetGCPercent(10) in backend/init.go is deliberate.
  • Logging goes through the logging package, not log/fmt.

Contents

  • Project overview and repository layout
  • Architecture diagram and the TUN -> GoVpnAdapter -> backend.ConnectSession
    -> intra.Tunnel flow
  • Go and Gradle build/test commands
  • Conventions and gotchas (module path, gomobile limits, socket protection,
    strict dependency locking, localization, license headers)
  • Commit/PR conventions and a pre-submit checklist

Documentation only; no code changes.

Documents the hybrid Java/Go layout, the localhost/Intra module path,
gomobile binding constraints, build and test commands, and the project
conventions that are otherwise only discoverable by reading the code.
@fortuna
fortuna requested review from jyyi1 and peterwgnd September 15, 2026 16:44

@peterwgnd peterwgnd left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@fortuna
fortuna added this pull request to stack #624 September 15, 2026 16:57
@fortuna
fortuna merged commit 92eb90b into master Sep 15, 2026
12 checks passed
@fortuna
fortuna deleted the docs/agents-md branch September 15, 2026 16:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants