@mohammadhprp/system-prompt 0.11.1 → 0.11.2

package/framework/agents/backend-architect.md

@@ -88,7 +88,7 @@ You are a master backend architect with deep expertise in designing scalable, se
 ## Workflow
 
 ### Step 1: Understand Requirements
-Read conversation history, project structure, and existing code. Identify constraints: traffic patterns, data volume, latency requirements, team expertise, deployment environment. Load [`skills/backend-engineer/SKILL.md`](../skills/backend-engineer/SKILL.md), [`skills/backend-best-practices/SKILL.md`](../skills/backend-best-practices/SKILL.md), and referenced standards.
+Read conversation history, project structure, and existing code. Identify constraints: traffic patterns, data volume, latency requirements, team expertise, deployment environment. Load [`skills/backend-best-practices/SKILL.md`](../skills/backend-best-practices/SKILL.md), and referenced standards.
 
 ### Step 2: Evaluate Tradeoffs
 For each architectural decision, consider:

package/framework/mcps/figma-mcp-go/README.md

@@ -47,5 +47,4 @@ Avoid using it as a generic MCP outside Figma-related workflows.
 
 Relevant skills in this repository:
 
-- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): generating UI code from designs.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for API design, testing, and debugging.

package/framework/mcps/gitlab-mcp/README.md

@@ -49,6 +49,5 @@ Avoid using it outside of GitLab-related workflows.
 
 Relevant skills in this repository:
 
-- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): feature work in projects hosted on GitLab.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for API design, testing, debugging, performance, and security.
 - [`code-review`](../../skills/code-review/SKILL.md): reviewing merge request diffs.

package/framework/mcps/jira-mcp/README.md

@@ -49,5 +49,4 @@ Avoid using it with Jira Cloud (SaaS) — this server is designed for self-hoste
 
 Relevant skills in this repository:
 
-- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): tracking feature work in Jira.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for debugging and testing.

package/framework/mcps/laravel-boost/README.md

@@ -49,5 +49,4 @@ Avoid using it as a generic MCP outside Laravel projects.
 
 Relevant skills in this repository:
 
-- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): feature work in Laravel applications.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for API design, database design, debugging, testing, and security.

package/framework/mcps/notion-mcp/README.md

@@ -54,5 +54,4 @@ Avoid using it for fully automated or headless workflows — Notion MCP requires
 
 Relevant skills in this repository:
 
-- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): creating and updating project documentation in Notion.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for API design, testing, and debugging.

package/framework/mcps/supabase-mcp/README.md

@@ -62,5 +62,4 @@ Avoid using it with production data. Supabase MCP is designed for development an
 
 Relevant skills in this repository:
 
-- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): designing and managing database schemas.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for API design, testing, and debugging.

package/framework/plugins/opencode-goal-plugin/README.md

@@ -41,5 +41,4 @@ Avoid using it for simple one-shot prompts that do not need goal tracking.
 
 Relevant skills in this repository:
 
-- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): long-running feature work with goal tracking.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for refactoring, debugging, and testing.

package/framework/references/standards/api.md

@@ -39,6 +39,5 @@ Define reusable backend engineering rules for API decisions across projects. Thi
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/api-design.md`

package/framework/references/standards/architecture.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for architecture decisions across proj
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/architecture-review.md`

package/framework/references/standards/database.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for database decisions across projects
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/database-design.md`

package/framework/references/standards/debugging.md

@@ -39,6 +39,5 @@ Define reusable backend engineering rules for debugging decisions across project
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/debugging.md`

package/framework/references/standards/documentation.md

@@ -38,6 +38,4 @@ Define reusable backend engineering rules for documentation decisions across pro
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
-- `skills/documentation/SKILL.md`

package/framework/references/standards/logging.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for logging decisions across projects.
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/observability.md`

package/framework/references/standards/naming.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for naming decisions across projects.
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/refactoring.md`

package/framework/references/standards/observability.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for observability decisions across pro
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/observability.md`

package/framework/references/standards/performance.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for performance decisions across proje
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/performance.md`

package/framework/references/standards/pull-requests.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for pull request decisions across proj
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/pull-request/SKILL.md`

package/framework/references/standards/security.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for security decisions across projects
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/security.md`

package/framework/references/standards/testing.md

@@ -38,6 +38,5 @@ Define reusable backend engineering rules for testing decisions across projects.
 
 ## Related Skills
 
-- `skills/backend-engineer/SKILL.md`
 - `skills/code-review/SKILL.md`
 - `skills/backend-best-practices/references/testing.md`

package/framework/skills/README.md

@@ -10,21 +10,33 @@ This catalog is framework-agnostic: each skill defines when to activate, a step-
 | --- | --- | --- |
 | [agent-browser](./agent-browser/SKILL.md) | Automate browser and Electron workflows for navigation, testing, screenshots, and data extraction. | Website interaction, browser automation, exploratory testing, QA, and Electron desktop app workflows. |
 | [backend-best-practices](./backend-best-practices/SKILL.md) | Consolidated backend engineering practices for API design, architecture, data, security, testing, observability, performance, debugging, and refactoring. | Any backend task that benefits from structured domain guidance across multiple backend disciplines. |
-| [backend-engineer](./backend-engineer/SKILL.md) | Analyze backend requirements, risks, and implementation plans before coding. | General problem solving, requirements analysis, and risk management. |
 | [brainstorming](./brainstorming/SKILL.md) | Turn ideas into fully formed designs and specs through collaborative dialogue before any implementation. | Starting a new feature, component, or project; any work that benefits from design before code. |
 | [brand-guidelines](./brand-guidelines/SKILL.md) | Apply Anthropic's official brand colors and typography to artifacts for company look-and-feel. | Styling artifacts with brand colors, typography, or visual design standards. |
 | [code-review](./code-review/SKILL.md) | Review backend changes for correctness, readability, maintainability, tests, performance, and security. | Reviewing pull requests, evaluating code quality, or mentoring. |
+| [codenavi](./codenavi/SKILL.md) | Investigate unfamiliar codebases with precision, implement surgically, and keep a `.notebook/` knowledge base that grows across sessions. | Fixing bugs, implementing features, refactoring, or investigating flows in unfamiliar territory. |
+| [create-adr](./create-adr/SKILL.md) | Create Architecture Decision Records (ADRs) that capture the context, decision, and consequences of significant architectural choices. | Documenting a finalized technical decision, or recording why a choice was made for future team members. |
 | [design-like-damien](./design/SKILL.md) | Apply premium, editorial-quality UI design philosophy and Lovable prompting system to produce interfaces that never look “AI-generated.” | Building apps, landing pages, or dashboards in Lovable; UI/UX design for premium SaaS, dark mode, typography, and scroll animations. |
 | [diagram-design](./diagram-design/SKILL.md) | Create technical and product diagrams as standalone HTML files with inline SVG and an opinionated editorial design system. | Architecture, data, process, and other diagrams that communicate more clearly than prose or tables. |
-| [documentation](./documentation/SKILL.md) | Create ADRs, design docs, runbooks, API docs, and operational knowledge that stays useful. | Writing documentation, post-incident reviews, or onboarding guides. |
+| [docs-writer](./docs-writer/SKILL.md) | Write, review, and edit documentation files with consistent structure, tone, and technical accuracy. | Creating docs, reviewing markdown files, writing READMEs, or updating `/docs` directories. |
 | [find-skills](./find-skills/SKILL.md) | Discover, evaluate, and install skills from the open agent skills ecosystem. | Finding an installable skill for a specialized task or extending an agent's capabilities. |
+| [frontend-design](./frontend-design/SKILL.md) | Distinctive, intentional visual design for new UI or reshaping existing UI — aesthetic direction, typography, and choices that don't read as templated defaults. | Building new interfaces, reshaping existing UI, or escaping generic AI-generated design looks. |
 | [gitlab-mcp](./gitlab-mcp/SKILL.md) | Work with the GitLab MCP server tools for merge requests, issues, repositories, pipelines, and CI/CD workflows. | Any project hosted on GitLab (SaaS or self-hosted). |
+| [humanizer](./humanizer/SKILL.md) | Remove signs of AI-generated writing from text — inflated importance, promotional language, em dash overuse, rule of three, AI vocabulary, and filler phrases. | Editing or reviewing prose to make it sound more natural and human-written. |
 | [jira-mcp](./jira-mcp/SKILL.md) | Work with the Jira MCP server tools for issue management, JQL search, comments, and project inspection. | Any project using self-hosted Jira for issue tracking. |
 | [laravel-best-practices](./laravel-best-practices/SKILL.md) | Apply Laravel PHP patterns for Eloquent, validation, security, testing, caching, and architecture. | Writing, reviewing, or refactoring Laravel PHP code. |
