Skip to content

installation.md

Latest commit

 

History

History
119 lines (88 loc) · 4.24 KB

installation.md

File metadata and controls

119 lines (88 loc) · 4.24 KB
Raw

Installing SpecForge

SpecForge installs in one line as a Claude Code plugin, and its skills are also installable into any skills.sh-compatible agent. Pick the path that fits you.

Prerequisites

  • Claude Code — latest version. If you don't see the /plugin command, update Claude Code first.
  • git — for the marketplace source.
  • Node.js (optional) — only for the skills.sh install path (npx).

Option 1 — Claude Code plugin (recommended)

The full experience: commands + skills + subagents + the enforced gate.

/plugin marketplace add pooyagolchian/specforge
/plugin install specforge@specforge
/reload-plugins

Non-interactive / scripted equivalent:

claude plugin marketplace add pooyagolchian/specforge
claude plugin install specforge@specforge

Option 2 — skills.sh (any agent, skills only)

Installs the lifecycle skills into 70+ agents. The skills still guide the workflow and write the specforge/ artifacts — but the enforcement hooks (the gate) ship only with the Claude Code plugin, so on this path the gate is advisory, not enforced.

npx skills add pooyagolchian/specforge          # all skills
npx skills add pooyagolchian/specforge --list     # preview first

Option 3 — From source (try before you install / develop)

git clone https://github.com/pooyagolchian/specforge
claude --plugin-dir ./specforge/plugins/specforge   # loads it for this session only

--plugin-dir also accepts a .zip. A local --plugin-dir copy overrides an installed same-named plugin for that session — handy while developing.

Option 4 — Team provisioning

Commit this to your repo's .claude/settings.json so teammates who trust the repo are prompted to install automatically:

{
  "extraKnownMarketplaces": {
    "specforge": { "source": { "source": "github", "repo": "pooyagolchian/specforge" } }
  },
  "enabledPlugins": { "specforge@specforge": true }
}

First run — and see the gate work

/specforge:init

Then fill in specforge/inputs/vision.md and tech-environment.md, and watch the gate enforce spec-before-code:

Step What happens
Ask Claude to edit a source file now 🚫 Blocked — no approved spec/plan
/specforge:specify "…" → /specforge:plan drafts the spec + plan
/specforge:approve specify && /specforge:approve plan ✅ gate opens
Ask Claude to edit again allowed — building under the approved plan
/specforge:quick fast-track a trivial change past the gate (audited)

Updating

/plugin marketplace update

SpecForge pins a semver version, so you receive an update when a new version is released. See the CHANGELOG.

Uninstalling

/plugin uninstall specforge@specforge
/plugin marketplace remove specforge        # optional: forget the marketplace

The committed specforge/ workspace in your project is just files — delete it if you no longer want the artifacts.

Troubleshooting

Symptom Fix
No /plugin command Update Claude Code to the latest version
Commands don't appear after install Run /reload-plugins
/specforge:* not namespaced as expected Confirm the plugin name is specforge (/plugin)
The gate never blocks It's inert without a specforge/ workspace — run /specforge:init; and remember the gate ships only with the plugin, not the skills.sh install
The gate blocks after approval Check specforge/state.md: the active feature's specify and plan rows must read approved
Private/enterprise repo won't clone Configure a git credential helper for the marketplace source

Install methods at a glance

Method Command Gets the gate? Best for
Plugin marketplace /plugin install specforge@specforge ✅ Everyone (recommended)
skills.sh npx skills add pooyagolchian/specforge ❌ (skills only) Non-Claude-Code agents
From source claude --plugin-dir … ✅ Trying it / development
Team settings extraKnownMarketplaces + enabledPlugins ✅ Auto-provisioning a team