Repository navigation
Fix the runbook's Workflows doctor step; document today's behavior - #52
Merged
jacobprall merged 4 commits intoOct 25, 2026
Merged
Conversation
- The runbook asked for doctor in the factory-workflows Render Shell, but a Workflows service has no Shell: Render starts a short-lived instance per task run. The runbook, operations guide, quickstart, and AGENTS.md now run the Workflows check locally with that service's values and deployed slug. - Operations: GitHub's Recent Deliveries is now the record of why a webhook started nothing, so the troubleshooting guide explains the gateway's responses and ignore reasons, its 422 and 502 log lines, how to read why an agent's submission was rejected, how to refresh a snapshot by hand, and how to clear a status comment stuck on "running". - The runbook expects doctor's "no webhook deliveries yet" warning before the smoke test, and can confirm telemetry from the smoke test's log line. - AGENTS.md: the gateway no longer depends on events; agent output objects must be strict. - Architecture: the Sandbox invariant matches AGENTS.md, two residual risks are added, and the code map lists claiming-task.ts. - /factory cancel now clears a status comment left on "running" by a run that already stopped, instead of replying that nothing is running. - tests/agents-catalog.test.ts enforces strict output schemas for every agent.
Use the repository's own spelling for the product name in docs, the runbook, the Blueprint comment, and the GitHub App description that setup:app sends. Agent prompts keep "an unattended software factory", which describes the concept rather than naming the product.
render.yaml now creates factory-gateway and factory-workflows in the production environment of a software-factory project, so a deployment shows up as one project in the Render Dashboard. The docs that describe what the Blueprint creates, and the add-a-database recipe, follow the new layout.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A review of every doc and the runbook against the current code.
Corrections
doctor: the runbook asked fordoctorin thefactory-workflowsRender Shell, but a Workflows service has none (Render starts a short-lived instance per task run, andrender sshdoesn't recognize workflow IDs). The runbook, operations guide, quickstart andAGENTS.mdnow run the Workflows check locally with that service's values and its deployed slug, which can carry a suffix.AGENTS.mdno longer says the gateway importsevents.docs/operations.mdexplains the gateway's responses and ignore reasons, plus its 422 and 502 log lines.architecture.mdnow matchesAGENTS.md.Newly documented
agent.finishedlog line.sandbox/changes.configuration.mdlinks to it.doctor's expected "no webhook deliveries yet" warning before the smoke test, and an optional telemetry check on the smoke test.CONTRIBUTING.mdandAGENTS.md.claiming-task.ts.Code
/factory cancelnow clears a status comment left on "running" by a run that already stopped, and terminates any Sandbox it left, instead of replying that nothing is running.tests/agents-catalog.test.tsenforces strict output schemas for every agent. I checked that it fails when one schema is loosened.Verification
npm run check: lint, typecheck, and 110 tests.