Universal Agent Workflow Template

Model-agnostic guardrails for building software with AI assistants without losing engineering discipline.

AI coding is fast, but speed without review can create fragile systems: leaked secrets, unsafe shell commands, missing tests, oversized files, and architecture drift. This template gives new projects a reviewable workflow from the first commit: design gates, Cursor project rules, runtime hooks, pre-commit checks, CI, and expert-review prompts.

The template is LLM-agnostic. It works with Cursor using OpenAI GPT/Codex models, Anthropic Claude models, or other providers. It also includes CHATGPT.md for ChatGPT/Codex-style workflows where users manually provide context instead of relying on Cursor automation.

What This Demonstrates

This template is built for teams that want AI-assisted development without losing engineering control.

• Evidence-first security mindset — secrets, PII, unsafe logging, risky shell commands, and weak security patterns are checked before they ship.
• Architecture discipline — dependency-direction tests enforce downward imports for src/<package>/, while file-size checks prevent god objects and keep modules maintainable.
• Human-in-the-loop governance — design docs and expert review happen before implementation and again before release.
• Model-agnostic workflow — works with Cursor, OpenAI GPT/Codex, ChatGPT-style workflows, Claude, and other AI tools.
• Operational readiness — CI, pre-commit hooks, runbooks, and specialist review agents make safety repeatable instead of dependent on memory.

What You Get

Five layers of protection, from design to deployment:

┌─────────────────────────────────────────────────────────────────┐
│  1. DESIGN GATE         No code without design docs            │
├─────────────────────────────────────────────────────────────────┤
│  2. RUNTIME HOOKS       Blocks dangerous commands live         │
├─────────────────────────────────────────────────────────────────┤
│  3. TESTS + PRE-COMMIT  Architecture, secrets, PII, patterns   │
├─────────────────────────────────────────────────────────────────┤
│  4. CI PIPELINE         Template checks, SAST, secret scanning │
├─────────────────────────────────────────────────────────────────┤
│  5. EXPERT REVIEW       23 specialist agents before release    │
└─────────────────────────────────────────────────────────────────┘

Quick Start

# Create a new public GitHub repo from this template
gh repo create my-project \
  --template KangaKode/universal-agent-workflow-template \
  --clone

cd my-project
python3 -m venv .venv && source .venv/bin/activate
make install          # Install local quality tools + pre-commit hooks
cp .env.example .env  # Add your environment values (never commit .env)
make check            # Verify template scripts/config

Next: Customize AGENTS.md, AGENT_GUIDE.md, CHATGPT.md, and docs/ARCHITECTURE.md for your project. Then open the project in your AI tool and use AGENT_GUIDE.md for Cursor or CHATGPT.md for ChatGPT/Codex-style workflows.

Non-Engineer POC Path

If you are using AI to turn an idea into a POC for engineers to review, start with START_HERE.md. It links the product brief, vibe-coding smell checklist, engineer handoff packet, and make validate-handoff gate. This is for guarded POCs and clean engineer handoff, not production shipping without engineering/security approval.

Positioning: non-engineers can move fast, but the output has guardrails, evidence, and review artifacts that make engineering takeover much safer.

Guardrail docs: docs/QUALITY_GUARDRAILS.md, docs/SECURITY_GUARDRAILS.md, and docs/ARCHITECTURE_GUARDRAILS.md.

Completed example: docs/examples/task-tracker-poc/.

The Workflow

flowchart TD
    request[Feature Request] --> design[Create Design Docs]
    design --> designReview["Expert Review: Design"]
    designReview --> implement[Implementation]
    implement --> specialistReview["Red Team + Code + Specialist Review"]
    specialistReview --> checks["Pre-commit + CI"]
    checks --> finalReview["Final Expert Sign-off"]
    finalReview --> ship[Ship]

Loading

