This repository contains the complete artifact trail from building MeshScope — a cross-platform desktop application for viewing, inspecting, measuring, and converting 3D mesh files — using the Solo Orchestrator Framework.

MeshScope is a real application. It was built by a single person using Claude Code as the AI execution layer, following the Solo Orchestrator's five-phase methodology. It is downloadable and fully functional on Windows, macOS, and Linux.

This repo does not contain MeshScope's source code. It contains the framework artifacts — the documents, decisions, plans, and evidence that the methodology produced at each phase. The purpose is to show you what the Solo Orchestrator process looks like in practice, so you know what to expect when you use it yourself.

Phase 3 and 4 examples will be replaced with real artifacts when MeshScope completes those phases.

The Solo Orchestrator process starts with the Project Intake — a structured document that captures every decision, constraint, and requirement before any code is written. MeshScope's intake was filled out using the framework's intake wizard, which asks questions interactively and offers context-aware suggestions based on the selected platform (desktop) and language (Python).

→ Read the filled-out Project Intake

Things to notice:

• Section 1 identifies the project as Light track, desktop platform, organizational deployment (Private POC mode)
• Section 2 defines the problem in concrete terms — not "make a 3D viewer" but the specific pain points with existing tools
• Section 4 lists 10 must-have features, each with a business logic trigger ("If [condition], the system must [action]") and a failure state (what happens when things go wrong)
• Section 6 includes the Competency Matrix — an honest self-assessment of where the builder can evaluate AI output and where automated tooling is mandatory
• Section 9 specifies colorblind-accessible UI as a hard constraint — this becomes an architectural requirement from day one, not a Phase 3 afterthought

Phase 0 takes the Intake and expands it into formal product documentation. The AI agent reads the Intake and produces three documents, which the Orchestrator reviews and approves.

→ Functional Requirements Document — Every feature specified with logic triggers and failure states. Look at Feature 1 (File Loading) to see the level of detail: specific file formats, parse behavior per format, 8 distinct failure states with exact error messages, performance requirements.

→ User Journey Map — How the user moves through the application. Entry points, success paths, failure recovery at each step.

→ Data Contract — What data the application handles, how it flows, what's persisted, what's ephemeral.

These three documents feed into the Product Manifesto — the governing constraint for the entire project.

→ Product Manifesto — The MVP cutline (10 features, hard boundary), will-not-have list (6 explicit exclusions), hard constraints (Python, PySide6, Nuitka, offline-only, colorblind-accessible), and success criteria with measurable targets.

Phase 0 → Phase 1 gate: The Orchestrator reviews all four documents and approves the transition. See the Approval Log for the gate entry.

Phase 1 takes the Product Manifesto and selects the technology stack. The AI agent proposes architecture options constrained by the Manifesto's requirements and budget. The Orchestrator selects, and the agent produces the Project Bible — the complete technical specification.

