Add hint for using bash commands to justify markdown tables

- 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

@@ -0,0 +1,54 @@
+---
+name: coder
+description: Specialized for large code generation using GPT 5.3 Codex. Generates production-ready code based on detailed specifications.
+model: custom:Gpt-5.3-Codex-(BYOK)-3
+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 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. 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:
+- <file>: <brief description of changes>
+
+Implementation Notes:
+- <any important decisions or trade-offs>
+- <known limitations if any>
+```
+
+Focus on correctness and completeness. The review droid will catch issues later.

.factory/droids/reviewer.md

@@ -0,0 +1,57 @@
+---
+name: reviewer
+description: Critical code reviewer using Opus 4.6. Finds bugs, security issues, and logic errors. Never generates code - only critiques.
+model: custom:Opus-4.6-(BYOK)-2
+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 subagent who is supposed to help the primary agent.
+
+## Your Rules
+
+1. **NEVER write or modify code** - You are strictly read-only and critical
+2. **NEVER create files** - Only analyze and report
+3. **Assume context is complete** - The parent agent should provide all relevant files; do not explore unnecessarily
+4. **Be thorough but constructive** - Find real issues, not nitpicks
+
+## 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                          |
+| **Maintainability** | Code duplication, tight coupling, missing error handling                           |
+| **Testing**         | Untested edge cases, missing assertions, brittle tests                             |
+
+## Process
+
+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
+
+```
+Summary: <one-line verdict: "No blockers", "Minor issues found", or "Critical issues require fix">
+
+Findings:
+
+- [SEVERITY] <file>:<line> - <issue description>
+  Impact: <what could go wrong>
+  Suggestion: <how to fix>
+
+Severity Levels:
+- 🔴 CRITICAL: Must fix before merge (security, data loss, crashes)
+- 🟡 WARNING: Should fix (bugs, performance issues)
+- 🟢 NIT: Nice to have (style, minor improvements)
+
+Follow-up Tasks:
+- <specific action items for the coder droid or human>
+```
+
+Be skeptical. Your value is in catching what others miss.

.factory/rules/code.md

@@ -0,0 +1,6 @@
+# Code Rules
+
+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. 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/github.md

@@ -0,0 +1,4 @@
+# GitHub Rules
+
+We have `gh` cli. Use that as much as possible. But read only.
+Ask user to run specific commands if they are not read only.

.factory/rules/markdown.md

@@ -0,0 +1,15 @@
+# Markdown Rules
+
+## Tables
+
+The tables in markdown should always by ascii char count justified for better readability.
+
+Example:
+
+| Name       | Age | City          |
+|------------|-----|---------------|
+| Abhishek   | 30  | New York      |
+
+## Hint
+
+Use bash commands to count the chars in each column and add spaces accordingly to justify the table.

.factory/rules/project.md

@@ -0,0 +1,17 @@
+# Project Rules
+
+Do not put obvious comments in the code. Every comment should add value to the codebase.
+Docstrings are different than comments.
+Do not put emojis in the code. Use ASCII characters as much as possible.
+
+## Explore
+
+Always start with `tree --gitignore`. Do not get stuck in loop of running `ls` or `grep`.
+
+Try to understand the code structure first.
+Try to grab the coding style and patterns used in the codebase. It will help you to write code that is consistent with the existing codebase.
+
+## Motive
+
+The motive should to do things the right way and not the easy way. The right way is to follow the coding standards and best practices. 
+The easy way is to write code that is quick and not manageable. Avoid the easy way.

.factory/rules/python.md

@@ -0,0 +1,25 @@
+# Python Rules
+
+Always make sure to run linter and typecheck.
+Possibly with `uv` like `uv run ruff check --fix` and `uv run ty`.
+
+## Package management
+
+use `uv pip` instead of `pip` as I always create my virtual environments with `uv` if it doesn't already exist. Example: `uv venv -p 3.12`
+
+## Code style
+
+Do not try to use comments to work around the linter (ruff) or type checker (ty) issues.
+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
+
+- Ban relative imports.
+- Keep imports at the top of the file.
+
+## Type checking
+
+Try to write type safe code. Use type hints and type annotations as much as possible. It will help you to catch bugs early and it will also help you to understand the code better.

.factory/rules/subagents.md

@@ -0,0 +1,18 @@
+# Subagent Rules
+
+Always use prep time to understand where you can leverage your available subagents.
+
+## Coding with subagents
+
+- The specialized coder subagent shall handle code generation. And even code refactoring.
+- The coder agent is not good at editing Markdown, YAML, JSON, or other structured data files. So you should handle those.
+- Alsways start providing relavant files and as much context as possible to the subagents. Don't hesitate, the more rich context you provide, the better the output will be.
+- None of the subagents use `tree --gitignore` command instictively, so you should ask them to do it or ptovide relevant file tree yourself. This is especially important for the coder subagent, as it will help it to understand the project structure and dependencies.
+
+### Productivity Trick
+
+Do utilize it in multiple stages:
+
+- Ask to analyze the code with in context of the task
+- Ask to show you a proposed plan which you'll evaluate and can ask for alternative approach or give a goahead.
+- Give the goahead and ask to implement the code.

.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
+
+Read the rule files from `~/.factory/rules/` and apply them as needed.
+
+### 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".

DROIDS.md

@@ -1,138 +0,0 @@
-# Factory Droids
-
-A system for orchestrating AI droids to handle complex coding tasks through specialized roles.
-
-## Overview
-
-Factory Droids uses `droid exec` to run AI agents non-interactively, each specializing in different aspects of software development.
-
-## Available Commands
-
-```bash
-droid exec --help              # Show exec command options (includes model list)
-droid --help                   # Show all droid commands
-droid exec --list-tools        # List available tools for a model
-```
-
-> **Tip:** Run `droid exec --help` to see all available models including BYOK custom models.
-
-## Quick Start
-
-```bash
-# Read-only analysis (default)
-droid exec "analyze the codebase structure"
-
-# With file input
-droid exec -f prompt.txt
-
-# With specific model
-droid exec --model custom:kimi-k2.5 "explore the project"
-
-# Low autonomy - safe file operations
-droid exec --auto low "add JSDoc comments"
-
-# Medium autonomy - development tasks
-droid exec --auto medium "install deps and run tests"
-
-# High autonomy - production operations
-droid exec --auto high "fix, test, commit and push"
-```
-
-## Available Models (BYOK)
-
-| Model ID                          | Name                 | Reasoning |
-|-----------------------------------|----------------------|-----------|
-| `custom:kimi-k2.5`                | Kimi K2.5            | Yes       |
-| `custom:claude-opus-4.6`          | Claude Opus 4.6      | Yes       |
-| `custom:gpt-5.3-codex`            | GPT 5.3 Codex        | Yes       |
-| `custom:gpt-5.2`                  | GPT 5.2              | Yes       |
-
-## Droid Roles
-
-| Droid      | Model                         | Purpose                               | Auto Level |
-|------------|-------------------------------|---------------------------------------|------------|
-| Explorer   | `custom:kimi-k2.5`            | Code exploration and research         | high       |
-| Spec       | `custom:gpt-5.2`              | Planning and specification generation | high       |
-| Coder      | `custom:gpt-5.3-codex`        | Large code generation                 | high       |
-| Coder-lite | `custom:kimi-k2.5`            | Small code generation and fixes       | high       |
-| Quality    | `custom:kimi-k2.5`            | Formatting, linting, type checking    | high       |
-| Reviewer   | `custom:claude-opus-4-6`      | Code review and bug finding           | high       |
-| Runner     | `custom:kimi-k2.5`            | Build, test, and execution            | high       |
-
-## Workflow
-
-1. **Start** with a good instruction follower (`custom:kimi-k2.5` or `custom:gpt-5.3-codex`)
-2. **Make** a todo list
-3. **Explore** - Launch multiple explorer droids with `custom:kimi-k2.5` in parallel
-4. **Spec** - Evaluate context with spec droid using `custom:gpt-5.2`
-5. **Confirm** spec with user
-6. **Code** - Use `custom:gpt-5.3-codex` for large code gen, `custom:kimi-k2.5` for small
-7. **Quality** - Run quality check droid with `custom:kimi-k2.5 --auto high`
-8. **Review** - Run review droid with `custom:claude-opus-4-6 --auto high`
-9. **Run** - Run build/test droid with `custom:kimi-k2.5 --auto high`
-10. **Summarize** - Provide final summary
-
-## Autonomy Levels
-
-| Level   | Flag           | Description                                           |
-|---------|----------------|-------------------------------------------------------|
-| Default | (none)         | Read-only - safest for reviewing planned changes      |
-| Low     | `--auto low`   | Basic file operations, no system changes              |
-| Medium  | `--auto medium`| Development ops - install packages, build, git local  |
-| High    | `--auto high`  | Production ops - git push, deploy, migrations         |
-| Unsafe  | `--skip-permissions-unsafe` | Bypass all checks - DANGEROUS!         |
-
-## Command Options
-
-```
-Usage: droid exec [options] [prompt]
-
-Arguments:
-  prompt                      The prompt to execute
-
-Options:
-  -o, --output-format <format>    Output format (default: "text")
-  --input-format <format>         Input format: stream-json for multi-turn
-  -f, --file <path>               Read prompt from file
-  --auto <level>                  Autonomy level: low|medium|high
-  --skip-permissions-unsafe       Skip ALL permission checks (unsafe)
-  -s, --session-id <id>           Existing session to continue
-  -m, --model <id>                Model ID (default: claude-opus-4-5-20251101)
-  -r, --reasoning-effort <level>  Reasoning effort (model-specific)
-  --enabled-tools <ids>           Enable specific tools
-  --disabled-tools <ids>          Disable specific tools
-  --cwd <path>                    Working directory path
-  --log-group-id <id>             Log group ID for filtering logs
-  --list-tools                    List available tools and exit
-  -h, --help                      Display help
-```
-
-## Authentication
-
-Create API key: https://app.factory.ai/settings/api-keys
-
-```bash
-export FACTORY_API_KEY=fk-... && droid exec "fix the bug"
-```
-
-## Examples
-
-```bash
-# Analysis (read-only)
-droid exec "Review the codebase for security vulnerabilities"
-
-# Documentation
-droid exec --auto low "add JSDoc comments to all functions"
-droid exec --auto low "fix typos in README.md"
-
-# Development
-droid exec --auto medium "install deps, run tests, fix issues"
-droid exec --auto medium "update packages and resolve conflicts"
-
-# Production
-droid exec --auto high "fix bug, test, commit, and push to main"
-droid exec --auto high "deploy to staging after running tests"
-
-# Continue session
-droid exec -s <session-id> "continue previous task"
-```

VISION.md

@@ -1,4 +1,4 @@
-# VISION
+# VISION of the Project
 
 Need a skill for factory droid which can launch `droid exec` for multiple things.
 
@@ -86,13 +86,13 @@ Need a skill for factory droid which can launch `droid exec` for multiple things
 | Rank | Model            |
 |------|------------------|
 | 1    | `gpt_5.2`        |
-| 2    | `gpt_5.3_codex`  |
-| 3    | `opus_4.6`       |
+| 2    | `opus_4.6`       |
+| 3    | `gpt_5.3_codex`  |
 | 4    | `kimi_k2.5`      |
 
 ## Flow
 
--> Start with good instruction follower (kimi_k2.5 or gpt_5.3_codex).
+-> Start with `kimi_k2.5` as the driver and entrypoint.
 User asks a question or give a task.
 -> Make a todo list.
 -> exploration is always needed. launch multiple explorer droid with kimi_k2.5 asking question in natural language.
@@ -103,3 +103,9 @@ User asks a question or give a task.
 -> Run review droid with opus_4.6 to find bugs and issues.
 -> Run build/test/run droid with kimi_k2.5.
 -> Provide summary
+
+## Important Notes
+
+- Assume that all droid exec with any model will try to explore the code base. So we need to provide as many context as possible that there should not be need to explore again when it comes to opus 4.6 or gpt 5.2. 5.3-codex and kimi-k2.5 are good at exploring, so they can be let loose.
+
+- Do not create unnecessary new markdown files. Need to ask this in every droid exec. Only the driver (kimi-k2.5) should be doing it.

install.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# Install .factory to ~/.factory (merges, does not replace parent folders)
+
+mkdir -p ~/.factory
+rsync -av .factory/ ~/.factory/
+
+echo "Installed .factory to ~/.factory"

settings.json

@@ -19,16 +19,17 @@
       "baseUrl": "http://localhost:8383",
       "apiKey": "sk-abcd",
       "displayName": "Kimi for Coding (BYOK)",
+      "maxOutputTokens": 131072,
       "noImageSupport": false,
       "provider": "anthropic"
     },
     {
-      "model": "Opus-4.5",
-      "id": "custom:Opus-4.5-(BYOK)-2",
+      "model": "Opus-4.6",
+      "id": "custom:Opus-4.6-(BYOK)-2",
       "index": 2,
       "baseUrl": "http://localhost:8383",
       "apiKey": "sk-abcd",
-      "displayName": "Opus 4.5 (BYOK)",
+      "displayName": "Opus 4.6 (BYOK)",
       "maxOutputTokens": 128000,
       "extraArgs": {
         "parallel_tool_calls": true,