@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.3

package/src/.claude/commands/master-orchestrator.md

@@ -0,0 +1,15 @@
+---
+name: 'orchestration-master'
+description: 'Conductor — Agile Workflow Orchestrator for your project. Triages task complexity, routes BMAD workflow tracks, gates milestones with review gates, manages branch lifecycle.'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_devo-bmad-custom/core/agents/master-orchestrator.md
+2. READ its entire contents — this contains the complete agent persona, critical_actions, menu, and prompts
+3. EXECUTE every critical_action in order (load all sidecar files)
+4. DISPLAY the welcome greeting as Conductor 🎯
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>

package/src/_memory/config.yaml

@@ -1,11 +1,11 @@
-# _MEMORY Module Configuration
-# Generated by BMAD installer
-# Version: 6.0.4
-# Date: 2026-03-09T16:29:06.037Z
-
-
-# Core Configuration Values
-user_name: Unnamed Developer
-communication_language: English
-document_output_language: English
-output_folder: "{project-root}/_bmad-output"
+# _MEMORY Module Configuration
+# Generated by BMAD installer
+# Version: 6.0.4
+# Date: 2026-03-09T16:29:06.037Z
+
+
+# Core Configuration Values
+user_name: Unnamed Developer
+communication_language: English
+document_output_language: English
+output_folder: "{project-root}/_bmad-output"

package/src/_memory/master-orchestrator-sidecar/instructions.md

@@ -171,8 +171,8 @@ Create this file at session start. Format:
 
 Track: {nano | small | compact | medium | extended | large}
 
-| Step | Agent | Claude Session ID | Status | Spawned At |
-|------|-------|-------------------|--------|------------|
+| Step | Agent | Pane ID | Session Name | Window ID | Pane Name | Name Source | Claude Session ID | Status | Spawned At |
+|------|-------|---------|--------------|-----------|-----------|-------------|-------------------|--------|------------|
 | {step-name} | {agent-name} | — | pending | — |
 | ... | ... | — | pending | — |
 ```
@@ -526,6 +526,20 @@ pre-output: Before generating any plan, spec, or document artifact, invoke: writ
 
 If an agent skips `writing-skills` and produces an artifact directly, the output is invalid — re-run the step with `writing-skills` loaded.
 
+### Sprint Size → Dev Agent Deployment Type
+
+At DS (dev-story) handoff, read the `deployment:` field on each story file to determine how the dev agent is launched:
+
+| Sprint size | File count | Score | Dev agent deployment |
+|---|---|---|---|
+| Large | 7+ files | 4+ | **Split pane** — `tmux_spawn_agent` with full context |
+| Small | 1–6 files | 0–3 | **In-process** Agent tool — targeted context only |
+
+sm-agent annotates each story file with `deployment: split-pane` or `deployment: in-process` before handing off to master-orchestrator.
+
+**Split pane deployment:** `tmux_spawn_agent` with full context (story file + PRD + architecture doc).
+**In-process deployment:** Agent tool with scoped context — story file + directly referenced docs only. No full PRD/arch unless the story explicitly references them.
+
 ### Split-Pane Agent Behaviour Rules
 
 **`--dangerously-skip-permissions` required:** ALL split pane agents MUST be launched with this flag. Mode [2] command blocks and Mode [3] launch scripts already include it. For tmux-based spawning: `tmux split-window -h "claude --dangerously-skip-permissions '{agent-persona-command}'"`.
@@ -557,14 +571,29 @@ tmux send-keys -t <pane_id> "<message>" Enter
 1. Note the new pane's ID immediately after `tmux split-window` (use `tmux display-message -p "#{pane_id}"` in the new pane or read it from `tmux list-panes`)
 2. Record it in the orchestration session file Active Agents table with role, status, and CWD
 3. Pass the spawner's own pane ID to the spawned agent as part of its task context so it knows where to report back
+4. Immediately after `split-window`, set pane title to `<role>-<pane_id>` and disable auto-rename:
+   ```bash
+   NEW_PANE_ID=$(tmux list-panes -F "#{pane_id}" | tail -1)
+   tmux set-option -t "$NEW_PANE_ID" -p allow-rename off
+   tmux select-pane -t "$NEW_PANE_ID" -T "${ROLE}-${NEW_PANE_ID}"
+   ```
+   Record `name_source: auto` in session file. If the pane had a non-default title before spawn → `name_source: manual` — NEVER rename a `manual` pane.
 
 ```bash
 # Spawn and capture spawner pane ID first
 SPAWNER_PANE=$(tmux display-message -p "#{pane_id}")
 tmux split-window -h -c "#{pane_current_path}" \
