ReadySignal

Diagnose what's blocking your delivery process — and bring it up.

ReadySignal analyzes your project's delivery health across 7 categories, generates technical + executive reports, AND boots the project's runtime environment via a unified readysignal up / readysignal down command pair (D-091).

Requirements

• Node.js >= 24
• Bun >= 1.3 (the engine runs on Bun; Node is fine for the CLI itself)
• Docker + Docker Compose >= 2.24.4 (only when the project uses compose)
• Claude Code >= 0.24 installed and authenticated, OR the ANTHROPIC_API_KEY env var set (the agent supervisor uses Claude when available; without it the CLI falls back to a manual-investigation hint)
• A ReadySignal token (free at readysignal.io)

Install

npm install -g @rigelrise/readysignal

Commands

readysignal analyze [path]

Run the 7-category assessment on a project directory. Generates readysignal-technical-report.md, readysignal-manifest.{json,md}, and readysignal-executive-report.pdf.

readysignal up [path]

Bring a project up via the ReadySignal engine. Zero-flag in the common case:

cd your-project
readysignal up

Flow (per data-model.md §"up command flow"):

1. Project root discovery (ascends for readysignal-manifest.json > package.json > compose file > .git/).
2. Token gate (uses your existing ~/.readysignal/config.json token).
3. Manifest detection — if absent or older than 7 days, runs analyze inline.
4. Compose detection → auto-enables port allocation (use --no-allocate-ports to disable).
5. Missing-input collection from manifest.missingEnvVars[] + UPPER_SNAKE tokens in externalResources[].requiresTeamInput[]. Prompts interactively for any not pre-supplied via --input KEY=value.
6. envId resolution (--env-id <id> overrides; otherwise derived as rs-<project>[-<name>]).
7. Per-invocation logDir at ~/.readysignal/runs/<rootHash>/<runDirId>/ (timestamped + random suffix; events.jsonl never collides across runs).
8. Engine spawn via Bun. Engine prints user-facing narration (step events, healthcheck status, decision verdict).
9. On healthz 200, the project is up. The CliRun is persisted to ~/.readysignal/runs/<rootHash>.json so readysignal down can find it later.

Options:

| Flag | Effect | |---|---| | --env-id <id> | Override the auto-derived envId (e.g., rs-my-project-qa-1) | | --name <name> | Human-readable env alias; combines with project name to derive a distinct envId (multi-env support — see SC-003 below) | | --no-allocate-ports | Disable the auto port allocator for compose projects | | --input KEY=value | Repeatable. Pre-supply a missing input so the prompt skips it | | --non-interactive | Fail instead of prompting (CI-friendly). Also suppresses the agent supervisor's ask-user proposals |

readysignal down [runId]

Tear down a project run started via readysignal up. Zero-flag in the common case:

cd your-project
readysignal down

Flow:

1. Reads the CLI state file. If it's missing or corrupt, falls back to scanning ~/.readysignal/runs/<rootHash>/*/runs/*.json for project records (FR-012 fallback).
2. Classifies each candidate as active (live containers/processes), suspicious (engine crashed mid-run; status:running RunRecord with no live resources), or inactive (already torn down).
3. Single active → auto-pick. Multiple active → numbered selection list.
4. Active path: invokes the engine down subcommand against the recorded logDir.
5. Suspicious path: label-based docker cleanup (com.docker.compose.project=<envId>) — containers FIRST, networks SECOND, volumes LAST. Retain-on-partial-failure: if any resource errored, the entry stays in the state file so the next down surfaces it for retry.
6. State file updated with tornDownAt on success.

Options:

| Flag | Effect | |---|---| | --env-id <id> | Tear down by engine envId (resolves to a CliRun) | | --name <name> | Human-readable alias (resolves the same way as up --name) | | --latest | Tear down the most recent run for this project | | --log-dir <path> | Escape hatch for engine-direct runs not in the state file | | --dry-run | Preview teardown without removing resources | | --force-unlink-modified | Remove user-modified files (D-080 override; explicit consent required) | | --force-forget | Drop the run from the state file without calling docker (when the engine never recorded resources) | | --non-interactive | Fail instead of prompting (CI-friendly) |

readysignal status

Show current configuration + readiness.

Multi-environment coexistence (SC-003)

# Terminal A:
readysignal up --name iso-a

# Terminal B:
readysignal up --name iso-b

Distinct envIds → distinct compose project labels → distinct ports/networks/containers. readysignal down --name iso-a tears only that env. The --name segment is sanitized byte-for-byte against the engine's env-id sanitizer (paired contract test enforces parity).

