polyforgeai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiloumap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+[![npm version](https://img.shields.io/npm/v/polyforgeai.svg)](https://www.npmjs.com/package/polyforgeai)
+[![CI](https://github.com/Vekta/polyforge/actions/workflows/ci.yml/badge.svg)](https://github.com/Vekta/polyforge/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+# PolyForge
+
+Self-adaptive Claude Code plugin for automated software development workflows.
+
+PolyForge scans your project, detects your stack, architecture, and conventions, then provides intelligent slash commands to automate common development tasks.
+
+## Install
+
+```bash
+npx polyforgeai install
+```
+
+This symlinks PolyForge skills and rules into `~/.claude/`, making them available in any Claude Code session.
+
+## Quick Start
+
+1. Install PolyForge
+2. Open Claude Code in your project
+3. Run `/init` — PolyForge scans your project and generates an optimized configuration
+4. Use any command: `/pr-review`, `/fix #123`, `/brainstorm`, etc.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/init` | Scan project, detect stack/architecture, generate config interactively |
+| `/pr-review` | Review a PR with fresh context — checks CI, code quality, security |
+| `/analyse-db` | Connect to DB (Docker or direct), generate `docs/DB.md` schema documentation |
+| `/analyse-code` | Full codebase analysis — patterns, security, performance, config issues |
+| `/report-issue` | Detect and create issues on GitHub/Jira/GitLab |
+| `/fix #N` | Fix an issue — branch, implement, test, PR (autonomy level configurable) |
+| `/fix-ci` | Diagnose and fix CI/CD failures — loops max 3 times then reports |
+| `/brainstorm` | Free-form brainstorming — produces action plan with parallelizable tasks |
+| `/generate-doc` | Generate/update Claude-optimized documentation (CLAUDE.md, docs, rules) |
+
+## How It Works
+
+PolyForge uses Claude Code's native extension points:
+
+- **Skills** (`.claude/skills/`) — Each command is a SKILL.md that Claude Code loads on demand
+- **Rules** (`.claude/rules/`) — Golden principles enforced across all interactions
+- **Hooks** — Pipeline verification (tests, lint, vulncheck) before push/PR
+
+### Project Configuration
+
+After `/init`, your project gets:
+
+```
+.claude/
+  polyforge.json         # Project config (stack, tracker, autonomy, pipeline)
+  rules/
+    polyforge-*.md       # Stack-specific rules (scoped by file path)
+  skills/                  # (symlinked from PolyForge install)
+CLAUDE.md                  # Short, high-signal project summary (<200 lines)
+docs/
+  CONTEXT.md               # Detailed architecture and project context
+tmp/                       # PolyForge working directory (gitignored)
+```
+
+### Autonomy Levels
+
+Configured per project during `/init`:
+
+- **Full auto**: PolyForge branches, fixes, tests, and creates PRs autonomously
+- **Semi-auto**: PolyForge proposes changes, waits for approval before applying
+
+### Permissions & Hands-Free Mode
+
+By default, Claude Code asks for permission on every file edit and shell command. If you chose "full auto" during `/init`, you'll be asked whether to grant full permissions for the project.
+
+**Via `/init` (persistent, per-project):**
+Generates a `.claude/settings.json` that auto-approves all operations in the project directory. You can revert by deleting the file.
+
+**Via CLI flag (one-time, any project):**
+```bash
+claude --dangerously-skip-permissions
+```
+Launches a single session with all permissions granted. Nothing is saved — next session returns to normal.
+
+### Skill Management
+
+Install everything or pick what you need:
+
+```bash
+npx polyforgeai install                  # Install all skills & rules
+npx polyforgeai install --force          # Reinstall, overwriting existing
+npx polyforgeai add-skill pr-review fix  # Install specific skills only
+npx polyforgeai remove-skill analyse-db  # Remove a skill
+npx polyforgeai list                     # See available skills & install status
+```
+
+### Issue Tracker Integration
+
+Auto-detected during `/init`:
+- **GitHub Issues** — detected via `gh api`
+- **Jira** — detected from `.env`, `.jira` config
+- **GitLab** — detected from git remote
+
+## Design Principles
+
+- **Positive rules** — all golden principles are phrased as assertions, not negations (proven more effective with LLMs)
+- **Fresh context** — PR reviews use isolated subagents to avoid author bias
+- **Circuit breakers** — max 3 retries on any failing operation, then switch strategy or ask for help
+- **Progressive disclosure** — context is loaded on-demand, not upfront, to preserve the context window
+- **Hooks enforce, rules guide** — deterministic checks (tests, lint) are hooks; advisory guidance stays in rules
+
+## Update
+
+```bash
+npx polyforgeai update
+```
+
+## Uninstall
+
+```bash
+npx polyforgeai uninstall
+```
+
+## Requirements
+
+- Node.js >= 18
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
+- [`gh` CLI](https://cli.github.com/) (for GitHub integration)
+
+> **Note:** PolyForge is built on Claude Code's native extension system (skills, rules, hooks). It requires Claude Code as its runtime and does not support other AI models or providers. The skills are plain markdown and could be adapted to other tools in the future, but the orchestration (subagents, worktrees, context management) relies on Claude Code.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Run tests (`node --test tests/**/*.test.js`)
+4. Commit your changes
+5. Open a pull request
+
+## License
+
+[MIT](LICENSE)

package/bin/polyforge.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync, mkdirSync, symlinkSync, readlinkSync, unlinkSync, readFileSync, readdirSync, statSync, lstatSync } from 'fs';
+import { homedir } from 'os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const CLAUDE_DIR = resolve(homedir(), '.claude');
+const FORCE = process.argv.includes('--force');
+
+const pkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8'));
+
+const commands = {
+  install,
+  uninstall,
+  update,
+  'add-skill': addSkill,
+  'remove-skill': removeSkill,
+  list: listSkills,
+  help,
+  '--version': version,
+  '-v': version,
+};
+
+const command = process.argv[2] || 'help';
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}`);
+  commands.help();
+  process.exit(1);
+}
+
+commands[command]();
+
+function version() {
+  console.log(`polyforge v${pkg.version}`);
+}
+
+function install() {
+  console.log(`\nPolyForge v${pkg.version} — Installing skills & rules\n`);
+
+  const targets = [
+    { src: resolve(ROOT, 'skills'), dest: resolve(CLAUDE_DIR, 'skills'), type: 'skills' },
+    { src: resolve(ROOT, 'rules'), dest: resolve(CLAUDE_DIR, 'rules'), type: 'rules' },
+  ];
+
+  for (const { src, dest, type } of targets) {
+    if (!existsSync(src)) continue;
+
+    mkdirSync(dest, { recursive: true });
+
+    const entries = readdirSync(src);
+    for (const entry of entries) {
+      const srcPath = resolve(src, entry);
+      const destPath = resolve(dest, entry.startsWith('polyforge-') ? entry : `polyforge-${entry}`);
+
+      if (existsSync(destPath)) {
+        if (isSymlinkTo(destPath, srcPath)) {
+          console.log(`  ✓ ${type}/${entry} (already linked)`);
+          continue;
+        }
+        if (FORCE) {
+          safeUnlink(destPath);
+          symlinkSync(srcPath, destPath);
+          console.log(`  ↻ ${type}/${entry} → replaced (--force)`);
+          continue;
+        }
+        console.log(`  ⚠ ${type}/${entry} exists — skipping (use --force to overwrite)`);
+        continue;
+      }
+
+      symlinkSync(srcPath, destPath);
+      console.log(`  + ${type}/${entry} → linked`);
+    }
+  }
+
+  console.log('\n✓ PolyForge installed. Use /init in Claude Code to configure a project.\n');
+}
+
+function uninstall() {
+  console.log('\nPolyForge — Uninstalling\n');
+
+  const dirs = [
+    resolve(CLAUDE_DIR, 'skills'),
+    resolve(CLAUDE_DIR, 'rules'),
+  ];
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+      if (!entry.startsWith('polyforge-')) continue;
+      const fullPath = resolve(dir, entry);
+      if (safeUnlink(fullPath)) {
+        console.log(`  - Removed ${entry}`);
+      }
+    }
+  }
+
+  console.log('\n✓ PolyForge uninstalled.\n');
+}
+
+function update() {
+  console.log(`Updating PolyForge to v${pkg.version}...`);
+  uninstall();
+  install();
+}
+
+function addSkill() {
+  const names = process.argv.slice(3).filter(a => !a.startsWith('--'));
+  if (names.length === 0) {
+    console.error('Usage: polyforge add-skill <name> [name2 ...]\n');
+    console.log('Available skills:');
+    getAvailableSkills().forEach(s => console.log(`  - ${s}`));
+    process.exit(1);
+  }
+
+  const available = getAvailableSkills();
+  const skillsDest = resolve(CLAUDE_DIR, 'skills');
+  mkdirSync(skillsDest, { recursive: true });
+
+  for (const name of names) {
+    if (!isValidSkillName(name) || !available.includes(name)) {
+      console.log(`  ✗ Unknown skill: "${name}". Available: ${available.join(', ')}`);
+      continue;
+    }
+
+    const srcPath = resolve(ROOT, 'skills', name);
+    const destPath = resolve(skillsDest, `polyforge-${name}`);
+
+    if (existsSync(destPath)) {
+      if (isSymlinkTo(destPath, srcPath)) {
+        console.log(`  ✓ ${name} (already installed)`);
+      } else if (FORCE) {
+        safeUnlink(destPath);
+        symlinkSync(srcPath, destPath);
+        console.log(`  ↻ ${name} → replaced (--force)`);
+      } else {
+        console.log(`  ⚠ ${name} exists — skipping (use --force to overwrite)`);
+      }
+      continue;
+    }
+
+    symlinkSync(srcPath, destPath);
+    console.log(`  + ${name} → installed`);
+  }
+}
+
+function removeSkill() {
+  const names = process.argv.slice(3).filter(a => !a.startsWith('--'));
+  if (names.length === 0) {
+    console.error('Usage: polyforge remove-skill <name> [name2 ...]');
+    process.exit(1);
+  }
+
+  const skillsDest = resolve(CLAUDE_DIR, 'skills');
+
+  for (const name of names) {
+    if (!isValidSkillName(name)) {
+      console.log(`  ✗ Invalid skill name: "${name}"`);
+      continue;
+    }
+
+    const destPath = resolve(skillsDest, `polyforge-${name}`);
+    if (!existsSync(destPath)) {
+      console.log(`  - ${name} (not installed)`);
+      continue;
+    }
+
+    if (safeUnlink(destPath)) {
+      console.log(`  - ${name} → removed`);
+    } else {
+      console.error(`  ✗ Failed to remove ${name}`);
+    }
+  }
+}
+
+function listSkills() {
+  const available = getAvailableSkills();
+  const skillsDest = resolve(CLAUDE_DIR, 'skills');
+
+  console.log('\nPolyForge Skills:\n');
+  for (const name of available) {
+    const destPath = resolve(skillsDest, `polyforge-${name}`);
+    const installed = existsSync(destPath);
+    console.log(`  ${installed ? '✓' : '○'} ${name}`);
+  }
+  console.log('');
+}
+
+function getAvailableSkills() {
+  const skillsDir = resolve(ROOT, 'skills');
+  if (!existsSync(skillsDir)) return [];
+  return readdirSync(skillsDir).filter(entry =>
+    statSync(resolve(skillsDir, entry)).isDirectory()
+  );
+}
+
+function help() {
+  console.log(`
+PolyForge v${pkg.version} — Self-adaptive Claude Code plugin
+
+Usage:
+  npx polyforge install [--force]     Install all skills & rules into ~/.claude/
+  npx polyforge uninstall             Remove all PolyForge skills & rules
+  npx polyforge update                Reinstall (uninstall + install)
+  npx polyforge add-skill <name>      Install a specific skill [--force]
+  npx polyforge remove-skill <name>   Remove a specific skill
+  npx polyforge list                  Show available skills and install status
+  npx polyforge --version             Show version
+  npx polyforge help                  Show this help
+
+After install, use these slash commands in Claude Code:
+  /init            Scan & configure current project
+  /pr-review       Review a PR (fresh context + CI check)
+  /analyse-db      Analyze database schema
+  /analyse-code    Full codebase analysis
+  /report-issue    Detect & report issues
+  /fix             Fix a specific issue
+  /fix-ci          Diagnose & fix CI failures (max 3 retries)
+  /brainstorm      Brainstorm a feature or fix
+  /generate-doc    Generate Claude-optimized documentation
+`);
+}
+
+function isSymlinkTo(linkPath, targetPath) {
+  try {
+    return readlinkSync(linkPath) === targetPath;
+  } catch {
+    return false;
+  }
+}
+
+function isValidSkillName(name) {
+  return /^[a-z0-9-]+$/.test(name) && !name.includes('..');
+}
+
+function safeUnlink(filepath) {
+  try {
+    const stat = lstatSync(filepath);
+    if (stat.isSymbolicLink() || stat.isFile()) {
+      unlinkSync(filepath);
+      return true;
+    }
+  } catch {
+    // skip
+  }
+  return false;
+}

package/hooks/pre-commit-check.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# PolyForge pre-commit hook
+# Blocks commits with .env files and runs tests
+
+set -e
+
+# Block .env files from being committed
+STAGED_ENV=$(git diff --cached --name-only | grep -E '\.env(\..+)?$' || true)
+if [ -n "$STAGED_ENV" ]; then
+  echo "[PolyForge] Blocked: .env files must not be committed:"
+  echo "$STAGED_ENV"
+  echo "Add them to .gitignore instead."
+  exit 1
+fi
+
+# Run tests
+if [ -f "package.json" ]; then
+  npm test 2>&1 || { echo "[PolyForge] Tests failed — commit blocked"; exit 1; }
+elif [ -f "composer.json" ]; then
+  composer test 2>&1 || php vendor/bin/phpunit 2>&1 || { echo "[PolyForge] Tests failed — commit blocked"; exit 1; }
+elif [ -f "go.mod" ]; then
+  go test ./... 2>&1 || { echo "[PolyForge] Tests failed — commit blocked"; exit 1; }
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+  python -m pytest 2>&1 || { echo "[PolyForge] Tests failed — commit blocked"; exit 1; }
+fi
+
+echo "[PolyForge] ✓ Pre-commit checks passed"

package/hooks/pre-push-verify.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# PolyForge pre-push verification hook
+# Runs tests, linter, and vulncheck before allowing push
+#
+# Install: Add to .claude/settings.json hooks or use as git pre-push hook
+
+set -e
+
+CONFIG_FILE=".claude/polyforge.json"
+
+if [ ! -f "$CONFIG_FILE" ]; then
+  echo "[PolyForge] No config found. Run /init first."
+  exit 0
+fi
+
+echo "[PolyForge] Running pre-push verification pipeline..."
+
+# Detect and run test command
+if [ -f "package.json" ]; then
+  echo "  → Running tests (npm)..."
+  npm test 2>&1 || { echo "  ✗ Tests failed"; exit 1; }
+elif [ -f "composer.json" ]; then
+  echo "  → Running tests (composer)..."
+  composer test 2>&1 || php vendor/bin/phpunit 2>&1 || { echo "  ✗ Tests failed"; exit 1; }
+elif [ -f "go.mod" ]; then
+  echo "  → Running tests (go)..."
+  go test ./... 2>&1 || { echo "  ✗ Tests failed"; exit 1; }
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+  echo "  → Running tests (python)..."
+  python -m pytest 2>&1 || { echo "  ✗ Tests failed"; exit 1; }
+fi
+
+# Detect and run linter
+if [ -f ".eslintrc.js" ] || [ -f ".eslintrc.cjs" ] || [ -f ".eslintrc.json" ] || [ -f ".eslintrc.yml" ] || [ -f "eslint.config.js" ] || [ -f "eslint.config.mjs" ] || [ -f "eslint.config.cjs" ] || [ -f "eslint.config.ts" ]; then
+  echo "  → Running linter (eslint)..."
+  npx eslint . 2>&1 || { echo "  ✗ Lint failed"; exit 1; }
+elif [ -f "phpstan.neon" ] || [ -f "phpstan.neon.dist" ]; then
+  echo "  → Running linter (phpstan)..."
+  php vendor/bin/phpstan analyse 2>&1 || { echo "  ✗ Lint failed"; exit 1; }
+elif [ -f ".golangci.yml" ] || [ -f ".golangci.yaml" ]; then
+  echo "  → Running linter (golangci-lint)..."
+  golangci-lint run 2>&1 || { echo "  ✗ Lint failed"; exit 1; }
+fi
+
+echo "[PolyForge] ✓ All checks passed"

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "polyforgeai",
+  "version": "0.1.0",
+  "description": "Self-adaptive Claude Code plugin for automated software development workflows",
+  "bin": {
+    "polyforge": "./bin/polyforge.js"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.js",
+    "polyforge": "node bin/polyforge.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "developer-tools",
+    "code-review",
+    "automation",
+    "skills",
+    "workflow"
+  ],
+  "author": "kiloumap",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vekta/polyforge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Vekta/polyforge/issues"
+  },
+  "homepage": "https://github.com/Vekta/polyforge#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "skills/",
+    "rules/",
+    "hooks/",
+    "templates/",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "devDependencies": {}
+}

package/rules/golden-principles.md

@@ -0,0 +1,22 @@
+# PolyForge Golden Principles
+
+## Code Quality
+1. Every change includes tests that verify the new behavior
+2. Functions have a single responsibility
+3. Error handling is explicit — every error path has intentional handling
+
+## Architecture
+4. Dependencies flow inward — infrastructure depends on domain, not the reverse
+5. Business logic lives in the service/domain layer, not in controllers or repositories
+6. External services are accessed through interfaces/abstractions
+7. Configuration comes from environment variables
+
+## Workflow
+8. Commits are atomic — one logical change per commit
+9. Documentation stays in sync with code changes
+10. Flag breaking changes explicitly with migration steps
+
+## Resilience
+11. Retry a failing approach at most 3 times — then try a different angle or ask for help
+12. Same error with same fix twice means the approach is wrong — switch strategy
+13. Scope investigations to specific files or directories — avoid reading the entire codebase

package/rules/security.md

@@ -0,0 +1,18 @@
+# PolyForge Security Rules
+
+## Secrets
+1. Credentials, API keys, and tokens live in environment variables
+2. Example env files (`.env.example`) use placeholder values only
+
+## Input Validation
+3. All user input is validated at system boundaries (controllers, API handlers)
+4. Shell commands use argument arrays, not string concatenation with user input
+
+## Authentication & Authorization
+5. Every endpoint that modifies data requires authentication
+6. Authorization checks happen at the service layer, not just the controller
+7. Sensitive operations require re-authentication or confirmation
+
+## Data Protection
+8. Sensitive data is excluded from logs and error messages
+9. API responses include only the fields the consumer needs

package/rules/testing.md

@@ -0,0 +1,14 @@
+# PolyForge Testing Rules
+
+## Structure
+1. Test names describe behavior: "it should {expected} when {condition}"
+2. Each test verifies one behavior
+3. Test data uses factories or fixtures, not hardcoded magic values
+
+## Coverage
+4. Every public method in a service has at least one test
+5. Critical paths (auth, payments, data mutations) have thorough test coverage
+
+## Quality
+6. Tests that pass without the implementation being correct are rewritten
+7. Time-dependent tests use frozen clocks; order-dependent tests use explicit setup