nurosys-agents 2.0.0

package/.agent/backend/skills/create-blueprint/SKILL.md

@@ -0,0 +1,650 @@
+---
+name: create-blueprint
+description: Bootstrap or refresh `project-memory/` artifacts (constitution, auth-model, repo-map, architecture, models, quality-playbook, core-memory) from the current codebase. The canonical onboarding skill — run this FIRST when installing nurosys-agents in a new project. Uses Serena for symbolic codebase analysis. Trigger with `/create-blueprint all` to bootstrap everything, or `/create-blueprint <artifact_type>` for a single artifact.
+disable-model-invocation: false
+---
+
+# Skill: create-blueprint
+
+Use this skill to generate or refresh project-memory documentation artifacts based on the current state of the codebase. Each artifact becomes a reference document that constrains and guides feature implementation.
+
+---
+
+## When to trigger
+
+- User asks `create-blueprint all` — runs all artifact types in sequence (full project-memory setup).
+- User asks `create-blueprint <artifact_type>` or `update-blueprint <artifact_type>` — creates or refreshes a single artifact.
+- Artifact types: `constitution`, `auth-model`, `repo-map`, `core-memory`, `models`, `architecture`, `quality-playbook`.
+- When codebase has evolved significantly and project-memory docs are stale or missing.
+- After completing a major feature or architectural refactor to capture new patterns.
+
+### `create-blueprint all` — full setup sequence
+
+When the user passes `all`, run each artifact **in this order** (dependencies first):
+
+1. `architecture` — establish system topology before anything else
+2. `models` — domain entities inform the repo map and constitution
+3. `repo-map` — module layout needed by all other docs
+4. `constitution` — rules derived from observed patterns in the codebase
+5. `auth-model` — auth flow and guards (depends on repo-map for file locations)
+6. `quality-playbook` — patterns and anti-patterns (derived from real code)
+7. `core-memory` — last, as it captures decisions made above
+
+After each artifact is generated and approved, continue to the next without stopping for further user input unless a blocking question arises (e.g., ambiguous auth pattern). At the end, report a summary table of all artifacts created.
+
+---
+
+## Supported artifacts
+
+| Artifact | Purpose | When to create/update |
+|----------|---------|----------------------|
+| `constitution` | Non-negotiable rules (security, validation, DI, auth, SQL, error handling) | After major security decisions or framework upgrades |
+| `auth-model` | Complete JWT flow, guard chain, RBAC entities, identity propagation, tenant/resource scoping | After auth system changes or new permission patterns |
+| `repo-map` | Module layout, naming conventions, reusable components, key entry points, file registry | After adding new module categories or changing structure |
+| `core-memory` | Historical implementation decisions, completed modules, design lessons, known patterns | End of each completed feature or milestone |
+| `models` | Domain model inventory (ORM entities, associations, field contracts, constraints) | After new model additions or significant schema changes |
+| `architecture` | System-level architecture decisions, module topology, data flow, integration points | After architectural refactors or major coupling changes |
+| `quality-playbook` | High-signal check patterns with symptoms, root causes, preferred fixes | After discovering recurring bugs or anti-patterns |
+
+---
+
+## Phase 1 — Understand intent
+
+### 1.1 Parse user request
+
+Extract:
+- **Artifact type**: the specific project-memory file to create/update.
+- **Intent**: is this a creation (new), update (refresh stale content), or refactor (reorganize)?
+- **Scope**: does the user want all artifacts or a specific one?
+
+### 1.2 Check for existing artifact
+
+```bash
+ls -la project-memory/<artifact-type>.md
+```
+
+If exists: → read the full file and understand its current state.
+If absent: → proceed to Phase 2 with a blank slate.
+
+---
+
+## Phase 2 — Analyze codebase with Serena
+
+Use Serena's symbolic tools to extract structured information **first** — avoid large file reads until you have a focused direction.
+
+### 2.1 Orient yourself
+
+Start with the project layout:
+
+```bash
+ls -la                    # see top-level layout
+cat package.json          # detect framework (NestJS/Express/Fastify/Koa) and key deps
+```
+
+Then check Serena memories from prior sessions (if any):
+
+```
+list_memories
+```
+
+If memories exist with names like `project_overview`, `tech_stack`, `project_structure`, read them — they may already contain bootstrap context.
+
+### 2.2 Artifact-specific Serena queries
+
+Call the appropriate sequence based on what you're building. **Target: ≤8 Serena calls per artifact.**
+
+#### For `repo-map` (module layout, conventions):
+1. `get_symbols_overview(relative_path="src")` — top-level structure
+2. For each major subdirectory found, `get_symbols_overview(relative_path="src/<subdir>")` — drill down 1-2 levels
+3. `find_symbol(name_path="...", substring_matching=true)` on patterns like `"Module"` or `"Service"` to enumerate module types
+
+#### For `architecture` (topology, layers):
+1. `get_symbols_overview` on the app entry file (e.g. `src/main.ts`, `src/app.module.ts`, `src/index.ts`)
+2. `find_symbol(name_path="AppModule", include_body=true)` (or equivalent) to see top-level wiring
+3. `find_referencing_symbols` on a couple of bridge classes (e.g. shared service, base controller) to map coupling
+
+#### For `auth-model` (auth flow, guards, RBAC):
+1. `find_symbol(name_path="...", substring_matching=true)` on terms like `Guard`, `Auth`, `Jwt`, `Permission`
+2. For each guard found, `find_symbol` with `include_body=true` to read its mechanism
+3. `find_referencing_symbols` on the auth guard to see where it's applied (gives the protected-endpoint inventory)
+4. Read auth config files directly with `Read` if non-symbol (e.g. `src/config/jwt.ts`)
+
+#### For `models` (entities, associations):
+1. `find_symbol(name_path="...", substring_matching=true)` on patterns like `Model` or `Entity` (filter by language convention)
+2. For each model found, `find_symbol(include_body=true)` to read decorators/associations
+3. Sample 3-5 representative models — don't enumerate all
+
+#### For `quality-playbook` (patterns, anti-patterns):
+1. Look at recent fix commits: `git log --grep="fix:" --oneline | head -20` to spot recurring issues
+2. `find_symbol` on commonly-fixed areas (validation, error handling)
+3. Read a representative service file to extract baseline patterns
+
+#### For `constitution` (security, validation, DI, errors):
+1. `find_symbol(name_path="...", substring_matching=true)` on patterns: `Dto`, `Pipe`, `Filter`, `Interceptor`, `Module`
+2. Read 1-2 examples of each to extract project conventions
+3. Read root module file for DI/wiring style
+
+#### For `core-memory` (history):
+1. Read existing `project-memory/core-memory.md` if present (this is a manual record, not auto-derived)
+2. `git log --oneline | head -30` to see recent work
+3. Cross-reference with existing core-memory to identify what's new or changed
+
+### 2.3 Efficiency
+
+- Always prefer `get_symbols_overview` + targeted `find_symbol` over raw `Read`
+- Target ≤8 Serena calls total for Phase 2
+- For files that aren't code (configs, migrations, json), use `Read` with `offset`/`limit` to read only relevant sections
+
+---
+
+## Phase 3 — Extract patterns from codebase
+
+Based on the graph results, perform targeted reads **only** for files the graph identified as relevant. Never read entire directories or all files of a type.
+
+### 3.1 For each artifact type, identify key sections
+
+| Artifact | What to extract | How | Sources |
+|----------|-----------------|-----|---------|
+| `repo-map` | Module directories, naming conventions, required files per module type, reusable components, entry points | Read 1–3 representative module files per community; extract patterns | Graph: list_communities results; File reads: module index files, example modules |
+| `architecture` | Layer structure, communication flows, module boundaries, coupling points | Read architecture-touching files (root module wiring, main controller/handler patterns) | Graph: get_architecture_overview, bridge/hub nodes; Spot-check: root module, integration points |
+| `auth-model` | Guard types, token structure, permission check flow, tenant/resource scoping patterns | Read auth entry points and example auth-gated endpoints | Graph: semantic_search results for "auth guard", "jwt", "permission"; Spot-check: auth.module, sample protected endpoints |
+| `models` | ORM conventions, association patterns, field naming, timestamps/soft deletes | Read 3–5 representative model files | Graph: semantic_search for "model entity"; Read: models from different domains |
+| `constitution` | Validation rules, error envelope, DI patterns, SQL safety, logging, secret handling | Read representative implementations of each concern | Graph: semantic_search for "validation", "error", "provider", "query"; Spot-check: sample service, controller, query file |
+| `quality-playbook` | Recurring bugs, anti-patterns, preferred fixes | Analyze graph results for hotspots; read examples of fixes in git history or test files | Graph: find_large_functions, get_knowledge_gaps; Bash: `git log --grep="fix:" --oneline \| head -20` |
+| `core-memory` | Completed modules, design decisions, patterns to reuse/avoid | Existing file + graph enumeration | Existing core-memory.md; Graph: list_communities |
+
+### 3.2 Read targeted files
+
+For each file the graph flagged:
+- Read it in full **once** (do not re-read).
+- Extract the pattern or decision it exemplifies.
+- Note: if file_path is long, use `offset` and `limit` to read only relevant sections.
+
+---
+
+## Phase 4 — Generate the artifact
+
+Create or update the project-memory file following the standard structure for that artifact type.
+
+### Structure templates
+
+#### constitution.md
+
+```markdown
+# Constitution
+
+Non-negotiable rules for this codebase.
+
+## 1. Project structure
+- [Rule about module layout, naming, file organization]
+- [Rule about where to put features]
+- [Rule about shared vs feature-specific code]
+
+## 2. Security
+- [Rule about auth guards, token handling]
+- [Rule about secrets, config, environment variables]
+- [Rule about input validation, injection safety]
+
+## 3. Validation
+- [Rule about DTO usage, validation pipes]
+- [Rule about boundary validation vs internal trust]
+- [Rule about error messages, logging PII]
+
+## 4. Auth invariants
+- [Rule about request context ownership]
+- [Rule about tenant/resource scoping]
+- [Rule about permission checks (controller vs service level)]
+
+## 5. Dependency injection
+- [Rule about module structure, imports/exports]
+- [Rule about token naming, reuse]
+- [Rule about avoiding circular dependencies]
+
+## 6. Database & SQL
+- [Rule about parameterization, no string interpolation]
+- [Rule about row-level security, ownership predicates]
+- [Rule about migrations, schema versioning]
+
+## 7. Error handling
+- [Rule about status codes, error envelope]
+- [Rule about logging vs swallowing errors]
+
+## 8. Caching
+- [Rule about cache key derivation]
+- [Rule about cache bypass/refresh triggers]
+
+## 9. Logging
+- [Rule about PII, secrets, sensitive data]
+- [Rule about structured logging, context]
+
+## 10. Dependencies
+- [Rule about adding external libraries]
+- [Rule about framework usage, anti-patterns]
+```
+
+#### auth-model.md
+
+```markdown
+# Auth Model
+
+Complete JWT flow, guard chain, RBAC entities, identity propagation.
+
+## Token issuance
+- [How JWT is created: algorithm, claims, expiry]
+- [Where token issuance happens: auth controller/service endpoint]
+- [Token refresh strategy if applicable]
+
+## Guard chain
+- [List of guards in order: auth guard, permission guard, custom guards]
+- [How each guard is applied: decorators, middleware, imports]
+- [Example endpoint with guard chain]
+
+## Request context propagation
+- [How authenticated user context flows into services]
+- [How to access current user in controller/service: decorator, injection]
+- [How tenant/ownership context is passed]
+
+## RBAC entities
+- [User role structure: built-in roles, custom roles]
+- [Permission structure: what permissions exist, how they're grouped]
+- [Role-permission associations: how roles get permissions]
+
+## Tenant/resource scoping
+- [How tenant is determined: from JWT claim, request context, or other]
+- [How resources are filtered by tenant: query predicates, service-level checks]
+- [How ownership is enforced: user ID checks, team ID checks]
+
+## Identity propagation patterns
+- [Example: controller accepting CurrentUser decorator → passing to service]
+- [Example: service using authenticated context for filtering]
+- [Example: cross-service calls preserving identity]
+```
+
+#### repo-map.md
+
+```markdown
+# Repo Map
+
+Module layout, naming conventions, reusable components, file organization.
+
+## Naming conventions
+- Modules: [kebab-case, snake_case, camelCase?]
+- Files: [extension patterns, file naming rules]
+- Classes/functions: [camelCase, PascalCase rules]
+- DTOs/entities: [naming patterns for requests, responses, database models]
+
+## Directory structure
+[Show the canonical structure: which folders hold features, which hold core, where config/shared lives]
+
+## Module types
+[For each type of module (API feature, core service, shared utility, etc.), list required files]
+
+Example:
+```
+src/apis/my-feature/
+├── my-feature.controller.ts
+├── my-feature.service.ts
+├── my-feature.dto.ts
+├── my-feature.model.ts
+├── my-feature.module.ts
+├── my-feature.repository.ts
+└── my-feature.spec.ts
+```
+
+## Reusable components
+- [Auth guards, decorators, and where to import them]
+- [Validation pipes, decorators]
+- [Common services (logger, config, cache, storage)]
+- [How to extend/use them in new features]
+
+## Key entry points
+- [Root module: where features are wired in]
+- [Server entry: main.ts, app.module.ts, or equivalent]
+- [Database: migrations, models registry]
+- [Config: env var patterns, bootstrap]
+
+## Known cross-module imports
+- [What modules are safe to import from: e.g., src/common/, src/core/]
+- [What modules should NOT be imported: avoid coupling]
+```
+
+#### core-memory.md
+
+```markdown
+# Core Memory
+
+Historical implementation decisions, completed modules, design lessons.
+
+## Completed modules / features
+- [Feature name and milestone]
+- [Brief description of what was built]
+- [Key design decisions made (if interesting)]
+- [Known limitations or follow-up work]
+
+Example:
+- **Auth system (M1-M3)**: Implemented JWT flow with Guardian guards. Uses @CurrentUser() for context propagation. Tenant scoping via JWT `tenant_id` claim. Follow-up: add refresh token rotation (deferred to M5).
+
+## Design decisions & rationale
+- [Decision]: [Why it was made] [Tradeoff or lessons learned]
+
+Example:
+- **Services handle all business logic, not controllers**: Keeps controllers thin, allows service reuse, testable in isolation. Downside: services can become large (mitigated by splitting into focused services per domain).
+
+## Patterns to follow
+- [Pattern name]: [When to use] [Example file]
+
+Example:
+- **Repository pattern for data access**: All database queries go through a repository. Controllers → Services → Repositories. Keeps SQL/ORM details out of business logic.
+
+## Patterns to avoid
+- [Anti-pattern]: [Why it's bad] [If encountered, how to fix]
+
+Example:
+- **Direct request data in queries**: Never pass req.body.userId into a SQL filter. Extract authenticated user context from JWT/request context instead.
+```
+
+#### models.md
+
+```markdown
+# Domain Models
+
+Inventory of ORM entities, associations, field contracts, constraints.
+
+## Model: [Entity name]
+- **Table**: [table_name]
+- **ORM**: [Sequelize / TypeORM / other]
+- **Fields**:
+  - [field_name]: [type] [constraints: nullable, unique, default, indexed]
+  - [...]
+- **Associations**:
+  - hasMany: [Target model] (via foreign key [fk_name])
+  - belongsTo: [Target model] (via foreign key [fk_name])
+  - [...]
+- **Timestamps**: [createdAt, updatedAt strategy]
+- **Soft delete**: [Yes/No, how]
+- **Indexing**: [Indexes on [fields]]
+- **Constraints**: [Unique, check, or business rules]
+
+[Example for User model]
+## Model: User
+- **Table**: users
+- **ORM**: Sequelize
+- **Fields**:
+  - id (UUID, primary key)
+  - email (string, unique, not null)
+  - password_hash (string, not null)
+  - role_id (UUID, foreign key to roles, not null)
+  - tenant_id (UUID, foreign key to tenants, not null)
+  - created_at (timestamp, auto)
+  - updated_at (timestamp, auto)
+  - deleted_at (timestamp, soft delete)
+- **Associations**:
+  - belongsTo: Role (via role_id)
+  - belongsTo: Tenant (via tenant_id)
+  - hasMany: Sessions (via user_id)
+- **Timestamps**: Yes (created_at, updated_at)
+- **Soft delete**: Yes (deleted_at)
+- **Indexing**: tenant_id, role_id, email
+```
+
+#### architecture.md
+
+```markdown
+# Architecture
+
+System-level architecture decisions, module topology, data flow, integration points.
+
+## System layers
+[Description of application layers: e.g., Controller → Service → Repository → Database]
+
+## Module topology
+- [Core modules]: [services that all other modules depend on]
+- [API modules]: [feature-specific modules in src/apis/]
+- [External integrations]: [modules for API clients, queues, storage, etc.]
+
+## Data flow
+[Diagram or description of how data moves through the system]
+
+Example:
+```
+Request → Controller → Guard (auth) → Service → Repository → Database
+          ↓
+        Interceptor (logging, error handling)
+```
+
+## Key integration points
+- [External API]: [How it's called, timeout/retry strategy, error handling]
+- [Message queue]: [How messages are published/consumed]
+- [Cache layer]: [What's cached, TTL strategy]
+- [Storage]: [File storage, blob service, bucket strategy]
+
+## Cross-module boundaries
+- [Module A imports from Module B]: [OK/Not OK; if OK, what interface]
+- [Known coupling]: [Description of unavoidable cross-module dependency]
+
+## Architectural decisions & tradeoffs
+- [Decision]: [Why] [Tradeoff]
+
+Example:
+- **Monolithic API backend**: Simple to deploy and reason about. Tradeoff: harder to scale individual features independently (mitigated with feature flags and service extraction when needed).
+```
+
+#### quality-playbook.md
+
+```markdown
+# Quality Playbook
+
+High-signal check patterns with symptoms, root causes, and preferred fixes.
+
+## Pattern: [Name]
+
+**When you see**: [Symptoms; what code looks like when this goes wrong]
+
+**Root cause**: [Why this happens]
+
+**Preferred fix**: [How to fix it; code pattern to follow]
+
+**Example**:
+[Code snippet showing the antipattern and the fix]
+
+---
+
+## Pattern: Unvalidated endpoint input
+
+**When you see**: Controller method accepts `req.body` and passes it directly to a service, or passes `req.body.userId` directly into a query filter.
+
+**Root cause**: Assuming the framework or downstream layers validate input. Trusting client data.
+
+**Preferred fix**: Always validate at the controller boundary. Use DTOs + ValidationPipe. Extract authenticated context (user ID, tenant) from JWT/request context, never from request body.
+
+**Example**:
+```typescript
+// ❌ Bad
+@Post('transfer')
+transfer(@Body() body: any) {
+  return this.service.transfer(body.fromId, body.toId, body.amount);
+}
+
+// ✅ Good
+@Post('transfer')
+@UseGuards(CanAuthGuard)
+transfer(
+  @CurrentUser() user: UserContext,
+  @Body() dto: TransferDto,
+) {
+  return this.service.transfer(user.id, dto.toId, dto.amount);
+}
+```
+
+---
+
+## Pattern: [Next pattern]
+...
+```
+
+---
+
+## Phase 5 — Compare with existing artifact (if update)
+
+### 5.1 Identify changes
+
+If the artifact already exists, compare:
+- **New sections**: sections in your generated version that don't exist in the current file.
+- **Updated sections**: sections where content has changed (decisions, patterns, module list).
+- **Stale sections**: sections that are outdated (modules that no longer exist, deprecated patterns).
+
+### 5.2 Preserve manual decisions
+
+For artifacts like `core-memory` that include manual decisions and lessons:
+- **Do NOT delete** existing completed modules or design decisions.
+- **Do ADD** new modules/decisions from the latest feature work.
+- **Do UPDATE** rationale if the reasoning has changed.
+
+---
+
+## Phase 6 — Present changes to user
+
+### 6.1 Show a diff-style summary
+
+For an **update**:
+```
+# Changes to project-memory/auth-model.md
+
+## New sections
+- [New section name]: [brief description]
+
+## Updated sections
+- [Section name]: [what changed]
+
+## Removed sections
+- [Section name]: [why no longer relevant]
+```
+
+For a **creation**:
+```
+# New artifact: project-memory/repo-map.md
+
+This artifact defines:
+- [Key item 1]
+- [Key item 2]
+- ...
+```
+
+### 6.2 Ask for confirmation
+
+Present the changes and ask:
+- "Does this match the current codebase structure?"
+- "Are there sections you'd like me to expand or clarify?"
+- "Any decisions or patterns you want me to add manually?"
+
+Wait for user approval before writing the file.
+
+---
+
+## Phase 7 — Write the artifact
+
+### 7.1 Write to project-memory/
+
+```
+project-memory/<artifact-type>.md
+```
+
+### 7.2 Update project-memory/README.md
+
+If the artifact is new, add an entry to the index:
+
+```markdown
+| [artifact-type].md | [Brief description] | [Who updates it: auto / manual / both] |
+```
+
+If artifact already exists, ensure the index is still accurate.
+
+### 7.3 Set up symlinks
+
+#### 7.3.1 Artifact symlinks (for new artifacts only)
+
+If this is a **new artifact**, create symlinks in `.claude/` and `.cursor/` pointing to the single source of truth in `project-memory/`:
+
+```bash
+# For .claude/
+ln -sf ../project-memory/<artifact-type>.md .claude/docs/<artifact-type>.md
+
+# For .cursor/
+ln -sf ../project-memory/<artifact-type>.md .cursor/docs/<artifact-type>.md
+```
+
+**Verify links exist and are correct**:
+```bash
+ls -la .claude/docs/<artifact-type>.md .cursor/docs/<artifact-type>.md
+```
+
+If either symlink already exists, skip (do not overwrite).
+
+#### 7.3.2 Module execution
+
+Feature execution is now handled entirely by the `/module-runner` skill (no shell script needed). `/module-runner` is wired during `npm exec nurosys-agent-setup` for the user's chosen IDE. No additional setup required here.
+
+### 7.4 Wire artifact as a Cursor rule
+
+After writing the artifact, run the cursor rules setup script to create (or refresh) the `.cursor/rules/<artifact-type>.mdc` symlink pointing to the new file:
+
+```bash
+node scripts/setup-cursor-rules.js
+```
+
+Or if installed as a package bin:
+```bash
+npm exec nurosys-setup-rules
+```
+
+This script:
+- Creates `.cursor/rules/` if it does not exist
+- Adds a `.mdc` symlink for every `project-memory/*.md` that exists
+- Skips files that already have a symlink
+- Reports which files were linked, skipped, or missing
+
+The `.cursor/rules/<artifact>.mdc` files are written by `nurosys-setup-rules` with the correct MDC frontmatter automatically — you do not need to embed frontmatter in the `project-memory/` source files. For reference, the frontmatter applied per artifact is:
+
+| Artifact | `description` | `globs` | `alwaysApply` |
+|----------|--------------|---------|---------------|
+| `constitution.md` | "Non-negotiable project rules and coding standards" | — | `true` |
+| `architecture.md` | "System architecture, module topology, and data flow" | — | `true` |
+| `repo-map.md` | "Repository module layout, naming conventions, and reusable components" | — | `true` |
+| `auth-model.md` | "Auth model, JWT flow, guard chain, RBAC, and tenant scoping" | `["src/auth/**", "src/core/auth/**"]` | `false` |
+| `models.md` | "Domain model inventory and entity definitions" | `["src/**/*.model.ts", "src/**/*.entity.ts"]` | `false` |
+| `quality-playbook.md` | "Code quality patterns, anti-patterns, and preferred fixes for this project" | — | `false` |
+| `core-memory.md` | "Project history, design decisions, and completed modules" | — | `false` |
+
+When `create-blueprint all` runs, call the script once at the end after all artifacts are written.
+
+### 7.5 Confirm with user
+
+Report:
+- The artifact file path: `project-memory/<artifact-type>.md`
+- Whether `.cursor/rules/<artifact-type>.mdc` symlink was created or already existed
+- Whether this was a creation or update
+- Number of sections/changes
+
+---
+
+## Quality gates
+
+Before finalizing the artifact:
+
+- [ ] All sections are present and complete for this artifact type.
+- [ ] Examples are concrete and drawn from actual codebase (not hypothetical).
+- [ ] Decisions/patterns are consistent with what the code actually does (not aspirational).
+- [ ] No broken file paths or module names (spot-check against actual files).
+- [ ] Language is clear and actionable (team members could follow the rules without asking).
+- [ ] For updates: no useful content from the prior version was removed without reason.
+
+---
+
+## Notes
+
+- **Single source of truth**: project-memory artifacts are the authoritative reference stored in `project-memory/<artifact-type>.md`. If they conflict with code, the code is wrong — update the code, not the artifact.
+- **Symlink architecture**: Artifacts in `project-memory/` are symlinked from `.claude/docs/` and `.cursor/docs/` to avoid duplication. Symlinks are created automatically when a new artifact is generated. **Always edit the artifact in `project-memory/`, never in the symlink copies.**
+- **Regular refresh cadence**: After each completed feature module (or every 2–3 weeks), run `create-blueprint` on `core-memory` and `repo-map` to keep them current.
+- **Serena-first approach**: Always use Serena's symbolic tools (`get_symbols_overview`, `find_symbol`, `find_referencing_symbols`) before reading whole files. Symbolic navigation is faster and uses far fewer tokens.
+- **Curation, not exhaustion**: Artifact sections describe the most important patterns and decisions, not every detail. If a pattern is used once, it probably doesn't need to be in the playbook.
+- **Portable artifacts**: These skill generates artifacts that are project-specific in content but portable in structure. You can copy the `project-memory/` folder to another project and run the skill again to regenerate them with that project's codebase.