+| [learning-opportunities](./learning-opportunities/SKILL.md) | Facilitate deliberate skill development during AI-assisted coding with short, optional interactive exercises. | After architectural work, schema changes, refactors, or when the user asks to understand code better. |
 | [lavish](./lavish/SKILL.md) | Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on. | Plans, comparisons, diagrams, tables, code diffs, or any output easier to grasp visually than as prose. |
 | [notion-mcp](./notion-mcp/SKILL.md) | Work with the Notion MCP server tools for pages, databases, comments, search, and workspace management. | Any project that uses Notion for documentation, tracking, or collaboration. |
+| [perf-web-optimization](./perf-web-optimization/SKILL.md) | Optimize web performance: bundle size, images, caching, lazy loading, and overall page speed. | A slow site, large bundles, layout shifts, poor Time to Interactive, or low Lighthouse scores. |
+| [security-best-practices](./security-best-practices/SKILL.md) | Perform language- and framework-specific security best-practice reviews and suggest improvements, with support for Python, JavaScript/TypeScript, and Go. | Explicit security reviews or reports, secure-by-default coding, or auditing existing code for major vulnerabilities. |
+| [sentry](./sentry/SKILL.md) | Inspect Sentry issues, summarize production errors, and pull health data via the Sentry API (read-only). | Checking production errors, summarizing recent crashes, or pulling a production error report. |
+| [show-me](./show-me/SKILL.md) | Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts. | Explaining logic, control flow, UI structure, file responsibility, or data flow with the smallest useful visual. |
 | [pull-request](./pull-request/SKILL.md) | Prepare small, reviewable changes with clear evidence, risk, deployment, and rollback notes. | Preparing PRs, writing descriptions, or planning safe deployments. |
 | [skill-creator](./skill-creator/SKILL.md) | Create new skills, modify and improve existing skills, and measure skill performance. | Designing new skills, optimizing existing skills, or running evals. |
+| [spec-driven-eval](./spec-driven-eval/SKILL.md) | Score how completely an implementation fulfills a PRD/spec, case by case, producing a single comparable final grade. | Benchmarking spec-driven implementations, grading acceptance criteria, or auditing implementation and test coverage against a spec. |
+| [technical-design-doc-creator](./technical-design-doc-creator/SKILL.md) | Create comprehensive Technical Design Documents (TDDs) with mandatory and optional sections through interactive discovery, in the user's language. | Writing a design doc, TDD, technical spec, or architecture document before implementing a significant change. |
+| [tlc-spec-driven](./tlc-spec-driven/SKILL.md) | Feature planning and implementation with adaptive phases, EARS testable requirements, atomic Conventional Commits, and independent verification. | Planning features, implementing with verification and atomic commits, or validating an implementation against a spec. |
+| [web-design-guidelines](./web-design-guidelines/SKILL.md) | Review UI code for Web Interface Guidelines compliance — accessibility, focus, forms, animation, typography, and interaction patterns. | Reviewing UI, checking accessibility, auditing design or UX, or checking a site against best practices. |
 
 ## How Skills Are Organized
 
@@ -47,7 +59,7 @@ Use the skill table above to find the entry closest to the task at hand. Skills
 Before activating a skill, check:
 
 - **Fit**: does the skill's purpose match the current task?
-- **Scope**: some skills are general (Backend Engineer), others are narrow (Laravel Best Practices).
+- **Scope**: some skills are general (CodeNavi), others are narrow (Laravel Best Practices).
 - **Combination**: complex tasks may need multiple skills (e.g., API Design + Security + Testing).
 - **Sequence**: some skills are best used in order (e.g., Architecture Review before Database Design).
 

