pi-orchestrator-config 4.1.5

package/rules/25-documentation-updates.md

@@ -0,0 +1,15 @@
+# Documentation Updates (MANDATORY)
+
+After ANY code is added, changed, or removed, check if documentation needs updating:
+
+| Change | Check these files |
+|--------|-------------------|
+| New feature/command/tool | `README.md` (feature table, usage examples) |
+| New or modified extension module | `dev-docs/repo-structure.md` (repository structure) |
+| New agent added/removed | `dev-docs/repo-structure.md` (structure), `rules/10-agent-routing.md` (routing table), `rules/50-agent-bug-reporting.md` (agent list) |
+| New prompt template | `README.md` (prompt templates table) |
+| Docker/container changes | `README.md` (Docker section, shell alias, mounts), `Dockerfile` |
+| New CLI tool or dependency | `README.md` (tools table), `Dockerfile` |
+| Dev workflow changes | `DEVELOPMENT.md` |
+
+**Do not skip this step.** Documentation drift is a bug.

package/rules/30-prompt-templates.md

@@ -0,0 +1,19 @@
+# Prompt Template Execution Rules
+
+## When a Prompt Template is Invoked
+
+1. **The prompt template is the authority** — follow its instructions
+2. **NEVER delegate the prompt template itself** to an agent — the orchestrator executes it
+3. **The prompt decides** when to run directly and when to delegate to agents
+4. If the prompt says "run this bash command" — run it directly
+5. If the prompt says "delegate to X agent" — delegate
+6. If the prompt doesn't specify — follow normal orchestrator rules (delegate to specialists)
+
+## Key Rules
+
+- The orchestrator **maintains control** of the prompt workflow
+- The prompt template's instructions **override** general delegation rules when they conflict
+- **NEVER** delegate the `/command` itself to an agent — only delegate sub-tasks when the prompt says to
+
+❌ **WRONG**: `/mycommand` → delegate entire prompt to an agent
+✅ **RIGHT**: `/mycommand` → orchestrator follows the prompt → delegates sub-tasks as the prompt instructs

package/rules/35-memory.md

