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

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