Skip to content

prd.md

Latest commit

 

History

History
280 lines (193 loc) · 17.1 KB

prd.md

File metadata and controls

280 lines (193 loc) · 17.1 KB

easy-git PRD

1. What we're building

Goal

Build a skill conforming to the Agent Skills open standard. Abstract away Git's complexity from the user — so anyone using an Agent can benefit from version control without deeply understanding Git (at most a few simple concepts, possibly none at all).

Why this is needed

Git is foundational infrastructure for software engineering, but its concepts are highly technical: staging area, commit/push/pull, branch/merge/rebase, three reset modes, local vs remote… Those alone are enough to scare off non-engineers. The reality for ordinary users is:

  • They want to write code / docs / make things with an Agent and want version control as a safety net (don't lose work, can roll back, can work in parallel)
  • But the cost of learning Git far exceeds what they want to pay
  • Having the Agent teach them Git one step at a time, repeating "commit and push" every conversation, is also tedious

easy-git inserts a layer between the user and Git — the user describes goals in everyday language; the Agent invokes Git at the right moments and reports results in plain language.

Target users

Anyone working with an Agent, not limited to developers:

  • People writing code (developers)
  • People writing docs / PRDs / notes (PMs, ops, researchers)
  • People making things (writing, blogging, design)
  • People managing personal projects with an Agent (anyone who doesn't want Git in their way)

If you're using an Agent and want version control as a safety net for your work, easy-git should make that transparent to you.

2. Features, install, how to use

Main features (one-liner version)

  1. Auto commit + push — automatically save progress and sync to remote when a unit of work completes; split atomically
  2. Repo init & .gitignore auto-management — git init proactively in non-git dirs; maintain ignore lists so common bad-to-commit files (dependency dirs, build artifacts, secrets) are blocked by default
  3. Commit message standardization — follow the public Conventional Commits spec; the user doesn't worry about format
  4. Worktree management (complex projects) — open worktree + new branch automatically for new features; ask the user how to merge when done
  5. Plain-language interaction layer — minimize exposure of Git jargon
  6. Safety guardrails — never take dangerous actions (force push, reset --hard, commit secrets, etc.) on your own

Install

easy-git is a skill conforming to the Agent Skills open standard and has nothing to do with MCP. 32+ AI Agent tools support this standard (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Junie, Goose, Amp, TRAE, etc.) — install once, works across many Agents.

Primary channels (Agent Skills official):

  • Claude Code: /plugin marketplace add xz1220/easy-git + /plugin install easy-git
  • Claude.ai: UI upload
  • Claude API: Skills API registration
  • Other compatible Agents: their respective skill install mechanisms

Secondary channels:

  • Third-party npx installer (e.g. npx skills install xz1220/easy-git, for users who prefer npx)
  • git clone directly into an Agent's local skill directory

How users use it

Short answer: nothing to do after install. With easy-git installed, the Agent decides on its own whether to invoke Git in any conversation moment. For example:

  • You finish a doc section → Agent saves and syncs to GitHub, reports "I saved this section and synced it to GitHub"
  • You say "add a new feature ..." → Agent starts a separate line, reports "I'm working on a separate line feat-xxx in <path> for this"
  • Your new directory is full of build artifacts → Agent auto-adds them to .gitignore, tells you "I told Git to ignore dist/"
  • You say "undo this change" → Agent rolls back to the previous checkpoint using git (without exposing the reset concept)

Few cases where the Agent must ask:

  • New feature on a worktree is done → "This line is done. Want me to (a) merge and clean up, (b) open a PR to review, (c) keep it around for now?"
  • About-to-commit content contains .env / secrets → "This file looks like a password / token — exclude it?"
  • Dangerous action triggered (force push to main / rebase pushed commits / reset --hard, etc.) → stop and ask

3. Modules and capabilities

Auto commit + push

Trigger: Agent judges in the course of conversation that "this is a save-worthy checkpoint". Signals: a task is done / tests pass / a doc section is complete / about to switch to another kind of work / user implies "this part is done".

Atomic splitting: when a single task produces multiple semantic clusters, split into multiple commits by change type + scope + purpose; don't pile into one big commit:

feat(api): add /tasks POST endpoint with Zod validation
test(api): add unit + integration tests for tasks POST
docs: update README with new endpoint and example payload

Aim for ≤ 100 lines per commit; > 1000 lines must be split further (industry consensus).

Push sync: in solo / personal-project contexts, commit + push are paired by default (modern solo / trunk-based consensus). Exceptions: protected branches / diverged from remote / would trigger a force push → tell the user first.

Repo init & .gitignore auto-management

Auto git init: When the Agent wants to save progress and detects the current directory is not a git repo (git rev-parse --git-dir fails) → initialize proactively. Flow: path safety check → tell the user → git init -b main → create default .gitignore → stage by name → first commit chore: init repository. Don't configure a remote on your own; wait for the user to say "push to GitHub".

Dangerous locations need confirmation: $HOME root, /tmp / mktemp, /, ~/Desktop / ~/Documents / ~/Downloads, already inside another git repo → confirm before init.

Auto-create .gitignore: new repos / repos missing .gitignore automatically get a baseline file covering language-agnostic common categories:

  • Dependency dirs: node_modules/, vendor/, .venv/, __pycache__/, target/, etc.
  • Build output: dist/, build/, .next/, out/, *.pyc, *.class
  • Env & secrets: .env, .env.* (with !.env.example / !.env.sample allow-listed), *.pem, *.key, credentials.json
  • IDE / editor: .vscode/, .idea/, .DS_Store, *.swp
  • Logs & temp: *.log, *.tmp, *.cache

Pre-commit, if files about to be staged match the above → auto-add to .gitignore and tell the user "I told Git to ignore these — they shouldn't be saved with the source".

Commit message spec

Follow Conventional Commits 1.0.0 strictly; don't inject user-specific style:

<type>(<optional scope>): <subject>

<optional body explaining the why, not the what>

<optional footer / trailers>

Types: feat / fix / refactor / docs / test / chore / style / perf / build / ci / revert.

Subject rules (industry standard):

  • ≤ 50 chars (CJK chars count as 2)
  • Imperative, lowercase first letter, no trailing period
  • Describe "why", not "what changed"

AI attribution: append Co-Authored-By: trailer at the end of every commit body to mark Agent involvement (industry consensus, machine-readable + doesn't crowd the subject). The specific identity is determined by the current harness; the skill itself doesn't embed a fixed template.

Worktree management (complex projects)

Applicable when: the project is big enough that "changing things on main might break what's running", and the user requests a new feature.

Detection heuristics (not strict; Agent decides; user can correct):

  • Prompt contains "add / implement / build / introduce" + noun → lean feature → open worktree
  • Prompt contains "change / fix / tweak / update / repair / optimize" → lean stay on current branch
  • Currently not on main / master → stay on current branch
  • Only doc / config / single-bug-fix changes → don't open a worktree

Worktree setup rules (industry consensus):

  • Path sibling to main repo; never nested (nesting makes git infinitely recurse)
  • Consistent naming: dir = branch = task name (kebab-case)
  • One worktree per task
  • Branches short-lived (≤ 1–3 days); aging is a smell
  • Restraint: ≤ 2 concurrent worktrees by default
  • New worktree → remind user to initialize the environment (npm install / uv sync, etc.)

After completion: Agent actively asks the user for one of three options:

  • (a) Merge into main + clean up worktree (smoothest)
  • (b) Open a PR for the user to review (when remote is GitHub)
  • (c) Keep the worktree around

Plain-language interaction layer

When talking to the user, prefer clear everyday phrasing; avoid throwing Git jargon at them. Glossary source = Git's official giteveryday common commands + industry-recognized user-friendly phrasings. Full glossary in references/translation.md; key entries:

Git operation What to say to the user
commit + push pair "Saved a chunk of progress and synced to GitHub"
pull "Pulled the latest"
open worktree + new branch "Started a separate line for this new feature, in <path>"
merge / resolve conflicts "Both sides changed the same place — you need to pick"
staged changes "Changes ready to save"
untracked files "New files not yet under management"
pre-commit hook failure "The pre-save check didn't pass; let me fix it"
status "Let me check what hasn't been saved yet"
.gitignore "The list that tells Git which files to ignore"
reset / revert / restore "Going back / undoing to that state"

Report outcomes, not steps:

  • ✅ "I saved that PRD section and synced it to GitHub."
  • ❌ "I ran git add docs/prd.md && git commit -m '...' && git push."

Safety guardrails

The skill never takes the following actions on its own; when conditions are met, must ask first:

  • Staging: git add -A / git add . (always stage by name)
  • Force push: git push --force / --force-with-lease to main / master / any protected branch
  • Skipping checks: git commit --no-verify / --no-gpg-sign (hook fail → fix the issue first)
  • Rewriting published history: git commit --amend or git rebase on pushed commits (once pushed, it's public history)
  • Destructive operations: git reset --hard, git checkout -- . / git restore ., git clean -f, git branch -D
  • Secrets into the repo: detect .env / *.pem / strings that look like API keys / tokens → stop and ask
  • Large files / binaries into the repo: > 10MB or non-text → flag
  • Unknown local state: unknown branch / unfamiliar untracked files → inspect first, don't clean directly
  • Nested worktree: never create a worktree inside the main repo
  • Reusing a branch: don't attach the same branch to two worktrees

Hook failure handling: fix the issue → re-stage → new commit (don't amend; avoid changing the previous commit).

v0 won't do (advanced Git → user manual)

  • git rebase / git cherry-pick cross-branch history rewriting
  • Auto-resolving merge conflicts (always let the user decide)
  • git submodule operations
  • git lfs large-file management
  • GitHub Issue operations (unrelated to git itself)

Repo structure (conforming to Agent Skills standard)

easy-git/
├── SKILL.md            # Main skill file
│                         frontmatter has name: easy-git, description: ...
├── references/
│   ├── translation.md  # Full translation glossary (sourced from giteveryday)
│   ├── commit-style.md # Conventional Commits spec + public examples
│   ├── worktree-flow.md # Worktree lifecycle + naming rules
│   └── hook-recovery.md # Standard recovery flow for pre-commit hook failures
├── scripts/            # Safety detection scripts (secret scan, large-file scan, optional)
├── docs/prd.md         # This document
├── README.md           # User-facing entry point (User-Story style)
└── LICENSE             # MIT

4. References

Skill standard

Git official docs

Related / reference skills (existing git-related skills on GitHub)

Engineering practices and research

General git practice:

AI Agent + git:

Worktree + AI Agent parallelism:

User pain points (basis for README User Story):

Post-PRD to-dos

The content of the four sections above is settled. Before landing, still to do:

  • Write SKILL.md (per Agent Skills spec; frontmatter + body; keep under 500 lines)
  • Full references/translation.md glossary (comprehensive pass over giteveryday)
  • Full references/commit-style.md (Conventional Commits 1.0.0 + real public examples)
  • Full references/worktree-flow.md (worktree lifecycle + naming template; follows Git Worktrees 2026 Guide)
  • Full references/hook-recovery.md (standard recovery for pre-commit hook failures)
  • README rewrite: User-Story style + pain-point hooks (Git learning cost too high; having to repeatedly nudge the Agent every time) to clarify "what your world looks like after installing this"
  • Test fixture: empty sandbox repo + a set of dry-run commands to validate skill behavior across typical scenarios
  • Detailed analysis of netresearch/git-workflow-skill and other peers to confirm easy-git's differentiation; vendor parts if needed