@@ -0,0 +1,240 @@
+# Project Memory
+
+Scored, topic-organized memory system with stability-based decay.
+Memories are scored, prioritized, and injected into the system prompt via situation reports.
+
+---
+
+## Memory Tools (MANDATORY)
+
+You have five memory tools and one session search tool. **USE THEM PROACTIVELY:**
+
+## Auto-Injection (how memories reach you)
+
+Three mechanisms automatically inject relevant context into your system prompt — you don't need to call tools for these:
+
+1. **Situation Report** — token-budgeted summary of scored memories (preferences, lessons, mistakes, patterns, decisions, completions). Always present.
+2. **Contextual Memory Recall** — vector similarity search against your current message. Entries with similarity > 0.65 appear as "Contextually Relevant Memories."
+3. **Session History Recall** — keyword search against past conversation summaries. Relevant past sessions appear as "Relevant Past Sessions."
+
+**Ground Truth:** All injected memories are authoritative. Use them directly —
+do not re-discover or re-verify information already in your context window.
+
+**Social closer gate:** Trivial messages ("ok", "thanks", "👍", < 6 chars) skip vector/session search.
+
+### `memory_search` — Search Before Answering
+
+**MANDATORY:** Before answering questions about prior sessions, user preferences, past decisions, or anything mentioned before —
+call `memory_search` first. Supports keyword and category-filtered queries.
+
+### `memory_reinforce` — Reinforce When Relevant
+
+**MANDATORY:** When a memory is relevant to the current task, call `memory_reinforce` to bump its evidence count and prevent decay.
+
+### `memory_add` — Add New Memories Proactively
+
+**MANDATORY:** When you learn something worth remembering — preferences, corrections, conventions, completed work — add it immediately.
+Keep entries short (~100 chars), specific, actionable.
+Use `pinned: true` ONLY when user explicitly says "remember this". Duplicates are auto-reinforced.
+When a correction is mechanical (can be checked by code), add `trigger` + `action` params — see "Code-Enforced Memories" below.
+
+### `memory_remove` — Remove Outdated Memories
+
+Remove entries that are no longer accurate, relevant, or superseded by newer entries.
+
+### `memory_topics` — Inspect Topic Organization
+
+List all memory topic files with hotness scores and entry counts.
+
+### `session_search` — Recall Past Conversations
+
+Search past conversation summaries for references to previous sessions. Returns matching snippets at zero LLM cost.
+
+---
+
+## Memory Storage
+
+```text
+.pi/memory/
+├── memory-scores.json     # Scoring backend (auto-managed)
+└── topics/
+    ├── preferences.md     # [preference] entries
+    ├── lessons.md         # [lesson] entries
+    ├── patterns.md        # [pattern] entries
+    ├── decisions.md       # [decision] entries
+    ├── completions.md     # [done] entries
+    └── mistakes.md        # [mistake] entries
+```
+
+**Pinned** — user explicitly said "remember this". Dream must NEVER remove these.
+**Learned** — auto-extracted by dreaming. Dream can reorganize, deduplicate, remove.
+
+---
+
+## Scoring System
+
+```text
+stability = cue_weight × exp(-Δt / half_life) × ln(1 + evidence_count)
+```
+
+- Reinforcing bumps evidence count and resets decay. Pinned = 9999 (never decay). Forgotten = 0.
+- **Lifecycle:** active → provisional → candidate → dropped
+
+---
+
+## Capacity Signal
+
+The situation report header shows usage: `# Project Memory [72% — 1,224/1,700 tokens]`
+
+- **Below 80%** — add freely
+- **Above 80%** — consolidate before adding: merge related entries, remove outdated ones
+
+---
+
+## Memory Quality Rules (CRITICAL)
+
+- **One line only** — max ~100 chars, single short sentence
+- **Specific and actionable** — concrete "do X" or "don't do Y", no fluff
+- **Preserve context scope** — if a preference was stated about a specific tool/project/workflow,
+  include that scope in the memory. NEVER generalize a context-specific statement into a universal rule.
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "We had issues with buildah and Docker caching and tried several approaches" | "buildah chown -R breaks cache mounts — use --mount=type=cache with correct uid" |
+| "User prefers a certain approach to handling processes" | "Attach child processes to pi (no detached:true) — kills on exit" |
+| "Never use gemini-2.5-flash model" (said about a specific tool) | "Never use gemini-2.5-flash for X — unreliable for that use case" |
+
+---
+
+## When to Write
+
+| Trigger | Category | Section |
+|---------|----------|--------|
+| User says "remember" / `/remember` | best fit | **Pinned** |
+| PR merged | `done` | Learned |
+| User corrects you | `lesson` | Learned |
+| Multiple fix attempts | `mistake` | Learned |
+| User states a preference | `preference` | Learned |
+
+---
+
+## Code-Enforced Memories (Enforcement Layer)
+
+Some memories can be **code-enforced** — the LLM cannot ignore them because runtime hooks
+check and act on them. Use enforcement when a rule is **mechanical** (can be checked by code).
+
+Add enforcement by passing `trigger`, `action`, and optionally `verifier` to `memory_add`:
+
+```text
+memory_add(text="...", category="lesson",
+  trigger="bash_contains git add .",
+  action="block")
+```
+
+**When to add enforcement (AI decides automatically):**
+
+| Pattern | Enforcement | Example |
+|---------|-------------|--------|
+| User corrects a specific command/tool usage | `trigger` + `block` | "never use git add ." |
+| User wants something to run after a specific action | `trigger` + `run_after <cmd>` | "always deploy after code changes" |
+| User wants a warning about a specific pattern | `trigger` + `warn` | "warn when modifying config files" |
+| User wants tool A called before tool B | `verifier` | "always ask_user before gh pr merge" |
+| General knowledge / context / facts | **No enforcement** | "buildah chown breaks cache mounts" |
+
+**Rule of thumb:** If you can express it as "when X happens, do/block/warn Y" — add enforcement.
+If it's knowledge that informs decisions but can't be checked mechanically — plain memory only.
+
+**Trigger types:** `bash_contains <str>`, `bash_regex <pattern>`, `tool_name <name>`, `file_modified <pattern>` (matches file extensions like `*.py` or path substrings like `Dockerfile`)
+**Action types:** `block` (prevent), `run_after <command>` (execute after), `warn` (append warning)
+**Verifier:** `tool_called <tool> before <command>` (checked at turn_end, forces retry on violation)
+
+---
+
+## Per-Turn Self-Improvement (MANDATORY)
+
+**After EVERY response, ask:** "Did this turn contain something worth remembering?"
+
+| What happened | Action |
+|---------------|--------|
+| User corrected you / said "don't do X" / "always do Y" | `memory_add` as `lesson` or `preference` |
+| Something failed or took multiple attempts | `memory_add` as `mistake` |
+| PR merged / technical decision made / non-obvious pattern found | `memory_add` as `done` / `decision` / `pattern` |
+
+**NEVER memorize:**
+
+- Ideas or requests the user rejected, abandoned, or said "nevermind" to
+- Unfinished conversations where no conclusion was reached
+- User requirements that were never implemented
+
+Only memorize **outcomes** (what happened), not **intentions** (what was discussed but dropped).
+
+**Save immediately — do NOT wait for `/dream` or session shutdown.**
+
+---
+
+## CLI
+
+```bash
+uv run myk-pi-tools memory <command>   # Commands: add, forget, show, migrate, path, status
+```
+
+**Categories:** `lesson`, `decision`, `mistake`, `pattern`, `done`, `preference`
+
+`memory status` — enforcement honesty inventory (code-tier vs injected topic counts + open promotions).
+
+---
+
+## Dreaming (Background Consolidation)
+
+Background async agent that reads the session, extracts things worth remembering, adds/deduplicates/reorganizes topic files, and removes stale entries. **NEVER removes Pinned entries.**
+Triggered by `/dream` (manual) or session shutdown (automatic).
+**ALWAYS run as async + fireAndForget** — never block the session.
+
+**Dreaming follows the same NEVER memorize rules as per-turn self-improvement:**
+do NOT extract rejected/abandoned ideas, unfinished conversations, or unimplemented requirements.
+Only extract outcomes, not intentions.
+
+---
+
+## Skill Creation (Procedural Memory)
+
+Memory stores facts; **skills store procedures.**
+When you complete a multi-step workflow (3+ steps, or doing the same multi-step task for the second time,
+trial-and-error, or non-obvious commands), save it as a skill via `/create-skill <name>`.
+Don't create skills for simple one-step tasks or standard workflows already covered by existing skills.
+
+---
+
+## Promotion Destinations (Correction → Structure)
+
+Memories are a staging area. High-evidence or recurring lessons should graduate:
+
+| Destination | When | Auto? |
+|-------------|------|-------|
+| `memory` | Stay as a scored topic line | default |
+| `skill` | Multi-step recurring workflow | dream may write `.pi/skills/` |
+| `enforcement` | Mechanical never/always + command/tool | safe auto-apply (`block`/`warn` + clear trigger) |
+| `project_rule` | Project-wide convention, not mechanical | **propose only** — never auto-write `rules/` or `.pi/rules/` |
+| `discard` | Stale / superseded | mark in queue |
+
+Queue file: `.pi/memory/promotions.md`. Situation report shows open `proposed` items.
+Thresholds (evidenceCount): enforcement/skill ≥ 3; project_rule ≥ 5.
+On reinforce crossing a threshold, a promotion pass runs automatically.
+`memory_consolidate` and dreaming must write promotion candidates to that queue.
+
+---
+
+## Provenance (optional)
+
+`memory_add` / `memory_edit` accept optional `sourceSession`, `derivedFrom`, `informs`.
+Preference extractor sets `sourceSession` when the session id is available.
+Dream may write `.pi/memory/provenance-pending.json`; merge happens on dream complete.
+Stored in `memory-scores.json` only — not injected into the situation report.
+Shown in `memory_search` / `memory_reflect` when present.
+
+---
+
+## Query-class injection (automatic)
+
+Injection biases section budgets from the user prompt (no tool call needed):
+`pr_review`, `git_release`, `debug`, or `general`.

