Skip to content

Commit 4649321

Browse files
goodguy1963goodguy1963
committed
feat: add cockpit-scheduler-router and cockpit-todo-agent skills
- Introduced `cockpit-scheduler-router` skill for routing and dispatching Cockpit Todo cards, including detailed rules for card management and scheduling. - Added `cockpit-todo-agent` skill to manage internal Cockpit board interactions, emphasizing the distinction between Cockpit cards and scheduled tasks. - Created introductory and setup skills (`copilot-scheduler-intro` and `copilot-scheduler-setup`) to assist users in understanding and integrating the scheduler plugin. - Implemented skill metadata handling in `skillMetadata.ts` to parse and validate skill documentation. - Added tests for skill metadata contract to ensure compliance with expected structures and behaviors.
1 parent bac24e2 commit 4649321

25 files changed

Lines changed: 1336 additions & 47 deletions

‎.github/skills/cockpit-scheduler-agent/SKILL.md‎

Lines changed: 290 additions & 0 deletions
Large diffs are not rendered by default.

‎.github/skills/cockpit-scheduler-router/SKILL.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
name: cockpit-scheduler-router
3+
description: "Use when an agent needs to route and dispatch Cockpit Todo cards from the workspace-local Cockpit store, including sqlite mode with compatibility mirrors."
4+
copilotCockpitSkillType: operational
5+
copilotCockpitToolNamespaces: [cockpit, scheduler]
6+
copilotCockpitWorkflowIntents: [needs-bot-review, ready]
7+
copilotCockpitApprovalSensitive: true
8+
copilotCockpitPromptSummary: "Route through canonical workflow flags, preserve approval checkpoints, and verify linked scheduler state before changing live scheduled cards."
9+
copilotCockpitReadyWorkflowFlags: [ready, ON-SCHEDULE-LIST]
10+
copilotCockpitCloseoutWorkflowFlags: [needs-user-review, FINAL-USER-CHECK]
11+
---
12+
13+
# Cockpit Scheduler Router Skill
14+
15+
Use this skill when a dispatcher should inspect Cockpit cards and decide whether to schedule, reject, or ask for clarification.
16+
17+
When `copilotCockpit.storageMode` is `sqlite`, treat the workspace Cockpit store as SQLite-primary with `.vscode/scheduler.private.json` kept as a compatibility mirror. MCP tool behavior stays the same.
18+
19+
## Core Rule
20+
21+
Cockpit routing state is not a single label bucket.
22+
23+
- `labels` are multi-value user categorization tags.
24+
- `flags` carry the live workflow state for active cards.
25+
- `comments[].labels` are comment metadata, not routing signals.
26+
- Legacy `GO` is normalized to the built-in `ready` flag.
27+
- `scheduled-task` is a label in this repo, not a flag.
28+
- Do not collapse `ON-SCHEDULE-LIST` into a label or a comment-only signal.
29+
30+
## Mandatory MCP Capability Gate
31+
32+
This router skill is MCP-dependent. It must not attempt live routing or scheduler/card mutation without the required Cockpit and scheduler tool surfaces.
33+
34+
- If the current agent cannot access the required `cockpit_` and `scheduler_` MCP tools, do not try to emulate routing by editing repo-local JSON files, inventing state transitions, or claiming dispatch succeeded.
35+
- First prefer a handoff or subagent path only when the destination agent actually has the required MCP tools and can perform the intended mutation.
36+
- Do not send live routing work to a read-only exploration agent or any agent that still lacks the required MCP tools.
37+
- If no MCP-capable handoff target is available, stop and tell the user that the current agent cannot fulfill the routing task until they switch to an MCP-enabled agent or grant the necessary tool permissions.
38+
- Only continue in analysis-only mode when the user explicitly wants a review, diagnosis, or plan instead of live Cockpit/scheduler updates.
39+
40+
## Recommended Read Flow
41+
42+
1. Call `cockpit_list_routing_cards` first.
43+
2. Use the returned `latestActionableUserComment` for intent and cron overrides.
44+
3. If you need full card context, call `cockpit_get_todo` for only the matching cards.
45+
46+
## Routing Semantics
47+
48+
- Match routing signals case-insensitively.
49+
- Treat `new`, `needs-bot-review`, `needs-user-review`, `ready`, `ON-SCHEDULE-LIST`, and `FINAL-USER-CHECK` as the canonical routing signals. Legacy `go` normalizes to `ready`.
50+
- Ignore non-actionable comments such as `Scheduled as ...`, `Done`, label-maintenance notes, dispatcher status comments, and scheduler status comments.
51+
- Sort comments newest-first by sequence, then by created time if needed.
52+
53+
## Action Policy
54+
55+
- `FINAL-USER-CHECK` → finalize/archive the card only when the implementation is actually accepted.
56+
- `needs-bot-review` → plan-only handling with exactly one clarification or two implementation options, depending on clarity.
57+
- `ready` → create or reuse the linked scheduler task only when the latest actionable user comment is specific enough.
58+
- `ON-SCHEDULE-LIST` → manage the linked scheduler job lifecycle for live scheduled cards.
59+
- `needs-user-review` or `new` → keep the card active and route it for follow-up instead of scheduling immediately.
60+
61+
## Rule Block: Workflow Outcomes
62+
63+
- `ON-SCHEDULE-LIST` + completed implementation:
64+
- remove the scheduler job if it exists
65+
- clear stale `taskId` when the linked task is gone
66+
- replace the scheduled-card workflow flag with `needs-user-review` or `FINAL-USER-CHECK`, depending on the requested handoff
67+
- `ON-SCHEDULE-LIST` + incomplete implementation:
68+
- verify the linked task by `taskId` first
69+
- keep and reuse the existing scheduler task when it still exists and still matches intent
70+
- recreate it only if the linked task is missing or stale and the card is still valid for scheduling
71+
- `ready`:
72+
- if intent is concrete, first check whether a linked `taskId` already points to a live scheduler task that matches intent, and reuse or update that task instead of creating a duplicate
73+
- only create a new scheduler task when the linked `taskId` is missing or stale
74+
- then swap `ready` for `ON-SCHEDULE-LIST` and add the schedule comment
75+
- if intent is vague, request clarification and add `needs-user-review`
76+
77+
## Rule Block: `needs-bot-review` Ambiguity Handling
78+
79+
The current live dispatcher source contains two different `needs-bot-review` behaviors: one scheduling-oriented and one plan/comment-oriented.
80+
81+
- Do not silently collapse those branches during support-only extraction.
82+
- Require the caller to choose `needs_review_mode`, or use `mirror-live-source` when the goal is documentation rather than mutation.
83+
- If the branch remains ambiguous during a live review, document the ambiguity and avoid repointing behavior in the same task.
84+
85+
## Rule Block: Scheduler Creation
86+
87+
- Prefer create-scheduler-first ordering so label changes do not outpace scheduler creation.
88+
- Preserve and reuse an existing linked `taskId` before any create path when the linked scheduler task still exists and still matches intent.
89+
- For `ready` cards, check `taskId` first and only create a new scheduler task when the link is missing or stale.
90+
- For `ON-SCHEDULE-LIST` incomplete cards, verify the linked task by `taskId` before recreating anything.
91+
- Use idempotent behavior:
92+
- no duplicate scheduler jobs
93+
- no duplicate comments
94+
- no duplicate labels
95+
- Derive cron from the latest actionable user comment when it includes `Cron: ...`.
96+
- Otherwise select the next available scheduling slot.
97+
- Allow the same 30-minute bucket for clearly disjoint tasks.
98+
- Require a 30-minute gap only when the new task and an existing scheduled task could plausibly overlap in touched files, components, or feature area, or when overlap is uncertain.
99+
- Base the overlap check on the card title, description, latest actionable user comment, and the existing scheduled task prompt or summary when available.
100+
- Preserve the current live execution defaults unless the caller explicitly overrides them.
101+
102+
## Rule Block: Delete Tombstones
103+
104+
- When a scheduler task is deleted, treat `deletedTaskIds` or scheduler tombstones as authoritative so stale reads or stale writes do not resurrect the task.
105+
- When a Cockpit todo is purged, treat `deletedCardIds` or cockpit card tombstones as authoritative so stale board writes do not recreate the card.
106+
- Clear stale `taskId` links instead of leaving a card pointed at a deleted scheduler task.
107+
- Do not recommend recreate-on-refresh behavior for deleted tasks or purged todos unless the caller explicitly asks to recreate them.
108+
- If a task or todo was intentionally deleted, the router should prefer documenting the tombstone-preserving state over trying to restore it.
109+
110+
## Closeout Discipline
111+
112+
- Do not treat comment text such as `Scheduled as ...` as proof that the linked scheduler task still exists. Use scheduler MCP tools to confirm the real task state.
113+
- Prefer `cockpit_closeout_todo` for final execution handoff so the comment, review-state update, requested section move, and stale task-link cleanup happen in one deterministic write.
114+
- If `scheduler_remove_task` or `scheduler_get_task` shows that the linked task is already gone, clear the Cockpit card's `taskId` instead of leaving a stale link behind.
115+
- Use flags for routing and review-state handoff. Keep the built-in `ON-SCHEDULE-LIST` flag when the card still represents a live scheduled item.
116+
- When implementation is complete but the user still needs to review the result, prefer an existing review-state flag such as `needs-user-review`, and move the card only if the requested review section actually exists.
117+
- Add one compact Cockpit comment that covers changes, validation, and remaining follow-up instead of scattering multiple status comments.
118+
119+
## Suggested Update Format
120+
121+
When you propose a deterministic card update, keep flags and labels separate in the wording.
122+
123+
- Use `Set flag to:` when the live state intentionally keeps `ON-SCHEDULE-LIST` on the card.
124+
- Use `Set flag to:` for a single review-state flag when no paired scheduling state is needed.
125+
- Use `Add label:` or `Add labels:` for multi-value categorization such as `scheduled-task`.
126+
- Use `Remove flag:` or `Remove flags:` only for state chips that should no longer remain on the card.
127+
128+
Correct example for a scheduled implementation that now needs user review:
129+
130+
- `Remove flag: GO`
131+
- `Set flag to: ON-SCHEDULE-LIST`
132+
- `Add label: scheduled-task`
133+
- `Set linked taskId to: <task-id>`
134+
- `Add schedule comment: Scheduled as <task-id>`
135+
136+
Correct example for scheduled work that is finished and now needs final review:
137+
138+
- `Remove flag: ON-SCHEDULE-LIST`
139+
- `Set flag to: needs-user-review`
140+
- `Remove scheduler task: <task-id>` if it still exists
141+
- `Keep linked taskId cleared when the task is gone`
142+
143+
Avoid output such as `Add flags: on-schedule-list, scheduled-task` because it mixes a routing flag with a label.
144+
145+
## Output Expectations
146+
147+
Return only the compact execution summary requested by the dispatcher flow. Avoid board dumps and avoid re-deriving routing state from the full board payload when `cockpit_list_routing_cards` already gives the candidate set.

0 commit comments

Comments
 (0)