nurosys-agents 2.0.0

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

@@ -0,0 +1,635 @@
+---
+name: create-blueprint
+description: Create or update project-memory artifacts (constitution, auth-model, repo-map, core-memory, models, architecture, quality-playbook) to keep them in sync with current codebase. Uses code-review-graph for efficient codebase analysis. Trigger with "create-blueprint all" to set up everything, or "create-blueprint <artifact_type>" for a specific artifact.
+disable-model-invocation: true
+---
+
+# 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 graph tools
+
+Use code-review-graph to extract structured information about the codebase **first** — avoid large file reads until you have a focused direction.
+
+### 2.1 Always call this first
+
+```
+get_minimal_context(task="Analyzing codebase for <artifact-type> blueprint")
+```
+
+This gives you:
+- Graph stats (total nodes, languages, communities, flows).
+- Risk score.
+- Key communities and flows.
+
+### 2.2 Artifact-specific graph queries
+
+Call the appropriate sequence based on what you're building:
+
+#### For `repo-map` (module layout, conventions):
+1. `list_communities(detail_level="minimal", sort_by="size")`
+2. `query_graph(pattern="file_summary", target="src/")`  (if src/ exists; adjust to your layout)
+3. `semantic_search_nodes(query="module entry point", kind="Function", limit=20)`
+
+#### For `architecture` (topology, coupling):
+1. `get_architecture_overview()`
+2. `get_bridge_nodes_tool(top_n=15)` — identify chokepoints
+3. `get_surprising_connections_tool(top_n=15)` — find unexpected coupling
+
+#### For `auth-model` (JWT, guards, RBAC):
+1. `semantic_search_nodes(query="auth guard middleware", kind="Class", limit=10)`
+2. `semantic_search_nodes(query="jwt token verify", limit=10)`
+3. `semantic_search_nodes(query="permission check", limit=10)`
+4. `query_graph(pattern="callees_of", target="<auth entry point>")`
+
+#### For `models` (entities, associations, constraints):
+1. `semantic_search_nodes(query="database model entity", kind="Class", limit=30)`
+2. `semantic_search_nodes(query="association foreign key", limit=10)`
+3. `query_graph(pattern="file_summary", target="src/path/to/models/")`
+
+#### For `quality-playbook` (patterns, anti-patterns):
+1. `list_graph_stats` — check for large functions
+2. `find_large_functions(min_lines=100, limit=20)` — identify complexity hotspots
+3. `get_knowledge_gaps_tool()` — find untested/undocumented areas
+4. `detect_changes(base="HEAD~20")` — analyze recent patterns in recent commits
+
+#### For `constitution` (security, validation, DI, error handling):
+1. `semantic_search_nodes(query="validation input dto", limit=10)`
+2. `semantic_search_nodes(query="auth guard decorator", limit=10)`
+3. `semantic_search_nodes(query="error exception handler", limit=10)`
+4. `semantic_search_nodes(query="dependency injection provider", limit=10)`
+
+#### For `core-memory` (decisions, completed modules):
+- If updating: read the existing file first (it's a manual record, not auto-derived).
+- Use graph to identify:
+  1. `list_communities(sort_by="name")` — enumerate all modules/communities.
+  2. `query_graph(pattern="file_summary", target="src/")` — understand what modules exist.
+- Cross-reference with existing core-memory to identify what's new or changed.
+
+### 2.3 Token efficiency
+
+- Use `detail_level="minimal"` on all queries.
+- Target ≤8 graph calls total for Phase 2.
+- Only escalate to `"standard"` if a query returns no results.
+
+---
+
+## 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 Script symlink (always check)
+
+Ensure `scripts/run-feature-modules.sh` is symlinked to `.agent/scripts/run-feature-modules.sh`:
+
+```bash
+# Check if symlink exists
+if [ ! -L scripts/run-feature-modules.sh ]; then
+  # Remove the file if it exists as a regular file
+  rm -f scripts/run-feature-modules.sh
+  # Create the symlink
+  ln -sf ../.agent/scripts/run-feature-modules.sh scripts/run-feature-modules.sh
+  echo "✅ Created symlink: scripts/run-feature-modules.sh"
+else
+  echo "✅ Symlink already exists: scripts/run-feature-modules.sh"
+fi
+```
+
+**Verify**:
+```bash
+ls -la scripts/run-feature-modules.sh
+```
+
+This ensures the script is maintained in a single location (`.agent/scripts/`) and referenced from the root `scripts/` folder.
+
+### 7.4 Confirm with user
+
+Report:
+- The artifact file path: `project-memory/<artifact-type>.md`
+- Symlink paths created (if new): `.claude/docs/<artifact-type>.md`, `.cursor/docs/<artifact-type>.md`
+- 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.
+- **Graph-first approach**: Always use code-review-graph tools before reading files. The graph is faster and gives you structural context.
+- **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.

package/.agent/monolith/skills/debug-issue/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: debug-issue
+description: Systematically debug issues using graph-powered code navigation
+disable-model-invocation: true
+---
+
+## Debug Issue
+
+Use the knowledge graph to systematically trace and debug issues.
+
+### Steps
+
+1. Use `semantic_search_nodes` to find code related to the issue.
+2. Use `query_graph` with `callers_of` and `callees_of` to trace call chains.
+3. Use `get_flow` to see full execution paths through suspected areas.
+4. Run `detect_changes` to check if recent changes caused the issue.
+5. Use `get_impact_radius` on suspected files to see what else is affected.
+
+### Tips
+
+- Check both callers and callees to understand the full context.
+- Look at affected flows to find the entry point that triggers the bug.
+- Recent changes are the most common source of new issues.
+
+## Token Efficiency Rules
+- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.

package/.agent/monolith/skills/explore-codebase/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: explore-codebase
+description: Navigate and understand codebase structure using the knowledge graph
+disable-model-invocation: true
+---
+
+## Explore Codebase
+
+Use the code-review-graph MCP tools to explore and understand the codebase.
+
+### Steps
+
+1. Run `list_graph_stats` to see overall codebase metrics.
+2. Run `get_architecture_overview` for high-level community structure.
+3. Use `list_communities` to find major modules, then `get_community` for details.
+4. Use `semantic_search_nodes` to find specific functions or classes.
+5. Use `query_graph` with patterns like `callers_of`, `callees_of`, `imports_of` to trace relationships.
+6. Use `list_flows` and `get_flow` to understand execution paths.
+
+### Tips
+
+- Start broad (stats, architecture) then narrow down to specific areas.
+- Use `children_of` on a file to see all its functions and classes.
+- Use `find_large_functions` to identify complex code.
+
+## Token Efficiency Rules
+- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.