card-workspace-git-workflow

name	card-workspace-git-workflow
description	Git workflow for the Card Workspace repository. Use when moving from research into implementation, or when the user asks to commit, tag, or release.

Card Workspace Git Workflow

Rules

• No git during read-only research/planning.
• Branch before implementation. Use short-lived branches from up-to-date main.
• No commits/tags/push/release unless explicitly requested.
• Atomic commits: one logical change per commit, including matching tests/docs.
• Conventional Commits: type(scope): summary.
• Bare semver tags only: x.y.z, never vX.Y.Z.
• Never force-push unless explicitly requested.

Preferred scopes: main, view, search, settings, i18n, styles, docs, release, tests.

Types: feat, fix, refactor, docs, test, chore.

Branching

Confirm current branch and worktree state first. If already on the correct task branch, continue there. If unrelated uncommitted changes exist, stop and ask.

Naming: <type>/<topic> in lowercase kebab-case.

git checkout main
git pull --ff-only origin main
git checkout -b <type>/<topic>

Examples: fix/search-readiness-gating, feat/folder-root-summary

Commits

Only commit when explicitly requested.

Before each commit:

1. Inspect the diff
2. Stage one logical unit
3. Run targeted verification
4. Commit with precise subject

Examples:

• fix(search): block non-empty queries until index ready
• chore(release): 0.6.0

If multiple independent logical changes exist, create multiple commits.

Push and PR

Push only when explicitly requested.

git push -u origin <branch>

PR title should align with the intended squash commit title.

Release

Only run when explicitly requested. Start from up-to-date main unless requested otherwise.

# 1. Prepare version metadata
npm run release:prepare -- "<version>" [minAppVersion]

# 2. Validate (touches package.json, package-lock.json, manifest.json, versions.json)
npm run release:check -- "<version>"

# 3. Commit release metadata separately
git commit -m "chore(release): <version>"

# 4. Push if requested
git push

# 5. Create and push bare semver tag
git tag <version>
git push origin <version>

GitHub Actions (.github/workflows/release.yml) publishes the release automatically.

Fast Decision Table

User asks for...	Action
Implementation only	Create/switch branch, edit, verify. No commit.
"Commit"	Atomic commit(s). No tag/release unless also requested.
"Push"	Push current branch after commit(s).
"Release"	Run prepare/check, commit chore(release): <version>, tag <version>, push tag.