# Project Rules
Generated by @hivellm/rulebook
Generated at: 2025-11-03T01:49:55.258Z
# Quality Enforcement Rules
**CRITICAL**: These rules are NON-NEGOTIABLE and MUST be followed without exception.
## Absolute Prohibitions
### Test Bypassing - STRICTLY FORBIDDEN
- NEVER use .skip(), .only(), or .todo() to bypass failing tests
- NEVER comment out failing tests
- NEVER use @ts-ignore, @ts-expect-error, or similar to hide test errors
- NEVER mock/stub functionality just to make tests pass without fixing root cause
- FIX the actual problem causing test failures
### Git Hook Bypassing - STRICTLY FORBIDDEN
- NEVER use --no-verify flag on git commit
- NEVER use --no-verify flag on git push
- NEVER disable or skip pre-commit hooks
- NEVER disable or skip pre-push hooks
- FIX the issues that hooks are detecting
### Test Implementation - STRICTLY FORBIDDEN
- NEVER create boilerplate tests that don't actually test behavior
- NEVER write tests that always pass regardless of implementation
- NEVER write tests without assertions
- NEVER mock everything to avoid testing real behavior
- WRITE meaningful tests that verify actual functionality
### Problem Solving Approach - REQUIRED
- DO NOT seek the simplest bypass or workaround
- DO NOT be creative with shortcuts that compromise quality
- DO solve problems properly following best practices
- DO use proven, established solutions from decades of experience
- DO fix root causes, not symptoms
## Enforcement
These rules apply to ALL implementations:
- Bug fixes
- New features
- Refactoring
- Documentation changes
- Any code modifications
**Violation = Implementation Rejected**
## Documentation Standards
**CRITICAL**: Minimize Markdown files. Keep documentation organized.
### Allowed Root-Level Documentation
Only these files are allowed in the project root:
- ✅ `README.md` - Project overview and quick start
- ✅ `CHANGELOG.md` - Version history and release notes
- ✅ `AGENTS.md` - This file (AI assistant instructions)
- ✅ `LICENSE` - Project license
- ✅ `CONTRIBUTING.md` - Contribution guidelines
- ✅ `CODE_OF_CONDUCT.md` - Code of conduct
- ✅ `SECURITY.md` - Security policy
### All Other Documentation
**ALL other documentation MUST go in `/docs` directory**:
- `/docs/ARCHITECTURE.md` - System architecture
- `/docs/DEVELOPMENT.md` - Development guide
- `/docs/ROADMAP.md` - Project roadmap
- `/docs/DAG.md` - Component dependencies (DAG)
- `/docs/specs/` - Feature specifications
- `/docs/sdks/` - SDK documentation
- `/docs/protocols/` - Protocol specifications
- `/docs/guides/` - Developer guides
- `/docs/diagrams/` - Architecture diagrams
- `/docs/benchmarks/` - Performance benchmarks
- `/docs/versions/` - Version release reports
## Testing Requirements
**CRITICAL**: All features must have comprehensive tests.
- **Minimum Coverage**: 95%
- **Test Location**: `/tests` directory in project root
- **Test Execution**: 100% of tests MUST pass before moving to next task
- **Test First**: Write tests based on specifications before implementation
## Feature Development Workflow
**CRITICAL**: Follow this workflow for all feature development.
1. **Check Specifications First**:
- Read `/docs/specs/` for feature specifications
- Review `/docs/ARCHITECTURE.md` for system design
- Check `/docs/ROADMAP.md` for implementation timeline
- Review `/docs/DAG.md` for component dependencies
2. **Implement with Tests**:
- Write tests in `/tests` directory first
- Implement feature following specifications
- Ensure tests pass and meet coverage threshold
3. **Quality Checks**:
- Run code formatter
- Run linter (must pass with no warnings)
- Run all tests (must be 100% passing)
- Verify coverage meets threshold
4. **Update Documentation**:
- Update `/docs/ROADMAP.md` progress
- Update feature specs if implementation differs
- Document any deviations with justification
## Rules Configuration
Rules can be selectively disabled using `.rulesignore` file in project root.
Example `.rulesignore`:
```
# Ignore coverage requirement
coverage-threshold
# Ignore specific language rules
rust/edition-2024
# Ignore all TypeScript rules
typescript/*
```
# Rust Project Rules
## Agent Automation Commands
**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
```bash
# Complete quality check sequence:
cargo fmt --all -- --check # Format check
cargo clippy --workspace --all-targets --all-features -- -D warnings # Lint
cargo test --workspace --all-features # All tests (100% pass)
cargo build --release # Build verification
cargo llvm-cov --all # Coverage (95%+ required)
# Security audit:
cargo audit # Vulnerability scan
cargo outdated # Check outdated deps
```
## Rust Edition and Toolchain
**CRITICAL**: Always use Rust Edition 2024 with nightly toolchain.
- **Edition**: 2024
- **Toolchain**: nightly 1.85+
- **Update**: Run `rustup update nightly` regularly
### Formatting
- Use `rustfmt` with nightly toolchain
- Configuration in `rustfmt.toml` or `.rustfmt.toml`
- Always format before committing: `cargo +nightly fmt --all`
- CI must check formatting: `cargo +nightly fmt --all -- --check`
### Linting
- Use `clippy` with `-D warnings` (warnings as errors)
- Fix all clippy warnings before committing
- Acceptable exceptions must be documented with `#[allow(clippy::...)]` and justification
- CI must enforce clippy: `cargo clippy --workspace -- -D warnings`
### Testing
- **Location**: Tests in `/tests` directory for integration tests
- **Unit Tests**: In same file as implementation with `#[cfg(test)]`
- **Coverage**: Must meet project threshold (default 95%)
- **Tools**: Use `cargo-nextest` for faster test execution
- **Async**: Use `tokio::test` for async tests with Tokio runtime
Example test structure:
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_feature() {
// Test implementation
}
#[tokio::test]
async fn test_async_feature() {
// Async test implementation
}
}
```
## Async Programming
**CRITICAL**: Follow Tokio best practices for async code.
- **Runtime**: Use Tokio for async runtime
- **Blocking**: Never block in async context - use `spawn_blocking` for CPU-intensive tasks
- **Channels**: Use `tokio::sync::mpsc` or `tokio::sync::broadcast` for async communication
- **Timeouts**: Always set timeouts for network operations: `tokio::time::timeout`
Example:
```rust
use tokio::time::{timeout, Duration};
async fn fetch_data() -> Result<Data, Error> {
timeout(Duration::from_secs(30), async {
// Network operation
}).await?
}
```
## Dependency Management
**CRITICAL**: Always verify latest versions before adding dependencies.
### Before Adding Any Dependency
1. **Check Context7 for latest version**:
- Use MCP Context7 tool if available
- Search for the crate documentation
- Verify the latest stable version
- Review breaking changes and migration guides
2. **Example Workflow**:
```
Adding tokio → Check crates.io and docs.rs
Adding serde → Verify latest version with security updates
Adding axum → Check for breaking changes in latest version
```
3. **Document Version Choice**:
- Note why specific version chosen in `Cargo.toml` comments
- Document any compatibility constraints
- Update CHANGELOG.md with new dependencies
### Dependency Guidelines
- ✅ Use latest stable versions
- ✅ Check for security advisories: `cargo audit`
- ✅ Prefer well-maintained crates (active development, good documentation)
- ✅ Minimize dependency count
- ✅ Use workspace dependencies for monorepos
- ❌ Don't use outdated versions without justification
- ❌ Don't add dependencies without checking latest version
## Codespell Configuration
**CRITICAL**: Use codespell to catch typos in code and documentation.
Install: `pip install 'codespell[toml]'`
Configuration in `pyproject.toml`:
```toml
[tool.codespell]
skip = "*.lock,*.json,target,node_modules,.git"
ignore-words-list = "crate,ser,deser"
```
Or run with flags:
```bash
codespell \
--skip="*.lock,*.json,target,node_modules,.git" \
--ignore-words-list="crate,ser,deser"
```
## Error Handling
- Use `Result<T, E>` for recoverable errors
- Use `thiserror` for custom error types
- Use `anyhow` for application-level error handling
- Document error conditions in function docs
- Never use `unwrap()` or `expect()` in production code without justification
Example:
```rust
use thiserror::Error;
#[derive(Error, Debug)]
pub enum MyError {
#[error("IO error: {0}")]
Io(#[from] std::io::Error),
#[error("Invalid input: {0}")]
InvalidInput(String),
}
pub fn process_data(input: &str) -> Result<Data, MyError> {
// Implementation
}
```
## Documentation
- **Public APIs**: Must have doc comments (`///`)
- **Examples**: Include examples in doc comments
- **Modules**: Document module purpose with `//!`
- **Unsafe**: Always document safety requirements for `unsafe` code
- **Run doctests**: `cargo test --doc`
Example:
```rust
/// Processes the input data and returns a result.
///
/// # Arguments
///
/// * `input` - The input string to process
///
/// # Examples
///
/// ```
/// use mylib::process;
/// let result = process("hello");
/// assert_eq!(result, "HELLO");
/// ```
///
/// # Errors
///
/// Returns `MyError::InvalidInput` if input is empty.
pub fn process(input: &str) -> Result<String, MyError> {
// Implementation
}
```
## Project Structure
```
project/
├── Cargo.toml # Package manifest
├── Cargo.lock # Dependency lock file (commit this)
├── README.md # Project overview (allowed in root)
├── CHANGELOG.md # Version history (allowed in root)
├── AGENTS.md # AI assistant rules (allowed in root)
├── LICENSE # Project license (allowed in root)
├── CONTRIBUTING.md # Contribution guidelines (allowed in root)
├── CODE_OF_CONDUCT.md # Code of conduct (allowed in root)
├── SECURITY.md # Security policy (allowed in root)
├── src/
│ ├── lib.rs # Library root (for libraries)
│ ├── main.rs # Binary root (for applications)
│ └── ...
├── tests/ # Integration tests
├── examples/ # Example code
├── benches/ # Benchmarks
└── docs/ # Project documentation
```
## CI/CD Requirements
Must include GitHub Actions workflows for:
1. **Testing** (`rust-test.yml`):
- Test on ubuntu-latest, windows-latest, macos-latest
- Use `cargo-nextest` for fast test execution
- Upload test results
2. **Linting** (`rust-lint.yml`):
- Format check: `cargo +nightly fmt --all -- --check`
- Clippy: `cargo clippy --workspace -- -D warnings`
- All targets: `cargo clippy --workspace --all-targets -- -D warnings`
3. **Codespell** (`codespell.yml`):
- Check for typos in code and documentation
- Fail on errors
## Crate Publication
### Publishing to crates.io
**Prerequisites:**
1. Create account at https://crates.io
2. Generate API token: `cargo login`
3. Add `CARGO_TOKEN` to GitHub repository secrets
**Cargo.toml Configuration:**
```toml
[package]
name = "your-crate-name"
version = "1.0.0"
edition = "2024"
authors = ["Your Name <your.email@example.com>"]
license = "MIT OR Apache-2.0"
description = "A short description of your crate"
documentation = "https://docs.rs/your-crate-name"
homepage = "https://github.com/your-org/your-crate-name"
repository = "https://github.com/your-org/your-crate-name"
readme = "README.md"
keywords = ["your", "keywords", "here"]
categories = ["category"]
exclude = [
".github/",
"tests/",
"benches/",
"examples/",
"*.sh",
]
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
```
**Publishing Workflow:**
1. Update version in Cargo.toml
2. Update CHANGELOG.md
3. Run quality checks:
```bash
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --all-features
cargo doc --no-deps --all-features
```
4. Create git tag: `git tag v1.0.0 && git push --tags`
5. GitHub Actions automatically publishes to crates.io
6. Or manual publish: `cargo publish`
**Publishing Checklist:**
- ✅ All tests passing (`cargo test --all-features`)
- ✅ No clippy warnings (`cargo clippy -- -D warnings`)
- ✅ Code formatted (`cargo fmt --all -- --check`)
- ✅ Documentation builds (`cargo doc --no-deps`)
- ✅ Version updated in Cargo.toml
- ✅ CHANGELOG.md updated
- ✅ README.md up to date
- ✅ LICENSE file present
- ✅ Package size < 10MB (check with `cargo package --list`)
- ✅ Verify with `cargo publish --dry-run`
**Semantic Versioning:**
Follow [SemVer](https://semver.org/) strictly:
- **MAJOR**: Breaking API changes
- **MINOR**: New features (backwards compatible)
- **PATCH**: Bug fixes (backwards compatible)
**Documentation:**
- Use `///` for public API documentation
- Include examples in doc comments
- Use `#![deny(missing_docs)]` for libraries
- Test documentation examples with `cargo test --doc`
```rust
/// Processes the input data and returns a result.
///
/// # Arguments
///
/// * `input` - The input string to process
///
/// # Examples
///
/// ```
/// use your_crate::process;
///
/// let result = process("hello");
/// assert_eq!(result, "HELLO");
/// ```
///
/// # Errors
///
/// Returns an error if the input is empty.
pub fn process(input: &str) -> Result<String, Error> {
// Implementation
}
```
# Agent Automation Rules
**CRITICAL**: Mandatory workflow that AI agents MUST execute after EVERY implementation.
## Workflow Overview
After completing ANY feature, bug fix, or code change, execute this workflow in order:
### Step 1: Quality Checks (MANDATORY)
Run these checks in order - ALL must pass:
```bash
1. Type check (if applicable)
2. Lint (MUST pass with ZERO warnings)
3. Format code
4. Run ALL tests (MUST pass 100%)
5. Verify coverage meets threshold (default 95%)
```
**Language-specific commands**: See your language template (TYPESCRIPT, RUST, PYTHON, etc.) for exact commands.
**IF ANY CHECK FAILS:**
- ❌ STOP immediately
- ❌ DO NOT proceed
- ❌ DO NOT commit
- ✅ Fix the issue first
- ✅ Re-run ALL checks
### Step 2: Security & Dependency Audits
```bash
# Check for vulnerabilities (language-specific)
# Check for outdated dependencies (informational)
# Find unused dependencies (optional)
```
**Language-specific commands**: See your language template for audit commands.
**IF VULNERABILITIES FOUND:**
- ✅ Attempt automatic fix
- ✅ Document if auto-fix fails
- ✅ Include in Step 5 report
- ❌ Never ignore critical/high vulnerabilities without user approval
### Step 3: Update OpenSpec Tasks
If `openspec/` directory exists:
```bash
# Mark completed tasks as [DONE]
# Update in-progress tasks
# Add new tasks if discovered
# Update progress percentages
# Document deviations or blockers
```
### Step 4: Update Documentation
```bash
# Update ROADMAP.md (if feature is milestone)
# Update CHANGELOG.md (conventional commits format)
# Update feature specs (if implementation differs)
# Update README.md (if public API changed)
```
### Step 5: Git Commit
**ONLY after ALL above steps pass:**
```bash
git add .
git commit -m "<type>(<scope>): <description>
- Detailed change 1
- Detailed change 2
- Tests: [describe coverage]
- Coverage: X% (threshold: 95%)
Closes #<issue> (if applicable)"
```
**Commit Types**: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
### Step 6: Report to User
```
✅ Implementation Complete
📝 Changes:
- [List main changes]
🧪 Quality Checks:
- ✅ Type check: Passed
- ✅ Linting: Passed (0 warnings)
- ✅ Formatting: Applied
- ✅ Tests: X/X passed (100%)
- ✅ Coverage: X% (threshold: 95%)
🔒 Security:
- ✅ No vulnerabilities
📊 OpenSpec:
- ✅ Tasks updated
- ✅ Progress: X% → Y%
📚 Documentation:
- ✅ CHANGELOG.md updated
- ✅ [other docs updated]
💾 Git:
- ✅ Committed: <commit message>
- ✅ Hash: <commit hash>
📋 Next Steps:
- [ ] Review changes
- [ ] Push to remote (if ready)
```
## Automation Exceptions
Skip steps ONLY when:
1. **Exploratory Code**: User says "experimental", "draft", "try"
- Still run quality checks
- Don't commit
2. **User Explicitly Requests**: User says "skip tests", "no commit"
- Only skip requested step
- Warn about skipped steps
3. **Emergency Hotfix**: Critical production bug
- Run minimal checks
- Document technical debt
**In ALL other cases: Execute complete workflow**
## Error Recovery
If workflow fails 3+ times:
```bash
1. Create backup branch
2. Reset to last stable commit
3. Report to user with error details
4. Request guidance or try alternative approach
```
## Best Practices
### DO's ✅
- ALWAYS run complete workflow
- ALWAYS update OpenSpec and documentation
- ALWAYS use conventional commits
- ALWAYS report summary to user
- ASK before skipping steps
### DON'Ts ❌
- NEVER skip quality checks without permission
- NEVER commit failing tests
- NEVER commit linting errors
- NEVER skip documentation updates
- NEVER assume user wants to skip automation
- NEVER commit debug code or secrets
## Summary
**Complete workflow after EVERY implementation:**
1. ✅ Quality checks (type, lint, format, test, coverage)
2. ✅ Security audit
3. ✅ Update OpenSpec tasks
4. ✅ Update documentation
5. ✅ Git commit (conventional format)
6. ✅ Report summary to user
**Only skip with explicit user permission and document why.**
# Vectorizer Instructions
**CRITICAL**: Use MCP Vectorizer as primary data source for project information instead of file reading.
## Core Functions
### Search
```
mcp_vectorizer_search - Multiple strategies:
- intelligent: AI-powered with query expansion
- semantic: Advanced with reranking
- contextual: Context-aware with filtering
- multi_collection: Cross-project search
- batch: Parallel queries
- by_file_type: Filter by extension (.rs, .ts, .py)
```
### File Operations
```
get_content - Retrieve file without disk I/O
list_files - List indexed files with metadata
get_summary - File summaries (extractive/structural)
get_chunks - Progressive reading of large files
get_outline - Project structure overview
get_related - Find semantically related files
```
### Discovery
```
full_pipeline - Complete discovery with scoring
broad_discovery - Multi-query with deduplication
semantic_focus - Deep semantic search
expand_queries - Generate query variations
```
## When to Use
| Task | Tool |
|------|------|
| Explore unfamiliar code | intelligent search |
| Read file | get_content |
| Understand structure | get_outline |
| Find related files | get_related |
| Read large file | get_chunks |
| Complex question | full_pipeline |
## Best Practices
✅ **DO:**
- Start with intelligent search for exploration
- Use file_operations to avoid disk I/O
- Batch queries for related items
- Set similarity thresholds (0.6-0.8)
- Use specific collections when known
❌ **DON'T:**
- Read files from disk when available in vectorizer
- Use sequential searches (batch instead)
- Skip similarity thresholds
- Search entire codebase when collection is known
<!-- VECTORIZER:END -->
<!-- OPENSPEC:START -->
# OpenSpec Instructions
**CRITICAL**: Use OpenSpec for spec-driven development of new features and breaking changes.
## When to Use
Create proposal for:
- ✅ New features/capabilities
- ✅ Breaking changes
- ✅ Architecture changes
- ✅ Performance/security work
Skip for:
- ❌ Bug fixes (restore intended behavior)
- ❌ Typos, formatting, comments
- ❌ Dependency updates (non-breaking)
## Task Creation Guidelines
**CRITICAL**: Before creating ANY OpenSpec task, you MUST:
1. **Check Context7 MCP** (if available):
- Use Context7 to review documentation and best practices for the technology/library involved
- Verify the correct task format and structure
- Review existing task examples from official documentation
- Most AIs create tasks in the wrong format - Context7 helps prevent this
2. **Validate Format Requirements**:
- Ensure scenario format uses `#### Scenario:` (4 hashtags)
- Follow SHALL/MUST conventions for requirements
- Include proper WHEN/THEN structure
**Why This Matters:**
Many AI assistants create OpenSpec tasks in incorrect formats, causing validation failures and rework. Using Context7 to review proper task structures BEFORE creation saves time and ensures consistency.
## Quick Start
```bash
# 1. Check existing
openspec list --specs
openspec list
# 2. Create change
CHANGE=add-your-feature
mkdir -p openspec/changes/$CHANGE/specs/capability-name
# 3. Create files
# - proposal.md (why, what, impact)
# - tasks.md (implementation checklist)
# - specs/capability-name/spec.md (deltas)
# 4. Validate
openspec validate $CHANGE --strict
```
## Spec Format
**CRITICAL**: Scenario format MUST be exact:
```markdown
## ADDED Requirements
### Requirement: Feature Name
The system SHALL provide...
#### Scenario: Success case
- **WHEN** user performs action
- **THEN** expected result occurs
```
❌ **WRONG:**
```markdown
- **Scenario: Login** # NO - bullet
**Scenario**: Login # NO - bold
### Scenario: Login # NO - 3 hashtags
```
✅ **CORRECT:**
```markdown
#### Scenario: User login # YES - 4 hashtags
```
## Three-Stage Workflow
### Stage 1: Create
1. Read `openspec/project.md`
2. Choose verb-led `change-id` (e.g., `add-auth`, `update-api`)
3. Create `proposal.md`, `tasks.md`, delta specs
4. Validate: `openspec validate [id] --strict`
5. Get approval
### Stage 2: Implement
1. Read `proposal.md`, `tasks.md`
2. Implement tasks
3. Run AGENT_AUTOMATION workflow
4. Update tasks as complete
5. Document commit hash in tasks.md
### Stage 3: Archive
After deployment:
```bash
openspec archive [change] --yes
```
## Commands
```bash
openspec list # Active changes
openspec list --specs # All capabilities
openspec show [item] # View details
openspec validate [change] --strict # Validate
openspec diff [change] # Show changes
openspec archive [change] --yes # Complete
```
## Best Practices
✅ **DO:**
- **Check Context7 MCP before creating tasks** (prevents format errors)
- One requirement per concern
- At least one scenario per requirement
- Use SHALL/MUST for normative requirements
- Validate before committing
- Keep changes focused and small
❌ **DON'T:**
- Create tasks without checking Context7 MCP first
- Mix multiple features in one change
- Skip scenario definitions
- Use wrong scenario format
- Start implementation before approval
## Integration with AGENT_AUTOMATION
OpenSpec drives implementation. AGENT_AUTOMATION enforces quality:
```
1. Create spec → Validate → Approve
2. Implement → Run AGENT_AUTOMATION
3. Update tasks.md with commit hash
4. Archive when deployed
```
<!-- OPENSPEC:END -->
<!-- CONTEXT7:START -->
# Context7 Instructions
**CRITICAL**: Use MCP Context7 to access up-to-date library documentation before adding dependencies.
## Core Functions
### 1. resolve-library-id
Resolve a package name to Context7-compatible library ID:
```
resolve-library-id("tokio") → "/tokio-rs/tokio"
resolve-library-id("react") → "/facebook/react"
```
### 2. get-library-docs
Fetch documentation with optional topic filter:
```
get-library-docs("/tokio-rs/tokio", topic="async")
```
## Workflow
**Before adding ANY dependency:**
```
1. resolve-library-id(library_name)
2. get-library-docs(library_id)
3. Check latest version and security
4. Add dependency with correct version
5. Document choice in commit
```
**Before updating major version:**
```
1. get-library-docs for current version
2. get-library-docs for target version
3. Review breaking changes
4. Plan migration
```
## Best Practices
✅ **DO:**
- Always check Context7 before adding dependencies
- Use topic parameter for specific info
- Document version choices
- Review security advisories
❌ **DON'T:**
- Add dependencies without checking latest version
- Skip migration guides on major updates
- Ignore security warnings
<!-- CONTEXT7:END -->
<!-- GIT:START -->
**AI Assistant Git Push Mode**: MANUAL
**CRITICAL**: Never execute `git push` commands automatically.
Always provide push commands for manual execution by the user.
Example:
```
✋ MANUAL ACTION REQUIRED:
Run these commands manually (SSH password may be required):
git push origin main
git push origin v1.0.0
```
# Git Workflow Rules
**CRITICAL**: Specific rules and patterns for Git version control workflow.
## Git Workflow Overview
This project follows a strict Git workflow to ensure code quality and proper version control.
**NEVER commit code without tests passing. NEVER create tags without full quality checks.**
## Initial Repository Setup
### New Project Initialization
**⚠️ CRITICAL**: Only run initialization commands if `.git` directory does NOT exist!
```bash
# Check if Git repository already exists
if [ -d .git ]; then
echo "❌ Git repository already initialized. Skipping git init."
echo "Current status:"
git status
git remote -v
exit 0
fi
# If no .git directory exists, initialize:
# Initialize Git repository
git init
# Add all files
git add .
# Initial commit
git commit -m "chore: Initial project setup"
# Rename default branch to main (GitHub standard)
git branch -M main
# Add remote (if applicable)
git remote add origin <repository-url>
```
**AI Assistant Behavior:**
```
BEFORE running any Git initialization commands:
1. Check if .git directory exists
2. If exists:
✅ Repository already configured
❌ DO NOT run: git init
❌ DO NOT run: git branch -M main
✅ Check status: git status
✅ Show remotes: git remote -v
3. If not exists:
✅ Safe to initialize
✅ Run full initialization sequence
```
## AI Assistant Git Checks
**CRITICAL**: AI assistants MUST perform these checks before Git operations:
### Automatic Checks
```bash
# 1. Check if Git repository exists
if [ ! -d .git ]; then
echo "No Git repository found."
# Ask user if they want to initialize
fi
# 2. Check if there are unstaged changes
git status --short
# 3. Check current branch
CURRENT_BRANCH=$(git branch --show-current)
echo "On branch: $CURRENT_BRANCH"
# 4. Check if remote exists
git remote -v
# 5. Check for unpushed commits
git log origin/main..HEAD --oneline 2>/dev/null
```
### Before Git Commands
**NEVER execute if `.git` directory exists:**
- ❌ `git init` - Repository already initialized
- ❌ `git branch -M main` - Branch may already be configured
- ❌ `git remote add origin` - Remote may already exist (check first with `git remote -v`)
- ❌ `git config user.name/email` - User configuration is personal
- ❌ Reconfiguration commands - Repository is already set up
**ALWAYS safe to execute:**
- ✅ `git status` - Check repository state
- ✅ `git add` - Stage changes
- ✅ `git commit` - Create commits (after quality checks)
- ✅ `git log` - View history
- ✅ `git diff` - View changes
- ✅ `git branch` - List branches
- ✅ `git tag` - Create tags (after quality checks)
**Execute with caution (check first):**
- ⚠️ `git push` - Follow push mode configuration
- ⚠️ `git pull` - May cause merge conflicts
- ⚠️ `git merge` - May cause conflicts
- ⚠️ `git rebase` - Can rewrite history
- ⚠️ `git reset --hard` - Destructive, only for rollback
- ⚠️ `git push --force` - NEVER on main/master
### Repository Detection
**AI Assistant MUST check:**
```bash
# Before ANY Git operation:
# 1. Does .git exist?
if [ -d .git ]; then
echo "✅ Git repository exists"
# 2. Check current state
git status
# 3. Check branch
BRANCH=$(git branch --show-current)
echo "On branch: $BRANCH"
# 4. Check remote
REMOTE=$(git remote -v)
if [ -z "$REMOTE" ]; then
echo "⚠️ No remote configured"
else
echo "Remote: $REMOTE"
fi
# 5. Proceed with normal Git operations
else
echo "⚠️ No Git repository found"
echo "Ask user if they want to initialize Git"
fi
```
## Daily Development Workflow
### 1. Before Making Changes
**CRITICAL**: Always check current state:
```bash
# Check current branch and status
git status
# Ensure you're on the correct branch
git branch
# Pull latest changes if working with team (use --ff-only for safety)
git pull --ff-only origin main
```
**Git Safety**: Use `--ff-only` to prevent unexpected merge commits and maintain linear history.
### 2. Making Changes
**CRITICAL**: Commit after every important implementation:
```bash
# After implementing a feature/fix:
# 1. Run ALL quality checks FIRST
npm run lint # or equivalent for your language
npm run type-check # TypeScript/typed languages
npm test # ALL tests must pass
npm run build # Ensure build succeeds
# 2. If ALL checks pass, stage changes
git add .
# 3. Commit with conventional commit message
git commit -m "feat: Add user authentication
- Implement login/logout functionality
- Add JWT token management
- Include comprehensive tests (95%+ coverage)
- Update documentation"
# Alternative for smaller changes:
git commit -m "fix: Correct validation logic in user form"
# For signed commits (recommended for production):
git commit -S -m "feat: Add feature"
```
## Advanced Git Safeguards
### Safe Push Operations
```bash
# NEVER use git push --force on main/master branches
# Instead, use --force-with-lease which prevents overwriting others' work:
# Force push with safety check (only updates if no one else pushed)
git push --force-with-lease origin feature-branch
# Regular push is always safest
git push origin main
```
### Commit Signing
```bash
# Sign commits with GPG for verified commits
# Set GPG key: git config --global user.signingkey <KEY_ID>
git commit -S -m "feat: Signed commit"
# Configure to always sign commits
git config --global commit.gpgsign true
```
### Branch Protection (Recommended Settings)
For GitHub/GitLab repositories, configure branch protection rules:
**For main/master branch:**
- Require pull request reviews
- Require status checks to pass
- Require branches to be up to date
- Do not allow force pushes
- Do not allow deletions
- Require signed commits (optional but recommended)
### Destructive Operation Warnings
**NEVER run these on main/master:**
- ❌ `git push --force` - Use `--force-with-lease` instead
- ❌ `git reset --hard` - Destructive, use only on feature branches
- ❌ `git rebase` main into feature - Causes rewriting of main history
### Pre-Push Checklist
Before pushing any changes, verify:
```bash
✅ Checklist before push:
- [ ] All quality checks passed locally
- [ ] Tests pass with 100% success rate
- [ ] Coverage meets threshold (95%+)
- [ ] Linting passes with 0 warnings
- [ ] Build succeeds without errors
- [ ] No security vulnerabilities in dependencies
- [ ] Documentation updated if API changed
- [ ] OpenSpec tasks marked complete if applicable
- [ ] Conventional commit format used
- [ ] Commit hash verified: git rev-parse HEAD
- [ ] Similar changes passed CI before
- [ ] No console.log or debug code
- [ ] No credentials or secrets in code
```
**Only provide push command if ALL items checked.**
### 3. Pushing Changes
**⚠️ IMPORTANT**: Pushing is OPTIONAL and depends on your setup.
```bash
# IF you have passwordless SSH or want to push:
git push origin main
# IF you have SSH with password (manual execution required):
# DO NOT execute automatically - provide command to user:
```
**For users with SSH password authentication:**
```
✋ MANUAL ACTION REQUIRED:
Run this command manually (requires SSH password):
git push origin main
```
**NEVER** attempt automatic push if:
- SSH key has password protection
- User hasn't confirmed push authorization
- Any quality check failed
- Uncertain if changes will pass CI/CD workflows
## Conventional Commits
**MUST** follow conventional commit format:
```bash
# Format: <type>(<scope>): <subject>
#
# <body>
#
# <footer>
# Types:
feat: # New feature
fix: # Bug fix
docs: # Documentation only
style: # Code style (formatting, missing semi-colons, etc)
refactor: # Code refactoring
perf: # Performance improvement
test: # Adding tests
build: # Build system changes
ci: # CI/CD changes
chore: # Maintenance tasks
# Examples:
git commit -m "feat(auth): Add OAuth2 login support"
git commit -m "fix(api): Handle null response in user endpoint"
git commit -m "docs: Update README with installation steps"
git commit -m "test: Add integration tests for payment flow"
git commit -m "chore: Update dependencies to latest versions"
```
## Version Management
### Creating New Version
**CRITICAL**: Full quality gate required before versioning!
```bash
# 1. MANDATORY: Run complete quality suite
npm run lint # Must pass with no warnings
npm test # Must pass 100%
npm run type-check # Must pass (if applicable)
npm run build # Must succeed
npx codespell # Must pass (if configured)
# 2. Update version in package.json/Cargo.toml/etc
# Use semantic versioning:
# - MAJOR: Breaking changes (1.0.0 -> 2.0.0)
# - MINOR: New features, backwards compatible (1.0.0 -> 1.1.0)
# - PATCH: Bug fixes (1.0.0 -> 1.0.1)
# 3. Update CHANGELOG.md
# Document all changes in this version:
## [1.2.0] - 2024-01-15
### Added
- New feature X
- New feature Y
### Fixed
- Bug in component Z
### Changed
- Refactored module A
# 4. Commit version changes
git add .
git commit -m "chore: Release version 1.2.0
- Updated version to 1.2.0
- Updated CHANGELOG.md with release notes"
# 5. Create annotated tag
git tag -a v1.2.0 -m "Release version 1.2.0
Major changes:
- Feature X
- Feature Y
- Bug fix Z
All tests passing ✅
Coverage: 95%+ ✅
Linting: Clean ✅
Build: Success ✅"
# 6. OPTIONAL: Push tag (manual if SSH password)
# Only if you're CERTAIN it will pass CI/CD workflows!
```
**For users requiring manual push:**
```
✋ MANUAL ACTIONS REQUIRED:
1. Verify all quality checks passed locally
2. Push commits:
git push origin main
3. Push tag:
git push origin v1.2.0
Note: Tag push will trigger CI/CD workflows and may create GitHub release.
Only push if you're confident all checks will pass.
```
## Quality Gate Enforcement
**CRITICAL**: Pre-commit checks MUST match GitHub Actions workflow commands to prevent CI/CD failures.
### Language-Specific Pre-Commit Commands
**The commands you run locally MUST be identical to those in your GitHub Actions workflows.**
#### TypeScript/JavaScript Projects
```bash
# These commands MUST match .github/workflows/*.yml
# 1. Type check (matches workflow)
npm run type-check # Must match workflow exactly
# 2. Lint (matches workflow)
npm run lint # Must match workflow exactly
# 3. Format check (matches workflow)
npx prettier --check 'src/**/*.ts' 'tests/**/*.ts' # Must match workflow
# 4. Tests (matches workflow)
npm test # Must match workflow exactly
# 5. Build (matches workflow)
npm run build # Must match workflow exactly
# If ANY fails: ❌ DO NOT COMMIT - Fix first!
```
#### Rust Projects
```bash
# These commands MUST match .github/workflows/*.yml
# 1. Format check (matches workflow)
cargo fmt --all -- --check
# 2. Clippy (matches workflow)
cargo clippy --all-targets --all-features -- -D warnings
# 3. Tests (matches workflow)
cargo test --all-features
# 4. Build (matches workflow)
cargo build --release
# If ANY fails: ❌ DO NOT COMMIT - Fix first!
```
#### Python Projects
```bash
# These commands MUST match .github/workflows/*.yml
# 1. Format check (matches workflow)
black --check .
# 2. Lint (matches workflow)
ruff check .
# 3. Type check (matches workflow)
mypy .
# 4. Tests (matches workflow)
pytest
# If ANY fails: ❌ DO NOT COMMIT - Fix first!
```
### Before ANY Commit
**MANDATORY CHECKS**:
```bash
# Checklist - ALL must pass:
☐ Code formatted
☐ Linter passes (no warnings)
☐ Type check passes
☐ ALL tests pass (100%)
☐ Coverage meets threshold (95%+)
☐ Build succeeds
☐ No console errors/warnings
# Run quality check script:
npm run quality-check # or equivalent
# If ANY check fails:
# ❌ DO NOT COMMIT
# ❌ FIX THE ISSUES FIRST
```
### Before Tag Creation
**MANDATORY CHECKS** (even stricter):
```bash
# Extended checklist - ALL must pass:
☐ All pre-commit checks passed
☐ Codespell passes (no typos)
☐ Security audit clean
☐ Dependencies up to date
☐ Documentation updated
☐ CHANGELOG.md updated
☐ Version bumped correctly
☐ All workflows would pass
# Run comprehensive check:
npm run lint
npm test
npm run type-check
npm run build
npx codespell
npm audit
# Only create tag if everything is green!
```
## Error Recovery & Rollback
### When Implementation Is Failing
If the AI is making repeated mistakes and user is frustrated:
```bash
# 1. Identify last stable commit
git log --oneline -10
# 2. Create backup branch of current work
git branch backup-failed-attempt
# 3. Hard reset to last stable version
git reset --hard <last-stable-commit-hash>
# 4. Verify stability
npm test
npm run build
# 5. Reimplement from scratch using DIFFERENT approach
# ⚠️ DO NOT repeat the same techniques that failed before
# ⚠️ Review AGENTS.md for alternative patterns
# ⚠️ Consider different architecture/design
# 6. After successful reimplementation
git branch -D backup-failed-attempt # Delete backup if no longer needed
```
### Undo Last Commit (Not Pushed)
```bash
# Keep changes, undo commit
git reset --soft HEAD~1
# Discard changes completely
git reset --hard HEAD~1
```
### Revert Pushed Commit
```bash
# Create revert commit
git revert <commit-hash>
# Then push (manual if SSH password)
```
## Branch Strategy
### Feature Branches
```bash
# Create feature branch
git checkout -b feature/user-authentication
# Work on feature...
# Commit regularly with quality checks
# When feature complete and tested:
git checkout main
git merge feature/user-authentication
# Delete feature branch
git branch -d feature/user-authentication
```
### Hotfix Workflow
```bash
# Critical bug in production
git checkout -b hotfix/critical-security-fix
# Fix the bug
# MUST include tests
# MUST pass all quality checks
git commit -m "fix: Critical security vulnerability in auth
- Patch authentication bypass
- Add regression tests
- Update security documentation"
# Merge to main
git checkout main
git merge hotfix/critical-security-fix
# Tag immediately if production fix
git tag -a v1.2.1 -m "Hotfix: Security patch"
# Manual push if required
```
## CRITICAL RESTRICTIONS - HUMAN AUTHORIZATION REQUIRED
**⚠️ IMPERATIVE RULES - THESE ARE NON-NEGOTIABLE ⚠️**
### Destructive Git Operations
**ABSOLUTELY FORBIDDEN without explicit human authorization:**
```
❌ NEVER execute: git checkout
✋ ALWAYS ask user: "Do you want to checkout [branch/commit]? [Y/n]"
✅ Only execute after explicit user confirmation
❌ NEVER execute: git reset
✋ ALWAYS ask user: "Do you want to reset to [commit]? This may lose changes. [Y/n]"
✅ Only execute after explicit user confirmation
⚠️ Explain consequences before executing
```
**Rationale**: These commands can cause data loss. Human oversight is mandatory.
### Merge Conflict Resolution
**When merge conflicts occur:**
```
❌ NEVER attempt to resolve conflicts by editing files automatically
❌ NEVER commit merged files without human review
✅ ALWAYS stop and request human assistance
✅ ALWAYS provide conflict locations and context
✅ ALWAYS wait for human to resolve manually
Message to user:
"⚠️ Merge conflict detected in the following files:
- [list of conflicted files]
Please resolve these conflicts manually. I cannot auto-resolve merge conflicts.
To resolve:
1. Open the conflicted files
2. Look for conflict markers (<<<<<<<, =======, >>>>>>>)
3. Choose the correct version or merge manually
4. Remove conflict markers
5. Run: git add <resolved-files>
6. Run: git commit
Let me know when you're done, and I can help with the next steps."
```
**Rationale**: Merge conflicts require human judgment about which code to keep.
### Commit Frequency Management
**⚠️ IMPORTANT: Reduce excessive commits**
```
❌ DO NOT commit after every small change
❌ DO NOT create multiple commits for the same logical feature
✅ COMMIT only when:
- A complete feature is implemented and tested
- A significant bug fix is completed
- A major refactoring is done
- Before creating a version tag
- User explicitly requests a commit
✅ GROUP related changes into meaningful commits
✅ USE conventional commit messages that describe the full scope
Example of GOOD commit frequency:
- Implement entire authentication system → 1 commit
- Add login, logout, and session management → 1 commit
- Complete feature with tests and docs → 1 commit
Example of BAD commit frequency (AVOID):
- Add login function → commit
- Add logout function → commit
- Add session check → commit
- Fix typo → commit
- Update comment → commit
```
**Rationale**: Too many commits pollute git history and make it harder to track meaningful changes.
### Feature Branch Strategy
**BEFORE starting ANY new task or feature:**
```
✋ ALWAYS ask user FIRST:
"Should I create a separate branch for this feature/task? [Y/n]
Options:
1. Create feature branch: git checkout -b feature/[name]
2. Work directly on current branch
3. Create hotfix branch: git checkout -b hotfix/[name]
What would you prefer?"
✅ Wait for user decision
✅ Respect user's branching strategy
❌ NEVER assume to work on main without asking
❌ NEVER create branches without permission
If user says YES to branch:
→ Create branch with descriptive name
→ Work on that branch
→ Ask before merging back to main
If user says NO to branch:
→ Proceed on current branch
→ Be extra careful with commits
```
**Rationale**: Branching strategy varies by team and project. Always confirm with the human first.
## Critical AI Assistant Rules
### Repository Initialization
**BEFORE any `git init` or setup commands:**
```
1. Check for .git directory existence
2. If .git exists:
- ❌ STOP - Repository already configured
- ❌ DO NOT run git init
- ❌ DO NOT run git config
- ❌ DO NOT run git branch -M
- ❌ DO NOT reconfigure anything
- ✅ Use existing repository as-is
3. If .git does NOT exist:
- ✅ Ask user if they want Git initialization
- ✅ Run initialization sequence if approved
```
### Push Command Behavior
**Based on configured push mode:**
```
Manual Mode (DEFAULT):
❌ NEVER execute: git push
✅ ALWAYS provide: "Run manually: git push origin main"
Prompt Mode:
⚠️ ALWAYS ask first: "Ready to push. Proceed? [Y/n]"
✅ Execute only if user confirms
Auto Mode:
⚠️ Check quality first
⚠️ Only if 100% confident
✅ Execute if all checks passed
```
### Quality Gate Enforcement
**MANDATORY checks before commit:**
```bash
# Run in this exact order:
1. npm run lint # or language equivalent
2. npm run type-check # if applicable
3. npm test # ALL tests must pass
4. npm run build # must succeed
# If ANY fails:
❌ STOP - DO NOT commit
❌ Fix issues first
❌ Re-run all checks
# If ALL pass:
✅ Safe to commit
✅ Proceed with git add and commit
```
**MANDATORY checks before tag:**
```bash
# Extended checks for version tags:
1. All commit checks above +
2. npx codespell # no typos
3. npm audit # no vulnerabilities
4. CHANGELOG.md updated
5. Version bumped correctly
6. Documentation current
# If ANY fails:
❌ STOP - DO NOT create tag
❌ Fix issues
❌ Re-verify everything
# Only create tag if 100% green!
```
## Best Practices
### DO's ✅
- **ALWAYS** check if .git exists before init commands
- **ALWAYS** run tests before commit
- **ALWAYS** use conventional commit messages
- **ALWAYS** update CHANGELOG for versions
- **ALWAYS** ask before executing `git checkout`
- **ALWAYS** ask before executing `git reset`
- **ALWAYS** ask user if a feature branch should be created before starting tasks
- **ALWAYS** request human assistance when merge conflicts occur
- **COMMIT** only when complete features/fixes are done (not for every small change)
- **TAG** releases with semantic versions
- **VERIFY** quality gates before tagging
- **DOCUMENT** breaking changes clearly
- **REVERT** when implementation is failing repeatedly
- **ASK** user before automatic push
- **PROVIDE** manual commands for SSH password users
- **CHECK** repository state before operations
- **RESPECT** existing Git configuration
- **GROUP** related changes into meaningful commits
### DON'Ts ❌
- **NEVER** run `git init` if .git exists
- **NEVER** run `git config` (user-specific)
- **NEVER** run `git checkout` without explicit user authorization
- **NEVER** run `git reset` without explicit user authorization
- **NEVER** auto-resolve merge conflicts by editing files
- **NEVER** commit merged files without human review
- **NEVER** create excessive commits for small changes
- **NEVER** assume branching strategy - always ask user first
- **NEVER** reconfigure existing repository
- **NEVER** commit without passing tests
- **NEVER** commit with linting errors
- **NEVER** commit with build failures
- **NEVER** create tag without quality checks
- **NEVER** push automatically with SSH password
- **NEVER** push if uncertain about CI/CD success
- **NEVER** commit console.log/debug code
- **NEVER** commit credentials or secrets
- **NEVER** force push to main/master
- **NEVER** rewrite published history
- **NEVER** skip hooks (--no-verify)
- **NEVER** assume repository configuration
## SSH Configuration
### For Users with SSH Password
If your SSH key has password protection:
**Configuration in AGENTS.md or project settings:**
```yaml
git_workflow:
auto_push: false
push_mode: "manual"
reason: "SSH key has password protection"
```
**AI Assistant Behavior:**
- ✅ Provide push commands in chat
- ✅ Wait for user manual execution
- ❌ Never attempt automatic push
- ❌ Never execute git push commands
### For Users with Passwordless SSH
```yaml
git_workflow:
auto_push: true # or prompt each time
push_mode: "auto"
```
## Git Hooks
### Pre-commit Hook
Create `.git/hooks/pre-commit`:
```bash
#!/bin/sh
echo "Running pre-commit checks..."
# Run linter
npm run lint
if [ $? -ne 0 ]; then
echo "❌ Linting failed. Commit aborted."
exit 1
fi
# Run tests
npm test
if [ $? -ne 0 ]; then
echo "❌ Tests failed. Commit aborted."
exit 1
fi
# Run type check (if applicable)
if command -v tsc &> /dev/null; then
npm run type-check
if [ $? -ne 0 ]; then
echo "❌ Type check failed. Commit aborted."
exit 1
fi
fi
echo "✅ All pre-commit checks passed!"
exit 0
```
### Pre-push Hook
Create `.git/hooks/pre-push`:
```bash
#!/bin/sh
echo "Running pre-push checks..."
# Run full test suite
npm test
if [ $? -ne 0 ]; then
echo "❌ Tests failed. Push aborted."
exit 1
fi
# Run build
npm run build
if [ $? -ne 0 ]; then
echo "❌ Build failed. Push aborted."
exit 1
fi
echo "✅ All pre-push checks passed!"
exit 0
```
Make hooks executable:
```bash
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push
```
## CI/CD Integration
### Before Providing Push Commands
**CRITICAL**: Only suggest push if confident about CI/CD success:
```
✅ Provide push command if:
- All local tests passed
- All linting passed
- Build succeeded
- Coverage meets threshold
- No warnings or errors
- Code follows AGENTS.md standards
- Similar changes passed CI/CD before
❌ DO NOT provide push command if:
- ANY quality check failed
- Uncertain about CI/CD requirements
- Making experimental changes
- First time working with this codebase
- User seems uncertain
Instead say:
"I recommend running the full CI/CD pipeline locally first to ensure
the changes will pass. Once confirmed, you can push manually."
```
## GitHub MCP Server Integration
**If GitHub MCP Server is available**, use it for automated workflow monitoring.
### Workflow Validation After Push
```
After every git push (manual or auto):
1. Wait 5-10 seconds for workflows to trigger
2. Check workflow status via GitHub MCP:
- List workflow runs for latest commit
- Check status of each workflow
3. If workflows are RUNNING:
⏳ Report: "CI/CD workflows in progress..."
✅ Continue with other tasks
✅ Check again in next user interaction
4. If workflows COMPLETED:
- All passed: ✅ Report success
- Some failed: ❌ Fetch errors and fix
5. If workflows FAILED:
a. Fetch complete error logs via GitHub MCP
b. Display errors to user
c. Analyze against AGENTS.md standards
d. Propose specific fixes
e. Implement fixes
f. Run local quality checks
g. Commit fixes
h. Provide push command for retry
```
### Next Interaction Check
```
On every user message after a push:
if (github_mcp_available && last_push_timestamp) {
// Check workflow status
const status = await checkWorkflows();
if (status.running) {
console.log('⏳ CI/CD still running, will check later');
} else if (status.failed) {
console.log('❌ CI/CD failures detected!');
await analyzeAndFixErrors(status.errors);
} else {
console.log('✅ All CI/CD workflows passed!');
}
}
```
### Error Analysis Flow
```
When workflow fails:
1. Fetch error via GitHub MCP:
- Workflow name
- Job name
- Failed step
- Error output
- Full logs
2. Categorize error:
- Test failure → Fix test or implementation
- Lint error → Format/fix code style
- Build error → Fix compilation issues
- Type error → Fix type definitions
- Coverage error → Add more tests
3. Fix following AGENTS.md:
- Apply correct pattern from AGENTS.md
- Add tests if needed
- Verify locally before committing
4. Commit fix:
git commit -m "fix: Resolve CI/CD failure - [specific issue]"
5. Provide push command:
"Ready to retry. Run: git push origin main"
6. After next push:
- Monitor again
- Verify fix worked
```
### CI/CD Confidence Check
**Before suggesting push:**
```
Assess confidence in CI/CD success:
HIGH confidence (safe to push):
✅ All local checks passed
✅ Similar changes passed CI before
✅ No experimental changes
✅ Follows AGENTS.md exactly
✅ Comprehensive tests
✅ No unusual patterns
MEDIUM confidence (verify first):
⚠️ First time with this pattern
⚠️ Modified build configuration
⚠️ Changed dependencies
⚠️ Cross-platform concerns
→ Suggest: "Let's verify locally first"
LOW confidence (don't push yet):
❌ Experimental implementation
❌ Skipped some tests
❌ Uncertain about compatibility
❌ Modified CI/CD files
→ Say: "Let's run additional checks first"
```
## Troubleshooting
### Merge Conflicts
```bash
# View conflicts
git status
# Edit conflicted files (marked with <<<<<<<, =======, >>>>>>>)
# After resolving:
git add <resolved-files>
git commit -m "fix: Resolve merge conflicts"
```
### Accidental Commit
```bash
# Undo last commit, keep changes
git reset --soft HEAD~1
# Make corrections
# Re-commit properly
```
### Lost Commits
```bash
# View all actions
git reflog
# Recover lost commit
git checkout <commit-hash>
git checkout -b recovery-branch
```