Experiment orchestration framework with traffic allocation, statistical analysis, and early stopping detection. Use to test routing changes, model upgrades, and role assignments with Welch's t-test significance testing.

2026-06-253

metrics-etl

niallyoung/agentic-engineers

DEPRECATED — This skill is no longer maintained. Prometheus and Grafana infrastructure was never implemented. Use local JSON metrics analysis instead.

2026-06-253

agent-creator

niallyoung/agentic-engineers

Scaffolds new SPEC-compliant agentic-engineers agents with a single call. Generates SKILL.md frontmatter, test scaffolds (TDD RED-phase), __init__.py, scripts/ layout, and DELEGATE/HANDBACK protocol templates. Use when creating any new automation agent, task handler, or operational tool. Validates role, model, effort, naming, and dependency graphs (circular dep detection) before writing files. Supports dry-run mode for planning without side effects.

2026-06-213

codex-agent-cleanup

niallyoung/agentic-engineers

Routine maintenance for Codex sessions: monitor queue state, close completed sub-agents, resume or escalate active work, and keep agent capacity available.

2026-06-213

consistency-checker

niallyoung/agentic-engineers

Automated cross-validation of protocol queue integrity. Scans all DELEGATEs/HANDBACKs, validates schema compliance, detects cycles, checks rate limits, generates compliance report. Enables self-referential protocol improvements.

2026-06-213

cost-aggregation

niallyoung/agentic-engineers

Consolidates provider-specific AI costs into unified metrics across Anthropic, OpenAI, Google Gemini, GitHub Copilot, and Ollama. Enables apples-to-apples cost comparison and savings analysis.

2026-06-213

name	code-hygiene-git-workflow
description	Disciplined queue-to-branch-to-PR-to-merge workflow for code quality and CI stability
type	meta
role	team-discipline
category	workflow-standards
version	1
maturity	draft
effort_estimate	15-20h for full team adoption

CODE-HYGIENE-GIT-WORKFLOW

Metadata

name: code-hygiene-git-workflow
type: meta
role: team-discipline
category: workflow-standards
version: 1.0
maturity: draft
effort_estimate: 15-20h for full team adoption

Purpose

Establish disciplined queue→branch→PR→merge→rebase workflow to maximize code quality, minimize CI failures, and maintain polished production state. This skill defines standards for:

Queue management (TODO.md, incoming tasks, DELEGATE tracking)
Branch discipline (feature branches, atomic commits, clear naming)
Pre-commit/pre-push validation gates (catch obvious failures locally)
PR consolidation & review (grouped by feature area)
Merge discipline (watch CI, fix failures ASAP)
Post-merge rebase & verification (keep all branches up-to-date)

Core Principles

Local Validation First: All obvious failures caught locally BEFORE CI runs
- Linting (syntax, style, naming conventions)
- Basic tests (unit tests, type checking)
- Contract validation (function signatures, parameter types)
- No commits that break test suite locally
CI as Release Gate: CI pipeline validates release-readiness, not development correctness
- Runs full test suite in container environment (catches environment mismatches)
- Validates against real infrastructure constraints (permissions, symlinks, paths)
- Acts as final sanity check before merge
- Quick re-run to confirm stability

Queue→Branch→PR Flow:

TODO.md / incoming/
   ↓ (DELEGATE task created)
Feature branch created
   ↓ (code + tests + docs)
Atomic commits (one logical change per commit)
   ↓ (pass all pre-commit/pre-push checks)
Pre-push: Full test suite passes locally
   ↓ (push to origin)
PR created (grouped by feature area)
   ↓ (CI runs, user review)
Merge to main (watch for CI failures)
   ↓ (PRIORITY: investigate + fix any CI failures)
Post-merge: Rebase all active branches
   ↓ (Verify no new conflicts/breakage)
Return to Step 2 for next task

