bytelyst-devops-tools/AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository.

Purpose

This repo is a mixed operational workspace, not a single product codebase. Your first job is orientation:

• identify whether the task targets root Bash tooling, a subproject, or generated data
• avoid treating tracked JSON or output files as canonical source without checking context
• prefer doc and safety improvements unless the requested task clearly requires behavioral changes

Canonical Docs

Read these first:

1. README.md
2. docs/getting-started.md
3. docs/repo-map.md
4. docs/tooling-status.md
5. scripts/README.md when the task involves standalone operational scripts
6. CLAUDE.md for Claude-specific guidance

High-Signal Areas

Primary

• bytelyst-cli.sh
• remove_user_interactive.sh
• remove_user_guided.sh
• remove_user_from_repos.sh
• scripts/
• git-work-safety-tools/
• github_access_scripts/

Secondary Or Self-Contained

• Slack Message/
• youtube/
• supabase monitor/

Do not assume these subprojects share the same dependencies or conventions as the root scripts.

Sensitive And Generated Files

Handle these carefully:

• accounts.json
• account or user snapshot JSON files in the repo root
• github_repo_scanners/contributor_repos/*.json
• .env files
• generated outputs under supabase monitor/output/

These may contain secrets, usernames, or operational snapshots. Avoid printing contents unless necessary for the task.

Editing Rules

• Prefer small, targeted changes.
• Preserve operational scripts' current interface unless the task asks for a breaking change.
• When reorganizing docs, keep old filenames if external references may depend on them.
• Do not move or delete generated/tracked data files unless explicitly asked.
• If you add a new directory or script, update docs/repo-map.md.

Recommended Workflow

1. Determine whether the task is about:
   • GitHub admin Bash scripts
   • multi-repo git safety tooling
   • a Python side project
   • repo documentation or cleanup
2. Read only the files relevant to that surface.
3. Check whether there is an existing README in that subdirectory.
4. Make the smallest coherent change set.
5. If docs or discoverability changed, update the canonical docs listed above.

Good First Checks

git status --short --branch
rg --files
sed -n '1,220p' README.md
sed -n '1,220p' docs/repo-map.md

Pitfalls

• The repo contains legacy one-off scripts and tracked local artifacts.
• Directory names do not always reflect actual function. supabase monitor/ is a YouTube-processing workflow project.
• The root README should stay broad; detailed usage belongs in docs/ or a subdirectory README.