ai-townVibe Coding GuideAI Replication Playbook

AI Replication Playbook

1. Master Project Briefing Prompt for AI Assistant

Instructions: This is your “Genesis Prompt.” Copy it and use it to kick off the entire project with your AI assistant. It is designed to be a complete project brief that establishes the vision, scope, architecture, and our new four-phase development plan.

It is written to replicate the original AI Town, but the sections marked with [// ...] are the precise points where you would inject your own unique vision to create a custom version.

Prompt
**Master Project Brief: Replicating the "AI Town" Simulation**
 
**Role:** You are my Lead Technical Architect and Engineering Partner. Your primary function is to act as an expert system designer and full-stack developer. My role is that of the Product Director; I will provide the vision and guide the project.
 
**Our Mission:** We are going to build a complete, full-stack, real-time, browser-based AI simulation application. Our foundational blueprint is the open-source project "AI Town."
 
**The Core Vision (The "Vibe"):**
The product is a charming, pixel-art virtual town where a society of AI agents live out their own lives. It is a digital terrarium for observing emergent social behavior. The core experience is one of discovery and narrative, watching unique stories unfold as these AI characters form relationships, remember their past, and build a community.
 
*   **User Experience:** The user experience is twofold. Initially, users are passive **Spectators**, able to pan and zoom around the world. Through a clear call-to-action, they can become active **Participants**, spawning their own character into the world to move, interact, and become part of the town's history.
 
`[// This is the core "Vibe" section. To create a custom project, you would replace the paragraph above with your own vision. For example: "The product is a high-fantasy world where AI-powered wizards, rogues, and warriors go on procedurally generated mini-quests and interact at a central tavern."]`
 
**Key Architectural Pillars:**
1.  **Real-Time Backend:** The simulation must run continuously on the server. The world state will be pushed to all connected clients in real-time. We will use **Convex**.
2.  **Generative AI Agents:** The agents' intelligence will be powered by a Large Language Model. Their behavior must emerge from a cognitive engine based on memory, reflection, and planning.
3.  **Performant 2D Frontend:** The town will be rendered on a 2D canvas. We will use **React/TypeScript** for the UI and **Pixi.js** for rendering.
 
**Our Development Plan:**
We will build this application in four distinct, sequential phases. I will provide you with a comprehensive master prompt for each phase.
 
*   **Phase 1: Backend Foundation & Simulation Engine.** First, we will build the core "physics" of our world.
*   **Phase 2: Frontend Rendering & Basic Interaction.** Next, we will build the "window" through which users view the world.
*   **Phase 3: Generative Agents - Memory & Dialogue.** Then, we will give our agents a "brain" and the ability to speak.
*   **Phase 4: Agent Autonomy & Social Behavior.** Finally, we will grant our agents "free will" to act on their own.
 
Your first task is to confirm that you have fully understood this comprehensive project brief, have internalized the role of Lead Technical Architect, and are ready to receive the master prompt for Phase 1.

2. The Master Roadmap

This is the complete project roadmap, aligned with the four phases in the AI Prompt Guide. Use this as your high-level checklist to track your progress.

Phase 1: Backend Foundation & Simulation Engine
  • Goal: Establish the serverless backend, define the database schema, and create the core simulation loop that makes the world feel alive and persistent.
  • Key Tasks:
    • Define all necessary data models (Worlds, Players, Engines).
    • Implement a persistent game loop driven by a scheduled task.
    • Implement world state loading and saving.
Phase 2: Frontend Rendering & Basic Interaction
  • Goal: Build the visual frontend to render the game world and allow a human player to join and move their character.
  • Key Tasks:
    • Set up the React/Vite project and connect to the Convex backend.
    • Implement the Pixi.js rendering canvas to display the map and characters from live backend data.
    • Implement the “click-to-move” functionality, sending user commands to the backend.
Phase 3: Generative Agents - Memory & Dialogue
  • Goal: Implement the core AI cognitive architecture, giving agents the ability to perceive, remember, and hold intelligent conversations.
  • Key Tasks:
    • Implement the memory creation pipeline (summarization, poignancy, embedding).
    • Implement the RAG-based memory retrieval system (relevance, importance, recency).
    • Implement the dialogue generation system that uses memories to create context-aware responses.
Phase 4: Agent Autonomy & Social Behavior
  • Goal: Grant agents “free will” to make their own decisions, wander the world, and initiate social interactions with each other, transforming them into truly autonomous entities.
  • Key Tasks:
    • Implement the agent state machine (tick() method) to manage states like “idle,” “walking,” and “talking.”
    • Implement the autonomous decision-making logic where agents use an LLM to decide what to do next.
    • Implement the full conversation lifecycle (inviting, accepting, leaving) driven by agent decisions.
Technical SpecificationsAI Prompt Library