| name | oip-proposal |
| description | Create OmoiOS Improvement Proposals (OIPs) through an interactive workflow. Gathers context
from the user via clarifying questions, researches relevant codebase files, then writes a
complete proposal following the OIP template.
Use when requesting "create a proposal", "write an OIP", "new proposal", "propose a feature",
"OIP", "improvement proposal", or when the user wants to formally propose a product, architecture,
or process change for OmoiOS.
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch |
OIP Proposal Skill
Create OmoiOS Improvement Proposals (OIPs) through an interactive, question-driven workflow. This skill gathers context from the user, researches the codebase for accurate file references, and writes a complete proposal following the project's OIP template.
Workflow
Follow these three phases in order. Do not skip the clarification phase — proposals written without understanding the user's intent produce vague specifications that require rewrites.
Phase 1: Clarify the Proposal
Goal: Understand what the user wants to propose and why, before writing anything.
Step 1: Determine the next OIP number
Read docs/proposals/README.md and check which OIP numbers are taken:
ls docs/proposals/oip-*.md
The next number is one above the highest existing number, zero-padded to 4 digits.
Step 2: Ask clarifying questions
Use the AskUserQuestion tool to gather essential context. Ask questions based on what the user has provided so far. Not all questions will be needed for every proposal — use judgment.
Always ask:
- What problem does this solve? (The "motivation" — should be concrete, not vague)
- Who benefits? (Users, developers, ops, everyone?)
- What's the proposed solution at a high level?
Ask if unclear:
- What type of proposal is this? (Standards Track for product/code changes, Informational for guidelines, Process for workflow changes)
- Are there constraints or non-goals? (Things this proposal deliberately does NOT do)
- Are there alternatives you considered and rejected?
- Does this depend on or conflict with other OIPs?
- What's the security surface? (New endpoints, auth changes, public-facing features)
- What infrastructure is needed? (New services, databases, external APIs)
Ask if the proposal involves frontend work:
- Which routes or pages are affected?
- Are new components needed, or can existing ones be reused?
- How does this interact with the navigation/sidebar?
Ask if the proposal involves backend work:
- Which services are affected?
- Are database migrations needed?
- Does this require new API endpoints?
Step 3: Confirm understanding
Summarize what you've gathered in 3-4 sentences and ask the user to confirm before proceeding. Use AskUserQuestion with options like "Yes, that's right" / "Close but let me clarify" / "No, let me re-explain".
Phase 2: Research the Codebase
Goal: Find the real files, components, and patterns that the proposal will reference. Proposals that reference actual codebase paths are far more useful than ones that speak abstractly.
What to research
Based on the proposal's scope, read the relevant files:
- Frontend changes: Check
frontend/app/ for route structure, frontend/components/ for existing components, frontend/hooks/ for data patterns, frontend/lib/api/ for API client functions
- Backend changes: Check
backend/omoi_os/api/routes/ for existing endpoints, backend/omoi_os/services/ for business logic, backend/omoi_os/models/ for database schema
- Configuration: Check
backend/config/base.yaml for settings patterns
- Existing proposals: Read related OIPs in
docs/proposals/ to avoid conflicts or duplication
Key reference documents
| Document | When to read |
|---|
ARCHITECTURE.md | Any backend or system-wide proposal |
UI.md | Any frontend proposal |
docs/proposals/README.md | Always — check status table for conflicts |
backend/CLAUDE.md | Backend conventions (structured_output, datetime, reserved words) |
Record your findings
Note the exact file paths (relative from repo root) for every component, service, hook, or route you'll reference. The Specification section must use real paths, not hypothetical ones.
Phase 3: Write the Proposal
Goal: Write the complete OIP file following the template exactly.
File location
docs/proposals/oip-{NNNN}-{short-title}.md
Where {NNNN} is the zero-padded number and {short-title} is a kebab-case slug (2-4 words).
Required structure
Every OIP must contain these sections in this order:
```
OIP: {NNNN}
Title: {Descriptive Title}
Description: {One-line summary, max 140 characters}
Author: {Name or handle}
Status: Draft
Type: {Standards Track | Informational | Process}
Created: {YYYY-MM-DD}
Requires: (optional, other OIP numbers)
Replaces: (optional)
Superseded-By: (optional)
```
## Abstract
2-3 sentences. A reader should understand the proposal in 30 seconds.
## Motivation
Why this change is needed. Include data, user research, or metrics.
Reference the problem concretely — link to specific code that demonstrates the issue.
## Specification
Concrete technical details. This is the longest section.
For each change, specify:
- **Modified file**: `path/to/file.ts` — what changes and why
- **New file**: `path/to/new/file.ts` — what it does, key interfaces/types
Include code snippets for interfaces, types, API endpoints, config changes.
Be specific enough that another engineer could implement without asking questions.
## Rationale
Why this approach over alternatives. Name the alternatives explicitly
and explain why they were not chosen. Discuss trade-offs.
## Backwards Compatibility
How existing users and behavior are affected.
If none: "No backwards compatibility concerns."
## Security Considerations
Authentication, rate limiting, abuse vectors, data exposure.
Every proposal MUST address this, even if the answer is "no new attack surface."
## Impact Assessment
Effort estimate (small/medium/large), infrastructure costs, expected user impact.
Include metrics for measuring success.
## Open Issues
Unresolved questions. Number them for easy reference in discussions.
Writing guidelines
- Reference real files: Use
path/to/file.ts format for every file mentioned. Readers should be able to cat the file and see what you're talking about.
- Show interfaces: For new components, APIs, or data structures, include the TypeScript interface or Python class definition.
- Be opinionated: State the recommended approach clearly. Don't present 3 options without recommending one.
- Quantify where possible: "~200 lines of new code", "$0.05 per session", "reduces onboarding from 6 steps to 2".
- Address security proactively: Don't wait to be asked. If the feature has a public surface, discuss rate limiting, auth, and abuse vectors.
After writing
- Update
docs/proposals/README.md — add the new OIP to the status table
- Show the user the completed file path and a brief summary
- Ask if they want to adjust anything before committing
Example Trigger Conversations
User: "I want to propose adding WebSocket support to the sandbox page"
Action: Ask clarifying questions about scope (which events? replace polling? backwards compatible?), research frontend/app/(app)/sandbox/[sandboxId]/page.tsx and frontend/hooks/useSandbox.ts, then write the OIP.
User: "Write an OIP for rate limiting the public API"
Action: Ask about which endpoints, what limits, whether it's IP-based or token-based, research backend/omoi_os/api/main.py and existing auth middleware, then write the OIP.
User: "New proposal"
Action: Ask what they want to propose — don't assume. Start with "What problem are you looking to solve?"
Related Resources
