jsf

[!WARNING] Work in Progress — Expect Daily Breaking Changes

This plugin is under active development and is not stable. The workflow, commands, skills, and configuration are subject to change at any time — often daily. If you are using this, expect things to break. There is no guarantee of backwards compatibility between any two versions. Proceed accordingly.

John's Software Factory (JSF)

An intelligent, phased workflow plugin for Claude Code that takes software projects from initial idea through complete, validated implementation. JSF enforces test-driven development discipline, security review gates, and structured human validation checkpoints — so you ship code that works and is safe.

Philosophy

• Simple over clever: JSF builds only what you ask for, with no speculative features or premature abstractions
• Safety by default: hooks block dangerous shell, git, and SQL commands before they execute
• Validated progress: each phase must pass automated tests and (when required) manual review before proceeding
• Persistent state: work survives interruptions via a file-based memory system; resume where you left off

---

Getting Started

Installation via Plugin Marketplace

1. Open Claude Code and navigate to Settings → Plugins → Marketplace
2. Search for "jsf" or "John's Software Factory"
3. Click Install

That's it. No additional setup is required for basic use.

Optional: OpenTelemetry Tracing

JSF emits OpenTelemetry spans for every Claude session and tool call, giving you APM-style visibility into what Claude is doing and how long each step takes. Traces appear in Jaeger (or any OTLP-compatible backend) with no extra configuration beyond enabling Claude Code's standard telemetry.

Enable tracing by setting these env vars before running claude:

# Required — opt in to Claude Code telemetry (enables JSF tracing hooks too)
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# Point at your OTLP collector (gRPC)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Once set, every Claude session automatically produces:

Span	When emitted
claude.session	Root span — opened on session start, closed on stop
claude.tool_call	One child span per tool invocation (Bash, Read, Edit, etc.)
claude.session.stop	Session ended normally
claude.session.subagent_stop	Sub-agent completed
claude.session.compact	Context compaction triggered
claude.session.notification	Notification event fired
factory.task	Full JSF workflow run (linked to claude.session)
factory.phase	Each implementation phase (linked to claude.session)

All spans are sent to your OTLP collector under service.name=jsf. View them in the Jaeger UI at http://localhost:16686 — select service jsf and you'll see the full trace tree for your session.

See the Claude Code monitoring documentation for the full list of supported environment variables, multi-team tagging, and backend configuration options.

Running the Local Observability Stack

The observability/ directory contains a ready-to-run Docker Compose stack that receives, stores, and visualises all three OTel signal types — metrics, traces, and logs — using entirely open-source components:

Component	Image	Purpose
otel-collector	otel/opentelemetry-collector-contrib:0.92.0	Receives OTLP and fans out to backends
Prometheus	prom/prometheus:v2.48.0	Metric storage and query
Jaeger	jaegertracing/all-in-one:1.53	Trace storage and UI
Loki	grafana/loki:2.9.3	Log storage
Grafana	grafana/grafana:10.2.3	Unified dashboard (datasources pre-wired)

Start the stack:

cd observability/
docker compose up -d

Service endpoints:

Service	URL
Grafana	http://localhost:3000 (admin / admin)
Prometheus	http://localhost:9090
Jaeger UI	http://localhost:16686
Loki	http://localhost:3100/ready
OTLP gRPC	localhost:4317
OTLP HTTP	localhost:4318

Stop and remove volumes:

docker compose down -v

---

Configuring Claude Code to Send Telemetry to the Stack

Claude Code can export metrics and events to the local collector via the standard OpenTelemetry environment variables. Set these before running claude:

# Required — opt in to telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# Send both metrics and logs/events over OTLP
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp

# Point at the local collector's gRPC endpoint
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317