PolyForge

Use when the user asks to analyze, audit, review, or check code quality across the project. Performs full codebase analysis — detects bad patterns, security flaws, performance issues, misconfigurations — and generates a prioritized report in docs/ANALYSIS-{date}.md.

Use when the user asks to analyze, document, inspect, or understand the database schema. Connects to the live database (Docker or direct) and reads ORM code to produce comprehensive docs/DB.md with tables, relations, indexes, and query patterns.

Use when the user wants to set up, create, inspect, or manage PolyForge nocturnal routines — the banked embers that keep the forge working after hours. Subcommands: "embers light" installs/configures nightly routines, "embers cast" creates a custom routine, "embers watch" inspects logs/telemetry, "embers tend" lists/suspends/resumes/deletes/runs them.

Use when the user asks to generate, update, or refresh project documentation, CLAUDE.md, context files, or scoped rules. Creates Claude-optimized documentation with a short CLAUDE.md (<200 lines), detailed docs/CONTEXT.md, and path-scoped rules.

Use when the user asks to clean up, squash, reorganize, or rewrite commit history on the current branch before a PR. Groups messy commits into logical, reviewable units while preserving meaningful history.

Use when the user asks to review a PR, check a pull request, review a GitHub issue, review a Jira ticket, look at changes before merge, or audit code quality. Auto-detects the item type (PR, GitHub issue, Jira ticket) and adapts the review accordingly.

Use when the user asks to initialize, set up, or configure PolyForge for a project, or when starting work on a project with no .claude/polyforge.json. Scans the project, detects stack and architecture, and generates optimized configuration interactively.

Use when the user wants to file a bug, create an issue, report a problem, or scan code for issues to report. Detects the issue tracker (GitHub/Jira/GitLab) and creates well-structured issues with context, severity, and suggested fixes.

Use when the user asks to investigate, diagnose, analyze, or understand a specific problem — an exception, error, unexpected behavior, log entry, or stack trace. Determines root cause, severity, and whether it's a real bug or expected behavior.

Use when CI/CD checks fail on a PR or branch, when the user says "CI is broken", "build failed", "tests fail in CI", or "fix the pipeline". Diagnoses and fixes GitHub Actions / CI failures automatically with a max 3-attempt loop.

Use when the user wants to brainstorm, explore ideas, plan a feature, discuss a technical approach, or think through a problem before implementing. Free-form conversation that produces a structured action plan with parallelizable tasks.

Use when the user asks to implement, build, develop, add, fix, or resolve work described by an issue or ticket (e.g. "smith

Use when the user asks to add, create, or configure a new rule, convention, or constraint for the project without re-running /forge. Creates or updates scoped rule files in .claude/rules/.