@meyverick/agentic 5.0.2 → 5.1.0

package/skills/okf-docs/scripts/{validate-frontmatter.mjs → validate-frontmatter.ts}

@@ -1,58 +1,91 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 /**
- * validate-frontmatter.mjs — OKF v0.2 frontmatter gate
- * Usage: node validate-frontmatter.mjs <document.md>
+ * validate-frontmatter.ts — OKF v0.2 frontmatter gate
+ * Usage: bun validate-frontmatter.ts <document.md>
  * Output: unified JSON envelope {target, pass, checks:[{id,status,detail}], summary}
  *
  * Checks: required keys (type/generated.by/at) · ISO 8601 formats · actor
  * convention values · status enum · stale_after chronology.
  */
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync } from 'node:fs';
+
+type CheckStatus = 'PASS' | 'FAIL' | 'WARN' | 'SKIP';
+
+interface CheckEntry {
+  id: string;
+  status: CheckStatus;
+  detail: string;
+}
+
+interface ValidationSummary {
+  total: number;
+  pass: number;
+  fail: number;
+  warn: number;
+  skip: number;
+}
+
+interface ValidationReport {
+  target: string;
+  pass: boolean;
+  checks: CheckEntry[];
+  summary: ValidationSummary;
+}
 
 const docPath = process.argv[2];
 
