diff --git a/README.md b/README.md index 717af9a6..b55fe2d1 100644 --- a/README.md +++ b/README.md @@ -171,12 +171,13 @@ Agent: Audits the diff against the design doc — scope creep, ## What changes in agent behavior -The flow above is powered by eight built-in skills, each addressing a failure mode developers see in real AI coding sessions: +The flow above is powered by nine built-in skills, each addressing a failure mode developers see in real AI coding sessions: | Failure mode | AI DevKit behavior | |--------------|--------------------| | Agent starts coding too early | `dev-lifecycle` forces requirements, design, planning, implementation, tests, and review | | Agent says "done" without proof | `verify` blocks completion claims without fresh test/build evidence | +| Agent commits unrelated local changes | `dev-commit` checks diffs, stages explicit paths, validates, and reports the SHA/status | | Agent forgets project decisions | `memory` gives it a local, searchable knowledge base across sessions and projects | | New behavior ships without tests | `tdd` pushes test-first implementation | | Debugging becomes guess-and-patch | `structured-debug` makes it reproduce, hypothesize, fix, and verify | diff --git a/packages/cli/src/__tests__/commands/skill.test.ts b/packages/cli/src/__tests__/commands/skill.test.ts index 607d63e8..a5dc453b 100644 --- a/packages/cli/src/__tests__/commands/skill.test.ts +++ b/packages/cli/src/__tests__/commands/skill.test.ts @@ -91,6 +91,10 @@ describe('skill command', () => { global: undefined, environments: undefined, }); + expect(mockAddSkill).toHaveBeenCalledWith('codeaholicguy/ai-devkit', 'dev-commit', { + global: undefined, + environments: undefined, + }); expect(mockAddSkill).toHaveBeenCalledWith('codeaholicguy/ai-devkit', 'dev-worktree', { global: undefined, environments: undefined, diff --git a/packages/cli/src/constants.ts b/packages/cli/src/constants.ts index 3671c3e4..c8f4736e 100644 --- a/packages/cli/src/constants.ts +++ b/packages/cli/src/constants.ts @@ -13,6 +13,7 @@ export const BUILTIN_SKILL_REGISTRY = 'codeaholicguy/ai-devkit'; export const BUILTIN_SKILL_NAMES = [ 'agent-communication', 'agent-management', + 'dev-commit', 'dev-lifecycle', 'dev-worktree', 'dev-requirements', diff --git a/skills/dev-commit/SKILL.md b/skills/dev-commit/SKILL.md new file mode 100644 index 00000000..f47dfdc7 --- /dev/null +++ b/skills/dev-commit/SKILL.md @@ -0,0 +1,39 @@ +--- +name: dev-commit +description: AI DevKit · Safe git commit workflow for AI coding agents. Use when the user asks to commit, prepare a commit, stage changes, create a PR-ready checkpoint, or finish work with a conventional commit while avoiding unrelated user changes. +--- + +# Dev Commit + +Make one intentional, verified commit without sweeping in unrelated work. + +## Commit Contract + +1. Check repository state with `git status --short --branch`, `git diff --stat`, and `git diff`. +2. Identify the files that belong to the requested change. Treat pre-existing user edits, local config, generated artifacts, dependency caches, build outputs, and unrelated formatting churn as out of scope unless the user explicitly includes them. +3. Run appropriate validation before committing. Prefer the repo's targeted tests, lint, typecheck, build, or documented verification commands. Record skipped validation with the reason. +4. Stage only intended paths. Prefer explicit pathspecs such as `git add path/to/file` over `git add .`. +5. Re-check with `git diff --cached --stat`, `git diff --cached`, and `git status --short`. +6. Write a concise conventional commit message: `(optional-scope): `. +7. Commit, then report the commit SHA, final status, validation commands, and any unstaged/untracked files left behind. + +## Guardrails + +- Do not commit secrets, credentials, `.env` files, local machine config, caches, coverage, logs, screenshots, or generated files unless the change explicitly requires them. +- Do not stage another person's unrelated edits. If intended and unrelated changes are mixed in one file, use an interactive or patch-based staging flow and review the staged diff carefully. +- Do not amend, rebase, force-push, reset, or delete branches unless the user explicitly asks for that operation. +- If validation fails, stop before committing unless the user explicitly instructs you to commit with failing validation. Report the failing command and key output. +- If the repo has commit hooks, let them run. If a hook changes files, inspect and stage only intended hook outputs before retrying. + +## Message Style + +Use semantic or conventional commit types that match the change: + +- `feat`: user-facing feature or capability +- `fix`: bug fix +- `docs`: documentation-only change +- `test`: test-only change +- `refactor`: behavior-preserving code restructuring +- `chore`: maintenance, build, tooling, metadata, or generated index updates + +Keep the subject under about 72 characters when practical, imperative, and specific. Add a body only when it explains non-obvious validation, risk, migration, or follow-up context. diff --git a/skills/dev-commit/agents/openai.yaml b/skills/dev-commit/agents/openai.yaml new file mode 100644 index 00000000..96278ba4 --- /dev/null +++ b/skills/dev-commit/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Dev Commit" + short_description: "AI DevKit · Commit only intended, verified changes" + default_prompt: "Use $dev-commit to review, stage, commit, and report this work safely." diff --git a/skills/index.json b/skills/index.json index 47e34d73..fc4954da 100644 --- a/skills/index.json +++ b/skills/index.json @@ -710,6 +710,13 @@ "description": "AI DevKit · Update CHANGELOG.md Unreleased items from git commits since the latest release. Use when users ask to update changelog/release notes from recent commits, with one concise line per commit and commit/PR links.", "lastIndexed": 1782001853281 }, + { + "name": "dev-commit", + "registry": "codeaholicguy/ai-devkit", + "path": "skills/dev-commit", + "description": "AI DevKit · Safe git commit workflow for AI coding agents. Use when the user asks to commit, prepare a commit, stage changes, create a PR-ready checkpoint, or finish work with a conventional commit while avoiding unrelated user changes.", + "lastIndexed": 1782001853290 + }, { "name": "dev-design", "registry": "codeaholicguy/ai-devkit", diff --git a/web/content/docs/1-getting-started.md b/web/content/docs/1-getting-started.md index e55d015d..871cbd57 100644 --- a/web/content/docs/1-getting-started.md +++ b/web/content/docs/1-getting-started.md @@ -113,6 +113,7 @@ Terminal commands still start with `ai-devkit`; skills are used by the agent ins |---------|---------| | `dev-lifecycle` | Orchestrate worktree setup, requirements, design, planning, implementation, testing, and review | | `dev-worktree`, `dev-requirements`, `dev-design`, `dev-planning`, `dev-implementation`, `dev-testing`, `dev-review` | Run focused lifecycle phases directly | +| `dev-commit` | Commit only intended, verified changes with a conventional message | | `tdd` | Add or change behavior test-first | | `verify` | Require fresh command output before completion claims | | `structured-debug` | Debug issues with reproduction, hypotheses, fixes, and verification | diff --git a/web/content/docs/7-skills.md b/web/content/docs/7-skills.md index b439b5e8..25bf0a8c 100644 --- a/web/content/docs/7-skills.md +++ b/web/content/docs/7-skills.md @@ -27,6 +27,7 @@ AI DevKit ships with a core set of skills in its default registry: |---|---| | `agent-orchestration` | Coordinate running AI agents and manage multi-agent workflows | | `document-code` | Document code entry points with structured analysis and dependency mapping | +| `dev-commit` | Commit only intended, verified changes with a conventional message | | `dev-lifecycle` | Orchestrate the SDLC workflow and route to phase skills | | `dev-worktree`, `dev-requirements`, `dev-design`, `dev-planning`, `dev-implementation`, `dev-testing`, `dev-review` | Run focused SDLC phases directly | | `structured-debug` | Follow a disciplined debugging and RCA process before implementing fixes | diff --git a/web/lib/skills/built-in.ts b/web/lib/skills/built-in.ts index b787c3a0..f6ee3a28 100644 --- a/web/lib/skills/built-in.ts +++ b/web/lib/skills/built-in.ts @@ -177,6 +177,20 @@ export const builtInSkills: BuiltInSkill[] = [ ], relatedAgents: ["Claude Code", "Codex"], }, + { + name: "dev-commit", + title: "Dev Commit", + category: "Workflow", + summary: "Create safe, verified commits from only the intended changes.", + description: + "Use dev-commit when work is ready to save as a git commit. It guides agents through status and diff inspection, validation, explicit staging, conventional commit messages, and final SHA/status reporting without including unrelated local changes.", + useCases: [ + "Commit finished work without sweeping in unrelated files", + "Stage only the intended paths after reviewing diffs", + "Record validation evidence and a conventional commit message", + ], + relatedAgents: ["Claude Code", "Codex", "Cursor", "opencode"], + }, { name: "dev-worktree", title: "Dev Worktree", diff --git a/web/public/llms.txt b/web/public/llms.txt index ad4fa1c8..dedca280 100644 --- a/web/public/llms.txt +++ b/web/public/llms.txt @@ -30,6 +30,7 @@ npx ai-devkit@latest init ## Key Skills - `dev-lifecycle` - Start a new feature, validate requirements and design, execute plans, and run pre-commit reviews +- `dev-commit` - Commit only intended, verified changes with a conventional message - `tdd` - Add test coverage with a test-first workflow - `structured-debug` - Debug systematically with reproduction, hypotheses, fixes, and verification - `memory` - Store important guidelines and patterns in memory