@abelxiaoxing/cadence 1.0.0

package/prompts/abel-init.md

@@ -0,0 +1,42 @@
+---
+description: Initialize OpenSpec and AGENTS indexes for an Abel workflow project
+argument-hint: "[project-path]"
+---
+
+Load the bundled `abel-workflow` Skill before inspecting or modifying OpenSpec or AGENTS files.
+If that core Skill is unavailable, stop before any write and report an executable package-resource restore or reinstall command.
+Read the complete value inside `<abel-request>` without a second whitespace-tokenization pass.
+
+<abel-request>
+$ARGUMENTS
+</abel-request>
+
+The request is an optional project path; when absent, target the current working directory.
+Resolve that root before action and preserve unrelated files, all human-authored AGENTS content, baseline dirty state, and nested repository boundaries.
+Never overwrite or cross a nested repository boundary merely because it is below the selected root.
+
+## Prerequisites
+
+Select Bun when it is usable; otherwise select npm.
+Use that single JavaScript toolchain for the whole run.
+If neither is usable, stop with the original probe errors and executable remediation.
+
+Discover the bundled `context7-auto-research` and `grok-search` Skills.
+Record each resolved discovery path when present.
+When either is missing, report an actionable package-resource restore or reinstall command, continue OpenSpec initialization and AGENTS repair, and mark the final environment as not fully ready.
+A missing research Skill does not prevent OpenSpec initialization or AGENTS repair.
+The absence of `git-commit`, external `dev-browser`, or a dedicated `time` Skill does not affect Init readiness; do not check them as Init prerequisites.
+
+Probe OpenSpec and all CLI capabilities required by the shared workflow.
+If OpenSpec is absent, install `@fission-ai/openspec@latest` globally with the selected toolchain (`bun add --global @fission-ai/openspec@latest` or `npm install --global @fission-ai/openspec@latest`), then recheck every required capability.
+If installation or the recheck fails, stop, preserve the original error, and report the exact executable remediation command for the selected toolchain.
+
+## Initialization
+
+Initialize or safely update OpenSpec without `--force` or another destructive force option.
+Resolve and validate the selected schema and its templates before reporting success.
+Create or repair only the verified managed blocks of appropriate root and nested AGENTS indexes, preserving all human-authored text and unrelated content.
+You must not edit `openspec/AGENTS.md`.
+
+Report the resolved project root, selected toolchain, OpenSpec capability results, schema/template validation, AGENTS repairs, research-Skill discovery paths or remediation, and final readiness.
+A missing research Skill makes the environment not fully ready even when OpenSpec and AGENTS repair completed.

package/skills/_shared/http-client.mjs

@@ -0,0 +1,89 @@
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+const DEFAULT_RETRY_DELAYS_MS = [1000, 2000];
+const MAX_RETRY_DELAY_MS = 10_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_ATTEMPTS = 3;
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function retryAfterMs(value, now = Date.now()) {
+  if (!value) return null;
+  if (/^\d+(?:\.\d+)?$/.test(value.trim())) {
+    return Math.min(Math.max(Number(value) * 1000, 0), MAX_RETRY_DELAY_MS);
+  }
+  const date = Date.parse(value);
+  if (Number.isNaN(date)) return null;
+  return Math.min(Math.max(date - now, 0), MAX_RETRY_DELAY_MS);
+}
+
+function sanitizedError({ operation, url, status, cause }) {
+  const endpoint = (() => {
+    try {
+      const parsed = new URL(url);
+      return `${parsed.origin}${parsed.pathname}`;
+    } catch {
+      return "invalid endpoint";
+    }
+  })();
+  const statusText = status ? ` (HTTP ${status})` : "";
+  const causeText = cause instanceof SyntaxError ? ": malformed JSON" : "";
+  return new Error(
+    `${operation} failed at ${endpoint}${statusText}${causeText}`,
+  );
+}
+
+export async function requestJson({
+  operation,
+  url,
+  method = "GET",
+  headers = {},
+  body,
+  fetchImpl = fetch,
+  sleep = defaultSleep,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(
+      () => controller.abort(new Error("request timeout")),
+      timeoutMs,
+    );
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: controller.signal,
+      });
+    } catch (cause) {
+      clearTimeout(timeout);
+      if (attempt + 1 >= MAX_ATTEMPTS) {
+        throw sanitizedError({ operation, url, cause });
+      }
+      await sleep(DEFAULT_RETRY_DELAYS_MS[attempt]);
+      continue;
+    }
+    clearTimeout(timeout);
+
+    if (!response.ok) {
+      if (
+        !RETRYABLE_STATUS.has(response.status) ||
+        attempt + 1 >= MAX_ATTEMPTS
+      ) {
+        throw sanitizedError({ operation, url, status: response.status });
+      }
+      const retryAfter = retryAfterMs(response.headers.get("retry-after"));
+      await sleep(retryAfter ?? DEFAULT_RETRY_DELAYS_MS[attempt]);
+      continue;
+    }
+
+    try {
+      return await response.json();
+    } catch (cause) {
+      throw sanitizedError({ operation, url, status: response.status, cause });
+    }
+  }
+
+  throw sanitizedError({ operation, url });
+}