-  "claude --dangerously-skip-permissions 'You are the <role> agent. Spawner pane: $SPAWNER_PANE. <task context>'"
+  "claude --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' 'You are the <role> agent. Spawner pane: $SPAWNER_PANE. <task context>'"
+sleep 8  # ⚠️ REQUIRED — wait for pane to initialize before reading pane list or sending commands
+NEW_PANE_ID=$(tmux list-panes -F "#{pane_id}" | tail -1)
 ```
 
+**⚠️ Sleep between consecutive tmux commands.** tmux commands are asynchronous — always insert `sleep` between operations:
+- `sleep 8` after `split-window`
+- `sleep 6` after `send-keys`, `kill-pane`, `select-layout`, `set-option`, or `select-pane -T`
+
+Without sleep, race conditions cause stale pane IDs, undelivered messages, and failed layout changes.
+
 **Every spawned agent MUST report back when done:**
 
 As its final action before closing or going idle, every spawned agent sends a completion message to the pane that spawned it:
@@ -618,6 +647,32 @@ tmux kill-pane -t <pane_id>
 
 ---
 
+### Autonomous Loop Continuation Rules
+
+By default, proceed without stopping between stories and epics — no "ready?" prompts. The workflow continues autonomously unless an explicit halt trigger is encountered.
+
+**Explicit halt triggers:**
+
+| Trigger | Action |
+|---|---|
+| 🔴 review finding requiring scope change decision | Stop, ask user |
+| Schema migration needing approval | Stop, show diff, await `[approve]` |
+| Missing external credentials | Stop, tell user exactly what's needed |
+| AR max retries (3) with unresolved 🔴 | Escalate via [CC] |
+| User says "pause/wait/stop/let me think" | Pause immediately |
+| Testing lock conflict | Halt per qa.md TESTING LOCK PROTOCOL |
+| Explicit USER APPROVAL GATE in track | Hard stop |
+
+**NOT halt triggers** (auto-proceed):
+- 🟡/🟢 review findings — auto-fix and proceed
+- Review pass — announce in one line, proceed
+- QA pass — proceed
+- Story count increase
+
+Split pane is the **default** deployment. In-process is the exception (small stories only — see Sprint Size → Dev Agent Deployment Type above).
+
+---
+
 ### Per-Agent Handoff Behaviour
 
 When routing to a sub-agent, produce output based on the active mode. **Always use the Agent Persona Command** from the table above.
@@ -695,7 +750,7 @@ Then print the command block:
 # Context file: _bmad-output/scripts/context-{session_id}.md
 # Branch: {branch}  |  Session: {session_id}  |  Step: {step-name}
 # ─────────────────────────────────────────────────────────────────────────────
-claude --dangerously-skip-permissions "{agent-persona-command}"
+claude --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' "{agent-persona-command}"
 ```
 
 The new conversation opens as that agent. The user can say "load the context file at `_bmad-output/scripts/context-{session_id}.md`" and the agent has everything it needs. After printing: halt and wait for user to confirm the step is complete before routing to the next step.
@@ -729,9 +784,9 @@ $agentCmd = "{agent-persona-command}"
 if ($NonInteractive) {
     # Headless mode: capture JSON output with session_id for chaining to next step
     if ($Resume) {
-        $result = claude --resume $Resume -p $agentCmd --output-format json --dangerously-skip-permissions
+        $result = claude --resume $Resume -p $agentCmd --output-format json --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}'
     } else {
-        $result = claude -p $agentCmd --output-format json --dangerously-skip-permissions
+        $result = claude -p $agentCmd --output-format json --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}'
     }
     # Parse and save the session_id for the next step to chain from
     $parsed = $result | ConvertFrom-Json
