Code Editing & Hashline
Relevant source files
The following files were used as context for generating this wiki page:
- packages/coding-agent/src/prompts/system/plan-mode-active.md
- packages/coding-agent/src/prompts/system/system-prompt.md
- packages/coding-agent/DEVELOPMENT.md
- packages/coding-agent/src/commit/agentic/validation.ts
- packages/typescript-edit-benchmark/src/report.ts
- packages/coding-agent/test/modes/components/plan-toc.test.ts
The "Code Editing & Hashline" system within Oh My Pi provides a robust framework for surgical file modifications, structural planning, and verification of code changes. At its core, it utilizes specialized tools like edit for precise modifications and a structural editing mode called "Hashline" for managing complex plans and block-based transformations. This system is designed to prioritize correctness and maintainer intent by enforcing rigorous planning phases before any state-changing modifications occur.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md, packages/coding-agent/src/prompts/system/plan-mode-active.md
Editing Subsystems and Tools
The project employs a multi-tiered approach to code modification, ranging from simple text-based edits to syntax-aware transformations.
Specialized Editing Tools
The system enforces the use of specialized tools over shell-based equivalents to ensure precision and auditability:
| Tool | Primary Purpose | Usage Constraint |
|---|---|---|
edit | Surgical edits to existing files | MUST use for surgical modifications |
write | Create or overwrite files | SHOULD prefer edit for existing files |
ast_edit | Structural codemods | Use for syntax-aware transformations |
lsp | Code intelligence and refactoring | MUST use for references and code actions |
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:105-130
Hashline Edit Mode
Hashline is a specific editing variant designed for block-level operations, particularly useful for managing implementation plans. It allows for revising documents section-by-section using Markdown headings as anchors.
Hashline Operations
- SWAP.BLK N: Rewrites an entire section (from the heading line to the next heading of same/higher level) in place.
- DEL.BLK N: Removes an entire section and its nested children.
- INS.BLK.POST N: Inserts a new section immediately after the target heading.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:40-50, packages/coding-agent/test/modes/components/plan-toc.test.ts:55-75
Planning and Execution Workflow
Oh My Pi utilizes a strict "Plan Mode" to separate design decisions from implementation.
The planning workflow ensures that an implementer can execute the plan without making further design decisions.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:1-20
Plan Sections
A comprehensive plan MUST include:
- Context: The literal ask and intended end state.
- Approach: Ordered steps defining concrete edits, symbols to reuse, and failure handling.
- Critical Files & Anchors: Files necessary for understanding non-obvious work.
- Verification: Steps to prove the new behavior works end-to-end.
- Assumptions & Contingencies: Pre-decided fallbacks for uncertain scenarios.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:105-140
Verification and Analysis
Verification is a non-negotiable phase of the code editing lifecycle.
Benchmark Metrics
The system tracks editing performance through benchmarks, focusing on the "Hashline" variant and patch application success.
| Metric | Description |
|---|---|
| Edit Success Rate | Percentage of runs where the edit tool successfully applied changes. |
| Autocorrect-Free Rate | Rate of successful edits that did not require automatic corrections. |
| Patch Failure Rate | Frequency of failures where the patch failed to apply. |
| Indent Score | A measure of how well the edit maintained code formatting/indentation. |
Sources: packages/typescript-edit-benchmark/src/report.ts:95-125
Validation Rules
Before committing changes, the system validates the "Summary" (commit message) to ensure it follows conventional standards:
- MUST start with a past-tense verb (e.g., "Added", "Fixed", "Refactored").
- MUST be under 72 characters.
- SHOULD avoid filler words like "comprehensive", "various", or "improved".
Sources: packages/coding-agent/src/commit/agentic/validation.ts:55-85
Technical Implementation Details
The core logic for plan manipulation involves parsing Markdown sections and tracking heading levels.
The parser ignores headings inside fenced code blocks and requires whitespace after hashes to identify valid ATX headings.
Sources: packages/coding-agent/test/modes/components/plan-toc.test.ts:10-50
Summary
The Code Editing & Hashline system provides a disciplined environment for software development. By enforcing a read-only "Plan Mode" and utilizing specialized tools like the Hashline block editor, the system minimizes design drift and maximizes implementation accuracy. Comprehensive benchmarking and validation ensure that every modification is not only correct but also adheres to the repository's structural and stylistic conventions.