The key rule: Design docs before code. The Worker Gate instructs agents to stop implementation until docs/designs/<feature>/ exists and is reviewed. After implementation, red-team, code-review, and specialist review inspect the diff; pre-commit and CI provide mechanical gates; final sign-off confirms review findings are resolved before shipping.

---

Safety Layers Explained

Layer 1: Design Gate (Worker Gate)

Before any code is written, design docs must exist:

docs/designs/<feature-name>/
├── 01_ARCHITECTURE_MAP.md
├── 02_DATA_FLOW.md
├── 03_WIREFRAMES.md
└── 04_IMPLEMENTATION_PLAN.md

The Cursor rules instruct agents to avoid production code until these exist. This reduces "vibe coding" failure modes where teams ship first and reason about architecture later.

Layer 2: Runtime Safety (Cursor Hooks)

These fire while you're coding in Cursor:

Hook	What It Does
block-dangerous-shell.py	Blocks rm -rf /, git push --force, curl | bash
block-tab-secrets.py	Prevents Tab autocomplete from ingesting .env, .pem files
session-start.py	Injects context about current Worker Gate phase
log-subagent-start.py	Logs when subagents are invoked
log-subagent-stop.py	Logs when subagents complete

Layer 3: Pre-Commit Checks

These fire when you try to commit:

Hook	What It Catches
check_secrets.py	API keys, passwords, tokens in code
check_pii.py	SSN, credit card numbers, emails, phone numbers, IPs
check_file_size.py	Files over 500 lines (forces modularity)
check_raw_logging.py	Logging entire objects (data exposure risk)
reject_env_files.py	.env files (should never be committed)
red_team_check.py	Security anti-patterns (SQL injection, SSRF)
tests/test_architecture.py	Downward dependency rules for src/<package>/

Plus standard tools: Black (formatting), Ruff (linting), Bandit (security).

Layer 4: CI Pipeline

Runs on every push and PR:

Job	What It Does
Lint & Format	Runs all pre-commit hooks (Black, Ruff, Bandit, custom checks)
Template Check	Validates hook scripts and config files
Architecture Test	Enforces downward imports once src/<package>/ exists
Secret Scan	gitleaks — scans full git history
SAST	Bandit — Python security analysis once src/ exists

After your project has real src/ and tests/ directories, add a dedicated app test job to .github/workflows/ci.yml.

SAST (Static Application Security Testing) catches vulnerabilities like:

• Hardcoded passwords
• SQL injection patterns
• Insecure random number generation
• Shell injection risks

Layer 5: Expert Review (23 Specialists)

Before major releases, invoke the expert panel:

Category	Agents
Security	red-team, security-hardener, agent-security-specialist, sast-reviewer
Architecture	solution-architect, codebase-scout, minimalist, project-curator
Data	sql-pro, data-flow-guardian, rag-engineer, knowledge-engineer
Delivery	cicd-engineer, infrastructure-engineer, observability-engineer, test-architect
Quality	ai-engineer, prompt-engineer, code-reviewer, debugger
Process	design-doc-author, compliance-auditor, ux-researcher

The expert review protocol (.cursor/rules/expert-review.mdc) runs an 8-expert deliberation before shipping.

---

What's Included

Core Files

├── AGENTS.md              # Repository map (what's where)
├── AGENT_GUIDE.md         # Session guide for Cursor (all models)
├── CHATGPT.md             # Session guide for paste-context workflows
├── Makefile               # Common commands
├── .cursor/
│   ├── agents/            # 23 specialist agent definitions
│   ├── rules/             # Always-on workflow rules (7 rules)
│   ├── hooks/             # Runtime safety hooks (5 hooks)
│   └── skills/            # Extensible skill system
├── scripts/hooks/         # Pre-commit enforcement scripts
├── .pre-commit-config.yaml
└── .github/workflows/ci.yml

Documentation

