okstra 0.123.0 โ 0.125.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/README.md +1 -0
- package/docs/architecture/storage-model.md +3 -1
- package/docs/architecture.md +16 -2
- package/docs/cli.md +3 -1
- package/docs/for-ai/README.md +41 -35
- package/docs/for-ai/skills/okstra-brief-gen.md +105 -105
- package/docs/for-ai/skills/okstra-container-build.md +61 -61
- package/docs/for-ai/skills/okstra-graphify.md +64 -0
- package/docs/for-ai/skills/okstra-inspect.md +87 -86
- package/docs/for-ai/skills/okstra-manager.md +32 -32
- package/docs/for-ai/skills/okstra-memory.md +49 -50
- package/docs/for-ai/skills/okstra-pr-gen.md +48 -0
- package/docs/for-ai/skills/okstra-rollup.md +58 -58
- package/docs/for-ai/skills/okstra-run.md +95 -95
- package/docs/for-ai/skills/okstra-schedule-gen.md +106 -106
- package/docs/for-ai/skills/okstra-setup.md +63 -64
- package/docs/for-ai/skills/okstra-user-response.md +48 -0
- package/docs/performance-improvement-plan-v2.md +6 -6
- package/docs/pr-template-usage.md +34 -34
- package/docs/project-structure-overview.md +91 -70
- package/docs/task-process/README.md +33 -33
- package/docs/task-process/common-flow.md +26 -26
- package/docs/task-process/error-analysis.md +20 -21
- package/docs/task-process/final-verification.md +41 -41
- package/docs/task-process/implementation-planning.md +33 -33
- package/docs/task-process/implementation.md +38 -38
- package/docs/task-process/release-handoff.md +46 -46
- package/docs/task-process/requirements-discovery.md +22 -23
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/workers/antigravity-worker.md +4 -4
- package/runtime/agents/workers/claude-worker.md +2 -2
- package/runtime/agents/workers/codex-worker.md +4 -4
- package/runtime/agents/workers/report-writer-worker.md +4 -4
- package/runtime/bin/lib/okstra/usage.sh +1 -1
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +1 -1
- package/runtime/prompts/launch.template.md +1 -1
- package/runtime/prompts/lead/convergence.md +10 -20
- package/runtime/prompts/lead/okstra-lead-contract.md +15 -17
- package/runtime/prompts/lead/plan-body-verification.md +18 -18
- package/runtime/prompts/lead/report-writer.md +46 -44
- package/runtime/prompts/lead/team-contract.md +11 -122
- package/runtime/prompts/profiles/_common-contract.md +15 -22
- package/runtime/prompts/profiles/_implementation-deliverable.md +1 -1
- package/runtime/prompts/profiles/_implementation-executor.md +1 -1
- package/runtime/prompts/profiles/_implementation-verifier.md +28 -2
- package/runtime/prompts/profiles/error-analysis.md +2 -2
- package/runtime/prompts/profiles/final-verification.md +1 -1
- package/runtime/prompts/profiles/implementation-planning.md +13 -13
- package/runtime/prompts/profiles/implementation.md +2 -1
- package/runtime/prompts/profiles/improvement-discovery.md +1 -1
- package/runtime/prompts/profiles/release-handoff.md +3 -3
- package/runtime/prompts/profiles/requirements-discovery.md +17 -18
- package/runtime/python/okstra_ctl/models.py +4 -2
- package/runtime/python/okstra_ctl/run.py +8 -2
- package/runtime/python/okstra_ctl/stage_fix_carry.py +112 -0
- package/runtime/schemas/final-report-v1.0.schema.json +6 -6
- package/runtime/skills/_fragments/bash-invocation-rule.md +1 -0
- package/runtime/skills/_fragments/preflight-outdated-cli.md +1 -0
- package/runtime/skills/_fragments/python-bootstrap-note.md +1 -0
- package/runtime/skills/okstra-brief-gen/SKILL.md +117 -122
- package/runtime/skills/okstra-container-build/SKILL.md +24 -14
- package/runtime/skills/okstra-graphify/SKILL.md +12 -4
- package/runtime/skills/okstra-inspect/SKILL.md +39 -747
- package/runtime/skills/okstra-inspect/facets/cost.md +84 -0
- package/runtime/skills/okstra-inspect/facets/error-zip.md +41 -0
- package/runtime/skills/okstra-inspect/facets/errors.md +69 -0
- package/runtime/skills/okstra-inspect/facets/history.md +90 -0
- package/runtime/skills/okstra-inspect/facets/logs.md +89 -0
- package/runtime/skills/okstra-inspect/facets/recap.md +96 -0
- package/runtime/skills/okstra-inspect/facets/report.md +61 -0
- package/runtime/skills/okstra-inspect/facets/status.md +145 -0
- package/runtime/skills/okstra-inspect/facets/time.md +56 -0
- package/runtime/skills/okstra-manager/SKILL.md +1 -1
- package/runtime/skills/okstra-memory/SKILL.md +3 -3
- package/runtime/skills/okstra-pr-gen/SKILL.md +3 -3
- package/runtime/skills/okstra-rollup/SKILL.md +12 -6
- package/runtime/skills/okstra-run/SKILL.md +49 -88
- package/runtime/skills/okstra-schedule-gen/SKILL.md +36 -30
- package/runtime/skills/okstra-setup/SKILL.md +1 -1
- package/runtime/skills/okstra-setup/references/project-config.md +17 -16
- package/runtime/skills/okstra-usage/SKILL.md +5 -2
- package/runtime/skills/okstra-user-response/SKILL.md +15 -3
- package/runtime/templates/prd/brief.template.md +92 -92
- package/runtime/templates/project-docs/task-index.template.md +1 -1
- package/runtime/templates/reports/error-analysis-input.template.md +1 -1
- package/runtime/templates/reports/fan-out-unit.template.md +6 -6
- package/runtime/templates/reports/final-verification-input.template.md +6 -6
- package/runtime/templates/reports/implementation-input.template.md +1 -1
- package/runtime/templates/reports/implementation-planning-input.template.md +1 -1
- package/runtime/templates/reports/improvement-discovery-input.template.md +1 -1
- package/runtime/templates/reports/quick-input.template.md +1 -1
- package/runtime/templates/reports/release-handoff-input.template.md +1 -1
- package/runtime/templates/reports/schedule.template.md +22 -22
- package/runtime/templates/reports/task-brief.template.md +3 -3
- package/runtime/templates/reports/user-response.template.md +20 -20
- package/runtime/templates/worker-prompt-preamble.md +111 -13
- package/runtime/validators/validate-schedule.py +1 -1
|
@@ -1,82 +1,82 @@
|
|
|
1
1
|
# okstra-memory AI Manual
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Source
|
|
4
4
|
|
|
5
|
-
-
|
|
5
|
+
- Skill source: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
|
|
6
6
|
- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
|
|
7
7
|
- memory CLI: [`src/commands/memory/memory.mjs`](../../../src/commands/memory/memory.mjs)
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Purpose
|
|
10
10
|
|
|
11
|
-
`okstra-memory
|
|
11
|
+
`okstra-memory` manages the Memory Book in the user's home.
|
|
12
12
|
|
|
13
13
|
```text
|
|
14
14
|
~/.okstra/memory-book/
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
It is not a project-local `.okstra/` artifact. It can be used even without `<PROJECT_ROOT>/.okstra/project.json`.
|
|
18
18
|
|
|
19
|
-
##
|
|
19
|
+
## When to use
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Use it when:
|
|
22
22
|
|
|
23
|
-
-
|
|
24
|
-
-
|
|
23
|
+
- The user explicitly asks to save, e.g. "remember this", "save the conversation", "organize and store this in okstra", "remember this", "save this decision".
|
|
24
|
+
- The user wants to search, list, read, or archive stored memory.
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Do not use it when:
|
|
27
27
|
|
|
28
|
-
-
|
|
29
|
-
- project task artifact
|
|
28
|
+
- The user is only brainstorming with no save request. In that case, ask a confirmation question first.
|
|
29
|
+
- The content should be kept as a project task artifact. In that case, use the brief/report/decision path of the relevant okstra task.
|
|
30
30
|
|
|
31
31
|
## safety rule
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Do not save without an explicit save request. Do not store credentials, API keys, tokens, private personal data, or secrets. If the conversation includes sensitive material, exclude it from the summary and note the omission.
|
|
34
34
|
|
|
35
|
-
CLI
|
|
35
|
+
The CLI can also detect high-confidence secret shapes and refuse `memory add`. If refused, redact the content and retry.
|
|
36
36
|
|
|
37
37
|
## CLI availability
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
Check the help first.
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
42
|
okstra memory --help
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
-
`okstra
|
|
45
|
+
If `okstra` is not on PATH, do not run `npx okstra@latest install` directly; tell the user to install it once and then retry.
|
|
46
46
|
|
|
47
|
-
## project-group
|
|
47
|
+
## project-group selection
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
Every memory entry belongs to a project-group. Pick the group before storing or searching.
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
Enumerate existing groups:
|
|
52
52
|
|
|
53
53
|
```bash
|
|
54
54
|
okstra memory groups --json
|
|
55
55
|
```
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
Recommendations:
|
|
58
58
|
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
59
|
+
- the most-used existing group
|
|
60
|
+
- the second existing group
|
|
61
|
+
- Enter directly
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
For a personal note, recommend `private` first. If there is no group or no selection, use the CLI default `global`.
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
Pass the chosen group to `add`, `search`, and `list` as `--project-group <group>`. Omit the flag only when the user explicitly wants a cross-group search.
|
|
66
66
|
|
|
67
|
-
##
|
|
67
|
+
## Store procedure
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
Do not store the full conversation transcript. Extract only durable memory worth keeping long-term and turn it into a concise Markdown summary.
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
Include:
|
|
72
72
|
|
|
73
|
-
-
|
|
73
|
+
- the reason for storing
|
|
74
74
|
- source: `conversation`
|
|
75
|
-
-
|
|
76
|
-
-
|
|
75
|
+
- `--project` when the related project id is clear
|
|
76
|
+
- tags for search
|
|
77
77
|
- memory type
|
|
78
78
|
|
|
79
|
-
|
|
79
|
+
The `okstra memory --help` output is authoritative for the type values. Categories per the source:
|
|
80
80
|
|
|
81
81
|
- `decision`
|
|
82
82
|
- `preference`
|
|
@@ -86,19 +86,19 @@ type ๊ฐ์ `okstra memory --help` ์ถ๋ ฅ์ด ๊ถ์๋ค. ์๋ฌธ ๊ธฐ์ค category:
|
|
|
86
86
|
- `follow-up`
|
|
87
87
|
- `context`
|
|
88
88
|
|
|
89
|
-
|
|
89
|
+
Store command shape:
|
|
90
90
|
|
|
91
91
|
```bash
|
|
92
92
|
okstra memory add --content "<summary markdown>" --title "<short title>" --type <type> --project-group <group> --tag <tag> --project <id> --source conversation --yes
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
-
|
|
95
|
+
Repeat `--tag` and `--project` as needed. Omit `--project` when no related project is clear.
|
|
96
96
|
|
|
97
|
-
`--yes
|
|
97
|
+
Use `--yes` only when the user explicitly asked to save.
|
|
98
98
|
|
|
99
|
-
##
|
|
99
|
+
## search / read / archive
|
|
100
100
|
|
|
101
|
-
|
|
101
|
+
The default scope is the chosen project-group.
|
|
102
102
|
|
|
103
103
|
```bash
|
|
104
104
|
okstra memory search "<query>" --project-group "<group>"
|
|
@@ -108,20 +108,19 @@ okstra memory show "<memory-id>"
|
|
|
108
108
|
okstra memory archive "<memory-id>"
|
|
109
109
|
```
|
|
110
110
|
|
|
111
|
-
|
|
111
|
+
Prefer `--json` when you need to parse IDs. Show the user only a short summary plus the entry id/path.
|
|
112
112
|
|
|
113
|
-
##
|
|
113
|
+
## Output rules
|
|
114
114
|
|
|
115
|
-
-
|
|
116
|
-
-
|
|
117
|
-
- archive
|
|
118
|
-
- project `.okstra
|
|
115
|
+
- On store, summarize title, type, project-group, tags, and the generated id.
|
|
116
|
+
- On search, show the match count and the most relevant entry first.
|
|
117
|
+
- Run archive only when the user's intent is clear.
|
|
118
|
+
- Do not write into a project `.okstra/`.
|
|
119
119
|
|
|
120
|
-
##
|
|
121
|
-
|
|
122
|
-
- ๋ช
์ ์์ฒญ ์์ด ์๋ ์ ์ฅ.
|
|
123
|
-
- secret/token/key๋ฅผ ์ ์ฅ.
|
|
124
|
-
- full transcript๋ฅผ ๊ทธ๋๋ก ์ ์ฅ.
|
|
125
|
-
- project-local task memory์ฒ๋ผ `.okstra/`์ ์ฐ๊ธฐ.
|
|
126
|
-
- cross-group search๋ฅผ ์ฌ์ฉ์๊ฐ ์์ฒญํ์ง ์์๋๋ฐ ๊ธฐ๋ณธ์ผ๋ก ์ํํ๊ธฐ.
|
|
120
|
+
## Forbidden patterns
|
|
127
121
|
|
|
122
|
+
- Auto-saving without an explicit request.
|
|
123
|
+
- Storing a secret/token/key.
|
|
124
|
+
- Storing the full transcript verbatim.
|
|
125
|
+
- Writing into `.okstra/` as if it were project-local task memory.
|
|
126
|
+
- Performing a cross-group search by default when the user did not ask for it.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# okstra-pr-gen AI Manual
|
|
2
|
+
|
|
3
|
+
## Sources
|
|
4
|
+
|
|
5
|
+
- Skill source: [`skills/okstra-pr-gen/SKILL.md`](../../../skills/okstra-pr-gen/SKILL.md)
|
|
6
|
+
- Template core (CLI): [`scripts/okstra_ctl/pr_template.py`](../../../scripts/okstra_ctl/pr_template.py)
|
|
7
|
+
- Node wrapper: [`src/commands/pr/pr.mjs`](../../../src/commands/pr/pr.mjs)
|
|
8
|
+
- Bundled default template: [`src/commands/pr/default.md`](../../../src/commands/pr/default.md)
|
|
9
|
+
|
|
10
|
+
## Purpose
|
|
11
|
+
|
|
12
|
+
`okstra-pr-gen` registers PR body templates and generates PR descriptions from a branch diff. Templates live in the user home at `~/.okstra/template/pr/`. This skill is **global** โ it does not require `<PROJECT_ROOT>/.okstra/project.json`. PR generation additionally requires the current directory to be a git repository.
|
|
13
|
+
|
|
14
|
+
## Check CLI availability
|
|
15
|
+
|
|
16
|
+
A separate Bash call with a literal leading token:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
okstra pr --help
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
If `okstra` is not on PATH: `okstra not installed โ run npx okstra@latest install once, then retry`. Every Bash command starts with the literal `okstra` token and passes literal arguments (do not wrap it in `$(...)`/leading `VAR=`/`if`/`eval`/`||`/`&&`).
|
|
23
|
+
|
|
24
|
+
## Pick the mode (always first)
|
|
25
|
+
|
|
26
|
+
A 3-option picker via `AskUserQuestion`:
|
|
27
|
+
|
|
28
|
+
1. `Generate PR` โ generate a PR body from a branch diff
|
|
29
|
+
2. `Register template` โ save a new PR body template
|
|
30
|
+
3. `Enter directly` โ always last (okstra picker convention)
|
|
31
|
+
|
|
32
|
+
## Mode A โ Generate PR
|
|
33
|
+
|
|
34
|
+
1. Pick a template: `okstra pr template list --json`. If empty, use the bundled default. Carry the chosen name as `<template>` (`default` for the bundled one).
|
|
35
|
+
2. Pick the base branch: `okstra pr branches --json`. 3-option from the top `recommended` entries plus `Enter directly`. Carry the choice as `<base>`.
|
|
36
|
+
3. Generation bundle: `okstra pr gen --base <base> --template <template> --json` โ `{base, currentBranch, templateName, template, commits, diffStat}`. Then **read the real diff honestly** (SSOT): `git diff <base>...HEAD` (large diffs section by section). Fill the placeholders from the diff and commits, describing **only actual changes**. Mark a checklist box `[x]` only when the diff supports it (tests touched โ tests box, docs touched โ docs box). If `commits`/`diffStat` are empty, say there is nothing to describe and stop. **Never append AI trailers/footers.**
|
|
37
|
+
4. Output and offer to create the PR: print the filled PR body as a single fenced markdown block. Ask whether to open a PR. **Only on an explicit yes**: write the body to a temp file and run `gh pr create --base <base> --title "<title>" --body-file <path>`. If `gh` is missing or unauthenticated (`gh auth status` fails), leave the text in chat and give manual-creation guidance. **No push/PR creation without the user's confirmation.**
|
|
38
|
+
|
|
39
|
+
## Mode B โ Register template
|
|
40
|
+
|
|
41
|
+
1. Template name (`AskUserQuestion`, free text) โ must match `^[A-Za-z0-9._-]+$`, otherwise re-ask.
|
|
42
|
+
2. body โ pasted text or an absolute path.
|
|
43
|
+
3. Save: `okstra pr template add --name <name> --file <abs-path>` (or, for pasted text, `--content "<body>"`). Add `--yes` only when the user confirmed overwriting a same-named template. Report the saved path (`saved: ...`).
|
|
44
|
+
|
|
45
|
+
## Output Rules
|
|
46
|
+
|
|
47
|
+
- Not read-side โ write actions (PR creation, template saving) happen only after the user's explicit confirmation.
|
|
48
|
+
- Do not invent changes not in the diff. Stop if commit/diffStat is empty.
|
|
@@ -1,82 +1,82 @@
|
|
|
1
1
|
# okstra-rollup AI Manual
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Source
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
-
|
|
7
|
-
- Node
|
|
8
|
-
-
|
|
9
|
-
- catalog
|
|
10
|
-
-
|
|
5
|
+
- Skill source: [`skills/okstra-rollup/SKILL.md`](../../../skills/okstra-rollup/SKILL.md)
|
|
6
|
+
- aggregation core (CLI): [`scripts/okstra_ctl/rollup.py`](../../../scripts/okstra_ctl/rollup.py)
|
|
7
|
+
- Node wrapper: [`src/commands/inspect/rollup.mjs`](../../../src/commands/inspect/rollup.mjs)
|
|
8
|
+
- reused single-task aggregators: [`scripts/okstra_ctl/time_report.py`](../../../scripts/okstra_ctl/time_report.py), [`scripts/okstra_ctl/error_log_core.py`](../../../scripts/okstra_ctl/error_log_core.py)
|
|
9
|
+
- catalog enumeration helper: [`scripts/okstra_project/state.py`](../../../scripts/okstra_project/state.py) (`list_project_tasks`)
|
|
10
|
+
- unit tests: [`tests/inspect/test_okstra_rollup.py`](../../../tests/inspect/test_okstra_rollup.py)
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## Purpose
|
|
13
13
|
|
|
14
|
-
`okstra-rollup
|
|
14
|
+
`okstra-rollup` **collects and summarizes the run results of multiple tasks at once**. It is a cross-task read-side layer, in contrast to `okstra-inspect` which looks at a single task.
|
|
15
15
|
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
16
|
+
- Input scope: one task-group, or the whole-project catalog when `--task-group` is omitted.
|
|
17
|
+
- Deterministic aggregation (counts, time sums, error sums, status/category/phase distributions) is handled entirely by the `okstra rollup` CLI. The skill renders that table and reads each task's report body to write a **cross-task synthesis (digest)**.
|
|
18
|
+
- Design principle: hand-computed aggregation is error-prone for an LLM, so it is pushed to the CLI (SSOT), and only the natural-language synthesis is left to the LLM. This is the same division of labor as `okstra-inspect time`, which insists on "never re-sum the time by hand".
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
This skill is read-only. It does not mutate task artifacts.
|
|
21
21
|
|
|
22
|
-
##
|
|
22
|
+
## When to use
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
Use it when:
|
|
25
25
|
|
|
26
|
-
-
|
|
27
|
-
-
|
|
26
|
+
- The user asks for "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "run results all at once".
|
|
27
|
+
- You want to look across **multiple tasks** rather than a single one.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Do not use it when:
|
|
30
30
|
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
31
|
+
- A single task's report/time/errors/recap โ `okstra-inspect` (report / time / errors / recap facet).
|
|
32
|
+
- A forward-looking work plan (a client-facing schedule of non-done tasks) โ `okstra-schedule-gen`. rollup is **retrospective**, collecting past run results; schedule is **forward-looking**, planning future work.
|
|
33
|
+
- Actual phase execution โ `okstra-run`.
|
|
34
34
|
|
|
35
35
|
## Preflight
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
A single Bash call starting with the literal `okstra` token (not wrapped in `if`/`eval`/`$(...)`/`VAR=`/`||`/`&&`/`npx` fallback):
|
|
38
38
|
|
|
39
39
|
```bash
|
|
40
40
|
okstra preflight --runtime claude-code --json
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
`ok:false` โ `/okstra-setup`
|
|
43
|
+
`ok:false` โ point to `/okstra-setup` and stop. If `ok:true`, carry `projectRoot` as a literal string and proceed.
|
|
44
44
|
|
|
45
|
-
## scope
|
|
45
|
+
## scope resolution
|
|
46
46
|
|
|
47
|
-
-
|
|
48
|
-
- "
|
|
49
|
-
-
|
|
47
|
+
- The user named a task-group ("summarize the alpha group") โ `--task-group <group>`.
|
|
48
|
+
- "all tasks" / "the whole project" / no scope named โ omit `--task-group` (whole catalog).
|
|
49
|
+
- If genuinely ambiguous, ask once: one task-group or the whole project? Do not silently guess a specific group.
|
|
50
50
|
|
|
51
|
-
## CLI
|
|
51
|
+
## CLI call
|
|
52
52
|
|
|
53
53
|
```bash
|
|
54
54
|
okstra rollup --task-group <group> --project-root <projectRoot> --json
|
|
55
55
|
```
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
For the whole project, drop `--task-group`. The output is always JSON, and **all times are raw milliseconds**.
|
|
58
58
|
|
|
59
|
-
##
|
|
59
|
+
## Interpreting the output
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
Top level:
|
|
62
62
|
|
|
63
|
-
- `taskGroup` โ
|
|
64
|
-
- `tasks[]` โ task
|
|
65
|
-
- `totals` โ `runs, cpuSumMs, wallClockMs, errors`,
|
|
63
|
+
- `taskGroup` โ the scope (`null` = whole project), `taskCount` โ number of tasks.
|
|
64
|
+
- `tasks[]` โ per task: `taskKey, taskGroup, taskId, taskType, workCategory, workStatus, currentPhase, currentPhaseState, nextRecommendedPhase, latestRunStatus, updatedAt, reportPath, runCount, cpuSumMs, wallClockMs, errorCount`.
|
|
65
|
+
- `totals` โ `runs, cpuSumMs, wallClockMs, errors`, plus `byWorkStatus` / `byWorkCategory` / `byCurrentPhase` / `byTaskType` (each a `{value: count}` map).
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
Numeric meanings (must observe):
|
|
68
68
|
|
|
69
|
-
- `runCount
|
|
70
|
-
- `cpuSumMs
|
|
71
|
-
- `reportPath
|
|
72
|
-
- `taskCount
|
|
69
|
+
- `runCount` is the **total number of runs** in the timeline. `cpuSumMs`/`wallClockMs` reflect only runs that reached Phase 7 usage, so they can be `0` even when `runCount > 0`.
|
|
70
|
+
- `cpuSumMs` is the **CPU sum** of the overlapping lead + workers, not wall-clock. Label it "CPU", and show wall-clock as `wallClockMs` only when the user explicitly asks.
|
|
71
|
+
- `reportPath` is project-relative and may be empty (a task with no report yet).
|
|
72
|
+
- If `taskCount` is `0`, say there are no okstra tasks in that scope and stop.
|
|
73
73
|
|
|
74
|
-
##
|
|
74
|
+
## Render
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
Convert every `*Ms` to `HH:MM:SS` (zero-pad; never expose raw ms โ the same rule as `okstra-inspect time`). Sort tasks by `updatedAt` descending.
|
|
77
77
|
|
|
78
78
|
```markdown
|
|
79
|
-
## okstra Rollup โ <task-group
|
|
79
|
+
## okstra Rollup โ <task-group or "whole project"> (<taskCount> tasks)
|
|
80
80
|
|
|
81
81
|
| Task | Category | workStatus | Phase | Runs | CPU | Errors | Report |
|
|
82
82
|
|------|----------|------------|-------|------|-----|--------|--------|
|
|
@@ -87,26 +87,26 @@ okstra rollup --task-group <group> --project-root <projectRoot> --json
|
|
|
87
87
|
**workStatus:** done 1 ยท in-progress 1 **category:** bugfix 1 ยท feature 1
|
|
88
88
|
```
|
|
89
89
|
|
|
90
|
-
- `Report`
|
|
91
|
-
-
|
|
90
|
+
- `Report` column: `โ` when `reportPath` is present, `โ` when not.
|
|
91
|
+
- Build the status/category/phase lines from the `totals` tally maps **verbatim**. Do not count the `tasks[]` array yourself (the CLI is the SSOT for aggregation).
|
|
92
92
|
|
|
93
|
-
## digest
|
|
93
|
+
## Writing the digest (the summary โ the skill's core value)
|
|
94
94
|
|
|
95
|
-
|
|
95
|
+
When the user asks to "summarize"/"organize"/"summarize"/"digest" (the common case):
|
|
96
96
|
|
|
97
|
-
1. `reportPath
|
|
98
|
-
2. per-task
|
|
99
|
-
3.
|
|
97
|
+
1. For each task with a non-empty `reportPath` whose `<projectRoot>/<reportPath>` file actually exists, read the report and summarize in 1โ2 lines **what it accomplished and its recommended next step**.
|
|
98
|
+
2. Above the per-task lines, write a 2โ4 sentence group-level synthesis: what was delivered across the group, where the open work sits (using `byWorkStatus`/`byCurrentPhase`), and whether there are error hot-spots (tasks with high `errorCount`).
|
|
99
|
+
3. Cite each per-task claim with the report path (`<reportPath>`) so the reader can open it directly.
|
|
100
100
|
|
|
101
|
-
|
|
101
|
+
For a task with no report, do not invent a summary; state the current phase/workStatus instead. Do not read non-report artifacts to fill the gap (artifact-home rule). If a report is empty or missing, say so.
|
|
102
102
|
|
|
103
|
-
|
|
103
|
+
If a deep single-task drill-down (full report, per-worker time, error breakdown, run-to-run recap) is needed, point the user to `/okstra-inspect`.
|
|
104
104
|
|
|
105
|
-
##
|
|
105
|
+
## Forbidden patterns
|
|
106
106
|
|
|
107
|
-
-
|
|
108
|
-
- raw ms
|
|
109
|
-
- `cpuSumMs
|
|
110
|
-
-
|
|
111
|
-
- okstra
|
|
112
|
-
-
|
|
107
|
+
- Re-counting aggregate numbers (totals, distributions) by hand from `tasks[]`. `totals` is the SSOT.
|
|
108
|
+
- Exposing raw ms. Always `HH:MM:SS`.
|
|
109
|
+
- Labeling `cpuSumMs` as if it were wall-clock.
|
|
110
|
+
- Inventing a summary for a task with no report. Substitute the current phase/workStatus.
|
|
111
|
+
- Reading files outside okstra artifacts (non-`.okstra`) to fill the summary.
|
|
112
|
+
- Handling single-task detail in rollup. Send it to `okstra-inspect`.
|