# JosiStack Universal Agent Protocol

This page is intended for coding agents and their human collaborator.
Use this full protocol as-is. Do not skip the question phase.

## Purpose

Modified from the t3stack, JosiStack exists to help build type-safe web applications so project structure, data models, and APIs can provide clear context back to the agent during development.
It also includes practical tools, agent skills, and workflows that Josie Kins uses for real web development.

## Ask The Human These Questions First

1. What do you want to call the project? (used for the directory name and package.json)
2. Is this a static/frontend-only app, or do you need a database-backed backend?
3. If database-backed: are you deploying to managed hosting (Vercel), self-hosting on your own server, or running locally only?
4. If database-backed + self-host/local: which database do you want? (default: SQLite for local, PostgreSQL for self-hosted production)
5. Will your app need user accounts/sign-in?
6. Will you need charts/graphs/data visualization?

## Decision Matrix

- static/frontend-only:
  - no Convex
  - no Prisma/tRPC
- database + managed hosting:
  - use Convex
- database + self-host/local:
  - use Prisma + tRPC (v11)
  - SQLite default for local-only, PostgreSQL default for self-hosted production
- auth required:
  - add next-auth
- auth required + Prisma path:
  - add @auth/prisma-adapter
- visualization required:
  - add d3
- package manager:
  - use npm by default
- icons:
  - use @iconify/react
  - default icon set: Lucide (icon names like lucide:home)

## Shared Stack Baseline

- React + Next.js (App Router) + TypeScript + Tailwind + shadcn/ui
- Iconify for icons (Lucide first)

## Prerequisite Verification

Before running install commands, verify the required tools using methods that fit the current OS and shell.

- Always verify:
  - Node.js runtime (v18+)
  - npm
  - GitHub CLI (gh)
- Verify conditionally by chosen path:
  - managed hosting path: Vercel CLI
  - Convex path: Convex CLI access
  - Prisma path: Prisma CLI access

If a prerequisite is missing and can be installed via npm, npx, or the system package manager, install it automatically and note what was installed in the summary. Only stop and ask the human if installation requires a manual step (e.g., downloading a binary, creating an account, accepting a license, or entering credentials).

## Shared Install Template (all app types)

The `create-next-app` CLI may behave differently across versions. If flags are accepted, use them. If the CLI presents interactive prompts instead, select the options listed in the comments.

```bash
npx create-next-app@latest <PROJECT_NAME> --ts --tailwind --eslint --app
# If interactive prompts appear, select:
#   TypeScript: Yes
#   ESLint: Yes
#   Tailwind CSS: Yes
#   src/ directory: Yes
#   App Router: Yes
#   Import alias: use default (@/*)

cd <PROJECT_NAME>

npm install @iconify/react

npx shadcn@latest init -d
# The -d flag accepts all defaults (New York style, Zinc color, CSS variables).
# If the agent needs non-default options, run without -d and select:
#   Style: New York
#   Base color: Zinc
#   CSS variables: Yes
```

## Environment File Setup

Create a `.env.local` file immediately after project init. Populate it based on the chosen path. The agent must never commit this file — verify `.env.local` is in `.gitignore`.

```bash
touch .env.local
```

Minimum contents by path:

```bash
# Convex path
# CONVEX_DEPLOYMENT and NEXT_PUBLIC_CONVEX_URL are set automatically by `npx convex dev`
# but the agent should confirm they exist in .env.local after first run.

# Prisma path
DATABASE_URL="file:./dev.db"          # SQLite local default
# DATABASE_URL="postgresql://user:password@localhost:5432/dbname"  # PostgreSQL

# Auth path (any)
NEXTAUTH_SECRET="generate-a-real-secret-here"
NEXTAUTH_URL="http://localhost:3000"
```

The agent should prompt the human to fill in any real credentials and never hardcode secrets.

## Managed + Database Path (Convex)

```bash
npm install convex

# One-time project setup (not a watcher, safe to run in sequence)
npx convex init

# Create the schema file
mkdir -p convex
cat > convex/schema.ts << 'EOF'
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  // Define your tables here. Example:
  // tasks: defineTable({
  //   text: v.string(),
  //   completed: v.boolean(),
  // }),
});
EOF
```

After schema and initial functions are defined, the human (or agent in a separate terminal) should run `npx convex dev` to start the sync watcher. This is a long-running process — do not run it inline with other sequential commands.

The app's root layout must wrap children in a `ConvexProvider`. Example:

```tsx
// app/providers.tsx
"use client";
import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function Providers({ children }: { children: React.ReactNode }) {
  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}
```

