Work-Buddy Commit

Commit with test verification, knowledge doc hygiene, PII check, branch management, push + PR creation, and structured metadata recording via commit_record

When to use

When the user invokes /wb-commit or asks to commit with test verification and metadata recording

Slash command: /wb-commit

Related capabilities

• commit_record

Directions

Commit your work with test verification, knowledge doc hygiene, and structured metadata recording.

0. Branch check

Before anything else, check which branch you're on:

git branch --show-current

If you're on main, you must create a feature branch first — main is protected and does not accept direct pushes.

git checkout -b <branch-name>

Branch naming conventions: - fix/<short-description> — bug fixes - feat/<short-description> — new features or capabilities - docs/<short-description> — documentation-only changes - chore/<short-description> — config, CI, dependency updates

Derive the name from the task or change. Keep it short and lowercase with hyphens.

If you're already on a feature branch, continue.

1. Assess changes

Run git status and git diff. Identify which files YOU modified during this session. Ignore untracked or modified files that are not yours — other agents may be working in parallel.

Classify your changes: - Module files — Python code under work_buddy/ - Knowledge store — JSON files in knowledge/store/ - Slash commands — .claude/commands/wb-*.md - Tests — files under tests/ - Config/other — pyproject.toml, config.yaml, READMEs, etc.

If you have no meaningful changes, say so and stop.

2. Run relevant tests

For each module file you changed under work_buddy/, check whether a corresponding test file exists: - work_buddy/foo/bar.py → look for tests/unit/test_bar.py or tests/component/test_bar.py - Also check for any test file that imports from the modules you changed

Run the relevant tests:

export WORK_BUDDY_SESSION_ID='test-session-00000000' && python -m pytest <test_files> -q --tb=short

If no test files exist for the modules you changed, note the gap but do not block.

Record: which test files ran, pass count, fail count. If tests fail on code you changed, fix the failures before proceeding. If tests fail on code you did NOT change, note the pre-existing failure and proceed.

3. Knowledge doc check + update

Your changes may have made existing documentation stale. Stale docs are worse than missing docs — they actively mislead future agents. This step is NOT optional for behavioral or architectural changes.

3a. Search for affected docs

For each subsystem you changed, search the knowledge store for units that describe it:

`mcp__work-buddy__wb_run("agent_docs", {"query": "<subsystem or feature name>"})`

Read any matching units. Ask: does this unit's content still accurately describe how the system works after my changes? If not, update it.

3b. Check CLAUDE.md

CLAUDE.md is the highest-priority instruction surface — every agent reads it first. Search it for references to the system you changed:

grep -n '<feature keyword>' CLAUDE.md

If CLAUDE.md contains instructions, examples, or flow descriptions that are now stale, update them.

3c. Apply updates

Use docs_update to modify knowledge units — don't edit JSON files directly:

`mcp__work-buddy__wb_run("docs_update", {
    "path": "<unit path>",
    "content_full": "<new full content>",
    "content_summary": "<new summary>",
    "description": "<new one-liner if needed>"
})`

For generated capability docs, rebuild instead: mcp__work-buddy__wb_run("agent_docs_rebuild")

3d. When to update

• Added or modified an MCP capability → rebuild generated docs
• Changed a workflow definition → knowledge/store/workflows.json may need updating
• Changed system behavior (not just signatures) → search for and update the directions/system unit that describes it
• Added a new slash command → the parent unit's children list may need the new path
• Changed the architecture of a subsystem → check knowledge/store/architecture.json and the subsystem README

The test is not "did a capability signature change?" — it's "would an agent reading the docs get the wrong instructions?"

3e. Rules for knowledge doc edits

• No clobbering — read the existing unit first. Only modify the fields that are stale given your changes.
• No recency bias — a unit describes its whole feature, not just your latest edit. Don't rewrite the description to disproportionately emphasize what you just changed.
• Precision with concision — update the specific text that changed. Don't rewrite unrelated sections.

If your changes only touch tests, config, or scratch files, skip this step.

4. Cleanup pass

For each file you changed, check for: - Temporary debug code, print statements, or TODO comments you left behind - Stale references to things you renamed or removed - Missing or broken imports caused by your changes - Obvious issues in code you wrote (typos, dead code, incomplete error handling)

Fix what you find. Do NOT refactor unrelated code or expand scope beyond your own changes.

5. PII check

Before staging, verify that staged files don't contain personal data that shouldn't be in the repo. Run:

git diff --cached -U0 | grep -iE '(C:/Vaults|C:\\Vaults|/Users/<username>|SecondBrain|hardcoded-email@|/home/[a-z]+/)' || echo 'Clean'

Also check unstaged files you're about to add:

grep -rnE '(C:/Vaults|C:\\Vaults|/Users/<username>|SecondBrain)' --include='*.py' --include='*.sh' --include='*.md' --include='*.json' <files-to-stage> || echo 'Clean'

Patterns to catch: - Hardcoded personal paths — <vault-root>, /Users/<username>, C:\\Users\\Owner - Vault names in URIs — obsidian://open?vault=<personal-vault> - First names in docs — references to the user by name instead of "the user" - Personal project names as examples — use generic names like my-project in docstrings - Machine-specific paths — conda env paths, PGDATA paths, etc.

If any hits are found, fix them before proceeding. Common fixes: - Replace personal fallback paths with cfg["vault_root"] (config is required) - Replace personal names with "the user" - Replace personal project names with generic examples - Add machine-specific config files to .gitignore

6. Stage precisely

Do NOT use git add -A or git add ..

When you own the entire file's changes, stage by name: git add <file1> <file2> ...

When a file contains both your changes and another agent's, use git add -p <file> to stage only your hunks: - y — stage this hunk (yours) - n — skip this hunk (not yours) - s — split a hunk if it mixes your changes with someone else's - q — quit staging this file

Pipe answers for non-interactive use: printf 'y\ny\nn\n' | git add -p <file>

When a hunk mixes your changes with another agent's and s can't split them further, stage the whole hunk (y). Your changes still need to go in.

After staging, verify with git diff --cached --stat that only your intended changes are included.

7. Commit

Run git log --oneline -5 to check for conflicts with recent commits. Write a clear commit message describing what you did and why.

8. Record commit metadata

After the commit succeeds, extract the commit hash and call:

`mcp__work-buddy__wb_run("commit_record", {
    "commit_hash": "<hash from git output>",
    "message": "<commit message>",
    "branch": "<current branch>",
    "files_changed": "<comma-separated list of committed files>",
    "tests_run": "<comma-separated test file names, or empty>",
    "tests_passed": <pass count>,
    "tests_failed": <fail count>,
    "knowledge_units_updated": "<comma-separated knowledge store paths, or empty>",
    "summary": "<1-2 sentence plain-English summary>"
})`

This stores structured metadata so the dashboard can render enriched commit cards.

9. Push and create PR

Ask the user: "Want me to push and create a PR?"

If yes:

1. Push the branch:

   git push -u origin <branch-name>
   

2. Create the PR:

   gh pr create --title "<concise title>" --body "$(cat <<'EOF'
   ## Summary
   <1-3 bullet points describing the change>
   
   ## Test plan
   - [ ] <what to verify>
   
   Task: <task-id if assigned>
   EOF
   )"
   

3. Report the PR URL to the user.

If the user declines, just confirm the commit is on the local branch and remind them they can push later.

Do not push without asking. Pushing is a shared-state action that requires explicit permission.