octocode-cli 1.2.10 → 1.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-cli",
-  "version": "1.2.10",
+  "version": "1.2.11",
   "description": "Interactive CLI installer for octocode-mcp - Configure MCP servers for Cursor, Claude Desktop, and more",
   "keywords": [
     "ai-coding",

package/skills/octocode-engineer/SKILL.md

@@ -1,29 +1,27 @@
 ---
 name: octocode-engineer
-description: "System-aware engineering skill for code understanding, safe implementation, refactoring, architecture review, and quality analysis. Use this before planning and for general task support when an agent must start with local Octocode tools, use AST search/tree-search to prove structure, and combine those checks with LSP and scanner results to understand structure, flows, blast radius, contracts, documentation gaps, and architectural risk instead of looking only at one file. Aims to improve any system, and is especially effective for Node-based applications."
+description: "System-aware engineering skill for code understanding, safe implementation, refactoring, architecture review, and quality analysis. Use this before planning and for general task support when an agent must start with local Octocode tools, use AST search/tree-search to prove structure, and combine those checks with LSP and scanner results to understand flows, feature surfaces, system summary, blast radius, contracts, documentation gaps, build/configuration risks, and architectural risk instead of looking only at one file. Aims to improve any system, and is especially effective for Node-based applications."
 ---
 
 # Octocode Engineer
 
 This skill helps an agent investigate, change, and verify a codebase with system awareness.
 
-Use this skill before writing a plan. First build system understanding, then switch to plan mode once structure, flows, blast radius, and architectural risks are clear.
-Use it as an organizer for agents: pick the right lens, choose the right tools, understand the system, then move into planning or implementation.
-Use it with a senior-architect review posture: check whether the system is clear, modular, extensible, efficient, documented, and safe to evolve.
-Start with local Octocode tools whenever they are available. Use AST to check and prove structural claims instead of trusting text search alone.
+Use this skill before planning or implementation. Treat it as the agent organizer for understanding the system first, then acting with a senior-architect mindset.
 
-Most agents naturally zoom into the file in front of them. This skill pushes the opposite direction first:
-- start with local Octocode discovery before deep reading
-- use AST to check structural patterns and confirm smells
-- understand the structure before editing the line
-- trace flows before changing behavior
-- check architecture before trusting a local fix
-- validate important claims from more than one angle
+Default operating mode:
+1. Start with local Octocode tools for discovery and scope.
+2. Use AST to prove structural claims.
+3. Use LSP and scanner results to understand semantics, blast radius, and architecture.
+4. Summarize the system, flows, features, and constraints in your own reasoning.
+5. Only then decide whether to ask, plan, explain, or edit.
 
 ## What This Skill Does
 
 Use this skill to:
-- help with almost any engineering task, especially before planning, by organizing investigation and decision-making
+- organize investigation and decision-making for almost any engineering task
+- understand the main flows, summarize the system clearly, and identify what features and capabilities actually exist
+- stay aware of which local Octocode, LSP, AST, scanner, and project tools are available before choosing an approach
 - understand how a feature, bug, or module really works
 - trace definitions, callers, callees, imports, and shared contracts
 - find architectural issues such as cycles, chokepoints, coupling, hotspots, and layer violations
@@ -33,6 +31,7 @@ Use this skill to:
 - flag rigid, naive, brittle, or clearly unnecessary code paths before they spread
 - prevent patchy fixes that work locally but make the system harder to extend later
 - improve both delivery velocity and long-term quality through smarter flows and better structure
+- check build and configuration when needed or requested, including module-system mistakes such as incorrect ESM/CJS usage
 - plan safer refactors with blast-radius awareness
 - check that important critical aspects are documented when behavior, contracts, architecture, or operations depend on them
 - verify that a change did not create new code-quality, architecture, or test-quality problems
@@ -45,11 +44,11 @@ It applies to any system, but is especially effective for Node and TypeScript ap
 ## When To Use It
 
 Use this skill when the user asks to:
-- help with almost any code or architecture task that benefits from better system understanding first
 - understand code before changing it
 - fix a bug in shared or unclear code
 - refactor a module, package, or cross-file flow
 - review code quality, architecture, or technical debt
+- investigate build, runtime, package, or configuration issues when they affect behavior or delivery
 - improve maintainability, modularity, contracts, or extensibility
 - validate docs, plans, or RFCs against the real implementation
 - check dead code, test gaps, security risks, or design problems
@@ -59,15 +58,17 @@ Use this skill when the user asks to:
 ## Core Mindset
 
 1. System first, file second.
-2. Root causes often live in boundaries, flows, ownership, coupling, or missing tests, not just in the visible line of code.
-3. Important findings should be validated with at least 2 approaches when possible.
-4. Prefer local Octocode tools first for discovery, scope, and evidence.
-5. Use AST to check structural claims whenever text search may be misleading.
-6. Report confidence clearly: `confirmed`, `likely`, or `uncertain`.
-7. Prefer clean, modular, contract-driven solutions over local patches.
-8. For medium or large changes, understand blast radius and architecture before editing.
-9. Track meaningful work with tasks or todos when the runtime supports it.
-10. Ask the user at the right checkpoint when scope, risk, or tradeoffs are genuinely unclear.
+2. Understand flows, features, and current system behavior before proposing fixes.
+3. Root causes often live in boundaries, flows, ownership, coupling, build/configuration mistakes, or missing tests, not just in the visible line of code.
+4. Important findings should be validated with at least 2 approaches when possible.
+5. Prefer local Octocode tools first for discovery, scope, and evidence.
+6. Use AST to check structural claims whenever text search may be misleading.
+7. Keep a running system summary in mind: what exists, what owns what, what connects to what, and which tools can prove it.
+8. Report confidence clearly: `confirmed`, `likely`, or `uncertain`.
+9. Prefer clean, modular, contract-driven solutions over local patches.
+10. For medium or large changes, understand blast radius and architecture before editing.
+11. Track meaningful work with tasks or todos when the runtime supports it.
+12. Ask the user at the right checkpoint when scope, risk, or tradeoffs are genuinely unclear.
 
 ## The Main Problem This Skill Solves
 
@@ -78,6 +79,7 @@ A function may look wrong, but the real issue may be:
 - a shared module doing too much
 - a weak boundary between layers
 - weak or implicit contracts between modules, APIs, or types
+- build or configuration mistakes, such as wrong ESM/CJS assumptions, broken module resolution, or incorrect package wiring
 - inefficient loops, repeated work, or avoidable `O(n^2)` logic
 - rigid or brittle code that is hard to extend without patching around it
 - duplicate logic spread across packages
@@ -86,10 +88,12 @@ A function may look wrong, but the real issue may be:
 - a quick patch that solves today but blocks safe extension tomorrow
 
 Because of that, always look at:
+- summary: what the system does, which features exist, and how the parts connect
 - structure: where code lives and how modules are grouped
 - architecture: dependencies, boundaries, cycles, hotspots, and ownership
 - contracts: TypeScript types, interfaces, DTOs, schemas, and public module boundaries
 - flows: entry points, call chains, data movement, and side effects
+- build/config: package/module format, tsconfig/bundler/runtime assumptions, scripts, env wiring, and compatibility edges
 - quality: clean code, low duplication, CSS hygiene, and maintainable module responsibilities
 - efficiency: algorithmic complexity, repeated work, repeated queries, N+1 patterns, and unnecessary orchestration
 - rigidity: brittle logic, over-coupled decisions, and code that is harder than necessary to extend
@@ -107,6 +111,7 @@ The target is a system that stays extendable, understandable, and fast to change
 | Semantics | What symbol is this and who uses it? | `localSearchCode` -> LSP tools |
 | Persistence | How is state stored and mutated? | schema files, SQL/Prisma/Mongoose definitions, migration files, repository/storage modules |
 | Efficiency | Is the implementation doing avoidable work or unnecessary complexity? | scanner complexity findings, code read, query/storage access paths, tests/benchmarks when available |
+| Build & Config | Is runtime/build setup correct for this feature or environment? | package/module config, tsconfig, bundler config, scripts, import/export patterns, build errors |
 | Docs | Are critical behaviors, contracts, flows, and operational constraints documented? | docs/readmes, API docs, config docs, migration notes, code comments near boundaries |
 | Structure | Does this pattern really exist? | `scripts/ast/search.js`, `scripts/ast/tree-search.js` |
 | Architecture | Is this area hard or risky to change? | `scripts/run.js`, graph and flow modes |
@@ -200,6 +205,7 @@ Use supporting quality checks when the task touches the relevant surface area.
 | duplication review | repeated logic, near-clones, copy-pasted flows, repeated CSS patterns, general redundancy |
 | efficiency review | avoidable `O(n^2)` work, repeated scans, N+1 calls, wasteful transforms, unnecessary recomputation |
 | rigidity review | brittle condition trees, hard-coded branching, patchy glue code, over-coupled modules, naive solutions |
+| build/config review | ESM/CJS mismatch, bad module resolution, wrong script wiring, incompatible runtime assumptions, broken package setup |
 | docs review | whether critical assumptions, contracts, flows, setup, migrations, and risks are documented where they should be |
 | clean CSS review | selector scope, token reuse, naming clarity, dead styles, layout consistency |
 | `knip` | unused exports, unused files, unused dependencies, dead integration edges |
@@ -235,13 +241,14 @@ For any non-trivial task, follow this order:
 3. Map the package/module area with local tools.
 4. Trace important symbols with LSP.
 5. Validate and check structural claims with AST tools.
-6. Check architecture, docs, and flow risk with the scanner and relevant docs.
+6. Check architecture, build/configuration, docs, and flow risk with the scanner and relevant project files.
 7. Read the actual code with context.
-8. Pause and ask the user if a real decision checkpoint appears.
-9. Only then decide whether to explain, plan, or edit.
+8. Summarize the current system, flows, and feature surface before deciding on action.
+9. Pause and ask the user if a real decision checkpoint appears.
+10. Only then decide whether to explain, plan, or edit.
 
 Short form:
-`clarify -> track -> layout -> symbols -> structure -> architecture/docs -> code -> checkpoint -> action`
+`clarify -> track -> layout -> symbols -> structure -> architecture/build/docs -> code -> summarize -> checkpoint -> action`
 
 ## How To Use This Skill
 
@@ -251,8 +258,10 @@ Short form:
 2. Use `localSearchCode` to find the symbol or flow.
 3. Use LSP to trace definitions, references, callers, and callees.
 4. Read the relevant code only after the surrounding context is clear.
-5. Check whether important contracts or critical flows are documented.
-6. If the area is shared, central, or suspicious, run a scoped scanner pass.
+5. Summarize the key flows, feature surface, and boundaries in your own reasoning.
+6. Check whether important contracts or critical flows are documented.
+7. If build or runtime behavior is involved, inspect build/config assumptions.
+8. If the area is shared, central, or suspicious, run a scoped scanner pass.
 
 ### For bug fixing
 
@@ -260,18 +269,19 @@ Short form:
 2. Trace incoming callers and outgoing callees.
 3. Check adjacent risk areas: error handling, retries, side effects, tests, shared consumers, and contract mismatches.
 4. Use AST tools if the bug may involve a structural smell.
-5. Use the scanner if the bug points to a hotspot, cycle, or orchestration problem.
-6. Fix the smallest layer that solves the root cause, not just the symptom.
-7. Prefer a clean boundary or contract fix over a narrow patch if the issue is systemic.
-8. Check whether the bug is caused by redundant work, inefficient flow, or rigid branching.
-9. Check whether the risky behavior and fix assumptions should be documented.
+5. Check build/configuration if module format, runtime wiring, or packaging may be involved.
+6. Use the scanner if the bug points to a hotspot, cycle, or orchestration problem.
+7. Fix the smallest layer that solves the root cause, not just the symptom.
+8. Prefer a clean boundary or contract fix over a narrow patch if the issue is systemic.
+9. Check whether the bug is caused by redundant work, inefficient flow, or rigid branching.
+10. Check whether the risky behavior and fix assumptions should be documented.
 
 ### For refactors
 
 1. Measure blast radius with `lspFindReferences` and `lspCallHierarchy`.
 2. Check architecture health in the target area with `scripts/run.js --scope=...`.
 3. Look for similar patterns nearby with AST or local search.
-4. Check whether duplication, weak contracts, or bad boundaries are the real refactor driver.
+4. Check whether duplication, weak contracts, bad boundaries, or build/config friction are the real refactor driver.
 5. Plan the change if multiple files, packages, or shared symbols are involved.
 6. Prefer extracting modules, clarifying contracts, simplifying flows, and removing redundant work over cosmetic reshuffling.
 7. Implement incrementally.
@@ -285,7 +295,7 @@ Short form:
 3. Use local tools to understand the folder and package layout.
 4. Use LSP to verify the real dependency pressure around candidate modules.
 5. Read representative files to explain why the structure is problematic.
-6. Check whether contracts, duplication, and module boundaries support extensibility.
+6. Check whether contracts, duplication, module boundaries, and build/runtime setup support extensibility.
 7. Check whether critical architectural constraints are documented.
 8. Report both local code issues and system-level causes.
 
@@ -301,6 +311,7 @@ Short form:
 | Can I prove this structural claim? | AST search/tree-search + targeted code read |
 | Are contracts weak or inconsistent? | LSP on public symbols + code read + scanner/AST signals |
 | Is this implementation inefficient? | scanner complexity signals + code read + persistence/query path review |
+| Is build/config part of the problem? | scripts/config review + import/export patterns + build/type errors + package/module checks |
 | Is this dead code? | `lspFindReferences` + AST import/export check + scanner dead-code signals |
 | Is this module risky to change? | scanner scope + LSP references/call flow + code read |
 | Is the problem architectural? | scanner graph/flow + local structure + LSP on chokepoints |
@@ -315,6 +326,7 @@ Short form:
 - find consumers and callers
 - inspect tests around the changed path
 - check whether the area is a hotspot, cycle member, or shared boundary
+- check whether build/configuration assumptions are part of the behavior
 - check contracts: types, inputs, outputs, schemas, and public APIs
 - check whether critical behavior and constraints are documented
 - check for duplication before adding another branch or helper
@@ -327,6 +339,7 @@ Short form:
 - prefer the smallest change that fixes the real issue
 - prefer the cleanest modular fix that keeps the system extendable
 - maintain clear contracts, especially in TypeScript-heavy code
+- keep build/configuration consistent with runtime expectations, especially around ESM/CJS boundaries
 - reduce redundancy and avoid layering new logic on top of rigid or naive code when a cleaner simplification is possible
 - improve inefficient flows when they are part of the real problem
 - keep CSS clean and scoped if the task touches frontend styling
@@ -338,6 +351,7 @@ Short form:
 - run lint and build or type-check as appropriate
 - run CSS checks when styles changed
 - run `knip` when refactors may have left dead exports, files, or deps behind
+- verify build and configuration still match runtime/module expectations
 - re-check changed symbols with LSP after renames or moves
 - run a scoped scanner pass for non-trivial changes
 - verify important critical aspects are documented if the task changed them
@@ -367,6 +381,7 @@ Examples:
 - Never skip local Octocode discovery when those tools are available.
 - Never present an important structural claim without checking it with AST when AST can prove it.
 - Never stop at code style if the deeper issue is structure or flow.
+- Never ignore build or configuration evidence when behavior may depend on package/module/runtime setup.
 - Never prefer a quick patch when the real issue is contracts, boundaries, duplication, or architecture.
 - Never ignore obvious inefficiency, redundancy, or rigid code if it materially hurts extensibility or clarity.
 - Never add new duplication if an existing abstraction or module should be improved instead.
@@ -394,6 +409,7 @@ A good result from this skill should answer all of these:
 - What is the blast radius?
 - Are the contracts clear and safe?
 - Is the problem local, structural, or architectural?
+- Is build/configuration part of the issue?
 - Is the implementation efficient enough, or is avoidable complexity hurting it?
 - Is the system becoming cleaner, more modular, and easier to extend?
 - Are important critical aspects documented?