omkx 0.1.0

package/.kiro/steering/omkx/architecture.md

@@ -0,0 +1,166 @@
+# omkx — Architecture & Agent Flows
+
+## System Architecture
+
+omkx is a three-tier multi-agent orchestration system:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      USER INTERFACE                      │
+│         (Kiro IDE — agent selection via shortcuts)       │
+└──────────┬──────────────┬──────────────┬────────────────┘
+           │ ctrl+p       │ ctrl+a       │ ctrl+e
+           ▼              ▼              ▼
+    ┌──────────┐   ┌──────────┐   ┌──────────┐
+    │PROMETHEUS│   │  ATLAS   │   │SISYPHUS  │
+    │ Planner  │   │Executor  │   │ Direct   │
+    └────┬─────┘   └────┬─────┘   └────┬─────┘
+         │              │              │
+         ▼              ▼              ▼
+    ┌─────────────────────────────────────────────────────┐
+    │               SUBAGENT ORCHESTRATION                 │
+    │                                                     │
+    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
+    │  │  METIS   │ │ MOMUS    │ │ ORACLE   │            │
+    │  │Pre-plan  │ │Validator │ │Advisor   │            │
+    │  └──────────┘ └──────────┘ └──────────┘            │
+    │                                                     │
+    │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
+    │  │EXPLORER  │ │LIBRARIAN │ │ JUNIOR   │            │
+    │  │Codebase  │ │Research  │ │Implement │            │
+    │  └──────────┘ └──────────┘ └──────────┘            │
+    │                                                     │
+    │  ┌──────────┐                                       │
+    │  │ LOOKER   │                                       │
+    │  │ Media    │                                       │
+    │  └──────────┘                                       │
+    └─────────────────────────────────────────────────────┘
+```
+
+## Agent Roles & Delegation Flows
+
+### Prometheus (Planning Flow)
+```
+User Request
+  │
+  ▼
+Pre-Analysis ──► ghost-metis (analyze intentions, risks, ambiguities)
+  │
+  ▼
+Research ──► ghost-explorer (explore codebase)
+  │      ──► ghost-librarian (research docs/web)
+  │
+  ▼
+Interview ──► User (clarify ambiguities)
+  │
+  ▼
+Plan Generation ──► .kiro/plans/{name}.md
+  │
+  ▼
+Validation ──► ghost-momus (review for blockers)
+  │
+  ▼
+Final Plan ──► User (handoff to Atlas)
+```
+
+### Atlas (Execution Flow)
+```
+Plan File (.kiro/plans/{name}.md)
+  │
+  ▼
+Parse Tasks ──► Identify dependencies, agent assignments
+  │
+  ▼
+Parallel Delegation ──► Task 1 ──► ghost-junior ──► Verify
+  │                  ──► Task 2 ──► ghost-junior ──► Verify
+  │                  ──► Task 3 ──► ghost-explorer ──► Verify
+  │
+  ▼
+Oracle Escalation (on failure) ──► ghost-oracle ──► Re-delegate
+  │
+  ▼
+Final Verification ──► All acceptance criteria met?
+  │
+  ▼
+Report ──► User
+```
+
+### Sisyphus (Direct Task Flow)
+```
+User Request
+  │
+  ▼
+Triage
+  │
+  ├── Trivial ──► Do it yourself
+  │
+  ├── Complex ──► ghost-junior (implement)
+  │
+  ├── Research ──► ghost-librarian (research)
+  │
+  └── Explore ──► ghost-explorer (explore)
+  │
+  ▼
+Oracle Escalation (if stuck) ──► ghost-oracle
+  │
+  ▼
+Report ──► User
+```
+
+## Notepad System
+
+Notepads provide context persistence across agent invocations:
+
+```
+.kiro/notepads/{plan-name}/
+├── pre-analysis.md      # ghost-metis: hidden intentions, risks
+├── exploration.md       # ghost-explorer: codebase findings
+├── research.md          # ghost-librarian: web/doc findings
+├── plan-review.md       # ghost-momus: validation results
+├── oracle-advice.md     # ghost-oracle: recommendations
+├── verification.md      # Atlas: per-task verification
+└── implementation.md    # ghost-junior: implementation notes
+```
+
+### Notepad Protocol
+1. Prometheus creates the notepad directory when generating a plan
+2. Each agent writes findings to their designated file
+3. Atlas reads all notepads for context before executing tasks
+4. ghost-junior reads notepads for implementation context
+5. Notepads are persistent — they survive agent session restarts
+
+## Write Restrictions
+
+The write restriction system prevents agents from modifying files outside their authority:
+
+| Agent | Write Zones |
+|-------|-------------|
+| Prometheus | `.kiro/plans/**`, `.kiro/notepads/**` |
+| Atlas | `.kiro/plans/**`, `.kiro/notepads/**` |
+| Sisyphus | Unrestricted |
+| ghost-explorer | `.kiro/notepads/**` |
+| ghost-metis | `.kiro/notepads/**` |
+| ghost-momus | `.kiro/notepads/**` |
+| ghost-oracle | `.kiro/notepads/**` |
+| ghost-librarian | `.kiro/notepads/**` |
+| ghost-junior | Unrestricted |
+| ghost-looker | No write access |
+
+## Oracle Consultation Pattern
+
+The Oracle is consulted only in three scenarios:
+
+1. **Architecture Advice**: Before major design decisions
+2. **Debugging Escalation**: After 2+ failed implementation attempts
+3. **Self-Review**: When agents need their output reviewed
+
+Oracle always provides exactly ONE recommendation per consultation, tagged with an effort estimate (TRIVIAL/SMALL/MEDIUM/LARGE/XLARGE).
+
+## Hook System
+
+Hooks enforce agent behavior at key lifecycle points:
+
+- **agentSpawn**: Injected identity reminder + git status context
+- **preToolUse**: Blocks destructive operations on `.kiro/` files
+- **userPromptSubmit**: Identity reinforcement for Atlas
+- **Prometheus guards**: Special read/write hooks enforcing planner-only behavior

package/.kiro/steering/omkx/conventions.md

@@ -0,0 +1,64 @@
+# omkx — Naming & File Conventions
+
+## Steering Directory
+All omkx steering files live under `.kiro/steering/omkx/`. The directory name `omkx` distinguishes it from other Kiro configurations.
+
+## Plan Files
+- Location: `.kiro/plans/`
+- Naming: `{YYYY-MM-DD}-{short-description}.md`
+- Examples: `2026-06-21-add-auth.md`, `2026-06-21-refactor-api.md`
+- Format: See `plan-format.md` for the full template
+
+## Notepad System
+- Location: `.kiro/notepads/{plan-name}/`
+- Each plan gets its own notepad directory
+- Notepad files persist intermediate agent findings:
+  - `pre-analysis.md` — ghost-metis analysis
+  - `exploration.md` — ghost-explorer findings
+  - `research.md` — ghost-librarian research
+  - `plan-review.md` — ghost-momus review
+  - `oracle-advice.md` — ghost-oracle consultations
+  - `verification.md` — Atlas verification notes
+  - `implementation.md` — ghost-junior implementation notes
+
+## Agent Names
+- Main agents: `prometheus`, `atlas`, `sisyphus` (lowercase, no prefix)
+- Subagents: `ghost-` prefix (e.g., `ghost-junior`, `ghost-oracle`)
+- Agent config files: `{name}.json` in `.kiro/agents/`
+- Agent prompt files: `{name}.md` in `.kiro/prompts/`
+
+## Delegation Format
+All delegations from main agents to subagents use the 6-section format:
+1. Task (name + target agent)
+2. Context (what the subagent needs to know)
+3. Objective (specific goal)
+4. Boundaries (scope limits)
+5. Output (expected deliverable)
+6. Success Criteria (verification)
+
+## File References
+- Agent configs reference prompts via `file://../prompts/{name}.md`
+- Agents reference steering via `file://.kiro/steering/omkx/**/*.md`
+- Agents reference skills via `skill://.kiro/skills/**/SKILL.md`
+
+## Write Restrictions
+- Prometheus: `.kiro/plans/**` and `.kiro/notepads/**` only
+- Atlas: `.kiro/plans/**` and `.kiro/notepads/**` only
+- Sisyphus: unrestricted (full user trust)
+- ghost-explorer: `.kiro/notepads/**` only
+- ghost-metis: `.kiro/notepads/**` only
+- ghost-momus: `.kiro/notepads/**` only
+- ghost-oracle: `.kiro/notepads/**` only
+- ghost-librarian: `.kiro/notepads/**` only
+- ghost-junior: unrestricted (full filesystem)
+- ghost-looker: no write access
+
+## Keyboard Shortcuts
+- `ctrl+p` — Prometheus (Planner)
+- `ctrl+a` — Atlas (Plan Executor)
+- `ctrl+e` — Sisyphus (Direct Executor)
+
+## Shell Access
+- All subagents: auto-allow readonly shell commands
+- ghost-junior: full shell access (not auto-allowed)
+- ghost-looker: no shell access

