mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 07:52:24 +00:00
Add multi-agent coordination guide to AGENTS.md and CLAUDE.md
- AGENTS.md Section 12: subsystem boundary table, PR discipline rules, in-flight work reservation section, and signaling conventions for parallel AI agent workflows (Claude Code, Codex, Jules) - CLAUDE.md: document the unstable→beta→main promotion pipeline, add multi-agent workflow section with coordination rules for both agents and human maintainers, fix Node.js version reference (20→22) https://claude.ai/code/session_01LzErpH9FNw4hAPsjoYb1v9
This commit is contained in:
2 files changed
+95
-4
No files matched your search
@@ -199,6 +199,56 @@ When moving a feature to a controller, follow these steps:
|
||||
|
||||
---
|
||||
|
||||
## 12. Multi-Agent Coordination
|
||||
|
||||
This project uses multiple AI agents (Claude Code, OpenAI Codex, Google Jules) working in parallel. Without coordination, agents will create conflicting PRs, duplicate work, and cause painful merge conflicts. Follow these rules to keep things clean.
|
||||
|
||||
### Before Starting Work
|
||||
|
||||
1. **Check open PRs.** Run `gh pr list --state open` or check GitHub. If another agent already has a PR touching the same files or subsystem, do not create a competing PR. Instead, note the conflict and ask the maintainer how to proceed.
|
||||
2. **Check this section for in-flight work.** The maintainer may list active work areas below. Respect these reservations.
|
||||
3. **Read KNOWN_ISSUES.md.** Do not open PRs to fix issues already documented there unless explicitly asked.
|
||||
|
||||
### Subsystem Boundaries
|
||||
|
||||
To minimize merge conflicts, treat these as independent work zones. An agent should avoid touching files outside its assigned zone in a single PR:
|
||||
|
||||
| Zone | Key Files | Description |
|
||||
|------|-----------|-------------|
|
||||
| **Nostr Core** | `js/nostr/client.js`, `js/nostr/adapters/`, `js/nostrClientFacade.js` | Protocol client, signers, relay management |
|
||||
| **Event Schemas** | `js/nostrEventSchemas.js`, `docs/nostr-event-schemas.md` | Event definitions and documentation |
|
||||
| **Playback** | `js/services/playbackService.js`, `js/playbackUtils.js`, `js/magnetUtils.js` | Video streaming, magnet handling |
|
||||
| **UI Controllers** | `js/ui/` | Modal controllers, notification, components |
|
||||
| **State** | `js/state/` | Profile cache, application state |
|
||||
| **DMs** | `js/ui/dm/`, `js/nostr/dm/` | Direct messaging subsystem |
|
||||
| **Moderation** | `js/moderation/`, `docs/moderation/` | Content moderation, reports, admin lists |
|
||||
| **Build & CI** | `.github/workflows/`, `scripts/`, `tailwind.config.cjs` | CI pipeline, lint scripts, build tooling |
|
||||
| **Styling** | `css/tokens.css`, `css/tailwind.source.css` | Design tokens and Tailwind source |
|
||||
| **App Orchestrator** | `js/app.js`, `js/app/` | Main app wiring (high conflict risk — only one PR at a time) |
|
||||
|
||||
**`js/app.js` is the highest-risk file.** It wires everything together. Never have two agent PRs modifying it simultaneously.
|
||||
|
||||
### PR Discipline
|
||||
|
||||
- **One subsystem per PR.** A PR that touches Nostr Core and UI Controllers is two PRs. Split them.
|
||||
- **Small and mergeable.** Target PRs that can be reviewed in one sitting. If a refactor spans 10+ files, break it into sequential PRs.
|
||||
- **Merge before branching.** Before starting new work on a subsystem, ensure all open PRs for that subsystem are merged or closed.
|
||||
- **Rebase, don't stack.** Long-lived branches diverge fast with multiple agents. Rebase onto `unstable` frequently.
|
||||
|
||||
### Signaling Work to Other Agents
|
||||
|
||||
When you create a PR or start work, leave a clear signal:
|
||||
- **PR title prefix**: Use a descriptive prefix like `[nostr-core]`, `[playback]`, `[ui]`, `[ci]` so the scope is visible at a glance.
|
||||
- **PR description**: Include a "Files Modified" section listing the key files touched, so other agents can quickly detect conflicts.
|
||||
|
||||
### Currently In-Flight Work
|
||||
|
||||
<!-- Maintainer: update this list when assigning work to agents. Agents: check this before starting. -->
|
||||
|
||||
_No reservations currently active._
|
||||
|
||||
---
|
||||
|
||||
## Next
|
||||
|
||||
Please read these documents next.
|
||||
|
||||
@@ -13,7 +13,7 @@ This document provides context and guidance for AI assistants working with the b
|
||||
- **WebTorrent**: P2P video streaming fallback
|
||||
- **Tailwind CSS**: Utility-first styling with custom design tokens
|
||||
- **Playwright**: E2E and visual regression testing
|
||||
- **Node.js 20+**: Development environment
|
||||
- **Node.js 22+**: Development environment
|
||||
|
||||
### License
|
||||
GPL-3.0-or-later (see `LICENSE`)
|
||||
@@ -383,10 +383,25 @@ rm css/tailwind.generated.css && npm run build:css
|
||||
|
||||
---
|
||||
|
||||
## Release Channels
|
||||
## Release Channels & Promotion Pipeline
|
||||
|
||||
- **Main**: Production track — preserve UX, atomic commits, feature flags default off
|
||||
- **Unstable**: Experimentation — gate risky features behind flags
|
||||
Code flows through three branches with increasing stability:
|
||||
|
||||
```
|
||||
unstable → beta → main
|
||||
(dev) (soak) (prod)
|
||||
```
|
||||
|
||||
| Branch | Purpose | CI Required | Manual QA |
|
||||
|--------|---------|-------------|-----------|
|
||||
| `unstable` | Active development, AI agent PRs land here | Yes | No |
|
||||
| `beta` | Stabilization soak (hosted for testing) | Yes | Yes — hosted domain |
|
||||
| `main` | Production | Yes | Verified via beta |
|
||||
|
||||
**Promotion rules:**
|
||||
- `unstable → beta`: After a batch of improvements passes CI and local testing
|
||||
- `beta → main`: After weeks of soak time on the beta hosted domain with no regressions
|
||||
- Never push directly to `main` or `beta` — always promote from the previous stage
|
||||
|
||||
### Emergency Response
|
||||
|
||||
@@ -397,6 +412,32 @@ If a change breaks playback or magnet handling:
|
||||
|
||||
---
|
||||
|
||||
## Multi-Agent Development Workflow
|
||||
|
||||
This project uses multiple AI coding agents working in parallel:
|
||||
- **Claude Code** — Refactoring, convention enforcement, codebase-wide changes
|
||||
- **OpenAI Codex** — Isolated feature implementation with clear specs
|
||||
- **Google Jules** — Issue triage and straightforward bug fixes
|
||||
|
||||
### Coordination Rules
|
||||
|
||||
All agents **must** follow the subsystem boundaries and PR discipline rules in `AGENTS.md` Section 12. The key principles:
|
||||
|
||||
1. **Check before you start.** Look at open PRs (`gh pr list`) before beginning work. If another agent has an open PR touching the same files, stop and flag the conflict.
|
||||
2. **One subsystem per PR.** Don't mix unrelated changes. A lint fix and a feature addition are two separate PRs.
|
||||
3. **`js/app.js` is single-writer.** Only one PR at a time should modify the main orchestrator.
|
||||
4. **Merge fast, branch short.** Long-lived branches cause exponential merge pain with multiple agents. Keep PRs small and mergeable in one sitting.
|
||||
|
||||
### For Human Maintainers
|
||||
|
||||
When assigning work to agents:
|
||||
- Update the "Currently In-Flight Work" section in `AGENTS.md` to reserve subsystems
|
||||
- Avoid sending two agents at the same subsystem simultaneously
|
||||
- Review and merge agent PRs promptly to keep the queue short — stale PRs compound conflicts
|
||||
- Use PR title prefixes (`[nostr-core]`, `[ui]`, `[playback]`, etc.) to make scope visible
|
||||
|
||||
---
|
||||
|
||||
## Key Documentation
|
||||
|
||||
| Document | What It Covers |
|
||||
|
||||
Reference in new issue
Block a user