Freelance Dev Suite

CLI toolkit for managing freelance development jobs — from intake and estimation through implementation to client handoff.

Problem

Freelance developers waste time on:

• Analyzing unfamiliar projects before quoting
• Underestimating AI costs and work hours
• Scope creep after price agreement
• Missing quality checks before delivery
• Assembling handoff packages manually

Freelance Dev Suite automates the entire job lifecycle with one CLI.

Install

Install the latest stable release from PyPI:

pip install freelance-dev-suite

For development, clone the repository and install the development dependencies:

git clone https://github.com/MatthiasLew/freelance-dev-suite.git
cd freelance-dev-suite
pip install -e ".[dev]"

Quick Start

# Create a new job
freelance job new

# List active jobs
freelance jobs

# Check job status
freelance status JOB-001
# Start and finish real repository work
freelance work start JOB-001 --task "Implement invoice export" --agent codex --model gpt-5.6-sol
freelance work status JOB-001
freelance work finish WORK-0001

Commands

Command	Description	Status
freelance job new	Create a new job	✅ implemented
freelance jobs	List all active jobs	✅ implemented
freelance status <JOB-ID>	Show job details	✅ implemented
freelance analyze <JOB-ID>	Run scan, validation, context, and AI-cost analysis	✅ implemented
freelance estimate <JOB-ID>	Generate and persist a full quote	✅ implemented
freelance requirements <JOB-ID>	Create, track, and confirm requirements checklist	✅ implemented
freelance templates	List available project starter templates	✅ implemented
freelance bootstrap <TEMPLATE>	Bootstrap standalone project from template	✅ implemented
freelance start <JOB-ID>	Bootstrap project and start job implementation	✅ implemented
freelance handoff <JOB-ID>	Run final QA Quality Gate & create handoff deliverables	✅ implemented
freelance finish <JOB-ID>	Close and archive delivered job	✅ implemented
freelance bug add <JOB-ID>	Add, parse, and structure client bug report	✅ implemented
freelance bug list <JOB-ID>	List tracked bug reports and status	✅ implemented
freelance bug show <JOB-ID> <BUG-ID>	View bug summary or client questions	✅ implemented
freelance bug status <JOB-ID> <BUG-ID>	Update bug lifecycle state	✅ implemented
freelance bug repro <JOB-ID> <BUG-ID>	View standalone reproduction script	✅ implemented
freelance bug test <JOB-ID> <BUG-ID>	Link regression test file	✅ implemented
freelance scope check <JOB-ID> [REQ]	Detect scope changes, estimate extra hours/AI cost & surcharge	✅ implemented
freelance scope list <JOB-ID>	List all analyzed scope changes	✅ implemented
freelance scope show <JOB-ID> <CHANGE-ID>	View scope change impact analysis or client proposal message	✅ implemented
freelance scope snapshot <JOB-ID>	Create a frozen baseline snapshot of requirements spec	✅ implemented
freelance timer start <JOB-ID>	Start recording development session	✅ implemented
freelance timer stop [JOB-ID]	Stop active timer session and log duration	✅ implemented
freelance timer status [JOB-ID]	Check active timer session status	✅ implemented
freelance timer log <JOB-ID>	Show recorded time log and sessions	✅ implemented
freelance stats <JOB-ID>	Calculate profitability, effective hourly rate, and margins	✅ implemented
freelance portfolio <JOB-ID>	Generate professional client case study (with optional --anonymize)	✅ implemented
freelance calibrate	Calculate historical estimation accuracy & multiplier recommendations	✅ implemented
freelance message <JOB-ID> <STAGE>	Generate tailored client messages for all project stages (PL/EN)	✅ implemented
freelance pricing	Inspect or dynamically update AI model pricing table	✅ implemented
freelance doctor	Diagnose environment, git, ai-dev engine, and state schema health	✅ implemented
freelance config [show|validate]	Inspect and validate suite configuration	✅ implemented
freelance history <JOB-ID>	View append-only business event audit timeline	✅ implemented
freelance export <JOB-ID>	Export job to verified archive with SHA-256 integrity	✅ implemented
freelance import <ARCHIVE>	Safely import job archive with path-traversal protection	✅ implemented
freelance mcp serve	Local STDIO Model Context Protocol (MCP) server for Cursor & Claude	✅ implemented
freelance work start <JOB-ID> --task <TASK>	Check scope, prepare incremental ai-dev context, and start time tracking	✅ implemented
freelance work status <JOB-ID>	Show the current task, elapsed time, AI usage, model, and validation	✅ implemented
freelance work finish <WORK-ID>	Run changed-file validation, stop time tracking, and record actual AI usage	✅ implemented
freelance work resume <WORK-ID>	Resume a NEEDS_FIX session with acknowledged incremental context	✅ implemented
freelance work list <JOB-ID>	List the complete development-session history for a job	✅ implemented

