Agentic Primitives

Atomic building blocks for AI agent systems

---

What Are Agentic Primitives?

This repository contains two kinds of primitives for building AI agent systems:

Prompt Primitives

Reusable prompts deployed as Claude Code plugins — commands, skills, hooks, and tools that agents use during software development.

Infrastructure Primitives

Python packages that power agent execution — isolation, security, events, logging, adapters, and settings. Used by the Agentic Engineering Framework (AEF) as its foundation.

---

Quick Start

Prerequisites

• Python 3.11+
• uv — fast Python package manager
• just — command runner (optional, recommended)

Install Plugins

Plugins are installed via Claude Code's built-in plugin system. Requires Claude Code v1.0.33+.

You can also do all of this interactively by typing /plugin inside Claude Code.

1. Add the marketplace (one-time setup):

claude plugin marketplace add AgentParadise/agentic-primitives

2. Install the plugins you need:

# Install globally (available in all projects)
claude plugin install sdlc@agentic-primitives --scope user

# Or install to current project only
claude plugin install sdlc@agentic-primitives --scope project

3. Update to the latest version:

# Refresh the marketplace catalog first
claude plugin marketplace update agentic-primitives

# Then update the plugin
claude plugin update sdlc@agentic-primitives

Plugins are pinned to a version and never auto-update. Updates require both steps above.

4. Disable / enable without uninstalling:

claude plugin disable sdlc@agentic-primitives
claude plugin enable sdlc@agentic-primitives

5. Uninstall:

claude plugin uninstall sdlc@agentic-primitives

6. Verify security hooks are active:

# Inside a Claude Code session, run:
/sdlc:validate_security-hooks

Replace sdlc with any plugin name (workspace, research, meta, docs) in the commands above.

---

Available Plugins

Plugin	Install	Description
sdlc	claude plugin install sdlc@agentic-primitives --scope user	Software Development Lifecycle
workspace	claude plugin install workspace@agentic-primitives --scope user	Observable isolated workspaces
research	claude plugin install research@agentic-primitives --scope user	Information gathering
meta	claude plugin install meta@agentic-primitives --scope user	Primitive generators
docs	claude plugin install docs@agentic-primitives --scope user	Documentation tools

What's in each plugin

Plugin	Commands	Skills	Hooks
sdlc	git_push, git_merge, git_merge-cycle, git_fetch, git_worktree, git_set-attributions, review, validate_security-hooks	commit, testing-expert, pre-commit-qa, qa-setup, prioritize, centralized-configuration, macos-keychain-secrets	PreToolUse security validators, UserPromptSubmit PII detection, git hooks
workspace	--	--	Session lifecycle, tool observability, structured JSONL event emission
research	scrape_docs	--	--
meta	/create-command, /create-prime, /create-doc-sync	prompt-generator	--
docs	--	Fumadocs integration	--

---

Python Packages

Infrastructure primitives in lib/python/, installable via pip or uv:

Package	Version	Description
agentic-isolation	0.3.0	Docker workspace sandboxing for agent execution
agentic-events	0.1.0	Zero-dependency JSONL event emission
agentic-logging	0.1.0	Structured logging for agents and humans

# Install a package for development
cd lib/python/agentic_isolation
uv sync --all-extras

# Run tests
uv run pytest -x -q

---

Repository Structure

agentic-primitives/
├── plugins/                    # Prompt Primitives
│   ├── sdlc/                   #   SDLC plugin (commands, skills, hooks)
│   ├── workspace/              #   Workspace observability hooks
│   ├── research/               #   Research tools (firecrawl, doc-scraper)
│   ├── meta/                   #   Primitive generators
│   └── docs/                   #   Documentation tools
├── lib/python/                 # Infrastructure Primitives
│   ├── agentic_isolation/      #   Docker workspace sandboxing
│   ├── agentic_events/         #   JSONL event emission
│   └── agentic_logging/        #   Structured logging
├── providers/                  # Workspace providers & model data
│   ├── workspaces/claude-cli/  #   Claude CLI Docker workspace
│   ├── models/                 #   Model cards (pricing, context windows)
│   └── agents/                 #   Agent configuration templates
├── scripts/                    # QA runner, benchmark tools
├── tests/                      # Integration & unit tests
├── docs/adrs/                  # Architecture Decision Records (32 ADRs)
├── VERSION                     # Repo version (3.0.1)
└── justfile                    # Task runner (just --list)

---

Development

# Initialize environment
just init

# Run all tests
just test

# Run QA (format check + lint + test)
just qa

# Auto-fix formatting and lint issues
just qa-fix

# Run full CI pipeline
just ci

Docker Workspace Images

# Build Claude CLI workspace image
just build-workspace-claude-cli

# List available providers
just list-providers

---

Architecture Decision Records

This project's design decisions are documented in 13 ADRs, including:

• ADR-020: Agentic Prompt Taxonomy
• ADR-025: Just Task Runner
• ADR-027: Provider Workspace Images
• ADR-029: Simplified Event System
• ADR-033: Plugin-Native Workspace Images

---

License

MIT