@@ -741,9 +796,9 @@ if ($NonInteractive) {
 } else {
     # Interactive mode: opens agent in terminal, user drives the conversation
     if ($Resume) {
-        claude --resume $Resume --dangerously-skip-permissions $agentCmd
+        claude --resume $Resume --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' $agentCmd
     } else {
-        claude --dangerously-skip-permissions $agentCmd
+        claude --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' $agentCmd
     }
 }
 
@@ -835,7 +890,7 @@ Synthesize all three outputs before routing to PRD creation.
 
 - AR passed with no criticals → do NOT announce and wait — proceed to next step
 - 🟡 Major findings in any track → auto-fix, then proceed (do not halt for 🟡)
-- 🟢 Minor findings → log and proceed (never halt)
+- 🟢 Minor findings → auto-fix and proceed (never halt — treat same as 🟡)
 - Pre-QA environment check passed → do NOT report and wait — acquire lock and hand off to QA
 - QA tests all passed → do NOT wait for confirmation — proceed to next step: USER APPROVAL GATE for Small, Compact, Medium, Extended (all after QA). For Nano, proceed to USER APPROVAL after DRY+UV gate (no QA in Nano chain). Those are designed halts, not mistakes
 - Any gate that passes cleanly → announce result in one line, immediately start the next step
@@ -846,9 +901,8 @@ Scripts are generated AT ROUTING TIME (after track selection), not at session st
 
 > **Track override:** Small track limits AR to 1 pass regardless of this section. Medium/Large tracks follow the loop below.
 
-- **AR passes (no 🔴):** Announce `"✅ AR passed."` and immediately proceed to next step — no halt.
-- **AR finds 🟡/🟢 only:** Auto-fix all findings, re-run AR. Do not halt for user input.
-- **AR finds 🔴 Critical:** Auto-route back to dev agent with findings. Dev fixes → re-run AR. This loop is autonomous up to max 3 iterations.
+- **AR passes (no findings):** Announce `"✅ AR passed."` and immediately proceed to next step — no halt.
+- **AR finds any combination of 🟢/🟡/🔴:** Auto-fix ALL findings (🔴 first, then 🟡, then 🟢), re-run AR. Do not halt for user input. This loop is autonomous up to max 3 iterations.
 - **AR loop max (3) reached with unresolved 🔴:** This is a halt trigger — requires user decision:
 
 ```
@@ -886,7 +940,7 @@ flowchart TD
 Chain: `Quick Spec → Quick Dev → Review Gate (3 sub-agents: AR+DRY · UV · SR) → QA Tests (Playwright) → ⛔ USER APPROVAL → /prepare-to-merge`
 
 
-**AR pass criterion (Small):** ONE pass only — no retry loop. **Small track overrides the general AR autonomous loop — 1 pass maximum regardless of general AR rules.** 🟡/🟢 findings auto-fixed inline. Only 🔴 Critical findings halt the pipeline; route to dev for fix, then re-run AR once. If 🔴 persists after one fix attempt: escalate to user.
+**AR pass criterion (Small):** ONE pass only — no retry loop. **Small track overrides the general AR autonomous loop — 1 pass maximum regardless of general AR rules.** All findings (🔴/🟡/🟢) auto-fixed inline. If 🔴 persists after one fix attempt: escalate to user.
 
 **Review gate (Small):** `review agent` in **split pane** — stays visible because a 🔴 finding may require user scope decision. Spawns 3 concurrent Gate Sub-agents (`review_type: 3-sub`): Sub-1 (architect-agent: AR+DRY), Sub-2 (ux-designer: UV), Sub-3 (security-agent: SR).
 
@@ -1021,7 +1075,7 @@ flowchart LR
 
 **Epic completion condition:** All stories in the sprint plan for that epic are marked `done` AND the Review Gate has passed.
 
-**Large track 3-sub-agent epic gate autonomous loop:** All 3 Gate Sub-agents run concurrently in Mode [4], sequentially in Mode [1] (`review_type: 3-sub`): Sub-1 architect-agent (AR+DRY), Sub-2 ux-designer (UV), Sub-3 security-agent (SR). Findings 🟡/🟢 → auto-fix → re-run gate. 🔴 → auto-fix what's fixable → re-run gate. All autonomous up to 3 iterations.
+**Large track 3-sub-agent epic gate autonomous loop:** All 3 Gate Sub-agents run concurrently in Mode [4], sequentially in Mode [1] (`review_type: 3-sub`): Sub-1 architect-agent (AR+DRY), Sub-2 ux-designer (UV), Sub-3 security-agent (SR). ALL findings (🔴/🟡/🟢) → auto-fix → re-run gate. All autonomous up to 3 iterations.
 
 **Review gate terminal (3 loops, unresolved 🔴):** Auto-escalate via [CC] Correct Course — do not halt, do not ask. Announce: `"⚠️ Review gate [{epic_slug}] — 🔴 unresolved after 3 reviews. Auto-escalating to Correct Course."` and invoke [CC] immediately.
 
@@ -1055,7 +1109,7 @@ Wait for explicit `[approve]` before running PTM. PTM runs in-process in the mai
 | story-file-written                                       | Dev Story (new dev-agent per story, split pane)                                 |
 | Dev Story                                                | skills-detection → TDD implementation                                            |
 | TDD implementation                                       | review agent (3 Gate Sub-agents concurrent, `review_type: 3-sub`)        |
-| review agent (Sub-1: AR+DRY)                  | auto-fix (🟡/🟢); halt ONLY if 🔴 requires user scope change                   |
+| review agent (Sub-1: AR+DRY)                  | auto-fix ALL (🔴/🟡/🟢); halt ONLY if 🔴 requires user scope change            |
 | review agent (Sub-2: UV + Sub-3: SR)              | qa-sub-agent (auto-invoked, split pane) if all pass; Dev Story if 🔴            |
 | qa-sub-agent                                             | story-done if tests pass; Dev Story with failing output if fail                 |
 | story-done                                               | Create Story (next backlog story) OR all-epics-complete                         |
@@ -1438,7 +1492,7 @@ Per epic:
   1. Dev Story     → /bmad-agent-bmm-dev  (split pane, --dangerously-skip-permissions)
   2. Review Gate   → review agent  (ar-only, up to 3 passes — standard AR loop rules)
   3. QA Tests      → /bmad-agent-bmm-qa   (Playwright .spec.ts only)
-  ↩ loop until story passes Review Gate + QA with no 🔴
+  ↩ loop until story passes Review Gate (all 🔴/🟡/🟢 fixed) + QA
 ```
 
 On max 3 AR iterations with unresolved 🔴 → HALT per AR escalation rules above.