Integration with ai-dev-cli-tools

This project uses ai-dev-cli-tools as the technical engine for:

• Project scanning and stack detection
• Test execution and linting
• Diagnostics and context building
• Bootstrap and final checks

Install with AI dev tools integration:

pip install "freelance-dev-suite[ai-dev]"

freelance analyze fails with a clear error when the engine is unavailable. During local cross-repository development, point it at a source checkout executable:

$env:AI_DEV_EXECUTABLE = "C:\path\to\ai-dev-cli-tools\.venv\Scripts\ai-dev.exe"

Analysis runs scan, map, check, and context build. Use --check-mode fast when a preview without the complete validation suite is sufficient. Both MVP commands support structured output:

freelance analyze JOB-001 --json
freelance estimate JOB-001 --json

Repository-backed work sessions

freelance work is the bridge between the business record and actual repository work. A session is stored under <job>/work/sessions/WORK-NNNN.json and records its task, scope classification, related requirements, timer segments, agent/model, provider-reported token usage, cost, and validation result.

freelance work start JOB-001 \
  --task "Add CSV invoice export" \
  --agent codex \
  --model gpt-5.6-sol \
  --requirement REQ-7

freelance work status JOB-001
freelance work finish WORK-0001

# When validation produces NEEDS_FIX:
freelance work resume WORK-0001
freelance work finish WORK-0001

freelance work list JOB-001 --json

At start, the command uses ai-dev task with an adaptive incremental context and saves its state fingerprint. Resume sends that fingerprint back as acknowledged state, avoiding a blind full-project reload while still accounting for repository changes. Finish uses ai-dev check --mode changed; the engine may conservatively expand validation when its dependency mapping is uncertain.

Token and cost fields contain only provider-reported telemetry recorded by ai-dev-cli-tools during the session. If telemetry contains tokens but no priced cost, the configured model pricing snapshot is used. Missing telemetry remains zero instead of being presented as measured usage.

Pricing configuration

Provider prices and the USD/PLN rate are assumptions, not live market data. The package contains a reviewable default pricing snapshot. A user configuration may select another model, pricing file, and exchange rate:

models:
  default: claude-sonnet-4
  pricing_file: C:/freelance/model-pricing.yaml

exchange_rates:
  usd_to_pln: 4.0

The external pricing file uses a top-level models mapping with separate input, output, cached input, and optional reasoning prices per million tokens.

Architecture

ZLECENIE → intake → estimate → requirements → bootstrap → work → handoff → DONE

Freelance Dev Suite is the business/workflow layer on top of ai-dev-cli-tools (technical engine).

The boundary is intentional:

Responsibility	Owner
Client, scope, pricing, time, profitability, handoff, and job records	freelance-dev-suite
Repository discovery, context selection, validation, technical telemetry, and environment bootstrap	ai-dev-cli-tools
Connecting a business work session to repository validation	freelance work adapter

This repository does not implement a second repository scanner, context builder, test selector, or telemetry collector. It calls the public ai-dev CLI contract and stores only the resulting business evidence.

Documentation

Comprehensive engineering documentation is available in the docs/ directory:

• System Architecture: Layer boundary, component design, concurrency model, and atomic storage.
• State Format & Schema Compatibility: Detailed JSON schemas, versioning policy, and persistent structures.
• ai-dev Technical Engine Integration: Public CLI integration points, subprocess contract, and fallbacks.
• CLI Contract & Exit Codes: Standard exit codes (0, 1, 2, 3), structured envelopes, --dry-run, and --explain.
• Security & Secret Redaction: Multi-provider secret masking, path traversal guards, and archive protection.
• Disaster Recovery & Diagnostics: freelance doctor, stale lock resolution, and archive backup/import.
• Model Context Protocol (MCP) Server: Configuration guide for Cursor, Claude Desktop, and VS Code.

Local MCP Server (Cursor & Claude)

Run the local Model Context Protocol (MCP) server over standard input/output:

freelance mcp serve

Configure Cursor (~/.cursor/mcp.json) or Claude Desktop:

{
  "mcpServers": {
    "freelance": {
      "command": "freelance",
      "args": ["mcp", "serve"]
    }
  }
}

