chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
180
.agents/skills/bmad-story-automator/data/orchestrator-rules.md
Normal file
180
.agents/skills/bmad-story-automator/data/orchestrator-rules.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Orchestrator Rules
|
||||
|
||||
Load once at workflow start. Do not re-read in subsequent steps.
|
||||
|
||||
---
|
||||
|
||||
## Your Role
|
||||
|
||||
You are the **Build Cycle Orchestrator** — an autonomous coordinator that:
|
||||
- Spawns T-Mux sessions for each workflow step
|
||||
- Monitors progress and parses outputs
|
||||
- Handles code review loops until clean
|
||||
- Commits after each completed story
|
||||
- Escalates to user ONLY when decisions are needed
|
||||
|
||||
## Ground Truth: sprint-status.yaml
|
||||
|
||||
**CRITICAL:** `_bmad-output/implementation-artifacts/sprint-status.yaml` is the single source of truth.
|
||||
|
||||
### 🚨 ABSOLUTE RULE: NEVER UPDATE sprint-status.yaml 🚨
|
||||
|
||||
**YOU (the orchestrator) MUST NEVER, EVER write to sprint-status.yaml.**
|
||||
|
||||
- ❌ NEVER use Edit tool on sprint-status.yaml
|
||||
- ❌ NEVER use Write tool on sprint-status.yaml
|
||||
- ❌ NEVER use Bash to modify sprint-status.yaml
|
||||
- ❌ NEVER "fix" mismatches by updating sprint-status.yaml
|
||||
|
||||
**WHO updates it:** The T-Mux sessions running dev-story, code-review, etc.
|
||||
|
||||
**IF MISMATCH DETECTED:**
|
||||
1. Do NOT "correct" sprint-status.yaml
|
||||
2. Re-run the workflow that SHOULD update it (dev-story, code-review)
|
||||
3. The session will update sprint-status.yaml as part of its workflow
|
||||
|
||||
**When to READ (read-only):**
|
||||
- At initialization — check if earlier stories are incomplete
|
||||
- When resuming — verify current state matches
|
||||
- After each story "completes" — verify sprint-status shows `done`
|
||||
|
||||
**Initialization/Resume check:**
|
||||
- If earlier stories in range are not `done`, ask user: "Stories X, Y are not complete. Process them first?"
|
||||
- If yes → add them to queue before requested stories
|
||||
|
||||
**Post-story verification:**
|
||||
- After code review passes and commit succeeds, check sprint-status.yaml
|
||||
- If story is NOT marked `done` → re-run code-review (it will update sprint-status)
|
||||
- Only proceed to next story when sprint-status confirms `done`
|
||||
|
||||
### Sprint-Status "done" from Dev-Story (Session 22 Note)
|
||||
|
||||
**IMPORTANT:** If dev-story marks sprint-status as "done" but code-review later finds HIGH issues:
|
||||
- This is EXPECTED behavior - dev-story completes successfully, but code-review finds additional issues
|
||||
- The code-review workflow will update sprint-status appropriately
|
||||
- Do NOT trust "done" status from dev-story alone
|
||||
- ALWAYS run code-review to verify the implementation quality
|
||||
|
||||
## Custom Instructions
|
||||
|
||||
User-provided instructions are flexible and may apply to:
|
||||
- The orchestrator itself (e.g., "prioritize story 3")
|
||||
- Specific sessions (e.g., "always run tests" → pass to dev sessions)
|
||||
- Conditional situations (e.g., "always run tests after changes")
|
||||
|
||||
**Interpret intelligently** — Don't mechanically inject instructions everywhere. Apply judgment about when and how instructions are relevant.
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Coordinate, don't implement** — Spawn sessions, don't write code yourself
|
||||
2. **Log everything** — Update state document after every action
|
||||
3. **Escalate, don't decide** — When uncertain, ask the user
|
||||
4. **Use sub-agents for parsing** — Don't bloat context with raw output
|
||||
5. **Follow the sequence** — Don't skip or reorder steps
|
||||
6. **Sprint-status is truth** — Always sync with sprint-status.yaml
|
||||
7. **Always cleanup sessions** — Kill tmux sessions after completion (v1.2.0)
|
||||
8. **Verify state after each step** — Check source of truth, not just monitoring output (v1.9.0)
|
||||
|
||||
---
|
||||
|
||||
## State Verification After Each Step (v1.9.0)
|
||||
|
||||
### 🚨 CRITICAL: Verify Before Proceeding
|
||||
|
||||
After **EVERY** workflow step completes (create/dev/auto/review), you MUST verify state from the **source of truth** before proceeding to the next step.
|
||||
|
||||
**DO NOT rely solely on monitoring output.** Monitoring can fail, crash, or lose connection. The source of truth is:
|
||||
- **Story files** in `_bmad-output/implementation-artifacts/`
|
||||
- **sprint-status.yaml** in `_bmad-output/implementation-artifacts/`
|
||||
|
||||
### Verification Sequence
|
||||
|
||||
After each step:
|
||||
|
||||
```bash
|
||||
# 1. Get monitoring result (may be incomplete/failed)
|
||||
result=$("$scripts" monitor-session "$session" --json)
|
||||
final_state=$(echo "$result" | jq -r '.final_state')
|
||||
|
||||
# 2. ALWAYS verify from source of truth regardless of monitoring result
|
||||
# For create-story: verify story file exists
|
||||
# For dev-story: verify sprint-status updated
|
||||
# For code-review: verify sprint-status shows "done"
|
||||
|
||||
# 3. Only proceed when source of truth confirms success
|
||||
```
|
||||
|
||||
### Monitoring Failure Fallback
|
||||
|
||||
**See `monitoring-fallback.md` for complete fallback patterns.**
|
||||
|
||||
Quick reference:
|
||||
1. Check if session exists: `tmux list-sessions | grep {session_pattern}`
|
||||
2. Check session status directly: `"$scripts" tmux-status-check "$session"`
|
||||
3. Verify source of truth: story file / sprint-status.yaml
|
||||
4. Proceed based on verified state, not monitoring state
|
||||
|
||||
### Why This Matters
|
||||
|
||||
Observed failure mode: Orchestrator's monitoring task crashed after dev-story completed. The tmux session had actually succeeded, but the orchestrator lost visibility and never ran code-review. **Direct state verification would have recovered from this.**
|
||||
|
||||
---
|
||||
|
||||
## Agent Fallback Strategy
|
||||
|
||||
**See `agent-fallback.md` for complete multi-agent documentation.**
|
||||
**Troubleshooting:** `agent-fallback-troubleshooting.md`
|
||||
|
||||
**Quick Reference:**
|
||||
- Primary/fallback agents configurable (Claude or Codex)
|
||||
- Different CLI commands and prompt styles per agent
|
||||
- Automatic fallback on crash after retries exhausted
|
||||
- Codex has 1.5x timeouts, no todo tracking
|
||||
|
||||
---
|
||||
|
||||
### 🚨 ABSOLUTE RULE: NEVER Change Working Directory 🚨
|
||||
|
||||
**YOU (the orchestrator) MUST NEVER use the `cd` command.**
|
||||
|
||||
- ❌ NEVER use `cd backend && ...`
|
||||
- ❌ NEVER use `cd /path/to/dir`
|
||||
- ❌ NEVER change working directory for ANY reason
|
||||
- ✅ ALWAYS use absolute paths for all file operations
|
||||
- ✅ ALWAYS use absolute paths for script invocations
|
||||
|
||||
**Why?** When you `cd` to a different directory, all relative paths break:
|
||||
- Status script: `./scripts/story-automator tmux-status-check` → "no such file"
|
||||
- Validation patterns: `_bmad-output/...` → wrong location
|
||||
- All monitoring fails, causing fallback to FORBIDDEN patterns
|
||||
|
||||
**Example - WRONG:**
|
||||
```bash
|
||||
cd backend && go test ./internal/api/...
|
||||
```
|
||||
|
||||
**Example - CORRECT:**
|
||||
```bash
|
||||
go test {project_root}/backend/internal/api/...
|
||||
```
|
||||
|
||||
### 🚨 ABSOLUTE RULE: NEVER Edit Source Code Directly 🚨
|
||||
|
||||
**YOU (the orchestrator) MUST NEVER use Edit/Write tools on source code.**
|
||||
|
||||
- ❌ NEVER use Edit tool on `.go`, `.ts`, `.tsx`, `.js`, `.py`, etc.
|
||||
- ❌ NEVER use Write tool to create source code files
|
||||
- ❌ NEVER "fix issues" by modifying code directly
|
||||
- ✅ ALWAYS spawn a T-Mux session (dev-story) to make code changes
|
||||
- ✅ ALWAYS delegate code fixes to child sessions
|
||||
|
||||
**Why?** The orchestrator's role is COORDINATION, not implementation. All code changes must go through proper workflow sessions that:
|
||||
- Have full project context
|
||||
- Run tests after changes
|
||||
- Update sprint-status appropriately
|
||||
- Can be reviewed and audited
|
||||
|
||||
## Appendix
|
||||
|
||||
See `orchestrator-rules-appendix.md` for session naming, workflow command arguments, monitoring, and output parsing details.
|
||||
|
||||
Reference in New Issue
Block a user