AI-DDTK - AI Driven Development ToolKit

Version: 1.0.5

Testing + Automation → Bugs → Fixes → Testing → Deploy

Overview

An early work in progress centralized toolkit for AI-driven WordPress development, designed to be called from any project.

At the center:

• VS Code AI Agents (Claude Code, Augment, Codex, etc.) with tuned system instructions
• MCP server integration for tool orchestration

Prerequisites

Requirement	Used By	Install
Git	Cloning AI-DDTK & WPCC updates	brew install git
Node.js	WP Code Check scanner	brew install node
Python 3	AI triage, HTML reports	brew install python3
Composer	PHPStan (optional)	brew install composer
GitHub CLI	Issue creation (optional)	brew install gh
Playwright	Browser automation (optional)	npm install -g playwright

Quick Start

# Clone to your bin directory
git clone https://github.com/Hypercart-Dev-Tools/AI-DDTK.git ~/bin/ai-ddtk
cd ~/bin/ai-ddtk

# Install (adds to PATH)
./install.sh

# Set up WP Code Check
./install.sh setup-wpcc

# Activate in current shell
source ~/.zshrc  # or ~/.bashrc

# Verify installation
wpcc --help

# (Optional) Set up temp folder structure for credentials, reports, etc.
# The folder structure is already created; this just shows what's available
ls temp/

Note: The /temp folder is for storing sensitive data (credentials, API keys, reports) that should never be committed to git. See temp/README.md for complete usage guidelines.

Usage from Any Project

# Run WPCC against a plugin
wpcc analyze ./wp-content/plugins/my-plugin

# Run WP-CLI via Local
local-wp my-site plugin list

Tools

Tool	Description
WP Code Check	Code review + AI triage with MCP server
WP AJAX Test	AJAX endpoint testing and validation
Fix-Iterate Loop	Autonomous test-verify-fix workflow for AI agents
local-wp	WP-CLI wrapper for Local by Flywheel
Playwright	Headless browser automation
PixelMatch	Visual regression testing

Repository Structure

AI-DDTK/
├── install.sh           # Install & maintenance script
├── bin/                  # Executable wrappers (added to PATH)
│   ├── wpcc             # WP Code Check wrapper
│   └── wp-ajax-test     # AJAX endpoint tester
├── tools/               # Embedded dependencies (git subtree)
│   ├── wp-code-check/   # WPCC source
│   └── wp-ajax-test/    # AJAX test tool source
├── recipes/             # Workflow guides (PHPStan, audits, etc.)
├── templates/           # Configuration templates
├── temp/                # Sensitive data storage (credentials, reports, logs)
│   ├── credentials/     # API keys, passwords, tokens
│   ├── reports/         # WPCC, PHPStan, performance reports
│   ├── data/            # Exports, imports, backups
│   ├── playwright/      # Playwright auth state
│   ├── logs/            # Debug logs
│   └── analysis/        # AI agent working files
├── local-wp             # Local WP-CLI wrapper
├── fix-iterate-loop.md  # Autonomous test-verify-fix pattern
├── AGENTS.md            # AI agent guidelines
└── CHANGELOG.md         # Version history

Maintenance Commands

./install.sh              # First-time setup
./install.sh update       # Pull latest AI-DDTK
./install.sh update-wpcc  # Pull latest WP Code Check
./install.sh status       # Show versions and status
./install.sh uninstall    # Remove PATH entries

For AI Agents

See install.sh for detailed guidance on:

• Git subtree operations for updating WPCC
• GitHub CLI commands for checking updates
• Architecture and maintenance notes

WPCC: Project Templates

Set up once, reuse forever. Templates save plugin/theme paths and scan settings so you can re-run audits with a single command.

# First time: auto-detects plugin name, version, and GitHub repo
wpcc run gravityforms
# → Template not found. Create from current directory? [y/N] y
# ✓ Created! Detected: Gravity Forms v2.7.1

# Every time after: one command runs the full workflow
# Ask AI: "Run gravityforms end to end"

That single command triggers the complete pipeline:

Scan → AI Triage → HTML Report → GitHub Issue
       (filters       (with AI        (with checkboxes,
       false           summary         ready for Jira/
       positives)      at top)         Linear/Asana too)

Templates handle flexible naming — Gravity Forms, gravity-forms, and gravityforms all resolve to the same config. See the Template Guide for details.

More WPCC Features

Feature	Description	How to Use
AI-Assisted Triage	Automated false positive detection	Ask AI: "Triage this scan" or "Run X end to end"
GitHub Issue Creation	Convert findings to trackable issues	Ask AI: "Create issue for scan"
IRL Audit Mode	Annotate real code for pattern library	See Audit Guide
Multi-Platform Export	Export issues to Jira, Linear, Asana, Trello	Issues saved to dist/issues/ for copy/paste

Quick Examples

# Basic scan (no template needed)
wpcc --paths ./wp-content/plugins/my-plugin --format json

# Show all available features and templates
wpcc --features

Full AI Instructions: WPCC AI Instructions

WordPress Development Guidelines

AI-DDTK includes comprehensive WordPress development guidelines in AGENTS.md for AI coding assistants.

🎯 Philosophy: Works Great by Default, Customizable for Experts

For beginners: Follow the patterns in AGENTS.md — they represent WordPress community best practices and will keep your code maintainable from day one.

For senior developers: The guidelines are Hypercart's opinionated defaults. Fork AGENTS.md and customize to match your team's standards.

What's Covered

Section	Type	Description
Security	Required	Nonces, sanitization, escaping, sensitive data handling
Performance	Required	Caching, query optimization, resource limits
WordPress APIs	Required	Hooks, filters, database access, WP-CLI
SOLID Principles	Opinionated	Architecture patterns with rationale and customization guidance
DRY & State Management	Opinionated	Helper patterns, single contract writers, FSM guidance
Scope Control	Opinionated	When to refactor, preservation vs. optimization trade-offs
Documentation	Opinionated	PHPDoc standards, versioning, CHANGELOG requirements
Testing	Opinionated	Backward compatibility, Fix-Iterate Loop pattern

Customization Examples

The guide includes team-specific customization examples for:

• Startups - Move fast, relax DRY requirements
• Enterprise - Strict documentation, lower FSM thresholds
• Open Source - Package tags, unit test requirements
• Agencies - Strict scope control, detailed changelogs
• Maintenance - Zero scope creep, preservation-first

See the full guide: AGENTS.md

Troubleshooting

wpcc: command not found — Reload your shell config, then retry:

source ~/.zshrc  # or ~/.bashrc

If that doesn't work, verify the install:

~/bin/ai-ddtk/install.sh status

WPCC not found or setup-wpcc needed — Run setup again:

cd ~/bin/ai-ddtk && ./install.sh setup-wpcc

WPCC stalls when scanning AI-DDTK itself — The repository includes embedded WPCC via git subtree. Use exclusions:

# Exclude embedded tools (recommended)
wpcc --paths . --exclude "tools/,.git/,node_modules/" --format json

# Or scan only specific directories
wpcc --paths "bin/ recipes/ templates/" --format json

Note: A .wpcignore file is included in the repository for future WPCC versions that support automatic exclusions.

License

Apache License 2.0 — see LICENSE and NOTICE for details.

The Fix-Iterate Loop methodology is licensed under CC BY 4.0.

Links

• WP Code Check
• IRL Audit Guide