Organon

def: An instrument for acquiring knowledge or achieving a goal; a body of principles for scientific investigation.

Organon is a disciplined and structured approach to collaborative human and AI software development. The primary goal is to find optimal workflows for highly efficient, predictable and enjoyable collaboration - to harness the power of Agents within a highly structured environment under the guidance of an experienced software engineer. The engineer controls the architecture and design and the Agents execute tasks such as writing code and documentation, researching and summarizing, and fixing defects.

Quick Start

When first working in this workspace:

# Install organon package from repository root
uv sync

# Verify installation
uv run organon --help

# Initialize organon in your project (includes MCP setup)
organon init

# Skip MCP setup if needed
organon init --no-mcp

CLI Tool

Organon provides a unified CLI tool for project lifecycle management:

# Admin commands
organon admin scan [path]              # Build codebase index
organon admin validate [path]          # Validate project structure (uses dynamic rules)
organon admin validate [path] --config FILE  # Use specific config file
organon admin validate-templates [path] # Validate document content
organon admin update-defaults          # Update .organon/defaults from package

# Spec alignment
organon admin align-scan [path]        # Run alignment scan (specs vs code vs tests)
organon admin align-scan . --format json  # JSON output
organon admin status [path]            # Project health summary

# Dynamic rule validation
organon admin rules list               # List available rules
organon admin rules list -v            # Show rule details
organon admin rules validate           # Validate rule definitions

# Structure generation
organon admin structure generate <path> # Generate STRUCTURE.md
organon admin structure update <path>   # Update existing STRUCTURE.md

# Project management
organon projects list                  # List project templates

# Sprint management
organon sprints create <name>          # Create new sprint
organon sprints list [--status]        # List sprints
organon sprints update-status <path> <status>

# Logging and metrics
organon logs stream                    # Stream Claude Code conversation logs
organon logs metrics [--by-operation]  # View token savings
organon logs metrics clear             # Clear metrics log
organon logs insights timeline --session ID # Unified session timeline
organon logs insights analyze LOG      # Analyze with efficiency

UI Testing Framework

Organon provides a comprehensive Playwright-based UI testing framework for AI agents:

# Install Playwright browsers
playwright install chromium

# Run UI tests
pytest tests/ -v

# Run with visual regression
pytest tests/ --update-snapshots

# Run with log forwarding
pytest tests/ --ctrf --loki-url=http://localhost:3100

Core Capabilities:

• Element Interaction - Playwright wrappers for clicks, typing, navigation
• Log Capture - Browser console logs, page errors, network events
• Visual Regression - Screenshot comparison with baseline management
• Page State Capture - Accessibility tree, DOM snapshots for agent analysis
• Workflow Orchestration - Multi-page state persistence
• Backend Integration - Testcontainers and LiveServer fixtures

Key Features:

• Automatic log correlation with correlation IDs
• Cross-browser testing (Chromium, Firefox, WebKit)
• Parallel test execution with pytest-xdist
• CTRF (Common Test Report Format) export
• Optional Grafana Loki integration

See UI Testing User Guide for complete documentation.

MCP Server

For AI agent integration with intelligent query tools:

# Start MCP server
uv run organon-mcp

# Or configure in ~/.config/claude/claude_desktop_config.json:
{
  "mcpServers": {
    "organon": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/organon", "organon-mcp"]
    }
  }
}

Available MCP Tools:

• Sprint management: create_sprint, list_sprints, update_sprint_status
• Template queries: query_workflows, query_tasks (96-99% token savings)
• Sprint queries: get_all_sprints_summary, get_current_sprint_context (60-96% savings)
• Log analysis: analyze_workflow_logs, analyze_conversations

Efficiency Tracking:

• All MCP query tools automatically log efficiency metrics to .organon/efficiency.jsonl
• Read tool usage is tracked via post-tool-use hook with MCP tool suggestions
• See Efficiency Tracking Reference for details

Documentation

For complete documentation, see:

• User Guide - Installation, CLI usage, workflows, examples
• Developer Guide - Contributing, architecture, adding features
• Design - Core principles and architecture decisions
• Reference - CLI, MCP, templates, schemas, and rules

Workflow Logging

Organon includes an automatic workflow logging system that tracks all agent interactions:

How it works:

1. Agent updates context when workflow/task changes via update_workflow_context MCP tool
2. Context is stored in .organon/current-context.json
3. Claude Code hooks automatically read context and append to .organon/workflow-log.jsonl
4. Every user message and assistant response is logged with full context

Log format:

{
  "timestamp": "2025-10-15T15:55:10Z",
  "session_id": "93c50738-f992-4876-8698-a5cef7dc16b3",
  "event": "user_message",
  "workflow": "one-off-task",
  "sprint_id": "Fix Session ID Logging",
  "task_type": "fix",
  "task_description": "Extract session_id from hook events"
}

Setup: The hooks (.claude/hooks/user-prompt-submit and .claude/hooks/assistant-stop) are already configured in this project. They automatically:

• Extract session_id from Claude Code hook events
• Read workflow context from state file
• Append structured log entries to .organon/workflow-log.jsonl

Stream logs:

organon logs stream  # Stream Claude Code conversation logs with formatting

Additional Tools

• LLM Context Capture (scripts/llm_capture/) - Capture and analyze Claude Code API requests

  • Intercept requests via mitmproxy to see complete LLM context
  • Extract tool definitions, system prompts, conversation history
  • Analyze token usage patterns and find optimization opportunities
  • Inspect large messages to identify inefficiencies
  • See scripts/llm_capture/README.md for full guide

• workflow-insights (tools/workflow-insights) - Claude Code log analysis (future integration)

Core idea

Organan is a disciplined and structured approach to collaborative human and AI software development. The primary goal is to find optimal workflows for highly efficient, predictable and enjoyable collaboration - to harness the power of Agents under the guidance of an experienced software engineer. Finding optimal workflows is a process that requires the developer to learn new patterns of working and collaborating with agents to achieve familiar goals but learning new methods and engaging in different modalities that work to the strength of the developer and to the agents.

The engineer controls the architecture and design and the Agents execute tasks such as writing code and documentation, researching and summarizing, and fixing defects. As of October of 2025, this seems to me the only way to get orders of magnitude gains in productivity in a consistent and predictable manner. The expectation is that this will be changing, possibly rather rapidly, as models and agents continue to improve. The intention is for this to be an evolving set of principles and tools, eventually evolving under the guidance of agents.

Fundamental features for working with agents

1. Predictability a. Navigation - Progressive disclosure b. Workflows c. Validation tools
2. Quality control a. Active human feedback and review
   1. UI b. Validation tools
3. Observability a. UI testing tools for agents