Real-World Examples

Example 1: Weather API Service

Challenge

Building a Python FastAPI weather service with caching, rate limiting, and multi-step orchestration requires multiple coordination steps and verbose documentation in natural language.

H2C Solution

[ARCH:PLAN]
id:weather-api|fw:python3.11|lib:[fastapi,httpx,cachetools]
auth:APIKey::env(OPENWEATHER_API_KEY)
struct:[main.py,routers/weather.py,services/weather_service.py]
notes:[cache_TTL_10min,rate-limit_60req-min]

[BUILD:EXEC]
id:m1|target:main.py|desc:setup_fastapi_app

[BUILD:DONE]
id:m1|diff:[main.py~1]|rev:1

[TEST:RUN]
id:test_weather|cmd:pytest tests/test_weather.py

[TEST:PASS]
id:test_weather|pass_count:42

[ORCH:END]
final:complete|est_token:2450

Impact

• All architectural metadata preserved
• Machine-parseable for agent coordination
• Scales to multi-agent workflows

Example 2: TODO Console App

Challenge

A C# .NET 8 console application with SQLite backend demonstrates how H2C handles stateful, long-running workflows with multiple state transitions and persistent queries.

H2C Solution

[ARCH:PLAN]
id:todo-app|fw:dotnet8|db:sqlite|lib:[EFCore,Spectre.Console]
struct:[Program.cs,Models/,Services/,Data/]

[CTX:UPDATE]
~progress:layer=init,status=in_progress
~next:database_setup
~active_files:[Program.cs~1]

[BUILD:EXEC]
id:b1|target:Program.cs|desc:setup_dependency_injection

[CTX:UPDATE]
~progress:layer=database,status=done
~next:crud_implementation
~active_files:[Program.cs~1,Data/TodoContext.cs~1]

[TEST:RUN]
id:t1|cmd:dotnet test TodoServiceTests.cs

[ORCH:END]
final:complete|est_token:1845

Impact

• Clear cycle tracking for debugging
• Persistent state management across sessions
• Cost-effective for long-running applications

Example 3: PRUNE/COMPACT Chain

Challenge

Long-running chains carry context blocks (PRUNE, COMPACT, FREEZE) that mark what can be dropped.

H2C Solution

[BUILD:DONE]
id:b1|diff:[src/main.py~1]|rev:5

[BUILD:DONE]
id:b2|diff:[src/utils.py~2]|rev:3

[CTX:PRUNE]
keep:[b1,b2]|pruned:[b1,b2]|reason:consolidate_old_builds

[BUILD:DONE]
id:b3|diff:[src/api.py~1]|rev:1

[CTX:COMPACT]
summary:[layer=3,status=done,files:[src/main.py~5,src/utils.py~3,src/api.py~1]]
keep_active:[src/api.py~1]
pruned_history:msg_2_to_5

[ORCH:END]
final:complete|est_token:7140

Impact

• CTX:PRUNE and CTX:COMPACT keep only active files in scope
• Scales to multi-week workflows

Example 4: Conformance Stress Test

Challenge

Confirm that a long, complex chain — CTX:NEGOTIATE handshake, multiple builds, prunes, a compact, a freeze, and fix cycles — round-trips cleanly through the reference parser, validator, and state machine, with zero silent drops. See tests/fixtures/test5-stress-130msg.h2c in the repo.

Key Findings

• Passes the reference parser, validator, and state machine (python3 conformance/run.py)
• Exercises CTX:NEGOTIATE, PRUNE, COMPACT, FREEZE, and fix cycles in one 130-message chain
• Zero silent drops — malformed or out-of-order blocks raise explicit diagnostics