Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
PlanQueue is an extension for the Oh My Pi (OMP) harness, designed to facilitate a prompt queue workflow for coding agents. Contributions to this project are welcome and are expected to follow specific technical standards, including TypeScript strict mode, Biome linting, and Conventional Commits. The following guidelines outline the necessary prerequisites, setup, and architectural constraints for developers looking to improve PlanQueue.
Sources: README.md:1-12, CONTRIBUTING.md:1-5
Development Environment Setup
PlanQueue is built using TypeScript and the Bun runtime. To ensure a consistent development environment, contributors must adhere to the following setup and verification steps.
Prerequisites and Installation
Contributors must have Bun (version >= 1.0.0) installed. Once the repository is cloned, dependencies are installed via the standard Bun command.
bun install
Sources: CONTRIBUTING.md:7-13, package.json:41-43
Local Plugin Linking
To test the extension within an OMP harness during development, contributors should use the OMP plugin link utility:
omp plugin link
Sources: CONTRIBUTING.md:32-35
Verification and Quality Gates
The project maintains a rigorous quality gate that must be passed before opening a pull request. This involves linting, typechecking, and running automated tests.
Required Checks
The following suite of commands constitutes the "full gate" for contributions:
bun run lint && bun run typecheck && bun test
- Linting: Handled by Biome.
bun run formatcan be used to apply auto-fixes. - Typechecking: TypeScript must pass in strict mode.
- Testing: New logic should be accompanied by a test in the
tests/directory.
Sources: CONTRIBUTING.md:15-27, package.json:45-50
Code Quality Workflow
The following diagram illustrates the workflow for verifying changes before submission:
This flow ensures that style enforcement, type safety, and functional requirements are met sequentially.
Sources: CONTRIBUTING.md:17-25
Technical Conventions and Architecture
Contributors must respect the architectural boundaries established in the project to maintain portability and modularity.
Module Separation
The project distinguishes between "pure modules" and "OMP host wiring." Pure modules must remain free of OMP host imports to ensure logic is decoupled from the specific agent harness.
| Module Type | Files / Responsibilities | Constraints |
|---|---|---|
| Pure Modules | src/queue.ts, src/store.ts, src/paths.ts, src/editor.ts, src/widget.ts | Must NOT import OMP host modules. |
| OMP Wiring | src/main.ts, src/queue-controller.ts | Entry point for OMP extension API and tool registration. |
Sources: CONTRIBUTING.md:23-25, src/main.ts:1-20
Styling and Standards
The codebase follows specific formatting and commit standards:
- Style Enforcement: Configured in
biome.jsonwith a preference for tabs and double quotes. - Commits: Use Conventional Commits in English.
- TypeScript: Targeted at
ESNextwithstrictmode enabled andnoUncheckedIndexedAccess.
Sources: CONTRIBUTING.md:26-30, biome.json:1-30, tsconfig.json:1-15
Tool and Command Registration
When adding new functionality, developers should follow the existing patterns for registering LLM tools and slash commands via the ExtensionAPI.
Sources: src/main.ts:211-230, src/main.ts:316-330
Code of Conduct and Reporting
PlanQueue maintains a professional and constructive community. Contributors are expected to:
- Be respectful and welcome newcomers.
- Keep discussions focused on the technical work.
- Assume good faith.
Security vulnerabilities should never be reported through public issues. Instead, use GitHub's private reporting feature or email aryrabelo@gmail.com.
Sources: CONTRIBUTING.md:37-41, SECURITY.md:1-12
By following these guidelines, contributors ensure that PlanQueue remains a robust and reliable tool for the OMP ecosystem. Proper modularity and strict type safety are the cornerstones of the project's maintenance strategy.