---
name: modify-prism-project
description: Rules and guidance for modifying existing Prism-generated projects. Use when editing code in a project created by Prism.
---

Guide for safely modifying a Prism-generated project without breaking regeneration.

## Golden Rule

**Modify the spec, not the generated code.** To add a field, model, endpoint, or UI component — update `specs/models.py` and run `uv run prismegenerate`.

## File Safety

### Never edit (regenerated on every `prisme generate`)
- `_generated/` directories (services, components, GraphQL types)
- `schemas/` (Pydantic request/response schemas)
- `types/generated.ts` (TypeScript types)

### Safe to edit (created once, never overwritten)
- `services/*_service.py` — extend the base class from `_generated/`
- `components/<Model>Form.tsx`, `<Model>Table.tsx` — wrap the base from `_generated/`
- `pages/*.tsx` — page-level customizations
- `hooks/*.ts` — data-fetching hooks
- `extensions/routers.py` — custom REST endpoints
- `extensions/dependencies.py` — custom FastAPI dependencies
- `extensions/events.py` — startup/shutdown lifecycle hooks
- `extensions/policies.py` — authorization policies

### Protected regions (inline customization in regenerated files)
Code between `PRISM:PROTECTED:START` and `PRISM:PROTECTED:END` markers is preserved during regeneration:

```python
# PRISM:PROTECTED:START - Custom Imports
from mylib import helper
# PRISM:PROTECTED:END
```

```tsx
{/* PRISM:PROTECTED:START - Custom Providers */}
<ThemeProvider theme={customTheme}>
{/* PRISM:PROTECTED:END */}
```

## Common Modification Workflows

### Add a new field to a model
1. Edit `specs/models.py` — add `FieldSpec` to the model
2. Run `uv run prismegenerate`
3. Run `uv run prismedb migrate` (if schema changed)

### Add a new model
1. Edit `specs/models.py` — add `ModelSpec` to the `models` list
2. Add `RelationshipSpec` entries on both sides if it relates to existing models
3. Run `uv run prismegenerate`
4. Run `uv run prismedb migrate`

### Customize a backend service
Edit the extension file, not the generated base:
```python
# services/customer_service.py (SAFE — edit this)
from ._generated.customer_base import CustomerServiceBase

class CustomerService(CustomerServiceBase):
    async def create(self, db, *, data):
        # Your custom logic
        return await super().create(db, data=data)
```

### Add a custom REST endpoint
Add routes in `extensions/routers.py`:
```python
from fastapi import APIRouter
router = APIRouter()

@router.get("/custom-endpoint")
async def custom_endpoint():
    return {"message": "custom"}
```

### Customize a frontend component
Edit the wrapper component, not the generated base:
```tsx
// components/customer/CustomerForm.tsx (SAFE — edit this)
import { CustomerFormBase } from '../_generated/CustomerFormBase';

export const CustomerForm = (props) => {
  return <CustomerFormBase {...props} />;
};
```

## Before Making Changes

```bash
uv run prismevalidate specs/models.py   # Verify spec is valid
uv run prismegenerate --dry-run         # Preview what would change
uv run prismereview list                # Check for existing overrides
```

## After Making Changes

```bash
uv run prismegenerate                   # Regenerate from spec
uv run prismedb migrate                 # Apply DB changes (if any)
uv run prismecheck                      # Verify project consistency
uv run prismetest                       # Run tests
```

## Troubleshooting

- **Override warning during generate**: You modified a generated file directly. Use `prismereview diff <file>` to see your changes, then move customizations to the extension file or a protected region.
- **Missing base class**: Run `prisme generate` — the base was likely not generated yet.
- **Spec validation error**: Run `prismevalidate specs/models.py` for detailed error messages with fix suggestions.
