omegon-pi 0.12.0

package/skills/cleave/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: cleave
+description: Task decomposition, code assessment, and OpenSpec integration. Use /cleave for parallel execution, /assess for code review (cleave, diff, spec subcommands), cleave_assess tool for complexity checks.
+---
+
+# Cleave
+
+Task decomposition is provided by the **cleave extension** (`extensions/cleave/`).
+
+## Tools & Commands
+
+| Surface | Purpose |
+|---------|---------|
+| `cleave_assess` tool | Assess directive complexity → execute / cleave / needs_assessment |
+| `cleave_run` tool | Execute a split plan with git worktree isolation |
+| `/cleave <directive>` | Full interactive workflow: assess → plan → confirm → execute → report |
+| `/assess cleave` | Adversarial review of last 3 commits → auto-fix all C/W issues |
+| `/assess diff [ref]` | Review changes since ref (default: HEAD~1) — analysis only |
+| `/assess spec [change]` | Validate implementation against OpenSpec Given/When/Then scenarios |
+| `/assess complexity <directive>` | Check if a task needs decomposition |
+
+## Usage
+
+```
+/cleave "Implement JWT authentication with refresh tokens"
+```
+
+The directive is assessed for complexity. If it exceeds the threshold (default 2.0),
+it's decomposed into 2–4 child tasks executed in parallel via git worktrees.
+
+## OpenSpec Integration
+
+When `openspec/changes/*/tasks.md` exists in the repo, `/cleave` uses it as the
+split plan instead of invoking the LLM planner:
+
+1. Detects `openspec/` directory in the working tree
+2. Finds changes with `tasks.md` files
+3. Matches the directive to a change by name (slug matching)
+4. Parses task groups → `ChildPlan[]` (skips all-done groups, caps at 4)
+5. Infers dependencies from "after X" / "requires X" / "depends on X" markers
+6. Falls back to LLM planner if no matching change is found
+
+This makes OpenSpec the upstream planning layer and cleave the downstream
+execution engine. OpenSpec is optional — cleave works standalone.
+
+### Spec-Domain Annotations
+
+Task groups in `tasks.md` can declare which spec files they own via HTML comments:
+
+```markdown
+## 2. RBAC Enforcement
+<!-- specs: relay/rbac -->
+- [ ] Wire has_capability() into create_session()
+```
+
+Cleave uses these annotations for deterministic scenario-to-child matching (3-tier priority):
+
+1. **Annotation match** — child's `specDomains` includes the scenario's domain
+2. **Scope match** — child's file scope includes files referenced in the scenario
+3. **Word-overlap fallback** — shared words between child description and scenario text
+
+### Orphan Scenario Safety Net
+
+Any spec scenario matching zero children is auto-injected into the closest child
+with a `⚠️ CROSS-CUTTING` marker. This prevents enforcement scenarios from falling
+between children when task groups are split by layer instead of by spec domain.
+The markers provide observability — if many orphans appear, task grouping needs improvement.
+
+### Full Lifecycle
+
+When OpenSpec is present, the complete lifecycle is:
+
+```
+/opsx:propose → /opsx:ff → /cleave → /assess spec → /opsx:verify → /opsx:archive
+```
+
+After `/cleave` completes with an OpenSpec change:
+- Tasks are automatically reconciled in `tasks.md`
+- If completed work cannot be mapped back to task groups, treat that as a lifecycle reconciliation warning and fix the OpenSpec plan before archive
+- The report includes Next Steps guidance
+- If all tasks complete: `/assess spec` → `/opsx:verify` → `/opsx:archive`
+- If partial: `/opsx:apply` or `/cleave` again
+- After `/assess spec` or `/assess cleave`, run post-assess reconciliation so failed/partial review can reopen implementation state and append design-tree implementation-note deltas
+- Before archive, ensure the bound design-tree node and OpenSpec task state both reflect reality
+
+### Session Start
+
+On session start, active OpenSpec changes are surfaced with task progress.
+This status is injected into the agent context (not just displayed).
+
+## Complexity Formula
+
+```
+complexity = systems × (1 + 0.5 × modifiers)
+effective  = complexity + 1  (when validation enabled)
+```
+
+The formula uses bare `systems` (not `1 + systems`) so that single-system,
+zero-modifier directives score 1.0 (effective 2.0) — at the default threshold
+of 2.0, they get `needs_assessment` rather than being falsely recommended
+for decomposition.
+
+## Patterns (12)
+
+Full-Stack CRUD, Authentication System, External Service Integration,
+Database Migration, Performance Optimization, Breaking API Change,
+Refactor, Bug Fix, Greenfield Project, Multi-Module Library,
+Application Bootstrap, Infrastructure & Tooling.
+
+## Adversarial Review Loop
+
+When `review: true` is passed to `cleave_run`, each child's work is reviewed
+after execution using a tiered loop:
+
+```
+Execute (cheap) → Review (opus) → [pass? done : Fix (cheap) → Review (opus)]
+```
+
+### Severity Gating
+
+| Severity | Action | Max Fix Iterations |
+|----------|--------|--------------------|
+| Nits only | Accept | 0 |
+| Warnings | Fix then accept | 1 (configurable) |
+| Critical | Fix then escalate if unresolved | 2 (configurable) |
+| Critical + security | Immediate escalate | 0 |
+
+### Churn Detection
+
+Between review rounds, issue descriptions are normalized and compared.
+If >50% of current issues appeared in the previous round (configurable
+threshold), the loop bails — the fix agent is going in circles.
+
+### Review Configuration
+
+Pass to `cleave_run`:
+- `review: true` — enable the review loop
+- `review_max_warning_fixes: 1` — max fix iterations for warnings
+- `review_max_critical_fixes: 2` — max fix iterations for criticals
+- `review_churn_threshold: 0.5` — reappearance fraction to trigger bail
+
+### Review State
+
+After execution, each child's state includes:
+- `reviewIterations` — number of review rounds completed
+- `reviewHistory` — verdict + issue count per round
+- `reviewDecision` — `accepted`, `escalated`, or `no_review`
+- `reviewEscalationReason` — why the review loop gave up (if escalated)
+
+## Skill-Aware Dispatch
+
+Children automatically receive skill directives based on their file scope.
+Skills are matched via file pattern → skill mapping (e.g., `*.py` → python,
+`Containerfile` → oci) and can be overridden with task annotations.
+
+### Skill Annotations
+
+Task groups in `tasks.md` can declare skills via HTML comments:
+
+```markdown
+## 2. Container Build
+<!-- skills: oci, python -->
+- [ ] Write Containerfile
+```
+
+Annotations override auto-matching for that child.
+
+### Model Tier Routing
+
+Skills can hint at the model complexity needed. The resolution order is:
+1. Explicit annotation on the child plan (always respected)
+2. Local override (if `prefer_local: true` and Ollama available)
+3. Skill-based tier hint (highest `preferredTier` wins)
+4. Default: sonnet
+
+## Child Dispatch: RPC Mode (Phase 1)
+
+Since Phase 1 of cleave-process-tree, child processes are spawned in **RPC mode**
+(`--mode rpc --no-session`) by default. This replaces the legacy pipe mode for
+task execution while keeping pipe mode for adversarial review.
+
+### How It Works
+
+1. The dispatcher spawns the child with `--mode rpc --no-session`
+2. The task prompt is sent as a JSON command on stdin via `sendRpcCommand()`
+3. The child emits structured JSON events on stdout (one per line, JSONL framing)
+4. Events are parsed by `parseRpcEventStream()` and mapped to `RpcProgressUpdate`
+5. Progress updates drive the dashboard in real time (tool starts, lifecycle, errors)
+
+### Key Types
+
+- **`RpcChildEvent`** — Union of all structured events from the child (agent/turn/message
+  lifecycle, tool execution, compaction, retry, pipe_closed sentinel)
+- **`RpcProgressUpdate`** — Dashboard-friendly summary: `{ kind, summary, toolName? }`
+
+### The `useRpc` Flag
+
+`spawnChild()` accepts `useRpc?: boolean` (default: `true`).
+- **`true`** → RPC mode with structured event streaming and dashboard progress
+- **`false`** → Legacy pipe mode with debounced last-line output
+
+### Pipe-Mode Fallback
+
+Adversarial review (`review.ts`) continues to use **pipe mode**. RPC mode is used
+only for task execution dispatch. If RPC stdout breaks mid-stream, the parser emits
+a synthetic `pipe_closed` event for graceful degradation.
+
+### Task File Contract
+
+The task file format (`tasks.md`) is **unchanged** by RPC mode. OpenSpec task parsing,
+dependency markers, spec-domain annotations, and skill annotations all work exactly
+as before. RPC mode changes only the coordination channel between dispatcher and child,
+not the planning or task contract layer.
+
+### Phase 1 vs Phase 2
+
+| Capability | Phase 1 (current) | Phase 2 (future) |
+|------------|-------------------|-------------------|
+| Dispatch mode | RPC for tasks, pipe for review | RPC for both |
+| Event streaming | Structured JSON on stdout | Same |
+| Dashboard progress | Real-time tool/lifecycle updates | + resource metrics |
+| Graceful degradation | pipe_closed sentinel | + reconnect |
+| Process tree control | spawn + timeout | + pause/resume/cancel |
+
+## Architecture
+
+```
+extensions/cleave/
+  index.ts        — Extension entry: registers tools + /cleave command
+  assessment.ts   — Pattern library, complexity formula, fast-path triage
+  planner.ts      — LLM prompt builder, JSON plan parser, wave computation
+  openspec.ts     — OpenSpec tasks.md parser → ChildPlan[] conversion
+  dispatcher.ts   — Child process dispatch, AsyncSemaphore, wave execution
+  rpc-child.ts    — RPC child communication: JSON framing, event parsing, progress mapping
+  review.ts       — Adversarial review loop, severity gating, churn detection (pipe mode)
+  skills.ts       — Skill matching, resolution, model tier hints
+  conflicts.ts    — 4-step conflict detection (file overlap, decision
+                    contradiction, interface mismatch, assumption violation)
+  workspace.ts    — Workspace management under ~/.pi/cleave/
+  worktree.ts     — Git worktree create/merge/cleanup under ~/.pi/cleave/wt/
+  types.ts        — Shared type definitions (includes RpcChildEvent, RpcProgressUpdate)
+```
+
+### Coordination Channel
+
+The dispatcher uses RPC mode as the primary coordination channel between the parent
+cleave process and child agent processes. Communication is bidirectional:
+
+- **Parent → Child**: JSON commands on stdin (`sendRpcCommand`, `buildPromptCommand`)
+- **Child → Parent**: Structured JSONL events on stdout (`parseRpcEventStream`)
+- **Progress**: Events are mapped to `RpcProgressUpdate` via `mapEventToProgress()`
+  and forwarded to the dashboard via `emitCleaveChildProgress()`
+
+## Workspace Layout
+
+Workspaces and worktrees live outside the target repo:
+
+```
+~/.pi/cleave/
+  <slug>/              — Workspace per run
+    state.json         — Serialized CleaveState
+    0-task.md          — Child task files
+    1-task.md
+  wt/                  — Git worktrees
+    0-api-layer/       — Isolated working copy per child
+    1-db-layer/
+```
+
+## Execution Flow
+
+The `/cleave` command handles assessment and planning inline (or via LLM delegation).
+`CleaveState` tracks execution from dispatch onward:
+
+```
+/cleave command:  assess → [openspec | llm plan] → user confirm
+cleave_run tool:  DISPATCH → HARVEST → REUNIFY → COMPLETE | FAILED
+```
+
+The `assess`, `plan`, `confirm`, and `report` phases exist in `CleavePhase`
+but are not currently used in state transitions — they're reserved for
+future resume capability.
+
+On merge failure, branches are preserved for manual resolution.
+On success, worktrees and branches are cleaned up automatically.