package/rules/40-critical-rules.md

@@ -0,0 +1,124 @@
+# Critical Rules
+
+## Questions Are Not Instructions (MANDATORY)
+
+When the user asks a question, ONLY answer it. Do not modify files, run state-changing commands,
+create branches/PRs/issues, or take any action beyond reading/searching.
+A question mark means answer only — the user will tell you when to act.
+
+---
+
+## Task Focus (MANDATORY)
+
+When executing a multi-step workflow, never abandon it for a side question. Answer the question,
+then immediately resume the workflow from where you left off. After every response, ask yourself:
+was I in a workflow? If yes, what's the next step?
+
+---
+
+## Parallel Execution (MANDATORY)
+
+Before every response, identify operations that can run in parallel and execute them all in one message.
+
+- Spawn independent agents simultaneously, not sequentially.
+- Only execute sequentially when there's a proven data dependency between operations.
+
+### Async Agents
+
+Use `async: true` for independent tasks (reviews, research, polling, monitoring, CI checks) — any task where you don't need the result immediately.
+Only use sync when the very next step depends on this agent's output.
+After spawning async agents, end your turn — results arrive automatically as a follow-up message.
+(`fireAndForget: true` agents are silent — no follow-up.)
+
+Do NOT write bash loops, sleep commands, or poll for results after spawning async agents.
+
+❌ Spawn async agent → write bash sleep/poll loop in the same turn
+✅ Spawn async agent → end your turn — results arrive as follow-up automatically
+
+Kill async agents with `asyncKill` when their result is no longer needed.
+
+### Sync Agent Time Estimates
+
+Provide `estimatedSeconds` when spawning sync subagents (single, parallel, or chain).
+If the estimated time is 30 seconds or more, use `async: true` instead — the tool enforces this.
+Single: `estimatedSeconds` on top-level. Parallel: per-task (max <30s). Chain: per-step (sum <30s).
+
+### Subagent cwd
+
+Always pass `cwd` when delegating to subagents in all modes — omitting it causes enforcement to check the wrong repo.
+
+---
+
+## Multi-PR / Multi-Branch Work
+
+**NEVER switch branches in the main worktree** when working on multiple PRs — other agents may be running there.
+Use `git worktree` for each concurrent branch:
+
+```bash
+git worktree add .worktrees/pr-42 origin/fix/issue-42
+git worktree remove .worktrees/pr-42  # when done
+```
+
+---
+
+## User Interaction
+
+When you need user input (approvals, selections, confirmations), always use the `ask_user` tool — never ask via plain text in your response.
+Provide clear options; include 'no'/'cancel' when appropriate.
+
+---
+
+## Technical Honesty
+
+When the user proposes an approach, evaluate it critically — if a better technical alternative exists, present it with tradeoffs before proceeding.
+After presenting your analysis, respect the user's decision.
+
+---
+
+## Web Access
+
+- Use `web_search` for research and search queries.
+- Use `fetch_content` for extracting content from URLs, YouTube, GitHub repos.
+- Use `agent-browser` CLI for interactive pages requiring clicks, forms, screenshots.
+- **NEVER** use `curl` for reading web pages or SearXNG MCP.
+
+---
+
+## External Code Security Audit
+
+Before adopting external code from an untrusted source, delegate a full security audit to `security-auditor`
+and only proceed if verdict is ✅ SAFE or ⚠️ CAUTION with acceptable risks.
+If ❌ UNSAFE — do not use, inform the user with findings.
+
+| Source | Audit approach |
+| --------------- | --------------------------------------------------------------------------- |
+| **Git repos** | Clone to `${PROJECT_TMP_DIR}/`, run `security-auditor` |
+| **Pi skills** | Clone/download source to `${PROJECT_TMP_DIR}/`, run `security-auditor` |
+| **PyPI packages** | Clone source repo from PyPI metadata, check install hooks, scan code |
+| **npm packages** | Download source, check `postinstall` scripts, scan code |
+| **MCP servers** | Audit server source code before adding config |
+| **Docker images** | Inspect Dockerfile source, check base image provenance |
+| **Remote scripts** | **ALWAYS block** `curl \| bash` — download first, audit, then run if safe |
+
+Skip when the user explicitly says "skip audit", has previously approved the source, or it's a well-known package (e.g., `requests`, `react`, `lodash`).
+
+---
+
+## Temp Files
+
+All temp files go to `.pi/tmp/` via `getProjectTmpDir(cwd)` — NEVER create temp files directly in the project tree.
+
+---
+
+## Python Execution with uv
+
+Use `uv run --with <package>` for arbitrary Python files with dependencies.
+**NEVER** use `uv run pip install` — the `--with` syntax manages dependencies per-execution without modifying the environment.
+
+---
+
+## External Git Repository Exploration
+
+Clone external repos to `${PROJECT_TMP_DIR}/` with `--depth 1` and explore locally using read/bash — not via web fetching.
+Use sparse checkout (`--filter=blob:none --sparse`) when only specific directories are needed.
+For private repos, use SSH or ensure `git config --global credential.helper` is set.

