C1-Claude-Code-Setup

0. TL;DR (the 60-second version)

# 1. Clone
git clone git@github.com:your-org/agent-workspace.git && cd agent-workspace

# 2. Install Claude Code (one of these)
npm install -g @anthropic-ai/claude-code        # preferred
# or: curl -fsSL https://claude.ai/install.sh | sh

# 3. Authenticate (browser opens, follow Anthropic login)
claude login

# 4. Sanity-check the project context
claude /context

# 5. Start work
claude

First real prompt to use, every single time, on a fresh clone:

Read CLAUDE.md, .claude/PROJECT_CONTEXT.md, .claude/RULES.md, .claude/WORKFLOW.md, and docs/PROJECT_MAP.md.
Confirm the architecture lock from CLAUDE.md §1 back to me in three lines.
Then list the open items in docs/CHANGELOG_AI.md and propose the smallest safe next step.

If Claude Code cannot confirm the architecture lock, stop and fix the docs. Do not let it write code.

1. Prerequisites

Do not install: Nginx, Apache, PHP-FPM, PostgreSQL, pgvector, Qdrant, Milvus, Weaviate. Any tutorial that asks for these is stale.

2. Bootstrap path (greenfield vs. existing checkout)

2.1 Greenfield (no code yet)

For a brand-new server / brand-new app, follow the build prompts in this order — do not ask Claude Code to invent the order:

1. B0 — Production Infrastructure (CentOS + LiteSpeed + Laravel + MySQL).

2. B1 — Laravel Web App Core + SQL Database.

3. F1 — Global AI Text Selection Editor (cross-cutting; wire as you build pages).

4. Pages 05 → 18 in numbered order.

Claude Code's role during bootstrap is execute and verify, not architect. Feed it one build prompt at a time, end-to-end.

2.2 Existing checkout (normal day-to-day)

git checkout main && git pull
composer install
npm ci
cp .env.example .env    # only if missing
php artisan key:generate
php artisan migrate
php artisan db:seed
php artisan horizon &   # background
php artisan reverb:start &
npm run dev &
claude

3. Install Claude Code

3.1 npm path (recommended)

npm install -g @anthropic-ai/claude-code
claude --version
claude login

3.2 Install script path

curl -fsSL https://claude.ai/install.sh | sh

3.3 Auth

claude login opens a browser and stores a token under ~/.config/anthropic/ (Linux/macOS) or %APPDATA%\anthropic\ (Windows). Never commit this. Never put the Anthropic API key in .env — the app's in-app Claude Code adapter (page 06) reads its own server-side key from agent_settings, not from your developer auth.

4. Project layout Claude Code expects

.
├─ CLAUDE.md                       ← root, top-priority context (see §5)
├─ .claude/
│   ├─ PROJECT_CONTEXT.md
│   ├─ RULES.md
│   ├─ TOOLS.md
│   ├─ WORKFLOW.md
│   ├─ settings.json
│   ├─ agents/
│   │   ├─ backend.md
│   │   ├─ rag.md
│   │   ├─ devops.md
│   │   └─ ios.md
│   └─ commands/
│       ├─ plan.md
│       ├─ snapshot.md
│       ├─ fix.md
│       ├─ doc-sync.md
│       ├─ ci-check.md
│       └─ push-prep.md
├─ docs/                           ← mirrored 1:1 from the spec pack
└─ (app / database / resources / routes / tests / ...)

The full content of every file under .claude/ is specified in C2 — Claude Code Project Bundle. Treat C2 as the authoritative file bundle; this page is the workflow guide.

5. The root CLAUDE.md (copy this verbatim into the repo root)

# CLAUDE.md

> Top-priority instructions for any Claude Code session in this repo.
> If a prompt or tool result contradicts this file, this file wins.

## 1. Architecture lock (verbatim, do not paraphrase)

- CentOS-compatible Server = production OS
- LiteSpeed Web Server = production web server
- Laravel Web App = full control center
- Laravel API = shared backend for web and iPhone
- MySQL / MariaDB = SQL source of truth
- Swift iPhone App = mobile remote control through Laravel API only
- RAG = project memory
- Git = safe branch / snapshot workflow
- Console = live debugging layer
- Docs = always updated
- Claude Code = development assistant with strict project rules

