Skip to content
/

shinpr/agentic-code

shinpr-agentic-code · shinpr/agentic-code · ★ 46 · last commit 2026-03-30

AGENTS.md-based framework that enforces TDD, Plan Injection gates, and progressive skill loading across Cursor, Codex CLI, and Gemini CLI.

Best whenContext engineering (what information the agent has at each step) is more important than model selection; progressive skill loading limits token cost without…
Skip ifLoading all skills at session start (load progressively only), Writing code without explicit Plan Injection evidence
vs seeds
superpowers(skills-only TDD-enforced behavioral framework), but differs in four ways: ships a CLI scaffolding tool, targets three A…
Primitive shape 9 total
Skills 9
00

Summary

shinpr/agentic-code — Summary

Elevator pitch: A multi-tool, language-agnostic coding-agent framework centered on AGENTS.md, delivered as an npm package (npx agentic-code) that scaffolds a new project with a full .agents/ directory tree. It targets Cursor, OpenAI Codex CLI, Gemini CLI, and any AGENTS.md-compatible tool without requiring configuration. The framework enforces TDD and sequential quality gates through task/workflow/skill markdown files read progressively by the agent; a metacognition skill applied at session start keeps the agent self-aware of its current phase. Codex is one of three primary target tools — not the planner or reviewer, but an equal-rank executor alongside Cursor and Gemini. A separate sibling repo (shinpr/codex-workflows) by the same author extends this with Codex-specific subagent TOML definitions; the README explicitly recommends that repo for "more Codex-specific setup." Compared to seeds: closest to superpowers (skills-only behavioral framework, TDD Iron Law), but distinguished by the CLI scaffolding tool, multi-tool portability via the AGENTS.md standard, and its progressive skill-loading pattern that limits token cost by loading only what is needed for the current task.

01

Overview

shinpr/agentic-code — Overview

Origin

By GitHub user shinpr (same author as shinpr/codex-workflows). Version 0.7.0, MIT license. 46 stars. Published as an npm package runnable via npx. Last commit: 2026-03-30.

The two repos have a documented relationship: agentic-code is the multi-tool universal framework; codex-workflows is a Codex-specific extension that adds subagent TOML definitions and context isolation.

Philosophy

"Every AI coding tool has the same problems: Forgets your project structure after 10 messages / Deletes tests when adding features / Ignores architectural decisions / Skips quality checks. We built the solution into the framework."

The framework treats context engineering (what information the agent has at each step) as the primary lever for quality, not model selection. AGENTS.md is the universal entry point, and skills are loaded progressively — only what is needed for the current task is loaded, explicitly limiting token cost.

Three pillars:

  1. Tasks — define WHAT to build (task-analysis.md, implementation.md, technical-design.md, etc.)
  2. Workflows — define HOW to build it (sequential or multi-step procedures)
  3. Skills — define quality STANDARDS (coding-rules, testing, metacognition, etc.)

AGENTS.md Philosophy (verbatim)

ABSOLUTE PRINCIPLES

1. EXECUTE all rules and requirements in task/skill files - no exceptions
2. COMPLETE all entry and exit conditions for every task
3. STOP at gates - proceed only when conditions are met

Metacognition Pattern

The metacognition skill is applied at session start and kept active for the entire session — a persistent self-monitoring layer that performs mandatory checkpoints at task-type changes, unexpected errors, and phase transitions.

02

Architecture

shinpr/agentic-code — Architecture

Distribution

  • Type: npm package (CLI tool)
  • Binary: agentic-code (via npx agentic-code)
  • Version: 0.7.0
  • License: MIT

Install

npx agentic-code my-project   # new project
# or for existing project:
cp -r path/to/agentic-code/AGENTS.md .
cp -r path/to/agentic-code/.agents .

# Install skills to Codex:
npx agentic-code skills --codex        # global (~/.codex/skills/agentic-code/)
npx agentic-code skills --codex --project  # project-scoped

# Install skills to Cursor:
npx agentic-code skills --cursor

Required Runtime

  • Node.js (no explicit minimum stated)
  • One of: Cursor, Codex CLI, Gemini CLI, or any AGENTS.md-compatible tool

Directory Tree (installed)

