Skip to content

QWEN.md

Latest commit

 

History

History
233 lines (170 loc) · 12.1 KB

QWEN.md

File metadata and controls

233 lines (170 loc) · 12.1 KB
Raw

Gobby — Project Context

This file provides guidance for developing the Gobby codebase.

Guiding Principles

These are enforced by hooks, rules and workflows.

  1. ALWAYS use progressive tool discovery. Do not try to call one step through another (e.g., don't use call_tool to invoke get_tool_schema).
  2. NEVER create or leave monoliths. Keep non-test Python, TypeScript, and CSS source files under 1,000 lines. For non-test .py, .ts, .tsx, and .css files only, you MUST search for an existing refactor task or create it if one does not already exist in gobby-tasks. Leave these tasks for another agent to pick up. Markdown files, including docs/guides/*.md and repo-root instruction files, are documentation artifacts and are not subject to this 1,000-line source-file rule; do not create refactor tasks or block docs work based only on Markdown line count.
  3. ALWAYS create or claim a task before editing a file. This applies to file edits only — no task needed for plan mode, research, investigation, or answering questions unless the user explicitly requests one.
  4. Validation runs when closing with a commit. If a commit is done, validation must run. skip_validation is silently stripped when commits are attached.
  5. NEVER close a task without a commit if there are diffs. If you changed something, you have to commit it.
  6. NEVER stop while you have a claimed task in progress. Your stop hook is blocked while you have a claimed task. Task must be closed before stopping. If you claim a task, you finish a task.
  7. Escalate only when the user explicitly needs to review your work, your agent skill/workflow/pipeline directs escalation, or you are genuinely stuck and need guidance. Do not use escalation as a workaround for committing, closing, or completing required validation.
  8. You found it, you own it. Every error, test failure, lint warning, or type error you encounter is yours to fix — even if it's pre-existing, even if it's unrelated to your task. Fix it before closing your task. The only exception is something that genuinely requires multi-session architectural planning; even then, investigate thoroughly and attempt the fix before filing a task to defer it.
  9. ALWAYS use gobby-memory to record valuable memories. You have access to a sophisticated memory system via gobby-memory through the MCP proxy. Use it to store and retrieve facts about the codebase, design decisions, and other relevant information.
  10. NEVER be a sycophant. Do not agree with the user just for the sake of agreement. If you disagree with the user, you MUST voice your concerns and provide alternative solutions.
  11. NEVER leave options or unanswered questions in plans. Plans are for execution, not exploration. If there are unanswered questions or ideas that need to be explored, explore them before finalizing the plan.
  12. ALWAYS choose/present the best approach to solve a problem. The best, most correct fix is ALWAYS in scope. NEVER choose or present the simplest approach if it is not the best or most complete/correct approach.
  13. ALWAYS remember: Rule templates are not rules. Templates must be installed in the rules engine to function. Templates are enabled by default and sync to the DB on first startup. The DB is the source of truth — before telling the user a rule is disabled, check the installed version in the DB.
  14. Agent depth limit of 5. No recursive agent chains deeper than 5 levels.

Progressive Tool Discovery Enforced by Hooks

Gobby uses an MCP proxy with progressive discovery. This means that you can't just call any tool you want. Each step (list_mcp_servers, list_tools, get_tool_schema, call_tool) is a separate top-level tool (e.g., mcp__gobby__list_mcp_servers). Load each via ToolSearch before first use. Do NOT try to call one step through another (e.g., don't use call_tool to invoke get_tool_schema).

DO NOT RUN THE FULL PYTEST SUITE

The repo has over 15,000 tests. Running the full suite takes over 30 minutes. Do not run the full suite unless explicitly asked to do so.

When running pytest as an agent, always prefix pytest commands with GOBBY_TEST_PROTECT=1.

Pytest must be isolated from the user’s running Gobby daemon and real local daemon state. Tests that need daemon behavior must start/use an isolated test daemon with temporary state and ports; they must not talk to the existing user daemon.

Plan Mode

Task management MCP calls (gobby-tasks) are allowed during plan mode. Planning includes organizing work, not just designing it.

Project Overview

A local-first daemon to unify your AI coding tools. Session tracking and handoffs across Claude Code, Codex, Droid, Gemini, and QwenCode. An MCP proxy that discovers tools without flooding context. Task management with dependencies, validation, and TDD expansion. Agent spawning and worktree orchestration. Persistent memory, extensible workflows, and hooks.

  • Session management that survives restarts and context compactions
  • Task system with dependency graphs, TDD expansion, and validation gates
  • MCP proxy with progressive discovery (tools stay lightweight until needed)
  • Rule engine with declarative enforcement (block, set_variable, inject_context, mcp_call)
  • On-demand workflows for structured multi-step processes (plan-execute, TDD, etc.)
  • Pipeline system for deterministic automation with approval gates
  • Agent spawning with P2P messaging, command coordination, and worktree isolation
  • Memory system for persistent facts across sessions

Key characteristics:

  • Python 3.13+ package, distributed via PyPI
  • Local daemon with HTTP, WebSocket, and MCP endpoints — no cloud dependency
  • PostgreSQL-backed hub storage with a sophisticated rule engine, workflow/pipeline system, and memory system (keyword + vector search via Qdrant)
  • Built with extensive type hints, async/await throughout, and full test coverage (80%+ enforced)
  • "Built with Gobby" — most of the codebase was written by AI agents using Gobby's own task system

Core subsystems:

Module Purpose
cli/ Click-based CLI commands (~25 subcommands)
servers/ FastAPI HTTP server + WebSocket endpoints
mcp_proxy/ MCP proxy with progressive tool discovery
hooks/ + adapters/ Event-driven hook system with CLI-specific adapters
agents/ Agent spawning with tmux, worktree/clone isolation
sessions/ Session lifecycle, transcript parsing, context compaction
tasks/ Task system with dependency graphs, TDD expansion, validation
workflows/ Rule engine, workflow engine, pipeline executor (~47 modules)
memory/ Persistent memory with semantic + keyword search
storage/ Hub storage layer with migrations and backend adapters (~20 modules)
skills/ Skill management (SKILL.md format, filesystem/GitHub/ZIP sources)
config/ YAML-based daemon configuration (~15 modules)
llm/ Multi-provider LLM abstraction (Claude, Gemini, OpenAI-compatible)
conductor/ Orchestration daemon with token budget tracking
scheduler/ Cron job scheduler
code_index/ AST-aware code indexing (gcode integration)

Building and Running

All development uses uv. Python 3.13+ is required.

Setup

uv sync                          # Install runtime + dev dependencies

Daemon Management

uv run gobby start --verbose     # Start daemon with verbose logging
uv run gobby stop                # Stop daemon
uv run gobby restart             # Restart daemon
uv run gobby status              # Check daemon health

Project Initialization

uv run gobby init                # Initialize .gobby state for this repo
uv run gobby install             # Detect and install hooks for supported CLIs

Code Quality

uv run ruff check src/           # Lint (line length: 100, target: py313)
uv run ruff format src/          # Auto-format
uv run mypy src/                 # Strict type checking

Testing

# Run a specific test file (preferred during development)
uv run pytest tests/tasks/test_validation.py -v

# Run a specific module
uv run pytest tests/storage/ -v

# Run with coverage
uv run pytest tests/workflows/ --cov=gobby --cov-report=term-missing

# Exclude slow tests
uv run pytest -m "not slow"

# Run integration tests only
uv run pytest -m integration

Important: The repo has over 15,000 tests (30+ min full run). Do NOT run the full suite unless explicitly asked. Target specific files or modules.

Coverage threshold: 80% minimum (enforced in CI and pre-push).

Test markers: unit, slow, integration, e2e, cli, no_config_protection.

Pipeline Management

uv run gobby pipelines list            # List available pipelines
uv run gobby pipelines run <name>      # Run a pipeline
uv run gobby pipelines status <id>     # Check execution status
uv run gobby pipelines approve <token> # Approve waiting pipeline
uv run gobby pipelines reject <token>  # Reject waiting pipeline

Development Conventions

Coding Style

  • Python 3.13+ with full type hints on all functions
  • 4-space indentation, lines within Ruff's 100-character limit
  • snake_case for modules/functions, PascalCase for classes, test_*.py for test files
  • async/await for I/O-heavy paths
  • Keep files under 1,000 lines — create refactor tasks if needed
  • Prefer small, focused modules within existing package boundaries

Error Handling

Use specific exceptions, never bare except. Use structured logging with context.

Database Access

Always use connection context managers:

with self.db.transaction() as conn:
    conn.execute("INSERT INTO tasks VALUES (?, ?)", (task_id, title))

Commit Messages

Follow the task-linked pattern: [gobby-#NNNNN] <type>: <summary> Types: fix, feat, refactor, chore.

Agent Workflow (Critical)

Before editing files, create or claim a Gobby task and work under that task. Use the gobby-tasks MCP server for task lifecycle operations — never use the gobby tasks CLI or direct storage/SQL/REST mutations for agent task writes. The MCP path is the only path that correctly updates workflow/session state.

When working task state:

  • Use lifecycle MCP tools: create_task (with claim=true), claim_task, close_task, reopen_task, escalate_task; use gobby-tasks-ops review tools such as submit_for_review(stage_name="...")
  • Do NOT set generic status/assignee fields through update_task, CLI, or DB writes
  • If gobby-tasks MCP is unavailable, stop and surface that as the blocker

Templates vs Active Enforcement

Files in src/gobby/install/shared/ (rules/, workflows/, agents/, pipelines/) are templates. They are synced to the workflow_definitions DB table on first startup. The DB is the source of truth for what's active, not the YAML template files.

Key File Locations

Path Purpose
~/.gobby/bootstrap.yaml Pre-DB bootstrap settings (ports, database URL, bind_host)
bootstrap.yaml database_url Runtime hub database connection
~/.gobby/logs/ Log files
.gobby/project.json Project metadata
.gobby/tasks.jsonl Task sync file (git-native)
src/gobby/runner.py Main daemon entry point (GobbyRunner)
src/gobby/cli/__init__.py CLI entry point (Click)

Configuration

Configuration lives in src/gobby/config/ with ~15 modules covering:

  • app.py — DaemonConfig (YAML config model)
  • bootstrap.py — Pre-DB bootstrap settings
  • features.py — Feature flags
  • llm_providers.py — LLM provider configuration
  • mcp.py — MCP server configuration
  • tasks.py, sessions.py, skills.py — Subsystem-specific config

Troubleshooting

Issue Solution
Import errors Run uv sync
Daemon won't start Check logs in ~/.gobby/logs/
MCP connection issues Verify daemon is running: gobby status
Type errors Run uv run mypy src/
Lint errors Run uv run ruff check src/ --fix

Status

Version: 0.4.0 (pre-1.0, evolving rapidly) License: Apache 2.0 Roadmap: Local AI integration testing, UI polish, onboarding improvements, bundled agent/workflow finalization (see ROADMAP.md)