हर्डर मल्टीएजेंट: समानांतर कोडिंग एजेंट वर्कफ़्लो

--- name: herdr-multiagent description: Run several coding agents in parallel under Herdr: stage decomposition, one git worktree, isolated env, pane and file brief per agent, state monitoring, review, merge. Child kind is read from `herdr pane current` (.result.pane.agent) and matches the orchestrator (omp, opencode, claude, codex, kimi, ...). Requires HERDR_ENV=1. --- # Herdr के माध्यम से मल्टी-एजेंट कार्य प्लेबुक: प्रोजेक्ट के कार्यों को स्वतंत्र चरणों में विभाजित करें, प्रत्येक चरण पर एक अलग एजेंट को उसके अपने git worktree और herdr-pane में बैठाएं, फ़ाइल ब्रीफ दें, निगरानी करें और परिणाम स्वीकार करें। स्किल एजेंट-स्वतंत्र है: child का kind = orchestrator का kind। opencode से स्किल चलाया - child opencode होंगे; omp से - omp; claude से - claude। orchestrator के kind को कभी भी स्मृति से न डालें और न ही कोई 'लोकप्रिय' kind चुनें। ## 0. पूर्व-शर्तें ```bash test "${HERDR_ENV:-}" = 1 # इसके बिना - रुकें, हम Herdr के अंदर नहीं हैं ``` यदि जाँच विफल होती है - उपयोगकर्ता को बताएं कि सत्र Herdr के अधीन नहीं है, और रुक जाएं। बाहर से किसी और के Herdr को नियंत्रित न करें। पैन/एजेंट के बुनियादी कमांड - मानक Herdr स्किल में (`herdr --skill`)। स्थापित बाइनरी सिंटैक्स के लिए प्राधिकारी है; संदेह होने पर `herdr agent`, `herdr pane`, `herdr integration` पढ़ें, अनुमान न लगाएं। ## 1. अपना kind निर्धारित करें - किसी भी कार्रवाई से पहले ```bash herdr pane current --current ``` फ़ील्ड `.result.pane.agent` - यही orchestrator का kind है, और यही child के लिए `--kind` का मान है: ```bash KIND=$(herdr pane current --current | jq -r '.result.pane.agent') # बिना jq: KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1) echo "$KIND" ``` खाली या `unknown` - उपयोगकर्ता से पूछें कि child को किस kind से चलाना है। आगे पाठ में `$KIND` - यह प्राप्त मान है, शाब्दिक नहीं। Herdr ↔ इस kind की एकीकरण जाँच करें (यह `agent list/wait/prompt` देता है): ```bash herdr integration status | grep -i "$KIND" ``` - `current` - ठीक है। - `not installed` - `herdr integration install "$KIND"`। एकीकरण केवल **नए** सत्रों में लागू होता है, इसलिए इसे child चलाने से पहले स्थापित करें; orchestrator स्वयं `agent list` के लिए अदृश्य रहेगा - यह सामान्य है, उसकी निगरानी करने की आवश्यकता नहीं है। - kind `herdr integration install` की सूची में नहीं है (जैसे `amp`, `cline`, `kiro`, `maki`) - संरचनात्मक निगरानी नहीं होगी, हम §7 के fallback (`pane read` + git) पर काम करते हैं। यह ब्लॉकर नहीं है। रिकॉर्ड करें और उपयोगकर्ता को घोषित करें: 'child का kind = $KIND'। ## 2. विघटन - मुख्य चरण, जल्दबाजी न करें - प्रोजेक्ट की योजना/स्पेक और वर्तमान स्थिति पढ़ें (`git log`, टेस्ट, `git worktree list`)। - शेष कार्य को **गैर-अतिव्यापी फ़ाइल क्षेत्रों** वाले चरणों में विभाजित करें। एक ही पैकेज पर दो एजेंट - केवल सोच-समझकर और स्पष्ट क्रम के साथ (बाद में, समानांतर नहीं)। - सामान्य फ़ाइलों (config, lock) में योगात्मक संपादन स्वीकार्य हैं - ब्रीफ में लिखें 'केवल योगात्मक, बिना सिग्नेचर बदले'; मर्ज-संघर्ष orchestrator सुलझाएगा। - 'चरण → फ़ाइलें जिन्हें छुआ जा सकता है / नहीं छुआ जा सकता' का मैट्रिक्स तय करें। चलाने से पहले: main में सब कुछ तैयार कमिट हो, पेड़ साफ हो। ## 3. Worktree + प्रति एजेंट पृथक वातावरण ```bash git worktree add ../<proj>-s<N> -b stage-<N>-<name> ``` Python प्रोजेक्ट्स का जाल: साझा venv दूसरे का कोड इम्पोर्ट करता है (मुख्य रिपो का editable install)। प्रत्येक worktree के लिए अपना venv: ```bash cd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` कई venv को एक पृष्ठभूमि कमांड में क्रमिक रूप से स्थापित करें (pip cache साझा है)। JS स्टैक: प्रत्येक worktree में अपने `node_modules` (`npm ci`)। यदि orchestrator के पास कमांड रैपर हुक है (rtk और इसी तरह): इंटरप्रेटर का सापेक्ष पथ (`../.venv/Scripts/python.exe`) ऐसे हुक के माध्यम से ब्रीफ में रिज़ॉल्व नहीं होता ('command not found')। ब्रीफ और प्रॉम्प्ट में - केवल संबंधित worktree के python/npm के **निरपेक्ष पथ**। ## 4. ब्रीफ - फ़ाइलों में, कमांड लाइन में नहीं `<repo>/.briefs/stage-<N>.md` (untracked)। ब्रीफ की संरचना: - **संदर्भ**: पहले क्या पढ़ें (स्पेक, कॉन्ट्रैक्ट, प्रमुख फ़ाइलें), क्या पहले से किया जा चुका है; - **कार्य**: स्पेक के बिंदुओं के संदर्भ के साथ विशिष्ट आवश्यकताएं; - **सीमाएं**: फ़ाइलें हाँ/नहीं, 'worktree से बाहर मत जाओ', 'push नहीं करना'; - **स्वीकृति**: टेस्ट/लिंटर के सटीक कमांड (worktree के इंटरप्रेटर के निरपेक्ष पथ के साथ), 'पुराने टेस्ट हरे रहें', अपनी शाखा में कमिट, अंतिम रिपोर्ट। ब्रीफ को एजेंट के किसी विशिष्ट kind का अनुमान नहीं लगाना चाहिए: उसमें 'omp/skill/... चलाएं' न लिखें - लक्ष्य, सीमाएं और स्वीकृति कमांड लिखें। Child खुद तय करेगा कि अपने किन टूल्स से यह करना है। एजेंट को प्रॉम्प्ट छोटा: 'फ़ाइल <ब्रीफ> पढ़ें और अंत तक पूरा करें'। ## 5. पैन: बनाएं, तुरंत नाम दें अनुशंसित लेआउट - main-left: orchestrator का पैन बाईं ओर पूरी ऊंचाई पर, सभी child दाईं ओर एक कॉलम में एक के नीचे एक। यदि उपयोगकर्ता के पास main-left के लिए डिज़ाइन किए गए लेआउट प्लगइन हैं, तो कोई अन्य योजना उसका दृश्य तोड़ देगी। यदि उपयोगकर्ता स्पष्ट रूप से दूसरा लेआउट मांगता है - उसका पालन करें। पहला child - `split --current --direction right`, बाकी - `split --pane <पिछला child> --direction down` दाएं कॉलम के **अंदर**। orchestrator के पैन को स्प्लिट न करें और एजेंट पैन को दाईं ओर स्प्लिट न करें - केवल दाएं कॉलम में down-श्रृंखला। ```bash herdr pane split --current --direction right --cwd "<worktree1>" --no-focus herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus ``` नए पैन का ID - JSON `.result.pane.pane_id` से। उपयोगकर्ता का फोकस न छुएं (`--no-focus`)। child का नाम चरण 6 में `agent start` के माध्यम से दिया जाता है, साथ ही स्पष्टता के लिए `herdr pane rename <pane_id> "s<N>-<name>"`। ## 6. अपने kind का child चलाना मानक मार्ग - `agent start`, यह सत्यापित भी करता है कि पैन में अपेक्षित एजेंट उठा है: ```bash herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <स्वायत्तता-फ्लैग> ``` नाम `[a-z][a-z0-9_-]{0,31}` से मेल खाना चाहिए और जीवित एजेंटों में अद्वितीय होना चाहिए। ### स्वायत्तता फ्लैग Child बिना इंसान के काम करता है, अन्यथा वह अनुमोदन पर रुक जाएगा। फ्लैग Herdr पर नहीं, CLI पर निर्भर करता है। पुष्टि किए गए: | kind | चालू करना | |---|---| | `omp` | `-- --yolo` | | `claude` | `-- --dangerously-skip-permissions` (या `--permission-mode bypassPermissions`) | | `opencode` | `-- --auto` | किसी भी अन्य kind (codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes, qodercli, mastracode, pi, ...) के लिए - फ्लैग का आविष्कार न करें। canonical निष्पादन योग्य फ़ाइल निर्धारित करें और उसकी सहायता पढ़ें: ```bash herdr agent start --help # --kind के विवरण में canonical executable है <executable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow" ``` फ्लैग नहीं मिला → जांचें कि CLI कॉन्फ़िग में स्वायत्तता मोड है या नहीं (जैसे `~/.omp/agent/config.yml: tools.approvalMode: yolo`, `~/.claude/settings.json: permissions`, `opencode.json: permission`), और उपयोगकर्ता को चेतावनी दें कि child अनुमोदन पर रुक सकता है - उन्हें `blocked` स्थिति के रूप में देखा जा सकता है (§7)। ### यदि `agent start` टाइमआउट पर विफल हो जाता है Windows पर PowerShell-पैन में ज्ञात बग: `agent start` विकृत `Start-Process` भेजता है → टाइमआउट। समाधान - CLI को सीधे पैन में उठाएं: ```bash herdr pane run <pane_id> "<executable> <स्वायत्तता-फ्लैग>" sleep 3 && herdr pane read <pane_id> --lines 15 # CLI प्रॉम्प्ट की उम्मीद herdr agent rename <pane_id> s1-<name> # यदि herdr ने एजेंट को पहचाना ``` यदि इसके बाद `herdr agent explain <pane_id>` पहचाना गया एजेंट नहीं देता - इस पैन के लिए संरचनात्मक निगरानी अनुपलब्ध है, हम §7 के fallback पर काम करते हैं। ### ब्रीफ देना `pane run` के माध्यम से नहीं: Enter निगल जाता है जबकि TUI इन्सर्ट रेंडर करता है। दो चरणों में विराम के साथ: ```bash herdr pane send-text <pane_id> "फ़ाइल <ब्रीफ का निरपेक्ष पथ> पढ़ें - यह आपका ब्रीफ है। अंत तक पूरी तरह निष्पादित करें (कोड, टेस्ट, लिंटर, अपनी शाखा में कमिट), फिर अंतिम रिपोर्ट दें।" sleep 5 && herdr pane send-keys <pane_id> Enter ``` मानक विकल्प, जब एकीकरण स्थापित है और `agent start` काम कर गया: ```bash herdr agent prompt s1-<name> "फ़ाइल <ब्रीफ> पढ़ें और अंत तक पूरा करें" --wait --timeout 300000 ``` `pane read` से जांचें कि ब्रीफ चला गया है: input खाली है, एजेंट काम कर रहा है। ## 7. निगरानी - एकीकरण के माध्यम से, cron नहीं ```bash herdr agent list # सभी child की स्थितियां herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<पाठ>" # काम कर रहे एजेंट को अतिरिक्त निर्देश दें herdr agent read s1-<name> --lines 40 ``` स्थितियों का अर्थ: `idle` - इनपुट के लिए तैयार और उसका टैब UI में देखा गया; `done` - अदृश्य पृष्ठभूमि कार्य के बाद वही idle (CLI के माध्यम से पढ़ना टैब को देखा हुआ चिह्नित नहीं करता); `blocked` - herdr ने अनुमोदन/प्रश्न UI पहचाना, child इंसान की प्रतीक्षा कर रहा है; `unknown` - एजेंट मौजूद है, लेकिन वर्गीकरण नहीं है, यह समाप्ति का संकेत नहीं है। Orchestrator का चक्र: `agent wait` क्रम से या घटना पर → स्वीकृति (§8)। `blocked` → `agent read`, प्रश्न समझें, `agent prompt` से उत्तर दें या उपयोगकर्ता से पूछें। संदिग्ध शांति → `pane read <pane_id>`। `wait` का टाइमआउट मध्यम रखें (~30 मिनट) और ट्रिगर होने पर फिर से सेट करें: बहुत बड़े मान 'timed out' में चले जाते हैं। Fallback, जब `$KIND` के लिए एकीकरण अनुपलब्ध है या `agent explain` ने child को नहीं पहचाना: आवधिक `herdr pane read <pane_id> --lines 60` + worktree में `git log/status`। Cron - केवल अंतिम उपाय और समाप्ति पर अनिवार्य रूप से हटाएं। Child सत्र का टूटना: worktree में कार्य सुरक्षित रहता है। पुनः आरंभ - उसी CLI के साथ उसके जारी रखने वाले फ्लैग के साथ (`--help` में जांचें): `omp --resume`, `claude --continue`, `opencode --continue`। फिर प्रॉम्प्ट: 'सत्र बाधित हुआ। git status जांचें, ब्रीफ <फ़ाइल> को अंत तक पूरा करें'। ## 8. स्वीकृति और मर्ज - प्रत्येक शाखा: उसके worktree में टेस्ट + लिंटर, `git diff main...<branch> --stat` की समीक्षा। - child की अंतिम रिपोर्ट को विश्वास पर न लें - स्वीकृति कमांड स्वयं जांचें। - main में मर्ज - केवल उपयोगकर्ता की पुष्टि के साथ; योगात्मक अतिव्यापन को मैन्युअल रूप से सुलझाएं। - मर्ज के बाद: `git worktree remove`; शाखाएं - उपयोगकर्ता के साथ सहमति से। - child के पैन मुक्त करें, उपयोगकर्ता के पैन को न छुएं।