@forwardimpact/map 0.11.0

package/examples/capabilities/delivery.yaml

@@ -0,0 +1,1001 @@
+# yaml-language-server: $schema=https://www.forwardimpact.team/schema/json/capability.schema.json
+
+id: delivery
+name: Delivery
+emojiIcon: 🚀
+ordinalRank: 3
+description: |
+  Building and shipping solutions that solve real problems.
+  Encompasses full-stack development, data integration, problem discovery,
+  and rapid prototyping.
+professionalResponsibilities:
+  awareness:
+    You complete assigned implementation tasks within established patterns with
+    guidance from senior engineers
+  foundational:
+    You deliver small features end-to-end with minimal guidance, understanding
+    how your code fits the broader system
+  working:
+    You own feature delivery from design through deployment, making sound
+    technical trade-offs to ship value on time
+  practitioner:
+    You lead technical delivery of complex projects across multiple teams,
+    unblock others through hands-on contributions, and ensure engineering
+    quality
+  expert:
+    You drive delivery of the most critical technical initiatives, establish
+    engineering delivery practices across the business unit, and are the
+    technical authority on high-stakes projects
+managementResponsibilities:
+  awareness:
+    You track team progress and communicate status to stakeholders with guidance
+  foundational:
+    You coordinate team delivery by managing dependencies, removing blockers,
+    and keeping stakeholders informed
+  working:
+    You own team delivery outcomes—balance scope, staffing, and timeline; make
+    resourcing decisions to meet commitments
+  practitioner:
+    You drive delivery excellence across multiple teams, establish delivery
+    metrics and practices for your area, hold teams accountable, and escalate
+    cross-team risks
+  expert:
+    You shape delivery culture across the business unit, lead strategic delivery
+    transformations, and represent delivery commitments at executive level
+skills:
+  - id: data_integration
+    name: Data Integration
+    human:
+      description:
+        Gaining access to enterprise data, cleaning messy real-world datasets,
+        and making information usable for decision-making—often with
+        inconsistent formats, missing values, and undocumented schemas. The
+        heart of embedded engineering work.
+      proficiencyDescriptions:
+        awareness:
+          You understand how data flows through systems and can use existing
+          pipelines, APIs, and data sources with guidance. You know to ask about
+          data quality.
+        foundational:
+          You create simple data transformations and handle common formats (CSV,
+          JSON, SQL). You identify and report data quality issues and understand
+          basic ETL concepts.
+        working:
+          You integrate multiple data sources independently, clean messy
+          datasets, handle inconsistent formats and missing values, and document
+          data lineage. You troubleshoot integration failures.
+        practitioner:
+          You navigate complex enterprise data landscapes across teams, build
+          relationships to gain data access, handle undocumented schemas through
+          investigation, and build robust, maintainable integration solutions.
+          You mentor engineers in your area on data integration challenges.
+        expert:
+          You define data integration patterns and best practices across the
+          business unit. You architect large-scale data flows, solve the most
+          complex integration challenges, and are the authority on enterprise
+          data integration.
+    agent:
+      name: data-integration
+      description: |
+        Guide for integrating data from multiple sources, cleaning messy
+        datasets, and handling data quality issues.
+      useWhen: |
+        Working with enterprise data, ETL pipelines, or data transformation
+        tasks.
+      stages:
+        specify:
+          focus: |
+            Define data integration requirements and acceptance criteria.
+            Clarify data sources, formats, and quality expectations.
+          readChecklist:
+            - Identify source and target data systems
+            - Document data format and schema requirements
+            - Define data quality acceptance criteria
+            - Clarify data freshness and latency requirements
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          confirmChecklist:
+            - Data sources are identified and accessible
+            - Data format requirements are documented
+            - Quality criteria are defined
+            - Latency requirements are clear
+        plan:
+          focus: |
+            Plan data integration approach. Identify sources, assess quality,
+            and plan transformation logic.
+          readChecklist:
+            - Identify data sources and access requirements
+            - Assess data quality and completeness
+            - Plan transformation logic and validation
+            - Document data lineage approach
+          confirmChecklist:
+            - Data sources are identified
+            - Data formats are understood
+            - Data quality requirements are defined
+            - Transformation logic is planned
+        onboard:
+          focus: |
+            Set up the data integration environment. Install data
+            processing tools, configure data source access, and verify
+            connectivity to all required systems.
+          readChecklist:
+            - Install data tools (DuckDB, Polars, Great Expectations)
+            - Configure database connections and API credentials
+            - Verify access to all identified data sources
+            - Set up virtual environment and pin dependency versions
+            - Create .env file with connection strings and credentials
+          confirmChecklist:
+            - All data processing libraries installed and importable
+            - Data source connections verified and working
+            - Credentials stored securely in .env (not committed to git)
+            - Sample queries run successfully against each data source
+            - Virtual environment is reproducible (requirements.txt or
+              pyproject.toml)
+        code:
+          focus: |
+            Implement data transformations with robust quality checks
+            and error handling for messy real-world data.
+          readChecklist:
+            - Implement data extraction and loading
+            - Handle data quality issues (nulls, formats, duplicates)
+            - Create transformation logic
+            - Add validation and error handling
+            - Document data lineage
+          confirmChecklist:
+            - Data transformations produce expected output
+            - Basic validation exists for input data
+            - Data formats are handled correctly
+            - Error handling exists for malformed data
+            - Pipeline is idempotent
+        review:
+          focus: |
+            Validate data quality, transformation correctness, and
+            operational readiness.
+          readChecklist:
+            - Verify data quality checks
+            - Test with edge cases and malformed data
+            - Review error handling coverage
+            - Validate documentation completeness
+          confirmChecklist:
+            - Data quality checks are implemented
+            - Edge cases are handled
+            - Data lineage is documented
+            - Failures are logged and alertable
+        deploy:
+          focus: |
+            Deploy data pipeline to production and verify data flow.
+            Monitor for data quality and latency issues.
+          readChecklist:
+            - Deploy pipeline configuration
+            - Verify data flows end-to-end in production
+            - Monitor data quality metrics
+            - Confirm alerting is operational
+          confirmChecklist:
+            - Pipeline deployed successfully
+            - Data flowing in production
+            - Quality metrics within thresholds
+            - Alerting verified working
+    toolReferences:
+      - name: DuckDB
+        url: https://duckdb.org/docs/
+        simpleIcon: duckdb
+        description: In-process analytical database
+        useWhen: Querying CSV/Parquet files with SQL or quick data exploration
+      - name: Polars
+        url: https://docs.pola.rs/
+        simpleIcon: polars
+        description: Fast DataFrame library with lazy evaluation
+        useWhen: Transforming and cleaning large datasets programmatically
+      - name: Great Expectations
+        url: https://docs.greatexpectations.io/
+        simpleIcon: python
+        description: Data validation and profiling framework
+        useWhen: Validating data quality and creating data documentation
+    instructions: |
+      ## Step 1: Explore the Source Data
+
+      Use DuckDB to quickly inspect files without loading into memory.
+      Check schema, data types, row counts, and null distributions.
+
+      ## Step 2: Transform with Polars
+
+      Use lazy evaluation for large datasets: filter, fill nulls,
+      parse dates, and aggregate. Collect only when the query plan
+      is complete. Write cleaned data to Parquet.
+
+      ## Step 3: Validate Data Quality
+
+      Define expectations with Great Expectations: not-null checks,
+      uniqueness constraints, value ranges. Run validation and
+      check results.
+
+      ## Step 4: Export to Target Format
+
+      Use DuckDB COPY or Polars write methods to export transformed
+      data to the target format and location.
+    installScript: |
+      set -e
+      pip install duckdb polars great-expectations
+      python -c "import duckdb, polars, great_expectations"
+    implementationReference: |
+      ## SQL Exploration
+
+      ```sql
+      SELECT * FROM read_csv('data.csv') LIMIT 10;
+      DESCRIBE SELECT * FROM read_csv('data.csv');
+      SELECT COUNT(*), COUNT(id), COUNT(email) FROM read_csv('data.csv');
+      ```
+
+      ## Polars Transformation
+
+      ```python
+      import polars as pl
+
+      df = (
+          pl.scan_csv("source_data.csv")
+          .filter(pl.col("status") == "active")
+          .with_columns(
+              pl.col("value").fill_null(0),
+              pl.col("date").str.to_date("%Y-%m-%d")
+          )
+          .group_by("category")
+          .agg(pl.col("value").sum())
+          .collect()
+      )
+      df.write_parquet("cleaned_data.parquet")
+      ```
+
+      ## Data Quality Validation
+
+      ```python
+      import great_expectations as gx
+
+      context = gx.get_context()
+      validator = context.sources.pandas_default.read_csv("cleaned_data.csv")
+      validator.expect_column_values_to_not_be_null("id")
+      validator.expect_column_values_to_be_unique("id")
+      validator.expect_column_values_to_be_between("age", 0, 120)
+      results = validator.validate()
+      ```
+
+      ## Verification
+
+      Your pipeline is working when:
+      - Source data loads without errors
+      - Transformation produces expected row counts
+      - Data quality checks pass
+      - Output file is readable and contains expected data
+
+      ```python
+      result = pl.read_parquet("output.parquet")
+      assert len(result) > 0, "Output should have rows"
+      ```
+
+      ## Common Pitfalls
+
+      - **Data leakage**: Using future data in training sets
+      - **Silent nulls**: Empty strings vs NULL vs placeholder values
+      - **Schema drift**: Columns change without warning
+      - **Encoding issues**: UTF-8 vs Latin-1 in CSV files
+  - id: full_stack_development
+    name: Full-Stack Development
+    human:
+      description:
+        Building complete solutions across frontend, APIs, databases, and
+        infrastructure without dependencies on specialists. JavaScript and
+        Python are our primary languages, with CloudFormation and Terraform for
+        infrastructure. Essential for rapid delivery and embedded engineering
+        work.
+      proficiencyDescriptions:
+        awareness:
+          You understand how frontend, backend, and database layers work
+          together. You can make changes in one layer with guidance and
+          understand the impact on other layers.
+        foundational:
+          You build simple features across frontend and backend using JavaScript
+          or Python. You understand how layers connect through APIs and can
+          debug across the stack.
+        working:
+          You deliver complete features end-to-end independently—frontend,
+          backend, database, and infrastructure (CloudFormation/Terraform). You
+          make pragmatic technology choices and deploy what you build.
+        practitioner:
+          You build complete applications rapidly across any technology stack
+          for teams in your area. You select the right tools for each problem,
+          balance technical debt with delivery speed, and mentor engineers on
+          full-stack development.
+        expert:
+          You work comfortably in any language and rapidly acquire new skills as
+          needed. You deliver production solutions in days not months, shape
+          full-stack practices across the business unit, and exemplify
+          polymathic engineering.
+    agent:
+      name: full-stack-development
+      description: |
+        Guide for building complete solutions across the full technology
+        stack.
+      useWhen: |
+        Asked to implement features spanning frontend, backend, database,
+        and infrastructure layers.
+      stages:
+        specify:
+          focus: |
+            Define full-stack feature requirements and acceptance criteria.
+            Clarify user needs and system integration points.
+          readChecklist:
+            - Identify user stories and acceptance criteria
+            - Document expected user interactions
+            - Clarify integration requirements with existing systems
+            - Define non-functional requirements (performance, security)
+            - Mark ambiguities with [NEEDS CLARIFICATION]
+          confirmChecklist:
+            - User stories are documented
+            - Acceptance criteria are defined
+            - Integration points are identified
+            - Non-functional requirements are clear
+        plan:
+          focus: |
+            Design the full-stack solution architecture. Define API
+            contracts and plan layer interactions.
+          readChecklist:
+            - Define the API contract first
+            - Plan frontend and backend responsibilities
+            - Design database schema
+            - Plan infrastructure requirements
+          confirmChecklist:
+            - API contract is defined
+            - Layer responsibilities are clear
+            - Database schema is planned
+            - Infrastructure approach is decided
+        onboard:
+          focus: |
+            Set up the full-stack development environment. Install
+            frameworks, configure services, set up database, and verify
+            the development server runs.
+          readChecklist:
+            - Install project dependencies (npm install, pip install)
+            - Configure environment variables in .env.local or .env
+            - Start local database and apply schema/migrations
+            - Configure linter, formatter, and pre-commit hooks
+            - Set up GitHub tokens for API access if needed
+            - Verify development server starts without errors
+          confirmChecklist:
+            - All dependencies installed and versions locked
+            - Environment variables configured for local development
+            - Database running locally with schema applied
+            - All credentials stored in .env — NEVER hardcoded in code,
+              including seed scripts and utility scripts
+            - Linter and formatter pass on existing code
+            - Development server starts and responds to requests
+            - CI pipeline configuration is valid
+        code:
+          focus: |
+            Build vertically—complete one feature end-to-end before
+            starting another. Validates assumptions early.
+          readChecklist:
+            - Implement API endpoints
+            - Build frontend integration
+            - Create database schema and queries
+            - Configure infrastructure as needed
+            - Test across layers
+          confirmChecklist:
+            - Frontend connects to backend correctly
+            - Database schema supports the feature
+            - Error handling spans all layers
+            - Feature works end-to-end
+            - At least one test exists for each API route and passes when run
+            - Deployment is automated
+        review:
+          focus: |
+            Verify integration across layers and ensure deployment
+            readiness.
+          readChecklist:
+            - Test integration across all layers
+            - Verify error handling end-to-end
+            - Check deployment configuration
+            - Review documentation
+          confirmChecklist:
+            - Integration tests pass
+            - Deployment verified
+            - Documentation is complete
+            - Feature is production-ready
+        deploy:
+          focus: |
+            Deploy full-stack feature to production and verify end-to-end
+            functionality in live environment.
+          readChecklist:
+            - Deploy backend services
+            - Deploy frontend changes
+            - Run database migrations
+            - Verify feature works in production
+            - Monitor for errors and performance issues
+          confirmChecklist:
+            - All components deployed successfully
+            - Feature works end-to-end in production
+            - No errors in monitoring
+            - Performance meets requirements
+    toolReferences:
+      - name: Supabase
+        url: https://supabase.com/docs
+        simpleIcon: supabase
+        description: Open source Firebase alternative with PostgreSQL
+        useWhen:
+          Building applications with PostgreSQL, auth, and real-time features
+      - name: Next.js
+        url: https://nextjs.org/docs
+        simpleIcon: nextdotjs
+        description: React framework for full-stack web applications
+        useWhen:
+          Building React applications with server-side rendering or API routes
+      - name: GitHub Actions
+        url: https://docs.github.com/en/actions
+        simpleIcon: githubactions
+        description: CI/CD and automation platform
+        useWhen: Automating builds, tests, and deployments
+      - name: Nixpacks
+        url: https://nixpacks.com/docs
+        simpleIcon: nixos
+        description: Build tool that auto-detects and builds applications
+        useWhen: Auto-building and deploying applications to containers
+      - name: Colima
+        url: https://github.com/abiosoft/colima
+        simpleIcon: docker
+        description:
+          Lightweight container runtime for macOS with Docker-compatible CLI
+        useWhen:
+          Running containers locally for development, building images, or
+          testing containerized apps
+    instructions: |
+      ## Step 1: Configure Environment
+
+      Get connection details from `supabase status`. Create `.env.local`
+      with Supabase URL and anon key. Create the Supabase client module.
+
+      ## Step 2: Create Database Schema
+
+      Create a migration with `supabase migration new`, define the
+      SQL schema with RLS enabled, and apply with `supabase db push`.
+
+      ## Step 3: Build API Routes
+
+      Create Next.js API routes for GET and POST operations using
+      the Supabase client.
+
+      ## Step 4: Build Frontend
+
+      Create a React component that fetches from the API and renders
+      data. Start with a simple list display.
+
+      ## Step 5: Deploy
+
+      Use Nixpacks to auto-detect and build the image. Run it
+      locally with Colima's Docker-compatible runtime to verify
+      before deploying to production.
+    installScript: |
+      set -e
+      brew install colima
+      colima start
+      brew install supabase/tap/supabase || npm install -g supabase
+      npx --yes create-next-app@latest my-app --typescript --yes
+      cd my-app
+      supabase init
+      supabase start
+      npm install @supabase/supabase-js
+      colima status
+    implementationReference: |
+      ## Supabase Client Setup
+
+      ```typescript
+      // lib/supabase.ts
+      import { createClient } from '@supabase/supabase-js'
+
+      export const supabase = createClient(
+          process.env.NEXT_PUBLIC_SUPABASE_URL!,
+          process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+      )
+      ```
+
+      ## Database Schema
+
+      ```sql
+      CREATE TABLE items (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          name TEXT NOT NULL,
+          description TEXT,
+          created_at TIMESTAMPTZ DEFAULT NOW()
+      );
+      ALTER TABLE items ENABLE ROW LEVEL SECURITY;
+      ```
+
+      ## API Route
+
+      ```typescript
+      // app/api/items/route.ts
+      import { supabase } from '@/lib/supabase'
+      import { NextResponse } from 'next/server'
+
+      export async function GET() {
+          const { data, error } = await supabase.from('items').select('*')
+          if (error) return NextResponse.json({ error }, { status: 500 })
+          return NextResponse.json(data)
+      }
+      ```
+
+      ## Frontend Component
+
+      ```typescript
+      // app/page.tsx
+      'use client'
+      import { useEffect, useState } from 'react'
+
+      export default function Home() {
+          const [items, setItems] = useState([])
+          useEffect(() => {
+              fetch('/api/items').then(r => r.json()).then(setItems)
+          }, [])
+          return (
+              <main>
+                  <h1>Items</h1>
+                  <ul>{items.map((item: any) => <li key={item.id}>{item.name}</li>)}</ul>
+              </main>
+          )
+      }
+      ```
+
+      ## Verification
+
+      Your full-stack app is working when:
+      - `npm run dev` starts without errors
+      - Frontend loads at http://localhost:3000
+      - API responds at http://localhost:3000/api/items
+      - Data persists in database (check Supabase Studio at http://localhost:54323)
+
+      ## Common Pitfalls
+
+      - **Missing env vars**: Supabase client fails silently
+      - **RLS without policies**: Queries return empty results
+      - **Type mismatch**: Generate types with `supabase gen types typescript`
+      - **Migration order**: Migrations apply alphabetically by filename
+
+      ## Local Container Testing with Colima
+
+      ```bash
+      # Start Colima (lightweight Docker-compatible runtime)
+      colima start
+
+      # Build with Nixpacks and run locally
+      nixpacks build . --name my-app
+      docker run --rm -p 3000:3000 --env-file .env.local my-app
+
+      # Verify app responds
+      curl http://localhost:3000
+      ```
+  - id: problem_discovery
+    name: Problem Discovery
+    human:
+      description:
+        Navigating undefined problem spaces to uncover real requirements through
+        observation and immersion. Where most engineers expect specifications,
+        FDEs embrace ambiguity—starting with open questions like "How can we
+        accelerate patient recruitment?" rather than detailed requirements
+        documents.
+      proficiencyDescriptions:
+        awareness:
+          You recognize that initial requirements are often incomplete. You ask
+          clarifying questions when you encounter gaps and don't make
+          assumptions.
+        foundational:
+          You actively seek context beyond initial requirements, interview
+          stakeholders to understand "why" behind requests, and document
+          discovered constraints and assumptions.
+        working:
+          You navigate ambiguous problem spaces independently. You discover
+          requirements through observation and user shadowing, reframe problems
+          to find higher-value solutions, and distinguish symptoms from root
+          causes.
+        practitioner:
+          You seek out undefined problems rather than avoiding them. You embed
+          with users to discover latent needs, coach engineers in your area on
+          problem discovery techniques, and turn ambiguity into clear problem
+          statements.
+        expert:
+          You shape approaches to problem discovery across the business unit.
+          You are recognized for transforming ambiguous situations into clear
+          opportunities, influence how teams engage with business problems, and
+          are the go-to person for the most undefined challenges.
+    agent:
+      name: problem-discovery
+      description: |
+        Guide for navigating undefined problem spaces and uncovering real
+        requirements.
+      useWhen: |
+        Facing ambiguous requests, exploring user needs, or translating vague
+        asks into clear problem statements.
+      stages:
+        specify:
+          focus: |
+            Explore the problem space and document what is known.
+            Surface ambiguities and unknowns before attempting solutions.
+          readChecklist:
+            - Document the initial problem statement as understood
+            - ASK the user who the stakeholders are and what their perspectives
+              are
+            - ASK the user what is known vs unknown about the problem
+            - ASK the user to confirm or reject your assumptions
+            - Mark all ambiguities with [NEEDS CLARIFICATION] and ASK the user
+              to clarify them
+          confirmChecklist:
+            - Initial problem statement is documented
+            - Stakeholders are identified
+            - Known vs unknown is explicit
+            - Assumptions are listed for validation
+        plan:
+          focus: |
+            Embrace ambiguity and explore the problem space. Understand
+            context deeply before proposing solutions.
+          readChecklist:
+            - Ask open-ended questions about goals and context
+            - Identify stakeholders and their needs
+            - Discover constraints and prior attempts
+            - Distinguish symptoms from root causes
+            - Write clear problem statement
+          confirmChecklist:
+            - Understand who has the problem
+            - Success criteria are clear
+            - Root cause identified, not just symptoms
+            - Constraints and assumptions documented
+            - Problem statement is validated
+        onboard:
+          focus: |
+            Set up the environment for solution implementation.
+            Install required tools, configure access to relevant
+            systems, and prepare workspace for development.
+          readChecklist:
+            - Install project dependencies from plan requirements
+            - Configure access to relevant data sources and APIs
+            - Set up environment variables and credentials
+            - Verify access to stakeholder communication channels
+            - Create workspace structure for documentation and code
+          confirmChecklist:
+            - All planned tools and dependencies are installed
+            - API keys and credentials are configured securely
+            - Workspace structure supports the planned approach
+            - Access to all required systems is verified
+            - Development environment matches plan requirements
+        code:
+          focus: |
+            Implement solution while staying connected to the original
+            problem. Validate assumptions as you build.
+          readChecklist:
+            - Build incrementally to validate understanding
+            - Check in with stakeholders frequently
+            - Adjust as new information emerges
+            - Document discovered requirements
+          confirmChecklist:
+            - Solution addresses the validated problem
+            - Stakeholder feedback is incorporated
+            - Discovered requirements are documented
+            - Scope boundaries are maintained
+        review:
+          focus: |
+            Verify solution addresses the real problem and stakeholders
+            agree on success.
+          readChecklist:
+            - Validate with original stakeholders
+            - Confirm problem is addressed
+            - Document learnings for future reference
+          confirmChecklist:
+            - Stakeholders confirm problem is solved
+            - Success criteria are met
+            - Learnings are documented
+        deploy:
+          focus: |
+            Release solution and verify it addresses the real problem
+            in production context.
+          readChecklist:
+            - Deploy solution to production
+            - Gather stakeholder feedback on live solution
+            - Monitor for unexpected usage patterns
+            - Document discovered requirements for future iterations
+          confirmChecklist:
+            - Solution is deployed
+            - Stakeholders have validated in production
+            - Usage patterns match expectations
+            - Learnings are captured
+    instructions: |
+      ## Discovery Process
+
+      ### 1. Embrace Ambiguity
+      - Don't rush to solutions
+      - Resist the urge to fill gaps with assumptions
+      - Ask open-ended questions
+      - Seek to understand context deeply
+
+      ### 2. Understand the Context
+      - Who are the stakeholders?
+      - What triggered this request?
+      - What has been tried before?
+      - What constraints exist?
+      - What does success look like?
+
+      ### 3. Find the Real Problem
+      - Ask "why" repeatedly (5 Whys technique)
+      - Distinguish wants from needs
+      - Identify root causes vs symptoms
+      - Challenge initial framing
+
+      ### 4. Validate Understanding
+      - Restate the problem in your own words
+      - Confirm with stakeholders
+      - Check for hidden assumptions
+      - Identify what's still unknown
+    implementationReference: |
+      ## Key Questions
+
+      ### Understanding Goals
+      - What outcome are you trying to achieve?
+      - How will you know if this succeeds?
+      - What happens if we do nothing?
+      - What's the deadline and why?
+
+      ### Understanding Context
+      - Who uses this and how?
+      - What's the current workaround?
+      - What constraints must we work within?
+      - What has been tried before?
+
+      ### Understanding Scope
+      - What's in scope vs out of scope?
+      - What's the minimum viable solution?
+      - What could we cut if needed?
+      - What can't we compromise on?
+
+      ## Problem Statement Template
+
+      A good problem statement answers:
+      - **Who** has this problem?
+      - **What** is the problem they face?
+      - **Why** does it matter?
+      - **When/Where** does it occur?
+      - **How** is it currently handled?
+
+      Format: "[User type] needs [capability] because [reason], but currently [obstacle]."
+
+      ## Common Pitfalls
+
+      - **Solutioning too early**: Jumping to "how" before understanding "what"
+      - **Taking requests literally**: Building what was asked, not what's needed
+      - **Assuming completeness**: Believing initial requirements are complete
+      - **Ignoring context**: Missing business or user context
+      - **Single perspective**: Only talking to one stakeholder
+  - id: rapid_prototyping
+    name: Rapid Prototyping & Validation
+    human:
+      description:
+        Building working solutions quickly to validate ideas and build trust
+        through delivery. Credibility comes from showing real software in days,
+        not months— demonstrating value before polishing details. "Working
+        solutions delivered in days" is the FDE standard.
+      proficiencyDescriptions:
+        awareness:
+          You understand the value of prototypes for learning quickly. You can
+          create simple demos and mockups with guidance.
+        foundational:
+          You build functional prototypes to validate ideas, prioritize core
+          functionality over polish, and iterate based on user feedback. You
+          know the difference between prototype and production code.
+        working:
+          You deliver working solutions rapidly (days not weeks). You use
+          prototypes to build stakeholder trust, know when to stop prototyping
+          and start productionizing, and balance speed with appropriate quality.
+        practitioner:
+          You lead rapid delivery initiatives across teams in your area, coach
+          on prototype-first approaches, establish trust through consistent fast
+          delivery, and define clear criteria for prototype-to-production
+          transitions.
+        expert:
+          You shape culture around rapid validation and iterative delivery
+          across the business unit. You are recognized for transformative fast
+          delivery, define standards for prototype-to-production, and exemplify
+          the "deliver in days" mindset.
+    agent:
+      name: rapid-prototyping
+      description: |
+        Guide for building working prototypes quickly to validate ideas and
+        demonstrate feasibility.
+      useWhen: |
+        Asked to build a quick demo, proof of concept, MVP, or prototype
+        something rapidly.
+      stages:
+        specify:
+          focus: |
+            Define what the prototype must demonstrate and success criteria.
+            Scope ruthlessly—prototypes are for learning, not production.
+          readChecklist:
+            - Identify the key question or hypothesis to validate
+            - Document minimum acceptable demonstration
+            - Define what success looks like for this prototype
+            - Explicitly mark what is out of scope
+            - Mark any ambiguities with [NEEDS CLARIFICATION]
+          confirmChecklist:
+            - Key question to answer is clear
+            - Minimum viable demonstration is defined
+            - Success criteria are explicit
+            - Out of scope items are documented
+        plan:
+          focus: |
+            Define what the prototype needs to demonstrate and set
+            success criteria. Scope ruthlessly for speed.
+          readChecklist:
+            - Define the key question to answer
+            - Scope to minimum viable demonstration
+            - Identify what can be hardcoded or skipped
+            - Set time box for delivery
+          confirmChecklist:
+            - Success criteria are defined
+            - Scope is minimal and focused
+            - Time box is agreed
+            - It's clear this is a prototype
+        onboard:
+          focus: |
+            Set up the prototyping environment as fast as possible.
+            Use scaffolding tools, install minimal dependencies,
+            and get to a running state quickly.
+          readChecklist:
+            - Scaffold project using template or CLI tool
+            - Install only essential dependencies
+            - Configure minimal environment variables
+            - Start development server and verify it runs
+            - Skip non-essential tooling (linters, CI) for speed
+          confirmChecklist:
+            - Project scaffolded and running locally
+            - Core dependencies installed
+            - Development server responds to requests
+            - Ready to start building visible output immediately
+        code:
+          focus: |
+            Build the simplest thing that demonstrates the concept.
+            Prioritize visible progress over backend elegance.
+          readChecklist:
+            - Start with visible UI/output
+            - Hardcode values that would normally be configurable
+            - Skip edge cases that won't appear in demo
+            - Show progress frequently
+            - Document shortcuts taken
+          confirmChecklist:
+            - Core concept is demonstrable
+            - Happy path works end-to-end
+            - At least one smoke test verifying the happy path exists
+            - SSR pages that fetch from API routes use environment-aware base
+              URLs (not hardcoded localhost)
+            - Known limitations are documented
+            - Stakeholders can interact with it
+        review:
+          focus: |
+            Validate prototype answers the original question. Decide
+            whether to iterate, productionize, or abandon.
+          readChecklist:
+            - Demo to stakeholders
+            - Gather feedback on the concept
+            - Decide next steps
+            - Document learnings
+          confirmChecklist:
+            - Stakeholders have seen the prototype
+            - Original question is answered
+            - Next steps are decided
+            - Learnings are captured
+        deploy:
+          focus: |
+            Make prototype accessible to stakeholders for evaluation.
+            Prototypes may not need production deployment.
+          readChecklist:
+            - Deploy to accessible environment (staging or demo)
+            - Share access with stakeholders
+            - Gather hands-on feedback
+            - Decide on next phase (iterate, productionize, or abandon)
+          confirmChecklist:
+            - Prototype is accessible to stakeholders
+            - Feedback has been gathered
+            - Decision on next steps is made
+            - Learnings are documented
+    toolReferences:
+      - name: Supabase
+        url: https://supabase.com/docs
+        simpleIcon: supabase
+        description: Open source Firebase alternative with PostgreSQL
+        useWhen: Instant PostgreSQL database with auth for rapid prototypes
+      - name: Next.js
+        url: https://nextjs.org/docs
+        simpleIcon: nextdotjs
+        description: React framework for full-stack web applications
+        useWhen: Scaffolding a full-stack prototype with server-side rendering
+      - name: Nixpacks
+        url: https://nixpacks.com/docs
+        simpleIcon: nixos
+        description: Build tool that auto-detects and builds applications
+        useWhen: Deploying prototypes to containers without writing Dockerfiles
+    instructions: |
+      ## Step 1: Define What to Demonstrate
+
+      Before writing code, answer: What question does this prototype
+      answer? What's the minimum to demonstrate the concept? What can
+      be hardcoded or skipped? When will you stop?
+
+      ## Step 2: Start with Visible Output
+
+      Build the UI first—stakeholders need to see something.
+      Hardcode data initially so you have working output in minutes.
+
+      ## Step 3: Add Real Data When Needed
+
+      Only add database when the UI needs real data. Use Supabase
+      Studio to create tables directly (skip migrations for prototypes).
+
+      ## Step 4: Document Shortcuts
+
+      Add a README section listing what was skipped and what's needed
+      to productionize. This prevents confusion later.
+    installScript: |
+      set -e
+      npx --yes create-next-app@latest my-prototype --typescript --yes
+      cd my-prototype
+      supabase init
+      supabase start
+      npm run dev
+    implementationReference: |
+      ## Start with Hardcoded UI
+
+      ```typescript
+      // app/page.tsx
+      export default function Home() {
+          const items = [
+              { id: 1, name: 'Demo Item 1' },
+              { id: 2, name: 'Demo Item 2' },
+          ]
+          return (
+              <main style={{ padding: '2rem' }}>
+                  <h1>Prototype Demo</h1>
+                  <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>
+              </main>
+          )
+      }
+      ```
+
+      ## Replace with Real Data
+
+      ```typescript
+      import { supabase } from '@/lib/supabase'
+      const { data: items } = await supabase.from('items').select('*')
+      ```
+
+      ## Document Shortcuts
+
+      ```markdown
+      ## Prototype Limitations
+      This is a prototype for [purpose]. Not production-ready.
+
+      **Shortcuts taken:**
+      - No authentication
+      - Hardcoded configuration in code
+      - No error handling for edge cases
+
+      **To productionize:**
+      - Add authentication
+      - Move config to environment variables
+      - Add proper error handling
+      ```
+
+      ## Acceptable vs Required
+
+      | Acceptable to Skip | Still Required |
+      |-------------------|----------------|
+      | Authentication | Core functionality works |
+      | Error handling | Happy path is reliable |
+      | Migrations | It's clear this is a prototype |
+      | Tests | Limitations are documented |
+
+      ## Common Pitfalls
+
+      - **Over-engineering**: Adding features "while you're at it"
+      - **No stopping point**: Polishing what you might throw away
+      - **Unclear purpose**: Building without knowing what question to answer
+      - **Hidden shortcuts**: Not documenting what was skipped