English | Русская версия
Note
Language & Localization: The default core rules (AGENTS.md and docs/) are written in Russian, as this kit was originally tailored for the Russian-speaking engineering community. However, it is 100% language-agnostic. If you work in English or another language, simply instruct your AI agent during onboarding:
"Translate all starter kit rules and docs into English (or your target language) and adapt them to our project." The agent will handle the translation instantly.
A battle-tested, vendor-neutral starter kit providing software engineering standards, architectural foundations, and automated verification protocols for all autonomous AI coding agents:
- Universal Agent Standard: Built on the open
AGENTS.mdspecification (stewarded by the Agentic AI Foundation / Linux Foundation), universally parsed by Gemini Antigravity, Claude Code, Cursor, Windsurf, Roo Code, Cline, Codex, GitHub Copilot, Aider, OpenCode, and custom agents. - Claude Code Ready: Zero-overhead compatibility via
CLAUDE.md -> AGENTS.mdsymlink. - 100% Agent- & Language-Agnostic: Operates on strict architectural contracts, system invariants, and Zero Vibe Coding, regardless of your IDE, terminal agent, or programming language.
This starter kit is the practical implementation of the AI engineering methodology published in the essay series: 👉 Code Got Cheap. Engineering Thought Did Not (AVPDev Blog)
- Part 1: Code Got Cheap. Engineering Thought Did Not — Shifting from syntax-level coding to architectural control, system invariants, and intent management.
- Part 2: AI Loves Straight Roads: Why Local Optimization Breaks Complex Systems — Why removing architectural fences, queues, and boundaries creates technical debt even when local tests are green.
- Part 3: Architect of the Future: From Line-by-Line Review to Design Review — The
Skeleton + Pluggable Modulespattern,DESIGN.md/ Design Review, delegation boundaries, and the architect’s responsibility for system integrity.
agent-starter-kit/
├── AGENTS.md # Single Source of Truth for rules, stack, and gates
├── .gitignore # Cross-stack local/secret artifact baseline
├── .github/workflows/verification.yml # CI Verification Gate for push/PR
├── CLAUDE.md # Symlink to AGENTS.md (Claude Code compatibility)
├── docs/ # Architectural core documentation
│ ├── onboarding-protocol.md # ⚡ Automated repository scanning & onboarding protocol
│ ├── architecture.md # System architecture (Skeleton + Pluggable Modules)
│ ├── theme-tokens.md # 🎨 Semantic design tokens spec & hot-swappable themes
│ ├── decisions.md # Architecture Decision Records (ADR registry)
│ ├── state.md # Session ledger (Done / In Progress / Tech Debt)
│ ├── glossary.md # Domain terminology glossary
│ ├── agent-routing.md # Adaptive agent routing and context containment
│ ├── project-structure.md # File hygiene, ownership and project boundaries
│ ├── verification.md # Impact, safety and test-coverage policy
│ ├── verification-profile.example.tsv # Profile template; adapt per project
│ └── design-manifest-template.md# Zero Vibe Coding pre-project design manifest
├── scripts/
│ ├── init-project.sh # One-click non-destructive setup script
│ ├── verify-project.sh # Project-local verification profile dispatcher
│ ├── security-scan.sh # Dependency-free secret baseline scanner
│ └── verification-profile.tsv # This kit's runnable gate; not copied to targets
├── CHANGELOG.md # Kit version history and releases
├── README.md # English documentation (this file)
└── README.ru.md # Russian documentation
Systems are divided into an immutable Skeleton designed by the Human Architect (DB schemas, Auth context, event bus, centralized audit) and Pluggable Modules generated by AI. Modules are strictly isolated by typed DTO contracts and have no direct access to foreign private tables. When requirements change, modules are regenerated from scratch rather than subjected to brittle manual refactoring.
Every engineering task is strictly assigned to an ownership tier:
- Zone 1: Full Delegation (100% AI) — Pure functions, DTO converters, utilities, UI components matching design systems, data parsers, edge-case unit tests.
- Zone 2: Contract Delegation (50 / 50) — CRUD endpoints, queue workers, external API integrations, Server Actions. The agent writes zero implementation code until Failure Modes are agreed.
- Zone 3: Zero Delegation (0% AI / Human Architect Only) — Data ownership model & DB schema, financial transactions, authorization model (RBAC/ABAC), core security. Modification strictly requires a Confirmation Gate.
Before writing code for non-trivial tasks, the agent formulates a concise manifest specifying:
- System Invariants: What can never happen (tenant isolation, transactional integrity, non-negative balances).
- State Machine: Valid entity states and permitted transitions.
- Failure Modes & Idempotency: Handling network timeouts, retry policies, and duplicate webhooks/requests.
- Acceptance Invariants: Specific failure and stress test scenarios.
Vibe coding must be strictly verified by automated tooling. A task is never considered done until the agent runs verification commands:
- TypeScript:
pnpm typecheck(tsc --noEmit),pnpm lint,pnpm test - Python:
ruff check .,mypy .,pytest - Go:
go vet ./...,golangci-lint run,go test -v ./... - Project-local profile:
./scripts/verify-project.shruns only commands confirmed during onboarding;./scripts/security-scan.shprovides a dependency-free secret baseline. Exit code 0 is mandatory. Every iteration must include unit/integration tests for both happy path and edge cases.
The repository-level workflow at .github/workflows/verification.yml runs on pushes to main, pull requests targeting main, and manual dispatch. It uses read-only repository permissions, checks out without persisting credentials, runs the project profile, validates local Markdown links, and fails if verification changes the checkout.
Before starting work on any iteration, the agent checks upstream synchronization:
git fetch origin && git status -uno- Remote Drift Rule: If the local branch is behind
origin, the agent must halt immediately and alert the user. Blind automaticgit pullis strictly prohibited to prevent merge conflicts. - Atomic Commits: Each verified iteration is committed using Conventional Commits (
feat:,fix:,test:,refactor:).
The agent utilizes Context7 MCP (resolve-library-id → query-docs) or web search to verify up-to-date SDK signatures and documentation before generating integration code. The agent prompts the user only if critical breaking changes exist; minor backward-compatible updates are adopted seamlessly.
For non-trivial work the main agent is the orchestrator: it defines the contract, delegates substantive work to isolated workers, checks evidence, runs gates, integrates and accepts the result. The topology policy uses orchestrated by default, with single reserved for trivial or explicit fallback tasks and fixed-pipeline, side-research, parallel, and hierarchical for specialized shapes. For long sessions, keep a task ledger and checkpoint after each gate instead of retaining raw transcripts in the main context. Checkpoints are separate from commits: commits are created only after a green gate, one atomic task at a time, and push/PR remain separate actions. Verification & Safety adds pre-change impact checks, positive/negative/security/regression layers, safe probes and targeted escalation. It does not prescribe models or a vendor-specific runtime; orchestration remains a documentation-driven role. See docs/agent-routing.md and docs/verification.md.
You do not need to write project descriptions manually. The agent inspects your repository and synthesizes the necessary standards following docs/onboarding-protocol.md. The same protocol supports manual completion, automatic brownfield discovery, and greenfield interviewing.
Open a new or existing repository in your IDE or terminal and prompt your agent:
Copy & Paste Prompt:
Read /path/to/agent-starter-kit/docs/onboarding-protocol.md. Inspect the current project, classify it as Brownfield or Greenfield, extract discoverable facts, preserve existing documentation, and prepare the non-destructive onboarding update. Ask only questions that cannot be answered from the repository and present a summary before applying changes.
The script only adds missing files, never overwrites existing project data, and copies the baseline .gitignore only when it is absent:
/path/to/agent-starter-kit/scripts/init-project.sh --yes /path/to/new-project
/path/to/agent-starter-kit/scripts/init-project.sh /path/to/your-project
/path/to/agent-starter-kit/scripts/init-project.sh --dry-run /path/to/your-project
/path/to/agent-starter-kit/scripts/init-project.sh --update /path/to/your-projectThen run the onboarding prompt from the protocol. Brownfield projects are scanned automatically; greenfield projects receive only the minimum necessary interview. The target receives the generic dispatcher, secret scanner and profile template, while the active profile is generated from its manifests. --update is intended only for an existing project and never creates a new target directory.
The agent preserves project-specific sections in AGENTS.md, adds only missing standard rules, and reports every preserved or created file. Existing documents, tests, configuration, secrets, and manual values are never silently replaced.
- Runtimes & Languages: Node.js 24 LTS / Node.js 26 Current (LTS expected in October 2026) / Bun 1.3+ / Python 3.13–3.14 / Go 1.27+ / TypeScript 5.8+
- Frontend: Next.js (App Router) / React / Astro / Tailwind CSS
- Backend & Background: Next.js Server Actions / FastAPI / Go microservices / WebSockets / BullMQ (Redis)
- Databases & Vector: PostgreSQL, Drizzle ORM, Redis, pgvector + HNSW indexes
- AI & Inference: LLM APIs (Anthropic Claude, OpenAI GPT, Gemini), ONNX Runtime, Agent Orchestration
- Infra & DevOps: Docker, Coolify / Dokploy (self-hosted PaaS), GitHub Actions (CI/CD), Linux (Bash, Nginx)
Aliaksei Patskevich (AVPDev)
AI SOLUTIONS ARCHITECT • GITHUB • TELEGRAM