<project>/
├── AGENTS.md                          # Universal AI entry point (task routing, gates)
└── .agents/
    ├── context-maps/                  # optional project maps
    ├── skills/
    │   ├── metacognition/SKILL.md     # persistent self-monitoring
    │   ├── coding-rules/SKILL.md      # development standards
    │   ├── testing/SKILL.md           # TDD process
    │   ├── testing-strategy/SKILL.md
    │   ├── ai-development-guide/SKILL.md
    │   ├── documentation-criteria/SKILL.md
    │   ├── implementation-approach/SKILL.md
    │   ├── integration-e2e-testing/SKILL.md
    │   └── ...
    ├── tasks/
    │   ├── task-analysis.md           # entry point — scale + path determination
    │   ├── implementation.md
    │   ├── technical-design.md
    │   ├── acceptance-test-generation.md
    │   ├── code-review.md
    │   ├── integration-test-review.md
    │   ├── prd-creation.md
    │   ├── quality-assurance.md
    │   ├── technical-document-review.md
    │   └── work-planning.md
    └── workflows/
        └── agentic-coding.md

Target AI Tools

  • Cursor (primary)
  • OpenAI Codex CLI (primary, skills install to ~/.codex/skills/)
  • Gemini CLI (primary, reads AGENTS.md automatically)
  • Any AGENTS.md-compatible tool
03

Components

shinpr/agentic-code — Components

CLI Binary (1)

Command Purpose
npx agentic-code <project-name> Scaffold new project with AGENTS.md + .agents/ tree
npx agentic-code skills --codex Install skills to ~/.codex/skills/agentic-code/
npx agentic-code skills --cursor Install skills to ~/.cursor/skills/agentic-code/
npx agentic-code skills --path <dir> Install to custom path

Tasks (10, in .agents/tasks/)

Name Purpose
task-analysis.md Universal entry point — determines scale (small/medium/large) and routes to appropriate path
implementation.md TDD implementation with required skill loading protocol
technical-design.md Architecture/design document creation
acceptance-test-generation.md Generate test skeletons from acceptance criteria
code-review.md Code review checklist and process
integration-test-review.md Integration and E2E test review
prd-creation.md Product requirements document creation
quality-assurance.md Quality gate execution
technical-document-review.md Review of technical specifications
work-planning.md Work breakdown and task ordering

Skills (9+, in .agents/skills/)

Name Purpose
metacognition Persistent self-monitoring — applies at session start, active entire session
coding-rules Development standards and best practices
testing TDD process (Red-Green-Refactor)
testing-strategy Test type selection and strategy
ai-development-guide AI agent development guidelines
documentation-criteria Document quality standards
implementation-approach Implementation pattern guidance
integration-e2e-testing Integration/E2E test standards

Workflows (1)

Name Purpose
agentic-coding.md Top-level workflow: task analysis → path selection → execution

Subagents

None. All execution is performed by the single agent following loaded task/skill files.

Hooks

None. Framework relies on AGENTS.md reading, not Claude Code hooks.

Key Pattern: Plan Injection

AGENTS.md mandates that all tasks require "Plan Injection" for BLOCKING READs — the work plan must explicitly list every file that will be read during execution, verified at each gate. Missing a BLOCKING READ causes an IMMEDIATE HALT.

05

Prompts

shinpr/agentic-code — Prompts

Prompt 1: AGENTS.md — Plan Injection (verbatim)

Source: .agents/tasks/AGENTS.md (the root AGENTS.md)

## Plan Injection [MANDATORY ENFORCEMENT]
**All tasks require Plan Injection for BLOCKING READs:**
- Task-analysis.md Step 8 scans and identifies ALL BLOCKING READ requirements
- Work plans MUST contain every BLOCKING READ from workflow/tasks/skills
- Each phase verifies its BLOCKING READs are in the plan
- Gates verify Plan Injection evidence before proceeding
- Missing ANY BLOCKING READ = IMMEDIATE HALT

Prompting technique: Hard constraint with automatic halt condition. The "IMMEDIATE HALT" language is an explicit behavioral override that takes precedence over any competing instruction. This is more aggressive than superpowers' "Iron Law" pattern because it creates a specific error state (halt + return to task analysis) rather than just forbidding the behavior.


Prompt 2: implementation.md — Entry Gate (verbatim)

Source: .agents/tasks/implementation.md

## Phase Entry Gate [BLOCKING - SYSTEM HALT IF VIOLATED]

**CHECKPOINT: System CANNOT write ANY CODE until ALL boxes checked:**
☐ [VERIFIED] THIS FILE (`implementation.md`) has been READ and is active
☐ [VERIFIED] Task Tracking completed (from implementation.md Task Tracking Requirement)
☐ [VERIFIED] All required rules listed above are LOADED and active
☐ [VERIFIED] Work Plan document EXISTS with task definitions
☐ [VERIFIED] Task List contains ALL BLOCKING READs from this file
☐ [VERIFIED] Current task identified from Work Plan document
☐ [VERIFIED] TDD process understood (Red-Green-Refactor-Verify)
☐ [VERIFIED] SESSION_BASELINE_DATE established and active

