@codemap-ai/cli 0.1.0

package/agent-pack/templates/COPILOT.md

@@ -0,0 +1,75 @@
+# COPILOT.md
+
+Use CodeMap MCP as the first context source for codebase work.
+
+- Prefer CodeMap tools before raw file reads.
+- Start with `get_project`.
+- For broad implementation/debug/review/refactor/test/research work with unclear files, call `explore_task`.
+- Use `find_related_files` or `search_codebase` to locate files.
+- Use `get_file` and `symbol` to keep context small.
+- Use `symbol` for impact analysis.
+- Read MCP summaries, ranking reasons, next steps, and resource URIs before expanding context.
+- Verify with focused build/test commands and reimport after meaningful changes.
+
+## Brainstorming (design before code)
+
+For new features or vague requirements, design first — never write production code before the design is approved.
+
+1. Call `explore_task` to gather real codebase context.
+2. Ask clarifying questions one at a time until scope is clear.
+3. Propose 2–3 approaches with trade-offs, referencing real files from CodeMap.
+4. Write a design doc (`docs/specs/YYYY-MM-DD-<topic>.md`) covering goal, approach, affected files, and open questions.
+5. Self-review the spec, then wait for user approval before touching any file.
+
+## Test-Driven Development
+
+For new functionality or bug fixes, follow RED → GREEN → REFACTOR strictly.
+
+- **RED**: `search_codebase("test <feature>")` to find patterns, write a minimal failing test, run with the host agent test runner and confirm it **fails**.
+- **GREEN**: Use `symbol` to read the target, implement only the minimum to pass, run the host agent test runner and confirm it **passes**.
+- **REFACTOR**: Clean up, run the host agent test runner again, then call `diff(mode="working")` before declaring done.
+
+No production code before a failing test exists.
+
+## Feature Area Investigation
+
+Use when the task involves a named feature (billing, auth, admin, graph, etc.).
+
+1. Call `explore_task(query)` — review likely files, entrypoints, and recommended reads.
+2. Call `get_file(path=[...])` on the top results to survey outlines without loading full files.
+3. Use `symbol` for the most relevant component, service, or controller.
+4. If still unclear, call `find_related_files` anchored to the best file found.
+
+## Symbol-Level Debugging
+
+Use when a bug or behavior centers on a specific function, class, component, or method.
+
+1. `search_codebase(symbol_name)` if the file is unknown.
+2. `symbol(action="context", symbol_name, file_path)` for the exact body.
+3. `symbol` when call flow or impact matters.
+4. Read only adjacent files needed to explain or change the behavior.
+
+Do not read an entire large file to inspect one symbol when CodeMap can return symbol context.
+
+## Interpreting CodeMap Output
+
+After any CodeMap tool returns ranked files, symbols, or related files:
+
+1. Read the summary first — decide if it is enough to act before expanding.
+2. Prefer high-ranked results before low-ranked ones.
+3. Follow `nextSteps`, `resourceUris`, and suggested tool calls before opening raw files.
+4. Use ranking signals to filter: exact path/symbol match = strong; fuzzy keyword = weak.
+5. Stop expanding context once the edit or answer is grounded enough.
+
+When results look weak or noisy, refine the query, anchor to a known file or symbol, or switch tool.
+
+## Token-Efficient Code Review
+
+Use when reviewing changes in a CodeMap-indexed repository.
+
+1. Start with `diff(mode="working")` or `diff(mode="refs")`.
+2. For changed symbols, use `symbol` instead of full-file reads.
+3. Use `symbol` for risky public API or shared behavior changes.
+4. Lead findings by severity. Mention test gaps and residual risk.
+
+Review behavior and integration risks — avoid summarizing broad context unless it supports a finding.

package/agent-pack/templates/GEMINI.md