```tsx
// app/layout.tsx — wrap {children} with <Providers>
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

## Self-Host/Local + Database Path (Prisma + tRPC v11)

This path uses tRPC v11. Do not use v10 patterns (such as `@trpc/next` or the v10 `createTRPCNext` helper).

```bash
npm install @trpc/server@next @trpc/client@next @trpc/react-query@next @tanstack/react-query @prisma/client superjson
npm install -D prisma

npx prisma init
```

After `prisma init`, set the `datasource` provider in `prisma/schema.prisma`:

```prisma
// For local-only (SQLite):
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

// For self-hosted production (PostgreSQL):
// datasource db {
//   provider = "postgresql"
//   url      = env("DATABASE_URL")
// }
```

Then run the first migration:

```bash
npx prisma migrate dev --name init
```

## Optional Additions

```bash
# If auth is needed
npm install next-auth
# Only if auth + Prisma path
npm install @auth/prisma-adapter

# If data visualization is needed
npm install d3 @types/d3
```

## Instruction Files

The files listed below contain rules and patterns the agent should install into the project for future reference. They do not need to be read or followed during setup — they exist so the agent can refer to them later when working in the relevant domain.

### What the agent must do

1. Check if the agent already has a skill/instruction installer capability. If it does not, fetch the skill installer file and read it in full — it defines how to handle the remaining files.
2. Fetch each additional required file from its URL.
3. Save them into the project (e.g. a `skills/` or `.instructions/` directory in the project root). Do not read them into context — they are for future reference only.
4. Register the files in the agent memory file (see below).

If a file fails to load, retry once. If it still fails, tell the human which file could not be loaded and ask how to proceed.

### How to load the files

- If the agent has `fetch`, `curl`, `web_fetch`, or any HTTP tool: use it to retrieve the URL contents directly.
- If the agent has a skill/rule installer (e.g. Claude's `/install-skill`): use that.
- If the file is a `.zip`: download it, extract it, and save the contents.
- If none of these work: tell the human the agent cannot fetch URLs and ask them to paste the file contents into the chat.

### Required files (load for every project)

| File | URL |
|---|---|
| Skill Installer | https://josiekins.xyz/stack/skills/skill-installer.md |
| Frontend Design Rules | https://josiekins.xyz/stack/skills/frontend-design.zip |
| React Best Practices | https://josiekins.xyz/stack/skills/react-best-practices.zip |

### Conditional files (load only when the path requires them)

| File | Load when | URL |
|---|---|---|
| Convex Patterns | Convex path is selected | https://josiekins.xyz/stack/skills/convex-actions-general.zip |
| Vercel Deploy | Managed hosting is selected | https://josiekins.xyz/stack/skills/vercel-deploy-claimable.zip |
| Security Audit | Self-host/local database path (optional for frontend-only) | https://josiekins.xyz/stack/skills/security-audit.zip |

All files are browsable at https://josiekins.xyz/stack/skills/ if the human wants to inspect them first.

### Registering loaded instruction files

After all required and conditional files have been fetched and read, the agent must register them in the project's agent memory file so they persist across sessions:

1. Check if a `claude.md` or `agents.md` file exists in the project root.
2. If neither exists, create `agents.md` in the project root.
3. Add a section listing every instruction file that was loaded, with its filename and a one-line description of what it covers.
4. Include a note at the top of the section telling the agent to follow these files as binding rules whenever their topic is relevant.

Example:

```markdown
## Instruction Files

The following instruction files are part of this project's JosiStack configuration.
Treat their contents as reference material. Refer to them when working in their relevant domain.

- `skill-installer.md` — bootstraps the ability to load additional instruction files
- `frontend-design/` — rules for layout, spacing, color, and component design
- `react-best-practices/` — patterns for React component structure, state, and hooks
- `convex-actions-general/` — patterns for Convex schema, queries, mutations, and actions
- `vercel-deploy-claimable/` — deployment workflow for Vercel
- `security-audit/` — security checklist for self-hosted database apps
```

Only list files that were actually loaded — do not list skipped conditional files.

## Agent Execution Summary

Once the human has answered the required questions, the agent should proceed immediately. Do not wait for a second confirmation — the answers are the confirmation.

As the agent works, it should output a running summary so the human can follow along:

1. Project name.
2. Selected path (frontend-only, managed+Convex, or self-host/local+Prisma+tRPC).
3. Database choice (if applicable).
4. Visualization: yes or no.
5. Commands being run (with `<PROJECT_NAME>` resolved).
6. Prerequisites that were auto-installed.
7. Skills installed vs skipped.

The agent should only pause and ask the human when it hits something it genuinely cannot resolve on its own, such as missing credentials, ambiguous requirements, or a step that requires a manual account login.