Fix: Convention improvement from issue #11

[claude]

Summary

Implements the convention improvement proposed in #11 by adding clear decision framework for choosing between Inertia and JSON responses in controller endpoints.

Changes

• File modified: project-roles/skills/backend-developer/SKILL.md:46-78
• Added new section: "Controller Response Types: Inertia vs JSON"
• Includes decision table comparing use cases (dedicated pages, modals, APIs)
• Provides clear decision rule: "Does this endpoint render a full page?"
• Shows code examples of wrong vs right approach

Why This Matters

Previously, the backend-developer skill mentioned both Inertia and JSON response patterns but didn't establish clear criteria for choosing between them. This led to defaulting to JSON responses even for dedicated pages with their own routes.

The new section provides an explicit decision framework at the moment of implementation:

• Dedicated pages with own routes → Inertia responses
• Reusable dialogs/modals → JSON responses
• External API endpoints → JSON responses

Testing

The improvement is documentation-only and positions the guidance early in the skill file (before "Integration with Other Skills" section) to ensure it's seen during implementation planning.

Closes #11

🤖 Generated with Claude Code

[RasmusGodske]

@claude I don't think this should be within our backend-engineer skill. Instead it should be part of the rules of the controller.

[claude]

Claude finished @RasmusGodske's task —— View job

---

Analyzing Request

Todo List

• Read the PR changes to understand what was added
• Review CLAUDE.md architecture guidance
• Determine correct placement per plugin architecture
• Discuss approach with user
• Implement the relocation if approved

---

Analysis

You're absolutely right. According to the plugin architecture defined in CLAUDE.md:

Convention hierarchy:

1. Rules (.claude/rules/) - Single source of truth for project conventions
2. Skills - Load and apply rules; provide context on when to use patterns
3. Role Commands - Load rules and set mindset for extended work

The Inertia vs JSON decision framework is a convention/pattern that belongs in .claude/rules/backend/, not in the skill itself.

Current Problem

The PR adds this content directly to backend-developer/SKILL.md:

• Lines 26-58: First instance of "Controller Response Types: Inertia vs JSON"
• Lines 80-112: Duplicate instance (this appears to be unintentional)

This violates the architecture principle that "Rules are the source of truth" and skills should only load and reference rules.

Recommended Solution

Since this is a plugin repository (not a user project), we have two options:

Option 1: Add to laravel-vue-rules repository (Recommended)

• The setup-rules.md command clones from https://github.com/RasmusGodske/laravel-vue-rules
• We should add a new file: backend/controller-responses.md in that repository
• Update this skill to reference: "Load .claude/rules/backend/controller-responses.md for Inertia vs JSON decision framework"

Option 2: Update rules-boilerplate plugin

• Currently the setup-rules.md command clones an external repo
• We could create template files in this plugin that get written to user's .claude/rules/
• More complex and changes the plugin's current clone-based approach

My Recommendation

Option 1 is cleaner and aligns with the existing architecture:

1. Add backend/controller-responses.md to the laravel-vue-rules repository
2. Remove the Inertia/JSON section from backend-developer/SKILL.md
3. The skill's "Loading Conventions" section already instructs Claude to load all backend rules

This way:

• ✅ Rules remain the single source of truth
• ✅ Skills load and apply rules (not define them)
• ✅ Users can customize the convention in their own .claude/rules/
• ✅ Follows the separation principle

Would you like me to:

1. Remove the Inertia/JSON content from the skill file?
2. Create the content for backend/controller-responses.md that should be added to the laravel-vue-rules repository?

--- |

[RasmusGodske]

@claude I would like you give me me the content of a new rule we can add in controller-responses.md then I will update it manually

[claude]

Claude finished @RasmusGodske's task —— View job

---

Todo List

• Read the PR changes to understand current content
• Extract and adapt the Inertia vs JSON decision framework
• Format as standalone rules file content
• Provide content to user

---

Content for controller-responses.md

Here's the content for the new rules file that should be added to the laravel-vue-rules repository at backend/controller-responses.md:

# Controller Response Types

This document defines when to use Inertia responses vs JSON responses in controller endpoints.

## Decision Framework

**BEFORE implementing a controller endpoint, determine the response type:**

| Use Case | Response Type | Example |
|----------|--------------|---------|
| Dedicated page with own route | **Inertia** | Settings page, Dashboard, Detail view |
| Reusable dialog/modal | **JSON** | Confirmation dialog, Quick-edit modal |
| API consumed by external clients | **JSON** | Public API, webhook endpoints |

## The Decision Rule

**Ask: "Does this endpoint render a full page?"**
- ✅ YES → Use Inertia response with Vue page component
- ❌ NO → Use JSON response

## Examples

### ❌ WRONG - Using JSON for a dedicated page

```php
public function show(): JsonResponse
{
    return response()->json(SettingsData::from($settings));
}

Problem: This endpoint serves a dedicated page with its own route (/settings), but returns JSON instead of rendering the page via Inertia.

✅ RIGHT - Using Inertia for a dedicated page

public function show(): Response
{
    return Inertia::render('Settings/Show', [
        'settings' => SettingsData::from($settings),
    ]);
}

Why: Dedicated pages should use Inertia to render the full Vue component with proper routing, SEO, and navigation.

✅ CORRECT - Using JSON for a modal

public function quickEdit(Request $request): JsonResponse
{
    $data = SettingsData::from($request->validated());
    
    return response()->json([
        'message' => 'Settings updated',
        'settings' => $data,
    ]);
}

Why: This endpoint is called from a modal/dialog component that's reused across multiple pages. JSON is appropriate here.

Reasoning

Inertia responses are for:

• Pages that have their own dedicated route in routes/web.php
• Full-page navigation where the URL changes
• Content that benefits from browser history and bookmarkability

JSON responses are for:

• AJAX requests from existing pages
• Modals/dialogs that appear over the current page
• API endpoints consumed by external clients or mobile apps
• Partial page updates without navigation

---

### Next Steps

Once you add this file to the `laravel-vue-rules` repository:
1. The `backend-developer` skill will automatically load it (it already reads all `.claude/rules/backend/*.md` files)
2. We should remove the duplicate content from `backend-developer/SKILL.md` in this PR
3. The skill will reference the rule instead of defining the convention itself

This properly separates:
- **Rules** (single source of truth) → `laravel-vue-rules` repo
- **Skills** (load and apply rules) → this plugin repo

---