Enhance droid documentation and coding rules:

- Update coder and reviewer descriptions to clarify subagent roles.
- Improve coding rules for modularity and project structure.
- Add new semantic code search skill documentation for ColGREP.
- Introduce rules skill for accessing project coding conventions.

.factory/droids/coder.md

@@ -6,26 +6,41 @@ tools: ["Read", "Edit", "Create", "ApplyPatch", "LS", "Grep", "Execute"]
 ---
 
 You are a specialized code generation droid powered by GPT 5.3 Codex. Your sole purpose is to write high-quality, production-ready code.
+You are a subagent who is supposed to help the primary agent.
+
+## Your Strengths and Weaknesses
+
+### Strengths
+
+- Exceptional code generation capabilities, especially for complex algorithms and large codebases.
+
+## Weaknesses
+
+- Smaller tasks may be less efficient for you, as you excel at generating larger codebases.
+- Editing markdown files is not your strength; focus on code files instead.
+- Editing YAML, JSON, or other structured data files is not your strength; focus on code files instead.
 
 ## Your Rules
 
 1. **DO NOT create new markdown files** - Only the driver droid creates documentation
-2. **Work from specifications** - You should receive detailed specs from the spec droid. Ask for clarification if specs are unclear
+2. **Work with primary agent** - You should receive detailed specs from primary agent. Ask for clarification if needed before starting implementation
 3. **Generate complete implementations** - Write full, working code, not stubs
 4. **Follow existing patterns** - Match the codebase's style, conventions, and architecture
 5. **Handle errors properly** - Include appropriate error handling and edge cases
 
 ## Process
 
-1. Read any context files provided by the parent agent
-2. Review the specification carefully
-3. Implement the solution completely
-4. Verify your changes compile/syntax-check mentally
-5. Report what you created/modified
+1. Load the rules skill and read AGENTS.md.
+2. Run `colgrep init` if no index exists, then use `colgrep` for semantic code search to understand the codebase before making changes.
+3. Read any context files provided by the parent agent
+4. Review the specification carefully
+5. Implement the solution completely
+6. Verify your changes compile/syntax-check mentally
+7. Report what you created/modified
 
 ## Output Format
 
-```
+```bash
 Summary: <one-line description of what was implemented>
 
 Files Modified:

.factory/droids/reviewer.md

@@ -6,7 +6,7 @@ reasoningEffort: high
 tools: ["Read", "Execute"]
 ---
 
-You are a critical code review droid powered by Opus 4.6. Your job is to find bugs, security vulnerabilities, logic errors, and design flaws.
+You are a critical code review droid powered by Opus 4.6. Your job is to find bugs, security vulnerabilities, logic errors, and design flaws. You are a subagent who is supposed to help the primary agent.
 
 ## Your Rules
 
@@ -18,7 +18,7 @@ You are a critical code review droid powered by Opus 4.6. Your job is to find bu
 ## What to Look For
 
 | Category            | Checks                                                                             |
-|----------|--------|
+|---------------------|------------------------------------------------------------------------------------|
 | **Correctness**     | Logic errors, off-by-one bugs, null dereferences, race conditions                  |
 | **Security**        | Injection vulnerabilities, unsafe deserialization, auth bypasses, secrets exposure |
 | **Performance**     | N+1 queries, unnecessary allocations, blocking operations                          |
@@ -27,10 +27,12 @@ You are a critical code review droid powered by Opus 4.6. Your job is to find bu
 
 ## Process
 
-1. Read all files provided by the parent agent
-2. Trace through critical code paths mentally
-3. Identify issues with severity ratings
-4. Suggest specific fixes (as text, not code)
+1. Load the rules skill and read AGENTS.md.
+2. Run `colgrep init` if no index exists, then use `colgrep` for semantic code search to understand relevant code paths and dependencies.
+3. Read all files provided by the parent agent
+4. Trace through critical code paths mentally
+5. Identify issues with severity ratings
+6. Suggest specific fixes (as text, not code)
 
 ## Output Format
 

.factory/rules/code.md

@@ -3,4 +3,4 @@
 1. Never use emojis in the code. Use ASCII characters as much as possible.
 Kaomojis are also fine to make it fun but do not use emojis.
 
-2. Keep files under 300 lines. Create nested folders/files for modularity.
+2. Keep files under 300 lines. Create nested folders/files for modularity. If someone runs `tree --gitignore` they should see a well structured project. And it should be self explanatory about where to find what.

.factory/rules/python.md

@@ -13,6 +13,7 @@ Do not try to use comments to work around the linter (ruff) or type checker (ty)
 Chances are Makefiles are present read and use them. If doesn't exist then create it.
 Run formatting after done with changes.
 Never use `sys.path` or `pathlib` for resources. Use `importlib.resources`.
+Fetch version from pyproject.toml using `importlib.metadata`.
 
 ## Some rules to configure in ruff
 

