Skip to content

Commit b1db2c0

Browse files
T72T72
committed
feat(skills): ship official task-orchestrator skill package
1 parent 7a7967c commit b1db2c0

6 files changed

Lines changed: 240 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,8 @@ export TM_AGENT_ID="your_agent_name"
110110
- **[API Reference](docs/reference/api-reference.md)** - Complete technical documentation
111111
- **[AI Agent Discovery](docs/guides/ai-agent-discovery-protocol.md)** - How agents automatically find and use Task Orchestrator
112112
- **[Agent Instruction Snippets](docs/guides/agent-instruction-snippets.md)** - Copy/paste blocks for `AGENTS.md` and `CLAUDE.md`
113+
- **[Official Agent Skill](skills/task-orchestrator/SKILL.md)** - Installable Agent Skills package for Codex/Claude Code style tools
114+
- **[Agent Skill Install Guide](docs/guides/agent-skill-installation.md)** - How to install/use the packaged skill from repo or release artifacts
113115
- **[Troubleshooting](docs/guides/troubleshooting.md)** - Solutions to common issues
114116
- **[Claude Code Integration](docs/guides/quickstart-claude-code.md)** - **REQUIRED** for Claude Code users
115117

‎docs/guides/agent-skill-installation.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Install the Task Orchestrator Agent Skill
2+
3+
This repository ships an official Agent Skills-compatible package at:
4+
5+
- `skills/task-orchestrator/`
6+
7+
## Option 1: Use directly from this repository
8+
9+
Point your skills-enabled agent tooling to:
10+
11+
- `skills/task-orchestrator/SKILL.md`
12+
13+
If your tooling expects a copied skill directory, copy the whole folder:
14+
15+
```bash
16+
cp -r skills/task-orchestrator /path/to/your-agent-skills/
17+
```
18+
19+
## Option 2: Use from public release artifact
20+
21+
When using a `public-releases/<version>/release-package.*` artifact, extract it and copy:
22+
23+
```bash
24+
cp -r skills/task-orchestrator /path/to/your-agent-skills/
25+
```
26+
27+
## Quick validation
28+
29+
From a project root that contains `./tm`:
30+
31+
```bash
32+
export TM_AGENT_ID="orchestrator_agent"
33+
bash skills/task-orchestrator/scripts/verify-tm.sh --json
34+
```
35+
36+
Expected result includes:
37+
38+
- `"ok":true`
39+
- `"exit_code":0`
40+
41+
## Notes
42+
43+
- `ORCHESTRATOR.md` is a static discovery/protocol file.
44+
- Live task state is always queried using `./tm list`.

‎release/public-manifest.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,14 @@ include_paths:
66
- docs/reference
77
- docs/releases
88
- templates
9+
- skills/task-orchestrator
910
- README.md
1011
- LICENSE
1112
- CHANGELOG.md
1213
- CONTRIBUTING.md
1314
- VERSION
1415
- tm
16+
- skills/task-orchestrator/SKILL.md
1517

1618
exclude_globs:
1719
- "**/.claude/**"

‎skills/task-orchestrator/SKILL.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
name: task-orchestrator
3+
description: Coordinate multi-agent software execution with Task Orchestrator using commander intent, dependency chains, and live status commands. Use when an agent must break down work, assign tasks, track progress, or unblock dependent work with tm.
4+
license: MIT
5+
compatibility: Designed for filesystem-based coding agents (Codex, Claude Code, similar tools). Requires shell access, Python 3.8+, and executable tm in the project root.
6+
metadata:
7+
author: T72
8+
version: "1.0"
9+
---
10+
11+
# task-orchestrator skill
12+
13+
Use this skill when the user needs reliable agent coordination with `tm`.
14+
15+
## Activation cues
16+
17+
Activate this skill when requests involve:
18+
19+
- delegating to multiple agents
20+
- sequencing dependent tasks
21+
- sharing context between assignees
22+
- tracking progress or blocked work
23+
- orchestrating a delivery pipeline
24+
25+
## Prerequisites
26+
27+
1. `tm` exists in the current project root.
28+
2. The project has been initialized with `./tm init`.
29+
3. `TM_AGENT_ID` is set for the current agent session.
30+
31+
## Startup protocol (always)
32+
33+
```bash
34+
./tm list
35+
./tm list --format json
36+
```
37+
38+
Do not treat `ORCHESTRATOR.md` as live runtime state. It is a static discovery contract.
39+
40+
## Standard workflow
41+
42+
1. Set identity:
43+
```bash
44+
export TM_AGENT_ID="orchestrator_agent"
45+
```
46+
2. Create tasks with Commander's Intent:
47+
```bash
48+
./tm add "Implement auth API" --assignee backend_agent \
49+
-d "WHY: secure user access, WHAT: login/token/session endpoints, DONE: users can authenticate successfully"
50+
```
51+
3. Add dependencies:
52+
```bash
53+
./tm add "Create login UI" --assignee frontend_agent --depends-on <backend_task_id>
54+
```
55+
4. Share handoff context:
56+
```bash
57+
./tm share <task_id> "API contract: POST /auth/login, POST /auth/refresh"
58+
```
59+
5. Track progress:
60+
```bash
61+
./tm progress <task_id> "Implemented token issuance and refresh validation"
62+
```
63+
6. Complete to trigger unblocking:
64+
```bash
65+
./tm complete <task_id>
66+
```
67+
68+
## Coordination rules
69+
70+
- Query state with `./tm list` before creating or updating tasks.
71+
- Include `WHY`, `WHAT`, and `DONE` in all substantive delegated tasks.
72+
- Use `./tm share` for cross-agent information, not private notes.
73+
- Use `./tm note` only for private reasoning.
74+
- Keep commands non-interactive and deterministic.
75+
76+
## Safety and quality
77+
78+
- Avoid destructive operations unless explicitly requested.
79+
- If task state conflicts with assumptions, re-query `./tm list --format json`.
80+
- For release-related orchestration, run from release source branch policy (`main` unless overridden by process).
81+
82+
## Available resources
83+
84+
- Runtime checks: `scripts/verify-tm.sh`
85+
- Extended reference: `references/REFERENCE.md`
86+