@@ -0,0 +1,77 @@
+# GEMINI.md
+
+Use CodeMap MCP before raw file reads or grep.
+
+Default workflow:
+
+1. Call `get_project`.
+2. For broad implementation/debug/review/refactor/test/research work with unclear files, call `explore_task`.
+3. Use `explore_task` for broad implementation/debugging.
+4. Use `find_related_files` for anchor file/symbol questions.
+6. Use `search_codebase` for known symbols, exports, filenames, or keywords.
+7. Use `get_file` for outlines and `symbol` for exact bodies.
+8. Read MCP summaries, rankings, score reasons, next steps, and resource URIs before opening raw files.
+9. After edits, build/test, inspect diff, and reimport when needed.
+
+## Brainstorming (design before code)
+
+For new features or vague requirements, design first — never write production code before the design is approved.
+
+1. Call `explore_task` to gather real codebase context.
+2. Ask clarifying questions one at a time until scope is clear.
+3. Propose 2–3 approaches with trade-offs, referencing real files from CodeMap.
+4. Write a design doc (`docs/specs/YYYY-MM-DD-<topic>.md`) covering goal, approach, affected files, and open questions.
+5. Self-review the spec, then wait for user approval before touching any file.
+
+## Test-Driven Development
+
+For new functionality or bug fixes, follow RED → GREEN → REFACTOR strictly.
+
+- **RED**: `search_codebase("test <feature>")` to find patterns, write a minimal failing test, run with the host agent test runner and confirm it **fails**.
+- **GREEN**: Use `symbol` to read the target, implement only the minimum to pass, run the host agent test runner and confirm it **passes**.
+- **REFACTOR**: Clean up, run the host agent test runner again, then call `diff(mode="working")` before declaring done.
+
+No production code before a failing test exists.
+
+## Feature Area Investigation
+
+Use when the task involves a named feature (billing, auth, admin, graph, etc.).
+
+1. Call `explore_task(query)` — review likely files, entrypoints, and recommended reads.
+2. Call `get_file(path=[...])` on the top results to survey outlines without loading full files.
+3. Use `symbol` for the most relevant component, service, or controller.
+4. If still unclear, call `find_related_files` anchored to the best file found.
+
+## Symbol-Level Debugging
+
+Use when a bug or behavior centers on a specific function, class, component, or method.
+
+1. `search_codebase(symbol_name)` if the file is unknown.
+2. `symbol(action="context", symbol_name, file_path)` for the exact body.
+3. `symbol` when call flow or impact matters.
+4. Read only adjacent files needed to explain or change the behavior.
+
+Do not read an entire large file to inspect one symbol when CodeMap can return symbol context.
+
+## Interpreting CodeMap Output
+
+After any CodeMap tool returns ranked files, symbols, or related files:
+
+1. Read the summary first — decide if it is enough to act before expanding.
+2. Prefer high-ranked results before low-ranked ones.
+3. Follow `nextSteps`, `resourceUris`, and suggested tool calls before opening raw files.
+4. Use ranking signals to filter: exact path/symbol match = strong; fuzzy keyword = weak.
+5. Stop expanding context once the edit or answer is grounded enough.
+
+When results look weak or noisy, refine the query, anchor to a known file or symbol, or switch tool.
+
+## Token-Efficient Code Review
+
+Use when reviewing changes in a CodeMap-indexed repository.
+
+1. Start with `diff(mode="working")` or `diff(mode="refs")`.
+2. For changed symbols, use `symbol` instead of full-file reads.
+3. Use `symbol` for risky public API or shared behavior changes.
+4. Lead findings by severity. Mention test gaps and residual risk.
+
+Review behavior and integration risks — avoid summarizing broad context unless it supports a finding.

package/agent-pack/templates/design-spec.md

@@ -0,0 +1,34 @@
+# Design Spec: <topic>
+
+## Goal
+
+Describe the user-visible goal and why it matters.
+
+## Non-Goals
+
+List what this change intentionally will not do.
+
+## Context
+
+Summarize the CodeMap tools used and the relevant files, symbols, or feature areas found.
+
+## Chosen Approach
+
+Describe the selected design and why it fits the existing codebase.
+
+## Affected Interfaces
+
+List public APIs, schemas, commands, resources, routes, or user-visible behavior that changes.
+
+## Risks and Edge Cases
+
+Describe failure modes, compatibility concerns, and high-risk areas.
+
+## Verification
+
+List the build/test/manual checks that must pass.
+
+## Open Questions
+
+List questions that must be answered before implementation.
+

package/agent-pack/templates/implementation-plan.md

@@ -0,0 +1,26 @@
+# Implementation Plan: <topic>
+
+## Summary
+
+Briefly state the intended change and success criteria.
+
+## Key Edits
+
+List the exact files, modules, or feature areas to change.
+
+## Steps
+
+1. Orient with CodeMap and confirm current state.
+2. Make the smallest scoped code or docs changes.
+3. Update related resources, exports, or registrations.
+4. Run verification.
+5. Refresh local index and decide whether cloud reimport is needed.
+
+## Verification
+
+List exact commands and expected outcomes.
+
+## Assumptions
+
+Record any decisions the implementer must preserve.
+