package/.kiro/steering/omkx/plan-format.md

@@ -0,0 +1,97 @@
+# Plan File Format
+
+Every plan created by Prometheus must follow this structure.
+
+## Template
+
+```markdown
+# Plan: {Descriptive Title}
+
+**Created:** {YYYY-MM-DD}
+**Status:** DRAFT | REVIEWED | IN_PROGRESS | COMPLETE
+**Goal:** {One-sentence description of what this plan achieves}
+
+---
+
+## Context
+
+### What We Know
+{Summary of research findings — from ghost-explorer, ghost-librarian, and user interview}
+
+### Pre-Analysis Summary
+{Key findings from ghost-metis: hidden intentions, risks, ambiguities}
+
+### Constraints
+- {Constraint 1}
+- {Constraint 2}
+
+---
+
+## Tasks
+
+### Task 1: {Task Name}
+**Agent:** {ghost-junior | ghost-explorer | ghost-librarian | ghost-oracle}
+**Depends On:** {none | task number}
+**Description:** {WHAT to do, not HOW}
+**Expected Output:** {files, changes, or results}
+**Verification:** {how Atlas will verify this task}
+
+### Task 2: {Task Name}
+**Agent:** {subagent}
+**Depends On:** {task number}
+**Description:** {WHAT to do}
+**Expected Output:** {deliverable}
+**Verification:** {verification steps}
+
+---
+
+## Acceptance Criteria
+
+- [ ] {Criterion 1 — verifiable condition}
+- [ ] {Criterion 2 — verifiable condition}
+- [ ] {Criterion 3 — verifiable condition}
+
+---
+
+## Risks & Mitigations
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| {Risk description} | HIGH/MEDIUM/LOW | {How to handle if it occurs} |
+
+---
+
+## Notes
+
+{Any additional information for Atlas or future reference}
+```
+
+## Task Guidelines
+
+### Task Description
+- Describe WHAT needs to be done, never HOW
+- Be specific enough that ghost-junior can implement without questions
+- Include relevant file paths when known
+
+### Agent Assignment
+- `ghost-junior`: Code implementation, file creation, command execution
+- `ghost-explorer`: Codebase exploration and file discovery
+- `ghost-librarian`: Web research and documentation lookup
+- `ghost-oracle`: Architectural decisions and design review
+
+### Dependencies
+- Most tasks should be independent for parallel execution
+- Only add dependencies when output of one task is required by another
+- Avoid long dependency chains
+
+### Verification
+- Each task must have verifiable success criteria
+- Atlas will check these after each task completes
+- Be specific: "File exists at path X" not "Task is done"
+- Include commands to run when applicable
+
+## Acceptance Criteria
+- Must be binary (pass/fail)
+- Must be verifiable without interpretation
+- Cover the complete plan scope
+- Include both functional and non-functional requirements

