@pulsarinteractive/geniustasker 0.1.0-beta.11 → 0.1.0-beta.13
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/CHANGELOG.md +22 -0
- package/README.md +14 -1
- package/docs/ARCHITECTURE.md +15 -13
- package/docs/CHATGPT.md +6 -0
- package/docs/CLI.md +153 -5
- package/docs/INTEGRATIONS.md +25 -2
- package/docs/MEMORY.md +9 -0
- package/docs/WORKFLOWS.md +14 -0
- package/examples/codex.toml +1 -1
- package/examples/mcp.json +1 -1
- package/mcp.json +1 -1
- package/package.json +2 -2
- package/plugin.json +1 -1
- package/remote/tool-catalog.json +296 -1
- package/remote/workflows.json +53 -2
- package/skills/geniustasker/SKILL.md +15 -1
- package/skills/geniustasker/references/agent-runs.md +144 -0
- package/skills/geniustasker/references/host-events.md +116 -0
- package/skills/geniustasker/references/importance.md +90 -0
- package/skills/geniustasker/references/metric-goals.md +143 -0
- package/skills/geniustasker/references/metrics-observations.md +184 -0
- package/skills/geniustasker/references/metrics.md +136 -0
- package/skills/geniustasker/references/protocols.md +156 -0
- package/skills/geniustasker/references/updates.md +31 -0
- package/skills/geniustasker-graph/SKILL.md +10 -0
- package/skills/geniustasker-memory/SKILL.md +19 -6
- package/skills/geniustasker-memory/references/knowledge-workflows.md +42 -0
- package/skills/geniustasker-planning/SKILL.md +6 -1
- package/src/changes.mjs +3 -5
- package/src/cli.mjs +108 -14
- package/src/command-catalog.mjs +849 -562
- package/src/command-input-schemas.d.mts +8 -0
- package/src/command-input-schemas.mjs +1021 -0
- package/src/commands.mjs +78 -25
- package/src/mcp.mjs +48 -20
- package/src/protocols.mjs +122 -0
- package/src/resources.mjs +98 -0
- package/src/run-events.mjs +145 -0
- package/src/update-runtime.mjs +169 -0
- package/src/update.mjs +306 -0
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
# Record, correct or void a metric observation
|
|
2
|
+
|
|
3
|
+
First read the [definition workflow](metrics.md), current identity, capabilities
|
|
4
|
+
and the exact definition. Use `metrics:read` to inspect it and `metrics:write`
|
|
5
|
+
for the requested mutation. The server also checks current native rights:
|
|
6
|
+
personal data belongs to the connected owner, while project observations use
|
|
7
|
+
the definition's writer policy. A grant never bypasses project opt-in or
|
|
8
|
+
membership. Do not add yourself to `writers` to work around a refusal.
|
|
9
|
+
|
|
10
|
+
## Read the consolidated result
|
|
11
|
+
|
|
12
|
+
Read the metric definition (`metrics` / `personalMetrics`) and inspect
|
|
13
|
+
`data.summary` before requesting observation history. This server-maintained
|
|
14
|
+
summary updates atomically with the source observation; it excludes voided
|
|
15
|
+
observations and all historical correction snapshots. It is lifetime-only.
|
|
16
|
+
A title such as “Weekly revenue” does not turn its summary into a current-week
|
|
17
|
+
aggregate. Requested [metric goals](metric-goals.md) have their own lifetime or
|
|
18
|
+
fixed-window evaluation. Discover that separate capability before using it; an
|
|
19
|
+
observation command never creates a goal or installs an arbitrary trigger.
|
|
20
|
+
|
|
21
|
+
- `activeCount` counts current, non-voided observations. It is distinct from
|
|
22
|
+
`observationCount`, which retains the count of recorded source observations.
|
|
23
|
+
- `sumUnits`, `numeratorUnits` and `denominatorUnits` are exact integer **strings**
|
|
24
|
+
in units of `10^-configuration.precision`. For precision 2, `"425"` means
|
|
25
|
+
4.25 units. Do not parse large totals as JavaScript `Number` or send these
|
|
26
|
+
strings back as new observations; keep exact integer/decimal arithmetic when
|
|
27
|
+
calculation is necessary.
|
|
28
|
+
- `value` is a nullable decimal **string**, already formatted at the configured
|
|
29
|
+
precision. Mean and Ratio round half away from zero for display. It is not a
|
|
30
|
+
JSON number or an unrounded threshold result. Use it for presentation without
|
|
31
|
+
another floating-point conversion; do not infer exact threshold satisfaction
|
|
32
|
+
from its rounded digits.
|
|
33
|
+
- `latest` identifies the latest active evidence with `observationId`,
|
|
34
|
+
`observedAt` and `measurement`. Gauge/Latest uses observation time, not arrival
|
|
35
|
+
time. A late older sample can change a Sum, Mean or Ratio without becoming the
|
|
36
|
+
latest observation. A correction or void can change which evidence is latest.
|
|
37
|
+
|
|
38
|
+
For an empty active set, `value` and `latest` are null. This is “no active
|
|
39
|
+
measurement,” not zero. A measured zero can instead have `activeCount > 0` and
|
|
40
|
+
`value:"0.00"`. A completely missing `summary` on a legacy definition means
|
|
41
|
+
unknown, not an empty set: never fabricate zero fields or reconstruct and write
|
|
42
|
+
the summary through client commands. If a write returns
|
|
43
|
+
`metric_summary_rebuild_required` (503), retain its immutable operation and
|
|
44
|
+
report that server repair is required; do not keep retrying or create another
|
|
45
|
+
metric to bypass it.
|
|
46
|
+
|
|
47
|
+
Freshness compares `summary.latest.observedAt` with the current time and
|
|
48
|
+
`configuration.freshnessSeconds`. Do not use definition `updated`, correction
|
|
49
|
+
arrival time or the time you fetched the page to claim fresh evidence. A null
|
|
50
|
+
freshness setting means no expected cadence was configured, not that all data
|
|
51
|
+
is always fresh. If latest is null, there is no active evidence to assess.
|
|
52
|
+
Late arrivals retain their source date; never replace it with now to make a
|
|
53
|
+
summary appear current.
|
|
54
|
+
|
|
55
|
+
## Choose the actual evidence
|
|
56
|
+
|
|
57
|
+
| Definition kind | `measurement` meaning |
|
|
58
|
+
| --------------- | ----------------------------------------------------------------------------------- |
|
|
59
|
+
| `Gauge` | `value` is the absolute level; `numerator` and `denominator` are null. |
|
|
60
|
+
| `Counter` | `value` is a signed contribution, not a running total; other fields are null. |
|
|
61
|
+
| `Ratio` | `value` is null; `numerator` is nonnegative and `denominator` is strictly positive. |
|
|
62
|
+
|
|
63
|
+
For example, a cumulative provider counter increasing from 100 to 103 is a
|
|
64
|
+
Gauge value of 103 **or**, for an explicitly defined increment metric with a
|
|
65
|
+
verified previous baseline, a Counter contribution of 3. It is never a Counter
|
|
66
|
+
contribution of 103. A negative Counter contribution can represent a real
|
|
67
|
+
reversal; correcting a wrong entry instead uses `metric.correct` so its cause
|
|
68
|
+
and previous value remain visible. Missing data is not a measured zero.
|
|
69
|
+
|
|
70
|
+
A Ratio's result uses the configured scale and sums of numerator and denominator.
|
|
71
|
+
Do not submit a percentage as `value`, or average rates with unequal denominators.
|
|
72
|
+
Do not calculate a global result from a partial history page. Corrections are
|
|
73
|
+
previous snapshots and must never be added to the observations; voided
|
|
74
|
+
observations must not be treated as active evidence.
|
|
75
|
+
|
|
76
|
+
Keep numbers in the definition's unit and precision. Magnitudes are bounded by
|
|
77
|
+
the current schema (currently 1,000,000,000); nonfinite numbers and invalid
|
|
78
|
+
denominators are not observations. Do not silently round or convert ambiguous
|
|
79
|
+
source units. Ask or clarify the definition when the source does not fit it.
|
|
80
|
+
|
|
81
|
+
## Record once
|
|
82
|
+
|
|
83
|
+
`metric.record` creates a new observation UUID with `expectedRevision:null`.
|
|
84
|
+
Its `data` contains `metricId`, the definition's current `measurementVersion`,
|
|
85
|
+
`sourceKey`, `sourceLabel`, `observedAt` and all three `measurement` fields.
|
|
86
|
+
The envelope ID is the **observation ID**, not the definition ID.
|
|
87
|
+
|
|
88
|
+
`sourceKey` is the stable event identity within that metric, for example a
|
|
89
|
+
provider record ID or a specific period's identifier. Preserve the observation
|
|
90
|
+
UUID and key in the producer's own mapping. Do not derive either from retry time
|
|
91
|
+
or translated text. Labels may be localized; identifiers must stay unchanged.
|
|
92
|
+
Neither field should contain credentials, signed download URLs or raw private
|
|
93
|
+
logs. A later independent observation gets its own event identity.
|
|
94
|
+
|
|
95
|
+
`observedAt` is the source observation time with an explicit timezone, not
|
|
96
|
+
arrival time. A late observation retains its real date. Do not substitute now
|
|
97
|
+
to evade freshness checks; the server bounds future skew. Never guess a missing
|
|
98
|
+
measurement, timestamp or source period.
|
|
99
|
+
|
|
100
|
+
Example `data` for a Gauge observation:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"metricId": "00000000-0000-4000-8000-000000000001",
|
|
105
|
+
"measurementVersion": 1,
|
|
106
|
+
"sourceKey": "finance:week-2026-46",
|
|
107
|
+
"sourceLabel": "Weekly sales export",
|
|
108
|
+
"observedAt": "2026-11-15T23:00:00Z",
|
|
109
|
+
"measurement": { "value": 1250.5, "numerator": null, "denominator": null }
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Example `data` for a different definition configured as Ratio:
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"metricId": "00000000-0000-4000-8000-000000000002",
|
|
118
|
+
"measurementVersion": 1,
|
|
119
|
+
"sourceKey": "support:week-2026-46",
|
|
120
|
+
"sourceLabel": "Reviewed support outcomes",
|
|
121
|
+
"observedAt": "2026-11-15T23:00:00Z",
|
|
122
|
+
"measurement": { "value": null, "numerator": 18, "denominator": 20 }
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Do not send a batch hidden in one field. Each observation is one normal command,
|
|
127
|
+
using the shared account request and storage quotas. Preparing a local command
|
|
128
|
+
persists its immutable journal before sending; hosted preparation returns the
|
|
129
|
+
exact command to retain. On an uncertain response, retry that same operation ID,
|
|
130
|
+
`issuedAt` and body under the same identity. This is separate from source-event
|
|
131
|
+
deduplication: creating a new operation or UUID does not make an already used
|
|
132
|
+
`sourceKey` a new observation. On duplicate-source refusal, reconcile the saved
|
|
133
|
+
mapping and current record; do not alter the key to get around it.
|
|
134
|
+
|
|
135
|
+
## Correct or void with a reason
|
|
136
|
+
|
|
137
|
+
Read the current observation by ID, along with its definition. `metric.correct`
|
|
138
|
+
targets that observation UUID and its current revision, never the definition's
|
|
139
|
+
revision. Supply a complete replacement measurement and observedAt, plus a
|
|
140
|
+
concrete reason. It cannot change metricId, sourceKey or sourceLabel. The server
|
|
141
|
+
retains the previous snapshot and attributes the change to the real caller.
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"observedAt": "2026-11-15T23:00:00Z",
|
|
146
|
+
"measurement": { "value": 1200.5, "numerator": null, "denominator": null },
|
|
147
|
+
"reason": "The verified export excluded a refunded sale that the initial amount included."
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Use `metric.void` when the evidence must be invalidated, with the current
|
|
152
|
+
observation revision and a reason:
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{ "reason": "This source export was generated from the wrong reporting period." }
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Void does not delete the observation or its audit trail. Do not clear source
|
|
159
|
+
keys, forge `voided` or write directly to correction collections. A conflict
|
|
160
|
+
means reread and decide again; do not overwrite a concurrent correction. If a
|
|
161
|
+
paused/archived definition or current writer policy refuses an operation, report
|
|
162
|
+
the refusal rather than changing settings implicitly.
|
|
163
|
+
|
|
164
|
+
## Bounded reads and truthful completion
|
|
165
|
+
|
|
166
|
+
```sh
|
|
167
|
+
geniustasker commands describe --kind metric.record --json
|
|
168
|
+
geniustasker commands describe --kind metric.correct --json
|
|
169
|
+
geniustasker metrics list --scope project:PROJECT --collection metricObservations --id OBSERVATION_UUID --json
|
|
170
|
+
geniustasker metrics list --scope project:PROJECT --collection metricObservations --metric-id METRIC_UUID --json
|
|
171
|
+
geniustasker metrics list --scope project:PROJECT --collection metricCorrections --metric-id METRIC_UUID --json
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Use the personal-prefixed collections for the connected personal scope. Every
|
|
175
|
+
page uses normal read admission; carry epoch/checkpoint/after and the exact
|
|
176
|
+
`metricId` filter unchanged. The equality filter applies only to observations
|
|
177
|
+
and corrections. Filtered reads return `changeCursor:null`; do not start a
|
|
178
|
+
filtered change stream. Only an unfiltered completed inventory supplies a
|
|
179
|
+
collection change cursor. There is no implicit full export or complex search.
|
|
180
|
+
A correction row includes `observationId`,
|
|
181
|
+
`previousRevision` and replacement attribution; it describes previous evidence,
|
|
182
|
+
not another event to count. Report the saved observation/correction and its
|
|
183
|
+
receipt. Do not claim goal progress, a trigger or a running collector unless
|
|
184
|
+
that separate capability is available and its result has actually been verified.
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Custom metric definitions
|
|
2
|
+
|
|
3
|
+
Use this workflow to define a measurement for the connected person or one
|
|
4
|
+
GeniusTasker project. Discover live capabilities first: `metrics:read` and
|
|
5
|
+
`metrics:write` are independent permissions. Existing task/goal grants do not
|
|
6
|
+
include them. Project configuration also requires the owner or administrator
|
|
7
|
+
and agent contributions enabled. A refusal is not permission to use private APIs.
|
|
8
|
+
|
|
9
|
+
Definition creation does not itself record a value. When capabilities advertise
|
|
10
|
+
`metric.record`, `metric.correct` and `metric.void`, use the
|
|
11
|
+
[observation workflow](metrics-observations.md) to record real evidence and retain
|
|
12
|
+
its corrections. These operations do not start a collector or link a goal.
|
|
13
|
+
When requested and advertised, use the separate [metric goal workflow](metric-goals.md)
|
|
14
|
+
to evaluate a target against the same scope’s metric. Existing YouTube/Spotify metrics are separate. Feature
|
|
15
|
+
activation and package installation are separate: use only what the current
|
|
16
|
+
server advertises.
|
|
17
|
+
|
|
18
|
+
## Read the right scope
|
|
19
|
+
|
|
20
|
+
Get `actor.ownerId` from current identity, never from a profile ID, name or old
|
|
21
|
+
session. For a personal definition use `personal:<actor.ownerId>`; for a project
|
|
22
|
+
definition use its discovered `project:<id>` scope. Consent to personal metrics
|
|
23
|
+
is a separate resource choice; it does not expose other personal account data.
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
geniustasker metrics list --scope personal:OWNER --json
|
|
27
|
+
geniustasker metrics list --scope project:PROJECT --json
|
|
28
|
+
geniustasker metrics list --scope project:PROJECT --id METRIC_UUID --json
|
|
29
|
+
geniustasker metrics list --scope project:PROJECT --collection metricObservations --json
|
|
30
|
+
geniustasker metrics list --scope personal:OWNER --collection personalMetricCorrections --json
|
|
31
|
+
geniustasker commands describe --kind metric.create --json
|
|
32
|
+
geniustasker workflow show --topic metrics --json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Use the chosen environment/context consistently, including
|
|
36
|
+
`--environment production` for production data. `resources list` also supports
|
|
37
|
+
`metrics` in project scopes and `personalMetrics` in the connected personal
|
|
38
|
+
scope. In MCP prefer `tasker_read_metrics` with that same collection and scope.
|
|
39
|
+
Select `metricObservations` / `personalMetricObservations` for the current
|
|
40
|
+
observations, or `metricCorrections` / `personalMetricCorrections` for previous
|
|
41
|
+
snapshots. Linked goals use `metricGoals` / `personalMetricGoals`; these accept
|
|
42
|
+
an exact goal `id`, not the history-only `metricId` filter. The default CLI collection remains definitions for compatibility.
|
|
43
|
+
Read one page at a time; carry `after`, `epoch` and `checkpoint` unchanged for
|
|
44
|
+
continuation. Take the epoch from the returned page, including an empty one.
|
|
45
|
+
Use an exact ID read before editing and preserve unmodified configuration.
|
|
46
|
+
For observation/correction collections, `--metric-id METRIC_UUID` (MCP
|
|
47
|
+
`metricId`) selects one exact definition. Preserve that filter on every page;
|
|
48
|
+
filtered results have `changeCursor:null` and cannot start a filtered change
|
|
49
|
+
stream. Date-window and compound query filters are not exposed. Do not invent
|
|
50
|
+
query parameters or load every page implicitly; request further bounded pages
|
|
51
|
+
only when needed and state when a result is partial.
|
|
52
|
+
|
|
53
|
+
## Choose a useful meaning
|
|
54
|
+
|
|
55
|
+
For an existing metric's consolidated result, first read the definition's
|
|
56
|
+
`summary` with `metrics` or `personalMetrics`. This avoids scanning observations
|
|
57
|
+
just to obtain a total. The server updates it atomically with each accepted
|
|
58
|
+
record, correction or void. It covers the metric's **entire recorded lifetime**,
|
|
59
|
+
not a week, month or rolling window, even if the title mentions a period.
|
|
60
|
+
For exact numeric fields, missing values and freshness, read
|
|
61
|
+
[the summary rules](metrics-observations.md#read-the-consolidated-result).
|
|
62
|
+
|
|
63
|
+
| Meaning | Configuration | Avoid |
|
|
64
|
+
| ----------------------------------------------- | ------------------ | ------------------------------------------------ |
|
|
65
|
+
| Current level, such as audience size | `Gauge` + `Latest` | Summing repeated cumulative totals |
|
|
66
|
+
| Average of comparable samples | `Gauge` + `Mean` | Averaging unlike units or unequal weighted rates |
|
|
67
|
+
| Additive contributions, such as completed units | `Counter` + `Sum` | Overlapping periods and repeated contributions |
|
|
68
|
+
| Numerator/denominator measure | `Ratio` + `Ratio` | Unweighted averages of percentages |
|
|
69
|
+
|
|
70
|
+
Explain the unit, data source, interval and interpretation in the description.
|
|
71
|
+
Ask only for an ambiguity that changes the meaning. Never invent values or
|
|
72
|
+
claim an approximation is an observed result. The machine key stays stable;
|
|
73
|
+
write title and description naturally in the user's language. Do not translate
|
|
74
|
+
keys, IDs, API property names or enum values.
|
|
75
|
+
|
|
76
|
+
`precision` is 0–6. `ratioScale` is 1 or 100 for a Ratio, and 1 otherwise.
|
|
77
|
+
`freshnessSeconds` is null or 60–31536000; it describes expected freshness and
|
|
78
|
+
does not schedule collection. `writers` is empty for a personal definition.
|
|
79
|
+
Project writers are current approved member user IDs, not agent profile IDs;
|
|
80
|
+
they do not grant project administration or additional API permissions.
|
|
81
|
+
|
|
82
|
+
## Prepare and persist
|
|
83
|
+
|
|
84
|
+
`metric.create` and `metric.update` take this complete `data` shape (example in
|
|
85
|
+
French). Inspect command help for the current limits; do not send the internal
|
|
86
|
+
`action` field or server-owned creator, count, version or attribution fields.
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"configuration": {
|
|
91
|
+
"key": "weekly_revenue",
|
|
92
|
+
"title": "Chiffre d’affaires hebdomadaire",
|
|
93
|
+
"description": "Montant total pour une semaine complète, en euros. La source et la période seront précisées lors de la collecte.",
|
|
94
|
+
"kind": "Gauge",
|
|
95
|
+
"aggregation": "Latest",
|
|
96
|
+
"unit": "EUR",
|
|
97
|
+
"precision": 2,
|
|
98
|
+
"ratioScale": 1,
|
|
99
|
+
"freshnessSeconds": 604800,
|
|
100
|
+
"writers": [],
|
|
101
|
+
"paused": false,
|
|
102
|
+
"archived": false
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
For creation choose and retain one lowercase UUID as `id`, the scope's current
|
|
108
|
+
`epoch`, `expectedRevision:null`, and `kind:"metric.create"`. For update read the
|
|
109
|
+
existing UUID/revision and send `kind:"metric.update"` with the complete updated
|
|
110
|
+
configuration. The key cannot change. A duplicate key is a reason to reread and
|
|
111
|
+
reuse the intended definition, not to create several nearly identical entries.
|
|
112
|
+
|
|
113
|
+
Local CLI: `commands prepare --file draft.json --json`, then
|
|
114
|
+
`commands retry --operation OPERATION_UUID --json`. Local MCP: prepare with
|
|
115
|
+
`tasker_prepare_command`, then retry the returned operation or execute the
|
|
116
|
+
immutable request with `tasker_edit_metrics`. The dedicated tool uses the same
|
|
117
|
+
journal and normal server admission. Hosted MCP has no local journal: retain the
|
|
118
|
+
exact command returned by preparation and pass it to `tasker_edit_metrics`.
|
|
119
|
+
|
|
120
|
+
After uncertainty retain the exact operation ID, time and body. Respect retry
|
|
121
|
+
delays. After a revision conflict, reread and decide whether a new edit is still
|
|
122
|
+
appropriate. Do not automatically replace the user's configuration or broaden
|
|
123
|
+
access. A definition receipt proves configuration persistence, not collection or
|
|
124
|
+
progress toward a goal.
|
|
125
|
+
|
|
126
|
+
## Preserve existing meaning
|
|
127
|
+
|
|
128
|
+
Changing kind, aggregation, unit, precision or ratio scale changes the meaning
|
|
129
|
+
of samples. The server refuses it when observations exist. Do not silently
|
|
130
|
+
convert a definition to another unit or manufacture a zero observation count.
|
|
131
|
+
Descriptive changes do not increment measurement semantics.
|
|
132
|
+
|
|
133
|
+
Archive through `configuration.archived:true` with a current revision when the
|
|
134
|
+
definition should be retained. `metric.delete` takes empty `data` and a current
|
|
135
|
+
revision; it is refused when observations exist. No bulk ingestion, history
|
|
136
|
+
deletion or custom-goal operation is implied by these definition commands.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# Reuse a task protocol
|
|
2
|
+
|
|
3
|
+
Use this workflow when the user wants a reusable procedure with several tasks,
|
|
4
|
+
dependencies, acceptance criteria and deliberately selected importance. A
|
|
5
|
+
protocol creates tracked work; it does not execute the work or run an agent.
|
|
6
|
+
For a few unrelated tasks, ordinary task commands remain sufficient.
|
|
7
|
+
|
|
8
|
+
## Find the right version
|
|
9
|
+
|
|
10
|
+
Read identity, capabilities, the selected project and its relevant configuration.
|
|
11
|
+
Discover `taskTemplates`, `protocolInstances` and `protocol.*` commands before
|
|
12
|
+
using them. Protocols target Details projects. A legacy template containing only
|
|
13
|
+
a name and description is not a published protocol. Existing project agent
|
|
14
|
+
contributions, current membership and the appropriate grants must permit writes.
|
|
15
|
+
|
|
16
|
+
Read the selected `taskTemplates` version, its `protocolDefinition`, family,
|
|
17
|
+
version and digest. Preserve its step keys; they determine task identities.
|
|
18
|
+
Check project features, dependencies, members and the user's intended outcome.
|
|
19
|
+
Do not infer that an administrative role or a task assignment authorizes an
|
|
20
|
+
unrelated external action.
|
|
21
|
+
|
|
22
|
+
Publishing requires project administration and `tasks:write`. Use
|
|
23
|
+
`protocol.publish` with a new UUID, null revision and
|
|
24
|
+
`data: {definition, previousVersionId}`. Null starts a family; otherwise use the
|
|
25
|
+
latest immutable version ID. Never patch a published version in place or
|
|
26
|
+
silently convert an older template. Read command help for the current schema.
|
|
27
|
+
|
|
28
|
+
## Inspect the exact data schema
|
|
29
|
+
|
|
30
|
+
Use `geniustasker commands describe --kind protocol.publish --json` or local /
|
|
31
|
+
hosted `tasker_command_help` with `{"kind":"protocol.publish"}` before preparing
|
|
32
|
+
it. The four protocol commands expose nested field schemas and required fields.
|
|
33
|
+
Local help is offline; it does not claim the account has access. The server still
|
|
34
|
+
checks semantic rules such as valid members, actual dates and dependency cycles.
|
|
35
|
+
Never send the internal `action` field.
|
|
36
|
+
|
|
37
|
+
A minimal `protocol.publish` **data** object (the immutable command envelope also
|
|
38
|
+
needs the selected project, current epoch, a new version UUID and null revision):
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"definition": {
|
|
43
|
+
"formatVersion": 1,
|
|
44
|
+
"name": "Verify a small delivery",
|
|
45
|
+
"description": "A reusable verification task.",
|
|
46
|
+
"variables": [],
|
|
47
|
+
"steps": [
|
|
48
|
+
{
|
|
49
|
+
"key": "verify",
|
|
50
|
+
"title": "Verify the requested behavior",
|
|
51
|
+
"description": "Check the agreed acceptance criteria.",
|
|
52
|
+
"kind": "Ticket",
|
|
53
|
+
"parent": null,
|
|
54
|
+
"dependencies": [],
|
|
55
|
+
"importance": "Normal",
|
|
56
|
+
"importanceReason": "",
|
|
57
|
+
"delivery": { "push": "silent", "recap": true, "animation": "silent" },
|
|
58
|
+
"acceptance": ["The requested behavior has been verified."],
|
|
59
|
+
"ownerVariable": null,
|
|
60
|
+
"dueAfterDays": null
|
|
61
|
+
}
|
|
62
|
+
]
|
|
63
|
+
},
|
|
64
|
+
"previousVersionId": null
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Adapt the work to the request; this is a schema example, not a prescribed workflow.
|
|
69
|
+
An `ownerVariable` references a declared user variable; null assigns the creator.
|
|
70
|
+
Parent/dependency values reference other step keys, never newly guessed task IDs.
|
|
71
|
+
A child kind and its parent must form a supported Epic → Ticket → Subtask chain.
|
|
72
|
+
|
|
73
|
+
## Bind and preview
|
|
74
|
+
|
|
75
|
+
Choose one lowercase UUID for `instanceId` and retain it. Bind only declared
|
|
76
|
+
variables: text, number, boolean, current user/member ID or date. Missing required
|
|
77
|
+
values need relevant user information. Preserve `false` and `0`; neither means
|
|
78
|
+
missing. Values are literal data, not expressions or agent instructions.
|
|
79
|
+
|
|
80
|
+
Capture an explicit timezone-qualified `anchor` once. `dueAfterDays` means elapsed
|
|
81
|
+
24-hour days from that anchor, not a local calendar or recurring schedule. Reuse
|
|
82
|
+
the same anchor on every preview page and in the eventual start command.
|
|
83
|
+
|
|
84
|
+
`tasker_protocol_preview` and `protocols preview --file` take:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"scope": "project:PROJECT_ID",
|
|
89
|
+
"protocolVersionId": "11111111-1111-4111-8111-111111111111",
|
|
90
|
+
"bindings": {
|
|
91
|
+
"instanceId": "22222222-2222-4222-8222-222222222222",
|
|
92
|
+
"scope": "project:PROJECT_ID",
|
|
93
|
+
"epoch": "EPOCH_FROM_CURRENT_READ",
|
|
94
|
+
"anchor": "2026-11-16T09:00:00+01:00",
|
|
95
|
+
"values": {}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Replace all example identifiers and the date with the actual project, version,
|
|
101
|
+
epoch and intended timing. Populate `values` from the chosen definition.
|
|
102
|
+
|
|
103
|
+
Preview requires `tasks:read`; it creates neither an instance nor tasks. Each
|
|
104
|
+
call consumes the normal read budget and returns at most 20 steps. When needed,
|
|
105
|
+
continue with `after: nextAfter` and the original returned `digest`, keeping the
|
|
106
|
+
version and every binding unchanged. Stop at `nextAfter: null`. Never claim
|
|
107
|
+
unread pages were inspected; changed context or lost access needs reconciliation.
|
|
108
|
+
|
|
109
|
+
Review the outcome, owners, dates, acceptance criteria, dependency structure and
|
|
110
|
+
importance. [Importance](importance.md) measures impact, independently of urgency
|
|
111
|
+
and hierarchy. Important/Critical need a concrete reason. Delivery preferences
|
|
112
|
+
request or suppress attention; a request cannot bypass recipient settings.
|
|
113
|
+
|
|
114
|
+
## Materialize only the requested work
|
|
115
|
+
|
|
116
|
+
If the user asked to create this work, use the normal immutable command workflow.
|
|
117
|
+
Otherwise show the relevant preview and await that decision. No preview grants
|
|
118
|
+
write access or authorizes a later changed plan.
|
|
119
|
+
|
|
120
|
+
1. Prepare `protocol.start` with `id: bindings.instanceId`, `expectedRevision:
|
|
121
|
+
null`, the same scope/epoch, and `data: {protocolVersionId, bindings}`.
|
|
122
|
+
2. Execute that exact prepared operation, then read the resulting
|
|
123
|
+
`protocolInstances` record for its current revision, digest and `appliedCount`.
|
|
124
|
+
3. Prepare `protocol.apply` against that instance and revision with
|
|
125
|
+
`data: {digest, from: appliedCount, count: 20}` or a smaller intended batch.
|
|
126
|
+
One call creates at most 20 steps through ordinary authority and quota checks.
|
|
127
|
+
4. Read the confirmed result before preparing another batch. Continue only
|
|
128
|
+
within the requested work; there is no automatic apply loop in the client.
|
|
129
|
+
|
|
130
|
+
An uncertain reply requires replaying the same operation, not incrementing the
|
|
131
|
+
cursor or creating a fresh ID. After a definitive conflict, reread and reconcile.
|
|
132
|
+
Do not bypass expired/revoked access, identity binding, an ID collision or a
|
|
133
|
+
human-owned importance decision by using another transport or recreating tasks.
|
|
134
|
+
The creating user or a current project administrator may continue or cancel an
|
|
135
|
+
instance. The same user may continue under another profile only within that
|
|
136
|
+
profile's current grants; each new command rechecks access. An uncertain operation
|
|
137
|
+
remains bound to its original command identity and cannot be moved to another
|
|
138
|
+
profile or session. Resolve its outcome before preparing a new batch.
|
|
139
|
+
|
|
140
|
+
`Applied` means the tasks were materialized. It says nothing about completed
|
|
141
|
+
work, earned XP or delivered notifications. `protocol.cancel` with the current
|
|
142
|
+
revision stops remaining materialization; it preserves already created tasks.
|
|
143
|
+
Do not delete them as an implicit rollback. Instance counters, state and
|
|
144
|
+
provenance are server-owned.
|
|
145
|
+
|
|
146
|
+
CLI example for inspection, without creation:
|
|
147
|
+
|
|
148
|
+
```sh
|
|
149
|
+
geniustasker workflow show --topic protocols --json
|
|
150
|
+
geniustasker protocols preview --file protocol-preview.json --context work --json
|
|
151
|
+
geniustasker commands describe --json
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
CLI/local MCP preparation saves a private journal. Hosted ChatGPT preparation
|
|
155
|
+
returns the immutable command object; retain it and pass it to `tasker_edit_tasks`.
|
|
156
|
+
Both share the same account budget, membership and project permissions.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# CLI updates
|
|
2
|
+
|
|
3
|
+
Use `geniustasker update check --json` when checking package freshness. It reads
|
|
4
|
+
the official npm registry anonymously and does not read an account or consume its
|
|
5
|
+
API quota. The installed release selects beta or stable automatically; use
|
|
6
|
+
`--channel beta` or `--channel stable` only when that channel change is intended.
|
|
7
|
+
An older registry version is not a downgrade instruction.
|
|
8
|
+
|
|
9
|
+
When the user has requested an update, stop the local MCP server and let active
|
|
10
|
+
CLI commands finish, then run `geniustasker update install --json` in a terminal.
|
|
11
|
+
It updates only the current global npm installation. If the host uses an npx
|
|
12
|
+
version pin, a project dependency, a source checkout or another package manager,
|
|
13
|
+
update that installation through its own workflow instead; do not replace an
|
|
14
|
+
unrelated global package or change the host configuration without authorization.
|
|
15
|
+
Restart the MCP host after installation. This is not a hosted connector update.
|
|
16
|
+
|
|
17
|
+
The updater preserves credentials and immutable journals. An uncertain operation
|
|
18
|
+
stays uncertain: inspect it and retry the same operation only when the underlying
|
|
19
|
+
task calls for it. Do not reset authentication, remove journals or automatically
|
|
20
|
+
retry domain commands because a package was updated.
|
|
21
|
+
|
|
22
|
+
`update_runtime_busy` means another CLI/MCP process or an installer still owns
|
|
23
|
+
the installation. Wait or close it; never kill another task to install an update.
|
|
24
|
+
A crashed installer may leave an `install.lock` directory. Recover it only after
|
|
25
|
+
confirming that the installer and all clients have stopped, using the procedure
|
|
26
|
+
in [CLI updates](../../../docs/CLI.md#updates). `update_install_unconfirmed` needs
|
|
27
|
+
inspection of the installed version before retrying; it is not a success receipt.
|
|
28
|
+
|
|
29
|
+
Automatic discovery never runs from MCP or JSON calls. For terminal sessions,
|
|
30
|
+
`GENIUSTASKER_NO_UPDATE_CHECK=1` disables it. A registry outage must not interrupt
|
|
31
|
+
the user's actual work or trigger repeated checks.
|
|
@@ -10,6 +10,16 @@ do not load every graph at startup. Search nodes, inspect `nodeIndex`, then use
|
|
|
10
10
|
`tasker_graph` around a selected node. Respect `truncated`: an incomplete
|
|
11
11
|
neighborhood cannot prove a relation is absent. Read full records before edits.
|
|
12
12
|
|
|
13
|
+
Graph creation, node/edge changes and delegated Graph reads/search/exploration
|
|
14
|
+
require the acting user's Starter or Pro plan as well as the existing resource
|
|
15
|
+
grant. A paid space owner does not upgrade another reader. Document pages,
|
|
16
|
+
attachments and document references remain independent capabilities.
|
|
17
|
+
On `memory_graph_premium_required`, stop Graph calls; another tool, profile or
|
|
18
|
+
connection is not a workaround. After downgrade, the user can still inspect
|
|
19
|
+
existing content through ordinary application sync and personal-data export.
|
|
20
|
+
Offer document-only work when it satisfies the request; do not copy Graph data
|
|
21
|
+
into pages to evade the restriction.
|
|
22
|
+
|
|
13
23
|
Each node owns its title, type, notes and optional resource thumbnail. Each edge
|
|
14
24
|
has a source, target, typed relation and certainty. Prefer precise relation names
|
|
15
25
|
and mark proposed connections as proposals. Preserve existing identities instead
|
|
@@ -6,7 +6,10 @@ description: Read and maintain GeniusTasker Memory documents and Graph relations
|
|
|
6
6
|
Memory belongs to the account and is independent of projects. Use the user's
|
|
7
7
|
selected context and environment; discover identity and capabilities first.
|
|
8
8
|
If no session exists, ask the user to run `geniustasker auth login --context work`
|
|
9
|
-
in their terminal
|
|
9
|
+
in their terminal with the intended environment. The beta defaults to development;
|
|
10
|
+
TestFlight data requires `--environment production` at login and on subsequent
|
|
11
|
+
CLI/MCP invocations. Use a distinct context; its name alone does not select an
|
|
12
|
+
environment. The browser lets them select resources and permissions.
|
|
10
13
|
Do not collect passwords or tokens, approve your own consent, or edit credentials.
|
|
11
14
|
|
|
12
15
|
## Navigate without loading the entire corpus
|
|
@@ -44,11 +47,16 @@ A new memory uses one UUID v4 for root ID, scope suffix and initial epoch. Updat
|
|
|
44
47
|
and deletes use a freshly read revision. Destructive changes require the user's
|
|
45
48
|
actual authorization; read access never implies write access.
|
|
46
49
|
|
|
47
|
-
Prepare a complete immutable operation using `tasker_prepare_command
|
|
48
|
-
it with `tasker_retry_command` and the returned operation ID
|
|
49
|
-
`commands prepare --file draft.json` and
|
|
50
|
-
|
|
51
|
-
|
|
50
|
+
Prepare a complete immutable operation using `tasker_prepare_command`. In local
|
|
51
|
+
MCP, execute it with `tasker_retry_command` and the returned operation ID; the CLI
|
|
52
|
+
equivalents are `commands prepare --file draft.json` and
|
|
53
|
+
`commands retry --operation ID`. Hosted ChatGPT has no local operation journal:
|
|
54
|
+
retain the returned command object and send it through the discovered Memory edit
|
|
55
|
+
tool (`tasker_edit_memory`), unchanged after an uncertain result. Do not call a
|
|
56
|
+
local-only retry tool in the connector. After a revision conflict, reread and
|
|
57
|
+
reconcile the other contribution before preparing a new operation; never replace
|
|
58
|
+
the complete current page with an older snapshot. See the multi-agent procedure
|
|
59
|
+
in [focused knowledge workflows](references/knowledge-workflows.md).
|
|
52
60
|
|
|
53
61
|
For authorized imports, keep a resumable local journal and source hashes; split
|
|
54
62
|
pages to the advertised bounds, avoid duplicates, preserve editorial authority,
|
|
@@ -64,6 +72,11 @@ deployments may not expose them. Nodes and edges live in a memory scope. Read
|
|
|
64
72
|
(`graph explore`) around a selected node rather than reading the entire graph.
|
|
65
73
|
`truncated` means the result is incomplete. Never infer absent relations from it.
|
|
66
74
|
|
|
75
|
+
Graph creation, edits and delegated Graph reads/search/exploration require
|
|
76
|
+
Starter or Pro for the acting user, plus the resource grant. Documents and their
|
|
77
|
+
attachments remain independent. On `memory_graph_premium_required`, stop Graph
|
|
78
|
+
calls; do not switch tools, profiles or copy it into documents to bypass the tier.
|
|
79
|
+
|
|
67
80
|
Each node owns its editable text; references contain only scope, pageId and an
|
|
68
81
|
optional blockId. Use `tasker_reference` (`memory resolve`) for linked content.
|
|
69
82
|
Access to Graph does not grant access to its references, including shared memories.
|
|
@@ -12,6 +12,12 @@ with the original epoch and checkpoint, including empty pages with a cursor.
|
|
|
12
12
|
An unavailable source is not an empty source. Report the gap without changing
|
|
13
13
|
accounts, permissions or the user's sharing settings.
|
|
14
14
|
|
|
15
|
+
Search is lexical, not a semantic ranking or a corpus-wide reasoning engine.
|
|
16
|
+
It matches up to twelve word prefixes together in one Memory and returns one
|
|
17
|
+
bounded page. If the result is insufficient, refine the words or make another
|
|
18
|
+
targeted call. Each call has normal authorization and usage accounting; do not
|
|
19
|
+
simulate an unlimited search with parallel calls over every Memory.
|
|
20
|
+
|
|
15
21
|
## Explore Graph progressively
|
|
16
22
|
|
|
17
23
|
Use node search or `nodeIndex` to find a starting node. Call `tasker_graph` with
|
|
@@ -55,3 +61,39 @@ and source provenance. Prepare one immutable command and retain its operation ID
|
|
|
55
61
|
retry that exact operation after a timeout. A revision conflict requires a new
|
|
56
62
|
read and a new operation. Report what changed, what was verified, and what
|
|
57
63
|
remains inaccessible or incomplete.
|
|
64
|
+
|
|
65
|
+
## Cooperate without overwriting another agent
|
|
66
|
+
|
|
67
|
+
Two agents can read the same revision. A successful edit by one makes the
|
|
68
|
+
other's older update stale, even when their intended changes affect different
|
|
69
|
+
blocks. There is no automatic document merge and no exclusive Memory run lease.
|
|
70
|
+
Use separate profiles for attribution, not to avoid limits or gain access.
|
|
71
|
+
|
|
72
|
+
1. Read the full page or node and retain its epoch, revision and stable block IDs.
|
|
73
|
+
Identify the requested change separately from the rest of the document.
|
|
74
|
+
2. Prepare one immutable operation. After a timeout, establish that operation's
|
|
75
|
+
outcome before sending any replacement; a fresh read alone cannot settle an
|
|
76
|
+
uncertain command.
|
|
77
|
+
3. If the service definitively reports `revision_conflict`, read the current
|
|
78
|
+
record again. Keep the other agent's contribution and all unrelated IDs,
|
|
79
|
+
references, source provenance and access fields.
|
|
80
|
+
4. If the changes are compatible, apply only the intended edit to the new full
|
|
81
|
+
content and prepare a **new operation ID** using the newly read revision.
|
|
82
|
+
For conflicting claims or incompatible edits, leave the current record intact
|
|
83
|
+
and present the conflict or an explicitly labeled proposal to the user. Do not
|
|
84
|
+
decide that your version is authoritative because it came from an agent.
|
|
85
|
+
5. Read back the saved result. Report the source ID/revision and the verified
|
|
86
|
+
change. Refresh relevant documentation mirrors after the source is confirmed.
|
|
87
|
+
|
|
88
|
+
`sourceId`, `authority`, `provenance` and `metadataJson` describe the content;
|
|
89
|
+
they are not verified identity, permission or proof of factual correctness.
|
|
90
|
+
Preserve original attribution and distinguish evidence from a new proposal.
|
|
91
|
+
The read-only `lastAgentActor`, when available on a page, node or edge, identifies
|
|
92
|
+
the server-verified latest agent editor (`ownerId`, `profileId`, `profileName`).
|
|
93
|
+
Never send or forge it in an edit. A human edit clears it; an older record without
|
|
94
|
+
the field has unknown agent attribution, not proof of human authorship. This
|
|
95
|
+
latest-editor snapshot is not a complete audit history or a claim that its
|
|
96
|
+
content has been fact-checked.
|
|
97
|
+
For local CLI/MCP retain the journal operation ID. For hosted ChatGPT retain the
|
|
98
|
+
complete prepared command and retry it with the discovered Memory edit tool;
|
|
99
|
+
the host cannot read a local journal or repository filesystem.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: geniustasker-planning
|
|
3
|
-
description: Use when the user asks to plan GeniusTasker tickets
|
|
3
|
+
description: Use when the user asks to plan GeniusTasker tickets, reuse a task protocol, manage projects/sprints/recurrences/documents, customize project tags or saved filters, or review task dependencies.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Plan tasks and shared project workflows
|
|
@@ -9,6 +9,11 @@ Inspect identity and capabilities, then read `tasker_workflow` with
|
|
|
9
9
|
`topic: planning` for the current transport and product instructions.
|
|
10
10
|
|
|
11
11
|
Read the project configuration, relevant tasks and existing sprint/workflow IDs.
|
|
12
|
+
For reusable multi-task procedures, read [Task protocols](../geniustasker/references/protocols.md)
|
|
13
|
+
and `tasker_workflow` with `topic: protocols`. Preview creates no work; applying
|
|
14
|
+
the requested procedure uses explicit journaled batches with current revisions.
|
|
15
|
+
When creating or reassessing tasks, use [task importance](../geniustasker/references/importance.md)
|
|
16
|
+
to distinguish impact from urgency and preserve human-owned classifications.
|
|
12
17
|
Use ticket.plan for placement changes and preserve its root and per-task revision
|
|
13
18
|
checks. Project tags and saved filters are shared configuration; do not turn an
|
|
14
19
|
example label into a global requirement for every project.
|