package/skills/_shared/load-config.mjs

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+export function parseEnvFile(content) {
+  const values = {};
+  const lines = content
+    .replaceAll("\r\n", "\n")
+    .replaceAll("\r", "\n")
+    .split("\n");
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const separator = line.indexOf("=");
+    if (separator <= 0)
+      throw new Error(`Invalid configuration syntax at line ${index + 1}`);
+
+    const name = line.slice(0, separator).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      throw new Error(`Invalid configuration name at line ${index + 1}`);
+    }
+
+    let value = line.slice(separator + 1).trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+      if (value.at(-1) !== quote) {
+        throw new Error(
+          `Unterminated quoted configuration value at line ${index + 1}`,
+        );
+      }
+      value = value.slice(1, -1);
+    }
+    values[name] = value;
+  }
+
+  return values;
+}
+
+export function loadConfig({ cwd, home, required = [] }) {
+  const projectPath = path.join(cwd, ".pi", "cadence", ".env");
+  const userPath = path.join(home, ".pi", "agent", "cadence", ".env");
+  const selectedPath = existsSync(projectPath)
+    ? projectPath
+    : existsSync(userPath)
+      ? userPath
+      : null;
+
+  if (!selectedPath) {
+    throw new Error(
+      `No cadence configuration file found; create ${projectPath} or ${userPath}`,
+    );
+  }
+
+  const values = parseEnvFile(readFileSync(selectedPath, "utf8"));
+  const missing = required.filter((name) => !values[name]);
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required configuration names in ${selectedPath}: ${missing.join(", ")}`,
+    );
+  }
+
+  return { path: selectedPath, values };
+}

package/skills/abel-workflow/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: abel-workflow
+description: Shared contract for the Abel Init, Design, Implement, and Diagnose workflow stages
+---
+
+# Abel workflow
+
+This Skill is the authoritative shared contract for `/abel-init`, `/abel-design`, `/abel-implement`, and `/abel-diagnose`.
+Load it before executing any stage; the package remains usable when no user-global `AGENTS.md` contains Abel-specific instructions.
+Stage prompts own their input contract and stage-specific procedure, while rules shared across stages live here.
+
+## Gates and trusted delivery
+
+Gate A approves the complete product behavior contract.
+Gate B separately approves the complete technical implementation contract.
+Neither Gate authorizes a tool permission; they do not grant permission authorization, identity signing, or approval to bypass repository controls.
+
+Design and Implement may run in different contexts.
+A handoff is trusted only when versioned Gate receipts bind the same change and schema, every covered artifact's normalized relative path and SHA-256 hash is valid, the Gate A receipt hash is valid, OpenSpec strict validation passes, and the artifact graph is complete.
+Normalize only the tracked task file's completed Markdown checkboxes before hashing; reject absolute paths, `..`, path escapes, and symbolic-link escapes.
+A missing receipt, invalid hash, or inconsistent artifact returns the change to Design rather than recreating a decision in Implement.
+
+Every approved behavior must retain a stable trace from Requirement to Scenario to Verification to Task.
+Every task must state exactly one executable verification type, its Red command and expected target failure, Green behavior, affected suite, target files, and AGENTS impact.
+
+## Verification discipline
+
+Before writes, record target, affected-suite, and full-suite baselines with commands, exit codes, and normalized failure identities.
+A pre-existing baseline failure is separate evidence and never satisfies a target Red.
+
+Use Red-Green-Refactor for code, tests, and executable static contracts:
+
+1. **Red:** add only the approved failing verification and run the exact command; it must fail for the specified target defect.
+2. **Green:** implement the minimum approved change and run the target verification after every code or test edit.
+3. **Refactor:** improve only in-scope structure or readability while target verification stays green; then run the affected suite.
+
+If Red passes, uses an invalid command, or fails for another reason, stop and return to Design rather than substituting an improvised verification.
+
+### Implement affected-suite repair boundary
+
+This boundary applies only to Implement.
+For each task, its exact affected-suite commands define a dynamic cross-module repair boundary.
+Keep each command, exit code, normalized failure identity, reproducibility result, attribution, and root-cause evidence in the implementation context and final report, not in a state file.
+Every reproducible pre-existing failure enters the current task separately from the task Red and requires a verified root cause plus minimum repair, including a failure outside the original module or target-file list.
+Only an attributed failure inside this boundary authorizes an additional repair path.
+Classify a failure newly visible on a later affected run as `pre-existing`, `introduced`, or `unresolved`; include and minimally repair a pre-existing failure, repair or revert an introduced failure, and block completion when attribution is unresolved.
+An environmental, transient, external-service-dependent, or non-reproducible failure blocks completion with an executable recovery condition and never authorizes a speculative product edit or repair.
+If an included repair requires new behavior, policy, dependency, architecture, irreversibility, or another substantive decision, return the expanded requirement to Design.
+A full-suite-only baseline failure outside the affected commands remains outside automatic scope.
+Finish only when all target and affected verifications are green and the full suite has no new failure relative to baseline.
+Do not archive, publish, or commit implicitly.
+
+## AGENTS indexes
+
+Treat AGENTS indexes as verified routers, not architecture documents or session ledgers.
+Preserve all human-authored text and edit only the managed region delimited by `<!-- ABEL:AGENTS-INDEX:START -->` and `<!-- ABEL:AGENTS-INDEX:END -->`.
+Update an index only at a stable task or diagnosis checkpoint when module routes, entrypoints, public/configuration surfaces, commands, ownership, data-flow boundaries, or indexed invariants changed.
+Otherwise record `none` with evidence.
+Never persist runtime user or session state, dirty-state ledgers, timestamps, or approval status in an index.
+
+Before an index write, inspect the complete task diff and compare actual impact with the approved contract.
+Stop and return to Design if the diff exposes unapproved behavior or architecture.
+Validate paths, commands, removed references, managed-marker uniqueness, and root-to-nested routes after every index update.
+
+## Parent and subagent authority
+
+The parent agent owns Gate handling, patches, repository writes, AGENTS index updates, and task completion state.
+A subagent receives bounded relevant index context and may perform only the delegated read-only exploration or review.
+A subagent must not approve a Gate, apply a patch, edit an index, or advance a task checkbox.
+
+## External browser E2E
+
+`dev-browser` is external and is required only when an approved task verification contract explicitly names browser E2E.
+Its absence does not block another task or workflow stage whose approved contract has no browser E2E step.
+When an approved browser-E2E task requires `dev-browser` and it is missing or unavailable, stop that task, report the missing capability and an executable remediation, and do not report the verification as passing.
+
+## Stage responsibilities
+
+- **Init:** initialize or safely repair OpenSpec and verified AGENTS routes without destructive overwrite.
+- **Design:** resolve blocking decisions, obtain Gate A and Gate B, write only OpenSpec change artifacts after Gate A, and deliver a strictly validated traceable change.
+- **Implement:** validate the trusted delivery in a fresh context, execute task contracts in tracked order through Red-Green-Refactor, and maintain indexes at stable checkpoints.
+- **Diagnose:** reproduce existing bugs, falsify candidate causes, establish a failing regression, and make the minimum repair; new behavior or substantive architecture returns to Design.

package/skills/context7-auto-research/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: context7-auto-research
+description: Fetch current official library documentation from Context7 when library or framework APIs are needed
+---
+
+# Context7 auto research
+
+Use this Skill proactively for current library/framework documentation, version-specific APIs, setup, migration, or code examples.
+Run its CLI from this Skill directory.
+
+## Commands
+
+```bash
+node context7.mjs search <library-name> <query|->
+node context7.mjs context <library-id> <query|->
+```
+
+Use a lone `-` to pass the complete UTF-8 query through stdin without shell tokenization:
+
+```bash
+node context7.mjs search react - <<'QUERY'
+<complete user question>
+QUERY
+```
+
+Choose an exact official library match first, then version fit and trust score.
+Fetch focused context for the selected library ID and answer from the returned current documentation.
+Treat a non-zero exit, invalid shape, or empty useful result as a failed lookup; never present it as successful research.
+
+The CLI selects the project `.pi/cadence/.env` as a whole file when present, otherwise `~/.pi/agent/cadence/.env`.
+It does not merge files, read ambient API configuration, or read `.env` beside the installed package.
+`CONTEXT7_API_KEY` may be empty; `CONTEXT7_API_URL` defaults to `https://context7.com/api/v2`.

package/skills/context7-auto-research/context7.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { homedir } from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { requestJson } from "../_shared/http-client.mjs";
+import { loadConfig } from "../_shared/load-config.mjs";
+
+const DEFAULT_API_URL = "https://context7.com/api/v2";
+
+export function loadContext7Config({ cwd, home }) {
+  const selected = loadConfig({ cwd, home });
+  return {
+    path: selected.path,
+    apiUrl: selected.values.CONTEXT7_API_URL || DEFAULT_API_URL,
+    apiKey: selected.values.CONTEXT7_API_KEY ?? "",
+  };
+}
+
+async function resolveQuery(queryArgs, readStdin) {
+  if (queryArgs.length === 1 && queryArgs[0] === "-") {
+    const query = (await readStdin()).trim();
+    if (!query) throw new Error("Stdin query input was empty");
+    return query;
+  }
+  if (queryArgs.includes("-")) {
+    throw new Error("When using -, it must be the only query argument");
+  }
+  const query = queryArgs.join(" ").trim();
+  if (!query) throw new Error("A non-empty query is required");
+  return query;
+}
+
+function buildHeaders(apiKey) {
+  return {
+    Accept: "application/json",
+    "User-Agent": "cadence-context7/0.0.0",
+    ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+  };
+}
+
+function validateResult(command, value) {
+  if (command === "search" && value && Array.isArray(value.results))
+    return value;
+  if (command === "context") {
+    if (Array.isArray(value)) return value;
+    if (
+      value &&
+      typeof value === "object" &&
+      (Array.isArray(value.codeSnippets) || Array.isArray(value.infoSnippets))
+    ) {
+      return value;
+    }
+  }
+  throw new Error(`Invalid Context7 ${command} response shape`);
+}
+
+export async function runContext7({
+  argv,
+  cwd,
+  home,
+  fetchImpl = fetch,
+  sleep,
+  readStdin,
+}) {
+  const [command, operand, ...queryArgs] = argv;
+  if (command !== "search" && command !== "context") {
+    throw new Error("Unknown command; expected search or context");
+  }
+  if (!operand) {
+    throw new Error(
+      `${command} requires a library ${command === "search" ? "name" : "id"}`,
+    );
+  }
+
+  const query = await resolveQuery(queryArgs, readStdin);
+  const config = loadContext7Config({ cwd, home });
+  const base = config.apiUrl.replace(/\/+$/, "");
+  const endpoint = new URL(
+    `${base}/${command === "search" ? "libs/search" : "context"}`,
+  );
+  endpoint.searchParams.set(
+    command === "search" ? "libraryName" : "libraryId",
+    operand,
+  );
+  endpoint.searchParams.set("query", query);
+  if (command === "context") endpoint.searchParams.set("type", "json");
+
+  const result = await requestJson({
+    operation: `Context7 ${command}`,
+    url: endpoint,
+    headers: buildHeaders(config.apiKey),
+    fetchImpl,
+    sleep,
+  });
+  return validateResult(command, result);
+}
+
+async function readAllStdin() {
+  process.stdin.setEncoding("utf8");
+  let content = "";
+  for await (const chunk of process.stdin) content += chunk;
+  return content;
+}
+
+function printUsage() {
+  process.stderr.write(
+    "Usage:\n  node context7.mjs search <library-name> <query|->\n  node context7.mjs context <library-id> <query|->\n",
+  );
+}
+
+const isMain =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMain) {
+  try {
+    const result = await runContext7({
+      argv: process.argv.slice(2),
+      cwd: process.cwd(),
+      home: homedir(),
+      readStdin: readAllStdin,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) {
+    printUsage();
+    process.stderr.write(
+      `${error instanceof Error ? error.message : "Context7 failed"}\n`,
+    );
+    process.exitCode = 1;
+  }
+}

package/skills/git-commit/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: git-commit
+description: Create one repository-compliant commit only after an explicit user commit request and deterministic safety audit
+---
+
+# Git commit
+
+Activate this Skill only when the user explicitly asks to commit or invokes this Skill.
+Workflow completion does not authorize a commit, Gate approval never authorizes a commit, and an installed Skill does not authorize or execute a commit by itself.
+
+## Safety audit
+
+After an explicit request:
+
+1. Read the repository root and all relevant nested `AGENTS.md` files.
+2. Inspect `git status --short`, `git diff`, and `git diff --staged` so staged and unstaged changes are both visible.
+3. Exclude every `.env` file, credential, private key, user or session state, workflow state, and obviously unrelated path.
+4. Review deletions and renames explicitly; never infer that an ambiguous deletion is safe.
+5. Decide whether the remaining safe relevant paths form exactly one logical commit.
+
+If changes contain multiple logical groups, unrelated dirty files, ambiguous deletions, unsafe files, or no uniquely safe group, leave the index and history unchanged and ask the user which logical group to commit.
+
+## One safe logical commit
+
+When the audit identifies one unambiguous logical commit:
+
+1. Stage only the explicit path list with `git add -- <paths>`.
+2. Reinspect `git diff --staged` and confirm it contains only that path list and no prohibited content.
+3. Derive a repository-compliant Conventional Commit message from the actual staged diff.
+4. Execute one normal commit and report its received output.
+
+## Prohibited operations
+
+Never use `git add .`, `git add -A`, `git add -p`, `--no-verify`, `--amend`, reset, force push, or `git config` mutation.
+Never bypass hooks, rewrite history, discard work, or broaden the explicit path list.
+
+If a commit hook fails, report the failure as received, preserve the staged state for inspection, and do not bypass the hook.

package/skills/grok-search/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: grok-search
+description: Search and retrieve current web information through a Grok-compatible gateway and optional Tavily operations
+---
+
+# Grok search
+
+Use this Skill for current web search, page retrieval, site maps, and source-backed fact checking.
+Run the dependency-free Node.js CLI from this Skill directory.
+
+## Commands
+
+```bash
+node grok-search.mjs web_search --query <text> \
+  [--platform <name>] [--min-results <n>] [--max-results <n>] \
+  [--model <id>] [--extra-sources <n>]
+
+node grok-search.mjs web_fetch --url <url> [--out <path>]
+
+node grok-search.mjs web_map --url <url> \
+  [--instructions <text>] [--max-depth <n>] \
+  [--max-breadth <n>] [--limit <n>]
+
+node grok-search.mjs get_config_info
+```
+
+Start with `web_search`, use `web_fetch` for a selected page, and use `web_map` for site structure.
+Cite source URLs and relevant dates for time-sensitive answers.
+Treat non-zero exits and invalid result shapes as failed research.
+
+`web_search` returns normalized `{title,url,description}` objects.
+`--extra-sources` explicitly requires enabled Tavily and fails rather than returning partial provider results.
+`web_fetch` uses Tavily Markdown extraction when enabled, emits a sanitized warning on extract failure, then falls back to Grok.
+`web_map` requires enabled Tavily.
+`get_config_info` prints only the selected path, provider URLs, model, and enabled/configured booleans; it does not test the network or print keys.
+
+The CLI selects the project `.pi/cadence/.env` as a whole file when present, otherwise `~/.pi/agent/cadence/.env`.
+`GROK_API_URL` and `GROK_API_KEY` are required.
+`GROK_MODEL` defaults to `grok-4.20-non-reasoning`, `TAVILY_API_URL` defaults to `https://api.tavily.com`, and Tavily is enabled by default once a non-empty `TAVILY_API_KEY` is configured; set `TAVILY_ENABLED=false` to opt out.