End to end feedback

[noelsaw1]

Here's my full feedback as a mid-level WP developer trying AI-DDTK for the first time:

---

First Impressions & Findings

README.md

The README is well-structured and informative. The "What's Inside" table, "Everyday Workflows" section, and "Hidden Gems" are genuinely helpful. However, there are friction points:

1. macOS-only messaging is buried and confusing. Line 32 says "macOS required" but then immediately says core scanning works on any Unix. A new user on Linux/WSL would wonder "can I use this or not?" — the answer is mostly yes, but the framing implies no.
2. The clone URL assumes ~/bin/ai-ddtk but the repo is named AI-DDTK (uppercase). A new user who git clones will get ~/bin/AI-DDTK and then source ~/.zshrc won't resolve wpcc because the PATH was set with the actual clone directory. This is fine if you clone to the right place, but the mismatch between repo name and install path could trip people up.
3. "Hidden Gems" is great for retention but bad for discoverability. If a feature is valuable enough to highlight in the README, it's valuable enough to mention in --help output or in the main "What's Inside" table.
4. No "What is MCP?" explanation. The README assumes familiarity with Model Context Protocol. A mid-level WP dev who uses Cursor or VS Code may not know what MCP is. One sentence would help.

AGENTS.md

This file is comprehensive but overwhelming for a human reader. It's clearly written for AI agents, and it does that job well. The orchestration logic (workflow triggers table, MCP vs. shell strategy, Fix-Iterate Loop guardrails) is clear. But:

1. The file serves dual duty as agent instructions AND human reference. The "Getting Started" section mixes agent-oriented commands (cat ~/bin/ai-ddtk/AGENTS.md) with human-oriented context. It would benefit from clearly separating "for AI agents" vs. "for humans."
2. The Workflow Triggers table is excellent for agents but invisible to humans who won't read a 500-line agent file.

Install Script

The install ran successfully end-to-end on this Linux environment. Observations:

1. local-wp --help silently crashes (exit 1, zero output). Root cause: set -e plus PHP_BIN="${PHP_BIN:-$(detect_php_bin)}" on line 79. When detect_php_bin returns 1 (no macOS Local app dirs), set -e kills the whole script. A brand-new user running local-wp --help to learn the tool sees nothing — this is a terrible first experience.
2. wpcc --help emits a bash parse error before showing output: pattern-loader.sh: line 657: warning: here-document at line 397 delimited by end-of-file (wanted 'EOFPYTHON'). The help still renders, but the error is alarming and looks broken.
3. The post-install "Next steps" block is good and copy-paste friendly.
4. ./install.sh status is excellent — tells you exactly what's working and what isn't.

Overall Clarity

I understood what this toolkit does after reading the README, but I had to read AGENTS.md to figure out how to actually use it with my AI editor. The "When to use which?" decision tree callout in the README is great. The Fix-Iterate Loop doc is clear, well-structured, and genuinely useful.

Biggest blocker: local-wp being completely broken on non-macOS. Not just "doesn't work" — silently crashes with no error message.

---

Actionable Feedback Checklist (Ranked by Severity)

#	Issue	Severity	Risk	Effort
1	local-wp --help silently crashes on non-macOS — set -e + detect_php_bin returning 1 kills the script with zero output. Users get no help text, no error message. Fix: change line 79 to `PHP_BIN="${PHP_BIN:-$(detect_php_bin		true)}"`	Critical
2	wpcc emits bash parse errors on every invocation — pattern-loader.sh has an unclosed here-document (EOFPYTHON). Output still works but the error scares users and looks like a broken install.	High	Medium — functional but erodes trust	Medium (debug the heredoc in pattern-loader.sh)
3	No explanation of MCP for non-AI-native users — README assumes readers know what Model Context Protocol is. Add 1-2 sentences: "MCP (Model Context Protocol) lets AI coding assistants call toolkit commands directly instead of pasting shell commands."	Medium	Medium — confuses the target audience (WP devs adopting AI tools)	Low (2 sentences)
4	macOS-only framing is misleading — "macOS required" at the top scares away Linux/WSL users even though wpcc, MCP server, and tmux all work fine. Reframe: "Full feature set on macOS; core scanning + MCP works on any Unix-like system."	Medium	Medium — loses potential Linux/WSL users at first glance	Low (reword 2 lines)
5	local-wp shows zero output on missing Local environment — even after the set -e fix, local-wp --list and local-wp <site> silently fail when Local by Flywheel isn't installed. Should print: "Local by Flywheel not detected. This tool requires Local. See https://localwp.com"	Medium	Medium — confusing UX on any non-macOS or non-Local setup	Low (add a guard + message)
6	AGENTS.md mixes human and agent audiences — the file is titled "for AI Agents" but the Getting Started section is written for humans. Either split the audiences or add a clear "For Humans: start here" vs. "For Agents: start here" heading.	Low	Low — agents handle it fine; humans may skip the file entirely	Low (restructure headings)
7	"Hidden Gems" features should be surfaced in tool help — LOCAL_WP_MEMORY_LIMIT, install.sh maintenance commands, and the QM bridge are buried. At minimum, local-wp --help should mention LOCAL_WP_MEMORY_LIMIT and install.sh --help should list doctor-playwright.	Low	Low — users miss useful features	Low (add lines to help output)
8	Clone path mismatch — README says git clone ... ~/bin/ai-ddtk but the GitHub repo name is AI-DDTK. If a user does a bare git clone without the target path, they get ~/AI-DDTK/ and the PATH entry won't match. Consider noting this explicitly or adding a post-clone path check in install.sh.	Low	Low — only affects users who deviate from instructions	Low (add a note)
9	install.sh hardcodes doctor-playwright but it's not in the help output — ./install.sh --help shows the command but ./install.sh doctor-playwright requires pw-auth args that aren't explained in the help text.	Low	Low — minor discoverability gap	Low (add example to help)
10	CHANGELOG has 5 entries all dated 2026-03-24 — rapid same-day versioning (1.2.0 through 1.2.4) makes it hard to tell what's stable. Consider batching same-day changes into fewer versions.	Info	Very Low — cosmetic	Low