Standards inheritance

Purpose: Documents the mechanisms by which child projects inherit framework standards, agents, and skills -- covering plugin install, legacy symlinks, manual copy, and integrity verification.

How child projects consume Framework base standards.

Plugin install (recommended)

Use the plugin install script for domain-selective inheritance:

# Install all domains (default):
bash ../framework/tools/scripts/plugin-install.sh

# Install specific domains only:
bash ../framework/tools/scripts/plugin-install.sh --domains core-pipeline,design-ui,backend-infra,testing-qa

# See available domains:
bash ../framework/tools/scripts/plugin-install.sh --list

# Rollback all framework symlinks:
bash ../framework/tools/scripts/plugin-install.sh --rollback

This creates symlinks in .claude/agents/ and .claude/skills/, plus a standards symlink.

Legacy symlink pattern

The manual symlink approach still works via backward-compatible symlinks:

# From child project root:
ln -s ../../framework/.claude/agents .claude/agents
ln -s ../../framework/.claude/teams .claude/teams
ln -s ../../framework/.claude/skills .claude/skills
ln -s ../framework/standards standards

This installs ALL domains. For selective installation, use the plugin install script above.

Turbopack protection (3 layers)

Symlinked dirs resolve outside the project root (e.g., ../framework/). Next.js Turbopack needs three guards to prevent crashes in dev mode:

1. outputFileTracingRoot in next.config.ts — Expands Turbopack's filesystem root to include the parent directory
   • Only needed for local dev (Vercel handles this automatically)
2. .gitignore entries — Tells Tailwind v4 auto-detection to skip symlinked dirs
   • No utility classes in framework files
3. @source not in app/globals.css — Belt-and-suspenders exclusion for Tailwind content scanning

If new symlinks to framework are added, they must also be added to .gitignore and @source not.

Global user-level skills (optional)

For convenience, you can create a global symlink so skills are available in sessions outside Framework child projects:

ln -sfn /path/to/framework/.claude/skills ~/.claude/skills

• What — ~/.claude/skills points to framework/.claude/skills
• Why — Makes the skills library available in any Claude Code session, even projects that aren't Framework children
• What breaks if missing — Non-child-project sessions lose skill access. Child projects are unaffected — their project-local symlinks (.claude/skills -> ../../framework/.claude/skills) are the primary, robust path
• Setup — Run framework/setup.sh or create the symlink manually

Project-local symlinks are always the canonical inheritance method. The global symlink is a convenience shortcut and does not replace per-project symlinks.

Manual copy (fallback)

For projects that can't use symlinks (deployment restrictions, different repo hosting, etc.):

1. Create CLAUDE.md

Copy base coding conventions from standards/reference/coding-conventions.md and customize with project-specific context.

2. Copy .mcp.json

cp path/to/framework/.mcp.json.example .mcp.json

Ensure LINEAR_API_KEY is set in your shell profile (personal API key from Linear Settings > API).

3. Copy PR template

mkdir -p .github/PULL_REQUEST_TEMPLATE
cp path/to/framework/.github/PULL_REQUEST_TEMPLATE/default.md .github/PULL_REQUEST_TEMPLATE/

4. Set up Linear project

Create a project in your Linear team. Connect the GitHub repo for branch detection + PR linking.

5. Create specs directory

mkdir -p docs/specs

[!IMPORTANT] When using manual copy, you must manually update CLAUDE.md whenever Framework standards change. Symlinks avoid this burden entirely.

What lives where

Content	Symlinked	Local-Only	Why
Agent definitions (.claude/agents/)	Yes (symlink)	—	Symlinked from agency-agents repo
Skills (.claude/skills/)	Yes	—	Shared capability library
Standards (standards/)	Yes	—	Core rules, teams, processes, references
CLAUDE.md	—	Yes	Project-specific instructions
.mcp.json	—	Yes	Contains local API keys (gitignored)
PR template (.github/)	—	Yes (copied)	GitHub requires in-repo
Spec artifacts (docs/specs/)	—	Yes	Project-specific

CLAUDE.md boundaries

A project's CLAUDE.md is local-only for good reason — it holds project-specific context. But it must never duplicate framework processes. When a CLAUDE.md copies review protocols, Linear workflows, or SDLC steps from the framework, those copies go stale as the framework evolves and the project ends up following an outdated process.

What belongs in project CLAUDE.md

• Project overview — Domain concepts, key integrations
• Route structure — Architecture, tech stack specifics
• Commands — pnpm dev, pnpm test, etc.
• Environment management — Vars, 1Password, Vercel targets
• Milestone roadmap
• Project-specific overrides — With rationale
• Symlinked framework files list — As a reference, not a duplication
• Pointers to framework standards — E.g., "Follow standards/core/review-protocol.md"

Scaffold extension guidance to include

When a project uses the prototype scaffold, CLAUDE.md should document:

• Scaffold boundary — Which directories are scaffold (don't modify) vs feature (your code). Reference standards/reference/coding-conventions.md § "Scaffold Extension Pattern"
• localStorage key registry — Table of all keys in use, their purpose, and owning feature
• Feature directory map — Where feature components, stores, and routes live (e.g., components/app/, lib/stores/)
• Layout integration points — Which layouts render feature shell components and where

What does NOT belong in project CLAUDE.md

• Review protocol details — Use standards/core/review-protocol.md
• Linear lifecycle / status machines — Use standards/core/linear-lifecycle.md
• SDLC phase definitions — Use standards/core/sdlc.md
• Agent delegation patterns — Defined in CLAUDE.md § "Agent Delegation"
• Linear comment formats — Use standards/core/review-protocol.md

Rule of thumb: If it's defined in a symlinked standards/ file, don't repeat it in CLAUDE.md — point to it. This keeps the framework as single source of truth and prevents drift.

Integrity verification

Symlinked inheritance means a compromised framework repo silently propagates to all child projects. Verify symlink integrity periodically:

# From child project root:
bash path/to/framework/tools/scripts/verify-inheritance.sh

The script checks that all symlinks point to the expected framework paths, that targets exist, and reports the framework repo's current commit. Pin child projects to a known framework commit when stability matters:

# In child project CI or pre-commit hook:
EXPECTED_COMMIT="abc1234"
ACTUAL_COMMIT=$(git -C ../framework rev-parse --short HEAD)
if [ "$ACTUAL_COMMIT" != "$EXPECTED_COMMIT" ]; then
  echo "Framework commit mismatch: expected $EXPECTED_COMMIT, got $ACTUAL_COMMIT"
  exit 1
fi

Overrides

Child projects can override framework defaults in their CLAUDE.md. Document the override with rationale:

## Project-Specific Overrides

- **date-fns over Luxon** — Tree-shakeable, lighter weight for this project's needs
- **No Axiom logging yet** — Not installed; using console.log temporarily (tracked in RAJ-XX)

Keep overrides minimal. If a pattern works better than the framework default across multiple projects, promote it to the framework instead.

Complete setup guide

For a comprehensive step-by-step checklist with infrastructure setup (Vercel, Supabase, Clerk, Sentry, PostHog, Axiom, CI/CD), see:

New Project Checklist