AIOX Git Workflow Guide

🌐 EN | PT | ES

Story: 2.2-git-workflow-implementation.yaml

Overview
Defense in Depth Architecture
Layer 1: Pre-commit Validation
Layer 2: Pre-push Validation
Layer 3: CI/CD Pipeline
Branch Protection
Daily Workflow
Troubleshooting
Performance Tips

Overview

Synkra AIOX implements a Defense in Depth validation strategy with three progressive layers that catch issues early and ensure code quality before merge.

Why Three Layers?

Fast feedback - Catch issues immediately during development
Local validation - No cloud dependency for basic checks
Authoritative validation - Final gate before merge
Story consistency - Ensure development aligns with stories

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                     Developer Workflow                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Pre-commit Hook (Local - <5s)                     │
│ ✓ ESLint (code quality)                                     │
│ ✓ TypeScript (type checking)                                │
│ ✓ Cache enabled                                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 2: Pre-push Hook (Local - <2s)                       │
│ ✓ Story checkbox validation                                 │
│ ✓ Status consistency                                         │
│ ✓ Required sections                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Layer 3: GitHub Actions CI (Cloud - 2-5min)                │
│ ✓ All lint/type checks                                      │
│ ✓ Full test suite                                           │
│ ✓ Code coverage (≥80%)                                      │
│ ✓ Story validation                                          │
│ ✓ Branch protection                                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                      ┌──────────────┐
                      │ Merge Ready  │
                      └──────────────┘

Defense in Depth Architecture

Layer 1: Pre-commit (Local - Fast)

Performance Target: <5 seconds Trigger: git commit Location: .husky/pre-commit

What it validates:

ESLint code quality
TypeScript type checking
Syntax errors
Import issues

How it works:

# Triggered automatically on commit
git add .
git commit -m "feat: add feature"

# Runs:
# 1. ESLint with caching (.eslintcache)
# 2. TypeScript incremental compilation (.tsbuildinfo)

Benefits:

⚡ Fast feedback (<5s)
💾 Cached for speed
🔒 Prevents broken code commits
🚫 No invalid syntax in history

Layer 2: Pre-push (Local - Story Validation)

Performance Target: <2 seconds Trigger: git push Location: .husky/pre-push

What it validates:

Story checkbox completion vs status
Required story sections present
Status consistency
Dev agent records

How it works:

# Triggered automatically on push
git push origin feature/my-feature

# Validates all story files in docs/stories/

Validation Rules:

Status Consistency:

# ❌ Invalid: completed but tasks incomplete
status: "completed"
tasks:
  - "[x] Task 1"
  - "[ ] Task 2"  # Error!

# ✅ Valid: all tasks completed
status: "completed"
tasks:
  - "[x] Task 1"
  - "[x] Task 2"

Required Sections:

id
title
description
acceptance_criteria
status

Status Flow:

ready → in progress → Ready for Review → completed

Layer 3: CI/CD (Cloud - Authoritative)

Performance: 2-5 minutes Trigger: Push to any branch, PR creation Platform: GitHub Actions Location: .github/workflows/ci.yml

Jobs:

ESLint (lint job)
- Runs on clean environment
- No cache dependency
TypeScript (typecheck job)
- Full type checking
- No incremental compilation
Tests (test job)
- Full test suite
- Coverage reporting
- 80% threshold enforced
Story Validation (story-validation job)
- All stories validated
- Status consistency checked
Validation Summary (validation-summary job)
- Aggregates all results
- Blocks merge if any fail

Performance Monitoring:

Optional performance job
Measures validation times
Informational only

Layer 1: Pre-commit Validation

Quick Reference

# Manual validation
npm run lint
npm run typecheck

# Auto-fix lint issues
npm run lint -- --fix

# Skip hook (NOT recommended)
git commit --no-verify

ESLint Configuration

File: .eslintrc.json

{
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "cache": true,
  "cacheLocation": ".eslintcache"
}

Key features:

TypeScript support
Caching enabled
Warns on console.log
Ignores unused vars with _ prefix

TypeScript Configuration

File: tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

Key features:

ES2022 target
Strict mode
Incremental compilation
CommonJS modules

Performance Optimization

Cache Files:

.eslintcache - ESLint results
.tsbuildinfo - TypeScript incremental data