→ Project Bible — Architecture selection (trimesh + VTK + PySide6), rejected alternatives with reasons (custom OpenGL: lower quality ceiling; Open3D: doesn't embed in Qt), threat model, data model, UI scaffolding, coding standards, test strategy, and packaging plan.

→ Architecture Decision Records — Four formal ADRs capturing key decisions: why VTK over custom OpenGL, why Python 3.13 not 3.14, why Nuitka for packaging, why STL as the primary format. Each records the decision, alternatives considered, and the reasoning.

→ Gate Snapshot — Summary of key decisions at the Phase 1 → Phase 2 gate, including the risk assessment (primary threat: malicious input files) and the packaging validation requirement (Nuitka + VTK must be validated before any feature code).

Phase 1 → Phase 2 gate: The Orchestrator reviews the Project Bible and approves. See the Approval Log.

Phase 2 builds features one at a time using test-driven development. Each feature follows the Build Loop: write tests → Orchestrator reviews test assertions → AI implements → security audit → documentation update → next feature.

→ Features Reference — All 10 features with build dates, status, design spec references, test coverage notes, and known limitations.

→ Bug Tracker — Bugs found during construction and UAT. Each entry includes reproduction steps, root cause, and fix reference.

→ Changelog — Change log with 8 categories (Security, Data Model, Added, Changed, Fixed, Removed, Infrastructure, Documentation).

→ API Documentation — Interface documentation for the mesh operations layer and viewport, produced during construction and updated as features were built.

→ Source Code Summary — Metrics and structure of the actual source code (5,227 lines across 28 files). For the full source, see the MeshScope repository.

→ Test Summary — Metrics and structure of the test suite (6,043 lines, 1.16:1 test-to-source ratio). For the full tests, see the MeshScope repository.

→ UAT Sessions — Real user acceptance test session reports. Manual testing sessions where the Orchestrator tested features against the FRD specifications.

What you don't see here (but exists in the live project): The MeshScope repo contains the full source code and test suite. The code was generated by Claude Code following the Project Bible's architecture, coding standards, and test strategy. The Orchestrator reviewed test assertions and validated behavior at each feature gate.

These are example artifacts. MeshScope has not yet completed formal Phase 3 validation. These files illustrate what Phase 3 produces when completed. They will be replaced with real artifacts when MeshScope undergoes Phase 3.

→ Phase 3 Examples

Phase 3 assumes everything is broken until proven otherwise. It produces:

• Security scan results — SAST, secret detection, dependency audit, license compliance
• Performance baselines — Startup time, file load, memory, rendering FPS
• Accessibility audit — Color independence, keyboard navigation, screen reader support
• SBOM summary — Software Bill of Materials
• Go-live checklist — Final decision gate

These are example artifacts. MeshScope has not yet completed formal Phase 4 release under the framework. These files illustrate what Phase 4 produces when completed. They will be replaced with real artifacts when MeshScope completes Phase 4.

→ Phase 4 Examples

Phase 4 packages, distributes, and establishes the maintenance cadence:

• HANDOFF.md — The document that enables a replacement to take over without reverse-engineering the codebase
• Incident response plan — Severity classification, response procedures, rollback, escalation
• Monitoring configuration — What to watch and how to alert (adapted for offline desktop applications)
• Release notes — User-facing release description

→ Approval Log — The audit trail. Shows Phase 0→1 and Phase 1→2 gate approvals, who approved, when, what evidence was reviewed, and under what mode (Private POC). Phase 3→4 gates are templated but unfilled — they become real when those phases complete.

→ Phase State — Machine-readable project state: current phase, track, deployment mode, POC mode, and gate dates.

→ CLAUDE.md — The generated agent instruction file. This is what Claude Code reads at the start of every session. It contains the project's constraints, the Builder's Guide reference, the platform module reference, coding standards, and behavioral rules. This file was generated by init.sh and customized during development.

→ Build Progress — The framework's feature tracking state. Shows all 10 features completed, 5 UAT sessions done, 0 features since last test.

→ Framework Feedback

During MeshScope's development, two gaps were discovered in the Solo Orchestrator Framework itself:

1. PR Workflow Guidance Gap — The AI agent created pull requests but didn't explain to the Orchestrator that PRs require human review and merge before work can continue. The framework now includes a PR Handoff Protocol.

2. Stop Hook Test Detection — A gap in how the framework's pre-commit hooks detect test co-location.

These feedback documents demonstrate the framework as a living system that improves from real use. Each gap discovered during a project becomes a fix in the framework for the next project.

→ CI Pipeline — Generated by init.sh for Python. Runs tests, linting, Semgrep SAST, gitleaks secret detection, dependency audit, and license checking on every push.

→ Release Pipeline — Generated by init.sh for desktop platform. Template for building, signing, and distributing cross-platform desktop executables.

• Solo Orchestrator Framework: https://github.com/kraulerson/solo-orchestrator
• MeshScope (live project): https://github.com/kraulerson/meshscope
• MeshScope Downloads: https://github.com/kraulerson/meshscope/releases

MIT — see LICENSE.

The artifacts in this repository are from a real project and are provided as educational examples of the Solo Orchestrator Framework in action. The MeshScope source code is in its own repository under its own license.