Atomic PRs: Each PR covers one logical feature/fix area
- Group related commits (e.g., all linting improvements, all test additions)
- Keep PRs focused and reviewable (< 500 LOC per PR is ideal)
- One PR per branch (avoid mixing unrelated work)
- Clear PR title/description linking to task IDs
Merge Discipline:
- Watch for CI failures immediately after merge
- Treat CI failures as PRIORITY (block new work until fixed)
- Watch CI to completion after every merge (see monitoring/cicd-watch.md — core behaviour); a merge is not done until main is green
- Root-cause analysis required (don't just re-run)
- Fix on a NEW branch + PR (the merged branch is gone; never push fixes directly to main — the PR-level Quality Gate must validate them)
- Repeat the watch/fix cycle until all workflows on main are green
Rebase Discipline:
- After successful merge, rebase all active feature branches
- Verify no new conflicts or breakage introduced
- Test locally after rebase (ensure merged code compatible with branch)
- Mark branches as "rebase-verified" before resuming work

Validation Gates

Pre-Commit (Auto-Run, Developer Workstation)

Catches issues before they're even committed:

checks:
  - name: syntax-validation
    tools: [python -m py_compile, shellcheck]
    description: "No syntax errors in Python/shell files"
    fail_fast: true
    
  - name: linting-basic
    tools: [black, pylint --disable=convention]
    description: "Code style and obvious bugs (not design/convention)"
    fail_fast: false
    categories: [pep8, naming, obvious-bugs]
    
  - name: type-checking
    tools: [mypy --strict]
    description: "Type annotations match function signatures"
    fail_fast: true
    
  - name: import-validation
    tools: [isort --check-only]
    description: "Imports properly sorted and organized"
    fail_fast: true
    
  - name: file-permissions
    tools: [custom: check_file_permissions.py]
    description: "No executable bits on .md, .yaml, .txt files"
    fail_fast: true
    
  - name: secrets-detection
    tools: [detect-secrets]
    description: "No API keys, passwords, tokens in committed code"
    fail_fast: true
    
  - name: contract-validation
    tools: [custom: validate_function_contracts.py]
    description: "Function signatures match decorator expectations"
    fail_fast: true

Implementation: .githooks/pre-commit (auto-installed by make setup)

Pre-Push (Auto-Run, Developer Workstation)

Catches failures before they reach origin:

checks:
  - name: unit-tests-pass
    command: "make test"
    description: "All unit tests pass locally (full suite, ~5min)"
    fail_fast: true
    
  - name: integration-tests-pass
    command: "make test-integration"
    description: "All integration tests pass locally (~3min)"
    fail_fast: true
    
  - name: spec-compliance
    command: "make validate-spec"
    description: "Code complies with SPEC.md requirements"
    fail_fast: true
    
  - name: env-simulation
    command: "docker run --rm -v $(pwd):/workspace -w /workspace python:3.11 make test"
    description: "Tests pass in container environment (simulates CI)"
    fail_fast: false
    optional: true
    note: "Optional on first push, mandatory on second attempt if CI later fails"

Implementation: .githooks/pre-push (auto-installed by make setup)

CI Pipeline (GitHub Actions)

Final gate before merge:

stages:
  - name: lint
    checks: [black --check, pylint, mypy]
    timeout: 5min
    
  - name: test
    checks: [make test, make test-integration]
    timeout: 10min
    matrix: [python-3.9, python-3.10, python-3.11]
    
  - name: container-validation
    checks: ["docker run ... make test"]
    timeout: 15min
    description: "Verify tests pass in clean container (CI environment)"
    
  - name: security-scan
    checks: [bandit, safety, secrets-detection]
    timeout: 5min
    
  - name: build-artifacts
    checks: ["make build", verify-artifact-integrity]
    timeout: 10min

Workflow Checklist

Starting a New Task (from TODO/queue)

Create feature branch: git checkout -b feature/TASK-ID-short-description
Update TODO.md: mark task as in_progress
Make changes, write tests, update docs
Commit atomically: git commit -m "TASK-ID: one logical change"
Pre-commit checks run automatically (fix any failures)

Before Pushing

Run make test locally (all tests pass)
Run make validate-spec (code complies with SPEC.md)
Review commits: git log origin/main..HEAD (each commit is one logical unit)
Update SPEC.md if behavior changed (required for all non-trivial changes)
Pre-push checks run automatically (fix any failures)

Creating PR

Title format: [AREA] TASK-ID: Brief description (e.g., [Security] TASK-CI-001: Fix path validation)
Link to task ID in PR description
Group related commits (same feature area)
Keep PR < 500 LOC if possible (break into multiple PRs if needed)
Add summary of changes, testing approach, and any breaking changes
Request review from appropriate role (Security Engineer, Senior Engineer, etc.)

After Merge (PRIORITY WORKFLOW)

CRITICAL: Watch for CI failures immediately after merge!

Monitor GitHub Actions CI run (don't close terminal/browser)
If CI passes: proceed to Post-Merge rebase (below)
If CI fails:
- Check logs immediately (don't let it sit)
- Root-cause analysis (not just re-run)
- Create fix commit to same branch (still available for checkout)
- Push fix to origin
- Create new PR for fix (or force-push to same PR if not yet merged)
- After fix merges, re-merge main to feature branches (see Post-Merge below)

Post-Merge (Rebase All Active Branches)

After successful merge, prepare all active branches:

List active branches: git branch -a | grep feature/
For each active branch:
- git fetch origin
- git checkout feature/X
- git rebase origin/main (handle any conflicts)
- make test (verify no new breakage from merged code)
- Mark branch as "rebase-verified" in TODO.md
Update TODO.md: mark all rebase-verified branches
Proceed to next task only after all rebases verified

Git Commit Message Format

TASK-ID: One-line summary (imperative, < 50 chars)

Optional detailed explanation (wrapped at 72 chars):
- What changed and why
- Any non-obvious implementation details
- Links to related tasks/issues

Relates-to: TASK-ID-RELATED
Fixes: #issue-number (if applicable)

Branch Naming Convention

feature/TASK-ID-short-slug        # New features, enhancements
fix/TASK-ID-short-slug            # Bug fixes
refactor/TASK-ID-short-slug       # Code refactoring (no behavior change)
docs/TASK-ID-short-slug           # Documentation only
security/TASK-ID-short-slug       # Security hardening
test/TASK-ID-short-slug           # Test additions/improvements

Example: feature/EVALS-001-sanitization-pipeline

Queue Management

TODO.md Structure

## In Queue (Ready to Start)
- [ ] TASK-CI-001: Implement linting gates (estimate: 4h)
- [ ] TASK-EVALS-001: Build sanitization pipeline (estimate: 6h)

## In Progress
- [x] TASK-SECURITY-001: Phase 1.5 FIXes (branch: feature/TASK-SECURITY-001)
  - Rebase-verified: ✓
  - Pre-push: ✓
  - PR: #24 (merged)

## Blocked (Waiting For)
- [ ] TASK-OPENCODE-001: Depends on TASK-SECURITY-001 (PR merged 2026-05-30)

## Completed This Week
- [x] TASK-SECURITY-001 → PR #24 merged

Incoming Queue (Parallel Delegation)

Store as YAML files in ~/.agentic-engineers/queue/incoming/:

---
task_id: TASK-FEATURE-001
type: DELEGATE
role: senior-engineer
model: claude-opus-4.8  # temporary 48h window
effort: high
priority: urgent

context:
  description: |
    Clear, actionable description
  repo: github.com/niallyoung/agentic-engineers
  branch: feature/TASK-FEATURE-001
  files: [list of relevant files]

requirements:
  - Req 1
  - Req 2
  
acceptance_criteria:
  - "AC1: Testable outcome"
  - "AC2: Framework integrated"

Prevention Patterns

Catch Environment Mismatch Bugs

Pattern: Test locally in container environment before push

# Before git push:
docker run --rm -v $(pwd):/workspace -w /workspace python:3.11 make test

Why: Catches filesystem differences (symlinks, permissions, paths)

Catch Contract Violations

Pattern: Add type hints + assert parameters at function entry

def validate_queue_path(path: Path | str) -> bool:
    """Validate queue path (must be directory, not file)."""
    p = Path(path)
    assert p.is_dir(), f"Expected directory, got file: {p}"  # Catch misuse immediately
    # ... rest of validation

Why: Catches wrong types at runtime with clear error messages

Catch Incomplete Feature Integration

Pattern: Use add-feature-to-framework SKILL checklist

Tests written (unit + integration)
Docs updated (README, AGENTS.md, inline comments)
SPEC.md updated (new requirements/constraints)
Framework integration verified (hooks, decorators, validators)
No framework drift (compliance check passes)

Why: Prevents partial features that work in isolation but break integration

Implementation Roadmap

Phase 1 (This 48h Window)

Create .githooks/pre-commit (linting, type checking, secrets detection)
Create .githooks/pre-push (run full test suite)
Add to make setup (auto-install hooks)
Document workflow in AGENTS.md

Phase 2 (Post-48h)

Add container simulation to pre-push (optional on first run)
Build comprehensive test environment validation
Create automated compliance dashboard (SPEC.md drift detection)

Phase 3 (Ongoing)

Apply to all team members (training, code review)
Measure impact (reduce CI failures by X%)
Iterate based on feedback

Related Skills

add-feature-to-framework: Checklist for fully integrating new features
spec-validator: Validates compliance with SPEC.md requirements
protocol-validator: Validates DELEGATE/HANDBACK protocol compliance
spec-management: Manages SPEC.md changes with approval workflow

References

.githooks/: Hook implementation
Makefile: make setup, make test, make validate-spec
SPEC.md: Framework requirements
AGENTS.md: Role definitions
TODO.md: Task tracking