package/skills/git/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: git
+description: Git conventions — conventional commits, semantic versioning, branch naming, tagging, changelogs, and release workflow. Use when committing, branching, tagging, or managing releases.
+---
+
+# Git Skill
+
+Conventions for git operations. Covers commit messages, versioning, branching, tagging, and changelogs.
+
+## Conventional Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages.
+
+### Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+| Type | When | Semver Impact |
+|------|------|---------------|
+| `feat` | New feature or capability | MINOR bump |
+| `fix` | Bug fix | PATCH bump |
+| `docs` | Documentation only | none |
+| `style` | Formatting, whitespace (no logic change) | none |
+| `refactor` | Code change that neither fixes nor adds | none |
+| `perf` | Performance improvement | none |
+| `test` | Adding or correcting tests | none |
+| `chore` | Build process, deps, tooling, version bumps | none |
+| `ci` | CI/CD configuration changes | none |
+| `revert` | Reverts a previous commit | varies |
+
+### Scope (optional)
+
+Parenthetical hint narrowing what changed. Free-form but consistent within a repo:
+
+```
+feat(auth): add OAuth2 PKCE flow
+fix(db): handle connection pool exhaustion
+test(api): add rate limit validation tests
+chore(deps): bump serde to 1.0.200
+```
+
+### Breaking Changes
+
+Mark with `!` after the type/scope, and explain in the footer:
+
+```
+feat(api)!: change response envelope format
+
+BREAKING CHANGE: Response wrapper changed from { data } to { result }.
+Clients must update to SDK >= 2.0.0.
+```
+
+### Commit Message Quality
+
+**Good** — explains the *why*, not just the *what*:
+```
+fix: normalize truncated hashes in message routing
+
+Short hashes from legacy clients caused lookup failures in the store.
+Now pads to full length before resolution.
+```
+
+**Bad** — restates the diff:
+```
+fix: change hash lookup code
+```
+
+### Validation Regex
+
+```
+^(feat|fix|docs|style|refactor|perf|test|chore|ci|revert)(\(.+\))?(!)?: .+
+```
+
+## Semantic Versioning
+
+Follow [SemVer 2.0.0](https://semver.org/):
+
+```
+vMAJOR.MINOR.PATCH
+```
+
+| Component | Increment When |
+|-----------|---------------|
+| **MAJOR** | Breaking API/protocol change |
+| **MINOR** | New feature, backward-compatible |
+| **PATCH** | Bug fix, backward-compatible |
+
+### Pre-1.0 Convention
+
+During `0.x.y` development:
+- MINOR bumps may include breaking changes
+- PATCH bumps are bug fixes
+- API stability is not guaranteed until `1.0.0`
+
+### Version Bump Commits
+
+Use `chore` type:
+```
+chore: bump version to 0.4.0
+```
+
+## Branch Naming
+
+```
+<type>/<short-description>
+```
+
+| Type | Purpose |
+|------|---------|
+| `feature/` | New functionality |
+| `fix/` | Bug fix |
+| `patch/` | Small targeted fix |
+| `chore/` | Tooling, deps, config |
+| `refactor/` | Code restructuring |
+| `perf/` | Performance work |
+| `breaking/` | Known breaking change |
+| `hotfix/` | Urgent production fix |
+
+**Examples:**
+```
+feature/oauth-integration
+fix/connection-pool-leak
+chore/bump-dependencies
+refactor/split-service-layer
+```
+
+**Main branch**: `main`. Tags and releases are cut from main only.
+
+## Tagging
+
+```bash
+git tag v0.4.0
+git push origin v0.4.0
+```
+
+- Always prefix with `v`: `v0.4.0`, not `0.4.0`
+- Tags should be on the `main` branch
+- Format: `vMAJOR.MINOR.PATCH`
+- Tag triggers release CI (build, publish, GitHub Release)
+
+### Release Flow
+
+```
+1. Complete work on feature/fix branch
+2. Merge to main via PR
+3. Update version in source files
+4. Commit: chore: bump version to X.Y.Z
+5. Update CHANGELOG.md
+6. Tag: git tag vX.Y.Z
+7. Push: git push origin main --tags
+8. CI builds and publishes
+```
+
+## Changelog
+
+Maintain `CHANGELOG.md` using [Keep a Changelog](https://keepachangelog.com/) format:
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+## [0.4.0] - 2026-02-03
+
+### Added
+- New feature description
+
+### Changed
+- Modified behavior description
+
+### Fixed
+- Bug fix description
+```
+
+### Section Order
+
+`Added` → `Changed` → `Deprecated` → `Removed` → `Fixed` → `Security`
+
+Only include sections that have entries. `[Unreleased]` collects changes since the last tag.
+
+## Quick Reference
+
+```bash
+# Feature branch
+git checkout -b feature/my-feature main
+git commit -m "feat(scope): add new capability"
+git push -u origin feature/my-feature
+
+# Fix branch
+git checkout -b fix/the-bug main
+git commit -m "fix: resolve crash on empty input"
+
+# Release (from main)
+git checkout main && git pull
+# bump version, update CHANGELOG
+git commit -m "chore: bump version to 0.5.0"
+git tag v0.5.0
+git push origin main --tags
+```
+
+## Pre-Publish Checklist
+
+Before tagging a release or merging work that will trigger a publish:
+
+1. **Verify manifest registration** — If new extensions, skills, prompts, or themes were added as files/directories, confirm they are listed in `package.json` under the appropriate `pi.*` array (`pi.extensions`, `pi.skills`, etc.). Autodiscovery is **bypassed** when a manifest field exists; unlisted entries won't load.
+2. **Verify imports and wiring** — New modules that are referenced by other modules (e.g. shared state, cross-extension calls) must actually be reachable at runtime. Check that import paths resolve and that the consuming code isn't silently swallowing missing-module errors.
+3. **Smoke-test the feature** — If the change adds user-visible behavior (UI, commands, startup effects), confirm it actually fires in a local run before publishing. A feature that loads but never activates is the same as a feature that was never shipped.
+
+See `_reference/ci-validation.md` for CI workflow templates that enforce these conventions.

package/skills/git/_reference/ci-validation.md

@@ -0,0 +1,204 @@
+# Git CI Validation Templates
+
+Workflow templates for enforcing git conventions in CI. Based on patterns from cleave.
+
+## Branch Name Validation
+
+```yaml
+validate-branch:
+  name: Validate Branch Name
+  runs-on: ubuntu-latest
+  if: github.event_name == 'pull_request'
+  steps:
+    - name: Check branch naming convention
+      run: |
+        BRANCH="${{ github.head_ref }}"
+        if [[ ! "$BRANCH" =~ ^(feature|fix|patch|chore|refactor|perf|breaking|hotfix)/.+ ]]; then
+          echo "ERROR: Branch name must follow convention: <type>/<description>"
+          echo "   Valid types: feature, fix, patch, chore, refactor, perf, breaking, hotfix"
+          echo "   Your branch: $BRANCH"
+          exit 1
+        fi
+        echo "Branch name follows convention: $BRANCH"
+```
+
+## Conventional Commit Validation
+
+```yaml
+validate-commits:
+  name: Validate Commit Messages
+  runs-on: ubuntu-latest
+  if: github.event_name == 'pull_request'
+  steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Validate conventional commits
+      run: |
+        COMMITS=$(git log --format=%s origin/main..HEAD)
+
+        PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|ci|revert)(\(.+\))?(!)?: .+"
+
+        FAILED=0
+        while IFS= read -r commit; do
+          if [[ ! "$commit" =~ $PATTERN ]]; then
+            echo "FAIL: $commit"
+            FAILED=1
+          else
+            echo "OK: $commit"
+          fi
+        done <<< "$COMMITS"
+
+        if [ $FAILED -eq 1 ]; then
+          echo ""
+          echo "Commit messages must follow Conventional Commits:"
+          echo "  <type>(<scope>): <description>"
+          echo ""
+          echo "Types: feat, fix, docs, style, refactor, perf, test, chore, ci, revert"
+          exit 1
+        fi
+```
+
+## Tag Validation (Release Workflow)
+
+```yaml
+name: Release
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  validate-tag:
+    name: Validate Tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag is on main branch
+        run: |
+          TAG_COMMIT=$(git rev-list -n 1 ${{ github.ref }})
+          MAIN_COMMITS=$(git rev-list origin/main)
+
+          if ! echo "$MAIN_COMMITS" | grep -q "$TAG_COMMIT"; then
+            echo "ERROR: Tag ${{ github.ref_name }} is not on main branch"
+            echo "   Tags must only be created from main branch"
+            exit 1
+          fi
+          echo "Tag ${{ github.ref_name }} is on main branch"
+
+      - name: Validate semantic version format
+        run: |
+          if [[ ! "${{ github.ref_name }}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "ERROR: Tag must follow semantic versioning: vMAJOR.MINOR.PATCH"
+            echo "   Got: ${{ github.ref_name }}"
+            exit 1
+          fi
+          echo "Valid semantic version: ${{ github.ref_name }}"
+```
+
+## Push Triggers with Branch Naming
+
+Use branch patterns in push triggers to only run CI on convention-following branches:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+      - 'feature/**'
+      - 'fix/**'
+      - 'patch/**'
+      - 'chore/**'
+      - 'refactor/**'
+      - 'perf/**'
+      - 'breaking/**'
+  pull_request:
+    branches:
+      - main
+```
+
+## Combined CI Template
+
+Full CI workflow with branch, commit, lint, and test validation:
+
+```yaml
+name: CI
+on:
+  push:
+    branches:
+      - main
+      - 'feature/**'
+      - 'fix/**'
+      - 'chore/**'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  validate-branch:
+    name: Validate Branch Name
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Check branch naming convention
+        run: |
+          BRANCH="${{ github.head_ref }}"
+          if [[ ! "$BRANCH" =~ ^(feature|fix|patch|chore|refactor|perf|breaking|hotfix)/.+ ]]; then
+            echo "ERROR: Branch name must follow convention: <type>/<description>"
+            exit 1
+          fi
+
+  validate-commits:
+    name: Validate Commit Messages
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Validate conventional commits
+        run: |
+          PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|ci|revert)(\(.+\))?(!)?: .+"
+          FAILED=0
+          while IFS= read -r commit; do
+            [[ "$commit" =~ $PATTERN ]] || { echo "FAIL: $commit"; FAILED=1; }
+          done < <(git log --format=%s origin/main..HEAD)
+          [ $FAILED -eq 0 ] || exit 1
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: [validate-branch, validate-commits]
+    if: always() && !failure()
+    steps:
+      - uses: actions/checkout@v4
+      # ... language-specific test steps
+```
+
+## Pre-commit Hook (Local Enforcement)
+
+Optional local validation via git hooks. Add to `.git/hooks/commit-msg`:
+
+```bash
+#!/usr/bin/env bash
+# Validate conventional commit format
+PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|ci|revert)(\(.+\))?(!)?: .+"
+MSG=$(head -1 "$1")
+
+if [[ ! "$MSG" =~ $PATTERN ]]; then
+    echo "ERROR: Commit message does not follow Conventional Commits"
+    echo "  Expected: <type>(<scope>): <description>"
+    echo "  Got:      $MSG"
+    echo ""
+    echo "  Types: feat, fix, docs, style, refactor, perf, test, chore, ci, revert"
+    exit 1
+fi
+```
+
+Make executable: `chmod +x .git/hooks/commit-msg`