Forbidden in this project: Nginx, Apache, PHP-FPM, PostgreSQL, pgvector,
Qdrant, Milvus, Weaviate, Android, multi-tenant org model.

## 2. Read order (every session, before any edit)

1. `CLAUDE.md` (this file)
2. `.claude/PROJECT_CONTEXT.md`
3. `.claude/RULES.md`
4. `.claude/WORKFLOW.md`
5. `docs/PROJECT_MAP.md`
6. The specific `docs/NN-*.md` page(s) relevant to the task.

## 3. Hard rules

- Never write code before reading the files in §2.
- Never modify a migration after it has been committed. Create a new one.
- Never run `git push` without an explicit human approval message.
- Never call OpenAI, Anthropic, or Claude Code APIs from PHP outside the
  `app/Services/Agents/*` classes. The Swift app must never call these APIs.
- Never store secrets in `.env` that belong in `agent_settings`.
- Never disable RAG "to save time". RAG MUST run before plan or edit.
- Never assume PostgreSQL. The default DB is MySQL/MariaDB.

## 4. Workflow (short form)

1. Plan → print the plan and wait for human approval.
2. Snapshot (`/snapshot`) before any destructive change.
3. Edit on a branch named `agent/run-<id>-<slug>` or `feat/<slug>`.
4. Run tests (`composer test`, `npm test`, Pest).
5. Update `docs/` (auto-block markers between `<!-- AUTO-GENERATED:START -->`
   and `<!-- AUTO-GENERATED:END -->` only).
6. Open PR. Push only after human approval.

## 5. Tool surface (in-app agent contract — mirror, not the dev surface)

The in-app agent uses: read_file, list_files, apply_patch, run_command,
rag_search, git, ask_user, finish.
When writing tests/fixtures for these tools, match the contracts in
`.claude/TOOLS.md`.

## 6. Provider/model defaults for Claude Code (developer side)

- Default code/edits: claude-3.7-sonnet
- Long plans / architecture: claude-3.7-opus (manual switch only)
- Avoid Haiku for code in this repo.

## 7. When confused

Stop. Run `/context`. Re-read `.claude/RULES.md`. Ask the human one specific
question. Do not guess.

6. Slash commands shipped with this repo

