observability

Agentic Primitives

Atomic building blocks for AI agent systems

---

What Are Agentic Primitives?

Atomic building blocks for AI agent systems — packaged as Claude Code plugins and Python libraries.

Designed to work in two contexts:

• Human-in-the-loop — a developer using Claude Code in the terminal, invoking commands explicitly, staying in control
• Headless workspaces — fully automated agents running in isolation with no human present, where tool scoping and policy hooks are the safety layer

The same primitives serve both. The difference is configuration: which tools are allowed, which hooks fire, which agents are trusted.

---

The Primitives

Commands

Explicit user-invocable slash commands (/sdlc:git_push). Granular, predictable, human-triggered. The developer stays in the loop.

→ Lives in: plugins/<plugin>/commands/<name>.md

Skills

Reusable workflows Claude invokes automatically when a task matches the description — or that you invoke as /sdlc:git. Consolidated, intent-driven, works in both human and headless contexts.

→ Lives in: plugins/<plugin>/skills/<name>/SKILL.md

Agents

Named specialist subagents with a scoped system prompt, explicit allowed/disallowed tools, and optional persistent memory. The tool scope is the key primitive — it determines what an agent can do, not just what it should do. Agents can preload skills and delegate to other agents via the Task tool.

→ Lives in: plugins/<plugin>/agents/<name>/agent.md

Hooks

Event-driven automation that fires on Claude Code lifecycle events (PreToolUse, PostToolUse, SubagentStop, SessionStart, etc.). Observe, modify, or block — enforcing policies and emitting telemetry without touching workflow code.

→ Lives in: plugins/<plugin>/hooks/hooks.json + handlers

Lib

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

→ Lives in: lib/python/

---

How They Compose

User: /sdlc:git_push          ← Command (explicit, human-in-loop)
  or
Claude detects push needed    ← Skill (auto-invoked, headless-friendly)
       │
       ├─► PreToolUse Hook validates git commands before execution
       │
       ├─► Skill delegates review to env-reviewer Agent (Task tool)
       │         ├─ tools: Read, Grep, Glob only (cannot modify anything)
       │         ├─ disallowedTools: Write, Edit (enforced, not just instructed)
       │         └─ SubagentStop Hook records telemetry
       │
       └─► PostToolUse Hook emits structured JSONL event (Lib: agentic-events)

The pattern:

• Commands give humans direct control at the right granularity
• Skills orchestrate work for agents — consolidated, intent-driven
• Agents specialize with enforced tool scopes — least privilege by design
• Hooks enforce policies and observability without touching workflow code
• Lib provides the runtime substrate — isolation, events, structured logging

---

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