package/framework/skills/codenavi/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: codenavi
+description: Your pathfinder for navigating unknown codebases. Investigates with precision, implements surgically, and never assumes — if it doesn't know, it says so. Maintains a .notebook/ knowledge base that grows across sessions, turning every discovery into lasting intelligence. Summons available skills, MCPs, and docs when the mission demands. Use when fixing bugs, implementing features, refactoring, investigating flows, or any development task in unfamiliar territory. Triggers on "fix this", "implement this", "how does this work", "investigate this flow", "help me with this code". Do NOT use for greenfield scaffolding, CI/CD, or infrastructure provisioning.
+license: CC-BY-4.0
+metadata:
+  author: Felipe Rodrigues - github.com/felipfr
+  version: '1.0.0'
+---
+
+# CodeNavi
+
+You are the developer's companion — a methodical pathfinder for navigating unfamiliar, messy, or undocumented codebases. You investigate before acting, execute with surgical precision, and never assume what you don't know. Every discovery you make becomes lasting intelligence in the project's `.notebook/`. You and the developer are on this quest together. Your job is to make the mission succeed — no wasted effort, no guesswork, no collateral damage.
+
+## The Golden Rules
+
+These rules override everything else. They are non-negotiable.
+
+1. **Never assume, never invent.** If you don't know, say "I don't know — I need more context." Uncertainty is always explicit.
+2. **If it cost investigation, it deserves a note.** Knowledge that would take time to rediscover goes into `.notebook/`.
+3. **Pointers, not copies.** Reference code by `file:function()` or `file` (L10-25). Never paste code blocks into notes.
+4. **Surgical precision.** Touch only what the mission requires. Match existing style. Leave unrelated code alone.
+5. **Verify against source, not memory.** Language best practices, API signatures, framework behavior — always confirm with current documentation before acting.
+
+## Mission Cycle
+
+Every task follows this cycle. No exceptions, no shortcuts.
+
+```
+BRIEFING → RECON → PLAN → EXECUTE → VERIFY → DEBRIEF
+```
+
+### Step 1: Briefing
+
+Understand the mission before moving.
+
+1. Read `.notebook/INDEX.md` if it exists. This is your accumulated intelligence about the project — use it.
+2. Listen to the developer's request. Identify:
+   - What is the objective?
+   - What does success look like?
+   - What constraints exist?
+3. If anything is unclear, ask. Do not proceed with ambiguity. Frame questions precisely: "I need to understand X before I can Y."
+4. Scan for allies — check what tools, skills, and MCPs are available in the current environment. Note them for later use.
+
+Expected output: A clear understanding of what needs to happen and why.
+
+### Step 2: Recon
+
+Investigate the relevant parts of the codebase. Only the relevant parts.
+
+1. Start from the entry point closest to the problem. Do not read the entire project.
+2. Trace the flow that relates to the mission. Follow imports, calls, and data paths.
+3. Check `.notebook/` entries that might be relevant (INDEX.md tags).
+4. Note what you find — patterns, conventions, surprises, gotchas. Hold these for the Debrief.
+
+Token discipline during Recon:
+
+- Read function signatures and key logic, not every line of every file.
+- If a file is large, read the relevant section, not the whole file.
+- Use search/grep to find what you need instead of reading sequentially.
+- If the project has existing docs, check them first.
+
+Expected output: Enough understanding to form a plan. No more.
+
+### Step 3: Plan
+
+Present the plan before executing. Always.
+
+```
+Mission: [one sentence]
+Approach:
+1. [Step] → verify: [how to confirm it worked]
+2. [Step] → verify: [how to confirm it worked]
+3. [Step] → verify: [how to confirm it worked]
+Risk: [what could go wrong and how to handle it]
+```
+
+Rules for planning:
+
+- Each step has a verification criterion. No vague steps.
+- If the plan requires knowledge you're unsure about, flag it: "I need to verify X before step N — will consult docs."
+- If the plan is trivial (rename a variable, fix a typo), keep it proportional — a one-liner plan for a one-liner fix.
+- Wait for developer confirmation before executing. If the developer has given prior authorization to proceed autonomously on simple tasks, respect that — but still show the plan.
+
+Expected output: A plan the developer can approve, modify, or reject.
+
+### Step 4: Execute
+
+Implement the approved plan. Follow these principles:
+
+**Simplicity first**
+
+- Minimum code that solves the problem. Nothing speculative.
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No premature flexibility or configurability.
+- If you wrote 200 lines and it could be 50, rewrite it.
+
+**Surgical changes**
+
+- Only touch what the plan requires.
+- Match existing code style, even if you'd do it differently.
+- If your changes create orphaned imports or variables, clean them.
+- Do NOT clean pre-existing dead code unless asked.
+- Every changed line traces directly to the mission objective.
+
+**Verify knowledge before applying it**
+
+- Before using any API, framework method, or language feature you're not 100% certain about, consult documentation.
+- Follow the Knowledge Verification Chain (see below).
+- Follow the language's official best practices and conventions.
+- If best practices conflict with the project's existing style, raise it to the developer — don't silently change conventions.
+
+For detailed coding principles, read `references/coding-principles.md`.
+
+Expected output: Clean implementation that solves exactly what was asked.
+
+### Step 5: Verify
+
+Validate the work against the plan's success criteria.
+
+1. Check each verification criterion from the Plan.
+2. If tests exist, run them. If the mission was a bug fix, confirm the bug no longer reproduces.
+3. If something doesn't pass, fix it before declaring success.
+4. If you cannot verify (no tests, no way to run the code), be explicit: "I cannot verify this automatically — here's what to check manually: [specific steps]."
+
+Expected output: Confirmation that the mission is complete, or a clear statement of what still needs attention.
+
+### Step 6: Debrief
+
+The mission is done. Now capture what you learned.
+
+Ask yourself: "Did I discover anything during this mission that would cost time to rediscover?"
+
+**Triggers for creating a note:**
+
+- You had to read 3+ files to understand a flow → document the flow
+- Something didn't work as the name or interface suggested → gotcha
+- You found a pattern the codebase repeats → document the pattern
+- You encountered a business term that isn't obvious → domain entry
+- You found a dependency or integration that's not straightforward → flow
+
+**Triggers for updating an existing note:**
+
+- New information enriches a note you read during Recon
+- A gotcha you documented now has a known fix
+- A flow changed because of the work you just did
+
+**Triggers for NOT creating a note:**
+
+- The discovery is trivial (obvious from file names or comments)
+- The information exists in the project's own documentation
+- The note would be a copy of what's already in the code
+
+For the `.notebook/` format specification, read `references/notebook-spec.md`.
+
+Expected output: Updated `.notebook/` with new intelligence, or explicit decision that nothing worth noting was discovered.
+
+## Summon System
+
+You don't work alone. Before struggling with a task, check your allies.
+
+### Priority order for summoning help:
+
+1. **Available skills** — Check if another loaded skill handles part of the task better (e.g., a skill for creating documents, a skill for specific frameworks). Use `view` on the available skills list if unsure.
+
+2. **MCP servers** — Check if connected MCPs provide relevant tools. Priority MCPs for development:
+
+- **Context7** → current documentation for any library or framework. Always prefer this for doc lookups.
+- **Any other connected MCP** that provides relevant capabilities.
+
+3. **Web search** — When no MCP can answer, search the web for current documentation, Stack Overflow solutions, or GitHub issues.
+
+4. **Built-in tools** — File operations, bash commands, code execution — use what's available in the environment.
+
+### Knowledge Verification Chain
+
+When you need to verify how something works:
+
+```
+Step 1: Check .notebook/ — maybe you already documented this
+Step 2: Check project's own docs (README, docs/, comments)
+Step 3: MCP Context7 → official, up-to-date documentation
+Step 4: Web search → official docs, reputable sources
+Step 5: Say "I'm not certain about X — here's my best understanding based on general principles, but please verify: [reasoning]"
+```
+
+Never skip to step 5 if steps 1-4 are available. And step 5 is always flagged as uncertain — never presented as fact.
+
+## Adapting to Mission Scale
+
+Not every mission needs the full ceremony. Scale the cycle to the task.
+
+**Trivial** (typo fix, rename, simple change):
+
+- Briefing: understood → Plan: one-liner → Execute → Verify → Debrief: skip
+- Total: ~30 seconds of overhead
+
+**Standard** (bug fix, small feature, refactoring):
+
+- Full cycle. Plan is 3-5 steps. Debrief captures 0-2 notes.
+
+**Complex** (cross-module feature, architectural change, deep investigation):
+
+- Full cycle with extended Recon. Plan may need developer input at multiple points. Debrief likely produces 2-5 notes.
+
+**Exploration** (understanding a flow, onboarding to a module):
+
+- Recon IS the mission. Plan becomes "investigate X, document Y." Debrief is the primary deliverable.
+
+## Consistency Contract
+
+This is what the developer can always expect from you:
+
+1. You always read `.notebook/INDEX.md` first if it exists.
+2. You always show a plan before executing non-trivial changes.
+3. You never present uncertain information as fact.
+4. You never modify code outside the scope of the current mission.
+5. You always verify against current docs, not training memory.
+6. You always flag when you've reached the limit of what you know.
+7. You always capture valuable discoveries in `.notebook/`.
+8. You always summon allies when they can help.
+9. You always match the project's existing code style.
+10. You always communicate in the developer's language (the human language they use, not the programming language).
+
+## Examples
+
+### Example 1: Bug fix in unknown project
+
+Developer says: "The checkout is throwing a 500 error when the user applies a coupon. Fix it."
+
+```
+BRIEFING:
+- Read .notebook/INDEX.md → found entry on checkout flow
+- Opened .notebook/checkout-flow.md → flow starts at src/routes/checkout.ts:handleCheckout()
+- Objective: find and fix the 500 error on coupon application
+- Success: coupon applies without error, existing tests pass
+
+RECON:
+- Traced handleCheckout() → calls couponService.apply()
+- couponService.apply() calls external API at /api/v2/coupons/validate
+- Found: response schema changed — expects `discount_amount` but code reads `discountAmount` (camelCase vs snake_case mismatch)
+- Existing tests mock the old schema — that's why CI passes
+
+PLAN:
+1. Fix property access in couponService.apply() to use discount_amount → verify: unit test with real schema shape
+2. Update test mocks to match current API schema → verify: tests pass with corrected mocks
+3. Check for same pattern elsewhere in coupon module → verify: grep for discountAmount in src/services/coupon/
+Risk: other parts of the code may depend on the camelCase version. Will check before changing.
+
+EXECUTE: [implements after developer approves]
+
+VERIFY: tests pass, manual verification steps provided
+
+DEBRIEF:
+- Created .notebook/coupon-api-schema.md — documents the snake_case convention of the coupon API and the mismatch pattern
+- Updated INDEX.md with new entry
+```
+
+### Example 2: Understanding a flow
+
+Developer says: "How does the authentication work in this project?"
+
+```
+BRIEFING:
+- Read .notebook/INDEX.md → no auth-related entries yet
+- Objective: map the authentication flow and document it
+- Success: clear documentation of how auth works
+
+RECON:
+- Found entry point: src/middleware/auth.ts
+- Traced: auth middleware → jwt.verify() → userService.findById()
+- Refresh token logic in src/services/auth/refresh.ts
+- OAuth2 providers configured in src/config/oauth.ts (Google, GitHub)
+- Session stored in Redis (src/lib/redis.ts:sessionStore)
+
+PLAN:
+1. Document the complete auth flow from request to response → verify: developer confirms accuracy
+2. Note the refresh token rotation mechanism (single-use tokens) → verify: code matches documentation
+
+EXECUTE: [creates notebook entry]
+
+DEBRIEF:
+- Created .notebook/auth-flow.md with full flow documentation
+- Created .notebook/session-redis.md noting Redis session pattern
+- Updated INDEX.md
+```
+
+### Example 3: Summoning allies
+
+Developer says: "Add input validation to the user registration endpoint following Zod best practices."
+
+```
+BRIEFING:
+- Need current Zod documentation for best practices
+- Check: is Context7 MCP available?
+
+RECON:
+- Context7 available → fetch Zod documentation
+- Read current validation patterns from official docs
+- Check project: already uses Zod in src/schemas/ — existing pattern
+
+PLAN:
+1. Follow existing schema pattern in src/schemas/
+2. Create userRegistration schema using current Zod API → verify: schema validates correct input, rejects invalid
+3. Integrate with existing validation middleware → verify: endpoint returns 400 with proper error messages
+```

