docs: clarify agent completion workflow
Tighten the completion checklist so future agents can follow a deterministic start procedure, implementation/doc-tick commit loop, and safe parallelization model. Include one-line prompts for up to three parallel streams with explicit ownership, gates, push, and audit-update requirements. Co-Authored-By: GPT-5 Codex <noreply@openai.com>
This commit is contained in:
parent
381c908ef3
commit
9362f2b843
@ -28,6 +28,133 @@ means, and which gates must pass before pushing.
|
||||
or auth behavior, pause and confirm unless the audit item explicitly requires
|
||||
that contract change.
|
||||
|
||||
## Fresh-Agent Start Procedure
|
||||
|
||||
Every agent should do this before writing code:
|
||||
|
||||
1. Read `docs/CODEX_RESUME_PROMPT.md` in full.
|
||||
2. Read `docs/AUDIT_REDESIGN.md` and this checklist.
|
||||
3. If touching platform, also read
|
||||
`/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/HANDOVER.md`
|
||||
and
|
||||
`/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/AUDIT_PLATFORM.md`.
|
||||
4. Run `source ~/.zshrc && export GITEA_NPM_TOKEN && git status --short`.
|
||||
5. Confirm the target audit row is still open and no other agent has claimed or
|
||||
pushed it.
|
||||
6. Run the relevant baseline gates before making code changes when the work is
|
||||
not docs-only.
|
||||
7. Implement only the assigned item or bucket.
|
||||
8. Run the full relevant gates again.
|
||||
9. Commit the implementation first.
|
||||
10. Update the audit row status and fix commit with the short implementation
|
||||
hash, then commit the doc tick separately.
|
||||
11. Push both commits.
|
||||
12. Report the item id, implementation commit hash, doc tick commit hash, and
|
||||
gate output in three sentences or fewer.
|
||||
|
||||
## Exact Commit and Audit Update Loop
|
||||
|
||||
Use this loop for every trading audit item:
|
||||
|
||||
```bash
|
||||
source ~/.zshrc
|
||||
export GITEA_NPM_TOKEN
|
||||
git status --short
|
||||
|
||||
# Baseline gates before substantial code changes
|
||||
npm --prefix web run typecheck
|
||||
npm --prefix web run build
|
||||
npm --prefix web test
|
||||
npx tsc --noEmit -p backend/tsconfig.json
|
||||
|
||||
# Edit files, then repeat gates
|
||||
npm --prefix web run typecheck
|
||||
npm --prefix web run build
|
||||
npm --prefix web test
|
||||
npx tsc --noEmit -p backend/tsconfig.json
|
||||
|
||||
git add <implementation-files>
|
||||
git commit -m "fix(B2,B3): short description" \
|
||||
-m "Present-tense why paragraph." \
|
||||
-m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \
|
||||
-m "Co-Authored-By: GPT-5 Codex <noreply@openai.com>"
|
||||
|
||||
IMPLEMENTATION_HASH="$(git rev-parse --short HEAD)"
|
||||
# Edit docs/AUDIT_REDESIGN.md: ⬜ -> ✅ and Fix commit -> $IMPLEMENTATION_HASH
|
||||
git add docs/AUDIT_REDESIGN.md
|
||||
git commit -m "docs(B2,B3): tick ticker header audit rows" \
|
||||
-m "Record the implementation commit in the redesign audit table." \
|
||||
-m "Refs: docs/AUDIT_REDESIGN.md items B2 and B3." \
|
||||
-m "Co-Authored-By: GPT-5 Codex <noreply@openai.com>"
|
||||
|
||||
# Final gates after both commits
|
||||
npm --prefix web run typecheck
|
||||
npm --prefix web run build
|
||||
npm --prefix web test
|
||||
npx tsc --noEmit -p backend/tsconfig.json
|
||||
|
||||
git push
|
||||
```
|
||||
|
||||
Do not amend the implementation commit to include the audit-row hash after the
|
||||
hash is written into the table. That creates a self-referential hash loop. The
|
||||
preferred pattern is one implementation commit plus one small docs tick commit.
|
||||
|
||||
For docs-only work, use the same commit style but run at least
|
||||
`git diff --check` and the trading gates unless the human explicitly waives
|
||||
them.
|
||||
|
||||
## Parallelization Rules
|
||||
|
||||
Maximum parallel streams: 3 agents.
|
||||
|
||||
- Parallel streams must own disjoint files or clearly disjoint repos.
|
||||
- Only one agent may edit `docs/AUDIT_REDESIGN.md` at a time. If multiple
|
||||
agents finish together, each should pull/rebase first, then update only its
|
||||
own rows.
|
||||
- Do not parallelize two items that both touch `web/src/views/HomeView.tsx`,
|
||||
shared strategy-builder files, or backend route helpers unless one agent is
|
||||
explicitly acting as integrator.
|
||||
- Prefer one frontend feature stream, one backend/security/test stream, and one
|
||||
platform-lint stream.
|
||||
- Each agent must push incremental commits for its owned item before taking the
|
||||
next item.
|
||||
- If a gate fails in code outside the agent's touched files, stop and report
|
||||
instead of masking the failure.
|
||||
- If merge conflicts appear in audit docs only, resolve by preserving all
|
||||
completed rows and commit hashes.
|
||||
|
||||
Recommended three-way split for the current backlog:
|
||||
|
||||
| Stream | Owns | Avoids |
|
||||
| --- | --- | --- |
|
||||
| Agent 1 - Web feature | `B2+B3`, then `B4+B5`, then `B6-B10` | Backend route/cache files and platform repo |
|
||||
| Agent 2 - Backend/security/tests | `C2`, `F6`, `C1`, then `C3-C7` | `TickerHeader`, layout polish, platform repo |
|
||||
| Agent 3 - Platform/infra/docs | Platform `P-sweep`, then `E1/E3/E4` if platform is blocked | nomgap WIP files and active trading feature files |
|
||||
|
||||
If only two agents are available, run Agent 1 and Agent 2. If only one agent is
|
||||
available, follow the recommended next commits top-down.
|
||||
|
||||
## One-Line Parallel Agent Prompts
|
||||
|
||||
Agent 1:
|
||||
|
||||
```text
|
||||
In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement B2+B3 only: wire TickerHeader Watchlist/alert actions and company name from fetchResearchProfile; run all trading gates, commit implementation, tick only B2/B3 rows with the implementation hash in a docs commit, push, and report hashes plus gate output.
|
||||
```
|
||||
|
||||
Agent 2:
|
||||
|
||||
```text
|
||||
In /Users/saravana/BytelystAI/trading/learning_ai_invt_trdg, read docs/CODEX_RESUME_PROMPT.md, docs/AUDIT_REDESIGN.md, and docs/COMPLETION_CHECKLIST.md, then implement C2 only: add a 30-minute in-memory FMP cache keyed by full upstream URL with tests where practical; run all trading gates, commit implementation, tick only C2 with the implementation hash in a docs commit, push, and report hashes plus gate output.
|
||||
```
|
||||
|
||||
Agent 3:
|
||||
|
||||
```text
|
||||
In /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat, read docs/HANDOVER.md and docs/AUDIT_PLATFORM.md plus the trading docs/COMPLETION_CHECKLIST.md, then do one package-scoped P-sweep lint fix only without touching nomgap WIP or platform pnpm-lock.yaml; run platform typecheck/test/lint, commit that package only, update AUDIT_PLATFORM.md if applicable, push, and report hashes plus before/after lint error count.
|
||||
```
|
||||
|
||||
## Current Snapshot
|
||||
|
||||
Completed in trading:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user