You know the feeling. You ask the AI to build a feature, and it writes 300 lines of flat, generic UI, introduces a subtle security flaw, and burns through your entire token budget re-reading files.

AdGhost Lily puts a stop to that. It is not just a prompt; it is an operating system backed by executable Python scripts that enforce quality by failing git pre-commit hooks and verification gates.

Why Lily?

• Enforced by Scripts: Python scripts (security-gate.py, check-ui-slop.py, check-minimal-diff.py) run via git hooks. If the AI uses an emoji instead of a Lucide icon, or overbuilds a 1-line bug fix, the gate fails and the Reflection Loop forces it to fix it.
• Zero-Command UX: You don't need to remember slash commands. Plain English ("make a feature", "is this secure?") automatically routes to the correct Lily pipeline.
• Token-Lean Architecture: Uses <tldr> progressive disclosure. Lily is designed to read 1-line summaries of references first instead of loading whole files, minimizing context window usage.
• Pro UI/UX Engine: 14 categories of expert design rules (60-30-10 color theory, 4-point grids, nested border radius math) are enforced by check-ui-slop.py to kill "vibe-coded" AI slop.
• Self-Improving (Approval-Gated): Learns from your corrections. The /lily evolve command audits past sessions and proposes a diff to optimize its own rulebook for your approval.
• Parallel Orchestration: Automatically detects large tasks and proposes spawning isolated sub-agents with disjoint file scopes to build different parts of the app simultaneously.

How it works

Before writing code, Lily runs a Sequential Intake to pin the exact stage and ask one high-leverage question. It then reuses existing code, uses stdlib, and writes the smallest safe diff.

1. Sequential Intake       -> Pin stage, ask ONE question if ambiguous.
2. Minimal-Diff Discipline -> Reuse existing -> stdlib -> dependency -> one-liner.
3. Build & Enforce         -> Write code, run gates (verify, secure, ui-slop).
4. Reflection Loop         -> If gate fails: root cause -> 2 fixes -> apply -> retry.
5. Handoff                 -> Save decisions to .memory/ for next session.

Lazy, not negligent: trust-boundary validation, data-loss handling, security, and accessibility are never on the chopping block.

Install

The most effort Lily will ever ask of you:

npx adghost-lily

Run this in your project root. The installer is data-loss safe: it never overwrites a file that already exists (your CLAUDE.md / config is untouched). Pass --force to update Lily in place.

What npx adghost-lily installs

The installer copies the shared runtime plus a native adapter per agent (it never overwrites files you already have):

| Agent | Adapter it installs | |---|---| | Claude Code | .claude/ (skill + rules) and CLAUDE.md | | Cursor | .cursor/ (skill + rules) | | Codex / AGENTS.md | .codex/ and AGENTS.md | | Gemini CLI | GEMINI.md | | Antigravity | ANTIGRAVITY.md | | Windsurf | .windsurfrules |

Shared by every agent: skills/, references/, templates/, prompts/, scripts/, and a seeded .memory/.

Adapters for Cline, Roo, Continue, GitHub Copilot, and Aider also live in the repo (.clinerules/, .roo/, .continue/, .github/, .aider.conf.yml) — clone the repo to use those; they are not part of the npx install.

Commands (Zero-Command Auto-Routed)

You can just talk to Lily in plain English, but these explicit commands are available:

| Command | What it does | |---------|--------------| | /lily doctor | Self-check: is Lily installed correctly? (Scores 100/100 on a clean install) | | /lily audit repo | Comprehensive audit: security, structure, frontend, backend, UI. | | /lily secure | OWASP-mapped security gate: 8 rows incl. optional Semgrep deep SAST. | | /lily verify | Run project lint/typecheck/test/build. Prove "done". | | /lily fix-one | Fix the single highest-priority approved issue. | | /lily prp | Generate a Product Requirements Plan before coding. | | /lily feature | Full pipeline: spec → PRP → build → verify → debt markers → handoff. | | /lily bug | Root-cause-first debugging (Iron Law: no fix without a named cause). | | /lily simplify | Over-engineering audit: what to delete / replace with stdlib / shrink. | | /lily debt | Ledger of every deliberate shortcut left in the code. | | /lily ts | TypeScript diagnostics gate (tsc --noEmit). | | /lily arch | Repo architecture gate: import cycles, layer direction, god files, orphans. | | /lily ship | Production GO/NO-GO: all gates chained into one verdict. | | /lily caveman | Compressed replies, ~65% fewer output tokens, substance intact. | | /lily evolve | Audit past sessions and propose self-improvements for approval. | | /lily handoff | Save state to .memory/ for the next session. |

How Lily compares (honest)

| Capability | Lily | addyosmani/agent-skills (~60k★) | |---|---|---| | Output contract | Status line + Proof + check-execution-form.py grader + always-on rule | Per-skill workflows; verify in prose | | Security | 7 Python scanners + write-time hook + pre-commit block | security-and-hardening skill (prompt-led) | | Memory / continuity | .memory/ + auto journal hooks + instincts | Varies by skill | | UI/UX depth | 10 merged skills + Playwright CLI + anti-slop detectors | frontend-ui-engineering skill | | Multi-IDE | Cursor · Claude · Codex · Antigravity copies + hooks | Cursor · Claude · Antigravity docs | | Token discipline | Fast-path · write-only memory · max 1–2 refs | Load skill on demand | | Lifecycle breadth | 20-stage router + 80+ references | 24 phase skills |

Lily's edge: executable gates (not prompt-only), defensive security depth, enforced plain-English owner output, existing-repo recovery, and an approval-gated self-improvement loop.

Gap vs agent-skills: fewer named lifecycle skills (they ship 24; Lily routes via Stage Router) — install upstream for niche workflows. Lily's enforcement (gates, grader, hooks) is the differentiator.

FAQ

Does it need a config file? No. Lily reads the .memory/ folder and project files automatically.

What if I really need the 120-line utility class? Lily will block it if you commit it as a fix:. Commit it as a feat: or refactor: and the minimal-diff gate will let it pass.

Does it scale? The token discipline (<tldr> headers, max 1-2 references loaded) keeps Lily fast even in massive codebases.

Attributions

Lily ingests and compresses concepts from several great open-source projects. See NOTICE.md for full attributions (including ECC, Ponytail, shadcn/improve, and Impeccable).

License

Apache-2.0.

Star History