Skip to content
App Framework Documentation

AI Agent Documentation

This section provides structured, machine-readable documentation for AI agents working with the app-framework monorepo.

Available Roles

AI agents can take on two primary roles when working with this codebase:

🔧 Internal Developer Role

Working on the app-framework monorepo itself - developing backend services, frontend apps, and shared libraries.

Documentation: Internal Developer Reference

Key Tasks:

  • Implement new features in backend services
  • Create reusable components in shared libraries
  • Fix bugs and write tests
  • Deploy and maintain infrastructure

📦 External Developer Role

Using published npm packages (@ifelse/customer-features, @ifelse/shared-ui) to build custom SaaS applications.

Documentation: External Developer Reference

Key Tasks:

  • Integrate published packages into external projects
  • Customize theming and styling
  • Implement custom features alongside framework features
  • Troubleshoot integration issues

🤖 Spec Driven Development

Set up @ifelse/agent-skills in your consumer project to enable AI-driven development with structured skill definitions, orchestrator workflows, and multi-session progress tracking.

Documentation: Spec Driven Development Setup

Key Tasks:

  • Install Agent Skills via CLI (npx @ifelse/agent-skills init)
  • Configure repo-specific rules and AGENTS.md
  • Use skills for modular feature implementation
  • Run orchestrator workflow for full app builds

Quick References

Architecture Summary

Condensed architecture overview from AGENTS.md covering:

  • Monorepo structure (apps vs libs)
  • Technology stack
  • Service patterns
  • Frontend source of truth architecture

Commands Reference

Complete reference of all npm scripts organized by category:

  • Development commands
  • Testing commands
  • Build and deployment
  • Publishing and release

API Reference

Quick lookup for GraphQL and REST APIs:

  • GraphQL schema overview
  • REST endpoint reference
  • Authentication patterns
  • Common queries and mutations

Usage Guidelines

For Internal Development

  1. Read Internal Developer Reference first
  2. Check Architecture Summary for patterns
  3. Use Commands Reference for npm scripts
  4. Refer to AGENTS.md for complete rules

For Package Integration

  1. Read External Developer Reference first
  2. Set up Spec Driven Development for AI-driven workflows
  3. Follow Package Usage Guide for setup
  4. Check API Reference for GraphQL queries
  5. Refer to package-specific docs for detailed API

Key Principles

Internal Development

  • Apps vs Libs: Apps are thin wrappers, libs contain reusable code
  • Frontend Source of Truth: Atomic components in libs/shared-ui, features in libs/customer-features
  • Multi-Instance Support: Services use SERVICE_NAME + SRV_ID patterns
  • Event-Driven: RabbitMQ for async communication

External Development

  • Package Installation: Configure npm registry access first
  • Theming: Use component slots pattern for customization
  • GraphQL Backend: Requires compatible backend with specific queries
  • Peer Dependencies: React 18+, Apollo Client, react-oidc-context

Documentation Structure

ai-agents/
├── index.md                       # This file
├── spec-driven-development.md     # Agent Skills setup and SDD workflow
├── internal-developer.md          # Quick reference for internal dev
├── external-developer.md          # Quick reference for package consumer
├── architecture-summary.md        # Condensed architecture overview
├── commands-reference.md          # All npm scripts
└── api-reference.md               # GraphQL/REST API lookup

Next Steps

Choose your role and dive into the relevant documentation: