forge-spec

Orchestrates spec-driven design brainstorming and enriches specs with architecture, ADR, and impact analysis.

1|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/jp5labs/forge-workflow --skill forge-spec-jp5labs
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: forge-spec
Source: https://github.com/jp5labs/forge-workflow/tree/main/forge_workflow/templates/skills/forge-spec
Command: npx skills add https://github.com/jp5labs/forge-workflow --skill forge-spec-jp5labs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Turning a rough idea into an approved, analysis-backed design spec requires structured brainstorming, architecture review, ADR compliance checks, and impact assessment — doing this manually is slow and inconsistent. This Skill orchestrates the entire ideation-to-approved-spec workflow so every design decision is documented, validated, and traceable. ## Core Features & Use Cases - Guided Design Brainstorming: Wraps the superpowers brainstorming skill with template, output path, and exit overrides to produce a structured spec in docs/specs/. - Conditional Analysis Enrichment: Dispatches parallel Sonnet subagents for ADR compliance, architecture review, impact analysis, dependency graphing, and scenario comparison based on spec content. - Conflict Resolution and Review Gate: Surfaces contradictions between design and analysis findings, runs a spec quality review, and enforces an explicit user approval gate before proceeding. - Use Case: After /forge-discover classifies a feature as High complexity, run /forge-spec "retrieval caching" to brainstorm the design, automatically validate it against ADRs and the platform map, and exit with an approved spec ready for issue decomposition via /forge-shape. ## Quick Start Invoke /forge-spec with a short topic like "bot notification routing" to start an interactive design session that ends with an approved, analysis-enriched spec file.

Frequently Asked Questions about forge-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a design spec before implementing a feature?

Run /forge-spec with a short topic to start an interactive brainstorming session that produces a structured spec in docs/specs/. The skill then enriches it with architecture, ADR, and impact analysis before you approve it.

When should I use forge-spec instead of going straight to planning?

Use forge-spec when /forge-discover classifies work as Medium, High, or Epic complexity, or whenever formal design is needed before implementation. For Trivial or Low complexity work, skip it and use /forge-shape directly.

Does forge-spec create GitHub issues or implementation plans?

No. forge-spec only produces an approved spec file. Issue creation is handled by /forge-shape and implementation planning by /forge-plan, which the skill points you to after approval.

What happens if an analysis subagent fails during spec enrichment?

The failure is reported and that analysis section is marked as unavailable with an error summary. The rest of the flow continues unblocked, and you can re-run the specific analysis later.

Can forge-spec skip the user approval gate for simple specs?

No. The skill explicitly requires explicit user approval before exiting under any circumstances, even when no analyses were triggered and no conflicts were found.