sig

Signal

Disciplined AI development workflow with a project-complexity calibration layer. Right-sized rigor per project tier — so you don't over-engineer throwaways or under-engineer production systems.

Signal is a Claude Code plugin. Run a six-phase workflow (calibrate → discuss → plan → execute → verify → review → ship) where every phase reads a PROFILE.md written at calibration time, and that drives whether you get TDD, four research agents, an 8-dimension plan validation, a full security audit, all of those — or none of them.

A 30-line throwaway script doesn't need ceremony. A production service handling other people's data does. Signal calibrates once and the workflow self-tunes.

Why this exists

Most AI-development workflows pick a fixed level of rigor. Heavy frameworks demand TDD + plans + reviews on every change; light frameworks skip discipline even when stakes are real. Both fail at the wrong end. Signal asks five diagnostic questions, classifies the work into one of four tiers (SKETCH / FEATURE / SPIKE / FULL), and then every downstream phase reads that classification as its first action.

In Signal's own dogfood:

Tier	Throwaway	Wall clock	Source LOC	Tests	Research agents	.planning/ artifacts
SKETCH	CSV-to-JSON one-shot	~5 min	~30	0 (smoke only)	0	8
FULL	Production URL shortener	~2 hours	~600	39	4	13

Same tooling. Same commands. The difference is calibration.

That FULL run is committed as a worked example you can read end to end: examples/url-shortener/ — the complete .planning/ chain (calibrate → ship) plus a runnable, zero-dependency service. Its README walks through why the project calibrated FULL and what each phase produced.

Install

Requirements & compatibility

Component	Notes
Node.js 22+	ESM, no native modules
Claude Code 2.1.141+	That release shipped the CLAUDE_CODE_PLUGIN_PREFER_HTTPS env var used by the troubleshooting workaround below
Operating system	Verified on macOS; Linux/WSL untested — see docs/install-verification.md for the verification matrix
Git	Any modern version (.planning/ requires a git repo to be useful)

Via Claude Code plugin marketplace

/plugin marketplace add insightriot/signal
/plugin install sig@signal
/reload-plugins

Then try /sig:calibrate to confirm the install. Signal's /sig:* commands should autocomplete.

Troubleshooting install

If /plugin install fails with Permission denied (publickey) or Could not read from remote repository, your machine has a non-default SSH config (multi-identity hosts, IdentitiesOnly yes, or no default Host github.com) and Claude Code's plugin loader is reaching for SSH. Two documented escape hatches:

1. Use Anthropic's HTTPS-prefer env var (Claude Code 2.1.141+):

   export CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1
   

   Then retry the install. This is the cleanest fix and doesn't change your SSH config.

2. Or install from a local clone (no marketplace fetch involved):

   GIT_CONFIG_GLOBAL=/dev/null git clone https://github.com/InsightRiot/signal ~/signal
   

   Then in Claude Code: /plugin marketplace add ~/signal → /plugin install sig@signal.

As of v0.1.1, Signal's marketplace.json pins HTTPS explicitly, so option 1 should rarely be needed — but it's there if some other plugin in your stack triggers the same path.

For other install symptoms — /plugin install reporting "already at latest" while running stale code, missing Uninstall verb in the /plugin UI, plugin staying Disabled after reinstall, pre-rename signal@signal cache orphans — see docs/install-troubleshooting.md.

From source (for development or hacking on Signal itself)

git clone https://github.com/InsightRiot/signal
cd signal
npm install
node tools/validate-plugin.js   # should report all checks green
npm test                        # 777 tests should pass

Then point Claude Code at the local plugin directory (settings → plugins → load from path), or symlink into your ~/.claude/plugins/ if you prefer.

${CLAUDE_PLUGIN_ROOT} for development. Several command markdown files reference paths like ${CLAUDE_PLUGIN_ROOT}/skills/... and ${CLAUDE_PLUGIN_ROOT}/state/config.json. Claude Code sets this env var when the plugin is installed via the marketplace. For local development (or when dogfooding Signal-on-Signal), set it manually before running Claude Code:

export CLAUDE_PLUGIN_ROOT="$(pwd)"   # from the Signal repo root

Without it, command markdown still works — Claude resolves the literal path from context — but explicit is faster.