From f5481484b046d32b1ca3e02690dd336fe5ed6f8a Mon Sep 17 00:00:00 2001 From: Patrick Singletary Date: Mon, 10 Aug 2026 15:40:35 -0400 Subject: [PATCH] Add gen-agents.zsh + AGENTS.common.md template; regenerate per-repo AGENTS.md --- AGENTS.common.md | 5 ++++ AGENTS.md | 4 +++- AGENTS.ptharbor.md | 3 +++ AGENTS.zodiac.md | 42 +++++++++++++++++++++++++++++++++ bin/gen-agents.zsh | 58 ++++++++++++++++++++++++++++++++++++++++++++++ plan.md | 1 + 6 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 AGENTS.common.md create mode 100644 AGENTS.ptharbor.md create mode 100644 AGENTS.zodiac.md create mode 100755 bin/gen-agents.zsh diff --git a/AGENTS.common.md b/AGENTS.common.md new file mode 100644 index 0000000..9e07f32 --- /dev/null +++ b/AGENTS.common.md @@ -0,0 +1,5 @@ +# AGENTS.md — {{REPO}} + +Conventions: AGENTS.md is the primary agent instructions file; .hermes.md (if present) is secondary. + +For any frontend/UI design, redesign, critique, audit, polish, or visual work, load the `impeccable` skill first (skill_view name='impeccable') and follow it. diff --git a/AGENTS.md b/AGENTS.md index a5e7659..5202403 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,5 @@ -# AGENTS.md — 1 +# AGENTS.md — _shared + +Conventions: AGENTS.md is the primary agent instructions file; .hermes.md (if present) is secondary. For any frontend/UI design, redesign, critique, audit, polish, or visual work, load the `impeccable` skill first (skill_view name='impeccable') and follow it. diff --git a/AGENTS.ptharbor.md b/AGENTS.ptharbor.md new file mode 100644 index 0000000..f1bfd36 --- /dev/null +++ b/AGENTS.ptharbor.md @@ -0,0 +1,3 @@ +Migration of ptharbor.com (Weebly) to ATProto hosting. Plan: `.hermes/plans/2026-08-08_030000-ptharbor-atproto-migration.md`. + +**Before doing any work in this repo, read `.hermes/plans/README_red_team.md`.** This project has a standing red-team reviewer; its findings files (`red_team_*.md`, co-located with their targets) contain binding sequencing overrides and required resolutions. Do not execute plan tasks without checking the findings mapped to them. diff --git a/AGENTS.zodiac.md b/AGENTS.zodiac.md new file mode 100644 index 0000000..e36e4a6 --- /dev/null +++ b/AGENTS.zodiac.md @@ -0,0 +1,42 @@ +## Security & Secret-Handling Rules (all agents, all tasks) + +These rules exist because a past audit documented a leaked secret by quoting it, +and the audit report itself was then committed — re-leaking the secret in git +history on the public remote. Do not repeat this. + +1. **Secrets are never quoted.** If you discover a real credential, phone + number, birthday, or other PII, reference it by type + location only (e.g., + "admin birthday at src/...:42"). Never reproduce the value in reports, + commit messages, code comments, chat output, or test fixtures. This applies + double when documenting a leak: describe the evidence, do not copy it. A + security report must itself pass the same secret scan it demands. + +2. **Findings ledgers stay out of git.** Any security-audit output + (`red-team-output/`, audit notes, PoC payloads) is local-only and + gitignored. Record dispositions as one-line summaries in commit messages — + never by committing the ledger. Before any commit, run `git status --short` + and confirm no audit artifacts, `.env` files, `.npmrc`, or tool-state dirs + (`.claude/`, `.cursor/`, `.impeccable/`) are staged. **`git add -A` is + forbidden in this repo** — stage files by name. + +3. **No auto-executing tool state in git.** Editor/agent hook configs + (`.claude/settings.local.json`, `.cursor/hooks.json`) execute code on tool + events. Committing them turns every clone into code execution on someone + else's machine. They are gitignored; keep them that way. + +4. **History rewrites need explicit owner approval, every time.** Even when a + secret is in history, present the rewrite plan and wait. After any + force-push to the public tangled.org remote, note that unreachable objects + may persist server-side — record the exposure window in the ledger. + +5. **Deployable = `out/` only.** Never deploy `.next/`. After builds, scan the + deployable tree: `grep -rE "\+1[0-9]{10}|ADMIN_" out/` must return nothing. + +6. **OneDrive builds:** npm/git commands may fail with ETIMEDOUT on dataless + files. Stage to /tmp (excluding `node_modules`), work there, copy results + back. Never "fix" this by committing `node_modules` or disabling git + safety features. + +7. **Failed auth flows leave residue.** After any OAuth/tooling auth problem + (wispctl, etc.), check for stale state (e.g., `oauth_state` rows in + `~/.config/wispctl/state.sqlite`) and clear it once resolved. diff --git a/bin/gen-agents.zsh b/bin/gen-agents.zsh new file mode 100755 index 0000000..08806af --- /dev/null +++ b/bin/gen-agents.zsh @@ -0,0 +1,58 @@ +#!/usr/bin/env zsh +# gen-agents.zsh — regenerate per-repo AGENTS.md from the shared template. +# +# ~/dev/_shared/bin/gen-agents.zsh # all repos under ~/dev +# ~/dev/_shared/bin/gen-agents.zsh stats zodiac # specific repos only +# +# Sources of truth (all in ~/dev/_shared/): +# AGENTS.common.md shared template; {{REPO}} is replaced by the repo dir name +# AGENTS..md optional per-repo extra block, appended verbatim after the common block +# +# Writes a repo's AGENTS.md only when content differs. Prints wrote/unchanged/skipped. + +set -euo pipefail + +DEV_ROOT="${DEV_ROOT:-$HOME/dev}" +SHARED="$DEV_ROOT/_shared" +COMMON="$SHARED/AGENTS.common.md" +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +if [[ ! -r "$COMMON" ]]; then + print -u2 "gen-agents: missing $COMMON" + exit 1 +fi + +repos=("$@") +if (( ${#repos[@]} == 0 )); then + for d in "$DEV_ROOT"/*(N); do + [[ -d "$d" ]] && repos+=("${d:t}") + done +fi + +wrote=0; unchanged=0; skipped=0 +for name in "$repos[@]"; do + dir="$DEV_ROOT/$name" + if [[ ! -d "$dir" ]]; then + print -u2 "gen-agents: skip $name (no dir $dir)" + (( ++skipped )) + continue + fi + out="$TMP/$name" + sed "s/{{REPO}}/$name/g" "$COMMON" > "$out" + extra="$SHARED/AGENTS.$name.md" + if [[ -f "$extra" ]]; then + printf '\n' >> "$out" + cat "$extra" >> "$out" + fi + target="$dir/AGENTS.md" + if [[ -f "$target" ]] && cmp -s "$out" "$target"; then + (( ++unchanged )) + else + cp "$out" "$target" + print "wrote $name/AGENTS.md" + (( ++wrote )) + fi +done + +print "gen-agents: $wrote written, $unchanged unchanged, $skipped skipped" diff --git a/plan.md b/plan.md index 91d8210..c909c83 100644 --- a/plan.md +++ b/plan.md @@ -27,6 +27,7 @@ git -C ATProtocol-Playground remote add github https://github.com/PSingletary/AT ## 3. AGENTS.md generation ~/dev/_shared/bin/gen-agents.zsh # regenerates AGENTS.md per repo from _shared/AGENTS.common.md + # (+ optional _shared/AGENTS..md extra blocks) ## 4. Rules - Working trees live in ~/dev only. NEVER inside OneDrive/CloudStorage paths. -- 2.51.2