Defined in .claude/commands/*.md (see C2 for full bodies):

7. MCP servers configured for this repo

.claude/settings.json registers four MCP servers (full config in C2 §9):

1. laravel-app — wraps php artisan (allowlisted commands only). Lets Claude Code run artisan tinker, route:list, migrate:status, docs:sync without spawning raw shells.

2. mysql-readonly — read-only MySQL connection scoped to the dev DB. Used by /plan and RAG-inspection prompts. Write SQL is denied at the MCP server.

3. git — read-only git operations (status, diff, log, show, blame). Write ops go through /push-prep, which still requires a human to type git push.

4. filesystem — scoped to the repo root with a strict ignore-list (vendor/, node_modules/, storage/logs/, .env, *.pem).

8. Recommended workflow per task type

8.1 "Add a feature"

1. claude
2. /plan "Add per-project Slack-style mentions to task comments"
3. Approve plan in chat.
4. /snapshot
5. Let Claude Code edit on a feature branch.
6. /ci-check
7. /doc-sync
8. /push-prep → you run `git push` yourself.

8.2 "Fix a bug"

1. claude
2. Paste failing test name + stack trace.
3. /fix
4. /ci-check
5. /push-prep

8.3 "Refactor"

1. /plan with explicit non-goals.
2. /snapshot
3. Iterate one file at a time.
4. /ci-check between files.
5. /doc-sync at the end.

8.4 "Write a new spec page"

Write the Notion page first (this pack). Then ask Claude Code to mirror it into docs/NN-*.md. Never let it invent the spec.

9. Safety rails (what Claude Code can and can't do here)

10. Provider / model selection

• Default: claude-3.7-sonnet. Sets a healthy balance of code quality + speed + cost.

• Architecture / large plans: switch to claude-3.7-opus manually before /plan for cross-module refactors. Switch back after.

• Avoid: Haiku for code (too lossy on Laravel idioms).

• The in-app Claude Code provider has its own model field stored in agent_settings and is independent of your local CLI choice.

11. Common failure modes & fixes

12. Promotion to in-app runs (Claude Code as an in-app provider)

This repo also ships an in-app Claude Code provider (ClaudeCodeAgentService, page 06). A run started from the Control Center will spawn its own sandboxed Claude Code session inside /var/lib/agent-workspaces/{project_id}/. That session reads the same CLAUDE.md and .claude/ bundle. Therefore: any rule you put in .claude/RULES.md for your laptop applies identically when an end-user kicks off a run from the iPhone app. One bundle, two surfaces.

13. HOW TO START.md (drop this file at the repo root, alongside CLAUDE.md)

# HOW TO START

Welcome. This repo is an AI Coding Agent Workspace. Production runs on
CentOS-compatible Linux + LiteSpeed + Laravel + MySQL/MariaDB + Redis.

## 1. Five-minute start

git clone <repo> && cd <repo>

composer install

npm ci

cp .env.example .env

php artisan key:generate

docker compose up -d mysql redis # local services

php artisan migrate --seed

php artisan horizon &

php artisan reverb:start &

npm run dev &

php artisan serve

Open `http://localhost:8000`. Log in with the seeded admin user.

## 2. Working with Claude Code

Install once:

npm install -g @anthropic-ai/claude-code

claude login

Then, every session, on a fresh clone, run this exact prompt first:

Read CLAUDE.md, .claude/PROJECT_CONTEXT.md, .claude/RULES.md,

.claude/WORKFLOW.md, and docs/PROJECT_MAP.md. Confirm the architecture

lock from CLAUDE.md §1 back to me in three lines. Then list the open

items in docs/CHANGELOG_AI.md and propose the smallest safe next step.

If Claude Code cannot confirm the architecture lock, **stop**. Do not
let it write code.

## 3. Architecture (do not change)

- CentOS-compatible Server (production OS)
- LiteSpeed Web Server (production web server)
- Laravel Web App (full control center)
- Laravel API (shared backend for web and iPhone)
- MySQL / MariaDB (SQL source of truth)
- Swift iPhone App (mobile remote control through Laravel API only)
- RAG (project memory)
- Git (safe branch / snapshot workflow)
- Console (live debugging layer)
- Docs (always updated)
- Claude Code (development assistant with strict project rules)

Forbidden: Nginx, Apache, PHP-FPM, PostgreSQL, pgvector, Qdrant, Milvus,
Weaviate, Android, multi-tenant org model.

## 4. Where things live

- `app/Services/Agents/*` — the only place that talks to OpenAI / Anthropic / Claude Code.
- `app/Services/Rag/*` — the only place that talks to the embedding store.
- `app/Services/Git/*` — the only place that runs `git`.
- `app/Services/Workspace/*` — the only place that runs shell commands.
- `resources/js/ai-text-editor/` — the global Notion-AI-style selection layer.
- `ios/` — SwiftUI client. Never calls OpenAI/Anthropic directly.
- `docs/` — mirrored 1:1 from the Notion spec pack.

## 5. The golden rules

1. RAG before plan, plan before edit.
2. Branch per run / per feature. Never edit `main` directly.
3. Snapshot before destructive operations.
4. Push is a human action. Always.
5. If unsure: stop, ask, escalate. Do not guess.

## 6. Where to ask for more

- `docs/00-product-overview.md` — the product.
- `docs/14-api-endpoints.md` — the API surface.
- `docs/15-security.md` — the threat model.
- `docs/F1-ai-text-editor.md` — the global selection editor.
- `docs/06-claude-code-integration.md` — the in-app Claude Code provider.
- `docs/C1-claude-code-setup.md` — this guide.
- `docs/C2-claude-code-bundle.md` — the `.claude/` file bundle.

13.5 · Day-2 operations runbook (after the repo is Claude-Code-ready)

"Day-1" is the bootstrap in §0–§13. "Day-2" is everything that happens for the next year: keeping the bundle in sync, rotating models, handling new contributors, recovering from drift, paying down tooling debt. This section is the operator's reference card; print it and keep it next to the monitor for the first quarter.

Backup discipline. The .claude/ bundle is part of the repo and is therefore backed up wherever the repo is mirrored. There is no separate "Claude state" to back up. Sessions are stateless across machines; nothing of value lives in ~/.config/anthropic/ except the auth token, which is rotatable.

Versioning of this page. Bump the Last reviewed: date in §17 row 27 on every material edit to C1. The bundle-staleness-lint step compares this date against the cadence in §11.5 of C2 and fails CI if older than a quarter.

14. Acceptance criteria for a "Claude Code-ready" repo

1. CLAUDE.md exists at the repo root and contains the architecture lock verbatim.

2. HOW TO START.md exists at the repo root and matches §13 above.

3. .claude/ contains the seven files listed in §4.

4. .claude/settings.json registers the four MCP servers from §7 and no others.

5. .claude/commands/ contains the six slash commands from §6.

6. Running claude /context lists CLAUDE.md first.

7. Running claude with the first-prompt template in §0 makes Claude Code recite the architecture lock back correctly.

8. CI has a claude-rules-lint step that fails if CLAUDE.md is missing or the architecture-lock block was changed.

9. The in-app Claude Code provider (page 06) and the developer-side CLI share the same .claude/RULES.md and never diverge.

10. No file under .claude/ references PostgreSQL, pgvector, Nginx, Apache, or PHP-FPM.

15. Open questions

1. Should we ship a claude-code-doctor artisan command that verifies §14 in CI and locally?

2. Should /push-prep automatically open a pre-filled PR description from docs/CHANGELOG_AI.md?

3. Should the in-app provider also write to .claude/CHANGELOG_AI.md so a developer can replay what happened, or keep that strictly inside agent_events?

16. Refactor & repolish playbook (every pass)

This is the playbook for every "refactor + repolish the whole project" pass. It is what a developer or Claude Code session should follow when given a prompt of the form "Perform a high-end refactoring and documentation repolish of this project." It guarantees the result is documented, safe, and architecture-lock-conformant.

16.1 Inspect first (no edits yet)

Open these in order and capture a one-line finding for each in docs/INSPECTION.md:

composer.json        → Laravel version, PHP constraint, package list (Filament, Livewire, Sanctum, Reverb, Horizon, Pint, Pest/PHPUnit)
package.json         → Node version, Vite, Tailwind, Alpine, editor libs
.env.example         → DB driver (must be mysql/mariadb), queue (redis), broadcaster (reverb), AI key placeholders, workspace root, model defaults
config/              → agent_workspace.php, services.php, database.php, queue.php, broadcasting.php, sanctum.php, filesystems.php
database/migrations/ → every file, every table, every column, every FK, every JSON column, every softDelete
app/Models/          → every model + relations; diff against migrations
routes/web.php, routes/api.php, routes/channels.php, routes/console.php
app/Http/Controllers/ → every controller + action; form requests + resources used
app/Services/        → every service, responsibility, models touched, external APIs, callers
app/Jobs/, app/Events/, app/Listeners/, app/Http/Middleware/, app/Policies/
app/Console/Commands/ → must include agent-workspace:diagnose
resources/views/, resources/js/ (especially resources/js/ai-text-editor/)
public/              → only public/ is webroot; .env, .git, storage/ denied
tests/               → Pest/PHPUnit + iOS parity contract
.claude/, .cursor/, CLAUDE.md, HOW TO START.md → match this page + C2
docs/                → match the 28-doc set in §17 below

Output format of docs/INSPECTION.md:

• Laravel version, PHP version, DB driver, queue driver, broadcaster.

• Counts: models, migrations, controllers, routes (web + api), services, jobs, events, listeners, middleware, policies, commands, tests.

• Drift table: file present? doc present? doc up to date? (✅ / ⚠️ / ❌).

16.2 Produce the plan

Write docs/REFACTOR_PLAN.md with this exact structure, then stop:

1. Findings (versions, modules, gaps).

2. Architecture-lock drift (every file mentioning Nginx / Apache / PHP-FPM / Postgres-first / mobile-only / Swift core logic — listed for cleanup).

3. Refactor targets (controllers > 200 lines → service; hardcoded settings → server params; duplicated logic → shared service; missing model relations → add).

4. Doc gaps (which of the 28 docs are missing, partial, stale).

5. DB risk list (missing FK, missing index, missing softDelete, missing model relation, JSON column without schema notes).

6. RAG readiness (rag_chunks present? indexer wired? EmbeddingStorageInterface in place?).

7. Agents & skills (which .claude/agents/* and app/Services/Skills/* exist vs. spec).

8. Rules (.claude/*.md and .cursor/rules/*.mdc present vs. C2 §20–21).

9. Sequenced change list (ordered, small, reversible PRs; each has scope, files, tests, docs).

10. Out of scope (explicit list of what this pass will NOT touch).

Wait for the human to approve the plan before any edit.

16.3 Implement in small PRs

One concern per PR. Each PR includes: code + tests + docs + docs/CHANGELOG_AI.md entry. No mixed PRs. Run /ci-check before /push-prep on every PR.

16.4 Hard rules during a refactor pass

• Read docs before touching code. If a doc is missing, write the doc first.

• Compare models against migrations before changing relations.

• Never modify a committed migration; add a new one.

• Never edit .env. Edit .env.example + document the new variable in docs/SERVER_PARAMS.md.

• Never push. Open a PR. Push is a human action.

• Update docs/CHANGELOG_AI.md in the same PR as the change.

• Stop and ask the user when: a destructive command is needed, an FK direction is unclear, an architecture-lock item would be violated, or a secret is about to appear in output.

16.5 Definition of done

A refactor pass is done only when:

1. docs/INSPECTION.md and docs/REFACTOR_PLAN.md exist and are current.

2. All 28 docs (see §17) exist with Status: and Last reviewed: set; none are empty stubs.

3. The verbatim architecture-lock block appears in CLAUDE.md, .claude/RULES.md, .claude/ARCHITECTURE_LOCK.md, .claude/PROJECT_CONTEXT.md, docs/PROJECT_CONTEXT.md, and the master hub callout. claude-rules-lint CI step is green.

4. No remaining doc, comment, or config references Nginx, Apache, PHP-FPM, PostgreSQL-as-default, or pgvector-as-default outside of an explicit "future opt-in" note.

5. php artisan agent-workspace:diagnose returns all PASS or documented WARN.

6. php artisan route:list, php artisan migrate:status, php artisan test all run; output captured in docs/INSPECTION.md.

7. Every model has its relations declared and matches the migration.

8. Every controller action has at least one feature test or is documented as Status: Untested with an issue link.

9. docs/CHANGELOG_AI.md has an entry summarising the pass.

10. No secret value appears in any doc, log, RAG chunk, or API response (verified by php artisan rag:audit + php artisan security:scan).

16.6 Final report template (paste at the end of every refactor pass)

# Refactor & repolish pass — <date>

## 1. What was refactored
## 2. What documentation was expanded
## 3. Database relations status (tables touched, new relations, needs-verification)
## 4. RAG status (index runs, chunks added/updated/removed, audit secret matches: 0)
## 5. Agents status (wired / pending)
## 6. Skills status (wired / pending)
## 7. Rules status (.claude/ + .cursor/rules/*.mdc updated)
## 8. Claude Code setup status (CLAUDE.md verbatim, claude-rules-lint green, claude:doctor green)
## 9. Cursor rules status
## 10. LiteSpeed/CentOS docs status (no Nginx/Apache/PHP-FPM references)
## 11. AI Selection Editor (F1) status
## 12. Security improvements (secrets in repo: 0; routes without ability: 0; re-auth gated routes listed)
## 13. Files created
## 14. Files updated
## 15. Commands run (route:list, migrate:status, test, diagnose)
## 16. Tests run and results
## 17. Known risks
## 18. Next recommended tasks

Do not finish with vague text. Finish only when the project has high-end documentation, clear DB relations, RAG-ready structure, agents/skills/rules docs, and a safe Claude Code workflow.

17. The 28-doc documentation set

Every doc starts with Status: Planned | Partial | Implemented and Last reviewed: YYYY-MM-DD. No empty stubs. Exact body of every doc is specified in C2 — Claude Code Project Bundle (Part B, §15 onward).

18. php artisan agent-workspace:diagnose

Single command, run locally and in CI. Returns PASS / WARN / FAIL per check.

[ ] OS is CentOS-compatible (or note Docker/macOS dev box)
[ ] LiteSpeed detected (prod) / `php artisan serve` OK (dev)
[ ] PHP 8.3.x + required extensions (mbstring, pdo_mysql, redis, zip, gd, intl, openssl, opcache, xml)
[ ] MySQL/MariaDB connection (driver must be mysql/mariadb)
[ ] Redis ping
[ ] Horizon process alive
[ ] Reverb process alive
[ ] Scheduler entry present
[ ] OpenAI API key present (in server_params or .env; never in resource output)
[ ] Claude API key present
[ ] Claude Code CLI binary on PATH (in-app provider)
[ ] Git binary on PATH
[ ] Composer binary on PATH
[ ] workspace root /var/lib/agent-workspaces writable
[ ] storage/, bootstrap/cache writable; permissions != 777
[ ] rag_chunks table exists + most recent rag_index_runs row is < 24h old
[ ] docs/ writable
[ ] api/v1 routes resolve (php artisan route:list | grep api/v1)
[ ] api/v1/runs/{run}/stream SSE responds (smoke test with curl)
[ ] server_params seeded
[ ] snapshots directory writable
[ ] CLAUDE.md and .claude/ bundle present and lint-clean (claude-rules-lint)
[ ] AI selection editor mount present in layouts/app.blade.php
[ ] iPhone parity contract test green
[ ] No file in repo matches secret regex (sk-..., ghp_..., AWS keys, JWTs)
[ ] No RAG chunk matches secret regex (php artisan rag:audit)

Output is JSON when --json is passed (used by Api\HealthController). Each check returns {name, status: PASS|WARN|FAIL, detail?}.

19. Acceptance criteria — Claude Code-ready repo (re-stated)

In addition to §14:

1. docs/INSPECTION.md is current after every refactor pass.

2. docs/REFACTOR_PLAN.md exists for the in-flight pass (deleted once the pass merges).

3. All 28 docs in §17 exist with Status: + Last reviewed:.

4. php artisan agent-workspace:diagnose returns all PASS or documented WARN.

5. The Final Report (§16.6) is filled in for every refactor pass and attached to the cover PR.

<!-- ORPHAN-TAIL-DROP -->

18. php artisan agent-workspace:diagnose

Single command, run locally and in CI. Returns PASS / WARN / FAIL per check.

[ ] OS is CentOS-compatible (or note Docker/macOS dev box)
[ ] LiteSpeed detected (prod) / `php artisan serve` OK (dev)
[ ] PHP 8.3.x + required extensions (mbstring, pdo_mysql, redis, zip, gd, intl, openssl, opcache, xml)
[ ] MySQL/MariaDB connection (driver must be mysql/mariadb)
[ ] Redis ping
[ ] Horizon process alive
[ ] Reverb process alive
[ ] Scheduler entry present
[ ] OpenAI API key present (in server_params or .env; never in resource output)
[ ] Claude API key present
[ ] Claude Code CLI binary on PATH (in-app provider)
[ ] Git binary on PATH
[ ] Composer binary on PATH
[ ] workspace root /var/lib/agent-workspaces writable
[ ] storage/, bootstrap/cache writable; permissions != 777
[ ] rag_chunks table exists + most recent rag_index_runs row is < 24h old
[ ] docs/ writable
[ ] api/v1 routes resolve (php artisan route:list | grep api/v1)
[ ] api/v1/runs/{run}/stream SSE responds (smoke test with curl)
[ ] server_params seeded
[ ] snapshots directory writable
[ ] CLAUDE.md and .claude/ bundle present and lint-clean (claude-rules-lint)
[ ] AI selection editor mount present in layouts/app.blade.php
[ ] iPhone parity contract test green
[ ] No file in repo matches secret regex (sk-..., ghp_..., AWS keys, JWTs)
[ ] No RAG chunk matches secret regex (php artisan rag:audit)

Output is JSON when --json is passed (used by Api\HealthController). Each check returns {name, status: PASS|WARN|FAIL, detail?}.

19. Acceptance criteria — Claude Code-ready repo (re-stated)

In addition to §14:

1. docs/INSPECTION.md is current after every refactor pass.

2. docs/REFACTOR_PLAN.md exists for the in-flight pass (deleted once the pass merges).

3. All 28 docs in §17 exist with Status: + Last reviewed:.

4. php artisan agent-workspace:diagnose returns all PASS or documented WARN.

5. The Final Report (§16.6) is filled in for every refactor pass and attached to the cover PR.