Skill: /init-references

Usage

/init-references

Run from the project root.

Purpose

/init-references is the most important step in this repository.

Its job is to create the durable project maps in references/ so future Claude Code tasks can read those maps first instead of repeatedly re-reading the whole codebase.

Core rules

1. Read before write. Explore the real project first. Never invent files, routes, tables, hooks, screens, services, or conventions.
2. Generate only applicable files. Absent reference files mean the stack is not present in this repo.
3. Do not overwrite existing maps. By default, create only missing, applicable files. If a map already exists, keep it.
4. Be stack-aware. A repo can contain Laravel, React, React Native, or any combination of them across root or monorepo app folders.
5. Mark uncertainty clearly. Use [REVIEW NEEDED] when the code does not support a confident conclusion.
6. Stay compatible with Claude Code. If the current session is in read-only planning mode, stop after the bootstrap summary instead of writing files.

Applicability matrix

• references/schema.md → create when Laravel-style migrations or a database schema source are present
• references/backend_map.md → create when Laravel backend code is present
• references/frontend_map.md → create when React web or frontend code is present
• references/mobile_map.md → create when React Native / Expo code is present
• references/methodology.md → create for every supported project because the workflow still needs a conventions map

Workflow

1. Pre-flight

• Confirm the command is running from the project root
• Ensure references/ exists; create it if needed
• Record which reference files already exist

Output a compact pre-flight table:

INIT-REFERENCES PRE-FLIGHT
  references/schema.md        -> missing | exists | not applicable
  references/backend_map.md   -> missing | exists | not applicable
  references/frontend_map.md  -> missing | exists | not applicable
  references/mobile_map.md    -> missing | exists | not applicable
  references/methodology.md   -> missing | exists

2. Detect stack roots

Inspect the repository root and common monorepo folders such as apps/*, packages/*, and services/*.

Detect each stack independently:

• Laravel: composer.json contains laravel/framework, plus expected app folders such as app/, routes/, or database/
• React web: package.json contains react, and the app is not only a React Native app
• React Native: package.json contains react-native, or the app has Expo or native mobile roots such as app.json, android/, or ios/
• Frontend-only: HTML/CSS/JS app structure without Laravel or React Native

For monorepos, list each detected app root and keep those roots visible in the generated reference files.

3. Explore only the applicable stack(s)

Laravel exploration

• Migrations and schema sources
• Routes and route groups
• Controllers, services, actions, repositories, models, jobs, events, notifications, API resources, policies, middleware, and auth flow

React / frontend exploration

• App root, routing, pages, components, stores, hooks, services, shared types, API client setup, forms, styling, and testing approach

React Native exploration

• Expo or native config, navigators, screens, platform-specific files, storage, app services, build config, and mobile-specific constraints

Methodology exploration

• Naming conventions
• Architecture patterns
• State-management patterns
• API response patterns
• Testing conventions
• Security constraints
• Existing repository workflow conventions that should guide future tasks

4. Decide what to create

Create only the missing files that are applicable for the detected stack(s).

If every applicable file already exists, output:

All applicable reference files already exist.
This project is already bootstrapped.
Use /update-references auto after code changes.

If a new stack was added later, create only the newly applicable missing maps.

5. Write the files

Write the missing files using the formats below.

Required file formats

references/schema.md

Include:

• project/app root for the schema source
• one section per table
• columns, types, nullability, defaults, key notes
• relationship notes where they can be traced confidently
• schema gotchas or review-needed items

Suggested structure:

# Database Schema Reference

## Overview

## {table_name}
| Column | Type | Nullable | Default | Notes |
| --- | --- | --- | --- | --- |

**Relations**
- belongs to:
- has many:

## Known Issues / Gotchas

references/backend_map.md

Include:

• Laravel app root(s)
• route groups and important endpoints
• controller → service/action/repository flow
• key models and relationships
• auth, middleware, queue, event, and resource notes when present
• backend gotchas

Suggested structure:

# Laravel Backend Map

## App Roots

## Routing Overview

## Route Flow Map

## Controllers

## Services / Actions

## Repositories

## Models

## Jobs, Events, Notifications

## Auth / Middleware Notes

## Known Issues / Gotchas

references/frontend_map.md

Include:

• web app root(s)
• routing and page structure
• state stores
• data-fetching hooks and services
• significant shared components
• important types/interfaces
• frontend gotchas

Suggested structure:

# Frontend Map

## App Roots

## Routing

## API Configuration

## Stores

## Hooks

## Pages

## Shared Components

## Types / Interfaces

## Known Issues / Gotchas

references/mobile_map.md

Include:

• mobile app root(s)
• navigation structure
• screens inventory
• Expo/native plugins and device integrations
• storage and auth notes
• platform-specific files or caveats
• mobile gotchas

Suggested structure:

# Mobile Map

## App Roots

## Navigation

## Screens

## Services

## Storage / Auth

## Platform-Specific Notes

## Build Configuration

## Known Issues / Gotchas

references/methodology.md

Include:

• the project's preferred architecture patterns
• naming conventions and file placement rules
• stack-specific working rules
• testing expectations
• security rules
• known gaps that future tasks should treat carefully

Suggested structure:

# Project Methodology

## Core Philosophy

## Laravel Standards

## React / Frontend Standards

## React Native Standards

## Naming Conventions

## Testing Conventions

## Security Rules

## Known Gaps / Review Needed

Completion report

After writing, report exactly which files were created, skipped, or marked not applicable.

End with:

/init-references complete
Next step: use the generated references as the primary map for planning and
implementation, then run /update-references auto after code changes.