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
• deployment-status.sh - Comprehensive deployment status report for investment trading
• deploy-invttrdg.sh - Production deployment script for investment trading
• remove_user_interactive.sh
• remove_user_guided.sh
• remove_user_from_repos.sh
• scripts/
• scripts/tracker-seed/ - file work items into the ByteLyst tracker (see "Cutting Tracker Items")
• 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.

Cutting Tracker Items (work tracking)

When the user asks to "cut items to track" (file feature/bug/task tickets for some work — e.g. the findings in ENGINEERING_REVIEW_SCORECARD.md), use the seed tooling in scripts/tracker-seed/. Do not hand-roll API calls.

How the tracker works:

• Items live in the ByteLyst tracker, served by platform-service (POST /api/items, in learning_ai_common_plat/services/platform-service), and viewed in tracker-web (learning_ai_common_plat/dashboards/tracker-web, :3003).
• Item schema: { productId, type: bug|feature|task, priority: critical|high|medium|low, title, description, labels[], source, visibility, ... }. Items are scoped per productId.
• Auth is an HS256 JWT signed with the shared JWT_SECRET (verified offline by platform-service); the seed script mints one itself.

Standard procedure:

1. Add payloads to scripts/tracker-seed/engineering-review-items.json (or a new payload file): one entry per item, scoped to the right productId. Use the repoToProductId map in that file for repo → product slugs (e.g. learning_ai_notes → notelett, common-plat/infra → platform).
2. Preview with no side effects: node scripts/tracker-seed/seed-tracker-items.mjs --dry-run.
3. Create for real only when the platform stack is up (it writes real records): JWT_SECRET=<secret> PLATFORM_API_URL=http://localhost:4003 node scripts/tracker-seed/seed-tracker-items.mjs. The script dedupes by title per product, so re-running is safe (--force to bypass).
4. If the stack is not running (no Docker / nothing on :4003), do not stand up Cosmos just to seed — commit the payloads + run instructions and tell the user to run the script when the stack is next up. Confirm before any live write (creating items is a side-effecting datastore operation).

See scripts/tracker-seed/README.md for full details.

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.