CodeNavi workflow skill. Use this skill when the user needs 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 and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
CodeNavi workflow skill. Use this skill when the user needs 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 and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
This public intake copy packages packages/skills-catalog/skills/(development)/codenavi from https://github.com/tech-leads-club/agent-skills into the native Omni Skills editorial shape without hiding its origin.
Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.
This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.
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.
Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Mission Cycle, Summon System, Adapting to Mission Scale, Consistency Contract.
When to Use This Skill
Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.
Use when the request clearly matches the imported source intent: 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....
Use when the operator should preserve upstream workflow detail instead of rewriting the process from scratch.
Use when provenance needs to stay visible in the answer, PR, or review packet.
Use when copied upstream references, examples, or scripts materially improve the answer.
Use when the workflow should remain reviewable in the public intake repo before the private enhancer takes over.
Operating Table
Situation
Start here
Why it matters
First-time use
metadata.json
Confirms repository, branch, commit, and imported path through the external_source block before touching the copied workflow
Provenance review
ORIGIN.md
Gives reviewers a plain-language audit trail for the imported source
Workflow execution
references/coding-principles.md
Starts with the smallest copied file that materially changes execution
Supporting context
references/notebook-spec.md
Adds the next most relevant copied source file without loading the entire package
Handoff decision
## Related Skills
Helps the operator switch to a stronger native skill when the task drifts
Workflow
This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.
Confirm the user goal, the scope of the imported workflow, and whether this skill is still the right router for the task.
Read the overview and provenance files before loading any copied upstream support files.
Load only the references, examples, prompts, or scripts that materially change the outcome for the current request.
Execute the upstream workflow while keeping provenance and source boundaries explicit in the working notes.
Validate the result against the upstream expectations and the evidence you can point to in the copied files.
Escalate or hand off to a related skill when the work moves out of this imported workflow's center of gravity.
Before merge or closure, record what was used, what changed, and what the reviewer still needs to verify.
Imported Workflow Notes
Imported: Mission Cycle
Every task follows this cycle. No exceptions, no shortcuts.
Read .notebook/INDEX.md if it exists. This is your accumulated intelligence about the project — use it.
Listen to the developer's request. Identify:
What is the objective?
What does success look like?
What constraints exist?
If anything is unclear, ask. Do not proceed with ambiguity. Frame questions precisely: "I need to understand X before I can Y."
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.
Start from the entry point closest to the problem. Do not read the entire project.
Trace the flow that relates to the mission. Follow imports, calls, and data paths.
Check .notebook/ entries that might be relevant (INDEX.md tags).
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.
Check each verification criterion from the Plan.
If tests exist, run them. If the mission was a bug fix, confirm the bug no longer reproduces.
If something doesn't pass, fix it before declaring success.
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.
Examples
Example 1: Ask for the upstream workflow directly
Use @codenavi to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.
Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.
Example 2: Ask for a provenance-grounded review
Review @codenavi against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.
Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.
Example 3: Narrow the copied support files before execution
Use @codenavi for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.
Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.
Example 4: Build a reviewer packet
Review @codenavi using the copied upstream files plus provenance, then summarize any gaps before merge.
Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.
Imported Usage Notes
Imported: 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
Best Practices
Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.
Never assume, never invent. If you don't know, say "I don't know — I need more context." Uncertainty is always explicit.
If it cost investigation, it deserves a note. Knowledge that would take time to rediscover goes into .notebook/.
Pointers, not copies. Reference code by file:function() or file (L10-25). Never paste code blocks into notes.
Surgical precision. Touch only what the mission requires. Match existing style. Leave unrelated code alone.
Verify against source, not memory. Language best practices, API signatures, framework behavior — always confirm with current documentation before acting.
Keep the imported skill grounded in the upstream repository; do not invent steps that the source material cannot support.
Prefer the smallest useful set of support files so the workflow stays auditable and fast to review.
Imported Operating Notes
Imported: The Golden Rules
These rules override everything else. They are non-negotiable.
Never assume, never invent. If you don't know, say "I don't know — I need more context." Uncertainty is always explicit.
If it cost investigation, it deserves a note. Knowledge that would take time to rediscover goes into .notebook/.
Pointers, not copies. Reference code by file:function() or file (L10-25). Never paste code blocks into notes.
Surgical precision. Touch only what the mission requires. Match existing style. Leave unrelated code alone.
Verify against source, not memory. Language best practices, API signatures, framework behavior — always confirm with current documentation before acting.
Troubleshooting
Problem: The operator skipped the imported context and answered too generically
Symptoms: The result ignores the upstream workflow in packages/skills-catalog/skills/(development)/codenavi, fails to mention provenance, or does not use any copied source files at all.
Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.
Problem: The imported workflow feels incomplete during review
Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task.
Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.
Problem: The task drifted into a different specialization
Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better.
Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.
Related Skills
@accessibility - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-cold-outreach - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-pricing - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-sdr - Use when the work is better handled by that native specialization after this imported skill establishes context.
Additional Resources
Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.
Resource family
What it gives the reviewer
Example path
references
copied reference notes, guides, or background material from upstream
references/coding-principles.md
examples
worked examples or reusable prompts copied from upstream
examples/n/a
scripts
upstream helper scripts that change execution or validation
scripts/n/a
agents
routing or delegation notes that are genuinely part of the imported package
agents/n/a
assets
supporting assets or schemas copied from the source package
You don't work alone. Before struggling with a task, check your allies.
Priority order for summoning help:
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.
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.
Web search — When no MCP can answer, search the web for current documentation, Stack Overflow solutions, or GitHub issues.
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.
Imported: Adapting to Mission Scale
Not every mission needs the full ceremony. Scale the cycle to the task.
