Cheat Sheet to create an Infinito.Nexus web-* role with AI

Development AI
1

This guide helps you efficiently create new web-app roles within the Infinito.Nexus ecosystem using a structured, iterative approach.

The goal is to stay fast, consistent, and maintainable by:

  • leveraging proven reference implementations (e.g. Pixelfed),
  • applying clean engineering principles,
  • and validating early through local testing and automation.

Whether you’re working with high or low confidence in AI-generated code, this workflow ensures that every role you create is understandable, testable, and production-ready.

Recommendations about what AI to choose and how to set it up you will find here.

:rocket: Task Prompt

Follow the instructions from AGENTS.md. 

Add a new port for application x to port group_vars/all/*_port.yml

Add a new network for application x to group_vars/all/*_network.yml

Create a new web-app role named web-app-x  
Reference implementation: https://github.com/infinito-nexus/core/tree/master/roles/web-app-pixelfed

Implement these Acceptance Criteria:
- A
- B
- C
- D

Follow this iteration procedure, until everything is deployed and all tests pass:
docs/agents/action/iteration.md

:repeat_button: Optimization Iteration

Validate the implementation:
- Check for errors
- Compare structure and behavior with the Pixelfed role

:light_bulb: Important: Always provide a strong reference (like Pixelfed) so the AI has a clear quality benchmark.

:brain: Best Practice

:white_check_mark: Do’s

:small_blue_diamond: Keep Things Atomic

Ask the AI to:

  • Apply KISS → keep it simple and focused
  • Follow DRY → avoid duplication
  • Respect SPOT → ensure a single source of truth

Keep the design patterns for Clean Code in mind.

:small_blue_diamond: Follow MVP for Yourself

Work iteratively and validate early instead of trying to solve everything at once:

  1. :test_tube: Set up a local test environment :test_tube:

  2. :white_check_mark: Verify a working baseline
    → e.g. deploy and test web-app-pixelfed

  3. :robot: Adjust scope based on your confidence with AI

    • Low confidence → generate only the basic role structure
    • High confidence → include full requirements (A–D)

  4. :broom: Run:

    make test

    → catches static/code issues early

  5. :rocket: Deploy locally

  6. :computer_mouse: Test via UI → click through the application

  7. :performing_arts: Write Playwright tests

  8. :magnifying_glass_tilted_left: Review the code carefully

    • Do not proceed if you don’t fully understand it

  9. :counterclockwise_arrows_button: Push CI/CD

  10. :green_circle: If pipelines pass → open Pull Request

The CI/CD merge flow is documented here.

:toolbox: Tips & Tricks

:electric_plug: Developing with minimal hardware resources

Keep your environment minimal and focused:

compose:
  services:
    matomo:
      enabled: false
      shared: false
    dashboard:
      enabled: false
      shared: false
    oidc:
      enabled: false
      shared: false
    logout:
      enabled: false
      shared: false

:light_bulb: This reduces noise, speeds up debugging, and improves iteration time.

:bullseye: Summary

  • Use Pixelfed as your reference standard
  • Work iteratively (MVP mindset)
  • Validate early with make test
  • Keep everything simple, clean, and consistent
  • Never ship code you don’t understand
1 Like