From c870f0df15a23bca5ea5503b681573ec9b86b912 Mon Sep 17 00:00:00 2001 From: Ayo Date: Sat, 11 Jul 2026 14:40:39 +0200 Subject: [PATCH] chore: initial agent instructions --- AGENTS.md | 39 +++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 7 +++++++ 2 files changed, 46 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9a0271c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# AGENTS.md + +Guidance for AI agents (and humans) working in this repository. + +## What this is + +A personal Bash toolkit dispatched through a single parent command, `ayo.sh` (aliased `yo`). Each capability is its own `*.sh` script; `ayo.sh` routes to them. One larger component, `tasks`, is a standalone Python curses TUI. There is no build step and no unit-test framework. + +## Running & developing + +- **Entry point:** `./ayo.sh [args]`, normally via the `yo` alias. An unmatched command prints `Command not found`. +- **Setup** (from the README): `cp example.conf ~/ayo.conf` and edit the values; alias `yo` → `/ayo.sh`; `pnpm install` (installs the Husky git hook). +- **Config is required and lives outside the repo** at `~/ayo.conf` (the repo ships `example.conf` as the template). Almost every script starts with `. ${HOME}/ayo.conf` then `. ${scripts_dir}/functions.sh`, so nothing works until `~/ayo.conf` exists and defines `scripts_dir`. +- **Tests:** there is no framework — `npm test` deliberately errors. The closest thing is the `tasks` app's self-test: `./tasks selftest` (exercises create/redate/log/move on a throwaway temp store). Syntax-check the Python with `python3 -c "import ast; ast.parse(open('tasks').read())"`. +- **Git remotes:** `gh` (GitHub), `sh` (SourceHut), `origin` (git.ayo.run). The Husky `post-commit` hook auto-pushes to `gh` and `sh`. + +## Architecture + +**Dispatcher + sourcing.** `ayo.sh` is one large `case $1 in` mapping short aliases and full names to scripts. Two-letter shortcuts are namespaced by first letter — `j*` journal, `n*` notes, `g*` git (e.g. `ns` = notes sync, `gd` = git diff, `ja` = journal append). Sub-scripts are invoked by **sourcing** (`. ${scripts_dir}/foo.sh "$@"`), not executing — they run in `ayo.sh`'s own shell. Two consequences to respect: + +- An `exit` in any sub-script kills the whole `ayo.sh` invocation. +- Env vars and shell state set in one script leak into the dispatcher and siblings. + +**Config-as-variables.** All paths and preferences come from `~/ayo.conf` variables (`scripts_dir`, `notes_dir`, `tasks_dir`, `tasks_template`, `editor`, ollama hosts, display outputs, …). Never hardcode a path — read the config variable. When adding a configurable location, add it to `example.conf`, and if the launcher/app needs it, pass it through `ayo.sh` as an env var — this is how `tasks_dir`/`tasks_template` become the `TASKS_HOME`/`TASKS_TEMPLATE` seen by the `tasks` app. + +**Shared helpers** live in `functions.sh` (sourced after config). The key one is `notesSync()`: pings the notes remote, then pull-rebase / add / commit / push of `notes_dir`, with a timeout-and-retry loop when offline. `editFile()` wraps "sync → open editor → sync". The notes store is itself a git repo that gets synced around edits. + +**The `tasks` app** is the most substantial subsystem — a single-file Python 3 curses TUI (no file extension, stdlib only) for managing markdown task files. Its data model is enforced in code, and these invariants matter when editing it: + +- **Status is the folder** a task lives in (`backlog` → `next` → `in-progress` → `done`); there is no status field. +- **The filename's date is the last-updated date** — every mutation re-dates the filename, while the `id:` frontmatter is a stable handle that is never rewritten. +- Moves/renames use `git mv` when the file lives in a repo. +- New tasks render from a **single template file** — the source of truth for a task's shape — at `$TASKS_TEMPLATE` (default `$TASKS_HOME/_TEMPLATE.md`), auto-seeded if missing. Inline `#` field comments and HTML comments in the template are stripped on render. +- It runs as a curses TUI given a TTY, and otherwise exposes headless subcommands (`list`, `show`, `new`, `move`, `selftest`). `ayo.sh` launches it wrapped in a `notes.sh sync` before and after. + +## Conventions + +- Editor artifacts (`.*.un~`, `*.swp`) litter the tree but are gitignored (`*~`, `*swp`); ignore them and don't commit them. +- Targets Linux; the README notes macOS differences (e.g. `timeout` via `brew install coreutils`). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b1a648f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +The guidance for this repository is maintained generically in [AGENTS.md](./AGENTS.md) so it applies to any coding agent. Read it and follow it. + +@AGENTS.md