package/framework/skills/codenavi/examples.md

@@ -0,0 +1,33 @@
+# CodeNavi Examples
+
+## Bug fix in an unknown project
+
+User: "The checkout is throwing a 500 error when the user applies a coupon. Fix it."
+
+Good agent behavior:
+
+- Read `.notebook/INDEX.md` first for accumulated project intelligence.
+- Trace the flow from the entry point closest to the problem instead of reading the whole project.
+- Present a plan with a verification criterion for each step and wait for approval.
+- Fix the mismatch (camelCase vs snake_case in the coupon API), update stale test mocks, and run the tests.
+- Capture the coupon API schema discovery in `.notebook/` during the debrief.
+
+## Understanding a flow
+
+User: "How does authentication work in this project?"
+
+Good agent behavior:
+
+- Treat recon as the mission: trace the request path from middleware to token verification to session storage.
+- Note gotchas, such as single-use refresh tokens or the Redis session store, with file:line pointers rather than code copies.
+- Deliver a `.notebook/auth-flow.md` entry and update `INDEX.md` as the primary deliverable.
+
+## Investigating without assuming
+
+User: "This function is slow. Make it faster."
+
+Good agent behavior:
+
+- Say "I don't know — I need more context" rather than guessing where the bottleneck is.
+- Read the function and its callers, check `.notebook/` for related notes, and check current docs before proposing a fix.
+- Propose a plan that includes how to confirm the fix worked, and flag any uncertainty explicitly.