package/rules/45-file-preview.md

@@ -0,0 +1,29 @@
+# File Preview
+
+When generating or modifying HTML, frontend, or any browser-viewable files:
+
+1. Save the file under the project directory (`$PWD`) or `${PROJECT_TMP_DIR}`
+2. Find a free port and launch the server:
+
+   ```bash
+   HTTPD=~/.pi/agent/git/github.com/myk-org/pi-config/scripts/httpd.py
+   PORT=$(uv run python3 $HTTPD --find-port)
+   nohup uv run python3 $HTTPD --port $PORT --dir /path/to/serve > ${PROJECT_TMP_DIR}/httpd-$PORT.log 2>&1 &
+   disown
+   sleep 0.5
+   if ! kill -0 $! 2>/dev/null; then echo "Server failed to start:"; cat ${PROJECT_TMP_DIR}/httpd-$PORT.log; fi
+   ```
+
+   Replace `/path/to/serve` with the directory containing the files.
+
+3. Tell the user:
+
+   > File is being served at `http://localhost:<port>/<filename>` — open this URL in your browser.
+
+4. Keep the server running until the user confirms they're done previewing.
+
+**Why `nohup` + `disown`?** `uv run` creates a parent process chain. When bash
+cleans up background jobs, it kills the `uv` parent. `nohup` protects from
+SIGHUP, `disown` removes it from bash's job table.
+
+This works in containers (`--network host`) and native installs.

