abelworkflow 0.1.0

package/commands/oc/research.md

@@ -0,0 +1,126 @@
+---
+name: OC:Research
+description: Transform user requirements into constraint sets via structured exploration (NO implementation)
+category: OC
+tags: [OC, research, constraints, exploration, subagents]
+---
+
+<!-- OC:RESEARCH:START -->
+
+# OC:Research — Operating Mode (Constraints & Specs Only)
+
+## Non‑Negotiable Rules (Highest Priority)
+1. RESEARCH MODE ONLY.
+   - You MUST NOT generate code.
+2. WRITE SCOPE IS RESTRICTED.
+   - You MAY create/edit files ONLY under: openspec/changes/<change-name>/** (and only after passing the confirmation gates).
+   - You MUST NOT write anywhere else.
+3. Output must be constraint sets + verifiable success criteria, not an information dump.
+
+## Goal
+Produce constraint sets that narrow the solution space, plus measurable success criteria.
+
+---
+
+
+
+## Phase 0 — Requirement Intake Gate (MANDATORY)
+- **MUST** confirm the user’s requirement exists and is clear **before** any research/action.
+- If missing/unclear, **MUST** use `AskUserQuestions` to collect: goal, in-scope area, top scenarios, non-goals, known constraints, success signals.
+- **MUST NOT** run `/opsx:new`, any codebase retrieval, spawn subagents, or generate artifacts until the user confirms a brief requirement summary.
+
+---
+
+## Phase 1 — Initialize OpenSpec Change Folder
+1) Run: /opsx:new <change-name>
+2) From now on, you may write ONLY under openspec/changes/<change-name>/**.
+
+---
+
+## Phase 2 — Initial Codebase Assessment (Read‑Only)
+- Use `mcp__augment-context-engine__codebase-retrieval` as the primary way to locate relevant code; avoid grep/find unless unavoidable.
+- If technical research needed (architectural patterns, best practices), invoke `/grok-search` skill
+- If the codebase spans multiple modules/directories, dispatch parallel explore subagents by context boundary.
+
+---
+
+## Phase 3 — Define Exploration Boundaries (Context-Based Division Only)
+- Identify natural context boundaries in the codebase (NOT functional roles).
+- Example divisions:
+  * Subagent 1: User domain code (user models, user services, user UI)
+  * Subagent 2: Authentication & authorization code (auth middleware, session, tokens)
+  * Subagent 3: Configuration & infrastructure (configs, deployments, build scripts)
+- Each boundary should be self-contained: no cross-communication needed between subagents.
+- Define exploration scope and expected output for each subagent.
+
+---
+
+## Phase 4 — Subagent Output Template (MANDATORY JSON)
+All explore subagents MUST return valid JSON using this schema:
+{
+  "module_name": "字符串 - 所探索的上下文边界",
+  "existing_structures": ["发现的关键结构/模式列表"],
+  "existing_conventions": ["当前使用的约定/标准列表"],
+  "constraints_discovered": ["限制解决方案空间的硬约束列表"],
+  "open_questions": ["需要用户输入的歧义问题列表"],
+  "dependencies": ["对其他模块/系统的依赖列表"],
+  "risks": ["潜在风险或阻碍列表"],
+  "success_criteria_hints": ["指示成功的可观察行为列表"]
+}
+
+---
+
+## Phase 5 — Parallel Subagent Dispatch
+- Monitor subagent execution and collect structured reports.
+- For each boundary, spawn an Explore subagent with:
+  - Mandatory use of `mcp__augment-context-engine__codebase-retrieval`
+  - Clear scope
+  - self-contained with independent output
+  - Required output template (from Phase 4)
+  - If boundary involves 3+ interconnected components, invoke `/sequential-think` skill
+  - Clear success criteria: complete analysis of assigned boundary
+
+
+---
+
+## Phase 6 — Aggregate & Synthesize
+- Collect all subagent JSON outputs.
+- Merge findings into unified constraint sets:
+  * **Hard constraints**: Technical limitations, existing patterns that cannot be violated.
+  * **Soft constraints**: Conventions, preferences, style guides.
+  * **Dependencies**: Cross-module relationships that affect implementation order.
+  * **Risks**: Potential blockers that need mitigation.
+- Identify **open questions** from all reports that require user clarification.
+- Synthesize **success criteria** from scenario hints across all contexts.
+
+---
+
+## Phase 7 — User Interaction for Ambiguity Resolution
+- Compile prioritized list of open questions from aggregated reports.
+- Use `AskUserQuestions` tool to present questions systematically:
+  * Group related questions together.
+  * Provide context for each question.
+  * Suggest default answers when applicable.
+- Capture user responses as additional constraints.
+- Update constraint sets with confirmed decisions.
+
+---
+
+## Phase 8 — Generate OpenSpec Artifacts
+- Transform finalized constraint sets into OpenSpec proposal/specs/design/tasks.
+- Every requirement MUST have a verifiable scenario and success criteria.
+- Keep all writes inside openspec/changes/<change-name>/**.
+
+## Reference
+- Review existing constraints: `rg -n "Constraint:|MUST|MUST NOT" openspec/specs`
+- Inspect codebase structure: `ls -R` or `mcp__augment-context-engine__codebase-retrieval` with `file list --recursive`
+
+- Check prior research outputs: `ls openspec/changes/*/`
+- OpenSpec CLI commands:
+  - `openspec view` - Interactive dashboard to browse changes
+  - `openspec list --changes` - List all active changes
+  - `openspec status --change <name>` - Check artifact completion status
+  - `openspec instructions proposal --change <name>` - Get proposal instructions
+- Validate subagent outputs conform to template before aggregation.
+- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess.
+<!-- OC:RESEARCH:END -->

package/lib/cli.mjs

@@ -0,0 +1,222 @@
+import { cp, lstat, mkdir, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const packageRoot = dirname(dirname(__filename));
+const home = homedir();
+const defaultAgentsDir = join(home, ".agents");
+const managedEntries = [
+  "AGENTS.md",
+  "README.md",
+  "commands",
+  "skills",
+  ".skill-lock.json",
+  ".gitignore"
+];
+
+function parseArgs(argv) {
+  const options = {
+    agentsDir: defaultAgentsDir,
+    force: false,
+    relinkOnly: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--force" || arg === "-f") {
+      options.force = true;
+      continue;
+    }
+    if (arg === "--link-only") {
+      options.relinkOnly = true;
+      continue;
+    }
+    if (arg === "--agents-dir") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--agents-dir requires a path");
+      }
+      options.agentsDir = resolve(value);
+      i += 1;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`AbelWorkflow installer
+
+Usage:
+  npx abelworkflow
+  npx abelworkflow --force
+  npx abelworkflow --link-only
+  npx abelworkflow --agents-dir /custom/path
+`);
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function backupIfNeeded(targetPath, force) {
+  if (!(await pathExists(targetPath))) {
+    return null;
+  }
+  if (!force) {
+    const backupPath = `${targetPath}.bak.${Date.now()}`;
+    await rename(targetPath, backupPath);
+    return backupPath;
+  }
+  await rm(targetPath, { recursive: true, force: true });
+  return null;
+}
+
+async function syncManagedFiles(agentsDir) {
+  await mkdir(agentsDir, { recursive: true });
+
+  for (const entry of managedEntries) {
+    const source = join(packageRoot, entry);
+    const target = join(agentsDir, entry);
+    await rm(target, { recursive: true, force: true });
+    await cp(source, target, { recursive: true });
+  }
+
+  await writeFile(
+    join(agentsDir, ".abelworkflow-install.json"),
+    JSON.stringify(
+      {
+        package: "abelworkflow",
+        installedAt: new Date().toISOString()
+      },
+      null,
+      2
+    ) + "\n",
+    "utf8"
+  );
+}
+
+async function ensureSymlink(targetPath, sourcePath, kind, force) {
+  await mkdir(dirname(targetPath), { recursive: true });
+
+  if (await pathExists(targetPath)) {
+    const stat = await lstat(targetPath);
+    if (stat.isSymbolicLink()) {
+      const existing = await readlink(targetPath);
+      const existingResolved = resolve(dirname(targetPath), existing);
+      if (existingResolved === resolve(sourcePath)) {
+        return { targetPath, status: "unchanged" };
+      }
+    }
+    await backupIfNeeded(targetPath, force);
+  }
+
+  const linkType = process.platform === "win32" ? (kind === "dir" ? "junction" : "file") : kind;
+  await symlink(sourcePath, targetPath, linkType);
+  return { targetPath, status: "linked" };
+}
+
+async function linkSkillDirectories(baseDir, agentsDir, force) {
+  const results = [];
+  const skillsRoot = join(agentsDir, "skills");
+  const skillNames = await getDirectoryNames(skillsRoot);
+  for (const skillName of skillNames) {
+    results.push(
+      await ensureSymlink(
+        join(baseDir, "skills", skillName),
+        join(skillsRoot, skillName),
+        "dir",
+        force
+      )
+    );
+  }
+  return results;
+}
+
+async function getDirectoryNames(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+}
+
+async function getCommandNames(commandsDir) {
+  const entries = await readdir(commandsDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => entry.name);
+}
+
+async function linkClaude(agentsDir, force) {
+  const claudeDir = join(home, ".claude");
+  await mkdir(join(claudeDir, "commands"), { recursive: true });
+  await mkdir(join(claudeDir, "skills"), { recursive: true });
+
+  return [
+    await ensureSymlink(join(claudeDir, "CLAUDE.md"), join(agentsDir, "AGENTS.md"), "file", force),
+    await ensureSymlink(join(claudeDir, "commands", "oc"), join(agentsDir, "commands", "oc"), "dir", force),
+    ...(await linkSkillDirectories(claudeDir, agentsDir, force))
+  ];
+}
+
+async function linkCodex(agentsDir, force) {
+  const results = [];
+  const codexDir = join(home, ".codex");
+  await mkdir(join(codexDir, "skills"), { recursive: true });
+  await mkdir(join(codexDir, "prompts"), { recursive: true });
+
+  results.push(await ensureSymlink(join(codexDir, "AGENTS.md"), join(agentsDir, "AGENTS.md"), "file", force));
+  results.push(...(await linkSkillDirectories(codexDir, agentsDir, force)));
+
+  const commandFiles = await getCommandNames(join(agentsDir, "commands", "oc"));
+  for (const fileName of commandFiles) {
+    results.push(
+      await ensureSymlink(
+        join(codexDir, "prompts", fileName),
+        join(agentsDir, "commands", "oc", fileName),
+        "file",
+        force
+      )
+    );
+  }
+
+  return results;
+}
+
+async function install() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (!options.relinkOnly) {
+    await syncManagedFiles(options.agentsDir);
+  } else if (!(await pathExists(options.agentsDir))) {
+    throw new Error(`${options.agentsDir} does not exist; remove --link-only or install first`);
+  }
+
+  const claudeResults = await linkClaude(options.agentsDir, options.force);
+  const codexResults = await linkCodex(options.agentsDir, options.force);
+
+  console.log(`Installed AbelWorkflow into ${options.agentsDir}`);
+  console.log("");
+  console.log("Linked targets:");
+  for (const result of [...claudeResults, ...codexResults]) {
+    console.log(`- ${result.status === "unchanged" ? "=" : "+"} ${result.targetPath}`);
+  }
+  console.log("");
+  console.log("Done. Re-run `npx abelworkflow@latest` to update the managed files.");
+}
+
+install().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "abelworkflow",
+  "version": "0.1.0",
+  "description": "Install AbelWorkflow into ~/.agents and create Claude/Codex symlinks.",
+  "type": "module",
+  "bin": {
+    "abelworkflow": "./bin/abelworkflow.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "AGENTS.md",
+    "README.md",
+    "commands",
+    "skills",
+    ".skill-lock.json",
+    ".gitignore"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/skills/confidence-check/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: Confidence Check
+description: Pre-implementation confidence assessment (≥90% required). Use before starting any implementation to verify readiness with duplicate check, architecture compliance, official docs verification, OSS references, and root cause identification.
+---
+
+# Confidence Check Skill
+
+## Purpose
+
+Prevents wrong-direction execution by assessing confidence **BEFORE** starting implementation.
+
+**Requirement**: ≥90% confidence to proceed with implementation.
+
+**Test Results** (2025-10-21):
+- Precision: 1.000 (no false positives)
+- Recall: 1.000 (no false negatives)
+- 8/8 test cases passed
+
+## When to Use
+
+Use this skill BEFORE implementing any task to ensure:
+- No duplicate implementations exist
+- Architecture compliance verified
+- Official documentation reviewed
+- Working OSS implementations found
+- Root cause properly identified
+
+## Confidence Assessment Criteria
+
+Calculate confidence score (0.0 - 1.0) based on 5 checks:
+
+### 1. No Duplicate Implementations? (25%)
+
+**Check**: Search codebase for existing functionality
+
+```bash
+# Use Grep to search for similar functions
+# Use Glob to find related modules
+```
+
+✅ Pass if no duplicates found
+❌ Fail if similar implementation exists
+
+### 2. Architecture Compliance? (25%)
+
+**Check**: Verify tech stack alignment
+
+- Read `CLAUDE.md`, `AGENTS.md`, `PLANNING.md`
+- Confirm existing patterns used
+- Avoid reinventing existing solutions
+
+✅ Pass if uses existing tech stack (e.g., Supabase, UV, pytest)
+❌ Fail if introduces new dependencies unnecessarily
+
+### 3. Official Documentation Verified? (20%)
+
+**Check**: Review official docs before implementation
+
+- Use Context7 MCP for official docs
+- Use WebFetch for documentation URLs
+- Verify API compatibility
+
+✅ Pass if official docs reviewed
+❌ Fail if relying on assumptions
+
+### 4. Working OSS Implementations Referenced? (15%)
+
+**Check**: Find proven implementations
+
+- Use Tavily MCP or WebSearch
+- Search GitHub for examples
+- Verify working code samples
+
+✅ Pass if OSS reference found
+❌ Fail if no working examples
+
+### 5. Root Cause Identified? (15%)
+
+**Check**: Understand the actual problem
+
+- Analyze error messages
+- Check logs and stack traces
+- Identify underlying issue
+
+✅ Pass if root cause clear
+❌ Fail if symptoms unclear
+
+## Confidence Score Calculation
+
+```
+Total = Check1 (25%) + Check2 (25%) + Check3 (20%) + Check4 (15%) + Check5 (15%)
+
+If Total >= 0.90:  ✅ Proceed with implementation
+If Total >= 0.70:  ⚠️  Present alternatives, ask questions
+If Total < 0.70:   ❌ STOP - Request more context
+```
+
+## Output Format
+
+```
+📋 Confidence Checks:
+   ✅ No duplicate implementations found
+   ✅ Uses existing tech stack
+   ✅ Official documentation verified
+   ✅ Working OSS implementation found
+   ✅ Root cause identified
+
+📊 Confidence: 1.00 (100%)
+✅ High confidence - Proceeding to implementation
+```
+
+## Implementation Details
+
+The TypeScript implementation is available in `confidence.ts` for reference, containing:
+
+- `confidenceCheck(context)` - Main assessment function
+- Detailed check implementations
+- Context interface definitions
+
+## ROI
+
+**Token Savings**: Spend 100-200 tokens on confidence check to save 5,000-50,000 tokens on wrong-direction work.
+
+**Success Rate**: 100% precision and recall in production testing.