AI-Coding-Agent-Workspace-Spec-Pack

Source of Truth System

Spec Header

Every spec page (HUB, B0, B1, F1, C1, C2, 00–18) MUST open with a callout containing the block below. Filled values per page live in the Spec Registry. The same block becomes the YAML front-matter of the mirrored docs/<file>.md in the repo.

spec_id:        SPEC-<short>
title:          <human title>
version:        <semver>            # bump on every material edit
status:         Planned | Approved | In Build | Implemented | Deprecated
authority:      Constitutional | Architecture | Specification | Implementation | Reference
priority:       P0 | P1 | P2 | P3
owner_role:     <role title>        # who writes the spec
reviewers:      [<role>, <role>]    # who must sign off on changes
last_reviewed:  YYYY-MM-DD
sync_targets:                       # repo files this spec owns
  - <path or glob>
depends_on:     [<Spec ID>, ...]    # upstream specs this assumes
consumed_by:    [<Spec ID>, ...]    # downstream specs / code
conflict_rule:  <pointer to higher authority or sibling tiebreaker>
change_policy:  <who can change, what gates apply>

Authority Hierarchy

Five levels, highest first. Higher beats lower in every conflict.

1. Constitutional — the architecture-lock verbatim block in this hub. One source. Never paraphrased. Verbatim in CLAUDE.md, .claude/RULES.md, .claude/PROJECT_CONTEXT.md, docs/00-product-overview.md. Enforced by claude-rules-lint.

2. Architecture — cross-cutting decisions that constrain the whole codebase: B0 (server), B1 (Laravel core), F1 (Selection Editor), 01 (platform strategy), 02 (backend modules & data model). Change requires architect sign-off plus a Registry version bump.

3. Specification — feature-level specs: pages 00, 03–18, C1, C2. Owns concrete features, contracts, schemas, endpoints. Change requires spec owner plus one reviewer of a different role.

4. Implementation — runnable how-to: build prompts, HOW TO START, deployment runbooks, the diagnose command. Generated from Specifications; not authoritative on its own.

5. Reference — glossary, changelog, audit trail, indexes. Read-only relative to higher levels.

Conflict Resolution

1. Constitutional > Architecture > Specification > Implementation > Reference. Always.

2. Within the same level, the spec listed in the Spec Registry as canonical for a given concern wins. The loser must be revised, cross-referenced, or marked Deprecated.

3. Verbatim blocks (architecture lock, forbidden list) are sacred. If another page contradicts them, the other page is wrong by definition.

4. Two specs cannot both claim the same sync_target. The Registry assigns exactly one primary owner; others list the path under consumed_by.

5. Any change to a Constitutional or Architecture spec requires: (a) version bump in the Registry, (b) entry in docs/CHANGELOG_AI.md, (c) sign-off from a reviewer role distinct from the author.

6. When a spec flips to Deprecated, every page listing it under depends_on MUST be re-reviewed in the same edit pass.

7. If a Claude Code or Cursor session encounters a runtime conflict, it stops and surfaces the disagreement. It never silently picks one.

Sync Targets

• Paths are relative to repo root (docs/..., .claude/..., .cursor/rules/..., app/Services/..., resources/js/ai-text-editor/...).

• A spec owns the file or directory and every doc generated from it.

• Specs MAY share a directory only when file patterns are disjoint (e.g. OpenAIAgentService.php belongs to SPEC-07; ClaudeCodeAgentService.php belongs to SPEC-06).

• Generated regions inside a human-owned file are wrapped in <!-- AUTO-GENERATED:START spec=SPEC-XX --> ... <!-- AUTO-GENERATED:END -->. Anything outside the markers belongs to humans.

• Mirroring direction is Notion → repo. A Cursor/Claude Code edit may propose a change to a Notion spec via docs/CHANGELOG_AI.md, but must not edit the Notion page directly.

Spec Registry

Roles

• Product architect — owns vision, lock, registry.

• Backend architect — owns Laravel core, models, routes, DB schema.

• Database architect — owns migrations, relations, indexes.

• RAG engineer — owns indexing, embedding, retrieval, secret exclusion.

• AI workflow lead — owns agents, skills, prompts, run lifecycle.

• Frontend lead — owns Filament panels, Livewire, Console UI, F1 mount.

• iOS lead — owns Swift client, parity contract.

• DevOps architect — owns server, queues, schedule, snapshots, Git ops.

• Security lead — owns threat model, auth, abilities, audit, secret scanning.

• Developer-tooling lead — owns .claude/, .cursor/, the Claude Code CLI guide.

• Docs lead — owns doc generators, templates, CHANGELOG_AI.

A reviewer must hold a different role from the author. Two-eyes minimum for Architecture+; one-eye minimum for Specification.

Change Management

1. Draft — edit the Notion page; set status: Planned or In Build in the spec header.

2. Bump version — semver. Major = breaking spec change (sync target removed, contract renamed); minor = additive; patch = wording or clarification.

3. Update Registry — bump the row in the Spec Registry in the same edit pass.

4. Log it — append a line to docs/CHANGELOG_AI.md with <date> | SPEC-XX | <author role> | <version> | <one-line summary>.

5. Re-review dependants — every spec listed under consumed_by must be re-checked. If any breaks, either revise the dependant in the same pass or roll back.