**METACOGNITION GATE [MANDATORY]:**
BEFORE writing first line of code:
- Understand what needs to be built
- Verify approach follows existing patterns
- Confirm TDD cycle will be followed

Prompting technique: Checkbox verification list as a hard gate. The agent must produce explicit evidence (the filled checkboxes) before proceeding. This pattern makes the pre-condition verification visible in the output rather than implicit.


Prompt 3: AGENTS.md — Metacognition Checkpoints (verbatim)

Source: AGENTS.md

## Metacognition Checkpoints

Perform self-assessment at these mandatory points:
- Task type changes
- Unexpected errors occur
- Completing a meaningful unit of work
- Before starting new implementation
- After completing each task from work plan

Prompting technique: Mandatory self-monitoring injection at session start. The metacognition skill is the only skill that is required to remain active for the entire session (not unloaded after its task phase completes). This acts as a persistent meta-layer monitoring all other behavior.

09

Uniqueness

shinpr/agentic-code — Uniqueness

differs_from_seeds

The closest seed is superpowers — both use markdown skill files with mandatory compliance language and both enforce TDD. However, agentic-code differs in four architectural dimensions: (1) it ships a CLI scaffolding tool (npx agentic-code) while superpowers installs via Claude Code plugin marketplace; (2) it targets three AI tools (Cursor, Codex, Gemini CLI) via the AGENTS.md standard versus superpowers' single-tool (Claude Code) focus; (3) it uses progressive skill loading (load only what the current phase needs, then unload) versus superpowers' always-on skill activation; (4) its "Plan Injection" pattern (every BLOCKING READ must be listed in the work plan before execution) is more explicit than any seed's verification mechanism. The second-closest seed is agent-os — both are AGENTS.md/CLAUDE.md scaffold tools — but agent-os ships only 5 commands to write the markdown, while agentic-code ships 10 task definitions and 9+ skills with full TDD enforcement.

Positioning

Multi-tool AGENTS.md framework with progressive context management and aggressive gate enforcement. The AGENTS.md standard is its competitive moat — it abstracts over the differences between Codex, Cursor, and Gemini CLI.

Relationship to shinpr/codex-workflows

Agentic-code is the universal base; codex-workflows extends it with Codex-specific features: TOML subagent definitions (26 named subagents), recipe-based invocation via $recipe-name, and context isolation through separate agent sessions for large refactors. The README explicitly states "If you mainly use Codex, see codex-workflows for a more Codex-specific setup."

Observable Failure Modes

  1. Gate bypass: The AGENTS.md gates rely on the AI self-reporting compliance evidence. A model that generates plausible-looking checkboxes without actually verifying will pass all gates.
  2. Progressive loading overhead: For simple tasks, the AGENTS.md requires loading task-analysis.md before every task — adding latency for operations where experienced developers would act immediately.
  3. Cross-tool consistency: AGENTS.md compliance varies across Codex, Cursor, and Gemini. The framework assumes all three tools follow the same gate logic, but tool-specific behavior differences can lead to inconsistent results.
  4. SESSION_BASELINE_DATE fragility: If the agent fails to execute date at session start (e.g., in a sandboxed environment), all subsequent date references will use the training cutoff date silently.
04

Workflow

shinpr/agentic-code — Workflow

Scale-Based Routing

The framework's core routing mechanism is in task-analysis.md:

Scale Trigger Condition Path
Small 1-2 files, single task Load specific task definition → execute directly
Medium/Large 3+ files or complex feature Full workflow with approvals via agentic-coding.md

Phases + Artifacts (Medium/Large path)

Phase Key File Artifact
1. Session Setup AGENTS.md + metacognition/SKILL.md SESSION_BASELINE_DATE, metacognition active
2. Task Analysis task-analysis.md Scale determination, path selection
3. Requirements (if Large) prd-creation.md PRD document
4. Design technical-design.md Technical design doc
5. Acceptance Tests acceptance-test-generation.md Test skeletons
6. Work Planning work-planning.md Phased work plan with BLOCKING READs
7. Implementation implementation.md Code (TDD: Red → Green → Refactor → Verify)
8. Quality quality-assurance.md All quality checks pass (0 errors)
9. Review code-review.md Code review complete

Approval Gates

Gate Type Location
Workflow selection for medium/large tasks freetext-clarify AGENTS.md "Approval Points"
After design/decision documents file-review AGENTS.md
Technical approach changes freetext-clarify AGENTS.md
Task-definition specified stop points varies per task definition

