菜单
Disciplined queue-to-branch-to-PR-to-merge workflow for code quality and CI stability
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| 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 |
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
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:
Local Validation First: All obvious failures caught locally BEFORE CI runs
CI as Release Gate: CI pipeline validates release-readiness, not development correctness
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
Merge Discipline:
Rebase Discipline:
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)
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)
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
git checkout -b feature/TASK-ID-short-descriptionin_progressgit commit -m "TASK-ID: one logical change"make test locally (all tests pass)make validate-spec (code complies with SPEC.md)git log origin/main..HEAD (each commit is one logical unit)[AREA] TASK-ID: Brief description (e.g., [Security] TASK-CI-001: Fix path validation)CRITICAL: Watch for CI failures immediately after merge!
After successful merge, prepare all active branches:
git branch -a | grep feature/git fetch origingit checkout feature/Xgit rebase origin/main (handle any conflicts)make test (verify no new breakage from merged code)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)
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
## 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
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"
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)
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
Pattern: Use add-feature-to-framework SKILL checklist
Why: Prevents partial features that work in isolation but break integration
.githooks/pre-commit (linting, type checking, secrets detection).githooks/pre-push (run full test suite)make setup (auto-install hooks)add-feature-to-framework: Checklist for fully integrating new featuresspec-validator: Validates compliance with SPEC.md requirementsprotocol-validator: Validates DELEGATE/HANDBACK protocol compliancespec-management: Manages SPEC.md changes with approval workflow.githooks/: Hook implementationMakefile: make setup, make test, make validate-specSPEC.md: Framework requirementsAGENTS.md: Role definitionsTODO.md: Task trackingExperiment 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.
DEPRECATED — This skill is no longer maintained. Prometheus and Grafana infrastructure was never implemented. Use local JSON metrics analysis instead.
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.
Routine maintenance for Codex sessions: monitor queue state, close completed sub-agents, resume or escalate active work, and keep agent capacity available.
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.
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.