How instructkr/clawd-code works
1. What this repository is
- This is a Python-first porting workspace for a harness/agent system, not a full production app.
- The tracked source is centered on describing and verifying a rewrite: generating manifests, summaries, and parity checks against archived reference data.
2. Primary execution path
- The main user-facing entrypoint is src/main.py.
- It appears to expose CLI commands such as summary, manifest, subsystems, commands, tools, and parity-audit.
- That makes the repository architecture “CLI-driven analysis/inspection” rather than a long-running server.
3. Core data model layer
- src/models.py holds the main structured types for the porting workspace, including concepts like subsystems, modules, and backlog/state.
- This is the shared schema layer used by the manifest/query tooling to describe the current workspace consistently.
4. Workspace inventory and manifest generation
- src/port_manifest.py is the source of truth for the current Python workspace structure.
- It likely scans or enumerates the active src/ tree and produces the manifest consumed by CLI commands and tests.
- This is the boundary between “actual code on disk” and “human-readable architecture inventory.”
5. Query/rendering layer
- src/query_engine.py is responsible for turning the workspace inventory into summaries and reports.
- src/query.py and src/QueryEngine.py suggest a compatibility/transition boundary around query functionality.
- In architectural terms, this is the read-only analytics layer above the manifest/model layer.
6. Command and tool cataloging
- src/commands.py and src/tools.py define the Python-side command metadata and tool metadata.
- These mirror archived command/tool inventories and are exposed through the CLI for inspection.
- The repo’s “behavior” is mostly represented as catalog data and summaries, not as many executable subsystems yet.
7. Parity and comparison flow
- src/parity_audit.py is the validation boundary that compares the Python port against local reference snapshots.
- src/reference_data/ contains archived JSON snapshots for subsystems, commands, tools, and archive surfaces.
- The flow is: current workspace manifest → compare with reference snapshots → report parity gaps.
8. Package layout as architecture markers
- The many top-level packages under src/ (assistant, bridge, cli, coordinator, hooks, server, skills, state, voice, etc.) mostly function as namespace markers for the porting effort.
- Their presence mirrors the original system’s subsystem map, even though the Python implementation is still incomplete.
- This matters for architecture diagrams because the project is organized around subsystem boundaries, not a single monolith.
9. Runtime and interaction model
- The project is run as a local Python module/CLI (python3 -m src.main ...).
- There is no evidence of a networked backend being the primary runtime; instead, the runtime is local and inspection-oriented.
- src/runtime.py, src/entrypoints/, and src/bootstrap/ indicate future or partial support for broader execution modes.
10. Supporting state and workflow modules
- Modules like history.py, context.py, task.py, tasks.py, coordinator/, buddy/, and assistant/ suggest the intended architecture of an agent/task orchestration system.
- In the current repo state, these are better understood as port targets and architectural placeholders than as fully wired runtime paths.
11. Tests and verification
- tests/test_porting_workspace.py verifies the current Python workspace behavior.
- Testing appears focused on structure/parity correctness rather than end-to-end agent execution.
12. Important architectural boundary
- The biggest boundary is between:
- active Python porting workspace in src/
- reference snapshots in src/reference_data/
- The repo’s purpose is to keep those two views aligned enough to measure rewrite progress.
13. What to draw in an architecture diagram
- Show a central CLI entrypoint feeding a manifest/query layer, which reads the workspace tree and the reference snapshots, then produces summaries, inventories, and parity reports.
- Surround that with the named subsystem namespaces as the intended modular architecture of the larger harness.
- Treat external services as absent from the current core architecture; the repo is mainly local analysis, metadata, and parity tooling.
Main entry points: main.py Main CLI · query_engine.py Query engine · port_manifest.py Manifest · models.py Models
Components 18
CLI & reports
Entry points and read-only inspection commands.
- Main CLI · Primary command-line entrypoint for summaries, manifests, and audits.
src/main.py
Workspace core
Shared models and inventory generation for the Python port.
- Manifest · Builds the current workspace manifest from the active source tree.
src/port_manifest.py - Query engine · Turns manifest and model data into summaries and inspection reports.
src/query_engine.py - Query API · Compatibility boundary around query functionality.
src/query.py - Legacy query · Legacy module name kept during transition.
src/QueryEngine.py - Models · Shared structured types for subsystems, modules, and workspace state.
src/models.py - Commands · Command metadata exposed through the CLI and parity checks.
src/commands.py - Tools · Tool metadata mirrored from archived inventories.
src/tools.py
Parity refs
Archived snapshots used to compare rewrite progress.
- Parity audit · Compares the Python port against archived reference snapshots.
src/parity_audit.py - Reference data · Archived JSON snapshots for subsystems, commands, tools, and archive surfaces.
src/reference_data
Ported namespaces
Major subsystem namespaces preserved as architectural boundaries.
- Coordinator · Port target for task and agent coordination logic.
src/coordinator - Assistant · Port target for assistant behavior and agent-facing flows.
src/assistant - Bridge · Namespace for integration and boundary-adapter logic.
src/bridge - Server · Namespace marker for server-side components in the original system.
src/server - Skills · Namespace for reusable agent capabilities and skill definitions.
src/skills - State · Namespace for shared state and workflow context.
src/state - Voice · Namespace for voice or interactive surface support.
src/voice
Runtime scaffold
Partial execution and orchestration layers for the broader agent system.
- Runtime · Local runtime and future execution-mode support.
src/runtime.py
Connections 22
- Main CLI → Manifest: builds · CLI commands surface the current workspace inventory.
- Main CLI → Query engine: reports · Main CLI invokes summary and inspection queries.
- Main CLI → Parity audit: audits · CLI exposes parity checking against reference snapshots.
- Main CLI → Commands: lists · CLI can inspect command catalog metadata.
- Main CLI → Tools: lists · CLI can inspect tool catalog metadata.
- Main CLI → Runtime: loads · Main entrypoint sits above the local runtime scaffold.
- Manifest → Models: uses · Manifest generation is shaped by the shared workspace schema.
- Query engine → Models: reads · Reports are rendered from structured workspace models.
- Query engine → Manifest: analyzes · Query layer consumes the current manifest snapshot.
- Query engine → Reference data: compares · Query/reporting can be aligned with archived reference data.
- Query API → Query engine: wraps · Compatibility module forwards to the newer query engine.
- Legacy query → Query engine: aliases · Legacy module name points at the current query implementation.
- Parity audit → Manifest: verifies · Parity checks start from the current workspace manifest.
- Parity audit → Reference data: checks · Validator compares against archived snapshots.
- Commands → Models: serializes · Command inventory is represented through the shared schema.
- Tools → Models: serializes · Tool inventory is represented through the shared schema.
- Runtime → Coordinator: orchestrates · Runtime scaffold points toward coordination logic.
- Coordinator → Assistant: drives · Coordination boundary leads into assistant behavior.
- Coordinator → State: persists · Coordinator depends on shared state for workflow progress.
- Assistant → Skills: invokes · Assistant behavior is composed from skills/capabilities.
- Assistant → Voice: surfaces · Assistant may expose voice or interactive surfaces.
- Bridge → Server: connects · Bridge namespace marks integration to server-side surfaces.