Agentic Engineering: Documentation-First Development for AI Coding Agents

Introduction

Agentic Engineering is a GitHub repository that champions documentation-first development for AI coding agents. It provides a comprehensive suite of ten skills designed to give AI agents persistent memory, zero-ambiguity specifications, append-only decisions, and an independent verification gate. This project acts as a crucial harness layer for long-running, loop-driven development, ensuring that AI agents produce coherent and architecturally sound code.

Its core description highlights its purpose: "Documentation-first development for AI coding agents, 10 skills: persistent memory, zero-ambiguity specs, append-only decisions, and an independent verification gate. The harness layer for long-running, loop-driven development."

Why Use It and Key Benefits

AI agents often struggle with statelessness, meaning each new session starts from scratch, unaware of previous decisions, naming conventions, or architectural constraints. This leads to "context collapse," where code might run but lacks architectural coherence. Agentic Engineering directly tackles these problems:

• Agent produces contradictory code: The SPEC skill provides a clear contract for the agent to build against.
• Agent makes resolved decisions again: ADR (Architecture Decision Record) preserves decision history.
• New session has no memory: STATUS provides persistent memory and checkpoints.
• Agent builds the wrong thing: PRD (Product Requirements Document) defines what and why.
• Agent claims "done" when it isn't: VERIFICATION makes "done" a verdict, not a claim.
• Code lands as untraceable commits: GIT WORKFLOW ensures each task ships as an evidence-carrying pull request.
• Docs say one thing, code another: DOC MAINTENANCE keeps documentation aligned with reality.
• Adopting on existing codebases is hard: ONBOARDING reverse-engineers the as-built chain.

The suite's skills flow logically, from initial project kickoff and specification to implementation, verification, and ongoing maintenance. Architecture Decision Records (ADR) can be triggered at any point where a decision fork appears. The VERIFY skill ensures every task is independently checked, and STATUS tracks progress across sessions. Code changes are managed via GIT WORKFLOW, with a branch per task and human-gated merges.

This framework serves as a robust "harness layer" for long-running agents, providing essential primitives:

• External completion criteria: Defined by SPEC acceptance criteria and IMPL PLAN locked done conditions.
• Persistent state: Managed by STATUS handoff logs and in-flight checkpoints.
• Independent evaluator: The independent-verification skill ensures maker-checker separation.
• Checkpoint cadence: STATUS protocol updates at task granularity.
• Project knowledge: AGENTS.md acts as the single source of truth.
• Decision history: ADR provides an append-only, non-rewritable record.
• Worktrees and sub-agents: git-workflow and the bundled verifier agent enable parallel, isolated work.

Crucially, the system incorporates "Loop Safety" non-negotiables, including a circuit breaker for consecutive failures, a test ratchet to prevent test deletion, locked done conditions, and a mandatory human gate for all merges, preventing "comprehension debt."

Installation

Agentic Engineering is designed for easy integration with various AI coding tools.

Quick Start (Claude Code, recommended)

If you are using Claude Code, you can add and install the plugin directly:

/plugin marketplace add affectionatec/agentic-engineering
/plugin install agentic-engineering@agentic-engineering

Once installed, you can use the entry point /using-agentic-engineering to assess your project's status or /run-loop M2 to drive tasks. Individual skills can be auto-triggered or invoked explicitly, for example, /agentic-engineering:independent-verification.

Manual Install

For other environments like Codex, Cursor, Copilot, or any agent that can read Markdown playbooks, you can manually clone the repository and symlink or copy the skill directories:

git clone https://github.com/affectionatec/agentic-engineering.git ~/src/agentic-engineering

mkdir -p ~/.claude/skills
for skill in agents-md-template architecture-decision-record \
             documentation-maintenance existing-project-onboarding \
             git-workflow implementation-plan independent-verification \
             project-kickoff-prd run-loop status-tracker \
             technical-specification using-agentic-engineering; do
  ln -s "$HOME/src/agentic-engineering/skills/$skill" "$HOME/.claude/skills/$skill"
done

The skills are plain Markdown playbooks, and the AGENTS.md chain is tool-agnostic, ensuring consistent instructions across different agents.

Examples

The workflow for your first project with Agentic Engineering is structured and guided:

1. Set up AGENTS.md: You say, "Set up AGENTS.md for this repo." The agents-md-template skill fires, creating AGENTS.md and pointer files for all tools.
2. Kick off PRD: You say, "Let's kick off: I want to build X." The project-kickoff-prd skill initiates a phased dialogue, resulting in docs/prd.md.
3. Write specs: You say, "Write the specs." The technical-specification skill generates docs/spec/*.md for each domain.
4. Record decisions: At any decision fork, you might say, "Should we use X or Y?" The architecture-decision-record skill creates docs/adr/ADR-NNN-*.md.
5. Create implementation plan: You say, "Break this into tasks." The implementation-plan skill produces docs/plans/implementation-plan.md.
6. Pick up next task: For every session, you say, "Pick up the next task." The status-tracker skill provides a briefing from docs/status.md, resuming work where it left off.
7. Verify tasks: You say, "Verify M1-T1." The independent-verification skill dispatches a bundled verifier, returning a PASS/FAIL verdict with evidence in docs/verification-log.md.
8. Run loop (unattended): You can use /run-loop M1 for unattended execution. This leverages git-workflow and the verifier agent to create a queue of verified draft pull requests, with merging remaining a human decision.
9. Documentation maintenance: At any time after kickoff, if you want to add a feature or if a spec becomes stale, the documentation-maintenance skill catches the drift, proposes gated updates, and folds them back into the chain with user approval.

If you already have an existing codebase, start with the existing-project-onboarding skill. It reverse-engineers the as-built chain (AGENTS.md, PRD, specs, ADRs, a forward plan, and seeded STATUS) from your code, allowing new work to proceed through the standard workflow.

Links

• GitHub Repository: https://github.com/affectionatec/agentic-engineering
• License: MIT License