hasbrains-agent-kit

Universal, project-agnostic playbook for managing an ENTIRE project inside the repo's docs/ folder — the docs/-native system of record, reusable in any project, new or existing, with no external issue tracker. Defines WHAT it manages: the work-item TAXONOMY (Roadmap → docs/ROADMAP.md + docs/roadmap.json, PRD → docs/prd/, TRD → docs/trd/, Epic → docs/epics/, User Story → docs/user_stories/, Test Case → docs/test_cases/, Bug → docs/bugs/, per-session team reports → docs/sessions/, feature work-log → docs/reports/), the cross-document LINK GRAPH written as relative-markdown links (User Story part-of Epic; Test Case is-tested-by User Story; Bug blocks its story; PRD↔TRD), the YAML-frontmatter STATUS lifecycle + the bookend rule (transition status: forward before starting work, again when done), required frontmatter fields, the mandatory Test Case Template and the Bug+RCA report format, the TEAM WORK-REPORTING convention (one session folder per run; every agent bookends a start/completion report there + appends to

Four always-on engineering principles for ALL work before, during, and after coding — Think Before Coding (surface assumptions/tradeoffs, never guess silently), Simplicity First (minimum code that solves it, nothing speculative), Surgical Changes (touch only what the request needs, every changed line traces to the ask), and Goal-Driven Execution (define verifiable success criteria, loop until verified). Use on EVERY task that writes, edits, refactors, or fixes code, designs an approach, or interprets a request — not just large features.

Use when designing a system, choosing an architecture pattern, making a technology decision, or doing capacity/scalability planning — BEFORE drilling into framework-specific mechanics. A lean MAP over three reference docs: pattern selection (monolith → modular monolith → microservices → event-driven → CQRS → event sourcing → hexagonal → clean → API gateway, with trade-offs), the how-to system-design workflows (system-design-interview approach, capacity planning, API design, DB schema design, scalability assessment, migration planning), and the technology-choice frameworks (database, caching, message queue, auth, frontend framework, cloud provider, API style). Trigger on: 'design the system', 'choose an architecture pattern', 'which pattern fits', 'tech decision', 'SQL or NoSQL', 'REST vs GraphQL vs gRPC', 'capacity/scalability planning', 'plan the migration'. This is general system-design knowledge; for Phoenix bounded-context/Ecto/authz/Oban specifics use the architecture-phx skill.

Use when implementing any feature or bugfix, in any language or framework, before writing implementation code — write the test first, watch it fail, then write minimal code to pass. Covers the red-green-refactor loop, test-quality principles, rationalization counters, and test-layer selection.

Write high-performing social media content engineered around named copywriting frameworks, scroll-stopping hooks, and retention mechanics. For video it produces three coordinated outputs — the spoken DIALOGUE (voiceover), the VIDEO SCENARIO (timed two-column shot list with visual cues), and the EXPLANATION (notes on the frameworks, hook, and retention beats used) — plus standalone written posts for LinkedIn, X, Instagram, and YouTube. Use whenever the user wants a social post, a Reel/Short/TikTok script, a video scenario or shot list, a hook or hook bank, a content matrix, a Hub-and-Spoke repurposing plan, a VSL, or any short- or long-form distribution content. Trigger even on casual asks like "write me a Reel about X," "give me hooks for Y," "script a 30-second video," "make this go viral," "write a LinkedIn post," or "turn this into TikToks." Also trigger when the user wants retention engineered in (e.g. "keep them watching," "re-hook every N seconds," "high retention script").

Turn a skill or raw data into an AI-optimized "second brain" skill — a lean SKILL.md map backed by atomized, tagged references and JSON navigation maps. Analyzes the source, triple-checks, and writes a before/after improvement report.

Durable, file-backed pipeline handoff BUS for the WHOLE squad (all worker agents + el-capitan). Persists per-run variables, per-phase outputs, and `.ai_log/` evidence-PATH references to a PER-SESSION, git-ignored JSON file under `.ai_log/` (`.ai_log/session-<id>-<name>.json`, one per run) that survives context compression; cleans stale `.ai_log/` artifacts on init. On phase START, READ it to pull this phase's inputs (key fields + evidence paths); on phase COMPLETION, WRITE this phase's outputs (key result fields + `.ai_log/` paths — never large inlined blobs). The standing pattern (R17): evidence -> `.ai_log/`; references + key fields -> pipeline-state; handoffs = state lookups, not inlined dumps. Coexists with the docs/ reports (R7/R8, the human record) + the `.ai_log/` offload (R15). Originally built for the e2e-test-healer; now squad-wide. Use for ANY cross-phase handoff.

Expert prompt engineer that interviews users and builds high-quality prompts for any AI (Claude, Gemini, Copilot, ChatGPT, etc.). Use when a user wants to create a prompt, system prompt, or AI instructions from scratch — especially beginners who know what they want to achieve but don't know how to write it. Trigger on: "help me write a prompt", "make me a prompt for...", "I want AI to do X", "build me a system prompt", "how do I ask AI to...", "create instructions for...", or any time the user describes a goal they want an AI to accomplish. Always interviews the user before writing anything. Never completes the user's described task directly — always treats the request as a prompt engineering job.

The universal, tech-agnostic DESIGNER ↔ FRONTEND contract — how the web designer and the frontend dev help each other, where they store their shared data, how they communicate, and how the contract between them is written and ENFORCED. Three sides: the DESIGNER freezes an approved mockup into a canonical oracle (oracle-manifest.json + baseline renders + a region/element inventory + token parity + a four-part visual acceptance contract); the FRONTEND dev consumes that contract and PORTS the oracle 1:1 (transcribe, never redesign), self-gating census → DOM → pixel before handoff; the VERIFIER (design-diff) independently screenshots every built page × access state × breakpoint against the frozen baseline and reports per-page PASS/FAIL — report-only, a mismatch is a gate reject. Works on ANY stack (Phoenix/LiveView, Rails/Hotwire, React, …): stack facts (dev server, template language, settle signal, token source, seed accounts) are read at runtime from docs/project_config/info.md, never baked in. Use when: freezi