AI-Assisted Development

Shipnative is built for vibecoding - describing features to AI and getting production-ready code that follows project patterns. The vibe/ folder teaches your AI everything it needs to know.

​

The Documentation Architecture: Layered Context

Shipnative uses a Layered Context architecture to ensure that AI agents get exactly the right amount of information at the right time. This maximizes accuracy while minimizing “token waste” (keeping interactions fast and cost-effective). The system operates across three distinct layers:

​

Tier 1: The Discovery Layer (AGENTS.md)

Following the AGENTS.md standard, these files act as the “Front Desk” for any AI agent.

• Nested Context: We use nested AGENTS.md files (in root, apps/app/, etc.). When an agent enters a folder, it reads the closest file first.
• Lean & Fast: It provides a directory map, “Always/Never” constraints, and points to deeper documentation.

​

Tier 2: The Specification Layer (vibe/ folder)

This is the “Brain” of the project, containing deep-dive technical specs.

• Detailed Specs: Located in shipnativeapp/vibe/ and apps/app/vibe/.
• Role: These files store the “why” and “how” of complex subsystems (e.g., service architecture, styling math, mock implementation).

​

Tier 3: The Single Source of Truth (AGENTS.md)

This is the “Law” of the project.

• Immutable Rules: Contains the core tech stack decisions (e.g., “Always use Unistyles”).
• Reference: Every agent instruction file points here to prevent the AI from suggesting incompatible libraries.

---

​

️ Maintenance & The “Tipping Point”

AI documentation is not a static reference—it is a living system. To keep your agents performing at 100%, you must manage Instruction Drift and follow the Tipping Point rules.

​

The “Update-as-you-go” Rule

Documentation is part of the “Definition of Done.” When an agent finishes a feature, it must:

1. Sync: Update the relevant vibe/ spec file with the new implementation details.
2. Verify: Ensure AGENTS.md and AGENTS.md are still accurate.
3. Commit: Commit documentation changes alongside the code.

​

️ The Tipping Point: Where does info go?

To save tokens and keep agents focused, follow this logic:

• Add to AGENTS.md (Discovery) ONLY if:
  1. It is a strict Constraint (Always/Never do X).
  2. It is a Navigation Aid (File X is actually for Y).
  3. It fixes a Recurring Mistake (Instruction Drift).
  • Keep this file under 100 lines.
• Add to vibe/ or docs/ (Specification) if:
  1. It is a Technical Deep Dive (SQL schema, logic flow).
  2. It is a Setup Guide (How to configure service X).
  3. it is Reference Data (List of all API endpoints).

​

Fixing “Instruction Drift”

If an agent makes a mistake (e.g., uses the wrong styling library), don’t just fix the code. Update the local AGENTS.md. By adding a specific “Never do X” rule to the local context, you ensure the agent (and future ones) won’t make that same mistake again. This is how the system becomes “smarter” over time. This prompt is designed to prime your AI assistant effectively:

1. I'm building with Shipnative.: Signals to the AI that you’re using the Shipnative boilerplate.
2. Read the vibe/ folder.: Instructs the AI to read the single source of truth (AGENTS.md) and context files.
3. I want to build [describe your feature in detail].: This is where you provide your specific requirements. Be as detailed as possible.
4. Check if similar functionality exists and outline your approach.: Encourages reusing existing patterns before writing new code.

​

AI Development Workflow

When working with your AI assistant, follow these steps:

​

Step 1: Read Context Files

Always ensure your AI has read AGENTS.md (the single source of truth) and the vibe/ folder. This is the most critical step for generating relevant and idiomatic code.

​

Step 2: Check Existing Code

Before implementing a new feature, instruct your AI to review existing code patterns:

• apps/app/app/components/: For reusable UI components.
• apps/app/app/screens/: For screen structure and common patterns.
• apps/app/app/stores/: For state management patterns using Zustand.
• apps/app/app/services/: For service interaction patterns (e.g., Supabase, RevenueCat).

This helps the AI understand how to integrate new code seamlessly.

​

Step 3: Implement Feature

Guide your AI to implement the feature following established Shipnative patterns:

• Styling: Use Unistyles with theme values (never hardcode).
• State Management: Leverage Zustand for global state and React Query for server state/data fetching.
• UI/UX: Ensure dark mode support, accessibility labels, and graceful error handling.
• API Interaction: Use the provided service wrappers (e.g., supabase, revenueCat) which automatically support mock mode.

​

Step 4: Update Documentation (Crucial for AI)

If you add a new major feature or modify existing ones, remember to update the relevant documentation. This keeps the AI’s context up-to-date for future tasks.

• shipnativeapp/vibe/CONTEXT.md: For major new features or significant architectural changes.
• Feature-specific .md files (e.g., SUPABASE.md, MONETIZATION.md): For detailed changes to integrated services.
• Mintlify Docs: Update the user-facing documentation (like this one!) to reflect new capabilities.

​

Benefits of Vibecoding

• Consistency: AI generates code that adheres to your project’s style and architecture.
• Speed: Automate boilerplate and repetitive tasks, allowing you to focus on core logic.
• Quality: Reduce human error and ensure best practices are followed.
• Maintainability: New features are integrated seamlessly, making the codebase easier to understand and maintain.

By effectively using the vibe/ folder and guiding your AI assistant, you can significantly accelerate your development process and maintain a high-quality codebase.