@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 +47 -14
- package/THIRD-PARTY-NOTICES.md +93 -0
- package/dist/main.js +590 -544
- package/package.json +13 -6
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> "
|
|
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
|
|
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
|
|
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
|
|
69
|
-
fizzyx flow
|
|
70
|
-
fizzyx flow done <card>
|
|
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.
|