package/rules/50-agent-bug-reporting.md

@@ -0,0 +1,90 @@
+# Agent Bug Reporting
+
+## Scope
+
+> **If you are a SPECIALIST AGENT:**
+> IGNORE this rule. This is for the ORCHESTRATOR only.
+
+When the orchestrator discovers a logic flaw or bug in an agent's configuration or instructions, follow this workflow.
+
+## Agents Covered by This Rule
+
+This rule applies ONLY to agents defined in this repository (`agents/` directory):
+
+- api-documenter
+- bash-expert
+- code-reviewer-docs
+- code-reviewer-guidelines
+- code-reviewer-quality
+- code-reviewer-security
+- code-reviewer-spec
+- issue-reviewer-spec
+- issue-reviewer-feasibility
+- issue-reviewer-scope
+- debugger
+- docs-fetcher
+- docker-expert
+- ts-expert
+- git-expert
+- github-expert
+- go-expert
+- java-expert
+- jenkins-expert
+- kubernetes-expert
+- planner
+- python-expert
+- reviewer
+- scout
+- security-auditor
+- technical-documentation-writer
+- test-automator
+- test-runner
+- worker
+
+**NOT covered:** Built-in pi agents or agents from other sources.
+
+## When to Trigger
+
+**Trigger** when you find flawed logic, incorrect results, contradictory behavior, or systematic errors in an agent's instructions (in `agents/` directory — see scope list above).
+**Do NOT trigger** for runtime/external failures, user code bugs, expected behavior the user disagrees with, or bugs in built-in pi agents.
+
+## Workflow
+
+1. **Ask user:** "I found a logic bug in [agent]. Do you want me to create a GitHub issue for this?"
+2. **If yes:** Delegate to `github-expert` to create the issue in `myk-org/pi-config`.
+3. **Continue** with the original task (fix bug or apply workaround) regardless of the answer.
+
+## Issue Creation Format
+
+**Title:** `bug(agents): [agent-name] - brief description`
+
+**Body template:**
+
+```markdown
+## Agent
+[Agent name from agents/ directory]
+
+## Bug Description
+[Clear description of the logic flaw]
+
+## Expected Behavior
+[What the agent should do]
+
+## Actual Behavior
+[What the agent actually does]
+
+## Suggested Fix
+[Proposed change, if known]
+
+## Impact
+[How this affects users/workflows]
+
+## Context
+[Any additional context about when/how the bug was discovered]
+```
+
+## Key Rules
+
+Always ask user before creating an issue — never auto-create.
+Delegate issue creation to `github-expert` (don't use `gh` commands directly).
+Be specific about which agent and which logic is flawed, and suggest a fix if you know one.

package/rules/55-coms-protocol.md

@@ -0,0 +1,63 @@
+# Coms Protocol — Inter-Agent Communication
+
+## Overview
+
+Two communication systems are available for talking to other pi sessions:
+
+| System | Activation | Tool prefix | Transport |
+|--------|-----------|-------------|-----------|
+| **P2P** (coms) | `/coms start` | `coms_` | Direct peer-to-peer |
+| **Networked** (coms-net) | `/coms-net start` | `coms_net_` | Hub server relay |
+
+Both systems can be active. When asked to list peers, send messages, or interact with coms —
+**try both** `coms_list` and `coms_net_list`. If one fails, use the other.
+Don't assume which system is active.
+
+## Activation
+
+Tools are unavailable until the user runs `/coms start` (P2P) or `/coms-net start` (networked).
+Use `coms_list` / `coms_net_list` to see connected peers.
+
+## Tool Reference
+
+| Action | P2P (coms) | Networked (coms-net) |
+|--------|-----------|---------------------|
+| List peers | `coms_list` | `coms_net_list` |
+| Send message | `coms_send` | `coms_net_send` |
+| Poll for response | `coms_get` | `coms_net_get` |
+
+## Inbound Messages — How to Reply
+
+Inbound messages appear as `[from <peer> @ <cwd>] <message>`. Your assistant text IS the reply — the `agent_end` hook captures it and sends it back automatically.
+
+❌ **Never call `coms_send` to reply** — that starts a new outbound conversation instead of replying.
+
+## Outbound Messages — How to Initiate
+
+To start a conversation: call the send tool, then **end your turn**.
+The peer's response auto-delivers as a followUp message — no polling needed.
+Use `coms_get` / `coms_net_get` only for non-blocking status checks.
+
+## Message Queue
+
+Inbound messages process in FIFO order. If multiple arrive while the peer is busy, they queue — each gets its own turn and response, nothing is dropped.
+
+## Structured Task Delegation
+
+Use the `tasks` parameter to delegate structured work items alongside messages. Tasks appear in the peer's task widget (requires `@tintinweb/pi-tasks`):
+
+```text
+coms_send(target="coder", prompt="Implement these features", tasks=[
+  {"subject": "Add auth middleware", "description": "JWT validation for all /api routes"},
+  {"subject": "Write tests", "description": "Unit tests for auth middleware"}
+])
+```
+
+## Key Rules
+
+1. **Responses auto-deliver** — after send, end your turn; the reply arrives as a followUp
+2. **Never call send tools to reply** to inbound messages — your assistant text is the reply
+3. **Always check peers first** — use list tools before sending
+4. **Try both systems** — try `coms_` and `coms_net_` when system isn't specified
+5. **Messages are never lost** — busy peers queue messages in FIFO order
+6. **Use tasks for structured work** — use `tasks` parameter instead of prose lists

package/rules/60-task-tracking.md

@@ -0,0 +1,66 @@
+# Task Tracking (MANDATORY)
+
+## Scope
+
+> **If you are a SPECIALIST AGENT:**
+> IGNORE this rule. This is for the ORCHESTRATOR only.
+
+---
+
+## When to Create Tasks
+
+**BEFORE starting any multi-step workflow (3+ steps)**, use `TaskCreate` to list ALL steps first.
+
+**Use tasks for:** feature implementation, bug fixes with multiple files,
+workflows from `rules/05-issue-first-workflow.md` or `rules/20-code-review-loop.md`,
+multi-file refactoring, or any work involving more than 2 actions.
+
+**Skip tasks for:** single-step actions, questions/explanations, `/btw` side questions, or trivial fixes.
+
+---
+
+## Task Granularity
+
+Tasks MUST be **detailed and specific** — not high-level summaries.
+
+- ❌ BAD: `Implement the fix` / `Review code` / `Create PR`
+- ✅ GOOD: `Edit extensions/orchestrator/utils.ts — add timeout parameter to fetchData()` / `Run code review loop (3 async reviewers)` / `Create PR with description`
+
+---
+
+## Task Lifecycle (MANDATORY)
+
+Create all tasks BEFORE starting work via `TaskCreate`.
+Mark each `in_progress` before starting and `completed` immediately after finishing via `TaskUpdate`.
+Work through tasks in order — do not skip tasks or start new work while unchecked tasks exist (unless user explicitly pivots).
+
+---
+
+## Side Questions
+
+Answer the question, then resume the next unchecked task immediately — the persistent task list tells you exactly where you left off.
+
+---
+
+## Integration & Key Rules
+
+Task tracking works alongside existing workflow rules — include issue-first, code review, and documentation steps as individual tasks.
+Tasks are code-enforced (reminders after 4+ ignored turns).
+Never abandon tasks — if scope changes, use `TaskUpdate` with `status: "deleted"` to remove obsolete tasks; the task list is your contract.
+
+---
+
+## Async Agent taskId (MANDATORY — code-enforced)
+
+**Every async agent call MUST include `taskId`.** Enforced — calls without it are rejected.
+Pass the task ID (e.g., `"5"`) when linked to a task, or `"-1"` when not.
+Linked tasks auto-complete on agent success — no manual `TaskUpdate` needed.
+
+```text
+subagent(agent="code-reviewer-quality", task="...", cwd="...", async=true, name="Review", taskId="5")
+subagent(agent="worker", task="...", cwd="...", async=true, name="Qodo Poll", taskId="-1")
+```
+
+- ✅ **ALWAYS** pass `taskId` — auto-completes on success, stays `in_progress` on failure
+- ❌ **NEVER** manually `TaskUpdate` a task to `completed` if it has an async agent
+- ❌ **NEVER** omit `taskId` — the call will fail