# JosiStack Agent Protocol

This page is intended for coding agents and their human collaborator.
Use it as a deterministic setup runbook. Do not skip the question phase.

## Purpose

JosiStack is a [T3 Stack](https://create.t3.gg/)-inspired setup protocol for type-safe web apps.
It chooses one of three paths, installs the matching baseline, and leaves future agents with the instruction files they need.

The leading word is **path**: ask enough to choose the path, follow only that path, and report the path in the execution summary.

## 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?

Completion criterion: every answer needed to choose a path, database default, auth option, and visualization option is known. If the human leaves a defaultable choice open, use the default from the decision matrix and say so.

## Decision Matrix

Choose exactly one primary path:

- frontend-only:
  - no Convex
  - no Prisma/tRPC
- managed+Convex:
  - use Convex
- self-host/local+Prisma+tRPC:
  - use Prisma + tRPC (v11)
  - Prisma is the intentional JosiStack SQL ORM standard for this path
  - SQLite default for local-only, PostgreSQL default for self-hosted production

Then layer optional additions:

- 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)

Completion criterion: the selected path and every optional addition have a yes/no decision before install commands begin.

## 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).

Completion criterion: every prerequisite for the selected path is either available, auto-installed, or blocked by a named manual step.

## 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
```

Completion criterion: the Next.js app exists, dependencies are installed, and shadcn/ui is initialized.

## 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.

Completion criterion: `.env.local` exists, `.gitignore` excludes it, and any placeholder requiring human credentials is called out in the summary.

## 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>
  );
}
```

Completion criterion: Convex is installed, initialized, has a schema file, and the app layout includes `ConvexProvider`.

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

This path uses stable tRPC v11 packages. Do not use the prerelease `@next` dist-tag. For this Next.js App Router baseline, do not use older v10-era patterns such as `@trpc/next` or the v10 `createTRPCNext` helper.

```bash
npm install @trpc/server @trpc/client @trpc/react-query @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
```

Completion criterion: Prisma is initialized with the selected provider, the first migration succeeds, and the project uses tRPC v11 packages only.

## 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
```

Completion criterion: each selected optional addition is installed, and skipped additions remain uninstalled.

## 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 during setup unless they are needed to perform the install itself.

### 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.

Completion criterion: every required file and every selected conditional file is saved locally, and failures have been retried once.

### Registering loaded instruction files

After all required and conditional files have been fetched, 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.

Completion criterion: the memory file lists exactly the installed instruction files and tells future agents when to use them.

## 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.
8. Manual follow-up required from the human, if any.

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.

Final completion criterion: the project has been created, the selected path is implemented, instruction files are registered, and the summary accounts for every selected option.