feat: agents

agents/AGENTS.md

@@ -0,0 +1,66 @@
+# RULES - Global Agent Baseline
+
+This file defines the cross-project baseline for AI coding agents. It focuses on safety, boundaries,
+and portable behavior.
+
+## 1) Instruction Priority
+
+Apply instructions in this order:
+
+1. Runtime system/developer instructions
+2. User task request
+3. Project-local policy (`AGENTS.md`, `CLAUDE.md`, repo docs)
+4. This global RULES
+
+If rules conflict, follow the higher-priority source and state the conflict briefly.
+
+## 2) Hard Safety Boundaries (MUST NOT)
+
+- MUST NOT read/write outside the approved workspace.
+- MUST NOT perform broad operations on the entire home directory.
+- MUST NOT run remote-mutating commands unless explicitly requested.
+  - Examples: `kubectl apply/delete`, `helm upgrade`, `terraform apply`, remote `ssh` mutation.
+- MUST NOT use destructive/force options unless explicitly requested.
+  - Examples: `--force`, `rm -rf`, `git reset --hard`, `git push --force`.
+- MUST NOT expose or commit secrets (tokens, keys, kubeconfig credentials, passwords).
+
+## 3) Security and Secrets Handling
+
+- Never write secret literals into tracked files.
+- Use environment variables, secret managers, or placeholders.
+- Redact sensitive output in logs and summaries.
+- For infra/IaC changes, prefer plan/eval/check before apply/switch.
+
+## 4) Scope Discipline
+
+- Keep changes strictly within requested scope.
+- Do not refactor unrelated areas unless user asks.
+- Preserve backward compatibility unless a breaking change is explicitly requested.
+
+## 5) Change Hygiene
+
+- Keep diffs minimal and reviewable.
+- Group logically related edits together.
+- Do not revert user/unrelated changes unless explicitly asked.
+- Do not claim verification you did not run.
+
+## 6) Tooling Defaults
+
+- Prefer fast discovery tools (`rg`, `fd`) where available.
+- Prefer project task runners (`just`, `make`, `task`, `npm scripts`, etc.) over ad-hoc commands
+  when equivalent.
+- If a required command is not already available, use only `nix run`, `nix shell`, the project's
+  `flake.nix`, or `shell.nix` to provide it.
+- If that is still insufficient, stop and ask the user to prepare the environment instead of using
+  any other installation method.
+
+## 7) Communication Defaults
+
+- Respond in the language the user is currently using, prefer English & Chinese.
+- Code, commands, identifiers, and code comments: English.
+- Be concise, concrete, and action-oriented.
+
+## 8) Project Overlay
+
+Project-local policy may add stricter constraints (build/test/deploy/style/ownership/environment).
+It must not weaken this baseline.

agents/README.md

@@ -0,0 +1,66 @@
+# agents
+
+This directory is a reusable home for agent-related files that can be shared across projects.
+
+The intended use is to symlink or copy files from here into different agent config directories,
+skill folders, or other agent runtimes. Treat it as a portable source of truth for important agent
+behavior and supporting materials.
+
+It is intended to be a personal collection similar in spirit to
+[`github/awesome-copilot`](https://github.com/github/awesome-copilot), but maintained for my own
+agents, workflows, and preferences.
+
+## Use Cases
+
+- shared agent rules
+- reusable prompts
+- skill definitions
+- agent templates
+- instruction packs
+- workflow notes
+- setup helpers
+- environment preparation docs
+
+## Current Files
+
+- `AGENTS.md`: baseline rules and operating constraints for agents.
+- `install-agents.py`: installs shared agent files into supported agent config directories.
+
+## Guidelines
+
+- Keep files portable across repositories when possible.
+- Prefer plain text and small reviewable files.
+- Document assumptions that downstream agent setups need to know.
+- Keep secrets and machine-specific credentials out of this directory.
+- Prefer reusable materials that can be copied, symlinked, or adapted by multiple agents.
+
+## Distribution
+
+You can:
+
+- symlink files from this directory into an agent's config or skills folder
+- copy selected files into another agent environment
+- treat this directory as the canonical source and sync outward from it
+
+## Installation
+
+Current install targets:
+
+- Codex: `AGENTS.md` -> `~/.codex/AGENTS.md`
+- OpenCode: `AGENTS.md` -> `~/.config/opencode/AGENTS.md`
+- Claude Code: `AGENTS.md` -> `~/.claude/CLAUDE.md`
+- Gemini: `AGENTS.md` -> `~/.gemini/GEMINI.md`
+
+Run:
+
+```bash
+python3 agents/install-agents.py
+```
+
+The installer handles each target independently and skips it if the destination directory does not
+already exist.
+
+## Goal
+
+Build a personal, reusable library of agent resources that is easy to share across environments and
+easy to extend over time.

agents/install-agents.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+from pathlib import Path
+
+
+def install_one(target_dir: Path, source_file: Path, target_name: str) -> None:
+    if not target_dir.exists():
+        print(f"skipped  {target_dir} (not found)")
+        return
+
+    target_file = target_dir / target_name
+
+    if target_file.exists() or target_file.is_symlink():
+        target_file.unlink()
+
+    target_file.symlink_to(source_file)
+    print(f"linked  {target_file} -> {source_file}")
+
+
+def main() -> int:
+    script_dir = Path(__file__).resolve().parent
+    agents_file = script_dir / "AGENTS.md"
+
+    if not agents_file.is_file():
+        print(f"Missing source file: {agents_file}", file=sys.stderr)
+        return 1
+
+    codex_dir = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+    xdg_config_home = Path(os.environ.get("XDG_CONFIG_HOME", "~/.config")).expanduser()
+    opencode_dir = xdg_config_home / "opencode"
+    claude_dir = Path("~/.claude").expanduser()
+    gemini_dir = Path("~/.gemini").expanduser()
+
+    install_one(codex_dir, agents_file, "AGENTS.md")
+    install_one(opencode_dir, agents_file, "AGENTS.md")
+    install_one(claude_dir, agents_file, "CLAUDE.md")
+    install_one(gemini_dir, agents_file, "GEMINI.md")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agents/install-cli.sh

@@ -0,0 +1,18 @@
+# codex
+npm i -g @openai/codex
+
+# opencode
+npm install -g opencode-ai
+
+# kimi-cli
+uv tool install --python 3.13 kimi-cli
+uv tool upgrade kimi-cli --no-cache
+
+# gemini-cli
+npm install -g @google/gemini-cli
+
+# context7 - up-to-date docs and code examples for for LLMs & agents
+npx ctx7 setup
+
+# update all agents installed via npm
+npm update -g