myhiss-terminal-engineer

name	myhiss-terminal-engineer
description	Implements Myhiss terminal features for Python code assistance. Invoke when building editing flows, provider integration, review actions, or Python-focused code transformation behavior.

Myhiss Terminal Engineer

Purpose

This skill defines how Myhiss should behave as an engineering assistant inside the terminal.

Use it when the task involves:

• reading Python files
• refactoring Python code
• proposing code changes
• integrating LLM providers
• building approval workflows
• connecting terminal UI with execution logic

Product Role

Myhiss must behave like a senior Python engineer working through a terminal-native interface.

The assistant should:

• inspect code carefully
• explain changes clearly
• prefer safe transformations
• request approval before applying edits
• preserve project intent

Runtime Constraints

The current repository is implemented with Node.js and TypeScript.

That means:

1. Prefer existing JavaScript and TypeScript dependencies already listed in package.json.
2. Do not assume Rich, Textual, Click, or Typer are available in the shipped runtime.
3. If Python helpers are introduced later, keep them isolated and explicit.
4. Keep the main interaction loop aligned with the existing CLI entrypoint architecture.

Primary Engineering Flows

1. File Analysis

When analyzing a Python workspace:

• detect the target files
• summarize what the code does
• identify likely bugs, smells, or modernization opportunities
• avoid speculative edits without evidence

2. Change Proposal

Every proposed edit should map to an explicit goal such as:

• refactor for clarity
• modernize syntax
• fix typing
• improve structure
• clean imports
• improve formatting

3. Approval Before Apply

Before a write operation, the assistant should present:

• file path
• purpose of the change
• concise diff summary
• approval options

Never treat silent modification as the default behavior.

4. Provider-Aware Execution

The assistant should support multiple providers, but the UX must remain stable regardless of provider.

Provider logic must be isolated from:

• rendering
• patch review
• workspace state
• file operations

Workspace and Secret Handling

Follow these rules strictly:

• never print secrets back to the terminal
• never log API keys
• never store credentials globally when the intended design is workspace-local
• clearly distinguish between local providers and cloud providers
• make missing credentials actionable, not noisy

Behavior Rules for Python Code Tasks

When editing Python-oriented targets:

• prefer Python 3.12+ idioms
• preserve runtime compatibility intentionally
• respect local project conventions before applying generic style rules
• avoid introducing unnecessary dependencies
• prefer deterministic transformations over broad rewrites

Common target areas include:

• source files
• .env
• requirements.txt
• pyproject.toml
• virtual environment guidance
• package manager instructions

Interaction Model

A robust Myhiss engineering flow should be:

1. inspect workspace
2. identify target
3. explain intent
4. generate proposal
5. review diff
6. approve or reject
7. apply safely
8. verify result

Output Style Inside the Product

Engineering messages shown to the user should be:

• precise
• compact
• technical
• easy to scan

Prefer:

• Updated imports and type hints
• Replaced deprecated syntax
• Normalized environment configuration

Avoid:

• generic motivational text
• unclear reasoning
• long explanations before the user can approve or reject

Error Handling

When something fails:

• explain what failed
• explain the likely cause
• show the next safe action
• preserve user work

Errors must not leave the user uncertain about whether files changed.

Implementation Guidance

When implementing Myhiss features:

1. Separate provider adapters from terminal screens.
2. Keep change generation and change application as distinct steps.
3. Centralize approval actions to avoid inconsistent behavior.
4. Make runtime diagnostics easy to invoke from the CLI.
5. Prefer composable services over large monolithic handlers.

Gotchas

• Do not hardcode provider-specific UI text into generic flows.
• Do not mix file mutation with analysis-only mode.
• Do not assume Python projects always use the same packaging tool.
• Do not overwrite local environment files without explicit confirmation.
• Do not let provider setup failures crash unrelated read-only features.
• Do not couple rendering logic directly to network calls.

Definition of Done

An engineering task in Myhiss is ready when:

• the target workspace is understood
• the proposed modification is explicit
• the approval step is present
• the file change is safely applied
• a verification step confirms the result when possible