/laravel-knowledge

Generates a Claude Code knowledge layer for a Laravel repo: a tiny always-loaded CLAUDE.md, a code-verified knowledge base in .ai/, and four project-specific subagents that tell themselves which .ai/ files to read. Named laravel rather than php because it relies on Laravel structure (routes, artisan, jobs, Kernel, phpunit).

Usage

/laravel-knowledge [path]       # create (or revise) the knowledge layer for a Laravel repo

Output

CLAUDE.md                       minimal guide + "read on demand" table + agents table
.ai/AGENTS.md                   index and orientation path
.ai/project.yaml               machine-readable facts
.ai/domain/*.md                 architecture, codebase-tour, known-gotchas, + subsystem files
.ai/danger-zones.yaml           only with evidence
.claude/agents/{dev,review,qa,architect}.md
.claude/settings.json           deny Read on vendor, logs, .env (merge, never clobber)

Steps

1. Facts (deterministic). Run python3 ~/.claude/skills/laravel-knowledge/scripts/laravel_facts.py <repo> for versions, datastores, loaded vs dead route files, symlinked dirs in app/, commented-out middleware, scheduler size, phpunit DB overrides, default branch, possible hardcoded-credential files (paths only). --project-yaml prints a draft .ai/project.yaml. It never reads .env.
2. Graph/wiki (optional). If /project-knowledge is installed: python3 ~/.claude/skills/project-knowledge/scripts/build_knowledge.py <repo> and read .ai/wiki/code-wiki.md for hub files instead of re-exploring.
3. Check existing state. If CLAUDE.md, .ai/, or .claude/agents/ already exist, revise them; never delete user content. Keep a copy as CLAUDE.original.md before restructuring an existing CLAUDE.md.
4. Write .ai/ following templates/domain-outlines.md: start with known-gotchas.md (verify each suspicious fact in code: dead routes, disabled middleware, observers registered or not, shared symlinks, test DB behaviour), then architecture.md, then the subsystem files the facts justify. Every claim cites file:line or says TODO: Domain owner input required. Use project.yaml from step 1, adding only evidenced keys (infrastructure, commands.lint, git.branch_pattern).
5. Write CLAUDE.md from templates/CLAUDE.md: concise, no restated lint rules, domain table pointing only at files that exist, the top operational risks inline.
6. Write agents from templates/agents/*.md. Fill every {{PLACEHOLDER}} from facts and .ai/; delete sections for datastores the repo lacks; replace template-style rules with ones you confirmed. Do not copy rules from another project: hand-written agents often name files that are dead or nonexistent (a legacy app/Http/routes.php, a missing layout) and contradict CLAUDE.md. Verify every path you name. Keep persona names Arjuna/Vidura/Yudhishthira/Krishna. Each <!-- FILL: ... --> comment is an instruction: replace it with real content (or delete the section), never leave it.
7. Settings and danger zones. Merge templates/settings.json deny rules into .claude/settings.json. Write .ai/danger-zones.yaml (template) only for entries with evidence.
8. Check. grep -rn '{{\|FILL:' CLAUDE.md .ai .claude must return nothing. Grep every path mentioned in CLAUDE.md and the agents with ls; confirm no secret values appear anywhere; confirm CLAUDE.md is under ~150 lines. Report what was written and every TODO left for the domain owner. Do not commit. Note that CLAUDE.md and .claude/ may be git-excluded locally (.git/info/exclude).

Rules

• Evidence only: imports, config, routes, tests, git history. Unknown stays unknown.
• Stale knowledge is worse than none: prefer a short true file to a long guessed one.
• Never read or reproduce .env values or hardcoded credentials; cite the file path only.
• Persona/agent content is project-specific; templates are structure, not facts.