using-avid

Files (3)

• SKILL.md
• codex-tools.md · references/
• opencode-tools.md · references/

SKILL.md (first lines)

# Using AVID

You have the **avid-skill** plugin: a **personal product-engineering workflow**, not a replacement for official tools (Tavily, Context7, Playwright, Matt Pocock skills, Impeccable, taste-skill, etc.).

AVID exists to reduce blind builds and wrong defaults. It does **not** exist to force one stack/runtime into every project.

## Priority

1. **User's explicit instructions** — always highest  
2. **Scene fit / technical reality** — invalid defaults must be dropped (e.g. Pi on pure web FE/BE)  
3. **AVID suggested defaults** — prefer when they fit  
4. **Claude Code process:** Matt Pocock skills (not Superpowers) + **ponytail** when coding  
5. Default system behavior  

## How to apply (important)

- Treat the table below as **recommended**, not court orders.
- When a skill fits: load it and follow the useful parts.
- When it doesn't: **skip or adapt**, and say one line why (scene mismatch / user override / cost).
- Never "comply" into a catastrophic wrong architecture just to satisfy a checklist.
- Tiny fixes, refactors, and already-scoped product work: no need to run bootstrap theater.

## Suggested routing

| Situation | Suggested skill | Notes |
|-----------|-----------------|-------|
| New product / new vertical / greenfield | `product-bootstrap` | Strongly recommended; still skippable if user already has research/spec |
| About to self-build a capability | `research-before-build` | Prefer find-before-found |
| Missing installable tool | `install-dont-reinvent` | Prefer install; hand-roll only with reason |
| Stack choice | `stack-defaults` | Defaults with easy exceptions |
| Agent runtime | `agent-framework-choice` | **Scene-based** — see below |
| Knowledge / RAG | `knowledge-architecture` | Clarify consumers first |
| High-stakes decision | `multi-agent-deliberation` | Optional second opinions |

## Agent runtime — scene fit (do not hard-force Pi)

| Scene | Prefer | Avoid forcing |
|-------|--------|----------------|
| Web FE/BE product, API, SaaS UI | Thin LLM SDK / server agent framework as needed; often **LangGraph** only if workflow/HITL graph is real | **Pi SDK as default** — wrong shape for normal web apps |
| Local coding / desktop / Electron / workspace harness agent | **Pi** family: Pi SDK, pi-ai, or embed/use Pi agent runtime — pick what docs + product need | LangGraph cargo-cult for a simple tool loop |
| Multi-step business workflow, durable state, HITL approvals | **LangGraph** + langgraph skills/docs | Pi-as-graph |
| "Just chat + a few tools" | Official provider SDK loop first | Heavy frameworks |

Always: fresh docs (Context7 / official) before coding on a chosen framework.

**Model API protocol (when building agents):** prefer **OpenAI Chat Completions** (`/v1/chat/completions`) for multi-model / gateway / Pi `openai-completions` compatibility. Treat Responses / Anthropic Messages as optional vendor paths — not the only P0 protocol unless the product is single-vendor by design. See `agent-framework-choice`.

## Tool defaults (prefer official tools)

| Need | Prefer |
|------|--------|
| Web research | Tavily |
| Vertical search | AnySearch |
| Lib docs | Context7 |
| Browser QA | Playwright |
| Email / pay / data | Resend / Stripe / SQLite→Postgres(Supabase) **when they fit** |
| Agent LLM wire protocol | **Chat Completions** first (multi-provider) |
| Minimal code | ponytail |
| Process (Claude Code) | **Matt Pocock skills** (`grill-me` / `grill-with-docs` → `to-spec`/`to-tickets` → `implement`/`tdd`/`code-review`) — **not Superpowers** |
| Frontend UI | **Impeccable + taste-skill** (`design-taste-frontend`) together — taste for direction/anti-slop; Impeccable for craft/audit/polish |

## Frontend pair (advisory)

- Non-trivial UI: load **both** `design-taste-frontend` (taste) and **Impeccable** (`/impeccable …`), not only one.
- Optional direction skills (`high-end-visual-design`, etc.) when the aesthetic is already chosen.
- shadcn / component libs remain implementation tools under that pair.

## Anti-patterns

- Blind build with zero market scan on a **new product** when research is cheap  
- Forcing Pi SDK because "AVID says harness → Pi" on a web platform where it doesn't apply  
- Forcing LangGraph on a trivial tool loop  
- Silent hand-roll of a mature hosted service without a reason  
- Ritual checklists that block a clearly scoped hotfix  
- Using **Superpowers** as the CC engineering methodology (superseded by Matt Pocock skills)  
- Shipping UI with only Impeccable **or** only taste when both are available  

## After planning

Prefer minimal implementation (ponytail); on Claude Code prefer Matt Pocock process skills when they fit. Bias to P0. User can always say "skip AVID for this" — obey.

From AVIDS2/avid-skill, MIT.

More from AVIDS2/avid-skill