diff --git a/dotfiles/agents/AGENTS.md b/dotfiles/agents/AGENTS.md index 675bb990..5505f9f1 100644 --- a/dotfiles/agents/AGENTS.md +++ b/dotfiles/agents/AGENTS.md @@ -51,3 +51,26 @@ - The pass password store lives at `~/.password-store/`. - Use `pass show ` to retrieve a secret, or `pass find ` to locate entries. - Never hardcode credentials or store them in plain text files. + +## Project links (local symlink index) +- Paths in this section are relative to this file's directory (`dotfiles/agents/`). +- Keep a local symlink index under `./project-links/` for projects that are frequently referenced. +- Treat these links as machine-local discovery state maintained by agents (do not commit machine-specific targets). +- Reuse existing symlinks first. If a link is missing or stale, search for the repo, then update the link with: + + ln -sfn "" "./project-links/" + +- If a project cannot be found quickly, do a targeted search (starting from likely roots) and only then widen the search. + +## Project constellation guides +- Keep per-constellation context in `./project-guides/` and keep this file minimal. +- When a request involves one of these projects: + - Open the guide first. + - If a mentioned repo/package name matches a guide's related-project list, open that guide even if the user did not name the constellation explicitly. + - Ensure required links exist under `./project-links/`. + - If links are missing, run a targeted search from likely roots, then create/update the symlink. +- Guide index: + - `./project-guides/mova-org-agenda-api.md` + - `./project-guides/taffybar.md` + - `./project-guides/railbird.md` + - `./project-guides/org-emacs-packages.md` diff --git a/dotfiles/agents/project-guides/mova-org-agenda-api.md b/dotfiles/agents/project-guides/mova-org-agenda-api.md new file mode 100644 index 00000000..496cac3f --- /dev/null +++ b/dotfiles/agents/project-guides/mova-org-agenda-api.md @@ -0,0 +1,29 @@ +# Mova / org-agenda-api constellation + +## Scope +- Use this guide for requests involving the mova constellation, including `org-agenda-api`. +- Primary anchor is the mova root repo; start there and branch out. + +## Related packages/projects (trigger list) +- If any of these names are mentioned, open this guide for context. +- `mova-dev`: coordination repo for the mova ecosystem and cross-repo workflows. +- `mova`: React Native app (iOS/Android/Web). +- `org-agenda-api`: Emacs Lisp HTTP API and deployment container. +- `org-window-habit`: habit-tracking logic used by org workflows. +- `org-wild-notifier`: org notification logic and scheduling behavior. +- `dotfiles` (within mova-dev context): infra/config and deployment glue for org-agenda-api. + +## Symlink targets +- `./project-links/mova-dev` -> mova constellation root. + +## Discovery hints +- Check likely roots first, especially `~/Projects`. +- Common local path is `~/Projects/mova-dev`, but do not assume it exists. +- If the symlink is missing or stale, search by directory name first, then by repo names. + +## Read-first docs +- `./project-links/mova-dev/README.md` +- `./project-links/mova-dev/org-agenda-api/README.md` (if present) + +## Notes +- Prefer treating mova root docs as canonical project context. diff --git a/dotfiles/agents/project-guides/org-emacs-packages.md b/dotfiles/agents/project-guides/org-emacs-packages.md new file mode 100644 index 00000000..679f4fb3 --- /dev/null +++ b/dotfiles/agents/project-guides/org-emacs-packages.md @@ -0,0 +1,25 @@ +# Org / Emacs package constellation + +## Scope +- Use this guide for org-related package repos, including `org-window-habit`. +- This is especially relevant when repos are managed through local Emacs package trees. + +## Related packages/projects (trigger list) +- If any of these names are mentioned, open this guide for context. +- `org-window-habit`: org habit-tracking package/repo. +- `org-wild-notifier`: org notification package/repo. +- `org-agenda-api`: Emacs Lisp HTTP API project that loads org package deps. +- `elpaca`: Emacs package manager tree where local checkouts may live. +- `elpa`: traditional Emacs package install tree (fallback search area). + +## Symlink targets +- `./project-links/org-window-habit` -> org-window-habit repo/root. + +## Discovery hints +- Start with Emacs roots, especially `~/.emacs.d`. +- Prefer checking package manager trees (including `elpaca`) before broader searches. +- Common pattern is nested repos under `~/.emacs.d` package directories. + +## Read-first docs +- `./project-links/org-window-habit/README.md` +- `./project-links/org-window-habit/README.org` (if present) diff --git a/dotfiles/agents/project-guides/railbird.md b/dotfiles/agents/project-guides/railbird.md new file mode 100644 index 00000000..c694db6c --- /dev/null +++ b/dotfiles/agents/project-guides/railbird.md @@ -0,0 +1,28 @@ +# Railbird constellation + +## Scope +- Use this guide for requests involving railbird backend/main repo and railbird mobile app work. + +## Related packages/projects (trigger list) +- If any of these names are mentioned, open this guide for context. +- `railbird`: primary backend/main railbird repository. +- `railbird-mobile`: primary mobile app repository. +- `railbird2`: alternate/new-generation backend repo. +- `railbird-mobile2`: alternate/new-generation mobile repo. +- `railbird-docs`: documentation repository. +- `railbird-landing-page`: marketing/landing site repository. +- `railbird-alert-tuning`: alert/tuning and operational experimentation repo. +- `railbird-agents-architecture`: architecture notes/prototypes for agent workflows. + +## Symlink targets +- `./project-links/railbird` -> primary railbird repo. +- `./project-links/railbird-mobile` -> railbird mobile app repo. + +## Discovery hints +- Start from `~/Projects`. +- Common backend location is `~/Projects/railbird`. +- Mobile repo often also lives under `~/Projects`, but name/path may vary by machine. + +## Read-first docs +- `./project-links/railbird/README.md` +- `./project-links/railbird-mobile/README.md` (if present) diff --git a/dotfiles/agents/project-guides/taffybar.md b/dotfiles/agents/project-guides/taffybar.md new file mode 100644 index 00000000..51bc6cce --- /dev/null +++ b/dotfiles/agents/project-guides/taffybar.md @@ -0,0 +1,30 @@ +# Taffybar constellation + +## Scope +- Use this guide for requests involving taffybar itself or local taffybar configuration. + +## Related packages/projects (trigger list) +- If any of these names are mentioned, open this guide for context. +- `taffybar`: top-level desktop bar library/app. +- `imalison-taffybar`: personal taffybar configuration package/repo. +- `gtk-sni-tray`: StatusNotifier tray integration for taffybar. +- `gtk-strut`: X11/WM strut handling used by taffybar ecosystem. +- `status-notifier-item`: StatusNotifier protocol/types library. +- `dbus-menu`: DBus menu protocol support used by tray integrations. +- `dbus-hslogger`: DBus logging helper used in ecosystem packages. + +## Symlink targets +- `./project-links/taffybar-main` -> main taffybar repo. +- `./project-links/taffybar-config` -> local taffybar config root. + +## Discovery hints +- Start with `~/.config/taffybar`. +- Common layout is: + - config root at `~/.config/taffybar` + - main repo at `~/.config/taffybar/taffybar` +- Other taffybar-related repos may exist elsewhere; find them from docs in the main repo. + +## Read-first docs +- `./project-links/taffybar-main/README.md` +- `./project-links/taffybar-config/README.md` (if present) +- `./project-links/taffybar-config/AGENTS.md` (if present) diff --git a/dotfiles/agents/project-links/.gitignore b/dotfiles/agents/project-links/.gitignore new file mode 100644 index 00000000..d6b7ef32 --- /dev/null +++ b/dotfiles/agents/project-links/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore