@puffinstudio/fizzyx 1.3.1 → 1.5.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 CHANGED
@@ -15,9 +15,9 @@ bun add -g @puffinstudio/fizzyx
15
15
  Use `.fizzyx.yaml` as the project config file for board and workflow settings.
16
16
 
17
17
  ```sh
18
- fizzyx flow work
19
- fizzyx flow list [--indexed-by <lane>] [--search <terms>] [--json]
20
- fizzyx flow search "<query>" [--all-boards] [--json]
18
+ fizzyx flow work [--agent]
19
+ fizzyx flow list [--indexed-by <lane>] [--search <terms>] [--json [--full]]
20
+ fizzyx flow search "<query>" [--all-boards] [--json [--full]]
21
21
  fizzyx flow columns
22
22
  fizzyx flow create --draft
23
23
  fizzyx flow create "<title>" --desc <draft-path>
@@ -27,11 +27,11 @@ fizzyx flow edit <card> [--title "<title>"] [--desc <file|->]
27
27
  fizzyx flow assign <card> <user>
28
28
  fizzyx flow comment <card> "<single-line body>"
29
29
  fizzyx flow comment <card> --body-file <markdown-file|->
30
- fizzyx flow show <card>
30
+ fizzyx flow show <card> [--check <n> | --uncheck <n>] [--json [--full]]
31
31
  fizzyx flow move <card> <column-id-or-name>
32
32
  fizzyx flow start <card>
33
33
  fizzyx flow review <card>
34
- fizzyx flow done <card> "commit <sha>: <subject>"
34
+ fizzyx flow done <card> ["<closing note>"] [--complete-steps]
35
35
  fizzyx flow reopen <card>
36
36
  fizzyx flow block <card> "<reason>"
37
37
  fizzyx flow unblock <card> "<reason>"
@@ -40,7 +40,9 @@ fizzyx flow doctor
40
40
  fizzyx flow repair
41
41
  ```
42
42
 
43
- `flow done` requires all steps to be complete and closes the card into Done.
43
+ `flow done` requires all steps to be complete (or `--complete-steps`) and closes the card. It needs no commit or branch reference and never reads git; the optional second argument is a free-text note recorded as a `done:` comment.
44
+ `flow work --agent` prints at most eight lines: your in-progress cards with their step progress and next unchecked step, then the next card.
45
+ `flow edit` requires a `## Steps` list only for a card that already has steps; a document card without steps can be updated from any description.
44
46
  `flow create` expects the standard draft shape with a `## Steps` task list; generate it with `flow create --draft` instead of passing plain text.
45
47
  `flow create` does not assign by default. Use `--assign <user>` while creating or `flow assign <card> <user>` afterwards.
46
48
  Drafts are stored outside the worktree in Git-local state (or the user state directory outside a Git repository). `flow edit <card> --draft` rebuilds one from the remote card.
@@ -49,7 +51,9 @@ Drafts are stored outside the worktree in Git-local state (or the user state dir
49
51
  `flow move` also accepts the Fizzy system targets `maybe`/`triage` and `not-now`; closing remains guarded by `flow done`.
50
52
  `flow list` filters cards on the configured board, while `flow search` uses Fizzy full-text search and filters results back to the project board unless `--all-boards` is passed. `flow comment` records a standardized note and renders safe Markdown as Fizzy rich text; use `--body-file -` for multiline stdin.
51
53
  `flow reopen`, `flow unblock`, and `flow untriage` provide the inverse lifecycle actions. Unblock returns the card to the configured default column; untriage returns it to Fizzy's system Maybe state.
52
- High-frequency flow commands accept `--json` and return an `ok`/`data`/`summary` envelope with next-action breadcrumbs for agents.
54
+ Flow commands print compact text by default, which is the cheapest form for an agent to read. High-frequency commands also accept `--json` and return a single-line `ok`/`data`/`summary` envelope with next-action breadcrumbs. Card lists in JSON are lean (`number`, `title`, `column`, `assignees`, `steps: { done, total }`) and `flow show --json` carries the description once; add `--full` for every field.
55
+ Set `flow.card.language: zh-CN` in `.fizzyx.yaml` to have the built-in card template and the generated `AGENTS.md` instruction ask for card content in Simplified Chinese (default `en`). Headings such as `## Steps` stay English, CLI output is unaffected, and a project-local `.agents/skills/fizzyx/CARD_TEMPLATE.md` still wins.
56
+ `flow.wip_limit` (default 20) caps the in-progress cards of the token's user on the board.
53
57
  Normal flow commands never create or rename board columns. When `flow:` is missing, explicit `fizzyx init` installs the bundled preset; custom boards can map their existing default and in-progress column IDs in `.fizzyx.yaml` and use `flow move` for all other transitions.
54
58
  `flow improve` is retained as a deprecated compatibility alias; use `fizzyx skill run improve-codebase` for the actual codebase workflow.
55
59
 
@@ -60,14 +64,12 @@ project instructions are preserved, and repeated initialization does not duplica
60
64
  Agent loop for card-backed code work:
61
65
 
62
66
  ```sh
63
- fizzyx flow work
67
+ fizzyx flow work --agent # what is in progress, what is next
64
68
  fizzyx flow show <card>
65
- fizzyx dev status --agent
66
- fizzyx dev start <slug> --kind <feature|fix|hotfix|ops|chore|docs> --card <card>
67
69
  fizzyx flow start <card>
68
- fizzyx dev ready --agent
69
- fizzyx flow review <card>
70
- fizzyx flow done <card> "commit <sha>: <subject>"
70
+ fizzyx dev start <slug> --kind <feature|fix|hotfix|ops|chore|docs> --worktree --agent # one worktree per sub-task; cd to worktree_path
71
+ fizzyx flow show <card> --check <n> # tick a step once its work is on the base branch
72
+ fizzyx flow done <card>
71
73
  ```
72
74
 
73
75
  Use `fizzyx skill ...` for bundled skills and project pins. Use flow commands for repair and health checks.
@@ -88,9 +90,14 @@ fizzyx dev baseline <show|accept>
88
90
  fizzyx dev ready [--agent] [--full]
89
91
  fizzyx dev promote <source> --to <environment|main> --dry-run
90
92
  fizzyx dev cleanup [--confirm-delete]
91
- fizzyx dev doctor
93
+ fizzyx dev doctor [--agent] [--verbose]
92
94
  ```
93
95
 
96
+ `dev start --worktree` creates the branch in `.git/fizzyx/worktrees/<branch>` and works from a checkout with uncommitted changes, which it never touches.
97
+ `dev doctor` prints section counts and names only the branches holding commits that are on no remote and not on the base (`local_only`); `--verbose` lists every section. It recognises branches whose commits were cherry-picked onto the base as integrated.
98
+ `dev cleanup` previews exactly which branches `--confirm-delete` would remove and why. Only work-role branches (built-in prefixes or `dev.branch_prefixes`) are deleted; a cherry-picked branch is pinned at `refs/fizzyx/deleted/<branch>` first and can be restored with `git branch <branch> refs/fizzyx/deleted/<branch>`.
99
+ `dev ready` prints `checks: none configured` when the project sets no `dev.checks.ready`, because it then verifies branch state only.
100
+
94
101
  Branch/card associations live in local Git config. Unchanged pre-existing worktree files may be accepted with `dev baseline accept`; readiness receipts are stored under `.git/fizzyx/` and are invalidated when HEAD changes. `.fizzyx.yaml` remains shared project policy only.
95
102
 
96
103
  Production promotions stay guarded:
@@ -461,6 +468,22 @@ setToken(null); // logout, clears storage
461
468
  - `Logger` controls **output** (console, file, sentry). Default: `console.error/warn/info/debug` with `[fizzyx]` prefix.
462
469
  - `RequestHook` fires **business callbacks** at lifecycle points (`onRequest`, `onSuccess`, `onError`). Use for toast, analytics, loading state.
463
470
 
471
+ Applications that already own an isolated session can supply a JSON `transport` instead of
472
+ using the generated native request and token storage:
473
+
474
+ ```ts
475
+ configure({
476
+ transport: (method, path, options) => session.request(method, path, options),
477
+ responseExtractor: (value) => value,
478
+ });
479
+ ```
480
+
481
+ The transport receives the generated endpoint path, query, body and headers. It owns
482
+ origin validation, authentication, logging, lifecycle hooks and errors. Transport failures
483
+ are preserved rather than converted into generated native-request errors. The response
484
+ extractor still runs on successful results; choose the identity extractor for APIs without
485
+ an envelope. Upload and download retain their separate native implementations.
486
+
464
487
  ### Generated Endpoint API
465
488
 
466
489
  Each endpoint is a standalone export function with typed params:
@@ -545,3 +568,13 @@ Credentials are resolved in this priority order:
545
568
  3. `.fizzyx.yaml` `access_key_id` / `secret_access_key` fields (legacy, discouraged)
546
569
 
547
570
  Credentials stored as `default` (without `--env`) are used as a fallback for all environments when no env-specific key is found. This means you only need to run `fizzyx oss setup` once — dev, prod, and any other env will reuse the same keys.
571
+
572
+ ## License
573
+
574
+ MIT, © 2026 Puffin Studio. See [`LICENSE`](LICENSE).
575
+
576
+ Some bundled skills are derived from [mattpocock/skills](https://github.com/mattpocock/skills)
577
+ (MIT, © 2026 Matt Pocock), rewritten in this project's voice and re-pointed at
578
+ `fizzyx` commands. They are listed file by file, with the upstream licence text,
579
+ in [`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md) — which also flags three
580
+ skills whose origin is not established.
@@ -0,0 +1,93 @@
1
+ # Third-party notices
2
+
3
+ This package's own code is MIT, © 2026 Puffin Studio (see [`LICENSE`](LICENSE)).
4
+ Some of the bundled skills are not its own work. They are listed here with what
5
+ is known about where they came from and under what terms.
6
+
7
+ The skill markdown is inlined into `dist/main.js` at build time, so a published
8
+ `@puffinstudio/fizzyx` carries this content — which is why this file ships with
9
+ the package rather than only living in the repository.
10
+
11
+ ---
12
+
13
+ ## mattpocock/skills — MIT, © 2026 Matt Pocock
14
+
15
+ <https://github.com/mattpocock/skills>
16
+
17
+ The skills below are derived from that repository. Most have been rewritten in
18
+ this project's own voice and re-pointed at `fizzyx flow` / `fizzyx dev` commands
19
+ in place of upstream's tracker-specific instructions, and several accompanying
20
+ reference files were condensed. They remain derivative works.
21
+
22
+ | Bundled file | Upstream source |
23
+ | --------------------------------------------- | ---------------------------------------------------------------------------- |
24
+ | `code-review.md` | `skills/engineering/code-review/SKILL.md` |
25
+ | `domain-modeling.md` | `skills/engineering/domain-modeling/SKILL.md` |
26
+ | `handoff.md` | `skills/productivity/handoff/SKILL.md` |
27
+ | `improve-codebase.md` | `skills/engineering/improve-codebase-architecture/SKILL.md` |
28
+ | `prototype.md` | `skills/engineering/prototype/SKILL.md` |
29
+ | `research.md` | `skills/engineering/research/SKILL.md` |
30
+ | `to-issues.md` | `skills/engineering/to-tickets/SKILL.md` (upstream renamed from `to-issues`) |
31
+ | `to-prd.md` | `skills/engineering/to-spec/SKILL.md` (upstream renamed from `to-prd`) |
32
+ | `triage.md` | `skills/engineering/triage/SKILL.md` |
33
+ | `resources/domain-modeling/ADR-FORMAT.md` | `skills/engineering/domain-modeling/ADR-FORMAT.md` |
34
+ | `resources/domain-modeling/CONTEXT-FORMAT.md` | `skills/engineering/domain-modeling/CONTEXT-FORMAT.md` |
35
+ | `resources/improve-codebase/HTML-REPORT.md` | `skills/engineering/improve-codebase-architecture/HTML-REPORT.md` |
36
+ | `resources/prototype/LOGIC.md` | `skills/engineering/prototype/LOGIC.md` |
37
+ | `resources/prototype/UI.md` | `skills/engineering/prototype/UI.md` |
38
+ | `resources/triage/AGENT-BRIEF.md` | `skills/engineering/triage/AGENT-BRIEF.md` |
39
+ | `resources/triage/OUT-OF-SCOPE.md` | `skills/engineering/triage/OUT-OF-SCOPE.md` |
40
+
41
+ Paths are relative to `src/skills/bundled/` here and to the upstream repository
42
+ root there. Content was last checked against `mattpocock/skills@66898f6`
43
+ (2026-07-13); see `src/use-cases/skill-service.ts`.
44
+
45
+ ```
46
+ MIT License
47
+
48
+ Copyright (c) 2026 Matt Pocock
49
+
50
+ Permission is hereby granted, free of charge, to any person obtaining a copy
51
+ of this software and associated documentation files (the "Software"), to deal
52
+ in the Software without restriction, including without limitation the rights
53
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
54
+ copies of the Software, and to permit persons to whom the Software is
55
+ furnished to do so, subject to the following conditions:
56
+
57
+ The above copyright notice and this permission notice shall be included in all
58
+ copies or substantial portions of the Software.
59
+
60
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
61
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
62
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
63
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
64
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
65
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE OTHER DEALINGS IN THE
66
+ SOFTWARE.
67
+ ```
68
+
69
+ ---
70
+
71
+ ## Origin not established
72
+
73
+ These three are **not** from `mattpocock/skills`, despite a commit message in
74
+ this repository's history saying otherwise. Their content does not appear
75
+ anywhere in that repository's full history:
76
+
77
+ | Bundled file | Distinguishing content | Searched for |
78
+ | -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------- |
79
+ | `codebase-design.md` | "Pass 1: Explore" through "Pass 5: Implement" | `Pass 1: Explore` — no match |
80
+ | `tdd.md` | "Phase 1: Triangulation", red/green/refactor | `Triangulation` — no match |
81
+ | `diagnosing-bugs.md` | OBSERVATION / CONTRACTION / HYPOTHESIS / EXPERIMENT / JUDGEMENT / RESOLUTION | `Socratic dialogue`, `CONTRACTION` — no match |
82
+
83
+ Upstream has skills by the same names, but with entirely different content.
84
+ Until the real source is identified these are listed as unknown rather than
85
+ credited to an author who may not have written them. If you recognise this
86
+ material, please open an issue.
87
+
88
+ ---
89
+
90
+ ## security-review.md
91
+
92
+ Carries `metadata.origin: ECC` in its own front matter. Terms not established
93
+ here.