package/agent-pack/templates/opencode-AGENTS.md

@@ -0,0 +1,76 @@
+# OpenCode CodeMap Agent Pack
+
+Use CodeMap MCP-first workflow in this repository.
+
+- New session: `get_project`.
+- Broad implementation/debug/review/refactor/test/research task with unclear files: `explore_task`.
+- Broad codebase exploration: `explore_task`.
+- Related files: `find_related_files`.
+- Known lookup: `search_codebase`.
+- Read many outlines: `get_file`.
+- Read exact symbol body: `symbol`.
+- Read MCP summaries, ranking reasons, next steps, and resource URIs before expanding context.
+- After edits: build/test, inspect diff, reimport when needed.
+
+## Brainstorming (design before code)
+
+For new features or vague requirements, design first — never write production code before the design is approved.
+
+1. Call `explore_task` to gather real codebase context.
+2. Ask clarifying questions one at a time until scope is clear.
+3. Propose 2–3 approaches with trade-offs, referencing real files from CodeMap.
+4. Write a design doc (`docs/specs/YYYY-MM-DD-<topic>.md`) covering goal, approach, affected files, and open questions.
+5. Self-review the spec, then wait for user approval before touching any file.
+
+## Test-Driven Development
+
+For new functionality or bug fixes, follow RED → GREEN → REFACTOR strictly.
+
+- **RED**: `search_codebase("test <feature>")` to find patterns, write a minimal failing test, run with the host agent test runner and confirm it **fails**.
+- **GREEN**: Use `symbol` to read the target, implement only the minimum to pass, run the host agent test runner and confirm it **passes**.
+- **REFACTOR**: Clean up, run the host agent test runner again, then call `diff(mode="working")` before declaring done.
+
+No production code before a failing test exists.
+
+## Feature Area Investigation
+
+Use when the task involves a named feature (billing, auth, admin, graph, etc.).
+
+1. Call `explore_task(query)` — review likely files, entrypoints, and recommended reads.
+2. Call `get_file(path=[...])` on the top results to survey outlines without loading full files.
+3. Use `symbol` for the most relevant component, service, or controller.
+4. If still unclear, call `find_related_files` anchored to the best file found.
+
+## Symbol-Level Debugging
+
+Use when a bug or behavior centers on a specific function, class, component, or method.
+
+1. `search_codebase(symbol_name)` if the file is unknown.
+2. `symbol(action="context", symbol_name, file_path)` for the exact body.
+3. `symbol` when call flow or impact matters.
+4. Read only adjacent files needed to explain or change the behavior.
+
+Do not read an entire large file to inspect one symbol when CodeMap can return symbol context.
+
+## Interpreting CodeMap Output
+
+After any CodeMap tool returns ranked files, symbols, or related files:
+
+1. Read the summary first — decide if it is enough to act before expanding.
+2. Prefer high-ranked results before low-ranked ones.
+3. Follow `nextSteps`, `resourceUris`, and suggested tool calls before opening raw files.
+4. Use ranking signals to filter: exact path/symbol match = strong; fuzzy keyword = weak.
+5. Stop expanding context once the edit or answer is grounded enough.
+
+When results look weak or noisy, refine the query, anchor to a known file or symbol, or switch tool.
+
+## Token-Efficient Code Review
+
+Use when reviewing changes in a CodeMap-indexed repository.
+
+1. Start with `diff(mode="working")` or `diff(mode="refs")`.
+2. For changed symbols, use `symbol` instead of full-file reads.
+3. Use `symbol` for risky public API or shared behavior changes.
+4. Lead findings by severity. Mention test gaps and residual risk.
+
+Review behavior and integration risks — avoid summarizing broad context unless it supports a finding.

package/agent-pack/templates/opencode-INSTALL.md

@@ -0,0 +1,5 @@
+# Install CodeMap Agent Pack For OpenCode
+
+This directory contains OpenCode-facing CodeMap guidance.
+
+Use CodeMap MCP as the context engine before raw file reads or grep. Follow `.opencode/AGENTS.md` for the default workflow.

package/agent-pack/templates/verification-report.md

@@ -0,0 +1,18 @@
+# Verification Report: <topic>
+
+## Diff Inspection
+
+Summarize changed files and whether they match the plan.
+
+## Commands Run
+
+List build, test, lint, or manual smoke checks and their results.
+
+## Indexing
+
+State whether `refresh_local_index` ran and whether cloud `reimport` was needed.
+
+## Skipped Checks
+
+List skipped checks with reasons and residual risk.
+