@puffinstudio/fizzyx 1.1.5 → 1.2.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.
Files changed (3) hide show
  1. package/README.md +43 -9
  2. package/dist/main.js +723 -431
  3. package/package.json +1 -2
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  > CLI tool for Fizzy board workflow, OSS/S3-compatible storage, and OpenAPI client generation.
4
4
 
5
- > <img src="./docs/images/fizzyx-logo.webp" alt="fizzyx logo" width="120" />
5
+ <img src="./docs/images/fizzyx-logo.webp" alt="fizzyx logo" width="120" />
6
6
 
7
7
  ## Install
8
8
 
@@ -16,16 +16,25 @@ Use `.fizzyx.yaml` as the project config file for board and workflow settings.
16
16
 
17
17
  ```sh
18
18
  fizzyx flow work
19
+ fizzyx flow list [--indexed-by <lane>] [--search <terms>] [--json]
20
+ fizzyx flow search "<query>" [--all-boards] [--json]
21
+ fizzyx flow columns
19
22
  fizzyx flow create --draft
20
- fizzyx flow create "<title>" --desc .fizzyx/card-<random>.md
21
- fizzyx flow create "<title>" --assign <user> --desc .fizzyx/card-<random>.md
23
+ fizzyx flow create "<title>" --desc <draft-path>
24
+ fizzyx flow create "<title>" --assign <user> --desc <draft-path>
25
+ fizzyx flow edit <card> --draft
26
+ fizzyx flow edit <card> [--title "<title>"] [--desc <file|->]
22
27
  fizzyx flow assign <card> <user>
28
+ fizzyx flow comment <card> "<body>"
23
29
  fizzyx flow show <card>
30
+ fizzyx flow move <card> <column-id-or-name>
24
31
  fizzyx flow start <card>
25
32
  fizzyx flow review <card>
26
33
  fizzyx flow done <card> "commit <sha>: <subject>"
34
+ fizzyx flow reopen <card>
27
35
  fizzyx flow block <card> "<reason>"
28
- fizzyx flow improve
36
+ fizzyx flow unblock <card> "<reason>"
37
+ fizzyx flow untriage <card>
29
38
  fizzyx flow doctor
30
39
  fizzyx flow repair
31
40
  ```
@@ -33,6 +42,19 @@ fizzyx flow repair
33
42
  `flow done` requires all steps to be complete and closes the card into Done.
34
43
  `flow create` expects the standard draft shape with a `## Steps` task list; generate it with `flow create --draft` instead of passing plain text.
35
44
  `flow create` does not assign by default. Use `--assign <user>` while creating or `flow assign <card> <user>` afterwards.
45
+ 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.
46
+ `flow edit` updates the title, description, or both. Description input accepts a standard card draft file or `-` for stdin and synchronizes its `## Steps` task list.
47
+ `flow columns` lists the real columns and IDs on the configured board. `flow move` is the column-agnostic primitive for custom Fizzy boards. `flow start` uses the configured `in_progress` column; `flow review` is a convenience command for the built-in REVIEW preset.
48
+ `flow move` also accepts the Fizzy system targets `maybe`/`triage` and `not-now`; closing remains guarded by `flow done`.
49
+ `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.
50
+ `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.
51
+ High-frequency flow commands accept `--json` and return an `ok`/`data`/`summary` envelope with next-action breadcrumbs for agents.
52
+ 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.
53
+ `flow improve` is retained as a deprecated compatibility alias; use `fizzyx skill run improve-codebase` for the actual codebase workflow.
54
+
55
+ On successful initialization, `fizzyx init` also creates `AGENTS.md` when it is missing or
56
+ updates a marker-delimited FizzyX development workflow section in the existing file. Other
57
+ project instructions are preserved, and repeated initialization does not duplicate the section.
36
58
 
37
59
  Agent loop for card-backed code work:
38
60
 
@@ -61,12 +83,15 @@ fizzyx dev status --agent
61
83
  fizzyx dev start <slug> --kind <feature|fix|hotfix|ops|chore|docs> [--card <id>]
62
84
  fizzyx dev sync
63
85
  fizzyx dev checkpoint [--message <message>]
86
+ fizzyx dev baseline <show|accept>
64
87
  fizzyx dev ready [--agent] [--full]
65
88
  fizzyx dev promote <source> --to <environment|main> --dry-run
66
89
  fizzyx dev cleanup [--confirm-delete]
67
90
  fizzyx dev doctor
68
91
  ```
69
92
 
93
+ 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.
94
+
70
95
  Production promotions stay guarded:
71
96
 
72
97
  ```sh
@@ -78,9 +103,11 @@ fizzyx dev promote <source> --to main --apply --confirm-production
78
103
 
79
104
  ```sh
80
105
  fizzyx skill list
106
+ fizzyx skill init --project
107
+ fizzyx skill init --global
81
108
  fizzyx skill add <source>
82
109
  fizzyx skill remove <name>
83
- fizzyx skill update [name]
110
+ fizzyx skill update [name] [--global]
84
111
  fizzyx skill info <name>
85
112
  fizzyx skill run <name>
86
113
  fizzyx skill doctor
@@ -88,7 +115,17 @@ fizzyx skill migrate --check
88
115
  fizzyx skill migrate --apply
89
116
  ```
90
117
 
91
- Built-in skills are bundled. `skill update [name]` refreshes the local copy from the current fizzyx release.
118
+ The bundled `coding-standards` skill covers repository-aware code style, code quality,
119
+ naming, and safe tool usage. The aliases `code-style`, `code-quality`, `naming`, and
120
+ `tool-usage` all resolve to that single skill. It includes a conditional TypeScript, React,
121
+ Bun/pnpm, and OXC profile while leaving exact scripts and framework policy to each project.
122
+
123
+ Built-in skills remain available from the fizzyx release without installation. Top-level
124
+ `fizzyx init` maintains the project's `AGENTS.md` instructions but does not copy skills. Use `skill init --project` for `.agents/skills`, or
125
+ `skill init --global` for `~/.agents/skills`; initialization preserves existing files.
126
+ `skill add <source>` records a project pin and materializes that skill in the project.
127
+ `skill update [name]` refreshes project files by default; pass `--global` explicitly for
128
+ the global copy.
92
129
 
93
130
  ![Skill command workflow](./docs/images/skill-workflow.webp)
94
131
 
@@ -99,15 +136,12 @@ Start a local planner dashboard backed directly by the Fizzy API:
99
136
  ```sh
100
137
  fizzyx planner start
101
138
  fizzyx planner snapshot
102
- fizzyx planner chat-config --host peer.example.com --port 443 --path /peerjs
103
139
  ```
104
140
 
105
141
  ![Planner dashboard workflow](./docs/images/planner-workflow.webp)
106
142
 
107
143
  `planner snapshot` prints the same JSON used by the web dashboard. Project workflow uses `BACKLOG → READY → IN PROGRESS → REVIEW → DONE`, with `DONE` coming from closed cards and `BLOCKED` from Not Now/postponed cards.
108
144
 
109
- `planner chat-config` stores the Team Chat signaling server globally in `~/.config/fizzyx/config.yaml`. Use `--insecure` for local HTTP/ws PeerServer instances.
110
-
111
145
  Planner conventions use tags for filtering:
112
146
 
113
147
  ```text