@staff0rd/assist 0.1008.0 → 0.1009.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.
@@ -110,10 +110,12 @@ Use the same permalink verbatim for both the ref and `--url`, and the item's nam
110
110
 
111
111
  Then show the user the item was created. If `propose` printed `Started a backlog run session for a<id>.`, the user chose **Approve & start** and implementation is already running — say so, and do not suggest running it. Otherwise suggest they can run `assist backlog run a<id>` to start implementation.
112
112
 
113
- Finally, signal that the bug-filing task is complete, passing the created item id (a-prefixed, e.g. `a555`):
113
+ If the conversation established that more items still need to be filed (e.g. a follow-up item, or one in another repo), do not signal yet — create each remaining item now, repeating Steps 3 and 4 for it.
114
+
115
+ Finally, once the last item is created, signal that the bug-filing task is complete, passing every item id created in this session (a-prefixed, e.g. `a555 a556`):
114
116
 
115
117
  ```
116
- assist signal done a<id> 2>&1
118
+ assist signal done a<id> [a<id> ...] 2>&1
117
119
  ```
118
120
 
119
- This lets a wrapping `assist bug --once` session end and surfaces the created item id to the session card; in a plain interactive session it has no effect.
121
+ This ends a wrapping `assist bug --once` session, so run it only once and only after the last item, and it surfaces every created id on the session card; in a plain interactive session it has no effect.
@@ -1,79 +1,66 @@
1
1
  ---
2
- description: Generate devlog entry for the next unversioned day
2
+ description: Generate the weekly dev entry for the next unwritten ISO week
3
3
  allowed_args: "[--all]"
4
4
  ---
5
5
 
6
- Parse `$ARGUMENTS`: if `--all` is present, enable **catch-up mode** (described below). Otherwise, process a single day as normal.
6
+ Parse `$ARGUMENTS`: if `--all` is present, enable **catch-up mode** (described below). Otherwise, process a single week.
7
7
 
8
- ## Single-day mode (default)
8
+ ## Single-week mode (default)
9
9
 
10
- Run `assist devlog next` to get the next unversioned day's commits and version options.
10
+ Run `assist devlog next`. It prints the project `name`, the ISO `week` (e.g. `2026-W33`), its Monday–Sunday `range`, the `versions` range, and every commit in the week oldest first, each tagged with the version from `package.json` at that commit (no version is shown when the repo has none). It only ever offers completed weeks; if it reports nothing to write, stop.
11
11
 
12
- Analyze the commits for that day to determine the appropriate action:
12
+ Decide whether the week is worth an entry:
13
13
 
14
- 1. **Trivial changes** (typos, formatting, config tweaks, dependency updates): Run `assist devlog skip YYYY-MM-DD` and stop. Check the diff before skipping to ensure no meaningful changes were made.
14
+ - **Trivial week** (only typos, formatting, config tweaks, dependency updates, release commits): check the diffs to confirm nothing meaningful changed, then run `assist devlog skip <week>` (e.g. `assist devlog skip 2026-W33`) and stop.
15
+ - Otherwise write the entry below.
15
16
 
16
- 2. **Bug fixes** (fixing broken behavior, error handling, corrections): Use the **patch** version.
17
+ ## Entry file
17
18
 
18
- 3. **New features** (new functionality, enhancements, new commands): Use the **minor** version.
19
-
20
- If creating a devlog entry:
21
-
22
- 1. Write a summary in first-person perspective describing the changes
23
- 2. Create a file in `~/git/blog/src/content/devlog/` with the format `YYYY-MM-DD-slug.md`
24
-
25
- The slug should be a short kebab-case description of the main theme of the day's work.
26
-
27
- Each devlog file should follow this format:
19
+ Write `~/git/blog/src/content/dev/<name>/<yyyy>-w<NN>.md`, where `<name>` is the `name` from `assist devlog next` and the filename is the week id lowercased (`2026-W33` → `2026-w33.md`). Create the `<name>` directory if needed.
28
20
 
29
21
  ```markdown
30
22
  ---
31
- title: <short descriptive title>
32
- date: YYYY-MM-DD
33
- version: <selected version>
34
- tags: [<name from the next command output>, <additional-tag>, ...]
35
- ai-generated: <model name, e.g., "claude-opus-4-5">
23
+ project: <name>
24
+ week: <week id, e.g. 2026-W33>
25
+ title: <one-line headline of the week's main themes>
26
+ versions:
27
+ first: <earliest version in the week>
28
+ last: <latest version in the week>
29
+ ai-generated: <model name, e.g. claude-opus-5>
30
+ added:
31
+ - text: <one line describing something new>
32
+ version: <version of the commit(s) it came from>
33
+ changed:
34
+ - text: <one line describing a change to existing behaviour>
35
+ version: <version>
36
+ fixed:
37
+ - text: <one line describing a fix>
38
+ version: <version>
36
39
  ---
37
40
 
38
- <First-person summary of the day's work. Group related commits into cohesive paragraphs. Focus on what was accomplished and why, not implementation details. Wrap code symbols (function names, variable names, file names, commands, etc.) in backticks.>
41
+ <1-2 sentence lede summarising what the week was about.>
39
42
  ```
40
43
 