@@ -1451,9 +1505,9 @@ On max 3 AR iterations with unresolved 🔴 → HALT per AR escalation rules abo
 
 #### SMALL PATH — Quick Dev
 
-**Step 8S:** Route `/bmad-agent-bmm-quick-flow-solo-dev` → `/bmad-bmm-quick-dev` (split pane). Fixes all 🔴 + 🟡 from `review-plan-{artifact_id}.md`.
+**Step 8S:** Route `/bmad-agent-bmm-quick-flow-solo-dev` → `/bmad-bmm-quick-dev` (split pane). Fixes ALL findings (🔴 + 🟡 + 🟢) from `review-plan-{artifact_id}.md`.
 
-**Step 9S — Review Gate:** `review agent` with `review_type: 3-sub`. **AR pass rules (Small path):** 1 pass max. 🟡/🟢 auto-fixed. 🔴 → route back to Step 8S once. Persistent 🔴 → escalate.
+**Step 9S — Review Gate:** `review agent` with `review_type: 3-sub`. **AR pass rules (Small path):** 1 pass max. ALL findings (🔴/🟡/🟢) auto-fixed. If 🔴 persists → route back to Step 8S once. Persistent 🔴 → escalate.
 
 **Step 10S:** QA Tests — `/bmad-agent-bmm-qa` (split pane). Playwright `.spec.ts` only.
 
@@ -1603,12 +1657,11 @@ Derive `artifact_id` from active `session_id` if not already set. Run ALL passes
 1. Route `/bmad-agent-bmm-ux-designer` with UI Review handoff context (`loop_mode: true`, `output_path: ...pass1.md`)
 2. ux-designer produces `ui-review-findings-{artifact_id}-pass1.md`
 3. Conductor reads findings:
-   - 🟢 only → log, announce `"✅ UV passed in 1 pass."` → exit loop early
-   - 🟡/🟢 → extract all actionable items, build fix list
-   - 🔴 → add to fix list (🔴 first)
+   - No findings → announce `"✅ UV passed in 1 pass."` → exit loop early
+   - 🟢/🟡/🔴 → extract ALL actionable items into fix list (🔴 first, then 🟡, then 🟢)
 
-**Auto-fix step (after each pass with 🔴 or 🟡):**
-Route dev agent with fix list from `ui-review-findings-{artifact_id}-pass{N}.md`. Dev fixes ALL listed items autonomously. No halts.
+**Auto-fix step (after each pass with ANY findings):**
+Route dev agent with fix list from `ui-review-findings-{artifact_id}-pass{N}.md`. Dev fixes ALL listed items (🔴 + 🟡 + 🟢) autonomously. No halts.
 
 **Pass 2** (if `uv_loop_max >= 2` AND pass 1 had findings):
 Re-run ux-designer. Write `ui-review-findings-{artifact_id}-pass2.md`. Same categorization.
@@ -1746,11 +1799,11 @@ Derive `artifact_id` from active `session_id` if not already set. Run ALL passes
 1. Route `/bmad-agent-bmm-architect` with DRY Review handoff context (`output_path: ...pass1.md`)
 2. architect-agent produces `dry-review-findings-{artifact_id}-pass1.md`
 3. Conductor reads findings:
-   - 🟢 only → log, announce `"✅ DRY passed in 1 pass."` → exit loop early
-   - 🟡/🔴 → extract all actionable items, build fix list (🔴 first)
+   - No findings → announce `"✅ DRY passed in 1 pass."` → exit loop early
+   - 🟢/🟡/🔴 → extract ALL actionable items into fix list (🔴 first, then 🟡, then 🟢)
 
-**Auto-fix step (after each pass with 🔴 or 🟡):**
-Route dev agent with fix list. Dev fixes ALL listed items autonomously. No halts.
+**Auto-fix step (after each pass with ANY findings):**
+Route dev agent with fix list. Dev fixes ALL listed items (🔴 + 🟡 + 🟢) autonomously. No halts.
 
 **Pass 2** (if `dry_loop_max >= 2` AND pass 1 had findings):
 Re-run architect-agent. Write `dry-review-findings-{artifact_id}-pass2.md`. Same categorization.
@@ -1887,11 +1940,11 @@ Derive `artifact_id` from active `session_id` if not already set. Run ALL passes
 1. Route `/bmad-agent-bmm-security` (or dev fallback) with both skills loaded
 2. Agent produces `sr-review-findings-{artifact_id}-pass1.md`
 3. Conductor reads findings:
-   - 🟢 only → log, announce `"✅ SR passed in 1 pass."` → exit loop early
-   - 🟡/🔴 → extract all actionable items (🔴 VULN first, then 🟡 VERIFY)
+   - No findings → announce `"✅ SR passed in 1 pass."` → exit loop early
+   - 🟢/🟡/🔴 → extract ALL actionable items (🔴 VULN first, then 🟡 VERIFY, then 🟢 minor)
 
-**Auto-fix step (after each pass with 🔴 or 🟡):**
-Route dev agent with fix list. Dev fixes ALL listed items autonomously. No halts.
+**Auto-fix step (after each pass with ANY findings):**
+Route dev agent with fix list. Dev fixes ALL listed items (🔴 + 🟡 + 🟢) autonomously. No halts.
 
 **Pass 2** (if `sr_loop_max >= 2` AND pass 1 had findings):
 Re-run security agent with both skills. Write `sr-review-findings-{artifact_id}-pass2.md`.
@@ -2274,7 +2327,7 @@ rm -f _bmad-output/qa-tests/.testing-lock-{session_id}.json
 | Large — Design DRY+UV Gate          | Large    | DRY+UV after Architecture (no AR, no SR)       | 2          | Winston, Bond, Sally, Bob, Paige (5 min) |
 | Large — Epic Review Gate (3-sub)        | Large    | 3 sub-agents concurrent in epic loop, per-story    | 3          | Bond, Amelia, qa-agent, Bob (4 min)         |
 
