AgentSpec Development

Spec-Driven Development framework for Data Engineering on Claude Code

Project Context

What is AgentSpec? A Claude Code plugin that provides structured AI-assisted development through a 5-phase SDD workflow, specialized for data engineering with 58 agents, 31 commands, 24 KB domains, and 21 skills (16 distributed in the plugin + 5 repo-local).

Component model (canonical: .claude/kb/shared/component-model.md):

New logic goes to the layer that owns it — the component-model skill walks the decision; the SDD workflow components are the reference implementation.

Current Status: v3.6.1 shipped (trust layer V0 for the built plugin, spec-driven agent creation pipeline + agent-architect, artifact scoring layer, github-review-pr repo-local review skill, single-source plugin.json version and release-branch flow). Linear is the project tracker (source of truth).

Repository Structure

agentspec/
├── .claude/                 # Claude Code integration
│   ├── agents/              # 58 specialized agents
│   │   ├── architect/       # 8 system-level design agents
│   │   ├── cloud/           # 10 AWS, GCP, cloud services, CI/CD
│   │   ├── platform/        # 6 Microsoft Fabric specialists
│   │   ├── python/          # 6 Python dev, code quality, prompts
│   │   ├── test/            # 3 testing, data quality, contracts
│   │   ├── data-engineering/ # 15 DE implementation specialists
│   │   ├── dev/             # 4 developer tools & productivity
│   │   └── workflow/        # 6 SDD phase agents
│   │
│   ├── commands/            # 31 slash commands
│   │   ├── workflow/        # SDD commands (7)
│   │   ├── data-engineering/ # DE commands (8)
│   │   ├── core/            # Utility commands (5)
│   │   ├── knowledge/       # KB commands (1)
│   │   ├── review/          # Review commands (2)
│   │   └── visual-explainer/ # Visual documentation commands (8)
│   │
│   ├── skills/              # 20 source skills: sdd-* phase skills + sdd-workflow umbrella,
│   │   │                    #   GitHub trio (github-cr-adr/-issue, github-post-issue) + github-review-pr*,
│   │   │                    #   authoring (component-model, create-skill*, create-agent*),
│   │   │                    #   kb-build, visuals (visual-explainer, excalidraw-diagram),
│   │   │                    #   agent-router, team comms (meeting-analysis*, standup-report*)
│   │   │                    #   (* = repo-local, excluded from the plugin; see docs/reference)
│   │
│   ├── sdd/                 # SDD framework
│   │   ├── architecture/    # WORKFLOW_CONTRACTS.yaml, ARCHITECTURE.md
│   │   ├── templates/       # 5 document templates (DE-aware)
│   │   ├── features/        # Active development
│   │   ├── reports/         # Build reports
│   │   └── archive/         # Shipped features
│   │
│   └── kb/                  # Knowledge Base (24 domains)
│       ├── _templates/      # 7 KB domain templates
│       ├── _index.yaml      # Domain registry
│       ├── shared/          # Cross-domain anti-patterns and conventions
│       ├── dbt/             # dbt patterns and concepts
│       ├── spark/           # PySpark, Spark SQL
│       ├── sql-patterns/    # SQL best practices
│       ├── airflow/         # DAG patterns
│       ├── streaming/       # Flink, Kafka, CDC
│       ├── data-modeling/   # Star schema, Data Vault, SCD
│       ├── data-quality/    # GE, Soda, observability
│       ├── lakehouse/       # Iceberg, Delta, catalogs
│       ├── cloud-platforms/ # Snowflake, Databricks, BigQuery
│       ├── ai-data-engineering/ # RAG, vector DBs, features
│       ├── modern-stack/    # DuckDB, Polars, SQLMesh
│       ├── aws/             # Lambda, S3, Glue, SAM
│       ├── gcp/             # Cloud Run, Pub/Sub, BigQuery
│       ├── microsoft-fabric/ # Lakehouse, Warehouse, Pipelines
│       ├── lakeflow/        # Databricks Lakeflow (DLT)
│       ├── medallion/       # Bronze/Silver/Gold architecture
│       ├── supabase/        # pgvector, RLS, Edge Functions, Auth
│       ├── prompt-engineering/ # Chain-of-thought, extraction
│       ├── genai/           # Multi-agent systems, guardrails
│       ├── pydantic/        # Validation, LLM output schemas
│       ├── python/          # Python patterns and idioms
│       ├── testing/         # pytest, fixtures, CI testing
│       └── terraform/       # IaC modules, state, workspaces
│
├── docs/                    # Documentation
│   ├── getting-started/     # Installation and first pipeline
│   ├── concepts/            # SDD pillars through DE lens
│   ├── tutorials/           # dbt, star schema, Spark, streaming tutorials
│   └── reference/           # Full catalog: agents, commands, KB domains
│
├── plugin/                  # Generated plugin (built by build-plugin.sh)
│   ├── .claude-plugin/      # Plugin manifest + marketplace config
│   ├── agents/              # Copied + path-rewritten agents
│   ├── commands/            # Copied + path-rewritten commands
│   ├── skills/              # 16 skills (15 from .claude/ + 1 plugin-only; repo-local excluded)
│   ├── kb/                  # Copied KB domains
│   ├── sdd/                 # Templates + architecture (no features/reports/archive)
│   ├── hooks/               # SessionStart workspace init
│   └── scripts/             # init-workspace.sh
│
├── plugin-extras/           # Plugin-only content (merged into plugin/ by build)
│   ├── skills/              # data-engineering-guide
│   ├── hooks/               # hooks.json
│   └── scripts/             # init-workspace.sh
│
├── Makefile                 # Developer entry point — `make help` lists all targets
├── build-plugin.sh          # Builds plugin/ from .claude/ (invokes scripts/generate-agent-router.py)
├── scripts/                 # Build tooling (not shipped in plugin)
│   ├── generate-agent-router.py  # Regenerates agent-router SKILL.md + routing.json from agent frontmatter
│   └── judge.py             # Judge V0: OpenRouter second opinion (backend for /judge command)
├── tests/                   # pytest suite (27 tests) — `make test`
├── .shellcheckrc            # Lint config for shell scripts
├── CHANGELOG.md             # Version history
├── CONTRIBUTING.md          # Contribution guide
├── SECURITY.md              # Security policy
└── README.md                # Project overview

Development Workflow

Use AgentSpec's own SDD workflow to develop AgentSpec:

# Explore an enhancement idea
/brainstorm "Add Judge layer for spec validation"

# Capture requirements
/define JUDGE_LAYER

# Design the architecture
/design JUDGE_LAYER

# Build it
/build JUDGE_LAYER

# Ship when complete
/ship JUDGE_LAYER

Data engineering example:

# Design a star schema
/schema "Star schema for e-commerce analytics"

# Scaffold a pipeline
/pipeline "Daily orders ETL from Postgres to Snowflake"

# Generate quality checks
/data-quality models/staging/stg_orders.sql

Active Development Tasks

Coding Standards

Markdown Files

• ATX-style headers (#, ##, ###)
• Fenced code blocks with language identifiers
• Tables properly aligned

Agent Prompts

• Specific trigger conditions
• Clear capabilities list
• Concrete examples
• Defined output format
• kb_domains field for DE agents

KB Domains

• index.md - Domain overview
• quick-reference.md - Cheat sheet
• concepts/ - 3-6 concept files
• patterns/ - 3-6 pattern files with code examples

Commands Available

SDD Workflow (7)

Data Engineering (8)

Core & Utilities (8)

Visual Explainer (8)

Key Files to Know

Version

• Version: 3.6.1
• Status: Release
• Last Updated: 2026-10-11