Agent supervisor (D-091 US4)

When up or down fails, the CLI invokes a focused specialist via Claude Code:

| Failure phase | Specialist | Routing rule | |---|---|---| | up.preflight (compose-shape blocks) | compose-diagnoser | phase mapping | | up.step / up.connector | runtime-diagnoser | phase mapping | | Incomplete RunRecord (engine crashed) | cleanup-advisor | overrides phase — orphan resources are the priority | | down cleanup ambiguity | cleanup-advisor | phase mapping | | Manifest staleness, input ambiguity | input-resolver | phase mapping |

The specialist proposes ONE of: explain | suggest-command | suggest-patch | ask-user | give-up. The CLI never auto-applies any proposal:

• suggest-command: shown with rationale + confirm prompt. Destructive commands (regex match against rm, docker rm, git reset --hard, git clean -f, git push --force, git branch -D, unlink, chmod -R, sudo) get an explicit DESTRUCTIVE label and default-N. The CLI overrides the specialist's destructive flag if the regex matches — specialist is advisory, CLI is authoritative.
• suggest-patch: target path is symlink-resolved and rejected if it escapes the project tree (sibling-prefix attacks like /foo/bar vs /foo/bar-evil are caught). Diff shown; confirm prompt; on y, file written via fs (NEVER subprocess).
• ask-user: prompt with optional shortlist; answer passed back to the supervisor for one round-trip (no recursion in MVP).
• give-up: printed; CLI exits non-zero with the supervisor's reason.

Every supervisor invocation appends one line to ~/.readysignal/agent-log.jsonl with a strict whitelist (ts, role, phase, failureClassSignature 16-char SHA, proposalKind, destructiveProposed, userAction, success, durationMs, runId, envId). Raw error messages, command strings, prompts, and diffs NEVER appear in the log — only the SHA hash. The hash is deterministic for identical contexts, so recurring failure classes cluster naturally for crystallization review.

Disable agent: set READYSIGNAL_DISABLE_AGENT=1 in your environment (TODO — currently agent simply skips when Claude is not configured). Force a specific specialist for debugging: READYSIGNAL_FORCE_AGENT=cleanup-advisor (fail-loud on invalid role).

Environment overrides

| Variable | Purpose | |---|---| | READYSIGNAL_V0_BIN | Absolute path to a custom engine binary. Bypasses the resolution chain — use for testing engine forks or pre-release builds. | | READYSIGNAL_FORCE_AGENT | Force routing to a specific specialist. Valid: runtime-diagnoser | compose-diagnoser | input-resolver | cleanup-advisor. Invalid values fail-loud. | | ANTHROPIC_API_KEY | If set, hasClaudeCode short-circuits to true (you don't need claude auth login). | | RS_PAID_LOG_DIR | (Engine-side) override the engine's log directory. CLI sets this automatically per-invocation; users typically don't touch it. | | RS_CONNECTORS_DIR | (Engine-side) override the engine's connectors directory. CLI sets this on the cache resolution path (D-091c). |

What the assessment measures

ReadySignal scores 7 delivery categories (0–2 each, total 0–14):

| Category | What it measures | |----------|-----------------| | Dev onboarding | How fast can a new developer run the project? | | Automated delivery | Can changes be delivered without manual work? | | Testing difficulty | How many systems need to be running to test a feature? | | Tech maintenance | How complex is the technology stack to maintain? | | Auto validation | Are changes automatically verified before delivery? | | Change impact | How much does one change affect the rest of the system? | | Security risk | Are credentials properly protected? |

Reports

After analyze, three artifacts are generated in your project directory:

• readysignal-technical-report.md — Detailed findings with file paths + evidence. For your engineering team.
• readysignal-manifest.{json,md} — Operational manifest used by up (steps, modes, missing inputs, external resources).
• readysignal-executive-report.pdf — Business-facing summary. Designed to share with leadership.

How it works

1. Your code is analyzed locally by Claude Code (your API key, your machine).
2. ReadySignal never sees or stores your source code.
3. Assessment findings are sent to ReadySignal's server only to generate the executive summary.
4. up spawns a Bun subprocess running the ReadySignal engine. Inputs are written to the subprocess's stdin (NEVER passed via argv — secrets stay off ps aux).
5. The engine writes a RunRecord at <logDir>/runs/<runId>.json (schema 2.5.0, discriminated on status). The CLI reads it post-exit to determine the outcome.

License

BUSL-1.1