41
- ## One post per version
42
-
43
- Navigation is keyed by `version`, so **every version may appear in at most one devlog file**. Because `assist devlog next` reports the day's `major.minor` version, consecutive days that only shipped patch releases report the _same_ version — these must not become separate posts.
44
-
45
- Before creating a file, check `~/git/blog/src/content/devlog/` for an existing entry whose `version` matches the one being written:
44
+ - **title**: a terse headline naming the week's 2-3 main themes (e.g. `Comment previews, Windows config writes, collapsible sidebar`), not a sentence.
45
+ - **versions**: the first and last versions reported by `assist devlog next`. Omit `versions` entirely when the repo has no versions.
46
+ - **added / changed / fixed**: one line per user-visible change, newest version first within each list. Merge related commits into one line and drop release commits, refactors, tests and other internal-only work. Use `feat:` commits as a hint for **added** and `fix:` for **fixed**, but classify by what changed for the user. Omit a list that would be empty.
47
+ - **version** on each line: the version shown against the commit(s) the line came from (the latest one when several commits are merged). Omit `version` when the repo has no versions.
48
+ - Write each line as a short changelog item, not first-person prose. Wrap code symbols (commands, function names, file names, config keys) in backticks.
49
+ - **lede**: one or two sentences, conversational, saying what the week was mostly about and why it matters.
46
50
 
47
- - **If a post with that version already exists**, merge the new day's work into it as additional paragraph(s) instead of creating a new file. Keep the existing post's `date` (the date the version was first cut) and its `title`/`slug`; widen the title only if the merged scope no longer fits it.
48
- - **If several unversioned days share one version** (catch-up mode), write a single post anchored on the earliest of those days and fold the later days' work into it.
49
-
50
- ## Tag Selection
51
-
52
- Fetch existing tags from https://staffordwilliams.com/tags.json for use when selecting tags.
53
-
54
- - The **first tag must always be the repo name** from the `assist devlog next` output
55
- - Add 1-3 additional tags relevant to the day's work (technologies, patterns, topics)
56
- - **Strongly prefer existing tags** from the fetched list over creating new ones
57
- - If a candidate tag is semantically similar to an existing tag, use the existing one (e.g., use `selenium` instead of creating `webdriver` or `selenium-webdriver`)
58
- - Only create a new tag when no existing tag adequately covers the topic
59
- - Do not include tags that are too broad or generic (e.g., `javascript`, `web`, `tooling`)
60
-
61
- Read existing devlogs in `~/git/blog/src/content/devlog/` for style inspiration if needed. The tone should be conversational and concise.
51
+ Read existing entries in `~/git/blog/src/content/dev/` for style if any exist.
62
52
 
63
53
  ## Catch-up mode (`--all`)
64
54
 
65
- When `--all` is passed, loop through all unversioned days up to (excluding) today:
66
-
67
- 1. Run `assist devlog next` to get the next unversioned day
68
- 2. If the target date is today, **stop** — catch-up is complete
69
- 3. If there are no more unversioned days, **stop**
70
- 4. Analyze the commits for that day:
71
- - **Trivial days**: automatically run `assist devlog skip YYYY-MM-DD` without prompting the user
72
- - **Non-trivial days**: create the devlog entry as normal (following the single-day instructions above), honouring the **One post per version** rule — if the reported version already has a post, merge into it rather than creating a new file
73
- 5. Go back to step 1
55
+ Loop through every completed unwritten week:
74
56
 
75
- This continues until all past unversioned days have been processed. Do not process today's date.
57
+ 1. Run `assist devlog next`
58
+ 2. If it reports nothing to write, **stop** — catch-up is complete
59
+ 3. For the reported week:
60
+ - **Trivial week**: run `assist devlog skip <week>` without prompting the user
61
+ - **Otherwise**: write the entry as in single-week mode
62
+ 4. Go back to step 1
76
63
 
77
64
  ## Important
78
65
 
79
- - Do not commit entries, these will be manually reviewed before publishing.
66
+ - Do not commit entries; they are manually reviewed before publishing.
@@ -144,10 +144,12 @@ Use the same permalink verbatim for both the ref and `--url`, and the item's nam
144
144
 
145
145
  Then show the user the item was created. If `propose` printed `Started a backlog run session for a<id>.`, the user chose **Approve & start** and implementation is already running — say so, and do not suggest running it. Otherwise suggest they can run `assist backlog run a<id>` to start implementation.
146
146
 
147
- Finally, signal that the drafting task is complete, passing the created item id (a-prefixed, e.g. `a555`):
147
+ If the conversation established that more items still need to be drafted (e.g. a follow-up item, or one in another repo), do not signal yet — draft each remaining item now, repeating Steps 3 and 4 for it.
148
+
149
+ Finally, once the last item is created, signal that the drafting task is complete, passing every item id created in this session (a-prefixed, e.g. `a555 a556`):
148
150
 
149
151
  ```
150
- assist signal done a<id> 2>&1
152
+ assist signal done a<id> [a<id> ...] 2>&1
151
153
  ```
152
154
 
153
- This lets a wrapping `assist draft --once` session end and surfaces the created item id to the session card; in a plain interactive session it has no effect.
155
+ This ends a wrapping `assist draft --once` session, so run it only once and only after the last item, and it surfaces every created id on the session card; in a plain interactive session it has no effect.
@@ -104,10 +104,10 @@ Ask if there is anything else to refine. Continue the conversation until the use
104
104
 
105
105
  ## Step 5: Signal completion
106
106
 
107
- Once the user confirms they are done refining, signal that the task is complete:
107
+ Once the user confirms they are done refining — and any new items the conversation called for (e.g. a split-out follow-up) have been created — signal that the task is complete, passing the ids of any items created in this session:
108
108
 
109
109
  ```
110
- assist signal done 2>&1
110
+ assist signal done [a<id> ...] 2>&1
111
111
  ```
112
112
 
113
113
  This lets a wrapping `assist refine --once` session end; in a plain interactive session it has no effect.