chore: sync main into develop after v2.9.2 release

.github/public-sync-allowlist.txt

@@ -1,19 +1,31 @@
-# Canonical public release subset contract (single-repo model).
-# Paths are relative to repository root.
+  # Canonical public release subset contract (single-repo
+  model).
+  # Paths are relative to repository root.
 
-README.md
-CHANGELOG.md
-VERSION
-LICENSE
-CONTRIBUTING.md
-tm
+  README.md
+  CHANGELOG.md
+  VERSION
+  LICENSE
+  CONTRIBUTING.md
+  tm
 
-docs/guides/user-guide.md
-docs/guides/developer-guide.md
-docs/guides/ai-agent-discovery-protocol.md
-docs/guides/troubleshooting.md
-docs/guides/quickstart-claude-code.md
+  docs/guides/user-guide.md
+  docs/guides/developer-guide.md
+  docs/guides/ai-agent-discovery-protocol.md
+  docs/guides/agent-instruction-snippets.md
+  docs/guides/agent-skill-installation.md
+  docs/guides/troubleshooting.md
+  docs/guides/quickstart-claude-code.md
 
-docs/reference/api-reference.md
+  docs/reference/api-reference.md
 
-deploy/CLAUDE_CODE_WHITELIST.md
+  deploy/CLAUDE_CODE_WHITELIST.md
+
+  skills/task-orchestrator/SKILL.md
+  skills/task-orchestrator/scripts/verify-tm.sh
+  skills/task-orchestrator/references/REFERENCE.md
+  EOF
+
+
+
+quit

CHANGELOG.md

@@ -1,3 +1,11 @@
+## [2.9.2] - 2026-03-02
+
+- Release preparation for v2.9.2.
+
+## [2.9.1] - 2026-03-01
+
+- Release preparation for v2.9.1.
+
 # Changelog
 
 All notable changes to the Task Orchestrator project will be documented in this file.