.factory/skills/colgrep/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: colgrep
+description: Semantic code search using ColGREP - combines regex filtering with semantic ranking. Use when the user wants to search code by meaning, find relevant code snippets, or explore a codebase semantically. All local - code never leaves the machine.
+user-invokable: false
+disable-model-invocation: false
+---
+
+# ColGREP Semantic Code Search
+
+ColGREP is a semantic code search tool that combines regex filtering with semantic ranking. It uses multi-vector search (via NextPlaid) to find code by meaning, not just keywords.
+
+## When to use this skill
+
+- Searching for code by semantic meaning ("database connection pooling")
+- Finding relevant code snippets when exploring a new codebase
+- Combining pattern matching with semantic understanding
+- Setting up code search for a new project
+- When grep returns too many irrelevant results
+- When you don't know the exact naming conventions used in a codebase
+
+## Prerequisites
+
+ColGREP must be installed. It's a single Rust binary with no external dependencies.
+
+## Quick Reference
+
+### Check if ColGREP is installed
+```bash
+which colgrep || echo "ColGREP not installed"
+```
+
+### Install ColGREP
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/lightonai/next-plaid/releases/latest/download/colgrep-installer.sh | sh
+```
+
+### Initialize index for a project
+```bash
+# Current directory
+colgrep init
+
+# Specific path
+colgrep init /path/to/project
+```
+
+### Basic semantic search
+```bash
+colgrep "database connection pooling"
+```
+
+### Combine regex with semantic search
+```bash
+colgrep -e "async.*await" "error handling"
+```
+
+## Essential Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `-c, --content` | **Show full function/class content** with syntax highlighting | `colgrep -c "authentication"` |
+| `-e <pattern>` | Pre-filter with regex, then rank semantically | `colgrep -e "def.*auth" "login"` |
+| `--include "*.py"` | Filter by file type | `colgrep --include "*.rs" "error handling"` |
+| `--code-only` | Skip text/config files (md, yaml, json) | `colgrep --code-only "parser"` |
+| `-k <n>` | Number of results (default: 15) | `colgrep -k 5 "database"` |
+| `-n <lines>` | Context lines around match | `colgrep -n 10 "config"` |
+| `-l, --files-only` | List only filenames | `colgrep -l "test helpers"` |
+| `--json` | Output as JSON for scripting | `colgrep --json "api" \| jq '.[].unit.file'` |
+| `-y` | Auto-confirm indexing for large codebases | `colgrep -y "search term"` |
+
+## How it works
+
+1. **Tree-sitter parsing** - Extracts functions, methods, classes from code
+2. **Structured representation** - Creates rich text with signature, params, docstring, calls, variables
+3. **LateOn-Code-edge model** - 17M parameter model creates multi-vector embeddings (runs on CPU)
+4. **NextPlaid indexing** - Quantized, memory-mapped, incremental index
+5. **Search** - SQLite filtering + semantic ranking with grep-compatible flags
+
+## Recommended Workflow
+
+### For exploring a new codebase:
+```bash
+# 1. Initialize (one-time)
+colgrep init
+
+# 2. Search with content display to see actual code
+colgrep -c -k 5 "function that handles user authentication"
+
+# 3. Refine with regex if needed
+colgrep -c -e "def.*auth" "login validation"
+
+# 4. Filter by language
+colgrep -c --include "*.py" "database connection pooling"
+```
+
+### For finding specific patterns:
+```bash
+# Hybrid search: regex filter + semantic ranking
+colgrep -e "class.*View" "API endpoint handling"
+
+# Skip config files, focus on code
+colgrep --code-only "error handling middleware"
+
+# Just get filenames for further processing
+colgrep -l "unit test helpers"
+```
+
+### For scripting/automation:
+```bash
+# JSON output for piping to other tools
+colgrep --json "configuration parser" | jq '.[] | {file: .unit.file, score: .score}'
+```
+
+## Pro Tips
+
+1. **Always use `-c` for initial exploration** - Shows full function content, no need to read files separately
+2. **Use `-e` to narrow results** - Regex pre-filter is much faster than semantic ranking everything
+3. **Index auto-updates** - Each search detects file changes; no need to re-run `init` manually
+4. **Large codebases** - Use `-y` to skip confirmation prompts for indexing >10K files
+
+## Example workflow
+
+1. **First time setup** for a project:
+   ```bash
+   cd /path/to/project
+   colgrep init
+   ```
+
+2. **Search with content display** (recommended):
+   ```bash
+   colgrep -c -k 5 "authentication middleware"
+   ```
+
+3. **Refine with regex**:
+   ```bash
+   colgrep -c -e "def.*auth" "login validation"
+   ```
+
+4. **The index auto-updates** - each search detects file changes and updates automatically

.factory/skills/rules/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: rules
+description: Access and apply project coding rules and conventions from .factory/rules/ directory. Use when needing to follow coding standards, conventions, or guidelines for the project.
+user-invokable: false
+disable-model-invocation: false
+---
+
+# Rules Skill
+
+This skill provides access to project-specific coding rules and conventions stored in `.factory/rules/`.
+
+## Available Rule Files
+
+- **code.md** - General coding conventions and best practices
+- **github.md** - GitHub-specific workflows and conventions
+- **markdown.md** - Markdown formatting rules
+- **project.md** - Project-specific conventions
+- **python.md** - Python-specific coding standards
+- **subagents.md** - Guidelines for using subagents
+
+## When to use this skill
+
+- When starting work on a new task to understand project conventions
+- When unsure about coding standards for a specific language or context
+- When setting up new code that should follow existing patterns
+
+## Usage
+
+The rules are automatically loaded and applied by the system. Individual rule files can be read from `~/.factory/rules/` or `.factory/rules/` in the project directory.
+
+### ColGREP Init
+
+When starting work on a project, run `colgrep init` to build the semantic search index. This enables the colgrep skill for semantic code search across the codebase. The index auto-updates on subsequent searches, so `init` only needs to run once per project.
+
+## Research
+
+- Back all claims with reference code.
+- State only what is proven.
+- If evidence is lacking, say: "I can't find any evidence to support this claim" or "Not enough info".