6d28e1307e
Add a "Cutting Tracker Items" section to AGENTS.md and register scripts/tracker-seed/ in docs/repo-map.md so future "cut items to track" requests route to the seed tooling instead of ad-hoc API calls. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
124 lines
4.8 KiB
Markdown
124 lines
4.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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.
|