bytelyst/bytelyst-devops-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agents): document "cut tracker items" workflow

Browse Source 
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>
This commit is contained in:
saravanakumardb1 2026-05-30 21:21:33 -07:00
parent 237481247e
commit 6d28e1307e
2 changed files with 44 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
AGENTS.md
View File

@ -32,6 +32,7 @@ Read these first:
- `remove_user_guided.sh` - `remove_user_guided.sh`
- `remove_user_from_repos.sh` - `remove_user_from_repos.sh`
- `scripts/` - `scripts/`
- `scripts/tracker-seed/` - file work items into the ByteLyst tracker (see "Cutting Tracker Items")
- `git-work-safety-tools/` - `git-work-safety-tools/`
- `github_access_scripts/` - `github_access_scripts/`
@ -75,6 +76,37 @@ These may contain secrets, usernames, or operational snapshots. Avoid printing c
4. Make the smallest coherent change set. 4. Make the smallest coherent change set.
5. If docs or discoverability changed, update the canonical docs listed above. 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 ## Good First Checks
```bash ```bash

12
docs/repo-map.md
View File

@ -98,6 +98,18 @@ Key files:
- `ubuntu-vm-security-update.sh` - `ubuntu-vm-security-update.sh`
- `README.md` - `README.md`
#### `scripts/tracker-seed/`
Seeds work items into the ByteLyst tracker (platform-service `POST /api/items`,
viewed in tracker-web). Use when asked to "cut items to track" — see the
"Cutting Tracker Items" section in `AGENTS.md`.
Key files:
- `seed-tracker-items.mjs` - dependency-free seeder (mints HS256 token, dedupes by title, `--dry-run`)
- `engineering-review-items.json` - item payloads + repo→productId map
- `README.md`
### `aliases/` ### `aliases/`
Reusable Bash/Zsh alias bundle for common git, tmux, shell, directory, and listing shortcuts. Reusable Bash/Zsh alias bundle for common git, tmux, shell, directory, and listing shortcuts.