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

npx polyforgeai install

This symlinks PolyForge skills and rules into ~/.claude/, making them available in any Claude Code session.

Restart Claude Code after installing or updating PolyForge — skills are loaded at session start.

Quick Start

1. Install PolyForge and restart Claude Code
2. If your project already has a .claude/ directory with custom commands or skills, back it up first (mv .claude .claude-backup) — /forge will recreate it cleanly
3. Open Claude Code in your project
4. Run /forge — PolyForge scans your project and generates an optimized configuration
5. Use any command: /review, /fix #123, /brainstorm, etc.

Commands

| Command | Description | |---------|-------------| | /forge | Scan project, detect stack/architecture, generate config interactively | | /review | Review a PR, GitHub issue, or Jira ticket — checks CI, 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 | | /diagnose | Investigate a specific error or behavior — determine root cause and if it's a real bug | | /report-issue | Detect and create issues on GitHub/Jira/GitLab | | /feature #N | Build a feature from an issue — plan, implement, test, PR | | /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) | | /squash | Clean up commit history — regroup messy commits into logical units before PR | | /add-rule | Add project rules or conventions without re-running /forge |

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 /forge, 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 /forge:

• 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 /forge, you'll be asked whether to grant full permissions for the project.

Via /forge (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):

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:

npx polyforgeai install                  # Install all skills & rules
npx polyforgeai install --force          # Reinstall, overwriting existing
npx polyforgeai add-skill 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 /forge:

• 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

npx polyforgeai update

Uninstall

npx polyforgeai uninstall

Requirements

• Node.js >= 18
• Claude Code CLI

Issue tracker CLIs (install only what you use):

• GitHub CLI — GitHub Issues
• GitLab CLI — GitLab Issues
• Jira CLI or API token — Jira

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