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:

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

# 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:

# 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

# 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:

⚠️ CRITICAL: All commit messages MUST be in English

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

Language Requirement: Commit messages must be written in English. Never use Portuguese, Spanish, or any other language.

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:

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.