timi-ty Development Harness
A project-local control plane that compiles product intent (ROADMAP.md) into a dependency-ordered set of validator-backed phase contracts, then executes them one bounded unit at a time. Works with both Cursor and Claude Code.
How It Works
- The user runs "create development harness" to bootstrap the harness in a workspace
- The harness detects the host tool (Cursor or Claude Code) and generates tool-appropriate artifacts
- After creation, 7 workspace slash commands are available in the tool's commands directory
- The user runs
/invoke-development-harnessto execute work - A stop hook keeps the agent iterating until a verifiable goal is reached or ambiguity is encountered
- Between sessions, the user can check state, sync, inject issues, or update the harness
Command Routing
Based on the user's request, read the corresponding command file from this skill's commands/ directory:
| User Intent | Command File |
|---|---|
| Create / initialize the harness | commands/create.md |
| Continue work / invoke / run harness | commands/invoke.md |
| Modify the harness itself | commands/update.md |
| Report harness and app state | commands/state.md |
| Sync harness with code reality | commands/sync.md |
| Remove all harness artifacts | commands/clear.md |
| Report problems / inject issues | commands/inject-issues.md |
Important: After reading the command file, follow its instructions completely. Each command file is self-contained.
Architecture Summary
- state.json is a runtime snapshot only -- pointers and summaries
- phase-graph.json is the canonical source of truth for phase/unit status
- select_next_unit.py is the authoritative "what to do next" source
- checkpoint.md is a human-readable summary -- never treat as authoritative data
- manifest.json tracks three ownership classes: harness-owned, product-owned, managed-block
For full architecture details, see references/architecture.md.
Python Detection
All harness scripts require Python 3. Before running any harness script, detect the available Python command:
PY=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
[ -z "$PY" ] && { echo "Error: Python 3 is required but neither python3 nor python was found"; exit 1; }
All command files use $PY to invoke Python scripts. Run this detection once per shell session before calling any harness command.
Version upgrades
When the skill's schema_version bumps (e.g., v1 → v2), existing harnesses become incompatible and validate_harness.py rejects them with a pointer to re-create. The upgrade path is:
- Re-run
/create-development-harnessto regenerate.harness/artifacts at the new schema version. ROADMAP.mdandPHASES/*.mdare preserved — the recreate flow reads them and rebuilds the harness around them. Product intent (ROADMAP) and phase contracts (PHASES) never get regenerated from scratch.- Harness-owned files that do get regenerated:
state.json,phase-graph.json,checkpoint.md,manifest.json, the scripts under.harness/scripts/, the workspace commands, and the hook/rule files.
No migration script is provided by design. The cost of a reliable general-purpose migration (covering every schema-version delta across every downstream file) exceeds the cost of regenerating with ROADMAP.md + PHASES/*.md as the preserved inputs. config.execution_mode.versioning.break_on_schema_bump: true (the default, set during Phase 2 of /create-development-harness) enforces this — if a user prefers in-place migration attempts they can opt into break_on_schema_bump: false, but the harness ships no migration tooling to back that choice up.
Key Principle
The harness builds a task-closing machine, not a project-finishing fantasy. Every unit of work must have a validator. Every completed unit must have evidence. Every phase completion must pass an internal review checklist. Deployment truth gates block deploy-affecting phases until verification passes.