The server provides 9 specialized tools: list_jobs, get_job_status, get_requirements, get_scope_changes, get_work_sessions, get_profitability, get_timeline, create_job, and check_scope. All tool responses automatically redact sensitive API keys and secrets.

Safe Mutation UX & Diagnostics

All state-mutating commands support:

• --dry-run: Preview operations and calculate changes without writing to disk.
• --explain: Explain all steps, affected files, git branches, and locks involved.
• --json: Output a structured envelope conforming to schema v1.0.

Verify the overall health of the environment, git, ai-dev engine, and all stored job schemas:

freelance doctor

Performance & Benchmarks

Freelance Dev Suite is optimized in pure Python without external native extensions (no Rust, Go, or C toolchain dependencies required). All optimizations are backed by a reproducible 80-scenario benchmark suite comparing identical workloads against the baseline:

Scenario	Workload	Baseline Median	Optimized Median	Speedup
Job Lookup	1,000-job workspace	2.24 ms	0.23 ms	9.61x
Scope Changes Listing	100 changes	2.14 ms	0.21 ms	10.19x
Archive Import (1MB)	Safe extract + SHA-256	250.2 ms	28.3 ms	8.85x
Archive Import (30MB)	Safe extract + SHA-256	4,888 ms	1,404 ms	3.48x
Work Sessions Listing	150 sessions	93.3 ms	19.3 ms	4.84x
Bug Report Processing	100 bug reports	35.7 ms	10.2 ms	3.49x
MCP Server Job Status	Stdio JSON-RPC tool	3.93 ms	1.07 ms	3.68x
Cold Start (--version)	Fresh Python process	486.5 ms	270.2 ms	1.80x
Cold Start (--help)	Fresh Python process	463.6 ms	265.4 ms	1.75x

Key Architectural Optimizations

• $O(1)$ Fast Path for Timeline: TimelineManager.record_event() performs a backward seek within an 8KB tail buffer to determine the next sequential ID, eliminating full-file JSON parsing. An $O(N)$ safety fallback automatically scans the file and recovers the sequence (max_seen) if records are malformed or truncated.
• Lazy Import of Concurrency Tooling: Deferred filelock import to dynamic execution inside storage_lock(), reducing Python startup module overhead by over 100 modules and cutting cold-start latency by ~44%.
• Streaming Directory Traversal: Replaced recursive Path.iterdir() and Path.glob() calls with low-overhead os.scandir() and high-watermark job ID caching, eliminating repeated filesystem scans.
• Buffered Single-Pass Archive I/O: Streamed archive import in 128KB chunks while computing SHA-256 digests in-flight, halving disk I/O and memory usage.

Native Acceleration (Rust) Analysis

During profiling with cProfile, disk-modifying operations were found to be physically dominated by kernel fsync (on Linux) and FlushFileBuffers (on Windows), which account for 35–50% of execution time. Because native code cannot bypass kernel disk synchronization latency, rewriting storage in Rust or C would not provide meaningful speedups while introducing compilation requirements and cross-platform binary dependencies. Native acceleration will only be revisited if future profiling identifies meaningful CPU-bound hotspots.

Complete methodology and reproducible measurements are documented in benchmarks/COMPARISON.md and benchmarks/PROFILE.md.

Quality & Engineering Standards

• Comprehensive Test Suite: 241 passed tests (1 skipped) validating business logic, concurrency, file locks, MCP protocol, and CLI contracts.
• Strict Branch Coverage: 83.11% branch coverage with continuous enforcement in CI (fail_under = 82%).
• Strict Type Checking: 100% strict type safety enforced across all source modules and tests using mypy --strict.
• Code Hygiene: Formatted and linted with ruff using strict rule sets.
• Security & Secret Redaction: Multi-provider runtime secret masking (mask_text), path traversal guards (assert_safe_path), and automated GitHub Actions CodeQL analysis and Gitleaks history scanning.
• Cross-Platform Matrix: Fully verified and continuously tested on Linux and Windows runners across Python 3.11, 3.12, and 3.13.

Releases

CI tests Linux and Windows on Python 3.11-3.13, installs the built wheel in an isolated environment, runs a full job lifecycle against ai-dev-cli-tools, and scans Git history with Gitleaks. A tag named vMAJOR.MINOR.PATCH starts .github/workflows/release.yml, verifies that the tag matches pyproject.toml, builds and tests the distributions, publishes to PyPI with Trusted Publishing, and creates a GitHub release.

PyPI publishing uses the Trusted Publisher configured for this repository, workflow release.yml, and environment pypi. Publishing is intentionally not attempted from developer machines or with a long-lived API token.

License

MIT