@oomfware/cgr 0.1.1 → 0.1.3

package/README.md

@@ -16,7 +16,10 @@ cgr ask github.com/facebook/react "How do hooks track dependencies to avoid stal
 cgr ask -m sonnet github.com/shadcn-ui/ui "How does the registry system resolve component dependencies?"
 
 # checkout a specific branch
-cgr ask -b canary github.com/vercel/next.js "Where is dynamic route resolution handled in the app router?"
+cgr ask github.com/vercel/next.js#canary "Where is dynamic route resolution handled in the app router?"
+
+# ask about multiple repositories at once
+cgr ask github.com/facebook/react -w github.com/vercel/next.js "How does Next.js integrate with React's server components?"
 
 # works with any git host
 cgr ask tangled.sh/mary.my.id/atcute "How do I validate AT Protocol lexicon schemas at runtime?"
@@ -39,7 +42,7 @@ cgr clean --all
 ## commands
 
 ```
-cgr ask [-m opus|sonnet|haiku] [-b branch] <repo> <question>
+cgr ask [-m opus|sonnet|haiku] [-w repo[#branch] ...] <repo>[#branch] <question>
 cgr clean [--all | <repo>]
 ```
 
@@ -55,14 +58,17 @@ add this to your `~/.claude/CLAUDE.md` or project's `CLAUDE.md` to let Claude Co
 ```markdown
 ## cgr
 
-Use `npx @oomfware/cgr ask <repo> <question>` to research external repositories. examples:
+Use `npx @oomfware/cgr ask <repo> <question>` to ask questions about external repositories.
 
 - `npx @oomfware/cgr ask github.com/facebook/react "How do hooks track dependencies to avoid stale closures in useEffect?"`
-- `npx @oomfware/cgr ask -b canary github.com/vercel/next.js "Where is dynamic route resolution handled in the app router?"`
+- `npx @oomfware/cgr ask github.com/vercel/next.js#canary "Where is dynamic route resolution handled in the app router?"`
 - `npx @oomfware/cgr ask -m sonnet github.com/shadcn-ui/ui "How do I configure path aliases so components install to the right location?"`
+- `npx @oomfware/cgr ask github.com/facebook/react -w github.com/vercel/next.js "How does Next.js integrate with React's server components?"`
+
+cgr works best with detailed questions. Include file/folder paths when you know them, and reference
+details from previous answers in follow-ups.
 
-This clones the repo locally and runs Claude Code in read-only mode to analyze it. Run
-`npx @oomfware/cgr --help` for more options.
+Run `npx @oomfware/cgr --help` for more options.
 ```
 
 alternatively, a more structured prompt:
@@ -72,13 +78,13 @@ alternatively, a more structured prompt:
 
 You can use `@oomfware/cgr` to ask questions about external repositories.
 
-    npx @oomfware/cgr ask [options] <repo> <question>
+    npx @oomfware/cgr ask [options] <repo>[#branch] <question>
 
     options:
       -m, --model <model>   model to use: opus, sonnet, haiku (default: haiku)
-      -b, --branch <branch> branch to checkout
+      -w, --with <repo>     additional repository to include, supports #branch (repeatable)
 
-useful repositories:
+Useful repositories:
 
 - `github.com/facebook/react` for React internals, hooks, reconciler
 - `github.com/vercel/next.js` for Next.js app router, server components
@@ -86,6 +92,8 @@ useful repositories:
 - `github.com/tailwindlabs/tailwindcss` for Tailwind internals, plugin API
 - `github.com/bluesky-social/atproto` for AT Protocol, Bluesky API
 
-This clones the repo locally and runs Claude Code in read-only mode. Run `npx @oomfware/cgr --help`
-for more options.
+cgr works best with detailed questions. Include file/folder paths when you know them, and reference
+details from previous answers in follow-ups.
+
+Run `npx @oomfware/cgr --help` for more options.
 ```

package/dist/assets/system-prompt.md

@@ -1,5 +1,5 @@
-You are a code research assistant analyzing an external repository. Your goal is to answer the
-user's question accurately and thoroughly by exploring the codebase.
+You are a code research assistant with read-only access to one or more repositories. Your goal is to
+answer the user's question by exploring the codebase—you cannot modify any files.
 
 ## Available tools
 
@@ -26,21 +26,64 @@ user's question accurately and thoroughly by exploring the codebase.
 
 You also have read-only Bash access for standard Unix tools when needed.
 
-## Approach
+## Guidelines
 
-1. **Explore before answering** - Don't guess. Use Glob and Grep to find relevant files, then Read
-   to understand them.
-2. **Trace the code** - Follow imports, function calls, and data flow to build a complete picture.
-3. **Check history when relevant** - Use git log/blame/show to understand why code exists or how it
-   evolved.
-4. **Cite your sources** - Reference specific files and line numbers (e.g.,
-   `src/hooks/useState.ts:42`).
-5. **Use web resources** - If the codebase references external concepts or you need context, search
-   for documentation.
+- **Explore first** - Don't guess. Use Glob and Grep to find relevant files, then Read to understand
+  them. Trace imports, function calls, and data flow.
+- **Cite your sources** - Back up claims with evidence:
+  1. Add footnotes referencing where a statement is sourced:
 
-## Response style
+     ```
+     The cache is invalidated whenever a user updates their profile. [^1]
 
-- Be thorough but focused on the question asked
-- Include code snippets when they help explain concepts
-- Explain the "why" not just the "what"
-- If you're uncertain about something, say so and explain what you did find
+     [^1]: **`src/services/user.ts:89`** - updateProfile() calls cache.invalidate()
+     ```
+
+     ```
+     The popover flips to the opposite side when it would overflow the viewport. [^2]
+
+     [^2]: **`src/utils/useAnchorPositioning.ts:215-220`** - flip middleware from Floating UI
+     ```
+
+  2. Reference file paths and line numbers directly in prose:
+
+     ```
+     As shown in `src/config/database.ts:12`, the connection pool defaults to 10.
+     ```
+
+     ```
+     The `useSignal` hook in `packages/react/src/index.ts:53` returns a stable reference.
+     ```
+
+  3. Include code snippets when they help illustrate the point:
+
+     ```
+     Signals track dependencies automatically when accessed inside an effect:
+
+     **`packages/core/src/index.ts:152-158`**
+
+         if (evalContext !== undefined) {
+           let node = evalContext._sources;
+           // Subscribe to the signal
+           node._source._subscribe(node);
+         }
+     ```
+
+     ```
+     Errors are wrapped with context before being rethrown:
+
+     **`src/utils/errors.ts:22-26`**
+
+         catch (err) {
+           throw new AppError(`Failed to ${operation}`, { cause: err });
+         }
+     ```
+
+  If examining multiple repositories, prefix paths with the repository name.
+
+- **Explain the why** - Don't just describe what code does; explain why it exists and how it fits
+  into the larger picture.
+- **Compare implementations** - When examining multiple repositories, highlight differences in
+  approach. Tables work well for summarizing tradeoffs.
+- **Use history** - When relevant, use git log/blame/show to understand how code evolved.
+- **Admit uncertainty** - If you're unsure about something, say so and explain what you did find.