Doc	Purpose
docs/ARCHITECTURE.md	System layers and import rules
docs/CONVENTIONS.md	Coding standards and security checklist
docs/TESTING_STANDARDS.md	Test markers, fixtures, coverage requirements
docs/QUALITY_GUARDRAILS.md	POC quality evidence and test-first expectations
docs/SECURITY_GUARDRAILS.md	Data, secrets, LLM, and deployment safety gates
docs/ARCHITECTURE_GUARDRAILS.md	Engineer handoff architecture standards
docs/examples/task-tracker-poc/	Completed example brief, design summary, handoff, and smell fix
docs/reference/AI_AGENT_SECURITY_PATTERNS.md	AI agent security patterns (identity, injection, scope)
docs/runbooks/	6 operational runbooks (rollback, recovery, incidents)

Docker Support

# Development
docker compose up -d        # After adding src/ and customizing Dockerfile CMD
docker compose down         # Stop services

# Production build
docker build --target production -t myapp .

The Dockerfile and docker-compose.yml are starter templates for Python services. They are intentionally not complete application containers until you add src/ and replace the placeholder command.

Secret Scanning

.gitleaks.toml configures secret detection for CI. Catches:

• Cloud keys, LLM provider tokens, internal service credentials
• Generic API keys, passwords, private keys
• Blocks commits before secrets reach the repo

---

Commands

make help            # Show all commands

# Testing
make check           # Validate template scripts/config
make test            # Run full test suite after adding tests/
make test-p0         # Run critical (P0) tests only
make test-coverage   # Run with coverage report
make validate-handoff HANDOFF=docs/handoffs/my-feature.md

# Quality
make lint            # Run linters (black, ruff, bandit)
make format          # Auto-format code

# Security
make red-team        # Run adversarial security check
make red-team-staged # Security check on staged files only

# Setup
make install         # Install deps + pre-commit hooks
make clean           # Remove caches and build artifacts

---

Using Different AI Tools

Tool	Entry Point	What Works
Cursor (any model)	AGENT_GUIDE.md	Full: hooks, rules, agents
ChatGPT / Codex	CHATGPT.md	Manual: follow the guide
GitHub Copilot	CHATGPT.md	Manual: follow the guide

Cursor provides the best experience because hooks and rules run automatically. Other tools require you to manually follow the guidelines.

---

Customization

Adding Project-Specific Rules

Create .cursor/rules/your-rule.mdc:

# Your Rule Name

[Description of when this rule applies]

## Requirements
- [Requirement 1]
- [Requirement 2]

Rules in .cursor/rules/ are always active for all Cursor sessions in this project.

Adding Pre-Commit Hooks

1. Create your script in scripts/hooks/your_check.py
2. Add to .pre-commit-config.yaml:

- repo: local
  hooks:
    - id: your-check
      name: Your check description
      entry: python scripts/hooks/your_check.py
      language: python
      types: [python]

Adding Specialist Agents

Create .cursor/agents/your-agent.md with the standard template (see existing agents for format).

Disabling Safety Checks

You can disable checks, but you shouldn't. Each check exists because someone shipped a bug without it.

If you must disable something temporarily:

• Pre-commit: git commit --no-verify (use sparingly)
• CI: Comment out the job in .github/workflows/ci.yml
• Worker Gate: Add "no Worker Gate needed" to the brief (PM decides, not worker)

---

Related: Reusable Guardrail Setup

This template provides project-level files that are versioned with each repo.

For a reusable installer that copies this rule pack into other projects, see: KangaKode/universal-agent-bootstrap

universal-agent-bootstrap     → Reusable guardrail installer
universal-agent-workflow-template → Project files (once per project)

Bootstrap installs project-local Cursor rules into a target repo. This template ships those rules directly as part of the project.

---

Daily Workflow

1. Describe what you want to build
2. Design — Ask the AI to create design docs in docs/designs/<feature>/
3. Review — Run expert panel on design docs
4. Implement — Build with tests (after design approval)
5. Verify — make lint, make test, make red-team
6. Ship — Commit only when all checks pass

---

License

MIT