# Agentic Engineering: Documentation-First Development for AI Coding Agents

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/affectionatec-agentic-engineering
Generated for open source discovery and AI-assisted research.

Agentic Engineering introduces a documentation-first development framework designed for AI coding agents. It effectively addresses the core challenges of agent statelessness and context collapse by providing a structured chain of documentation and verification skills. This suite serves as a robust harness layer, enabling long-running, loop-driven AI development workflows with persistent memory and clear contracts.

GitHub: https://github.com/affectionatec/agentic-engineering
OSRepos URL: https://osrepos.com/repo/affectionatec-agentic-engineering

## Summary

Agentic Engineering introduces a documentation-first development framework designed for AI coding agents. It effectively addresses the core challenges of agent statelessness and context collapse by providing a structured chain of documentation and verification skills. This suite serves as a robust harness layer, enabling long-running, loop-driven AI development workflows with persistent memory and clear contracts.

## Topics

- AI Agents
- Agentic Engineering
- Developer Tools
- Documentation-First
- LLM Development
- Software Architecture
- Git Workflow
- Code Generation

## Repository Information

Last analyzed by OSRepos: Sun Sep 20 2026 16:31:05 GMT+0100 (Western European Summer Time)
Detail views: 2
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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:

bash
/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:

bash
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](https://github.com/affectionatec/agentic-engineering){:target="_blank"}
*   **License:** [MIT License](https://github.com/affectionatec/agentic-engineering/blob/main/LICENSE){:target="_blank"}