| name | commit-and-document |
| description | Stage selected files, write a Conventional Commit, optionally link a GitHub issue, and append a dated journal entry under docs/journal/. Use when the user wants to commit work and capture a local record of what changed. |
Commit and Document
Deterministic flow. Execute steps in order; do not deviate.
1. Inspect git changes
Run and read via Bash:
git status --shortgit diff --statgit diff --cached --stat
Summarise: which files, what changed.
If the working tree is clean, stop and report. Skip the rest.
2. Propose a Conventional Commit
One-line message:
<type>(<scope>): <short, action-focused summary>
- type:
feat, fix, refactor, docs, chore, test, style, perf
- scope: area touched. Omit parens if unclear.
- summary: imperative, present tense, under 70 chars, starts with a verb.
Show: proposed message, files to stage, files excluded (tests, docs, secrets). Ask via AskUserQuestion: "Commit with this message? (yes / edit / cancel)". On edit, accept the user's revised message verbatim and re-run detection (step 2.5) on it before proceeding. On cancel, stop and report.
2.5 Detect or ask for an issue reference
Silent pre-checks via Bash first:
git remote -v — bail if no github.com remote.command -v gh — bail if gh is not installed.
Detection on the proposed message:
- Closing keywords:
Closes/Close/Closed/Fixes/Fix/Fixed/Resolves/Resolve/Resolved #N (case-insensitive)
- Bare
#N anywhere
Branches:
- A — closing keyword present: ask via
AskUserQuestion "After commit, comment on issue #N and close it? (yes / no)". yes → {action: close, issue: N}.
- B — bare
#N: ask "After commit, post a progress comment on issue #N? (yes / no / close)". Map to comment / close / none.
- C — no reference: ask once "Is this commit related to a GitHub issue? (issue number / no / skip)". On a number, ask "Comment only or close after commit? (comment / close)". Anything non-numeric → none.
Carry the result as issue_action (default none).
3. Stage and commit
Stage explicit files with git add <file>... via Bash (never git add .). Exclude:
- anything under
test/, tests/, __tests__/, spec/, specs/
- files matching
*.test.*, *.spec.*, test_*, *_test.*
- anything that looks like secrets (
.env, credentials, tokens)
Flag exclusions to the user.
Commit with the approved message via Bash. Capture the short hash via git rev-parse --short HEAD.
3.5 Act on the issue reference
If issue_action is none, skip.
Otherwise build via Bash:
> *This was generated by AI during commit.*
Linked from commit `<short-hash>`: <commit subject>
Run gh issue comment <N> --body "<body>" via Bash. If action == close, then run gh issue close <N> (never --comment; comment first).
If either fails, report the error and continue. Do not abort. Do not close an issue you could not comment on.
4. Ensure docs/ is gitignored
Read .gitignore via Read. If no line matches docs/, append via Edit:
# Local documentation — never committed
docs/
Do not commit the gitignore change. If the user accidentally staged anything under docs/, unstage it via Bash (git restore --staged docs/<path>) and warn.
5. Inspect existing docs/journal/
List docs/journal/ via Glob if present. If it uses a different date/file convention than the default below, follow its existing convention. Create the directory if missing via Bash.
6. Write a dated entry
Date via Bash with date +%Y-%m-%d. Create docs/journal/<YYYY-MM-DD>/ if missing. Write via Write to <HH-MM>-<short-slug>.md (kebab-case slug, 3–6 words from the summary). Template:
# <Commit summary>
**Commit:** <full hash>
**Short hash:** <short hash>
**Date:** <YYYY-MM-DD HH:MM local time>
## What changed
<2–4 sentences. Plain English, not a file list.>
## Why
<1–3 sentences on motivation, pulled from conversation context.>
## Notes for future me
<Gotchas/follow-ups, one paragraph max. Skip if nothing worth saying.>
7. Surface stale docs (if any)
Read git diff --cached --stat via Bash. If any staged path overlaps with a path referenced in .zoo-flow/CONTEXT.md, output exactly one line before "Confirm":
"Public surface may have drifted. Run /zoo-update-docs? (yes / skip)"
On yes → suggest /zoo-update-docs <area>. On skip → continue.
8. Confirm
Report: commit hash + message, journal entry path, whether .gitignore was updated, and any issue actions taken. Close with: "All of docs/ is gitignored, so this entry stays local."
Complete
COMPLETION PROTOCOL: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.
- commit hash (short)
- journal entry path
- status (complete / blocked with reason)
- recommended next command
Context economy
Before broad reads, locate relevant files/symbols with Glob, Grep, or targeted file reads.
Prefer targeted Read with line ranges or block reads once the relevant area is known.
Read full files only when structure, ordering, or surrounding context is required for correctness.
Do not re-read unchanged files; use prior findings unless the file changed.
Use git status --short, git diff --stat, and targeted git diff -- <file> rather than dumping the full repo diff at once.
Safety
- Never
git push, --amend, --force, or reset --hard.
- Flag suspected secrets; do not stage them.
- If
git status is clean, abort early.