TDD Enforcement

implementation.md requires:

  1. Load coding-rules/SKILL.md and testing/SKILL.md (BLOCKING if not loaded)
  2. Evidence confirmation block required before first line of code
  3. TDD cycle: Red (failing tests) → Green (implementation) → Refactor → Verify
  4. Session cannot start writing code without explicit "Skill Status Verification" evidence

Key Constraint: Plan Injection

Before any work begins, the work plan must contain EVERY BLOCKING READ from all loaded workflow/task/skill files. Any missing BLOCKING READ = IMMEDIATE HALT and return to task analysis.

06

Memory Context

shinpr/agentic-code — Memory and Context

State Storage

  • File-based: Work plans, design docs, and task files written to the project directory serve as external memory (e.g., docs/plans/ for codex-workflows; the agentic-code framework uses the .agents/ structure and user-specified paths).
  • SESSION_BASELINE_DATE: The current date retrieved at session start and stored in the agent's working memory (not persisted to disk) to ensure accurate date references throughout the session.
  • Context Maps: .agents/context-maps/ directory (present in the structure) provides project-specific context maps that agents can load to understand the project.

Persistence

  • Project-scoped: Work plans and design documents persist in the project directory for the duration of the feature.
  • No global state: No cross-project or cross-session persistence mechanism.

Progressive Skill Loading

The framework's key memory management mechanism: skills are loaded on demand as tasks require them, and unloaded after their task phase completes. Only metacognition remains permanently active. This limits the total prompt size by avoiding loading all 9+ skills simultaneously.

Compaction

Not explicitly handled. The progressive loading pattern implicitly reduces context size by loading only needed skill files per phase.

Cross-Session Handoff

Not supported natively. Work plans written to disk serve as informal handoff artifacts, but there is no built-in resume mechanism.

Memory Type

File-based, project-scoped.

07

Orchestration

shinpr/agentic-code — Orchestration

Multi-Agent

No. The base agentic-code framework is single-agent. All tasks are executed by the single AI reading the AGENTS.md and task/skill files. The sibling repo shinpr/codex-workflows adds subagent-based context isolation for large tasks.

Orchestration Pattern

Sequential. Task analysis → path selection → phase execution in order. No parallel fan-out.

Isolation Mechanism

None at the framework level (files are edited in-place). The related shinpr/codex-workflows extends this with Codex subagent context isolation.

Multi-Model

No. The framework is model-agnostic and designed to work with whatever model the user's chosen tool uses. It does not assign different models to different roles.

Execution Mode

Interactive-loop. The user requests a task, the agent reads AGENTS.md and relevant task/skill files, executes the workflow, and stops at gates for user approval.

Consensus Mechanism

None.

Codex Role

Worker / executor (one of three primary tools). Codex is not given a special planner or reviewer role — it is treated as an equivalent-rank coding agent alongside Cursor and Gemini CLI. The framework's value is the AGENTS.md standard that all three tools can consume.

Cross-Tool Portability

High. The AGENTS.md standard is explicitly designed to be tool-agnostic. Skills installed to ~/.codex/skills/ or ~/.cursor/skills/ use each tool's native skill discovery mechanism.

08

Ui Cli Surface

shinpr/agentic-code — UI and CLI Surface

Dedicated CLI Binary

Yes — agentic-code binary via npm.

Subcommand Purpose
<project-name> Scaffold new project directory with AGENTS.md + .agents/ tree
skills --codex Install skills to ~/.codex/skills/agentic-code/
skills --cursor Install skills to ~/.cursor/skills/agentic-code/
skills --cursor --project Install to ./.cursor/skills/agentic-code/ (project-scoped)
skills --codex --project Install to ./.codex/skills/agentic-code/
skills --path <dir> Install to custom path

The CLI is a thin scaffolding tool (Node.js bin/cli.js); it copies the template .agents/ tree and AGENTS.md into the target directory and handles skills installation path resolution.

Local UI

None.

IDE Integration

  • Cursor: skills installed to ~/.cursor/skills/ (requires Nightly release channel for skills feature)
  • Codex CLI: skills installed to ~/.codex/skills/
  • Gemini CLI: reads AGENTS.md automatically; no special install required
  • Other AGENTS.md tools: any tool that reads AGENTS.md works without extra install

Observability

  • Progress is visible through the agent's explicit checkpoint/evidence outputs mandated by the AGENTS.md gates (e.g., the "Skill Status Verification" block that must appear before implementation).
  • No structured logging or dashboards.

Cross-Tool Portability

High — the framework is explicitly designed to be portable via the AGENTS.md standard.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.