-if (!docPath) {
-  console.error(JSON.stringify({ error: 'Usage: node validate-frontmatter.mjs <document.md>' }));
+if (!docPath || docPath === '-h' || docPath === '--help') {
+  if (docPath === '-h' || docPath === '--help') {
+    console.log('Usage: bun validate-frontmatter.ts <document.md>');
+    process.exit(0);
+  }
+  console.error(JSON.stringify({ error: 'Usage: bun validate-frontmatter.ts <document.md>' }));
   process.exit(2);
 }
 
 if (!existsSync(docPath)) {
-  console.log(JSON.stringify({
+  const report: ValidationReport = {
     target: docPath,
     pass: false,
     checks: [{ id: 'okf.file', status: 'FAIL', detail: 'Document not found' }],
     summary: { total: 1, pass: 0, fail: 1, warn: 0, skip: 0 }
-  }));
+  };
+  console.log(JSON.stringify(report));
   process.exit(1);
 }
 
 const content = readFileSync(docPath, 'utf-8');
-const checks = [];
+const checks: CheckEntry[] = [];
 
-const add = (id, ok, detail) => checks.push({ id, status: ok ? 'PASS' : 'FAIL', detail });
-const warn = (id, detail) => checks.push({ id, status: 'WARN', detail });
+const add = (id: string, ok: boolean, detail: string): void => {
+  checks.push({ id, status: ok ? 'PASS' : 'FAIL', detail });
+};
+const warn = (id: string, detail: string): void => {
+  checks.push({ id, status: 'WARN', detail });
+};
 
 // Extract frontmatter
 const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
 if (!fmMatch) {
-  console.log(JSON.stringify({
+  const report: ValidationReport = {
     target: docPath,
     pass: false,
     checks: [{ id: 'okf.frontmatter', status: 'FAIL', detail: 'No frontmatter block found' }],
     summary: { total: 1, pass: 0, fail: 1, warn: 0, skip: 0 }
-  }));
+  };
+  console.log(JSON.stringify(report));
   process.exit(1);
 }
 add('okf.frontmatter', true, 'Frontmatter block present');
 
 // Parse simple YAML subset (top-level + one nested level for generated)
 const fm = fmMatch[1];
-function get(key) {
+function get(key: string): string | null {
   const m = fm.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
   return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
 }
-function getNested(parent, key) {
+function getNested(parent: string, key: string): string | null {
   const m = fm.match(new RegExp(`^${parent}:\\s*\\{\\s*([^}]*)\\}`, 'm'));
   if (!m) return null;
   const inner = m[1].match(new RegExp(`${key}:\\s*([^,}]+)`));
@@ -69,14 +102,22 @@ const at = getNested('generated', 'at');
 add('okf.generated-by', !!by, by ? `generated.by = ${by}` : "Missing required 'generated.by'");
 
 const actorRe = /^([a-z0-9][a-z0-9-]*\/\d+(\.\d+)*|human:[a-z0-9-]+|process:[a-z0-9-]+)$/;
-add('okf.actor-convention',
+add(
+  'okf.actor-convention',
   !!by && actorRe.test(by),
-  by ? (actorRe.test(by) ? `Actor '${by}' matches convention` : `Actor '${by}' violates convention (<producer>/<version> | human:<id> | process:<id>)`) : 'No actor to check');
+  by
+    ? actorRe.test(by)
+      ? `Actor '${by}' matches convention`
+      : `Actor '${by}' violates convention (<producer>/<version> | human:<id> | process:<id>)`
+    : 'No actor to check'
+);
 
 const isoRe = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?Z)?$/;
-add('okf.generated-at-format',
+add(
+  'okf.generated-at-format',
   !!at && isoRe.test(at),
-  at ? (isoRe.test(at) ? `generated.at = ${at}` : `'${at}' is not ISO 8601`) : "Missing required 'generated.at'");
+  at ? (isoRe.test(at) ? `generated.at = ${at}` : `'${at}' is not ISO 8601`) : "Missing required 'generated.at'"
+);
 
 // sources (WARN if missing — recommended not mandatory)
 const hasSources = /^sources:/m.test(fm);
@@ -87,13 +128,10 @@ const status = get('status');
 if (!status) {
   warn('okf.status', "Missing 'status' (draft | stable | deprecated)");
 } else if (!['draft', 'stable', 'deprecated'].includes(status)) {
-  failStatus(status);
+  add('okf.status', false, `Invalid status '${status}' — must be draft | stable | deprecated`);
 } else {
   add('okf.status', true, `status = ${status}`);
 }
-function failStatus(value) {
-  add('okf.status', false, `Invalid status '${value}' — must be draft | stable | deprecated`);
-}
 
 // stale_after chronology vs generated.at
 const stale = get('stale_after');
@@ -102,8 +140,11 @@ if (stale) {
     add('okf.stale-after', false, `stale_after '${stale}' is not YYYY-MM-DD`);
   } else if (at) {
     const genDay = at.slice(0, 10);
-    add('okf.stale-after', stale >= genDay,
-      stale >= genDay ? `stale_after ${stale} ≥ generated ${genDay}` : `stale_after ${stale} predates generation ${genDay}`);
+    add(
+      'okf.stale-after',
+      stale >= genDay,
+      stale >= genDay ? `stale_after ${stale} ≥ generated ${genDay}` : `stale_after ${stale} predates generation ${genDay}`
+    );
   } else {
     add('okf.stale-after', true, `stale_after = ${stale} (no generated.at to compare)`);
   }
@@ -112,19 +153,19 @@ if (stale) {
 }
 
 // Unified envelope
-const fails = checks.filter(c => c.status === 'FAIL').length;
-console.log(JSON.stringify({
+const fails = checks.filter((c) => c.status === 'FAIL').length;
+const report: ValidationReport = {
   target: docPath,
   pass: fails === 0,
   checks,
   summary: {
     total: checks.length,
-    pass: checks.filter(c => c.status === 'PASS').length,
+    pass: checks.filter((c) => c.status === 'PASS').length,
     fail: fails,
-    warn: checks.filter(c => c.status === 'WARN').length,
-    skip: checks.filter(c => c.status === 'SKIP').length
+    warn: checks.filter((c) => c.status === 'WARN').length,
+    skip: checks.filter((c) => c.status === 'SKIP').length
   }
-}));
+};
 
+console.log(JSON.stringify(report));
 process.exit(fails > 0 ? 1 : 0);
-

package/skills/openspec-learn/references/evaluation-methodology.md

@@ -10,13 +10,13 @@ Before applying improvements:
 
 1. **Structural validation**:
    ```bash
-   project/skills/create-skill/scripts/validate-structure.mjs <skill-dir>
+   bun project/skills/create-skill/scripts/validate-structure.ts <skill-dir>
    ```
    Extract: pass/fail, errors, warnings
 
 2. **Antipattern audit**:
    ```bash
-   project/skills/create-skill/scripts/audit-antipatterns.mjs <skill-dir>
+   bun project/skills/create-skill/scripts/audit-antipatterns.ts <skill-dir>
    ```
    Extract: pass/fail, violation count, violations
 

package/skills/openspec-pi-apply/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: openspec-pi-apply
+description: >
+  Delegate OpenSpec change task implementation to a headless pi worker agent via JSON-RPC.
+  Use when the user wants to apply an OpenSpec change using pi as a worker engine,
+  saying "pi apply", "opsx pi apply", or "apply change with pi".
+  Do NOT use when applying changes directly without pi (use openspec-apply-change),
+  or when proposing/planning changes (use openspec-propose).
+allowed-tools: Bash(bun:*), Bash(openspec:*), Read, Grep
+license: MIT
+compatibility: Requires pi CLI, bun, and openspec CLI.
+metadata:
+  author: agentic
+  version: "1.0.0"
+positive_triggers:
+  - "apply change using pi"
+  - "pi apply change"
+  - "openspec pi apply"
+  - "delegate task implementation to pi"
+anti_triggers:
+  - "implement change directly yourself"
+  - "apply change without pi"
+  - "openspec apply change"
+  - "propose a new change"
+---
+
+# OpenSpec Pi Apply Workflow
+
+Delegate task execution for an active OpenSpec change to a headless `pi` worker engine communicating over JSON-RPC. Antigravity acts as architectural supervisor, triaging worker questions and enforcing verification gates.
+
+## Contrast Matrix
+
+| Dimension | Direct Supervisor (`openspec-apply-change`) | Headless Pi Worker (`openspec-pi-apply`) | Why Different |
+| :--- | :--- | :--- | :--- |
+| **Execution** | Supervisor edits project files directly in turn context | Child process worker (`pi -a -c --mode rpc`) executes edits | Prevents supervisor context bloat & high turn latency |
+| **Supervision** | Self-directed implementation | Supervisor monitors tool events & validates completion gates | Decouples code authoring from architectural oversight |
+| **Clarifications** | Halts and asks human immediately | Supervisor triages autonomously against change artifacts | Eliminates unnecessary user interruptions for specified details |
+
+## Anti-Examples (What NOT to do)
+
+- **Do NOT edit project files directly** in this workflow. Task implementation is delegated to the worker process via `.agents/skills/openspec-pi-apply/scripts/pi-rpc-apply.ts`.
+- **Do NOT pipe raw `pi` stdout directly** into conversational logs. Always use the bridge runner to filter high-frequency token deltas and prevent buffer stalls.
+- **Do NOT guess unstated requirements** when the worker pauses for clarification. If an answer cannot be grounded in `specs/`, `design.md`, or `AGENTS.md`, escalate to the user.
+- **Do NOT mark the change complete** based solely on worker claims. Verify that `openspec instructions apply --change <name> --json` confirms 0 remaining tasks.
+
+## Workflow — 5 Steps
+
+### Step 1: Pre-Flight & Change Discovery
+
+1. Identify target change name (from user input or active changes):
+   ```bash
+   openspec list --json
+   ```
+2. Verify that planning artifacts are complete:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Ensure `isPlanningComplete: true`. If planning is incomplete, advise completing artifacts with `/openspec-continue-change` first.
+
+### Step 2: Spawn Pi Worker Engine
+
+Run the bridge runner from the workspace root:
+```bash
+bun run .agents/skills/openspec-pi-apply/scripts/pi-rpc-apply.ts --change "<name>"
+```
+
+*(For low-level RPC framing specifications, see [references/rpc-protocol.md](references/rpc-protocol.md).)*
+
+The runner:
+- Resolves workspace root and spawns `pi -a -c --mode rpc`
+- Transmits `/skill:openspec-apply-change <name>` over stdin
+- Filters raw token noise, emitting clean progress logs (`⚙ [pi:tool] Invoking: ...`)
+- Detects `agent_settled` upon turn completion
+
+### Step 3: Triage Worker Settlement State
+
+Evaluate the runner's exit status:
+
+#### Case A: `[STATUS] COMPLETED`
+All tasks in `tasks.md` are marked complete (`remaining: 0`).
+- Proceed directly to **Step 5: Completion Verification**.
+
+#### Case B: `[STATUS] PAUSED_FOR_CLARIFICATION`
+Worker paused with remaining tasks or posted a question before finishing.
+1. Read the worker's question from the runner log.
+2. Cross-reference the question against:
+   - `openspec/changes/<name>/specs/**/*.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/proposal.md`
+   - `AGENTS.md`
+3. **Autonomous Resolution**:
+   - If the answer is documented in specifications or conventions, formulate the concise clarification grounded in the artifacts and resume worker execution:
+     ```bash
+     bun run .agents/skills/openspec-pi-apply/scripts/pi-rpc-apply.ts --change "<name>" --reply "<clarification-answer>"
+     ```
+   - Return to **Step 3** to inspect the next settlement state.
+4. **Human Escalation**:
+   - If the question involves domain ambiguity, product preference, or missing credentials not covered by specs:
+   - Ask the user directly.
+   - Once the user answers, resume worker execution:
+     ```bash
+     bun run .agents/skills/openspec-pi-apply/scripts/pi-rpc-apply.ts --change "<name>" --reply "<user-answer>"
+     ```
+   - Return to **Step 3**.
+
+#### Case C: `[STATUS] FAILED`
+Worker exited with an error or timed out.
+- Inspect stderr and diagnostic logs.
+- Report failure details to user and pause.
+
+### Step 4: Resume Iteration Loop
+
+Repeat Step 3 until `[STATUS] COMPLETED` is reached or user intervention is requested.
+
+### Step 5: Completion Verification
+
+1. Run OpenSpec apply inspection:
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+2. Confirm `progress.remaining === 0`.
+3. Run project verification suite (linters, typecheck, or tests) to confirm workspace health:
+   ```bash
+   openspec validate --change "<name>"
+   ```
+4. Present final implementation summary:
+   - Change name and status
+   - Completed task summary
+   - Prompt user to archive: "All tasks complete! You can archive this change with `/openspec-archive-change <name>`."

package/skills/openspec-pi-apply/references/rpc-protocol.md

@@ -0,0 +1,43 @@
+# Pi JSON-RPC Protocol Reference (Level 2)
+
+This reference outlines the JSON-RPC framing and event specifications used by `scripts/pi-rpc-apply.ts` to control `pi -a -c --mode rpc`.
+
+## Process Invocation Flags
+
+- `-a` (`--approve`): Auto-approves operations within the project scope, preventing interactive confirmation prompts.
+- `-c` (`--continue`): Maintains conversational session memory and context across turns and process restarts.
+- `--mode rpc`: Activates bidirectional JSON-RPC 2.0 streaming over standard I/O.
+
+## Standard Input Commands
+
+### Initial Apply Prompt
+```json
+{
+  "id": "prompt-1",
+  "type": "prompt",
+  "message": "/skill:openspec-apply-change <change-name>"
+}
+```
+*Note*: `pi` natively expands `/skill:name` commands prior to session execution.
+
+### Clarification Reply
+```json
+{
+  "id": "prompt-reply",
+  "type": "prompt",
+  "message": "<clarification-answer>"
+}
+```
+
+## Standard Output Stream & Framing
+
+Records are strictly formatted as single-line JSON objects separated by LF (`\n`):
+
+1. **`message_update` (suppressed by runner)**:
+   Emits streaming deltas (`text_delta`, `thinking_delta`). Filtered out to avoid context flooding.
+2. **`toolcall_start` / `toolcall_end`**:
+   Emitted when `pi` executes workspace tools (`read_file`, `write_to_file`, `run_command`).
+3. **`message_end`**:
+   Emitted when the assistant finishes a response turn. Captured to extract any worker questions.
+4. **`agent_settled`**:
+   Signals that the agent has settled and has no remaining automatic work.