@flowmind/cli 0.3.1 → 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdullah Faruk Gonullu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,6 +13,9 @@ flowmind hooks install
 
 `hooks install` copies the Flowmind skill to Codex and Claude Code and adds session hooks to
 `~/.codex/hooks.json` and `~/.claude/settings.json`. Other hooks in those files stay as they are.
+When the Flowmind Claude Code plugin (`flowmind@flowmind` from `afgonullu/flowmind-skill`) is
+installed and enabled, the plugin provides the skill in Claude Code: `hooks install` writes no
+copy to `~/.claude/skills`, removes an unmodified copy it wrote earlier, and still adds the hooks.
 The hooks run `agent hook` through the absolute paths of the installing Node binary and CLI file,
 because hooks start without your shell profile and a version manager may not put `node` on PATH.
 Codex on Windows gets a PowerShell command (`& '<node>' '<cli>' agent hook --agent codex`).
@@ -88,13 +91,25 @@ AI confirmation time. Run `fm log --help` for all options.
 ## Stage an agent proof
 
 Agents stage completed work for explicit human approval. In a linked repository with the session
-hooks installed, the intention and outcome are enough:
+hooks installed, the intention and outcome are enough. Write the outcome as one line of at most
+120 characters: what changed for the project or its users. Add up to three optional `--detail`
+values for proof or open items. Each detail must be one line of at most 100 characters.
+Keep commits, runs, paths, and open items in details or use `--artifact-url` for the proof link.
+
+For example:
 
 ```sh
-flowmind agent stage --intention "Finish the reader" --outcome "Shipped the reader" \
-  --artifact-url https://example.com/proof --json
+flowmind agent stage --intention "Fix CLI sign-in" \
+  --outcome "Signed-out CLI sign-in now returns to Authorize CLI" --detail "Cause: Supabase rejected the www callbacks" --detail "Still needs: deploy approval" \
+  --json
 ```
 
+If a proof breaks these rules, the CLI rejects it before any request. The error says exactly
+what to shorten or split and includes the worked example above. In `--json` mode, stderr contains
+an `error` message and an `issues` list. API rejections retain the server's exact message.
+Existing long notes remain readable; this rule applies to new proofs. `agent proposals` shows
+details as indented bullets, and `--json` includes the API's details unchanged.
+
 The CLI reads the project from `.flowmind.json` and the session from `CODEX_THREAD_ID` or the one
 session with a turn in progress in the repository. The duration is the main agent's recorded turn
 time since the session's last staged proof, in whole minutes; the remaining seconds carry over to

package/dist/flowmind/SKILL.md

@@ -49,7 +49,7 @@ To find gaps across the user's folders, run `flowmind link --scan <dir...>`. It
 In a linked repository, the session hooks record how long the main agent's turns run. When you finish a material unit of work, such as a feature, fix, investigation, or document, stage it before you start the next one. Do not stage every turn.
 
 ```bash
-flowmind agent stage --intention "<what you set out to do>" --outcome "<what changed or shipped>" --artifact-url <commit, PR, or document URL> --json
+flowmind agent stage --intention "<what you set out to do>" --outcome "<one line: what changed>" --detail "<proof or open item>" --artifact-url <commit, PR, or document URL> --json
 ```
 
 - The CLI reads the project from `.flowmind.json` and the time from the session record. The time is the main agent's turn time on the awake clock that Codex uses for "Worked for", so sleep does not count. It includes the time that subagents work during the turn.
@@ -60,10 +60,37 @@ flowmind agent stage --intention "<what you set out to do>" --outcome "<what cha
 - After 20 minutes of unstaged agent time, each prompt in a linked repository carries a reminder with the unstaged minutes. Stage when the current unit of work is complete; a stage with explicit times also resets the count.
 - Add `--dry-run` to preview the project and minutes without staging.
 - Pass `--project`, `--minutes`, and `--started-at` only when no session record exists. Use observed times only. Never estimate time from tokens or tool calls.
-- Write the intention and the outcome as one short sentence each. Never paste transcripts, terminal output, commit messages, issue titles, emails, or secrets.
 - Share `proposal.webReviewUrl` with the user. The user approves staged work in Flowmind Activity; **Approve all with links** approves every item with an artifact link at once. Approved agent time counts on the project, not as the user's personal effort or XP.
 - If staging fails, report the error. Never fall back to `flowmind log`, and never approve your own proposals.
 
+### Write the proof for a person
+
+The user reads many proofs at once, often on a dashboard. Keep each one short:
+
+- `--intention`: what you set out to do, in one short sentence.
+- `--outcome`: one line of at most 120 characters that says what changed for the project or its users. Lead with the result, not the method.
+- `--detail`: optional, at most 3, each one line of at most 100 characters. Use details for proof (cause, check, version) and for anything still open ("Still needs: ..."). Repeat the flag for each detail.
+- Put the commit, PR, or document in `--artifact-url`, not in the text.
+- Never paste transcripts, terminal output, commit messages, issue titles, emails, or secrets.
+
+The CLI and the API reject a proof that breaks these limits and say what to change. Shorten the text and stage again.
+
+Good:
+
+```bash
+flowmind agent stage --intention "Fix CLI sign-in for signed-out users" \
+  --outcome "Signed-out CLI sign-in now returns to Authorize CLI" \
+  --detail "Cause: production Supabase rejected the www callbacks" \
+  --detail "Still needs: Supabase URL settings and deploy approval" \
+  --artifact-url https://github.com/<owner>/<repo>/commit/<sha> --json
+```
+
+Rejected, because the outcome is a paragraph:
+
+```text
+--outcome "Found that production Supabase rejects every www sign-in callback and falls back to the apex domain, so Google and GitHub sign-in land on the home page signed out. Changed the web app so a signed-out CLI link goes to /login ..."
+```
+
 ## Log the user's own work
 
 Use `flowmind log` only when the user asks you to log work that they did themselves: