overlord-cli 4.7.0 → 4.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,46 +1,82 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: overlord-ticket
|
|
3
|
-
description: Overlord local workflow protocol
|
|
3
|
+
description: Overlord local workflow protocol for Claude Code, covering both Overlord-launched tickets and chat-invoked Overlord work.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Overlord Ticket
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
##
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
8
|
+
Use this skill whenever Claude Code needs to work with Overlord, whether the session was launched by Overlord Desktop/CLI or the user asks from chat to engage with Overlord.
|
|
9
|
+
|
|
10
|
+
## Mode 1: Launched From Overlord Desktop Or CLI
|
|
11
|
+
|
|
12
|
+
Use this mode when the prompt already contains a ticket ID or explicitly says the session was launched by Overlord.
|
|
13
|
+
|
|
14
|
+
1. Attach first with `ovld protocol attach --ticket-id <ticket-id>`.
|
|
15
|
+
2. Keep the returned `session.sessionKey` for all follow-up calls.
|
|
16
|
+
3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
|
|
17
|
+
4. Post updates while working with `ovld protocol update --phase execute`.
|
|
18
|
+
5. If the user sends a follow-up message after the initial ticket, publish it immediately with `--event-type user_follow_up`.
|
|
19
|
+
6. If blocked, call `ovld protocol ask` and stop.
|
|
20
|
+
7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
|
|
21
|
+
|
|
22
|
+
### Mode 1 Reference
|
|
23
|
+
|
|
24
|
+
Attach:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
ovld protocol attach --ticket-id $TICKET_ID
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Update:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Supported `--phase` values:
|
|
37
|
+
- `draft`
|
|
38
|
+
- `execute`
|
|
39
|
+
- `review`
|
|
40
|
+
- `deliver`
|
|
41
|
+
- `complete`
|
|
42
|
+
- `blocked`
|
|
43
|
+
- `cancelled`
|
|
44
|
+
|
|
45
|
+
These are hardcoded CLI-supported values for the `--phase` flag. They are not user-defined phase types.
|
|
46
|
+
|
|
47
|
+
Event types:
|
|
48
|
+
- `update` for standard progress updates
|
|
49
|
+
- `user_follow_up` for human follow-up messages after the initial ticket
|
|
50
|
+
- `alert` for warnings or non-blocking issues
|
|
51
|
+
|
|
52
|
+
Ask when blocked:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
ovld protocol ask --session-key <sessionKey> --ticket-id $TICKET_ID --question "Specific question for the PM."
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Deliver:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
ovld protocol deliver --session-key <sessionKey> \
|
|
62
|
+
--ticket-id $TICKET_ID \
|
|
63
|
+
--summary "Narrative: what you did, next steps." \
|
|
64
|
+
--artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' \
|
|
65
|
+
--change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
|
|
69
|
+
|
|
70
|
+
## Mode 2: Asked From Chat To Use Overlord
|
|
71
|
+
|
|
72
|
+
Use this mode when the conversation starts normally and the user asks Claude to create, inspect, connect to, or otherwise use Overlord.
|
|
73
|
+
|
|
74
|
+
1. If the user wants a new ticket, use `/overlord:spawn` or run `ovld protocol spawn --agent claude-code --objective "..."`.
|
|
75
|
+
2. If the user already has a ticket ID and only wants to inspect it, use `/overlord:load` or run `ovld protocol load-context --ticket-id <ticket-id>`.
|
|
76
|
+
3. If the user wants to route the current session onto an existing ticket by ID, use `/overlord:connect` or run `ovld protocol connect --ticket-id <ticket-id>`.
|
|
77
|
+
4. If the user wants to find a ticket but does not know the ID, use `ovld attach` for interactive ticket search and agent launch, or ask the user for the ticket ID if staying strictly inside chat is the better fit.
|
|
78
|
+
5. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
|
|
79
|
+
6. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
|
|
44
80
|
|
|
45
81
|
## Change Rationales
|
|
46
82
|
|
|
@@ -62,19 +98,17 @@ ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID \
|
|
|
62
98
|
--change-rationales-json '[{"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
|
|
63
99
|
```
|
|
64
100
|
|
|
65
|
-
Record only meaningful behavioral changes
|
|
101
|
+
Record only meaningful behavioral changes. Skip formatting-only noise.
|
|
66
102
|
|
|
67
|
-
## Project Discovery
|
|
103
|
+
## Project Discovery And Ticket Creation
|
|
68
104
|
|
|
69
|
-
When creating tickets from within a repository, `spawn` automatically resolves the
|
|
70
|
-
correct project by matching your current working directory against each project's
|
|
71
|
-
configured "Local working directory". No `--project-id` flag is needed:
|
|
105
|
+
When creating tickets from within a repository, `spawn` automatically resolves the correct project from the current working directory. No `--project-id` flag is needed unless you want to override resolution.
|
|
72
106
|
|
|
73
107
|
```bash
|
|
74
108
|
ovld protocol spawn --agent claude-code --objective "Implement feature X" --priority medium
|
|
75
109
|
```
|
|
76
110
|
|
|
77
|
-
To
|
|
111
|
+
To inspect project resolution explicitly:
|
|
78
112
|
|
|
79
113
|
```bash
|
|
80
114
|
ovld protocol discover-project
|
|
@@ -82,7 +116,7 @@ ovld protocol discover-project
|
|
|
82
116
|
|
|
83
117
|
You can override with `--project-id` or `--working-directory` if needed.
|
|
84
118
|
|
|
85
|
-
## Context
|
|
119
|
+
## Context And Artifacts
|
|
86
120
|
|
|
87
121
|
```bash
|
|
88
122
|
ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
|
|
@@ -93,12 +127,10 @@ ovld protocol artifact-download-url --session-key <sessionKey> --ticket-id $TICK
|
|
|
93
127
|
|
|
94
128
|
## Rules
|
|
95
129
|
|
|
96
|
-
- Always attach first
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
- The `summary` in deliver is what the PM reads first — write it as a narrative, not a command list.
|
|
130
|
+
- Always attach first and always deliver last once you are on a ticket.
|
|
131
|
+
- Use `ovld protocol` commands and the plugin's slash commands instead of ad hoc scripts.
|
|
132
|
+
- Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
|
|
133
|
+
- The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
|
|
101
134
|
- Use `write-context` for facts a future agent session should know.
|
|
102
|
-
-
|
|
103
|
-
-
|
|
104
|
-
- **Delivery is the concluding step.** After delivering, stop working. Do not continue unless the user follows up or the ticket is reopened.
|
|
135
|
+
- Do not add or commit changes unless the user explicitly asks you to commit.
|
|
136
|
+
- Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
|
|
@@ -5,4 +5,6 @@ alwaysApply: true
|
|
|
5
5
|
|
|
6
6
|
# Overlord Local Workflow
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
- If the session was launched by Overlord Desktop or CLI, attach first with `ovld protocol attach --ticket-id $TICKET_ID`, update during work, ask when blocked, and deliver last.
|
|
9
|
+
- If the user asks from chat to use Overlord, use `/spawn` for new tickets, `/load` for read-only context by ticket ID, `/connect` to route the session onto an existing ticket, and `search_tickets` to find tickets by keyword or status.
|
|
10
|
+
- If you need other protocol commands or flags, run `ovld protocol help` instead of guessing.
|
|
@@ -1,8 +1,34 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: overlord-ticket
|
|
3
|
-
description:
|
|
3
|
+
description: Overlord local workflow protocol for Cursor, covering both Overlord-launched tickets and chat-invoked Overlord work.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Overlord Ticket
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Use this skill whenever Cursor needs to work with Overlord, whether the session was launched by Overlord Desktop/CLI or the user asks from chat to engage with Overlord.
|
|
9
|
+
|
|
10
|
+
## Mode 1: Launched From Overlord Desktop Or CLI
|
|
11
|
+
|
|
12
|
+
1. Attach first with `ovld protocol attach --ticket-id <ticket-id>`.
|
|
13
|
+
2. Keep the returned `session.sessionKey` for all follow-up calls.
|
|
14
|
+
3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
|
|
15
|
+
4. Post updates while working with `ovld protocol update --phase execute`.
|
|
16
|
+
5. If the user sends a follow-up message after the initial ticket, publish it immediately with `--event-type user_follow_up`.
|
|
17
|
+
6. If blocked, call `ovld protocol ask` and stop.
|
|
18
|
+
7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
|
|
19
|
+
|
|
20
|
+
## Mode 2: Asked From Chat To Use Overlord
|
|
21
|
+
|
|
22
|
+
1. If the user wants a new ticket, use `/spawn` or run `ovld protocol spawn --agent cursor --objective "..."`.
|
|
23
|
+
2. If the user already has a ticket ID and only wants to inspect it, use `/load` or run `ovld protocol load-context --ticket-id <ticket-id>`.
|
|
24
|
+
3. If the user wants to route the current session onto an existing ticket by ID, use `/connect` or run `ovld protocol connect --ticket-id <ticket-id>`.
|
|
25
|
+
4. If the user wants to search for tickets by keyword or status, use the `search_tickets` MCP tool.
|
|
26
|
+
5. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
|
|
27
|
+
6. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
|
|
28
|
+
|
|
29
|
+
## Rules
|
|
30
|
+
|
|
31
|
+
- Always attach first and always deliver last once you are on a ticket.
|
|
32
|
+
- Use `ovld protocol` commands, the plugin commands, and the MCP tool instead of ad hoc scripts.
|
|
33
|
+
- Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
|
|
34
|
+
- Include at least one progress update before delivering.
|
|
@@ -1,27 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: overlord-ticket
|
|
3
|
+
description: Durable local workflow for working Overlord tickets from Codex, covering both Overlord-launched tickets and chat-invoked Overlord work.
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# Overlord Ticket
|
|
2
7
|
|
|
3
|
-
Use this skill when
|
|
4
|
-
Overlord plugin.
|
|
8
|
+
Use this skill when Codex needs to work with Overlord, whether the session was launched by Overlord Desktop/CLI or the user asks from chat to engage with Overlord.
|
|
5
9
|
|
|
6
|
-
##
|
|
10
|
+
## Mode 1: Launched From Overlord Desktop Or CLI
|
|
7
11
|
|
|
8
12
|
1. Attach first with `ovld protocol attach --ticket-id <ticket-id>`.
|
|
9
13
|
2. Store the returned `SESSION_KEY` or `session.sessionKey`.
|
|
10
|
-
3.
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
14
|
+
3. Treat the Overlord ticket prompt as authoritative for the specific objective and ticket-level constraints.
|
|
15
|
+
4. While working, publish meaningful progress with `ovld protocol update --session-key <sessionKey> --ticket-id <ticket-id> --phase execute --summary "..."`.
|
|
16
|
+
5. If a later user message arrives during the ticket session, publish it immediately with `--event-type user_follow_up` before doing anything else.
|
|
17
|
+
6. If blocked on a human-only action, ask a precise blocking question with `ovld protocol ask` and stop.
|
|
18
|
+
7. Deliver last with `ovld protocol deliver`, including meaningful `changeRationales` for every behavioral git-tracked change.
|
|
19
|
+
|
|
20
|
+
### Mode 1 Reference
|
|
21
|
+
|
|
22
|
+
Attach:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
ovld protocol attach --ticket-id $TICKET_ID
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Update:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID --summary "What you did and why." --phase execute
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Supported `--phase` values:
|
|
35
|
+
- `draft`
|
|
36
|
+
- `execute`
|
|
37
|
+
- `review`
|
|
38
|
+
- `deliver`
|
|
39
|
+
- `complete`
|
|
40
|
+
- `blocked`
|
|
41
|
+
- `cancelled`
|
|
42
|
+
|
|
43
|
+
These are hardcoded CLI-supported values for the `--phase` flag. They are not user-defined phase types.
|
|
44
|
+
|
|
45
|
+
Event types:
|
|
46
|
+
- `update` for standard progress updates
|
|
47
|
+
- `user_follow_up` for human follow-up messages after the initial ticket
|
|
48
|
+
- `alert` for warnings or non-blocking issues
|
|
49
|
+
|
|
50
|
+
Ask when blocked:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
ovld protocol ask --session-key <sessionKey> --ticket-id $TICKET_ID --question "Specific question for the PM."
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Deliver:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
ovld protocol deliver --session-key <sessionKey> \
|
|
60
|
+
--ticket-id $TICKET_ID \
|
|
61
|
+
--summary "Narrative: what you did, next steps." \
|
|
62
|
+
--artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' \
|
|
63
|
+
--change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
|
|
67
|
+
|
|
68
|
+
## Mode 2: Asked From Chat To Use Overlord
|
|
69
|
+
|
|
70
|
+
1. If the user wants a new ticket, use `ovld protocol spawn --objective "..."`. It creates the ticket and attaches immediately.
|
|
71
|
+
2. If the user wants to inspect an existing ticket without starting work, use `ovld protocol load-context --ticket-id <ticket-id>`.
|
|
72
|
+
3. If the user wants to work an existing ticket, attach with `ovld protocol attach --ticket-id <ticket-id>` and then switch to Mode 1.
|
|
73
|
+
4. If the user wants to find existing tickets by keyword or workflow state, use the `search_tickets` tool.
|
|
74
|
+
5. If you need to understand project routing before spawning, use `ovld protocol discover-project`.
|
|
75
|
+
6. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
|
|
76
|
+
|
|
77
|
+
## Change Rationales
|
|
78
|
+
|
|
79
|
+
Always include `changeRationales` when delivering. Optionally include them on updates during long-running work.
|
|
80
|
+
|
|
81
|
+
Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact.
|
|
82
|
+
|
|
83
|
+
These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. For larger full delivery payloads, prefer `--payload-file -` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
|
|
87
|
+
--summary "Recorded rationale details for the latest code changes." --phase execute \
|
|
88
|
+
--change-rationales-json '[{"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
ovld protocol update --session-key <sessionKey> --ticket-id $TICKET_ID \
|
|
93
|
+
--summary "Added retry logic." --phase execute \
|
|
94
|
+
--change-rationales-json '[{"label":"Add backoff","file_path":"lib/api.ts","summary":"Added retry.","why":"Transient failures.","impact":"Retries 3x.","hunks":[{"header":"@@ -22,4 +22,18 @@"}]}]'
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Record only meaningful behavioral changes. Skip formatting-only noise. Prefer 1-5 concise rationales per ticket, each tied to a specific file and diff hunk.
|
|
98
|
+
|
|
99
|
+
## Context And Artifacts
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
ovld protocol read-context --session-key <sessionKey> --ticket-id $TICKET_ID
|
|
103
|
+
ovld protocol write-context --session-key <sessionKey> --ticket-id $TICKET_ID --key "key" --value '"json-value"'
|
|
104
|
+
ovld protocol artifact-upload-file --session-key <sessionKey> --ticket-id $TICKET_ID --file ./spec.pdf --content-type application/pdf
|
|
105
|
+
ovld protocol artifact-download-url --session-key <sessionKey> --ticket-id $TICKET_ID --artifact-id <artifact-id>
|
|
106
|
+
```
|
|
19
107
|
|
|
20
108
|
## Rules
|
|
21
109
|
|
|
22
|
-
- The authoritative lifecycle is the `ovld protocol` CLI.
|
|
23
|
-
- Always attach first and always deliver last.
|
|
24
|
-
- Do not create or rely on a local Codex `AGENTS.md` bundle for Overlord.
|
|
110
|
+
- The authoritative lifecycle is the `ovld protocol` CLI once you are on a ticket.
|
|
111
|
+
- Always attach first and always deliver last once you are working a ticket.
|
|
25
112
|
- Prefer the installed `ovld` CLI and the plugin's MCP tools instead of ad hoc repo scripts.
|
|
26
|
-
-
|
|
27
|
-
|
|
113
|
+
- Do not create or rely on a local Codex `AGENTS.md` bundle for Overlord.
|
|
114
|
+
- When the ticket was launched by Overlord, the ticket prompt remains authoritative for the specific task objective and ticket-level constraints.
|