-**Universal rule:** All present agents ≥10 items each. Severity: 🔴 Critical blocks progression | 🟡 Major addressed before next phase | 🟢 Minor at discretion.
+**Universal rule:** All present agents ≥10 items each. Severity: 🔴 Critical blocks progression | 🟡 Major addressed before next phase | 🟢 Minor addressed before next phase.
 
 ### PMR (Party Mode Review) — Standalone Only
 

package/src/_memory/skills/nimbalyst-tracking/SKILL.md

@@ -1,103 +1,103 @@
----
-name: nimbalyst-tracking
-description: Nimbalyst structured item tracking syntax. Use when identifying tasks, bugs, ideas, or decisions.
----
-
-# SKILL: Nimbalyst Structured Tracking
-
-## Goal
-Integrate structured item tracking across all AI agent interactions using YAML frontmatter blocks.
-
-## Tracked Item Types
-- `task`: Actionable items to be completed.
-- `bug`: Defects found in code or design.
-- `idea`: Potential improvements or new concepts.
-- `decision`: Key architectural or product decisions.
-- `feature-request`: User or stakeholder requested features.
-- `technical-debt`: Identified code or architecture smells.
-- `user-feedback`: Feedback gathered from users.
-- `user-story`: Agile user stories generated during planning.
-- `plan`: Planning items.
-
-## Rules
-1. **Structured YAML Blocks**: Output trackable items as `trackingStatus` YAML frontmatter in markdown files.
-2. **Capture Aggressively**: Every time you identify a bug, make a decision, or propose an idea, create a tracker.
-3. **File Placement**: Write tracker files to `nimbalyst-local/tracker/[type]-[id].md`
-4. **MCP Bridge**: If you have access to `tracker_create` or `tracker_update` MCP tools (Nimbalyst environment), call them directly IN ADDITION to writing the file. This ensures items appear immediately on the Nimbalyst Trackers page.
-5. **Status Updates**: When updating an existing item's status:
-   - Update the `status` and `updated` fields in the file's YAML frontmatter
-   - If `nimbalystId` is present in frontmatter, call `tracker_update(id: nimbalystId, status: mapped_status)`
-   - If `nimbalystId` is NOT present, search `tracker_list(search: title)` to find the item, then call `tracker_update`
-
-### MCP Tool Field Mapping
-
-| YAML Field | MCP `tracker_create` Param | Notes |
-|------------|---------------------------|-------|
-| `title`    | `title`                   | Required |
-| `type`     | `type`                    | task, bug, idea, decision |
-| `priority` | `priority`                | low, medium, high, critical |
-| `status`   | `status`                  | See status mapping below |
-| `tags`     | `tags`                    | Pass as array |
-| body       | `description`             | Markdown description |
-
-### Status Mapping (File -> Nimbalyst MCP)
-
-| File Status    | Nimbalyst Status |
-|---------------|-----------------|
-| Draft          | to-do           |
-| Ready          | to-do           |
-| In Development | in-progress     |
-| In Review      | in-progress     |
-| Completed      | done            |
-| Rejected       | to-do           |
-| Blocked        | to-do           |
-
-## Item Structure
-
-Each tracker item is a markdown file with this frontmatter:
-
-```yaml
----
-trackingStatus:
-  itemId: [type]-[unique-id]
-  nimbalystId: [nimbalyst-id]    # Set by sync automation or MCP bridge - enables direct updates
-  title: [Short Description]
-  type: [task|bug|idea|decision]
-  status: [Draft|Ready|In Development|In Review|Completed|Rejected|Blocked]
-  priority: [None|Low|Medium|High|Critical]
-  assignee: [username]
-  tags:
-    - [tag1]
-    - [tag2]
-  created: "YYYY-MM-DD"
-  updated: "YYYY-MM-DDTHH:MM:SS.sssZ"
----
-
-Description and details here.
-```
-
-## Example Usage
-
-If you are the Architect and you just decided to use Redis for pub/sub:
-
-"I have decided to use Redis for the WebSocket pub/sub implementation. Here is the recorded decision:
-
-```yaml
----
-trackingStatus:
-  itemId: decision-pubsub-01
-  title: "Use Redis for WebSocket Pub/Sub"
-  type: decision
-  status: Completed
-  priority: Medium
-  assignee: []
-  tags:
-    - architecture
-    - websockets
-    - redis
-  created: "2026-03-11"
-  updated: "2026-03-11T12:00:00.000Z"
----
-```
-
-"
+---
+name: nimbalyst-tracking
+description: Nimbalyst structured item tracking syntax. Use when identifying tasks, bugs, ideas, or decisions.
+---
+
+# SKILL: Nimbalyst Structured Tracking
+
+## Goal
+Integrate structured item tracking across all AI agent interactions using YAML frontmatter blocks.
+
+## Tracked Item Types
+- `task`: Actionable items to be completed.
+- `bug`: Defects found in code or design.
+- `idea`: Potential improvements or new concepts.
+- `decision`: Key architectural or product decisions.
+- `feature-request`: User or stakeholder requested features.
+- `technical-debt`: Identified code or architecture smells.
+- `user-feedback`: Feedback gathered from users.
+- `user-story`: Agile user stories generated during planning.
+- `plan`: Planning items.
+
+## Rules
+1. **Structured YAML Blocks**: Output trackable items as `trackingStatus` YAML frontmatter in markdown files.
+2. **Capture Aggressively**: Every time you identify a bug, make a decision, or propose an idea, create a tracker.
+3. **File Placement**: Write tracker files to `nimbalyst-local/tracker/[type]-[id].md`
+4. **MCP Bridge**: If you have access to `tracker_create` or `tracker_update` MCP tools (Nimbalyst environment), call them directly IN ADDITION to writing the file. This ensures items appear immediately on the Nimbalyst Trackers page.
+5. **Status Updates**: When updating an existing item's status:
+   - Update the `status` and `updated` fields in the file's YAML frontmatter
+   - If `nimbalystId` is present in frontmatter, call `tracker_update(id: nimbalystId, status: mapped_status)`
+   - If `nimbalystId` is NOT present, search `tracker_list(search: title)` to find the item, then call `tracker_update`
+
+### MCP Tool Field Mapping
+
+| YAML Field | MCP `tracker_create` Param | Notes |
+|------------|---------------------------|-------|
+| `title`    | `title`                   | Required |
+| `type`     | `type`                    | task, bug, idea, decision |
+| `priority` | `priority`                | low, medium, high, critical |
+| `status`   | `status`                  | See status mapping below |
+| `tags`     | `tags`                    | Pass as array |
+| body       | `description`             | Markdown description |
+
+### Status Mapping (File -> Nimbalyst MCP)
+
+| File Status    | Nimbalyst Status |
+|---------------|-----------------|
+| Draft          | to-do           |
+| Ready          | to-do           |
+| In Development | in-progress     |
+| In Review      | in-progress     |
+| Completed      | done            |
+| Rejected       | to-do           |
+| Blocked        | to-do           |
+
+## Item Structure
+
+Each tracker item is a markdown file with this frontmatter:
+
+```yaml
+---
+trackingStatus:
+  itemId: [type]-[unique-id]
+  nimbalystId: [nimbalyst-id]    # Set by sync automation or MCP bridge - enables direct updates
+  title: [Short Description]
+  type: [task|bug|idea|decision]
+  status: [Draft|Ready|In Development|In Review|Completed|Rejected|Blocked]
+  priority: [None|Low|Medium|High|Critical]
+  assignee: [username]
+  tags:
+    - [tag1]
+    - [tag2]
+  created: "YYYY-MM-DD"
+  updated: "YYYY-MM-DDTHH:MM:SS.sssZ"
+---
+
+Description and details here.
+```
+
+## Example Usage
+
+If you are the Architect and you just decided to use Redis for pub/sub:
+
+"I have decided to use Redis for the WebSocket pub/sub implementation. Here is the recorded decision:
+
+```yaml
+---
+trackingStatus:
+  itemId: decision-pubsub-01
+  title: "Use Redis for WebSocket Pub/Sub"
+  type: decision
+  status: Completed
+  priority: Medium
+  assignee: []
+  tags:
+    - architecture
+    - websockets
+    - redis
+  created: "2026-03-11"
+  updated: "2026-03-11T12:00:00.000Z"
+---
+```
+
+"