README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
-[![Version](https://img.shields.io/badge/version-2.9.0-blue.svg)](https://github.com/T72/task-orchestrator/releases)
+[![Version](https://img.shields.io/badge/version-2.9.2-blue.svg)](https://github.com/T72/task-orchestrator/releases)
 
 ## 🎯 Transform Your Meta-Agent Into An Orchestration Engine
 
@@ -42,21 +42,26 @@ Every task delegation includes THREE elements:
 ## ⚡ Quick Start (60 Seconds)
 
 ```bash
-# 1. Setup
-git clone https://github.com/T72/task-orchestrator.git
-cd task-orchestrator
+# 1. In YOUR project root
+cd /path/to/your-project
+
+# 2. Add tm from a release artifact or local install
+cp /path/to/task-orchestrator/tm ./tm
+chmod +x ./tm
+
+# 3. Initialize Task Orchestrator in this project
 ./tm init
 
-# 2. Set agent identity (required for coordination)
+# 4. Set agent identity (required for coordination)
 export TM_AGENT_ID="orchestrator_agent"
 
-# 3. Create AI Agent Workflow with Commander's Intent
+# 5. Create AI Agent Workflow with Commander's Intent
 BACKEND=$(./tm add "Build auth API" --assignee backend_agent \
   -d "WHY: Secure foundation, WHAT: OAuth2/JWT/sessions, DONE: Users can login safely" | grep -o '[a-f0-9]\{8\}')
 
 FRONTEND=$(./tm add "Create login UI" --assignee frontend_agent --depends-on $BACKEND | grep -o '[a-f0-9]\{8\}')
 
-# 4. Watch Real-Time Orchestration
+# 6. Watch Real-Time Orchestration
 ./tm watch  # See instant updates as agents work
 
 # When backend completes, frontend auto-unblocks!
@@ -104,6 +109,9 @@ export TM_AGENT_ID="your_agent_name"
 - **[Developer Guide](docs/guides/developer-guide.md)** - Architecture and contribution guide
 - **[API Reference](docs/reference/api-reference.md)** - Complete technical documentation
 - **[AI Agent Discovery](docs/guides/ai-agent-discovery-protocol.md)** - How agents automatically find and use Task Orchestrator
+- **[Agent Instruction Snippets](docs/guides/agent-instruction-snippets.md)** - Copy/paste blocks for `AGENTS.md` and `CLAUDE.md`
+- **[Official Agent Skill](skills/task-orchestrator/SKILL.md)** - Installable Agent Skills package for Codex/Claude Code style tools
+- **[Agent Skill Install Guide](docs/guides/agent-skill-installation.md)** - How to install/use the packaged skill from repo or release artifacts
 - **[Troubleshooting](docs/guides/troubleshooting.md)** - Solutions to common issues
 - **[Claude Code Integration](docs/guides/quickstart-claude-code.md)** - **REQUIRED** for Claude Code users
 
@@ -118,7 +126,15 @@ python3 docs/examples/multi_agent_workflow.py  # Team coordination
 ## 🚀 Installation
 
 ```bash
-# Requirements: Python 3.8+, 10MB disk space
+# Use in your own project
+cd /path/to/your-project
+cp /path/to/task-orchestrator/tm ./tm
+chmod +x ./tm
+./tm init
+```
+
+```bash
+# Contributor path (develop task-orchestrator itself)
 git clone https://github.com/T72/task-orchestrator.git
 cd task-orchestrator
 ./tm init
@@ -148,4 +164,4 @@ export TM_AGENT_ID="orchestrator_agent"
 
 ---
 
-**Task Orchestrator v2.9.0** - Transform your meta-agent into an orchestration engine.
+**Task Orchestrator v2.9.2** - Transform your meta-agent into an orchestration engine.

VERSION

@@ -1 +1 @@
-2.9.0
+2.9.2

docs/guides/agent-instruction-snippets.md

@@ -0,0 +1,54 @@
+# AI Agent Instruction Snippets
+
+Use these snippets to make AI coding agents consistently discover and use Task Orchestrator in your project.
+
+## Option 1: AGENTS.md snippet
+
+```markdown
+## Task Orchestrator
+
+This project uses Task Orchestrator for multi-agent coordination.
+
+Before starting work:
+1. Run `./tm list` to get fresh task state from the database.
+2. Check `ORCHESTRATOR.md` for discovery guidance and command patterns.
+3. Set identity when coordinating work:
+   - `export TM_AGENT_ID="your_agent_name"`
+
+When delegating:
+- Use Commander's Intent in task descriptions:
+  - `WHY`: purpose
+  - `WHAT`: deliverables
+  - `DONE`: success criteria
+
+Example:
+`./tm add "Implement auth API" --assignee backend_agent -d "WHY: secure user access, WHAT: login/token/session endpoints, DONE: users can authenticate successfully"`
+```
+
+## Option 2: CLAUDE.md snippet
+
+```markdown
+## REQUIRED: Task Orchestrator Workflow
+
+If `./tm` and `ORCHESTRATOR.md` are present, use Task Orchestrator as the source of truth for task coordination.
+
+Required startup flow:
+1. `./tm list`
+2. `./tm list --assignee $TM_AGENT_ID` (when identity is configured)
+3. Use `ORCHESTRATOR.md` for usage patterns, not for live task state.
+
+Required task lifecycle:
+- Create: `./tm add ... --assignee ...`
+- Progress: `./tm progress TASK_ID "..."`
+- Share context: `./tm share TASK_ID "..."`
+- Complete: `./tm complete TASK_ID`
+
+Do not treat `ORCHESTRATOR.md` as a live task board.
+Live state is always retrieved via `./tm list`.
+```
+
+## Notes
+
+- `ORCHESTRATOR.md` is a static discovery and protocol file.
+- Runtime task status is always stored in Task Orchestrator data and queried via CLI commands.
+- Keep snippets short and project-specific if you have custom agent roles.

docs/guides/agent-skill-installation.md

@@ -0,0 +1,44 @@
+# Install the Task Orchestrator Agent Skill
+
+This repository ships an official Agent Skills-compatible package at:
+
+- `skills/task-orchestrator/`
+
+## Option 1: Use directly from this repository
+
+Point your skills-enabled agent tooling to:
+
+- `skills/task-orchestrator/SKILL.md`
+
+If your tooling expects a copied skill directory, copy the whole folder:
+
+```bash
+cp -r skills/task-orchestrator /path/to/your-agent-skills/
+```
+
+## Option 2: Use from public release artifact
+
+When using a `public-releases/<version>/release-package.*` artifact, extract it and copy:
+
+```bash
+cp -r skills/task-orchestrator /path/to/your-agent-skills/
+```
+
+## Quick validation
+
+From a project root that contains `./tm`:
+
+```bash
+export TM_AGENT_ID="orchestrator_agent"
+bash skills/task-orchestrator/scripts/verify-tm.sh --json
+```
+
+Expected result includes:
+
+- `"ok":true`
+- `"exit_code":0`
+
+## Notes
+
+- `ORCHESTRATOR.md` is a static discovery/protocol file.
+- Live task state is always queried using `./tm list`.

docs/guides/ai-agent-discovery-protocol.md

@@ -16,7 +16,7 @@ Task Orchestrator implements automatic discovery through the **ORCHESTRATOR.md P
 ### How It Works
 
 1. **Automatic Generation**: When you run `./tm init`, Task Orchestrator creates `ORCHESTRATOR.md` in your project root
-2. **Live Updates**: The file auto-updates whenever tasks change, showing current status
+2. **Static Discovery Contract**: The file is a stable protocol guide, not a live task board
 3. **AI-Optimized Format**: Written specifically for AI agents to understand and use
 4. **Universal Discovery**: Works with Claude Code, GitHub Copilot, Cursor, and any AI tool
 
@@ -25,8 +25,8 @@ Task Orchestrator implements automatic discovery through the **ORCHESTRATOR.md P
 ```markdown
 # 🤖 AI Agent Orchestration Protocol
 
-## 📋 Current Task Status
-[Auto-updated list of current tasks with status]
+## 📋 Runtime Task Status
+[Retrieved live via `./tm list` from Task Orchestrator data]
 
 ## 🚀 Quick Start for AI Agents
 [Essential commands and patterns]
@@ -50,28 +50,28 @@ class OrchestratorDiscovery:
         # Creates ORCHESTRATOR.md from template
 
     def update_orchestrator_md(self) -> bool
-        # Updates task status section with current data
+        # Compatibility hook: ensure file exists if missing
 
     def add_readme_section(self) -> bool
         # Optionally adds discovery hint to README.md
 ```
 
-### Auto-Update Triggers
+### Runtime Source of Truth
 
-ORCHESTRATOR.md updates automatically when:
-- Tasks are created (`tm add`)
-- Tasks are completed (`tm complete`)
-- Task status changes (`tm update`)
-- Dependencies are resolved
-- Progress is updated
+Task status is not persisted in `ORCHESTRATOR.md`.
+
+Live state is always queried from Task Orchestrator data via:
+- `./tm list`
+- `./tm list --format json`
+- `./tm list --assignee <agent>`
 
 ### Template System
 
 The protocol uses a template at `templates/ORCHESTRATOR.md.template` that includes:
 - Quick reference commands
 - Multi-agent coordination patterns
 - Best practices for AI agents
-- Real-time task status placeholders
+- Runtime status retrieval commands
 
 ## Benefits for AI Agents
 
@@ -82,11 +82,10 @@ AI agents can check for ORCHESTRATOR.md existence:
 ```
 
 ### 2. Current Context
-The file always shows the current state:
-- Tasks in progress
-- Blocked tasks waiting for dependencies
-- Recently completed work
-- Pending assignments
+The file points agents to current-state commands:
+- `./tm list`
+- `./tm list --format json`
+- `./tm show TASK_ID`
 
 ### 3. Ready-to-Use Examples
 Each pattern includes working code:
@@ -113,11 +112,11 @@ Tailored guidance for different agent types:
        use_task_orchestrator()
    ```
 
-2. **Read Current Status**
+2. **Read Discovery Contract**
    ```python
    with open("ORCHESTRATOR.md") as f:
        content = f.read()
-       # Parse current tasks and status
+       # Parse orchestration protocol and command patterns
    ```
 
 3. **Follow Patterns**
@@ -160,12 +159,12 @@ You can customize the ORCHESTRATOR.md template:
 2. Add project-specific patterns
 3. Include custom agent instructions
 
-### Update Frequency
+### Status Retrieval Frequency
 
-By default, updates occur after task operations. Adjust in `tm`:
-```python
-# Update after these commands
-UPDATE_TRIGGERS = ["add", "complete", "update", "progress"]
+Agents should retrieve runtime state directly whenever needed:
+```bash
+./tm list
+./tm list --format json
 ```
 
 ## Integration with AI Tools
@@ -194,8 +193,8 @@ def discover_orchestration():
 
 ## Best Practices
 
-### 1. Keep It Updated
-The auto-update mechanism ensures freshness, but you can manually trigger:
+### 1. Keep It Regenerated
+Regenerate from template when needed:
 ```bash
 ./tm init  # Regenerates ORCHESTRATOR.md
 ```
@@ -238,21 +237,21 @@ When starting a session, remind agents:
    TM_VERBOSE=1 ./tm init  # Enable verbose output
    ```
 
-### Updates Not Happening
+### Task Status Seems Stale
 
-1. Verify update triggers are working:
+1. Query runtime state directly:
    ```bash
-   ./tm add "Test task"  # Should update ORCHESTRATOR.md
+   ./tm list
    ```
 
-2. Check modification time:
+2. Use machine-readable output when parsing:
    ```bash
-   ls -la ORCHESTRATOR.md  # Check last modified
+   ./tm list --format json
    ```
 
-3. Enable verbose mode for debugging:
+3. Regenerate discovery file if missing/corrupt:
    ```bash
-   export TM_VERBOSE=1
+   ./tm init
    ```
 
 ### Agents Not Discovering
@@ -288,7 +287,7 @@ We welcome improvements to the discovery protocol:
 The ORCHESTRATOR.md Protocol transforms Task Orchestrator from a tool you have to remember to use into one that AI agents discover and use automatically. This creates a self-organizing ecosystem where:
 
 - **Discovery is automatic** - No manual configuration needed
-- **Context is always current** - Live updates keep agents informed
+- **Context retrieval is deterministic** - Live status always comes from task data
 - **Patterns guide usage** - Ready-to-use examples ensure correct implementation
 - **Coordination is seamless** - Agents naturally work together