SKILL.md
$27
Verify the workspace
python3 -m unittest discover -s tests -v
No PyPI package yet — use directly from source.
---
## Repository Layout.
├── src/
│ ├── init.py
│ ├── commands.py # Python-side command port metadata
│ ├── main.py # CLI entrypoint
│ ├── models.py # Dataclasses: Subsystem, Module, BacklogState
│ ├── port_manifest.py # Current Python workspace structure summary
│ ├── query_engine.py # Renders porting summary from active workspace
│ ├── task.py # Task primitives
│ └── tools.py # Python-side tool port metadata
└── tests/ # Unittest suite
---
## CLI Reference
All commands are invoked via `python3 -m src.main <command>`.
### `summary`
Render the full Python porting summary.
python3 -m src.main summary
### manifest
Print the current Python workspace manifest (file surface + subsystem names).
python3 -m src.main manifest
### subsystems
List known subsystems, with optional limit.
python3 -m src.main subsystems
python3 -m src.main subsystems --limit 16
### commands
Inspect mirrored command inventory.
python3 -m src.main commands
python3 -m src.main commands --limit 10
### tools
Inspect mirrored tool inventory.
python3 -m src.main tools
python3 -m src.main tools --limit 10
### parity-audit
Run parity audit against a locally present (gitignored) archived snapshot.
python3 -m src.main parity-audit
Requires the local archive to be present at its expected path (not tracked in git).
## Core Modules & API
### src/models.py — Dataclasses
from src.models import Subsystem, Module, BacklogState
A subsystem groups related modules
sub = Subsystem(name="tool-harness", modules=[], status="in-progress")
A module represents a single ported file
mod = Module(name="tools.py", ported=True, notes="tool metadata only")
BacklogState tracks overall port progress
state = BacklogState(
total_subsystems=8,
ported=5,
backlog=3,
notes="runtime slices pending"
)
### src/tools.py — Tool Port Metadata
from src.tools import get_tools, ToolMeta
tools: list[ToolMeta] = get_tools()
for t in tools[:5]:
print(t.name, t.ported, t.description)
### src/commands.py — Command Port Metadata
from src.commands import get_commands, CommandMeta
commands: list[CommandMeta] = get_commands()
for c in commands[:5]:
print(c.name, c.ported)
### src/query_engine.py — Porting Summary Renderer
from src.query_engine import render_summary
summary_text: str = render_summary()
print(summary_text)
### src/port_manifest.py — Manifest Access
from src.port_manifest import get_manifest, ManifestEntry
entries: list[ManifestEntry] = get_manifest()
for entry in entries:
print(entry.path, entry.status)
## Common Patterns
### Pattern 1: Check how many tools are ported
from src.tools import get_tools
tools = get_tools()
ported = [t for t in tools if t.ported]
print(f"{len(ported)}/{len(tools)} tools ported")
### Pattern 2: Find unported subsystems
from src.port_manifest import get_manifest
backlog = [e for e in get_manifest() if e.status != "ported"]
for entry in backlog:
print(f"BACKLOG: {entry.path}")
### Pattern 3: Programmatic summary pipeline
from src.query_engine import render_summary
from src.commands import get_commands
from src.tools import get_tools
print("=== Summary ===")
print(render_summary())
print("\n=== Commands ===")
for c in get_commands(limit=5):
print(f" {c.name}: ported={c.ported}")
print("\n=== Tools ===")
for t in get_tools(limit=5):
print(f" {t.name}: ported={t.ported}")
### Pattern 4: Run tests before contributing
python3 -m unittest discover -s tests -v
### Pattern 5: Using as part of an OmX/agent workflow
Generate summary artifact for an agent to consume
python3 -m src.main summary > /tmp/claw_summary.txt
Feed into another agent tool or diff against previous checkpoint
diff /tmp/claw_summary_prev.txt /tmp/claw_summary.txt
## Rust Port (In Progress)
The Rust rewrite is on the [dev/rust](https://github.com/instructkr/claw-code/tree/dev/rust) branch.
Switch to the Rust branch
git fetch origin dev/rust
git checkout dev/rust
Build (requires Rust toolchain: https://rustup.rs)
cargo build
Run
cargo run -- summary