HOW-TO-START-Claude-Code-Guide

⚡ Easy Mode — the 5-minute version

If you want the short version, this is it. Read §1–§16 below only when something breaks.

E.1 · The 3 commands to start (literally)

cd agent-workspace
claude
# paste §10.3 prompt (from master hub) → enter → approve plan → ship

That is the whole workflow. Everything else on this page is a safety net for when this loop doesn’t “just work.”

E.2 · Where each kind of documentation lives (one map)

This is the only folder map you need. Every Notion spec mirrors 1:1 to a docs/ file. Claude reads only docs/ — never Notion directly. You (the human) update Notion; CI verifies the docs/ mirror is in sync.

Rule of thumb. New doc? Add the Notion page first (master hub or STV sub-pack), add a row in §SoT.5 with its sync_targets, then let Claude generate the matching docs/*.md. Never write a fresh docs/*.md without a Registry row pointing to it — spec-registry-lint will fail the PR.

E.3 · Connections / integrations to enable (one-time)

Everything below is optional except #1 and #2. Add the rest as you grow.

Hard rule: every MCP server must be listed in .claude/settings.json under mcpServers. If it isn’t listed there, Claude Code won’t connect to it. Same allowlist principle as for bash.

E.4 · What goes in .claude/RULES.md (paste verbatim)

This is the canonical RULES.md body. It is the file Claude Code reads on every turn. Keep it short, declarative, and copy-pasteable. The architecture-lock block must match the master hub callout byte-for-byte (CI checks).

# RULES.md (canonical, Claude Code reads this every turn)

## 1. Identity
You are Claude Code running inside the agent-workspace repo. You are not a chatbot.
You are the in-repo coding agent for the AI Coding Agent Workspace project
(SPEC-HUB v1.4.0+) and the STV sub-pack (SPEC-STV-HUB v1.3.0+).

## 2. Doctrine read order (every turn, before any output)
1. CLAUDE.md (repo root)
2. .claude/RULES.md (this file)
3. .claude/PROJECT_CONTEXT.md
4. .claude/TOOLS.md
5. .claude/WORKFLOW.md
6. docs/SPEC_REGISTRY.md
7. docs/00-product-overview.md
8. The specific docs/<SPEC-ID>.md you are about to touch
9. .cursor/rules/*.mdc (if present)

## 3. SoT ladder (conflict resolution)
Constitutional > Architecture > Specification > Implementation > Reference.
If two specs disagree, stop and ask. Do not invent a third answer.

## 4. Architecture lock (verbatim — byte-identical to master hub callout)
- OS: AlmaLinux 9 / Rocky Linux 9, SELinux enforcing.
- Web server: LiteSpeed (LSWS) + lsphp 8.3 LSAPI.
  Never Nginx. Never Apache. Never PHP-FPM.
- App: Laravel 11 (12 when GA).
- SQL: MySQL 8 or MariaDB 11.4+. Never PostgreSQL as default.
  pgvector is opt-in only.
- Cache / queues / locks / pub-sub: Redis 7.
  Workers via Laravel Horizon. Realtime via Laravel Reverb (WS) + SSE.
- Auth: session (web) + Laravel Sanctum (API).
- Admin: Filament v3 (admin only, never end-user surface).
- Storage: S3-compatible (AWS S3 / R2 / MinIO) with signed URLs.
- AI: OpenAI + Anthropic accessed only via backend services
  (app/Services/Ai/**, app/Services/Agents/**). Never from JS, never from Swift.
- Mobile: iPhone (SwiftUI) is post-v1. Mobile-web must be excellent first.

## 5. Hard forbids (refuse, never execute)
Nginx, Apache, PHP-FPM, PostgreSQL-as-default, Qdrant, Milvus, Weaviate,
Android client, multi-tenant in v1, direct AI calls from JS or Swift,
controllers > 200 LOC, raw HTML from the editor without sanitization,
SELECT * on hot paths, unsigned URLs for private files,
public share links without a token, any Notion branding / logo / exact UI /
proprietary design / icon set.

## 6. Behavioural rules
- Plan before code. Output a numbered plan, then wait for approval.
- One Spec ID per PR. PR title: SPEC-<id>: <short summary>.
- Files touched MUST be inside that spec’s sync_targets in docs/SPEC_REGISTRY.md.
- If the spec content changed, bump the Registry row (major.minor.patch) in the same PR.
- Append exactly one line per PR to docs/CHANGELOG_AI.md, format:
  <YYYY-MM-DD> | SPEC-<id> | <role> | <semver> | <one-line summary>
- Branch name: agent/run-{run_id}-{slug}. Never main, never master.
- Never git push. Stage + commit only. The human pushes after review.
- Never edit Notion from the repo. Source of truth for code is docs/*.md.
- Preview gate is mandatory for any AI text edit to user content. Never auto-apply.
- Architecture+ tier changes require two-eyes review.
- Pre-run + pre-command snapshots (tar + commit hash) before any change.

## 7. Product-line firewall
Product line A (AI Coding Agent platform):
  domain object Run, namespace app/Services/Agents/**.
Product line B (AI-Powered Documentation Workspace, STV):
  domain object Page, namespace app/Services/Pages/**.
No cross-imports. Cross-line data flows go through the signed-token bridge
defined in §9.5 of the master hub.

## 8. Allowlist obedience
Only propose shell commands matching .claude/settings.json tools.bash.allow.
If a command is not on the allowlist, propose it as a plan item and ask the human
to add it via a Registry PR. Never bypass.

## 9. First action of every session
1. Run: php artisan agent-workspace:diagnose (or list what is missing).
2. Read docs/SPEC_REGISTRY.md, find the next Planned spec in priority order.
3. Output: current phase (P0–P13), next Spec ID, numbered plan, proposed branch name.
4. Wait for approval before any file edit or shell command.

Drop that into .claude/RULES.md, commit as SPEC-C2: seed RULES.md from spec, append the CHANGELOG_AI line. Done.

E.5 · What goes in .claude/skills/ (the 5 skills you need)

Claude Code “skills” are short, named, repeatable behaviours that Claude can invoke without you re-typing instructions. Each skill lives as a single .md file in .claude/skills/ and is auto-discovered.

Minimal skeleton for a skill file (use this shape for all 5):

---
name: pick-next-spec
description: Pick the next Planned spec from the Registry and produce a plan + branch.
triggers:
  - session_start
  - user_says: "what's next" | "pick next spec" | "next"
---

When invoked:

1. Read docs/SPEC_REGISTRY.md.
2. Filter rows where Status == "Planned" AND Phase == <current phase from PROJECT_CONTEXT.md>.
3. Sort by Priority (P0 > P1 > ...).
4. Pick the first row. Print: Spec ID, Title, Owner, sync_targets.
5. Propose a numbered plan (max 7 steps) and a branch name agent/run-{timestamp}-{spec-id-slug}.
6. Stop. Wait for the human to type "approved, proceed" or a correction.

That’s the entire shape. Repeat for the other 4 with their own logic.

E.6 · The 3 micro-prompts you’ll use 90% of the time

After the big §10.3 prompt has been pasted as turn 1 of a session, these are the only follow-ups you usually need. Copy-paste verbatim.

Micro-prompt #1 — “What’s next?”

What's next? Pick the lowest-priority Planned spec in the current phase from docs/SPEC_REGISTRY.md. Output Spec ID, sync_targets, numbered plan (max 7 steps), branch name. Wait for approval.

Micro-prompt #2 — “Approved, ship it.”

Approved. Proceed step by step. Pause after each shell command for my OK. After the last edit, run /run-ci-locally. If green, /open-pr. Do not git push.

Micro-prompt #3 — “Mirror this Notion page”

Mirror Notion page <URL or Spec ID> into its sync_target docs/*.md. Run spec-registry-lint. Bump the Registry row (patch). Append a CHANGELOG_AI line. Open a PR titled SPEC-<id>: mirror Notion update. Do not git push.

If you ever feel like writing a longer prompt: stop, check whether one of these three covers it, and only escalate if it doesn’t.

⭐ The one-paragraph mental model (read once, then refer back)

You are running a documented, deterministic, low-surprise build. The Notion spec pack is the human source of truth — humans edit pages there, reviewers approve there, governance lives there. The docs/ folder in the repo is the machine source of truth — Claude Code reads only docs/, never Notion directly. The docs/SPEC_REGISTRY.md file is the index that maps every Spec ID to its sync_targets, version, owner role, and status. The .claude/ folder is the operating system for Claude Code: RULES.md is behaviour, PROJECT_CONTEXT.md is identity, TOOLS.md is permissions, WORKFLOW.md is procedure, skills/ is repeatable actions, commands/ is slash commands. Every PR cites exactly one Spec ID, touches only files inside that spec's sync_targets, bumps the Registry row if the spec content changed, and appends one line to docs/CHANGELOG_AI.md. git push is always a human action. CI guards the architecture lock (claude-rules-lint), the Registry integrity (spec-registry-lint), the mirror SHA-256s (docs-mirror-lint), and the secret hygiene (secrets-scan). If you internalize that paragraph, the rest of this guide is a safety net for when the loop doesn't "just work."

⭐⭐ The five questions every session must answer (in order, before any edit)

1. Which phase am I in? Read docs/SPEC_REGISTRY.md and docs/00-product-overview.md. Phases are P0–P13 across both product lines.

2. Which Spec ID am I touching? Pick the lowest-priority Planned row in the current phase; cite it in the branch name and PR title.

3. What are the sync_targets for that Spec ID? Anything outside those globs is out-of-scope; flag it and stop.

4. What does the architecture lock say? Re-read the verbatim block in CLAUDE.md §1. If your plan contradicts it, your plan is wrong — not the lock.

5. Who reviews this? Pick a reviewer of a different role from the spec owner; Architecture+ tier requires two eyes.

If any of these five answers is unclear, stop and ask the human. Do not invent the answer. Inventing the answer is the most common cause of drift.

0 · What Claude Code is in this project

Claude Code is not a chatbot. In this project it is the in-repo coding agent that takes a Spec ID from the Registry, reads the matching Notion spec (mirrored into docs/), plans, asks for approval, edits the right files in the right namespace, and opens a PR. It refuses to push, refuses to touch the wrong product line, and refuses to install anything on the forbidden list (Nginx, PHP-FPM, PostgreSQL-as-default, etc.).

It drives two product lines under one master hub:

• Product line A — AI Coding Agent platform (operator surface for code).

• Product line B — AI-Powered Professional Documentation Workspace (STV sub-pack, end-user documentation OS).

It never blurs their domain objects (Run belongs to A; Page belongs to B).

1 · Prerequisites (one-time, per machine)

1. OS. macOS, Linux, or WSL2 on Windows. Anything else: use WSL2.

2. Node 20 LTS. node -v should print v20.*. Install via nvm if you don’t have it.

3. PHP 8.3 + Composer. php -v prints 8.3.*; composer -V prints any 2.x.

4. Git. git --version prints 2.40+.

5. Docker (optional but recommended). For a local MySQL 8 / MariaDB 11.4+ / Redis 7 stack that matches production.

6. Claude Code CLI. Install per Anthropic’s instructions (npm i -g @anthropic-ai/claude-code or the official installer). Then run claude doctor and confirm green.

7. Anthropic API key. Export ANTHROPIC_API_KEY in your shell rc (~/.zshrc / ~/.bashrc). Do not commit it.

8. Cursor (optional). If you prefer an IDE wrapper, install Cursor and point it at the Claude provider. Everything below works in plain CLI too.

2 · First-time repo setup (one-time, per repo)

git clone <repo-url> agent-workspace
cd agent-workspace
composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed

Then confirm the C2 bundle is present at the repo root:

test -f CLAUDE.md && \
test -f .claude/RULES.md && \
test -f .claude/PROJECT_CONTEXT.md && \
test -f .claude/TOOLS.md && \
test -f .claude/WORKFLOW.md && \
test -f .claude/settings.json && \
test -f docs/SPEC_REGISTRY.md && \
test -f docs/00-product-overview.md && \
echo "C2 OK"

If any file is missing, your first Claude Code session will create them by mirroring the Notion specs (see §6 below).

3 · Open Claude Code at the repo root

cd agent-workspace
claude

You should see the Claude Code prompt waiting for input at the repo root. Confirm working directory is the repo root, not a parent or a sub-folder — Claude needs the C2 bundle in scope.

4 · Paste THE prompt as turn 1

Open the master hub AI Coding Agent Workspace — Spec Pack → scroll to §10.3 · The prompt (verbatim — paste this into Claude Code) → copy the entire fenced block (from # Role to 4. Wait for approval before any file edit or shell command.).

Paste it as turn 1 in your fresh Claude Code session. Hit enter.

What Claude will do next (deterministic):

1. Read CLAUDE.md, .claude/RULES.md, .claude/PROJECT_CONTEXT.md, .claude/TOOLS.md, .claude/WORKFLOW.md.

2. Read docs/SPEC_REGISTRY.md and docs/00-product-overview.md.

3. Try to run php artisan agent-workspace:diagnose (or list what is missing).

4. Output: current phase (P0–P13), next Spec ID it will tackle, proposed plan, proposed Git branch name.

5. Stop and wait for your approval.

5 · Approve the plan (turn 2)

Read Claude’s plan carefully. Check:

• The Spec ID it picked matches the phase you’re actually in.

• The branch name follows agent/run-{run_id}-{slug} (never main, never master).

• The proposed file list lives inside the spec’s sync_targets (look up the row in docs/SPEC_REGISTRY.md).

• The proposed commands are all on the allowlist in .claude/settings.json (see §10 below). If a command is not on the allowlist, Claude will propose it and wait; never let it bypass.

If everything checks out, reply approved, proceed (or similar). If anything is off, reply with the correction; Claude will revise the plan and ask again.

6 · The bootstrap session (if C2 bundle was missing)

If §2 said any C2 file was missing, your first Claude Code session will produce these files by mirroring the corresponding Notion specs. The phase for this session is P0 · Foundation. Expect Claude to:

1. Open CLAUDE.md (root) and write the architecture-lock verbatim block (copy from the master hub callout titled “Architecture lock (canonical, verbatim)”). It MUST be byte-identical.

2. Write .claude/RULES.md, .claude/PROJECT_CONTEXT.md, .claude/TOOLS.md, .claude/WORKFLOW.md from the C2 spec (📁C2-Claude-Code-Bundle).

3. Write .claude/settings.json allowlist (see §10 below).

4. Write docs/SPEC_REGISTRY.md by mirroring §SoT.5 of the master hub.

5. Write docs/00-product-overview.md by mirroring page 00 of the master hub.

6. Append the first CHANGELOG_AI.md line: <today> | SPEC-C2 | developer-tooling lead | 1.0.0 | bootstrap C2 bundle from Notion specs.

At the end of the bootstrap session, run:

php artisan agent-workspace:diagnose

It should report zero drift. If not, fix what it reports before moving to P1.

7 · The day-one operating loop (every PR, every spec)

flowchart LR
	A[Pick next Spec ID<br>from docs/SPEC_REGISTRY.md] --> B[Open Claude Code at repo root]
	B --> C[Paste §10.3 prompt as turn 1]
	C --> D[Claude outputs plan + branch]
	D --> E{Plan correct?}
	E -- No --> C
	E -- Yes --> F[Approve plan]
	F --> G[Claude proposes commands<br>one by one]
	G --> H{Command on allowlist?}
	H -- No --> G
	H -- Yes --> I[Approve command]
	I --> J[Claude edits files<br>in sync_targets only]
	J --> K[Run CI locally:<br>pest + phpstan + pint +<br>claude-rules-lint + spec-registry-lint +<br>secrets-scan + agent-workspace:diagnose]
	K --> L{All green?}
	L -- No --> G
	L -- Yes --> M[Bump Registry row version<br>Append CHANGELOG_AI line]
	M --> N[Open PR: SPEC-XX: short summary]
	N --> O[Review diff → merge to main]
	O --> A

8 · Phase-by-phase prompt cheatsheet

For every phase, after Claude greets you with the plan from §10.3, steer it explicitly with a one-liner so it picks the right Spec ID. Copy-paste these as your turn 2 if needed.

9 · Slash commands you should know

These live in .claude/commands/ (or .claude/slash/ depending on Claude Code version). They are project-scoped.

10 · The .claude/settings.json allowlist

Claude Code asks for approval on every shell command, BUT it will only ever propose commands that match patterns in this allowlist. Anything not on the allowlist is auto-refused. Anything on the denylist is auto-refused even if you try to approve it.

{
  "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 *"
      ]
    }
  }
}

If you find yourself wanting to bypass the allowlist, stop. Either the spec is missing a command (add it to the allowlist via PR with a CHANGELOG_AI line) or the command should not be running at all.

11 · The Spec-ID rule (every PR)

1. Branch name — agent/run-{run_id}-{slug}. Never main.

2. PR title — SPEC-<id>: <short summary> (example: SPEC-STV-04: add 28-block JSON validator + slash menu).

3. Files touched — only paths listed under that spec’s sync_targets in docs/SPEC_REGISTRY.md. If you need to touch something outside, open a separate spec or update the Registry first.

4. Registry bump — if the spec content changed, bump its row (major.minor.patch) in the same PR.

5. CHANGELOG_AI line — one line per PR, format <YYYY-MM-DD> | SPEC-<id> | <author role> | <semver> | <one-line summary>.

6. CI gates — claude-rules-lint, spec-registry-lint, secrets-scan, Pest suite, php artisan agent-workspace:diagnose ALL green.

7. No git push from Claude — you push by hand after review.

12 · What to do when Claude wants to do the wrong thing

13 · Mini examples (copy-paste, full prompts)

13.1 · “Claude, do P0 step 1: install LiteSpeed + lsphp 8.3”

We are on a fresh AlmaLinux 9 box. Phase P0. Spec SPEC-B0.

1. Output the exact yum/dnf commands to install LiteSpeed Web Server and lsphp 8.3 (LSAPI), enable HTTP/2 + HTTP/3, configure Let's Encrypt for our domain, and create a system user `www-data` (or equivalent) with SELinux enforcing.
2. Do NOT propose Nginx, Apache, or PHP-FPM.
3. Pause after step 1 for my approval before you run anything.

13.2 · “Claude, do P3 step 1: STV migrations”

Phase P3. Spec SPEC-STV-02.

1. Output the migration plan for the 23 tables listed in §5 of the STV sub-pack (users, workspaces, workspace_members, pages, page_blocks, page_versions, documentation_databases, database_properties, database_rows, database_cell_values, database_views, comments, mentions, files, templates, tags, shares, share_links, permissions, activity_logs, ai_text_transformations, rag_chunks, settings).
2. Indexes per the spec. Soft-delete where the spec says.
3. Sync targets: database/migrations/**, docs/DATABASE_SCHEMA.md only.
4. Pause for approval before generating any file.

13.3 · “Claude, do P7 step 1: STV AI selection editor”

Phase P7. Specs SPEC-STV-08 + SPEC-STV-13.

1. Build the select-to-AI overlay on both desktop and mobile. Vocabulary verbatim: improve / rewrite / shorter / longer / simplify / professional / translate / summarize / outline.
2. Preview gate is mandatory: replace / insert below / copy / discard. AI never auto-applies.
3. SSE stream tokens from /api/v1/ai/transform. Rate-limit per user.
4. Sync targets: app/Services/Ai/**, resources/js/ai-selection/**, docs/AI_ASSISTANT.md.
5. Pause for approval before editing.

14 · Daily ritual (the human side)

1. Morning: open the master hub → §SoT.5 → pick the next Spec ID in the current phase.

2. Open Claude Code at the repo root → paste §10.3 prompt → approve plan → approve commands.

3. While Claude works, you review the diff in another pane. Push back on anything that violates §12 above.

4. When green, you bump the Registry row, append the CHANGELOG_AI line, and merge the PR.

5. End of day: tag the day’s spec IDs done in the Registry status column.

15 · Troubleshooting

16 · Links you’ll open every day

• Master hub: AI Coding Agent Workspace — Spec Pack — §SoT.5 (Registry), §9 (product-line matrix), §10 (the prompt).

• STV sub-pack: 📘AI-Powered-Documentation-Workspace — product line B (documentation OS).

• C1 — Claude Code Setup Guide: 🧭C1-Claude-Code-Setup.

• C2 — Claude Code Project Bundle: 📁C2-Claude-Code-Bundle.

• F1 — Global AI Text Selection Editor: ✨F1-AI-Selection-Editor.

• B0 — Production Infrastructure: 🖥️B0-Production-Infrastructure.

• B1 — Laravel Web App Core: 🧱B1-Laravel-Web-Core.

17 · The first two weeks (suggested onboarding plan)

A concrete two-week schedule for a new engineer joining the project. Treat this as a recommendation, not a contract; calibrate to your team's velocity, and skip any day whose acceptance criteria are already met.

§17.1 · Week 1 — read, mirror, bootstrap

• Day 1. Read this guide top-to-bottom. Skim master hub §SoT and §10. Skim the STV sub-pack §0–§4. No code yet.

• Day 2. Install prerequisites (§1). Clone the repo. Run §2 verification block. Do not open Claude Code yet.

• Day 3. Open Claude Code at repo root. Run the bootstrap session (§6). Land the C2 bundle. Confirm php artisan agent-workspace:diagnose reports zero drift.

• Day 4. Pick one Planned spec in phase P0. Use micro-prompt #1 (§E.6), approve, ship the first PR. Pair with someone for the merge.

• Day 5. Run the daily ritual (§14) end-to-end alone. Add one row to docs/CHANGELOG_AI.md. Confirm green CI.

§17.2 · Week 2 — your first Spec ID end-to-end

• Day 6–8. Pick a P1 or P3 spec (your choice of product line). Walk it from plan → CI green → merged PR over three sessions. Pause whenever the §12 table fires.

• Day 9. Mirror one Notion spec into its docs/*.md using micro-prompt #3. Confirm spec-registry-lint passes.

• Day 10. Open a Registry update PR adding a small clarification to your spec. Bump patch. Append CHANGELOG_AI.md. Get one reviewer.

By the end of week two you should be able to recite the §SoT.3 conflict ladder from memory and have at least three PRs landed under your name. If you cannot, slow down — speed without doctrine ends in drift.

18 · FAQ

Q. Can I edit Notion from inside Claude Code?

No. Notion is human-curated. If a spec is wrong, open a CHANGELOG_AI.md proposal entry, then a human applies the Notion edit. One-way mirroring (Notion → repo) is the only safe direction.

Q. What if two specs disagree?

Stop and ask. Do not invent a third answer. Follow §SoT.3 in the master hub: Constitutional > Architecture > Specification > Implementation > Reference. If they are at the same authority level, the Spec Registry assigns one canonical owner per concern.

Q. Can I add a new sync target to a spec mid-PR?

Only via a Registry update PR. Open it first, get the row bump merged, then run your code PR on top. spec-registry-lint will fail otherwise.

Q. The architecture lock says LiteSpeed but a teammate keeps proposing Nginx — what now?

Reject the proposal. The lock is verbatim and CI-enforced (claude-rules-lint). Unlocking requires a SPEC-HUB minor bump with a written rationale that survives review.

Q. Claude wants to push to remote — should I let it?

Never. git push is a deliberate human action. Stage and commit only. The human pushes after diff review.

Q. The CI is green but the spec feels wrong — do I merge?

No. Green CI proves syntactic conformance, not architectural correctness. If the spec feels wrong, open a Registry update PR and surface the concern in the same edit pass.

Q. How do I run only the lints, not the full Pest suite?

Use the /lint slash command, or manually: claude-rules-lint && spec-registry-lint && secrets-scan.

Q. The bootstrap session created files I don't recognize — is that normal?

Yes, if they appear in C2's sync targets. Walk the C2 spec (📁C2-Claude-Code-Bundle) and confirm each file matches its template. Open a Registry comment if anything looks off.

Q. Can one PR cover two Spec IDs?

Strongly discouraged. The "one Spec ID per PR" rule is what keeps the Registry honest. If you genuinely need to cross specs, split into two PRs and chain them with depends_on in the description.

Q. Where does the build prompt come from?

§10.3 of the master hub (AI Coding Agent Workspace — Spec Pack). It is the only canonical source. Mirrors live in docs/CLAUDE_CODE_BUILD_PROMPT.md; if the mirror diverges from Notion, the mirror is wrong.

Q. The STV sub-pack and the master hub disagree about a shared rule — which wins?

The master hub. §9.3 (shared doctrine) and §9.6 (conflict rule) both anchor doctrine on SPEC-HUB. The STV sub-pack version of any shared rule must either bump and update SPEC-HUB in the same pass, or revise to match.

Q. I want to run an off-allowlist command just once. Is there an override?

No. Open a Registry PR that adds the command pattern to .claude/settings.json with a rationale and reviewer; merge it; then run. The allowlist is the seatbelt.

19 · Glossary of jargon