6. Mirror to repo — only after Notion review. A repo PR may not edit Notion-owned content directly; it edits the mirrored docs/<file>.md and the matching <!-- AUTO-GENERATED:* --> blocks.

CI Enforcement

• claude-rules-lint — verifies the architecture-lock verbatim block in CLAUDE.md, .claude/RULES.md, .claude/PROJECT_CONTEXT.md, docs/00-product-overview.md. Fails CI on drift.

• spec-registry-lint — parses the Registry (mirrored to docs/SPEC_REGISTRY.md) and asserts: every sync_target exists OR is marked Planned; no two specs claim the same primary sync_target; every Spec ID referenced under depends_on exists.

• secrets-scan — runs on every PR; refuses commits matching sk-*, ghp_*, AWS access keys, JWTs.

• php artisan agent-workspace:diagnose — runtime guard; surfaces any drift between the deployed app and the active specs.

Status Legend

• Planned — spec exists, code does not.

• Approved — spec finalized, build authorized, code may be missing or partial.

• In Build — code is actively landing PRs against this spec.

• Implemented — code matches spec; CI green; doc mirrors current.

• Deprecated — spec superseded; do not consume. The replacement must be cited under consumed_by.

Rollout Plan

1. Phase 1 (done). The SoT section is live on the master hub. SPEC-HUB v1.0.0 → v1.1.0 (SoT system adopted) → v1.2.0 (sister pack adopted as idea & improvement track) → v1.3.0 (STV sub-pack physically merged as sub-page of this hub; §9 renamed to Integrated Second Product Line; STV-HUB row added to §SoT.5; "sister/peer" framing retired) → v1.4.0 (final repolish: §9 prose normalized to "product line" vocabulary throughout; §10 Production-Ready Build Prompt for Claude Code added with verbatim prompt, allowlist sketch, acceptance gates, and day-one operating loop; "one final documentation" milestone).

2. Phase 2 (next pass). Add the spec-header callout (Spec Header) to the top of every page: HUB, B0, B1, F1, C1, C2, 00–18.

3. Phase 3. Mirror the Registry into docs/SPEC_REGISTRY.md and wire spec-registry-lint into CI.

4. Phase 4. Every future page or section change opens with a Registry version bump and a CHANGELOG_AI line; no exceptions. Cross-pack changes that touch §9.3 shared doctrine require the matching edit on the sister pack in the same pass.

Versioning

Every spec page in the Registry follows strict semantic versioning. The discipline guarantees that any consumer (Claude Code session, Cursor rule, CI lint, downstream spec) can compute compatibility at a glance and decide whether a re-review is required.

• Major (X.0.0) — breaking spec change. A sync_target was removed or renamed; a contract field disappeared; an authority tier was downgraded; a depends_on edge was severed. Every spec listed under consumed_by MUST be re-reviewed in the same edit pass before the bump merges.

• Minor (1.X.0) — additive change. New sections, new sync_targets, new optional fields, clarifications that close ambiguity. Backward compatible by definition. Consumers are notified but not blocked.

• Patch (1.0.X) — wording, typo, formatting, callout color, link repair, version-drift alignment. No semantic change. No re-review required, but CHANGELOG_AI entry still mandatory.

• Rollback — version numbers are monotonic; a rollback is a new version with a Reverts: vX.Y.Z note in CHANGELOG_AI, never an in-place rewrite of the previous tag.

• Pre-release tags — vX.Y.Z-rc.N is allowed for Architecture+ tier specs during a long migration; production code never consumes a pre-release tag.

Drift Detection

Drift is any divergence between the Notion spec, the mirrored docs/<file>.md, and the deployed code. Three guards keep drift bounded:

1. Mirror lint (docs-mirror-lint) — compares the SHA-256 of each docs/<file>.md against the SHA-256 recorded in the Notion spec header (mirrored on every save). Mismatch → CI fails with a one-liner pointing at the offending Spec ID and the diff cursor.

2. Sync-target audit (sync-target-audit) — walks every sync_target glob in the Registry and asserts the path exists (for Approved+ specs) or is marked Planned (for the rest). Orphan files inside an owned glob trigger a warning to the spec owner via the daily digest.

3. Runtime diagnose (php artisan agent-workspace:diagnose) — surfaces drift between the deployed app and the active specs (missing migrations, missing env keys, missing service classes, missing slash commands, MCP server unreachable). Run on every deploy and on every Claude Code session start.

Remediation playbook: (a) determine which side is authoritative per the Authority Hierarchy; (b) open a same-pass PR that either bumps the spec or updates the code; (c) record the drift cause in CHANGELOG_AI under category drift-fix; (d) if the drift was caused by an out-of-band manual edit, write a one-paragraph note in docs/INCIDENTS.md so the team learns the exact failure mode.

Deprecation

No spec is deleted. Deprecation is a four-stage transition; skipping a stage is forbidden.

1. Marked — status: Deprecated, consumed_by rewritten to point at the replacement Spec ID. Page banner added at the top: "This spec is deprecated. See {replacement}." All downstream consumers are notified in the next daily digest.

2. Quarantined — sync_targets cleared. Any file previously owned by this spec is reassigned to the replacement in the same pass. spec-registry-lint enforces zero overlap. The page remains readable but is no longer indexed by RAG.

3. Sunset — the page is moved under the master hub's /_archive sub-page. It remains addressable by URL forever; new Claude Code sessions are instructed never to consume it. Cursor rules referencing the old Spec ID are auto-rewritten to point at the replacement.