‎skills/task-orchestrator/references/REFERENCE.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Task Orchestrator Skill Reference
2+
3+
## Intent format
4+
5+
Use this compact intent format for delegated work:
6+
7+
- `WHY`: business or engineering purpose
8+
- `WHAT`: concrete deliverables
9+
- `DONE`: measurable acceptance criteria
10+
11+
Example:
12+
13+
```bash
14+
./tm add "Add audit logging" --assignee backend_agent \
15+
-d "WHY: compliance and incident traceability, WHAT: structured auth event logs, DONE: all auth actions are logged and queryable"
16+
```
17+
18+
## Coordination patterns
19+
20+
### Sequential pipeline
21+
22+
```bash
23+
DESIGN=$(./tm add "Design storage schema" --assignee architect_agent | grep -o '[a-f0-9]\{8\}')
24+
API=$(./tm add "Implement API endpoints" --assignee backend_agent --depends-on "$DESIGN" | grep -o '[a-f0-9]\{8\}')
25+
UI=$(./tm add "Implement settings UI" --assignee frontend_agent --depends-on "$API" | grep -o '[a-f0-9]\{8\}')
26+
```
27+
28+
### Parallel specialists
29+
30+
```bash
31+
EPIC=$(./tm add "Release authentication feature" --assignee orchestrator_agent | grep -o '[a-f0-9]\{8\}')
32+
./tm add "Backend implementation" --assignee backend_agent --depends-on "$EPIC"
33+
./tm add "Frontend implementation" --assignee frontend_agent --depends-on "$EPIC"
34+
./tm add "Security test plan" --assignee qa_agent --depends-on "$EPIC"
35+
```
36+
37+
## Operational commands
38+
39+
- Current board: `./tm list`
40+
- Current board (machine-readable): `./tm list --format json`
41+
- Single task details: `./tm show <task_id>`
42+
- Live event feed: `./tm watch`
43+
44+
## Troubleshooting quick checks
45+
46+
1. Run `scripts/verify-tm.sh --json`.
47+
2. Confirm `./tm list` returns state.
48+
3. If blocked tasks remain, inspect dependencies with `./tm show <task_id>`.

‎skills/task-orchestrator/scripts/verify-tm.sh‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
show_help() {
5+
cat <<'EOF'
6+
Usage: scripts/verify-tm.sh [--json]
7+
8+
Validate Task Orchestrator skill prerequisites in the current project.
9+
10+
Options:
11+
--json Print machine-readable JSON result to stdout
12+
--help Show this help
13+
14+
Exit codes:
15+
0 All checks passed
16+
2 tm executable missing
17+
3 task orchestrator not initialized (.task-orchestrator missing)
18+
4 TM_AGENT_ID not set
19+
EOF
20+
}
21+
22+
emit_json() {
23+
local ok="$1"
24+
local code="$2"
25+
local message="$3"
26+
printf '{"ok":%s,"exit_code":%s,"message":"%s"}\n' "$ok" "$code" "$message"
27+
}
28+
29+
json_mode=0
30+
case "${1:-}" in
31+
--help|-h) show_help; exit 0 ;;
32+
--json) json_mode=1 ;;
33+
"") ;;
34+
*) echo "Error: unknown argument '$1'. Use --help." >&2; exit 1 ;;
35+
esac
36+
37+
if [[ ! -x "./tm" ]]; then
38+
msg="tm executable not found in current directory. Expected ./tm"
39+
if [[ "$json_mode" -eq 1 ]]; then emit_json false 2 "$msg"; else echo "$msg" >&2; fi
40+
exit 2
41+
fi
42+
43+
if [[ ! -d ".task-orchestrator" ]]; then
44+
msg="Task Orchestrator not initialized. Run ./tm init"
45+
if [[ "$json_mode" -eq 1 ]]; then emit_json false 3 "$msg"; else echo "$msg" >&2; fi
46+
exit 3
47+
fi
48+
49+
if [[ -z "${TM_AGENT_ID:-}" ]]; then
50+
msg="TM_AGENT_ID is not set. Export TM_AGENT_ID before orchestrating"
51+
if [[ "$json_mode" -eq 1 ]]; then emit_json false 4 "$msg"; else echo "$msg" >&2; fi
52+
exit 4
53+
fi
54+
55+
msg="Task Orchestrator skill prerequisites satisfied"
56+
if [[ "$json_mode" -eq 1 ]]; then emit_json true 0 "$msg"; else echo "$msg"; fi
57+
exit 0
58+

0 commit comments

Comments
 (0)