gflows 0.1.17 → 1.0.0

package/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md — using gflows from coding agents
+
+gflows is a **local Git branching workflow CLI** (main + dev + typed short-lived branches). Prefer gflows over inventing git-flow merges by hand.
+
+## Rules for agents
+
+1. **Non-interactive only** — never assume the TTY menu. Always pass explicit args.
+2. **Finish needs push polarity** — pass `-p` / `--push` or `-P` / `--no-push`. Use `-y` to accept the finish plan (delete branch defaults **on**; use `-N` to keep).
+3. **Do not finish empty branches** — if there are no commits beyond the merge target, finish exits `2`. Commit first.
+4. **Conflicts** — resolve files, then `gflows continue`. Or `gflows abort` / `gflows undo`.
+5. **Discover the API** — run `gflows schema` (JSON) or read this file + README.
+6. **MCP** — `gflows mcp` (stdio JSON-RPC) exposes status/doctor/list/start/sync/finish/schema tools.
+7. **Hub / viz** — bare `gflows` (TTY) opens an Ink fullscreen hub (`/` commands). Prompts use Clack. `gflows viz` prints the scrollback status panel.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Usage / validation |
+| 2 | Git / system |
+
+## Recipes
+
+```bash
+# Setup
+gflows init --no-push -y
+# or with remote: gflows init -y
+
+# Daily feature
+gflows start feature my-thing
+# … commit …
+gflows sync --force
+gflows pr                    # needs gh or glab
+gflows finish feature -y -P  # or -p to push
+
+# Production bugfix
+gflows start bugfix hotfix-login -o main
+# … commit …
+gflows finish bugfix -y -p   # merges main, then main→dev
+
+# Release
+gflows bump up minor
+# commit version files, or: gflows finish release --bump …
+gflows start release v1.2.0
+# … changelog / commits …
+gflows finish release -y -p
+
+# Stuck
+gflows doctor --json
+gflows continue
+gflows abort
+gflows undo
+```
+
+## Branch merge targets
+
+| Type | Base | Finish merges into |
+|------|------|--------------------|
+| feature, chore, spike | dev | dev |
+| bugfix | dev (or main with `-o main`) | dev, or main then dev if based on main |
+| release | dev | main, then main→dev + tag |
+| hotfix | main | main, then main→dev + tag |
+
+## Cursor MCP snippet
+
+```json
+{
+  "mcpServers": {
+    "gflows": {
+      "command": "bun",
+      "args": ["run", "path/to/gflows/src/cli.ts", "mcp"]
+    }
+  }
+}
+```
+
+Or after install: `bunx gflows mcp`.

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Fullscreen **Ink** TUI hub (`gflows` on TTY): bordered frame, tips / what’s next, actions, `❯` slash prompt, status bar
+- Slash commands: `/init` `/start` `/sync` `/pr` `/finish` `/doctor` `/help` …
+- Interactive prompts via **@clack/prompts** (Inquirer removed)
+- Legacy Clack menu fallback when TUI cannot run; `gflows viz` for scrollback panel
+- `gflows init`: optional `package.json` script alias (`--script-alias g`, TTY prompt); docs recommend shell `alias g=gflows` for shortest DX
+- Hub wizards (`/start`, `/finish`, `/sync`) run **inside Ink** (fewer Clack drop-outs); only git dispatch leaves the TUI
+
+## [1.0.0] - 2026-07-24
+
+### Added
+
+- Interactive hub: bare `gflows` in a TTY opens a guided menu
+- `gflows sync` — update workflow branch from base (merge/rebase, stash-aware)
+- `gflows pr` — open PR/MR via `gh` or `glab` against the correct base
+- `gflows doctor`, `gflows config get|set`, `gflows schema`, `gflows mcp`
+- Recovery: `gflows continue`, `gflows undo`, `gflows abort` with run-state under `.git/gflows/`
+- Finish plan preview, `--squash`, `--preview`, `--bump`, empty/dirty finish guards
+- Delete-after-finish defaults **on** (`-N` to keep); `-y` accepts the plan
+- Bugfix-from-main finish merges to main then dev
+- `--json` on status/list/doctor; hints go to stderr (stdout stays scriptable)
+- `AGENTS.md` + `llms.txt` for AI agents
+- Kebab-case long flags (`--dry-run`, `--no-ff`, `--no-delete`, …) bind correctly
+- Merge `-m` / `--message` wired through to git merge
+
+### Fixed
+
+- Documented flags that previously did not parse
+- Help text incorrectly claimed start pushes by default
+- Finish picker prefers the current workflow branch