4. Tombstoned — after one major release cycle (or 6 months, whichever is longer), the page is reduced to a single redirect callout and a CHANGELOG_AI entry. Body is preserved in Git history of the repo mirror so audits can replay any past state.

A deprecated spec may be un-deprecated only by a same-pass PR that documents why the replacement failed and re-establishes the previous spec as canonical; this is rare and requires two-eyes review at the Architecture tier or higher.

0 · TL;DR

A structured AI coding workspace where a user gives a real software task to an AI agent, and the system manages:

• project workspace (cloned repo on the server)

• code inspection (routes, controllers, models, migrations, services, jobs, events, policies, config)

• RAG context (pgvector-backed, project-scoped)

• file changes (tracked, hashed, diffed)

• terminal commands (allowlist + blocklist, sandboxed)

• Git (branch-per-run, snapshots, optional commit/push)

• snapshots and revisions (pre-run, pre-command, final)

• live console log (every event, every payload, streamed via SSE)

• automatic documentation update (PROJECT_MAP, DATABASE_SCHEMA, ARCHITECTURE_DIAGRAMS, etc.)

• multiple specialized agents (Architect, Backend, Frontend, iPhone, RAG, QA, DevOps, Documentation)

• providers: OpenAI, Claude API, Claude Code, local shell runner

• iPhone-first SwiftUI client driven by a clean REST/SSE API

It is not a chatbot. It is an execution platform with full auditability and safe recovery.

1 · Product Pillars

2 · Specification Pack Index

Sub-pages will be created below. They form the canonical documentation set:

1. 00 — Product Overview & Goals

2. 01 — Platform Strategy & Stack

3. 02 — Backend Modules & Data Model

4. 03 — Database Migrations

5. 04 — RAG System Design

6. 05 — Agent Providers & Specialized Agents

7. 06 — Claude Code Integration

8. 07 — OpenAI API Integration

9. 08 — Server Params & Configuration

10. 09 — Git Workflow & Safety

11. 10 — Auto Documentation System

12. 11 — Cursor Rules Pack

13. 12 — Console Log UI Spec

14. 13 — iPhone SwiftUI App Spec

15. 14 — API Endpoints Reference

16. 15 — Security Rules & Threat Model

17. 16 — PROJECT_MAP / DATABASE_SCHEMA / DIAGRAMS templates

18. 17 — Implementation Roadmap

19. 18 — Laravel Web Admin Panel & Control Center Spec

Build prompts (executable):

• B0 — Production Infrastructure (CentOS + LiteSpeed + Laravel + MySQL) — server-build authoritative source.

• B1 — Laravel Web App Core + SQL Database — app-skeleton authoritative source.

Global features (cross-cutting specs):

• F1 — Global AI Text Selection Editor (Notion-AI-style layer) — app-wide select-to-AI overlay across every text surface; wired into B1, B5, B6, pages 14, 15, 18.

Claude Code (developer & in-app rules):

• C1 — Claude Code Setup Guide & HOW TO START.md — the developer-side onboarding (install, first prompt, slash commands, MCP servers, safety rails, the verbatim HOW TO START.md file).

• C2 — Claude Code Project Bundle (.claude/ files) — authoritative bodies for CLAUDE.md, .claude/PROJECT_CONTEXT.md, .claude/RULES.md, .claude/TOOLS.md, .claude/WORKFLOW.md, .claude/settings.json, sub-agents, slash commands, hooks. The same bundle is loaded by the in-app ClaudeCodeAgentService (page 06) — one bundle, two surfaces.

3 · System at a Glance

flowchart LR
	Web(["Web operator<br>Filament + Livewire"]) -->|HTTPS + Reverb WS| API["Laravel API + Control Center"]
	IOS(["iPhone operator<br>SwiftUI"]) -->|HTTPS + SSE| API
	API --> Orchestrator["AgentRunOrchestrator"]
	Orchestrator --> Providers{"Provider"}
	Providers -->|OpenAI API| OAI["OpenAI"]
	Providers -->|Claude API| CLA["Anthropic"]
	Providers -->|Claude Code adapter| CC["Claude Code CLI"]
	Orchestrator --> RAG["RagContextService<br>pgvector"]
	Orchestrator --> WS["WorkspaceService<br>(isolated repo)"]
	Orchestrator --> GIT["GitService"]
	Orchestrator --> SNAP["SnapshotService"]
	Orchestrator --> DOCS["DocumentationAutoUpdateService"]
	Orchestrator --> EVT["ConsoleEventService<br>(agent_events)"]
	EVT -->|SSE / WebSocket| API
	WS --> FS[("Project workspace<br>on disk")]
	RAG --> PG[("PostgreSQL + pgvector")]
	EVT --> PG
	SNAP --> S3[("Snapshot store")]

4 · Agent Run Lifecycle

stateDiagram-v2
	[*] --> draft
	draft --> queued: start()
	queued --> running: worker picked up
	running --> waiting_for_user: agent needs input
	waiting_for_user --> running: user responds
	running --> paused: user pause()
	paused --> running: resume()
	running --> completed: final_summary
	running --> failed: fatal error
	running --> cancelled: user cancel()
	completed --> [*]
	failed --> [*]
	cancelled --> [*]

5 · Core Design Decisions

• Why Laravel 11 + Horizon + Redis + PostgreSQL + pgvector

  • Laravel 11 gives a mature HTTP/queue/auth stack and Sanctum for token auth out of the box.

  • Horizon makes long-running agent jobs observable and supervisable.

  • Redis is the event bus for SSE/WebSocket fan-out, queue backend, and short-lived locks (one agent per project workspace at a time).

  • PostgreSQL is the durable store. pgvector is preferred for rag_chunks.embedding. If the existing app is on MySQL, the abstraction layer (RagContextService) keeps the storage backend swappable.

• Why branch-per-run + snapshots

  • Every run gets its own Git branch agent/run-{run_id}-{slug}. The default branch is never modified by an agent.

  • A pre_run snapshot (tar + commit hash) is created before any change. A pre_command snapshot is created before any destructive command.

  • Restoring a snapshot is always possible without losing audit history.

• Why provider-agnostic agents

  • AgentProviderInterface abstracts OpenAI, Claude API, Claude Code, and local shell runner.

  • Same RAG, same workspace, same event log — only the model/tool layer changes.

  • Adding a new provider is a single class implementing the interface.

• Why web-first, mobile-supported

  • The Laravel Control Center is the primary operator surface: admin, RAG inspector, diff review, plan/approve, server params, audit log.

  • The iPhone app is a fully-featured remote with full feature parity — same API, same events, same actions. Parity is enforced by a CI contract test.

  • The API is designed to serve both transports cleanly: WS over Reverb for the web client, SSE for the iPhone client, both fanned out from one ConsoleEventService::publish().

  • Earlier wording called this "iPhone-first". That is superseded.

• Why LiteSpeed + lsphp on CentOS-compatible Linux

  • LSWS LSAPI is markedly faster than PHP-FPM for PHP workloads and ships native HTTP/2 + HTTP/3 (QUIC). The iPhone client benefits directly from QUIC on mobile networks.

  • CentOS-compatible (AlmaLinux 9 / Rocky 9) gives long-support RPM packaging, SELinux enforcing, and is widely supported by managed-hosting providers.

  • The full infra and tuning lives in B0; this page only references it.

6 · Top-Level Folder Layout (target)

app/
	Http/Controllers/Api/
	Models/
	Services/
		Agents/
			OpenAIAgentService.php
			ClaudeAgentService.php
			ClaudeCodeAgentService.php
			AgentRunOrchestrator.php
		Rag/
			RagContextService.php
			ProjectIndexer.php
		Workspace/
			WorkspaceService.php
			CommandExecutionService.php
			SnapshotService.php
		Git/
			GitService.php
		Docs/
			DocumentationAutoUpdateService.php
			ProjectMapService.php
			SchemaAnalyzerService.php
		Events/
			ConsoleEventService.php
	Jobs/
	Events/
	Listeners/
config/agent_workspace.php
database/migrations/
docs/
	PROJECT_CONTEXT.md
	PROJECT_MAP.md
	DATABASE_SCHEMA.md
	ARCHITECTURE_DIAGRAMS.md
	API_ENDPOINTS.md
	RAG_SYSTEM.md
	AGENT_WORKFLOW.md
	CLAUDE_CODE_INTEGRATION.md
	OPENAI_INTEGRATION.md
	SERVER_PARAMS.md
	GIT_WORKFLOW.md
	IPHONE_APP_PLAN.md
	SECURITY.md
	CHANGELOG_AI.md
.cursor/rules/
	project-overview.mdc
	architecture.mdc
	database.mdc
	rag-system.mdc
	agent-workflow.mdc
	git-workflow.mdc
	testing.mdc
	security.mdc
	iphone-first.mdc
	documentation-auto-update.mdc
.claude/
	PROJECT_CONTEXT.md
	RULES.md
	TOOLS.md
	WORKFLOW.md
ios/
	AgentWorkspace.xcodeproj/
	AgentWorkspace/...

7 · Non-Goals (explicit)

Each non-goal below is intentional. Adding any of these reopens the architecture lock and requires a SPEC-HUB minor bump with a written rationale that survives reviewer-set sign-off.

• No Android client in v1. SwiftUI iPhone is the only mobile-native surface in v1. Rationale: parity is hard to enforce across two native platforms during iPhone bring-up; mobile-web covers Android users until a dedicated Android spec is written.

• No multi-tenant org/team model in v1 — single-owner workspaces with API tokens. Rationale: tenancy invariants leak into every policy, query, and cache key; defer until the single-tenant path is hardened.

• No web IDE — file edits are applied by the agent, reviewed in diff form. Rationale: an in-app IDE would compete with Cursor / Claude Code without adding leverage; diff review is sufficient at this stage.

• No automatic push to remote. Push is always a deliberate user action. Rationale: an in-repo agent that can push can also publish bad commits; the human gate is mandatory.

• No execution of arbitrary unsigned shell commands. Allowlist only (see .claude/settings.json). Rationale: a misbehaving model plus an open shell equals a production outage; the allowlist is the seatbelt.

• No PostgreSQL or pgvector as default. Opt-in only behind the RAG abstraction. Rationale: MySQL 8 / MariaDB 11.4+ is the production lock; pgvector lives as an opt-in upgrade path for very large RAG indexes.