First run: ~10-15s (no cache) Subsequent runs: <5s (cached)

Cache invalidation:

Configuration changes
Dependency updates
File deletions

Layer 2: Pre-push Validation

Quick Reference

# Manual validation
node .aiox-core/utils/aiox-validator.js pre-push
node .aiox-core/utils/aiox-validator.js stories

# Validate single story
node .aiox-core/utils/aiox-validator.js story docs/stories/1.1-story.yaml

# Skip hook (NOT recommended)
git push --no-verify

Story Validator

Location: .aiox-core/utils/aiox-validator.js

Features:

Colored terminal output
Progress indicators
Clear error messages
Warnings for potential issues

Example Output:

══════════════════════════════════════════════════════════
  Story Validation: 2.2-git-workflow-implementation.yaml
══════════════════════════════════════════════════════════

Story: 2.2 - Git Workflow with Multi-Layer Validation
Status: in progress

Progress: 12/15 tasks (80.0%)

✓ Story validation passed with warnings

Warning:
  • Consider updating status to 'Ready for Review'

Validation Rules

1. Checkbox Format

Supported formats:

[x] - Completed (lowercase)
[X] - Completed (uppercase)
[ ] - Incomplete

Not recognized:

[o], [*], [-] - Not counted as complete

2. Status Consistency

Status	Rule
`ready`	No tasks should be checked
`in progress`	Some tasks checked
`Ready for Review`	All tasks checked
`completed`	All tasks checked

3. Required Sections

All stories must have:

id: "X.X"
title: "Story Title"
description: "Story description"
status: "ready" | "in progress" | "Ready for Review" | "completed"
acceptance_criteria:
  - name: "Criterion"
    tasks:
      - "[ ] Task"

4. Dev Agent Record

Recommended but not required:

dev_agent_record:
  agent_model: 'claude-sonnet-4-5'
  implementation_date: '2025-01-23'

Warning if missing.

Error Messages

Missing Required Sections:

✗ Missing required sections: description, acceptance_criteria

Status Inconsistency:

✗ Story marked as completed but only 12/15 tasks are checked

Non-existent File:

✗ Story file not found: docs/stories/missing.yaml

Layer 3: CI/CD Pipeline

Workflow Structure

File: .github/workflows/ci.yml

Jobs:

lint - ESLint validation
typecheck - TypeScript checking
test - Jest tests with coverage
story-validation - Story consistency
validation-summary - Aggregate results
performance (optional) - Performance metrics

Job Details

ESLint Job

- name: Run ESLint
  run: npm run lint

Runs on Ubuntu latest
Timeout: 5 minutes
Uses npm cache
Fails on any lint error

TypeScript Job

- name: Run TypeScript type checking
  run: npm run typecheck

Runs on Ubuntu latest
Timeout: 5 minutes
Fails on type errors

Test Job

- name: Run tests with coverage
  run: npm run test:coverage

Runs on Ubuntu latest
Timeout: 10 minutes
Coverage uploaded to Codecov
Enforces 80% coverage threshold

Story Validation Job

- name: Validate story checkboxes
  run: node .aiox-core/utils/aiox-validator.js stories

Runs on Ubuntu latest
Timeout: 5 minutes
Validates all stories

Validation Summary Job

needs: [lint, typecheck, test, story-validation]
if: always()

Runs after all validations
Checks all job statuses
Fails if any validation failed
Provides summary

CI Triggers

Push Events:

master branch
develop branch
feature/** branches
bugfix/** branches

Pull Request Events:

Against master
Against develop

Viewing CI Results

# View PR checks
gh pr checks

# View workflow runs
gh run list

# View specific run
gh run view <run-id>

# Re-run failed jobs
gh run rerun <run-id>

Branch Protection

Setup

# Run setup script
node scripts/setup-branch-protection.js

# View current protection
node scripts/setup-branch-protection.js --status

Requirements

GitHub CLI (gh) installed
Authenticated with GitHub
Admin access to repository

Protection Rules

Master Branch Protection:

Required Status Checks:
- ESLint
- TypeScript Type Checking
- Jest Tests
- Story Checkbox Validation
Pull Request Reviews:
- 1 approval required
- Dismiss stale reviews on new commits
Additional Rules:
- Linear history enforced (rebase only)
- Force pushes blocked
- Branch deletion blocked
- Rules apply to administrators

Manual Configuration

Via GitHub CLI:

# Set required status checks
gh api repos/OWNER/REPO/branches/master/protection/required_status_checks \
  -X PUT \
  -f strict=true \
  -f contexts[]="ESLint" \
  -f contexts[]="TypeScript Type Checking"

# Require PR reviews
gh api repos/OWNER/REPO/branches/master/protection/required_pull_request_reviews \
  -X PUT \
  -f required_approving_review_count=1

# Block force pushes
gh api repos/OWNER/REPO/branches/master/protection/allow_force_pushes \
  -X DELETE

Daily Workflow

Starting a New Feature

# 1. Update master
git checkout master
git pull origin master

# 2. Create feature branch
git checkout -b feature/my-feature

# 3. Make changes
# ... edit files ...

# 4. Commit (triggers pre-commit)
git add .
git commit -m "feat: add my feature [Story X.X]"

# 5. Push (triggers pre-push)
git push origin feature/my-feature

# 6. Create PR
gh pr create --title "feat: Add my feature" --body "Description"

Updating a Story

# 1. Open story file
code docs/stories/X.X-story.yaml

# 2. Mark tasks complete
# Change: - "[ ] Task"
# To:     - "[x] Task"

# 3. Update status if needed
# Change: status: "in progress"
# To:     status: "Ready for Review"

# 4. Commit story updates
git add docs/stories/X.X-story.yaml
git commit -m "docs: update story X.X progress"

# 5. Push (validates story)
git push

Fixing Validation Failures

ESLint Errors:

# Auto-fix issues
npm run lint -- --fix

# Check remaining issues
npm run lint

# Commit fixes
git add .
git commit -m "style: fix lint issues"

TypeScript Errors:

# See all errors
npm run typecheck

# Fix errors in code
# ... edit files ...

# Verify fix
npm run typecheck

# Commit fixes
git add .
git commit -m "fix: resolve type errors"

Story Validation Errors:

# Check stories
node .aiox-core/utils/aiox-validator.js stories

# Fix story file
code docs/stories/X.X-story.yaml

# Verify fix
node .aiox-core/utils/aiox-validator.js story docs/stories/X.X-story.yaml

# Commit fix
git add docs/stories/
git commit -m "docs: fix story validation"

Test Failures:

# Run tests
npm test

# Run specific test
npm test -- path/to/test.js

# Fix failing tests
# ... edit test files ...

# Run with coverage
npm run test:coverage

# Commit fixes
git add .
git commit -m "test: fix failing tests"

Merging a Pull Request

# 1. Ensure CI passes
gh pr checks

# 2. Get approval
# (Wait for team member review)

# 3. Merge (squash)
gh pr merge --squash --delete-branch

# 4. Update local master
git checkout master
git pull origin master

Troubleshooting

Hook Not Running

Symptoms: Commit succeeds without validation

Solutions:

Check Husky installation:

npm run prepare

Verify hook files exist:

ls -la .husky/pre-commit
ls -la .husky/pre-push

Check file permissions (Unix):

chmod +x .husky/pre-commit
chmod +x .husky/pre-push

Slow Pre-commit Hook

Symptoms: Pre-commit takes >10 seconds

Solutions:

Clear caches:

rm .eslintcache .tsbuildinfo
git commit  # Rebuilds cache

Check file changes:

git status
# Commit fewer files at once

Update dependencies:

npm update

Story Validation Fails

Symptom: Pre-push fails with story errors

Common Issues:

Checkbox mismatch:

# Error: Completed status but incomplete tasks
status: 'completed'
tasks:
  - '[x] Task 1'
  - '[ ] Task 2' # ← Fix this


# Solution: Complete all tasks or change status

Missing sections:

# Error: Missing required sections
id: '1.1'
title: 'Story'
# Missing: description, acceptance_criteria, status

# Solution: Add missing sections

Invalid YAML:

# Error: Invalid YAML syntax
tasks:
  - "[ ] Task 1
  - "[ ] Task 2"  # ← Missing closing quote above

# Solution: Fix YAML syntax

CI Fails but Local Passes

Symptoms: CI fails but all local validations pass

Common Causes:

Cache differences:

# Clear local caches
rm -rf node_modules .eslintcache .tsbuildinfo coverage/
npm ci
npm test

Environment differences:

# Use same Node version as CI (18)
nvm use 18
npm test

Uncommitted files:

# Check for uncommitted changes
git status

# Stash if needed
git stash

Branch Protection Blocks Merge

Symptoms: Cannot merge PR even with approvals

Check:

Required checks pass:

gh pr checks
# All must show ✓

Required approvals:

gh pr view
# Check "Reviewers" section

Branch is up to date:

# Update branch
git checkout feature-branch
git rebase master
git push --force-with-lease

Performance Tips

Cache Management

Keep caches:

.eslintcache - ESLint results
.tsbuildinfo - TypeScript build info
coverage/ - Test coverage data

Commit to .gitignore:

.eslintcache
.tsbuildinfo
coverage/

Incremental Development

Best Practices:

Small commits:
- Fewer files = faster validation
- Easier to debug failures
Test during development:

# Run validation manually before commit
npm run lint
npm run typecheck
npm test

Fix issues immediately:
- Don't let issues accumulate
- Easier to fix in context

CI Optimization

Workflow optimizations:

Parallel jobs - All validations run in parallel
Job timeouts - Fail fast on hangs
Caching - npm dependencies cached
Conditional jobs - Performance job only on PRs

Story Validation Performance

Current Performance:

Single story: <100ms
All stories: <2s (typical)

Optimization tips:

Keep stories focused - One feature per story
Limit task count - Break large stories into smaller ones
Valid YAML - Parsing errors slow validation

Advanced Topics

Skipping Validations

When appropriate:

Emergency hotfixes
Documentation-only changes
CI configuration changes

How to skip:

# Skip pre-commit
git commit --no-verify

# Skip pre-push
git push --no-verify

# Skip CI (not recommended)
# Add [skip ci] to commit message
git commit -m "docs: update [skip ci]"

Warning: Only skip when absolutely necessary. Skipped validations won't catch issues.

Custom Validation

Add custom validators:

Create validator function:

// .aiox-core/utils/custom-validator.js
module.exports = async function validateCustom() {
  // Your validation logic
  return { success: true, errors: [] };
};

Add to hook:

# .husky/pre-commit
node .aiox-core/utils/aiox-validator.js pre-commit
node .aiox-core/utils/custom-validator.js

Add to CI:

# .github/workflows/ci.yml
- name: Custom validation
  run: node .aiox-core/utils/custom-validator.js

Monorepo Support

For monorepos:

Scope validations:

// Only validate changed packages
const changedFiles = execSync('git diff --name-only HEAD~1').toString();
const packages = getAffectedPackages(changedFiles);

Parallel package validation:

strategy:
  matrix:
    package: [package-a, package-b, package-c]

References

AIOX Validator: .aiox-core/utils/aiox-validator.js
CI Workflow: .github/workflows/ci.yml

Questions? Issues?

FilesExpand file tree

git-workflow-guide.md

Latest commit

History

git-workflow-guide.md

File metadata and controls

AIOX Git Workflow Guide

Table of Contents

Overview

Why Three Layers?

Architecture Diagram

Defense in Depth Architecture

Layer 1: Pre-commit (Local - Fast)

Layer 2: Pre-push (Local - Story Validation)

Layer 3: CI/CD (Cloud - Authoritative)

Layer 1: Pre-commit Validation

Quick Reference

ESLint Configuration

TypeScript Configuration

Performance Optimization

Layer 2: Pre-push Validation

Quick Reference

Story Validator

Validation Rules

1. Checkbox Format

2. Status Consistency

3. Required Sections

4. Dev Agent Record

Error Messages

Layer 3: CI/CD Pipeline

Workflow Structure

Job Details

ESLint Job

TypeScript Job

Test Job

Story Validation Job

Validation Summary Job

CI Triggers

Viewing CI Results

Branch Protection

Setup

Requirements

Protection Rules

Manual Configuration

Daily Workflow

Starting a New Feature

Updating a Story

Fixing Validation Failures

Merging a Pull Request

Troubleshooting

Hook Not Running

Slow Pre-commit Hook

Story Validation Fails

CI Fails but Local Passes

Branch Protection Blocks Merge

Performance Tips

Cache Management

Incremental Development

CI Optimization

Story Validation Performance

Advanced Topics

Skipping Validations

Custom Validation

Monorepo Support

References