package/.kiro/steering/omkx/product.md

@@ -0,0 +1,66 @@
+# omkx — Multi-Agent Orchestration for Kiro
+
+## What is omkx?
+
+omkx is a multi-agent orchestration system for the Kiro IDE. It brings the battle-tested agent architecture from [oh-my-openagent](https://github.com/seyisulu/oh-my-openagent) (a TypeScript-based multi-agent system) into Kiro's native agent format.
+
+## Agent System
+
+omkx provides 10 specialized agents organized into three tiers:
+
+### Main Agents (User-Facing)
+| Agent | Shortcut | Role |
+|-------|----------|------|
+| **Prometheus** | `ctrl+p` | The Planner — gathers info, interviews users, writes structured execution plans |
+| **Atlas** | `ctrl+a` | The Plan Executor — reads plans, delegates to subagents, verifies everything |
+| **Sisyphus** | `ctrl+e` | The Direct Executor — handles ad-hoc user requests by delegating to specialists |
+
+### Subagents (Internal Specialists)
+| Agent | Role |
+|-------|------|
+| **ghost-oracle** | Strategic technical advisor — architecture, debugging, self-review |
+| **ghost-metis** | Pre-planning analyst — finds hidden intentions, risks, ambiguities |
+| **ghost-momus** | Plan validator — reviews plans for blocking issues |
+| **ghost-librarian** | Research specialist — web search, documentation, library evaluation |
+| **ghost-explorer** | Codebase explorer — finds files, maps structure, identifies patterns |
+| **ghost-junior** | Implementation specialist — writes code, creates files, verifies results |
+| **ghost-looker** | Media analyst — analyzes images, PDFs, diagrams |
+
+## Core Philosophy
+
+1. **Plan-First Development**: Prometheus creates detailed plans. Atlas executes them. Never skip planning.
+2. **Delegation, Not DIY**: Main agents delegate everything to specialists. They never write code themselves.
+3. **Verification Over Trust**: Atlas verifies every subagent output. Subagents can and do make mistakes.
+4. **Plan as Sole Handoff**: The plan file on disk is the single source of truth between agents.
+5. **Parallel by Default**: Independent tasks are executed in parallel for speed.
+6. **Notepad System**: Intermediate findings are stored in `.kiro/notepads/{plan-name}/` for context persistence.
+
+## File System
+
+```
+.kiro/
+├── agents/          # Agent JSON configurations
+├── prompts/         # Agent behavior prompts (markdown)
+├── hooks/           # Shell hooks for agent lifecycle
+├── skills/          # Shared skill definitions
+├── steering/omkx/   # System configuration and conventions
+├── settings/        # MCP and tool settings
+├── plans/           # Execution plans (created by Prometheus)
+└── notepads/        # Intermediate agent findings and context
+```
+
+## Workflow
+
+```
+User → Prometheus (creates plan) → Atlas (executes plan) → Done
+                                  ↑
+User → Sisyphus (ad-hoc tasks, no plan needed)
+```
+
+## Based On
+
+omkx converts the agent personalities and workflows from oh-my-openagent into Kiro's native JSON agent format, following the conventions established by oh-my-kiro.
+
+## Version
+
+0.1.0 — Initial release with 10 agents

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seyisulu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.