mirror of
https://github.com/bitsocialnet/5chan.git
synced 2026-08-03 07:41:04 +02:00
Tommaso CasaburiandGitHub
ebf5ab64e4
* chore(ai-workflow): tighten agent workflow and worktree tooling * fix(ai-workflow): address review feedback * fix(ai-workflow): make format hook portable
68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
# Long-Running Agent Workflow
|
|
|
|
Use this playbook when a task is likely to span multiple sessions, handoffs, or spawned agents.
|
|
|
|
## Goals
|
|
|
|
- Give each fresh session a fast way to regain context
|
|
- Keep work incremental instead of one-shotting a large change
|
|
- Catch a broken local baseline before adding more code
|
|
- Leave durable artifacts that the next session can trust
|
|
|
|
## Where to Keep State
|
|
|
|
- Use `docs/agent-runs/<slug>/` when humans, review bots, or multiple toolchains need the same task state.
|
|
- Use a tool-local directory such as `.codex/runs/<slug>/` only when the task state is intentionally local to one workstation or one toolchain.
|
|
- Do not hide multi-session shared state in a private scratch file if another contributor or agent will need it later.
|
|
|
|
## Required Files
|
|
|
|
Create these files at the start of the long-running task:
|
|
|
|
- `feature-list.json`
|
|
- `progress.md`
|
|
|
|
Use the templates in `docs/agent-playbooks/templates/feature-list.template.json` and `docs/agent-playbooks/templates/progress.template.md`.
|
|
|
|
Prefer JSON for the feature list so agents can update a small number of fields without rewriting the whole document.
|
|
|
|
## Session Start Checklist
|
|
|
|
1. Run `pwd`.
|
|
2. Read `progress.md`.
|
|
3. Read `feature-list.json`.
|
|
4. Run `git log --oneline -20`.
|
|
5. Run `./scripts/agent-init.sh --smoke`.
|
|
6. Choose exactly one highest-priority item that is still `pending`, `in_progress`, or `blocked`.
|
|
|
|
If the smoke step fails, fix the broken baseline before implementing a new feature slice.
|
|
|
|
## Session Rules
|
|
|
|
- Work on one feature or task slice at a time.
|
|
- Keep the feature list machine-readable and stable. Update status, notes, files, and verification fields instead of rewriting unrelated items.
|
|
- Only mark an item verified after running the command or user flow listed in that item.
|
|
- Use spawned agents for bounded slices, not for overall task-state ownership.
|
|
- When a child agent owns one item, give it the exact item id, acceptance criteria, and files it may touch.
|
|
|
|
## Session End Checklist
|
|
|
|
1. Append a short progress entry to `progress.md`.
|
|
2. Update the touched item in `feature-list.json`.
|
|
3. Record the exact commands run for verification.
|
|
4. Capture blockers, follow-ups, and the next best item to resume.
|
|
|
|
## Recommended Progress Entry Shape
|
|
|
|
Use a short structure like:
|
|
|
|
```markdown
|
|
## 2026-03-17 14:30
|
|
|
|
- Item: F003
|
|
- Summary: Updated the browser-check flow to use the shared init/bootstrap path.
|
|
- Files: `.cursor/agents/browser-check.md`, `.codex/agents/browser-check.toml`
|
|
- Verification: `yarn build`, `yarn lint`, `yarn type-check`
|
|
- Next: Run the smoke flow and update the task-board status.
|
|
```
|