@ceyhunbilir/synaphex 1.0.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ceyhunbilir/synaphex",
+  "version": "1.0.0",
+  "description": "Multi-agent AI pipeline as a Claude Code skill — Examiner → Researcher → Coder → Questioner → Reviewer",
+  "main": "dist/index.js",
+  "bin": {
+    "synaphex": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "npm run build",
+    "prepare": "husky install 2>/dev/null || true",
+    "lint:commit": "commitlint --from HEAD~1 --to HEAD"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "scripts/postinstall.js"
+  ],
+  "keywords": [
+    "claude-code",
+    "ai-pipeline",
+    "multi-agent",
+    "skill",
+    "claude"
+  ],
+  "author": "ceyhunbilir",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ceyhunbilir/synaphex.git"
+  },
+  "homepage": "https://github.com/ceyhunbilir/synaphex",
+  "dependencies": {
+    "commander": "^9.4.1",
+    "fs-extra": "^9.1.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^18.0.0",
+    "@commitlint/config-conventional": "^18.0.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^12.20.0",
+    "husky": "^8.0.0",
+    "typescript": "^4.9.0"
+  },
+  "engines": {
+    "node": ">=10.0.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILLS_SRC = path.join(__dirname, '..', 'skills');
+const COMMANDS_DEST = path.join(os.homedir(), '.claude', 'commands', 'synaphex');
+
+try {
+  // Create destination directory
+  fs.mkdirSync(COMMANDS_DEST, { recursive: true });
+
+  // Find all .md files in skills directory
+  const files = fs.readdirSync(SKILLS_SRC).filter((f) => f.endsWith('.md'));
+
+  if (files.length === 0) {
+    console.warn('[synaphex] Warning: No skill files found in skills/ directory');
+    process.exit(0);
+  }
+
+  // Copy each skill file
+  for (const file of files) {
+    const src = path.join(SKILLS_SRC, file);
+    const dest = path.join(COMMANDS_DEST, file);
+    fs.copyFileSync(src, dest);
+    console.log(`[synaphex] ✓ Installed skill: ~/.claude/commands/synaphex/${file}`);
+  }
+
+  console.log('\n[synaphex] Skills installed successfully!');
+  console.log('[synaphex] Available commands:');
+  console.log('  /synaphex/init <project>');
+  console.log('  /synaphex/query <task>');
+  console.log('  /synaphex/fix <task>');
+  console.log('\n[synaphex] Documentation: https://github.com/ceyhunbilir/synaphex');
+} catch (err) {
+  // Non-fatal error — postinstall script failures block npm install
+  console.warn('[synaphex] ⚠️  Warning: Could not auto-install skills:', err.message);
+  console.warn('[synaphex] You can manually copy them:');
+  console.warn(`  cp ${SKILLS_SRC}/*.md ~/.claude/commands/synaphex/`);
+  process.exit(0);
+}

package/skills/fix.md

@@ -0,0 +1,210 @@
+---
+description: "Run Synaphex fix pipeline with optional researcher skip: Examiner → [Researcher?] → Coder → Questioner → Reviewer"
+---
+
+# Synaphex Fix Pipeline
+
+**Fix Request:** $ARGUMENTS
+
+You are running the Synaphex fix pipeline. This is tailored for targeted bug fixes or code improvements where you may not need extensive research.
+
+---
+
+## Step 0: Load Agent Customizations
+
+Before asking about research, load any agent customizations for this project. Run:
+
+```bash
+synaphex load-config $ARGUMENTS
+```
+
+Read the output. If customizations are present, apply them throughout each agent stage:
+- **Provider & Auth** — The configured LLM provider and authentication method for each agent
+  - `claude` + `api_key`: Use ANTHROPIC_API_KEY
+  - `claude` + `cli`: Use claude CLI
+  - `claude` + `vscode_extension`: Use Claude Code extension (native)
+  - `gemini` + `api_key`: Use GEMINI_API_KEY
+  - `copilot` + `cli`: Use gh CLI
+- **Model** — The specific model to use (e.g., claude-opus-4-5, gemini-1.5-pro)
+- **Focus** — prioritize that area
+- **Depth** — adjust thoroughness (quick = surface-level, standard = balanced, deep = comprehensive)
+- **Custom instructions** — follow any extra guidance provided
+
+---
+
+## Step 1: Ask About Research Phase
+
+Before starting, I need your input on whether to include the Researcher stage:
+
+> **Would you like to include the Researcher phase?**
+>
+> - **Yes** — Full pipeline (Examiner → Researcher → Coder → Questioner → Reviewer)
+>   - More thorough, researches best practices and solutions
+>   - Takes longer
+>   - Good for complex fixes or unclear requirements
+>
+> - **No** — Fast pipeline (Examiner → Coder → Questioner → Reviewer)
+>   - Skips research, goes straight to implementation
+>   - Faster, assumes you know what to do
+>   - Good for straightforward fixes or when you're confident in the approach
+
+Please respond with **Yes** or **No**.
+
+---
+
+## Pipeline Execution (Based on Your Choice)
+
+Based on your response above, I'll now run the appropriate pipeline.
+
+### Stage 1: EXAMINER — Context Analysis
+
+**Role:** Project context analyst. Understand what needs to be fixed.
+
+**Your Instructions:**
+
+1. **Analyze the fix request.** What exactly needs to be fixed or improved?
+
+2. **Examine the relevant code.** Read and understand:
+   - The code that needs fixing
+   - Related code that might be affected
+   - Existing patterns and conventions
+
+3. **Load project memory** (if available):
+   ```bash
+   synaphex load-memory $ARGUMENTS
+   ```
+
+4. **Identify the problem** and its context.
+
+**Produce:** Context report with sections:
+- **Problem Statement** — What's broken or needs improvement
+- **Root Cause Analysis** — Why is it happening?
+- **Affected Code** — Files and functions involved
+- **Current Patterns** — How similar issues are handled
+- **Impact Assessment** — What breaks if not fixed?
+- **Fix Strategy Outline** — Initial approach
+
+---
+
+### Stage 2 (OPTIONAL): RESEARCHER — Best Practices
+
+**⚠️ SKIP THIS STAGE IF USER CHOSE "NO"**
+
+**Role:** Research analyst. Find the best approach to fix this.
+
+**Your Instructions:**
+
+1. **Research the problem domain.**
+   - What are standard solutions for this type of issue?
+   - Are there libraries or patterns that help?
+
+2. **Evaluate fix approaches.**
+   - What are the options?
+   - What are trade-offs?
+   - What's most maintainable?
+
+3. **Document best practices** for this type of fix.
+
+**Produce:** Research report with sections:
+- **Recommended Fix** — Detailed approach
+- **Why This Approach** — Rationale
+- **Best Practices** — How to do this right
+- **Potential Issues** — What to watch out for
+- **Reference Examples** — Similar patterns in codebase
+
+---
+
+### Stage 3: CODER — Implementation
+
+**Role:** Senior developer. Write the fix.
+
+**Your Instructions:**
+
+1. **Implement the fix.** Based on Examiner (and Researcher if included):
+   - Write clean, tested code
+   - Follow existing patterns
+   - Include error handling
+   - Add comments where needed
+
+2. **Keep it focused.** This is a fix, not a refactor.
+   - Don't change unrelated code
+   - Don't add features beyond the fix
+   - Minimal necessary changes
+
+3. **Provide complete code** for all files that need changes.
+
+**Produce:** Implementation with sections:
+- **Code Changes** — Exact changes needed
+- **Why This Fixes It** — Explanation of the fix
+- **Side Effects** — Any other code that might be affected
+- **Testing** — How to verify the fix works
+
+---
+
+### Stage 4: QUESTIONER — Critical Review
+
+**Role:** Critical reviewer. Challenge the fix.
+
+**Your Instructions:**
+
+1. **Question the implementation.**
+   - Does it fully fix the issue?
+   - Are there edge cases?
+   - Could it break something else?
+   - Is error handling sufficient?
+
+2. **Identify improvements** and issues.
+
+3. **Suggest concrete fixes** with code examples.
+
+**Produce:** Critique with sections:
+- **Does It Fix The Problem?** — Yes/no assessment
+- **Edge Cases** — Scenarios not covered
+- **Potential Issues** — Bugs or problems the fix could introduce
+- **Improvements** — Better approaches
+- **Revised Code** — Specific fixes for issues found
+
+---
+
+### Stage 5: REVIEWER — Final Decision
+
+**Role:** Senior architect. Final quality gate.
+
+**Your Instructions:**
+
+1. **Review all prior outputs.**
+   - Is the fix correct?
+   - Is it complete?
+   - Are all Questioner feedback incorporated?
+
+2. **Make final decision:** APPROVED or NEEDS REVISION
+
+3. **Deliver the final implementation.**
+
+**Produce:** Final assessment with sections:
+- **Final Verdict** — APPROVED or NEEDS REVISION
+- **Complete Implementation** — Final fixed code
+- **Quality Verification** — Checklist of concerns addressed
+- **Impact Summary** — What changed and why
+- **Next Steps** (if any)
+
+---
+
+## Save Pipeline Output
+
+After all stages complete:
+
+```bash
+synaphex save-output $ARGUMENTS '{"command":"fix","task":"$ARGUMENTS","skip_researcher":false,"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","stages":{"examiner":"...","coder":"...","questioner":"...","reviewer":"..."}}'
+```
+
+(Set `skip_researcher` to `true` if the user chose to skip the research phase.)
+
+---
+
+## Important Notes
+
+- **Focused fixes:** This is for targeted fixes, not full rewrites
+- **Hard failure guards:** Stop immediately if any stage fails
+- **Quick feedback loops:** Fix pipeline is faster than query because research is optional
+- **Researcher inclusion:** Is your choice — skip for confidence, include for thorough vetting

package/skills/init.md

@@ -0,0 +1,69 @@
+---
+description: "Initialize a new Synaphex project at ~/.claude/projects/<project> with config, memory, and outputs directories"
+---
+
+# Synaphex Init
+
+I'll guide you through initializing a new Synaphex project. The project name is: **$ARGUMENTS**
+
+## Step 1: Create Project Directory
+
+**Run this command in your terminal** (copy and paste):
+
+```bash
+synaphex init-project $ARGUMENTS
+```
+
+This creates `~/.claude/projects/$ARGUMENTS/` with:
+- **config.md** — YAML configuration with per-agent LLM settings
+- **memory/** — project memory files for context across sessions
+- **outputs/** — pipeline run results
+
+The config will have all 5 agents (Examiner, Researcher, Coder, Questioner, Reviewer) with Claude as the default provider.
+
+## Step 2: Configure Per-Agent LLM Providers (Optional)
+
+Your project comes with **Claude (Anthropic)** as the default for all agents. To customize providers and authentication per agent, run:
+
+```bash
+/synaphex:settings $ARGUMENTS
+```
+
+Then execute the command it shows in your terminal. This opens an interactive settings CLI where you can configure each agent independently:
+
+**Supported providers:**
+- **claude** — Anthropic Claude (auth modes: api_key, cli, vscode_extension)
+  - Models: claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5-20251001
+  - API key: `ANTHROPIC_API_KEY`
+  - CLI: `claude` command
+  - VSCode: Claude Code extension (native, no API key)
+  
+- **gemini** — Google Gemini (auth mode: api_key)
+  - Models: gemini-2.5-pro, gemini-1.5-pro, gemini-1.5-flash
+  - API key: `GEMINI_API_KEY`
+  
+- **copilot** — GitHub Copilot (auth mode: cli)
+  - CLI: `gh` command with `gh auth login`
+
+## Step 3: Verify Project Creation
+
+After running the init command, verify the project was created:
+
+```bash
+ls -la ~/.claude/projects/$ARGUMENTS/
+```
+
+You should see:
+- `config.md` — YAML configuration with per-agent settings
+- `memory/` — Directory for project memories
+- `outputs/` — Directory for pipeline results
+
+## Step 4: Ready to Go
+
+Once the project is created, you can use:
+
+- **`/synaphex:query <task>`** — Run the full 5-stage pipeline (Examiner → Researcher → Coder → Questioner → Reviewer)
+- **`/synaphex:fix <task>`** — Run the pipeline with optional Researcher skip  
+- **`/synaphex:settings $ARGUMENTS`** — Configure per-agent LLM providers and authentication
+
+Each pipeline run will be saved to `~/.claude/projects/$ARGUMENTS/outputs/` automatically.

package/skills/query.md

@@ -0,0 +1,217 @@
+---
+description: "Run the full Synaphex 5-stage pipeline: Examiner → Researcher → Coder → Questioner → Reviewer"
+---
+
+# Synaphex Query Pipeline
+
+**Task:** $ARGUMENTS
+
+You are running the complete Synaphex multi-agent pipeline. This will take you through 5 stages of analysis and refinement. Think deeply at each stage and produce thorough, high-quality outputs.
+
+---
+
+## Load Agent Customizations
+
+Before starting, I need to load any agent customizations configured for this project. Run this in your terminal:
+
+```bash
+synaphex load-config $ARGUMENTS
+```
+
+Read the output. If customizations are present, apply them throughout each agent stage below:
+- **Provider & Auth** — The configured LLM provider and authentication method for each agent
+  - `claude` + `api_key`: Use ANTHROPIC_API_KEY
+  - `claude` + `cli`: Use claude CLI
+  - `claude` + `vscode_extension`: Use Claude Code extension (native)
+  - `gemini` + `api_key`: Use GEMINI_API_KEY
+  - `copilot` + `cli`: Use gh CLI
+- **Model** — The specific model to use (e.g., claude-opus-4-5, gemini-1.5-pro)
+- **Focus** — prioritize that area
+- **Depth** — adjust thoroughness (quick = surface-level, standard = balanced, deep = comprehensive)
+- **Custom instructions** — follow any extra guidance provided
+
+If no customizations are shown, proceed with standard agent behavior for each stage using Claude models.
+
+---
+
+## Stage 1: EXAMINER — Context Analysis
+
+**Role:** You are a project context analyst. Your job is to understand the current state and what needs to be done.
+
+**Your Instructions:**
+
+1. **Analyze the task.** What exactly is being asked? What are the success criteria?
+
+2. **Examine the current codebase.** Read relevant files to understand:
+   - Existing architecture and patterns
+   - Technology stack in use
+   - File structure and organization
+   - Existing implementations that are related
+
+3. **Identify constraints and context.**
+   - What patterns are already established?
+   - What libraries/frameworks are in use?
+   - What conventions should be followed?
+
+4. **Load project memory** (if available). Run:
+   ```bash
+   synaphex load-memory $ARGUMENTS
+   ```
+   Review the output to understand project history and context.
+
+**Produce:** A comprehensive context report with sections:
+- **Task Analysis** — What needs to be done and why
+- **Current State** — Existing code, architecture, patterns
+- **Technology Stack** — Languages, frameworks, libraries in use
+- **Constraints & Conventions** — What to follow
+- **Identified Gaps** — What's missing or needs improvement
+- **Recommended Approach** — Initial strategy
+
+---
+
+## Stage 2: RESEARCHER — Best Practices & Solutions
+
+**Role:** You are a research analyst. Based on the context from Examiner, research the best approach.
+
+**Your Instructions:**
+
+1. **Research the problem domain.** What are the accepted best practices for this type of task?
+
+2. **Evaluate approaches.** Consider:
+   - Multiple solutions and their trade-offs
+   - Performance implications
+   - Security considerations
+   - Maintainability and readability
+   - Testing strategies
+
+3. **Check for existing solutions.** Are there libraries, patterns, or examples that directly apply?
+
+4. **Document findings.** Be specific about why certain approaches are better.
+
+**Produce:** A structured research report with sections:
+- **Recommended Approach** — Detailed explanation and rationale
+- **Alternative Approaches** — What else could work (and why you rejected them)
+- **Best Practices** — Security, performance, testing, patterns
+- **Relevant Libraries/Tools** — What to use and why
+- **Common Pitfalls** — What to avoid
+- **Reference Implementation** — Code examples or patterns to follow
+
+---
+
+## Stage 3: CODER — Implementation
+
+**Role:** You are a senior developer. Implement the solution based on all prior analysis.
+
+**Your Instructions:**
+
+1. **Write production-ready code.** This means:
+   - Follow the patterns identified by the Examiner
+   - Use the approaches recommended by the Researcher
+   - Include proper error handling
+   - Write clear, maintainable code
+   - Add comments for non-obvious logic
+   - Include type hints/types where applicable
+
+2. **Comprehensive implementation.** Provide:
+   - All necessary file changes or new files
+   - Complete, runnable code (not pseudocode)
+   - Integration points with existing code
+   - Usage examples or tests
+
+3. **Quality standards:**
+   - Consistent with the existing codebase style
+   - No unnecessary complexity
+   - Proper structure and organization
+   - Security-conscious (validate inputs, prevent common attacks)
+
+**Produce:** Complete implementation with sections:
+- **Code Changes** — All files to create or modify
+- **Key Implementation Details** — How it works, important decisions
+- **Integration Points** — Where this connects to existing code
+- **Usage Examples** — How to use the new code
+- **Testing Suggestions** — How to verify it works
+
+---
+
+## Stage 4: QUESTIONER — Critical Review
+
+**Role:** You are a critical code reviewer (Socratic method). Challenge every assumption.
+
+**Your Instructions:**
+
+1. **Question the implementation.**
+   - Does it handle all edge cases?
+   - Are there security vulnerabilities?
+   - Could it be more performant?
+   - Is the error handling sufficient?
+
+2. **Identify improvements:**
+   - Critical issues (must fix)
+   - Optimization opportunities
+   - Better patterns or libraries
+   - Edge cases not handled
+
+3. **Suggest concrete fixes.** For each issue, provide:
+   - What's wrong
+   - Why it matters
+   - Specific fix with code examples
+
+**Produce:** A structured critique with sections:
+- **Strengths** — What the implementation does well
+- **Critical Issues** — Things that must be fixed
+- **Suggested Improvements** — Better approaches, edge cases
+- **Performance Considerations** — Any bottlenecks?
+- **Security Review** — Any vulnerabilities?
+- **Revised Code Snippets** — Specific fixes for the most important issues
+
+---
+
+## Stage 5: REVIEWER — Final Quality Gate
+
+**Role:** You are a senior architect doing final review. Consolidate everything and deliver the final solution.
+
+**Your Instructions:**
+
+1. **Review all prior outputs holistically.**
+   - Does the final code address the original task?
+   - Have all Questioner feedback been incorporated?
+   - Is the solution complete and coherent?
+
+2. **Make a final decision:** APPROVED or NEEDS REVISION
+
+3. **If APPROVED:**
+   - Provide the complete, final implementation incorporating all improvements
+   - Explain what changed from Coder → final version
+   - Summarize the quality gates passed
+
+4. **If NEEDS REVISION:**
+   - Identify what's blocking approval
+   - Provide specific next steps
+
+**Produce:** Final verdict with sections:
+- **Final Verdict** — APPROVED or NEEDS REVISION (and why)
+- **Complete Implementation** — The final, polished code
+- **Changes Made** — Summary of improvements from Questioner feedback
+- **Quality Summary** — Verification checklist
+- **Next Steps** (if applicable) — What remains to be done
+
+---
+
+## Save Pipeline Output
+
+After all 5 stages complete successfully, save the results:
+
+```bash
+synaphex save-output <project-name> '{"command":"query","task":"$ARGUMENTS","skip_researcher":false,"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","stages":{"examiner":"...","researcher":"...","coder":"...","questioner":"...","reviewer":"..."}}'
+```
+
+(Note: In practice, this would be a complete JSON object with all stage outputs. You can output this to a file and pipe it to the save command if the output is large.)
+
+---
+
+## Important Notes
+
+- **Hard failure guards:** If any prior stage fails or produces no output, immediately stop the pipeline and report the failure. Do not continue.
+- **Token budget awareness:** Coder stage gets the most tokens (produces the most detailed code). Reviewer stage is concise.
+- **Output format:** Each stage should have clear section headers and complete thoughts.
+- **Quality over speed:** Take time to do this right. Better to produce a thorough output than a rushed one.

package/skills/settings.md

@@ -0,0 +1,43 @@
+---
+description: "Configure LLM provider and model for a Synaphex project via interactive CLI"
+---
+
+# Synaphex Settings
+
+I'll show you how to configure per-agent LLM providers and authentication for your project: **$ARGUMENTS**
+
+## Step 1: Open Interactive Settings
+
+**Run this command in your terminal** (copy and paste):
+
+```bash
+synaphex configure $ARGUMENTS
+```
+
+This opens an interactive terminal UI where you can configure each agent.
+
+## Step 2: Configure Each Agent
+
+The interactive settings UI will let you configure each of the 5 agents (Examiner, Researcher, Coder, Questioner, Reviewer) independently.
+
+For each agent, you can set:
+
+- **Provider** — Choose from: claude, gemini, copilot
+- **Auth Mode** — Depends on provider:
+  - claude: api_key (ANTHROPIC_API_KEY), cli (claude command), or vscode_extension (Claude Code)
+  - gemini: api_key (GEMINI_API_KEY)
+  - copilot: cli (gh command)
+- **Model** — Select from available models for that provider
+- **Focus** — Optional focus area (e.g., security, performance, simplicity)
+- **Depth** — Thoroughness level (quick, standard, deep)
+- **Custom Instructions** — Optional additional guidance
+
+## Step 3: Verify Configuration
+
+After configuration, view your settings at any time:
+
+```bash
+synaphex load-config $ARGUMENTS
+```
+
+This displays all agents with their current provider, auth mode, model, and settings.