Imported from FocusedDiversity/industry-specific-aiq-app (AGENTS.md). Install upstream with npx skills add FocusedDiversity/industry-specific-aiq-app. Copyright stays with the author.

AI Agent Instructions for Industry-Specific AIQ App

Project Overview

This is an Industry-Specific AIQ (AI Quotient) Assessment application - a lead magnet tool for Synaptiq targeting directors+ in Healthcare and Legal industries to assess AI maturity, deliver insights, and funnel qualified prospects into sales.

Issue Tracking with bd (beads)

IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

Why bd?

• Dependency-aware: Track blockers and relationships between issues
• Git-friendly: Auto-syncs to JSONL for version control
• Agent-optimized: JSON output, ready work detection, discovered-from links
• Prevents duplicate tracking systems and confusion

Quick Start

Check for ready work:

bd ready --json

Create new issues:

bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask (gets ID like epic-id.1)

Claim and update:

bd update bd-42 --status in_progress --json
bd update bd-42 --priority 1 --json

Complete work:

bd close bd-42 --reason "Completed" --json

Issue Types

• bug - Something broken
• feature - New functionality
• task - Work item (tests, docs, refactoring)
• epic - Large feature with subtasks
• chore - Maintenance (dependencies, tooling)

Priorities

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (default, nice-to-have)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Workflow for AI Agents

1. Check ready work: bd ready shows unblocked issues
2. Claim your task: bd update <id> --status in_progress
3. Work on it: Implement, test, document
4. Discover new work? Create linked issue:
   • bd create "Found bug" -p 1 --deps discovered-from:<parent-id>
5. Complete: bd close <id> --reason "Done"
6. Commit together: Always commit the .beads/issues.jsonl file together with the code changes so issue state stays in sync with code state

Auto-Sync

bd automatically syncs with git:

• Exports to .beads/issues.jsonl after changes (5s debounce)
• Imports from JSONL when newer (e.g., after git pull)
• No manual export/import needed!

Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:

• Store ALL AI-generated planning/design docs in history/
• Keep the repository root clean and focused on permanent project files
• Only access history/ when explicitly asked to review past planning

CLI Help

Run bd <command> --help to see all available flags for any command. For example: bd create --help shows --parent, --deps, --assignee, etc.

Important Rules

• Use bd for ALL task tracking
• Always use --json flag for programmatic use
• Link discovered work with discovered-from dependencies
• Check bd ready before asking "what should I work on?"
• Store AI planning docs in history/ directory
• Run bd <cmd> --help to discover available flags
• Do NOT create markdown TODO lists
• Do NOT use external issue trackers
• Do NOT duplicate tracking systems
• Do NOT clutter repo root with planning documents

Tech Stack

• Frontend: Next.js/React with Tailwind CSS
• Backend: Firebase Cloud Functions (Node/TypeScript)
• Hosting: Firebase Hosting
• CRM Integration: HubSpot API
• Content Management: JSON/YAML configs

Key Files

• history/industry-specific-aiq-app-plan.md - Product planning document
• history/pie-chart-links.tsx - Reference donut chart component
• history/prompts/ - Writing style and persona guidelines

Voice & Style

All content should follow the "Raise Your AIQ" Magician/Sage/Creator style addressing the Enterprise Innovation Leader persona. See history/prompts/ for guidelines.