PlannerAgentSkills

A Copilot CLI skill for managing Microsoft Planner tasks through natural language conversations.

Say things like:

• "update task Add OKR view in progress"
• "create an urgent task: Fix login bug, due March 20"
• "what tasks are in progress?"
• "assign the API refactoring task to John"

Architecture

PlannerAgentSkills/
├── SKILL.md                        ← Skill definition (loaded by Copilot CLI)
├── patterns/                       ← NL→CLI mapping & Planner domain docs
├── examples/                       ← Example conversation flows
├── cli/                            ← TypeScript CLI tool
│   ├── src/
│   │   ├── index.ts               ← Entry point (commander-based)
│   │   ├── graph-client.ts        ← Microsoft Graph API auth
│   │   ├── planner-service.ts     ← Planner CRUD operations
│   │   ├── commands/              ← CLI subcommands
│   │   └── utils/                 ← Output formatting & config
│   └── __tests__/                 ← Unit tests
├── setup/
│   ├── setup-entra-app.ps1        ← Auto-create Entra ID app registration
│   └── verify-auth.ts             ← Verify Graph API connectivity
└── README.md

Quick Start

1. Set Up Azure App Registration

Run the automated setup script (requires Azure CLI):

cd setup
.\setup-entra-app.ps1

This creates an Entra ID app registration with the required permissions:

• Group.Read.All — List groups/teams
• Tasks.ReadWrite.All — Full Planner task CRUD
• User.Read.All — List users for assignment

It writes the credentials to cli/.env automatically.

2. Install CLI Dependencies

cd cli
npm install

3. Configure (if not using setup script)

Copy and edit the environment file:

cp .env.example .env
# Edit .env with your CLIENT_ID, TENANT_ID, CLIENT_SECRET

Optionally set default GROUP_ID and PLAN_ID to avoid passing them every time.

4. Verify Connectivity

npx tsx ../setup/verify-auth.ts

5. Use the CLI

# List tasks
npx tsx src/index.ts tasks list --plan-id <your-plan-id>

# Search tasks
npx tsx src/index.ts tasks search "OKR"

# Create a task
npx tsx src/index.ts tasks create --title "Fix login bug" --priority urgent --due 2025-04-01

# Update task status
npx tsx src/index.ts tasks update <taskId> --progress "in progress"

# Complete a task
npx tsx src/index.ts tasks complete <taskId>

# List users (for assignment)
npx tsx src/index.ts users list --search "John"

# List groups, plans, buckets
npx tsx src/index.ts groups list
npx tsx src/index.ts plans list --group-id <groupId>
npx tsx src/index.ts buckets list --plan-id <planId>

Using as a Copilot CLI Skill

1. Register this directory as a skill in your Copilot CLI configuration
2. The SKILL.md file defines when and how the skill activates
3. When you say something like "update task X in progress", the agent will:
   • Search for the task by name
   • Map your intent to the appropriate CLI command
   • Execute the command and report the result

Running Tests

cd cli
npm test              # Run once
npm run test:watch    # Watch mode
npm run test:coverage # With coverage

CLI Command Reference

Command	Description
tasks list	List all tasks in a plan
tasks search <query>	Search tasks by title
tasks get <taskId>	Get task details
tasks create --title <text>	Create a new task
tasks update <taskId>	Update a task
tasks complete <taskId>	Mark task as complete
tasks delete <taskId>	Delete a task
groups list	List Microsoft 365 groups
plans list	List plans in a group
plans get <planId>	Get plan details
buckets list	List buckets in a plan
categories list	List category labels
users list	List/search users

All commands support --format json (default) or --format table.

License

MIT