• No Notion branding, logo, exact UI, proprietary design, colors, design tokens, or icon set anywhere in the shipping product. Rationale: the product is an original high-end design; the inspiration is Notion-class quality, not Notion-clone surface.

• No agent self-modification of Notion content from the repo. Repo edits propose changes to Notion via docs/CHANGELOG_AI.md; humans apply them. Rationale: Notion is the human-curated source of truth; one-way mirroring is the only safe direction.

8 · Glossary

9 · Integrated Second Product Line · AI-Powered Documentation Workspace (STV)

Product Line Identity

Scope Boundary

1. No mixing of domain objects. A Run belongs to product line A (Coding Agent); a Page belongs to product line B (STV). Neither product line imports the other's tables, routes, controllers, services, or Livewire components.

2. Co-hosted in one Laravel repo, isolated by namespace. Both product lines may ship in the same Laravel repo. Each lives under its own service namespace (app/Services/Agents/** vs app/Services/Pages/**); migrations are non-overlapping; route prefixes are distinct (/api/v1/runs/* vs /api/v1/pages/*); Filament panels live under distinct route prefixes.

3. No cross-citation in RAG by default. Product line A's RAG indexes project code and coding-run history; product line B's RAG indexes user-authored documentation. A workspace in one is never a workspace in the other unless an explicit, audited bridge service is built (see §9.5 candidate #2; opt-in, off by default).

4. One user account model is allowed but not required. When both product lines ship together, identity SHOULD use one users table with role grants per product line. SSO via OAuth/OIDC is the supported alternative; no foreign-key join from one product line's tables into the other.

5. One admin surface, two Filament panels (or one with two clusters). A single operator can administer both product lines; permissions are split by Filament policy.

Shared Doctrine

• The Source of Truth system (authority hierarchy, conflict ladder, sync-target ownership, change-management protocol, CI guards).

• The architecture posture lock: MySQL/MariaDB as SQL source of truth; Redis 7; Horizon; Laravel 11/12; no PHP-FPM-as-default, no PostgreSQL-as-default, no Nginx-as-default.

• The forbidden lists (each product line maintains its own; the union is enforced project-wide — no Notion branding / logo / exact UI / proprietary design / colors / copyrighted elements anywhere in the product).

• The preview-gate principle for AI: AI never auto-applies to user content; user must explicitly accept / replace / insert / discard.

• The CHANGELOG_AI.md discipline: append-only, one line per AI-assisted change, dated, attributed by role, formatted <YYYY-MM-DD> | SPEC-<id> | <author role> | <semver> | <one-line summary>.

• The secrets hygiene rules: no provider API keys in frontend, no sk-* / ghp_* / AWS keys / JWTs in any committed file, secret-scan in CI.

Promotion Path

Cross-Pollination Ideas

1. Run report → documentation page. When a coding-agent run completes (product line A), optionally export its final report into product line B as a page under a designated workspace, with the run summary, diff, and snapshot links rendered as blocks. Owner candidate: AI workflow lead (source) + Frontend lead (target).

2. Documentation page → agent context. Allow product line A's RagContextService to read-only consume product line B's published documentation pages of a designated workspace as additional context, via a signed read-only token and a dedicated consumed_workspaces whitelist. Strictly opt-in per coding-project.

3. Selection editor parity. Both product lines ship a select-to-AI overlay (F1 in product line A; SPEC-STV-08 / SPEC-STV-13 in product line B). The prompt action vocabulary (improve / rewrite / shorter / longer / simplify / professional / translate / summarize / outline) is kept verbatim-identical across product lines so a single .cursor/rules/*.mdc AI-action lint passes in both.

4. CHANGELOG_AI line format. Standardized <YYYY-MM-DD> | SPEC-<id> | <author role> | <semver> | <summary> across both product lines so a single tool can lint both logs (now part of shared doctrine in §9.3).

5. Shared claude-rules-lint core. Extract the verbatim-block linter into a shared internal package consumed by both product lines (each product line supplies its own canonical block).

6. Public read-only documentation host. Product line B's public-page reader (tokenized link + premium mobile reader) could expose read-only run reports from product line A as a publish target. Strictly opt-in; same threat-model gates as the STV /public/{token} endpoint.

Conflict Rule

When something is genuinely shared (doctrine in §9.3) and the two product lines ever disagree, the version on this master hub (SPEC-HUB) is the doctrinal anchor for both, because the master hub defined the Source of Truth system first. Any STV sub-pack page that contradicts §9.3 must either bump its version with an explicit rationale (and update the doctrine on the master hub in the same edit pass) or revise to match. There is no silent divergence within the project.

Linked Artifacts

• STV sub-pack root: AI-Powered Professional Documentation Workspace · Spec Pack — SPEC-STV-HUB v1.3.0, Approved, nested as sub-page of this hub (project-final polish).

• STV sub-pack sub-specs (current count: 14): SPEC-STV-00 Product Overview, -01 Architecture & Modules, -02 Database Schema, -03 API Endpoints, -04 Editor System & 28 Block Types, -05 Databases / Tables, -06 Template System, -07 RAG Knowledge Base, -08 AI Writing Assistant, -09 Search, -10 Mobile & Desktop UX, -11 Sharing / Permissions / Security / Scalability / Admin, -12 Comments / Activity / Import-Export / Testing / Docs / CHANGELOG, -13 Mobile Gestures & Text Selection Editor.

• Mirror path in repo (if co-hosted): docs/RELATED_PACKS.md — generated from this section, owner Docs lead.

10 · Production-Ready Build Prompt for Claude Code

Why This Exists

The Notion pack is the spec. The repo is the implementation. The bridge between them is this prompt. It does four jobs at once: (1) it transplants the Source of Truth system into Claude's working memory, (2) it forbids the things this project bans (Nginx, PHP-FPM, PostgreSQL-as-default, etc.), (3) it routes the agent to the correct sync targets per Spec ID, and (4) it gives a phased, gated execution plan so Claude does not invent features that are not in the Registry.

How to Use

1. Clone the repo. Open Claude Code at the repo root (claude CLI, or via Cursor / IDE plugin).

2. Confirm the C2 bundle exists: CLAUDE.md, .claude/RULES.md, .claude/PROJECT_CONTEXT.md, .claude/TOOLS.md, .claude/WORKFLOW.md, .claude/settings.json, docs/SPEC_REGISTRY.md, docs/00-product-overview.md. If missing, the first session creates them from the Notion specs.

3. Paste the prompt in §10.3 as the first message.

4. Approve plans before edits. Approve commands before they run (allowlist in .claude/settings.json).

5. Every PR opened by Claude Code MUST: (a) cite one Spec ID, (b) update the matching Registry row if version changed, (c) append a CHANGELOG_AI.md line, (d) pass claude-rules-lint, spec-registry-lint, secrets-scan, the Pest suite, and php artisan agent-workspace:diagnose.

The Prompt

# Role
You are a senior staff engineer, Laravel architect, RAG engineer, SwiftUI engineer, and DevOps lead, working as the in-repo coding agent for the AI Coding Agent Workspace project. The project has TWO product lines under ONE master hub (SPEC-HUB v1.4.0+): (A) AI Coding Agent platform — operator-grade execution surface for code, and (B) AI-Powered Professional Documentation Workspace (STV sub-pack, SPEC-STV-HUB v1.2.0+) — end-user documentation OS. You implement both, but you never blur their domain objects.

# Doctrine (read in this order, then keep loaded for the whole session)
1. `CLAUDE.md` — root rules. The architecture-lock verbatim block lives here.
2. `.claude/RULES.md`, `.claude/PROJECT_CONTEXT.md`, `.claude/TOOLS.md`, `.claude/WORKFLOW.md` — the C2 bundle.
3. `docs/SPEC_REGISTRY.md` — mirror of the Notion Spec Registry. Every PR MUST cite a Spec ID from this file.
4. `docs/00-product-overview.md` and the rest of `docs/*.md` — the mirrored Notion spec pages.
5. `.cursor/rules/*.mdc` — Cursor-style rule files (also consulted by you).
You operate under the Source of Truth hierarchy: Constitutional > Architecture > Specification > Implementation > Reference. Higher beats lower in every conflict. Stop and surface conflicts; never silently pick one.

# Production stack (LOCKED — do not propose alternatives)
- OS: CentOS-compatible (AlmaLinux 9 / Rocky 9), SELinux enforcing.
- Web server: LiteSpeed Web Server + lsphp 8.3 (LSAPI). Never Nginx. Never Apache. Never PHP-FPM.
- Framework: Laravel 11 (12 when GA). Sanctum tokens for API. Filament v3 for admin only.
- SQL: MySQL 8 / MariaDB 11.4+. Never PostgreSQL as default (opt-in upgrade path only).
- Cache / queue / pub-sub / locks: Redis 7. Horizon for workers. Reverb for WS. SSE for AI token streaming.
- Storage: S3-compatible (S3 / R2 / MinIO). Signed URLs only for private files.
- AI providers: OpenAI + Anthropic accessed via `app/Services/Ai/**` and `app/Services/Agents/**`. Never call providers from JS or Swift.
- RAG: `rag_chunks` table (MySQL JSON default; pgvector opt-in via abstraction).
- Clients: Laravel web Control Center (Livewire 3 + Alpine + Tailwind for STV; Filament for product line A admin) and iPhone SwiftUI (product line A only in v1). Android is banned in v1.
- Multi-tenant org/team model: banned in v1. Single-owner workspaces with API tokens.

# Behavioural rules
- Plan before code. Output a numbered plan, then await approval before edits.
- One Spec ID per PR. Title format: `SPEC-<id>: <short summary>`.
- Bump version in `docs/SPEC_REGISTRY.md` when a spec changes; append a `CHANGELOG_AI.md` line: `<YYYY-MM-DD> | SPEC-<id> | <role> | <semver> | <one-line summary>`.
- Never edit Notion content from the repo. If a spec is wrong, open a `CHANGELOG_AI.md` proposal entry and stop.
- Never auto-apply AI text edits to user content. Preview-gate is mandatory (replace / insert below / copy / discard).
- Never push to remote. `git push` is a deliberate human action.
- Allowlist for shell commands lives in `.claude/settings.json`. If a command is not on the allowlist, propose it and wait.
- Snapshots: `pre_run` (tar + commit hash) before any run; `pre_command` before any destructive command.
- Branch per run: `agent/run-{run_id}-{slug}`. Default branch is never modified by you.
- Two-eyes review minimum for Architecture+ specs. One-eye minimum for Specification.

# Hard forbids (do not propose, do not configure, do not install)
Nginx · Apache · PHP-FPM · PostgreSQL-as-default · pgvector-as-default · Qdrant · Milvus · Weaviate · Android · multi-tenant org/team in v1 · direct OpenAI / Anthropic / Claude Code calls from JS or Swift · controllers over 200 LOC · raw editor HTML without server-side sanitization · `SELECT *` on hot paths · unsigned URLs for private files · public share links without tokenized URL · Notion branding / logo / exact UI / proprietary design / colors / copyrighted elements anywhere in the product.

# Phased build plan (deterministic; advance phase only when the previous is green)
P0 — Foundation: SPEC-B0 (server), SPEC-B1 (Laravel core), SPEC-C1+C2 (Claude bundle), SPEC-03 (migrations skeleton). Acceptance: `php artisan migrate` green; LiteSpeed + lsphp 8.3 serving HTTPS; Redis + Horizon healthy.
P1 — Coding-agent core (product line A): SPEC-02, SPEC-05, SPEC-06, SPEC-07, SPEC-09, SPEC-14, SPEC-15. Acceptance: end-to-end agent run on a test repo with snapshot + diff + Console SSE.
P2 — Coding-agent surface: SPEC-04 (RAG), SPEC-08 (server params), SPEC-10 (auto-docs), SPEC-12 (Console UI), SPEC-18 (Filament Control Center), SPEC-13 (iPhone). Acceptance: web Control Center and iPhone client both drive an agent run; parity test green.
P3 — STV foundation (product line B): SPEC-STV-01, SPEC-STV-02, SPEC-STV-03. Acceptance: users / workspaces / pages / page_blocks CRUD with autosave on web and mobile.
P4 — STV editor: SPEC-STV-04 (28 block types + version history), SPEC-STV-06 (templates). Acceptance: slash menu, drag handle, floating toolbar, autosave reliable, version restore working.
P5 — STV databases: SPEC-STV-05 (databases / tables / views). Acceptance: table / board / list / gallery / calendar views with server-side filter and sort.
P6 — STV collaboration: SPEC-STV-11 (shares, permissions, security, scalability, admin), SPEC-STV-12 (comments, activity, import / export, testing, docs, CHANGELOG). Acceptance: per-user shares + tokenized public links + Filament admin + audit log.
P7 — STV AI + RAG: SPEC-STV-07 (RAG), SPEC-STV-08 (AI writing assistant), SPEC-STV-13 (mobile gestures + selection editor). Acceptance: preview-gated AI on selection across all surfaces; RAG citations to internal pages.
P8 — STV search: SPEC-STV-09 (Meilisearch via Scout; FULLTEXT fallback). Acceptance: Cmd/Ctrl+K palette across pages / blocks / files / comments / databases.
P9 — STV mobile + desktop polish: SPEC-STV-10. Acceptance: mobile-web fluent for editor / search / share / AI / RAG.
P10 — Cross-pollination (opt-in): §9.5 #1 (Run report → STV page) and §9.5 #2 (STV page → agent context). Acceptance: signed-token bridge with audited consumption whitelist.
P11 — Hardening: secrets-scan, secret rotation runbook, rate limits, IDOR test sweep, signed-URL audit, queue retry caps, failed-job alerting.
P12 — Performance: indexes verified; N+1 sweep; cache warming; Meilisearch tuning; LSWS LSAPI process model tuned.
P13 — Release: tag; mirror Registry to `docs/SPEC_REGISTRY.md`; generate `docs/PROJECT_MAP.md` + `docs/DATABASE_SCHEMA.md` + `docs/ARCHITECTURE_DIAGRAMS.md`; build deployment artefact; smoke-test on staging; cut release notes from `CHANGELOG_AI.md`.

# First action right now
1. Run `php artisan agent-workspace:diagnose` if available; otherwise list what is missing.
2. Open `docs/SPEC_REGISTRY.md` and confirm every Spec ID above has a row.
3. Output the current phase (P0–P13), the next Spec ID you will tackle, the proposed plan, and the proposed Git branch name.
4. Wait for approval before any file edit or shell command.

{
  "tools": {
    "bash": {
      "allow": [
        "php artisan *",
        "composer install",
        "composer require *",
        "npm install",
        "npm run *",
        "git status",
        "git diff *",
        "git log *",
        "git branch *",
        "git checkout -b agent/run-*",
        "git add *",
        "git commit -m *",
        "vendor/bin/pest *",
        "vendor/bin/phpstan *",
        "vendor/bin/pint *"
      ],
      "deny": [
        "rm -rf /",
        "git push *",
        "git reset --hard *",
        "sudo *",
        "curl * | sh",
        "wget * | sh",
        "* /etc/*",
        "mysql -e 'DROP *",
        "psql -c 'DROP *"
      ]
    }
  }
}

Acceptance Gates

1. claude-rules-lint green on CLAUDE.md + .claude/RULES.md + .claude/PROJECT_CONTEXT.md + docs/00-product-overview.md.

2. spec-registry-lint green: every sync_target exists OR its spec is Planned; no two specs claim the same primary sync_target; every depends_on Spec ID exists.

3. secrets-scan green on every commit (no sk-*, ghp_*, AWS keys, JWTs).

4. Pest test suite green (feature + unit + policy + API contract + Livewire + parity).

5. CI parity test green: Laravel Control Center and iPhone client drive the same agent-run state machine identically.

6. php artisan agent-workspace:diagnose reports zero drift.

7. LiteSpeed + lsphp 8.3 + MySQL 8 / MariaDB 11.4+ + Redis 7 + Horizon + Reverb confirmed in production; HTTPS via Let's Encrypt; Supervisor managing queues; SELinux enforcing.

8. STV /public/{token} rate-limited; signed URLs only for private files; HTML sanitizer pass on every editor write.

9. CHANGELOG_AI.md lines present for every spec touched during the release.

10. No banned dependency anywhere in composer.json / package.json / server packages.

Day-One Loop

1. Open the master hub (this page). Pick the next Spec ID for the current phase.

2. Open Claude Code at the repo root. Paste the §10.3 prompt as turn 1.

3. Approve the plan on turn 2. Approve commands as they come.

4. Review the diff. Merge to main only via PR with green CI.

5. After merge: bump the Registry row version, append a CHANGELOG_AI.md line, mirror the Notion spec page if its content changed, close the issue.

6. Loop to step 1.

11 · Open issues, known gaps & next-pass agenda

The following items are deliberately tracked here at hub level rather than buried inside a single spec — they cut across the project and need explicit cross-pollination decisions. Treat this section as the canonical backlog of follow-ups; everything not here is either landed in a spec or out of scope.

Doc-System Gaps

1. C1 (C1 — Claude Code Setup Guide) orphan tail. Duplicate §17/§18/§19 footer and a DELETE_ME_ORPHAN_MARKER sentinel still present at the bottom of C1; needs a targeted cleanup pass with a safer anchor than was tried previously. Owner: developer-tooling lead.

2. C2 (C2 — Claude Code Project Bundle) Part B bodies (§15–§26) never landed. Only headings exist; the deeper sub-agent / slash-command / hook bodies are still pending. Estimated ~3500 words; should be applied in three update passes, one tier at a time, to avoid render-stripping adjacent headings.

3. §10.4 heading was stripped during a previous render of this page; restore via a small targeted edit with safer fencing — do not re-paste the §10.3 prompt block in the same pass.

4. SoT spec-header callout rollout (Spec Header) still missing on 23 of 25 pages in the pack. This is Phase 2 of the Rollout Plan. Each page needs the same 12-line YAML callout at the top, filled per Registry row.

Pending Cross-Pack Ideas

1. Shared claude-rules-lint core (§9.5 #5) — extract the verbatim-block linter into a small internal package consumed by both product lines; each product line supplies its own canonical block.

2. Public read-only documentation host for run reports (§9.5 #6) — depends on STV /public/{token} rate-limiter and threat-model gates being audited first.

3. Run report → STV page (§9.5 #1) — first cross-product-line bridge; needs an audited consumption whitelist and a signed read-only token spec landed before any code touches it.

Repo Mirrors Pending

• docs/RELATED_PACKS.md — mirror of §9 of this hub.

• docs/CLAUDE_CODE_BUILD_PROMPT.md — verbatim mirror of §10.3.

• docs/HOW_TO_START.md — mirror of HOW TO START AND USE.

• docs/SPEC_REGISTRY.md — mirror of the Spec Registry.

• docs/CHANGELOG_AI.md — seed file; append-only thereafter.

All five are blocked on the first Claude Code bootstrap session (§6 of the HOW TO START guide). They are listed in C2's sync targets but produced by the repo, not by Notion.

Versioning Calendar

12 · Operating cadence & review rhythm

The Source of Truth system needs a heartbeat or it drifts. Treat the following as the doctrinal cadence; deviations require an explicit CHANGELOG_AI.md entry with a cadence-skip tag and a one-line rationale.

Daily

1. Open the master hub; pick the next Spec ID in the current phase from the Spec Registry.

2. Paste §10.3 prompt as turn 1 of a Claude Code session at the repo root.

3. Approve plan; approve commands; review diff; merge PR with green CI.

4. Bump the Registry row if the spec content changed; append a CHANGELOG_AI.md line.

5. Snapshot any pre-run / pre-command artefacts (tar + commit hash) to the snapshot store.

Weekly

1. Walk every row in the Spec Registry; flag any spec whose last_reviewed is older than 30 days.

2. Run spec-registry-lint locally on the docs mirror; reconcile any drift back into Notion in the same edit pass.

3. Read the week's CHANGELOG_AI.md lines; confirm one PR per line and no orphans.

4. Resolve any cross-product-line conflicts surfaced during the week (§9.6 ladder).

Monthly

1. Re-read the Authority Hierarchy and Conflict Resolution sections. Confirm no implicit drift in actual practice.

2. Audit the Deprecated set; remove anything that has been replaced and is no longer cited.

3. Tag a docs/SPEC_REGISTRY.md mirror release; cut release notes from CHANGELOG_AI.md.

4. Refresh the forbidden list against the current ecosystem; bump SPEC-HUB minor if anything changes.

Quarterly

1. Re-evaluate the locked stack (LiteSpeed, lsphp 8.3, MySQL/MariaDB, Redis 7) against major upstream releases. Unlock only after a written rationale lands in this hub.

2. Run a tabletop incident exercise on STV /public/{token} abuse, RAG secret exfiltration, and snapshot restore correctness.

3. Confirm secret rotation across every provider key (Anthropic, OpenAI, S3, Meilisearch admin).

4. Re-read the Change Management protocol with the full pool; calibrate where it has eroded.