feat(foundation): create directory structure and standards library
- Create root-level directories: agents/, commands/, standards/, templates/ - Port 5 core standards from global Claude standards - Adapt standards for claude-skills context (cs-* prefix, Python tools, skills) - Create sprint planning documents (context.md, plan.md) - All directories tracked with .gitkeep files Standards created: - communication-standards.md (absolute honesty, zero fluff, pragmatic focus) - quality-standards.md (Python tool quality, agent workflows, testing) - git-workflow-standards.md (conventional commits, semantic versioning) - documentation-standards.md (Markdown standards, living docs, templates) - security-standards.md (secret detection, dependency security, input validation) Sprint plan ready for Days 1-6 implementation. Phase: 1 (Foundation) Issues: #8, #9
This commit is contained in:
Reza Rezvani
0
standards/git/.gitkeep
Normal file
0
standards/git/.gitkeep
Normal file
439
standards/git/git-workflow-standards.md
Normal file
439
standards/git/git-workflow-standards.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# Git Workflow Standards
|
||||
|
||||
## Core Principles
|
||||
|
||||
### **1. Conventional Commits**
|
||||
- All commits follow conventional commits specification
|
||||
- Enable automated changelog generation
|
||||
- Clear categorization of all changes
|
||||
- Explicit marking of breaking changes
|
||||
|
||||
### **2. Semantic Versioning**
|
||||
- Automated versioning based on commit types
|
||||
- MAJOR version: BREAKING CHANGE
|
||||
- MINOR version: feat type commits
|
||||
- PATCH version: fix type commits
|
||||
|
||||
### **3. Branch Protection**
|
||||
- Main branch requires review
|
||||
- All quality gates must pass
|
||||
- No force pushes to main
|
||||
- Signed commits recommended
|
||||
|
||||
## Conventional Commits Specification
|
||||
|
||||
### **Commit Message Structure**
|
||||
|
||||
```
|
||||
<type>[optional scope]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
### **Standard Types**
|
||||
|
||||
```yaml
|
||||
feat: # New features (agents, skills, tools)
|
||||
fix: # Bug fixes
|
||||
docs: # Documentation only changes
|
||||
style: # Formatting changes (no functional impact)
|
||||
refactor: # Code restructuring without feature changes
|
||||
perf: # Performance improvements
|
||||
test: # Adding or correcting tests
|
||||
chore: # Maintenance tasks (dependencies, build)
|
||||
ci: # CI/CD configuration changes
|
||||
```
|
||||
|
||||
### **Examples**
|
||||
|
||||
```bash
|
||||
# New agent implementation
|
||||
feat(agents): implement cs-content-creator agent
|
||||
|
||||
# Bug fix in Python tool
|
||||
fix(seo-optimizer): correct keyword density calculation
|
||||
|
||||
# Documentation update
|
||||
docs(README): add agent catalog section
|
||||
|
||||
# Breaking change
|
||||
feat(agents)!: replace agent template structure
|
||||
|
||||
BREAKING CHANGE: agent frontmatter now requires 'tools' field
|
||||
```
|
||||
|
||||
### **Scopes for Claude Skills**
|
||||
|
||||
```yaml
|
||||
Common Scopes:
|
||||
agents: # Agent implementation
|
||||
skills: # Skill packages
|
||||
standards: # Standards library
|
||||
templates: # Templates
|
||||
docs: # Documentation
|
||||
foundation: # Core infrastructure
|
||||
marketing: # Marketing domain
|
||||
c-level: # C-level domain
|
||||
product: # Product domain
|
||||
engineering: # Engineering domain
|
||||
ra-qm: # RA/QM domain
|
||||
```
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
### **Branch Naming Conventions**
|
||||
|
||||
```yaml
|
||||
# Feature branches (agent/skill development)
|
||||
feature/agents-{name}: # New agent implementation
|
||||
feature/skills-{name}: # New skill package
|
||||
feature/{domain}-{component}: # Domain-specific features
|
||||
|
||||
# Documentation branches
|
||||
docs/{component}: # Documentation updates
|
||||
docs/standards-{name}: # Standards library updates
|
||||
|
||||
# Bug fixes
|
||||
fix/{issue-number}-{description}: # Bug fixes
|
||||
|
||||
# Hotfixes (critical production issues)
|
||||
hotfix/{issue}-{description}: # Emergency fixes
|
||||
|
||||
# Test branches
|
||||
test/{feature}: # Testing and validation
|
||||
```
|
||||
|
||||
### **Examples**
|
||||
|
||||
```bash
|
||||
# Create feature branch for new agent
|
||||
git checkout -b feature/agents-ceo-advisor
|
||||
|
||||
# Create documentation branch
|
||||
git checkout -b docs/installation-guide
|
||||
|
||||
# Create fix branch
|
||||
git checkout -b fix/23-broken-relative-paths
|
||||
|
||||
# Create test branch
|
||||
git checkout -b test/agent-path-resolution
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### **1. Development Workflow**
|
||||
|
||||
```bash
|
||||
# Start new feature
|
||||
git checkout -b feature/agents-product-manager
|
||||
|
||||
# Make changes
|
||||
# ... edit files ...
|
||||
|
||||
# Stage changes
|
||||
git add agents/product/cs-product-manager.md
|
||||
|
||||
# Commit with conventional message
|
||||
git commit -m "feat(agents): implement cs-product-manager agent
|
||||
|
||||
- Add YAML frontmatter
|
||||
- Document RICE prioritization workflow
|
||||
- Add interview analysis integration
|
||||
- Test relative path resolution
|
||||
|
||||
Phase: 2.3
|
||||
Issue: #13"
|
||||
|
||||
# Push to remote
|
||||
git push origin feature/agents-product-manager
|
||||
```
|
||||
|
||||
### **2. Pull Request Workflow**
|
||||
|
||||
```bash
|
||||
# Create PR using gh CLI
|
||||
gh pr create \
|
||||
--base main \
|
||||
--head feature/agents-product-manager \
|
||||
--title "feat(agents): implement cs-product-manager agent" \
|
||||
--body "Closes #13
|
||||
|
||||
## Summary
|
||||
Implements product management agent with RICE prioritization and interview analysis.
|
||||
|
||||
## Testing
|
||||
- [x] Relative paths resolve correctly
|
||||
- [x] Python tools execute successfully
|
||||
- [x] Workflows documented
|
||||
- [x] Quality gates pass"
|
||||
```
|
||||
|
||||
### **3. Review & Merge**
|
||||
|
||||
```bash
|
||||
# After review approval
|
||||
gh pr merge feature/agents-product-manager \
|
||||
--squash \
|
||||
--delete-branch
|
||||
```
|
||||
|
||||
### **4. Release Workflow**
|
||||
|
||||
```bash
|
||||
# Create release with semantic versioning
|
||||
git tag v1.0.0-agents
|
||||
git push origin v1.0.0-agents
|
||||
|
||||
# GitHub Actions automatically creates release with changelog
|
||||
```
|
||||
|
||||
## Commit Message Templates
|
||||
|
||||
### **For Agent Implementation**
|
||||
|
||||
```
|
||||
feat(agents): implement cs-{agent-name}
|
||||
|
||||
- Add YAML frontmatter with required fields
|
||||
- Document {number} workflows
|
||||
- Add integration examples
|
||||
- Test Python tool execution
|
||||
- Verify relative path resolution
|
||||
|
||||
Phase: {phase-number}
|
||||
Issue: #{issue-number}
|
||||
```
|
||||
|
||||
### **For Skill Development**
|
||||
|
||||
```
|
||||
feat(skills): add {skill-name} to {domain} domain
|
||||
|
||||
- Create skill directory structure
|
||||
- Implement {number} Python automation tools
|
||||
- Add knowledge base references
|
||||
- Create user templates
|
||||
|
||||
Domain: {domain}
|
||||
Issue: #{issue-number}
|
||||
```
|
||||
|
||||
### **For Standards Updates**
|
||||
|
||||
```
|
||||
docs(standards): update {standard-name} for {context}
|
||||
|
||||
- Adapt for claude-skills context
|
||||
- Remove factory-specific references
|
||||
- Add agent-specific guidelines
|
||||
- Update examples
|
||||
|
||||
Issue: #{issue-number}
|
||||
```
|
||||
|
||||
### **For Bug Fixes**
|
||||
|
||||
```
|
||||
fix({scope}): resolve {issue-description}
|
||||
|
||||
Problem: {what was broken}
|
||||
Solution: {what was fixed}
|
||||
Impact: {who/what this affects}
|
||||
|
||||
Fixes #{issue-number}
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
|
||||
### **Pre-commit Hook**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
echo "Running pre-commit checks..."
|
||||
|
||||
# Check for secrets
|
||||
if git diff --cached | grep -iE '(api[_-]?key|secret|password|token).*=.*[^x{5}]'; then
|
||||
echo "❌ Potential secret detected in commit"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate Python syntax
|
||||
python -m compileall $(git diff --cached --name-only --diff-filter=ACM | grep '\.py$')
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Python syntax errors detected"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Pre-commit checks passed"
|
||||
```
|
||||
|
||||
### **Commit-msg Hook**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/commit-msg
|
||||
|
||||
# Validate conventional commit format
|
||||
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\([a-z-]+\))?(!)?:\ .{1,}'
|
||||
|
||||
if ! head -1 "$1" | grep -qE "$commit_regex"; then
|
||||
echo "❌ Commit message does not follow conventional commits format"
|
||||
echo "Format: <type>[(scope)]: <description>"
|
||||
echo "Example: feat(agents): implement cs-product-manager"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Commit message format valid"
|
||||
```
|
||||
|
||||
## Quality Gates Integration
|
||||
|
||||
### **Pre-push Validation**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-push
|
||||
|
||||
echo "Running pre-push validation..."
|
||||
|
||||
# Run quality checks
|
||||
/review
|
||||
|
||||
# Check for TODO comments in production code
|
||||
if git diff origin/main...HEAD | grep -i "TODO"; then
|
||||
echo "⚠️ TODO comments found - consider addressing before push"
|
||||
fi
|
||||
|
||||
echo "✅ Pre-push validation complete"
|
||||
```
|
||||
|
||||
## Branch Protection Rules
|
||||
|
||||
### **Main Branch Protection**
|
||||
|
||||
```yaml
|
||||
branch_protection:
|
||||
required_status_checks:
|
||||
strict: true
|
||||
contexts:
|
||||
- "ci-quality-gate"
|
||||
- "claude-review"
|
||||
|
||||
required_pull_request_reviews:
|
||||
required_approving_review_count: 1
|
||||
dismiss_stale_reviews: true
|
||||
require_code_owner_reviews: false
|
||||
|
||||
enforce_admins: true
|
||||
required_conversation_resolution: true
|
||||
allow_force_pushes: false
|
||||
allow_deletions: false
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### **Hotfix Process**
|
||||
|
||||
```bash
|
||||
# Create hotfix branch from main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b hotfix/critical-path-resolution
|
||||
|
||||
# Fix issue
|
||||
# ... make changes ...
|
||||
|
||||
# Commit with high priority
|
||||
git commit -m "fix(agents)!: resolve critical path resolution failure
|
||||
|
||||
BREAKING CHANGE: agent path resolution now requires absolute project root
|
||||
|
||||
Fixes #42
|
||||
Priority: P0"
|
||||
|
||||
# Create PR with hotfix label
|
||||
gh pr create --label "P0,hotfix" --base main
|
||||
|
||||
# After merge, tag immediately
|
||||
git tag v1.0.1-hotfix
|
||||
git push origin v1.0.1-hotfix
|
||||
```
|
||||
|
||||
### **Multi-Agent Coordination**
|
||||
|
||||
```bash
|
||||
# Coordinating changes across multiple agents
|
||||
git checkout -b feature/update-all-marketing-agents
|
||||
|
||||
# Update cs-content-creator
|
||||
git add agents/marketing/cs-content-creator.md
|
||||
git commit -m "feat(agents): enhance cs-content-creator workflows"
|
||||
|
||||
# Update cs-demand-gen-specialist
|
||||
git add agents/marketing/cs-demand-gen-specialist.md
|
||||
git commit -m "feat(agents): enhance cs-demand-gen-specialist workflows"
|
||||
|
||||
# Push coordinated changes
|
||||
git push origin feature/update-all-marketing-agents
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### **Do's**
|
||||
|
||||
- ✅ Use conventional commit format for all commits
|
||||
- ✅ Reference issue numbers in commit messages
|
||||
- ✅ Keep commits atomic (one logical change per commit)
|
||||
- ✅ Write clear, descriptive commit messages
|
||||
- ✅ Test changes before committing
|
||||
- ✅ Pull before pushing to avoid conflicts
|
||||
- ✅ Use feature branches for all changes
|
||||
- ✅ Delete branches after merging
|
||||
|
||||
### **Don'ts**
|
||||
|
||||
- ❌ Commit directly to main (use PRs)
|
||||
- ❌ Force push to shared branches
|
||||
- ❌ Commit secrets or credentials
|
||||
- ❌ Mix multiple unrelated changes in one commit
|
||||
- ❌ Use vague commit messages ("fix stuff", "updates")
|
||||
- ❌ Skip quality checks
|
||||
- ❌ Leave branches unmerged for extended periods
|
||||
|
||||
## Emergency Procedures
|
||||
|
||||
### **Rollback Commit**
|
||||
|
||||
```bash
|
||||
# Revert the last commit (creates new commit)
|
||||
git revert HEAD
|
||||
|
||||
# Revert specific commit
|
||||
git revert <commit-hash>
|
||||
|
||||
# Force rollback (use with caution!)
|
||||
git reset --hard HEAD~1
|
||||
git push origin main --force # Only if absolutely necessary!
|
||||
```
|
||||
|
||||
### **Fix Bad Commit Message**
|
||||
|
||||
```bash
|
||||
# Amend last commit message (before push)
|
||||
git commit --amend -m "feat(agents): corrected commit message"
|
||||
|
||||
# After push (creates new commit)
|
||||
git revert HEAD
|
||||
git commit -m "feat(agents): correct implementation with proper message"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Standard**: Conventional Commits v1.0.0
|
||||
**Versioning**: Semantic Versioning v2.0.0
|
||||
**Updated**: November 2025
|
||||
**Review**: Monthly git workflow assessment
|
||||
Reference in New Issue
Block a user