From cb88caf52a5ed220f5f2d57ac81cdab32d063a4d Mon Sep 17 00:00:00 2001 From: bob walker Date: Tue, 24 Feb 2026 18:11:25 +0000 Subject: [PATCH] Update GEMINI.md guidelines and add DXW.md standards --- DXW.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ GEMINI.md | 46 ++++++++-------------------------------- 2 files changed, 72 insertions(+), 37 deletions(-) create mode 100644 DXW.md diff --git a/DXW.md b/DXW.md new file mode 100644 index 0000000..ae66865 --- /dev/null +++ b/DXW.md @@ -0,0 +1,63 @@ +# dxw Development Standards (GEMINI.md) + +This document provides project-level instructions and context for Gemini CLI agents, ensuring adherence to dxw's development standards and practices. + +## Core Principles +- **Secure by Design**: Prioritize security at every stage. Follow OWASP Top Ten guidelines. +- **High Quality**: Deliver stable, readable, and well-tested code. +- **Transparency**: Use clear commit messages, detailed PRs, and document architectural decisions. + +## Workflow & Task Management +- **Prerequisites**: Ensure you have a clear understanding of requirements and acceptance criteria before starting work. +- **Branching**: + - Always create a new branch for each task. + - Naming convention: `[ticket-number]/[short-description]` or `[type]/[ticket-number]-[short-description]` (e.g., `123/add-login-validation`). + - Avoid using personal names in branch identifiers. +- **TDD (Test-Driven Development)**: + - Develop code and tests concurrently. + - Aim for full test coverage. + - Ensure the test suite passes before every commit. + +## Version Control (Git) +- **Atomic Commits**: Make small, focused, and self-contained commits. +- **Commit Messages**: + - Use the imperative mood (e.g., "Add validation" not "Added validation"). + - Explain *what*, *why*, and *how*. + - Reference ticket numbers if available. +- **History Management**: + - Regularly rebase on the main development branch. + - Tidy up commit history (e.g., via interactive rebase) before requesting a code review. + - Prevent accidental commitment of sensitive data (API keys, credentials). + +## Code Review & Pull Requests +- **Mandatory Review**: All production code changes require review by at least two people (author + reviewer). +- **PR Content**: + - Link to the relevant ticket. + - Describe the problem and the solution. + - Highlight any specific difficulties or trade-offs. + - Include screenshots for UI changes. + - Clarify met acceptance criteria and any follow-up work. + +## Deployment & CI/CD +- **Continuous Delivery**: Automate builds, tests, and deployments (e.g., via GitHub Actions). +- **Versioning**: + - Application code: No explicit versioning required. + - Reusable components (libraries, gems, plugins): Must follow [Semantic Versioning](https://semver.org/). + +## Documentation +- **Changelog**: Maintain a `CHANGELOG.md` in the repository root for versioned components, following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +- **ADRs**: Document significant architectural decisions using Architectural Decision Records (ADRs). + +--- + +## Agent-Specific Instructions + +When working in this repository, you **must**: + +1. **Research First**: Always analyze existing tests and code style before implementing changes. +2. **Test Everything**: Do not consider a task complete until you have added or updated tests that verify the change and ensure no regressions. +3. **Commit Atomically**: Do not bundle unrelated changes. Use `git add -p` logic to stage only what is necessary for a specific commit. +4. **Rebase Frequently**: Before proposing a change, ensure your branch is rebased on the latest `main`. +5. **Detailed Explanations**: When explaining your work, focus on the "why" and "how" behind your technical decisions. +6. **Security Audit**: Proactively check for OWASP Top Ten vulnerabilities in any code you write or modify. +7. **No Secrets**: Never output or commit anything that looks like a secret or credential. diff --git a/GEMINI.md b/GEMINI.md index ea2643a..c29ab5b 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,40 +1,12 @@ -## Core Guidelines +## Core CLI Guidelines - **Persona:** Assume the user is a 30-year veteran system administrator. Skip explanations of basic concepts. Be direct, technical, and concise. -- **Direct Action:** Edit files directly. Do not commit or branch autonomously; always ask for permission first. Proactively suggest logical points for atomic commits and suggest new branches if the work deviates from the current scope or a significant task shift occurs. +- **Direct Action:** Edit files directly. Do not commit or branch autonomously; always ask for permission first. - **Code Comments:** Use them sparingly. Only explain complex "why" logic. Never explain "what" the code is doing. -- **Project Discovery:** - - Always check for a `Makefile` or `scripts/` directory first for build/test/lint commands. - - Identify language stacks via manifests (`package.json`, `go.mod`, `Cargo.toml`, `requirements.txt`). -- **Language Defaults:** - - **Ruby:** Assume `bundler`. - - **Python:** Assume `virtualenv`. - - **Node.js:** Check for `package-lock.json` (npm) vs `yarn.lock`. - - **Go:** Assume `go modules`. -- **Standards & Testing:** - - Mimic local indentation (tabs vs spaces) and naming conventions exactly. - - Always write a test if a framework exists. Match the existing style (e.g., table-driven tests in Go). - - Respect `.gitignore` and `.editorconfig`. -- **Shell Usage:** Prefer non-interactive commands with silent/quiet flags (e.g., `apt-get -y`, `npm install --quiet`). -- **Git Branching:** - - **Discovery:** On new repo entry, ask "Does this repo require feature branches?". Record answer in the repo's `GEMINI.md`. - - Use a new branch for each feature or bug fix. - - include ticket/issue number in branch name if available (e.g., `123-add-login`). - - Naming convention: `description` (e.g., `add-login`, `memory-leak`). - - Branch from the default branch (`main` or `master`) and keep branches short-lived. - - Rebase from the default branch frequently to avoid conflicts. -- **Git Worktrees:** - - Suggest `git worktree` for parallel tasks or frequent context switching. - - **Discovery:** On new repo entry, ask "Is this repo suitable for worktrees?". Record answer in the repo's `GEMINI.md`. -- **Git Safety & History:** - - **Pre-commit:** Always run `git diff` (or `git diff --staged`) to verify changes before asking to commit. - - **Force Push:** Permitted *only* on private feature branches (`--force-with-lease`). Never on shared/main branches. - - **Conflicts:** If a rebase/merge encounters complex conflicts, abort and ask for guidance. - - **Cleanup:** Squash "wip" or "fix typo" commits into the main feature commit before final merge instructions. -- **Git Commits:** - - Use present tense, imperative mood (e.g., `resolve memory leak`). - - Keep summary <= 50 chars; wrap body at 72 chars. - - Explain _why_ in the body, not _what_. - - Reference issue/ticket numbers if available (e.g., `Fixes #456`). - - Keep commits atomic; one logical change per commit. - - Separate whitespace and linting changes into their own commits, distinct from functional logic changes. +- **Project Discovery:** Always check for a `Makefile` or `scripts/` directory first for build/test/lint commands. Identify language stacks via manifests (`package.json`, `go.mod`, etc.). +- **Engineering Standards:** Mimic local indentation (tabs vs spaces) and naming conventions exactly. Respect `.editorconfig` and `.gitignore`. +- **Shell Usage:** Prefer non-interactive commands with silent/quiet flags (e.g., `npm install --quiet`). +- **Safety:** Always run `git diff` (or `git diff --staged`) to verify changes before asking to commit. + +## dxw Standards +@./DXW.md