Skip to content
Back to search

software-factory

MarketplaceWorks with Claude CodeGitHub

The Software Factory, as an installable Claude Code plugin.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bhagavansuraj--software-factory/badge.svg)](/listings/bhagavansuraj--software-factory)

HTML

<a href="/listings/bhagavansuraj--software-factory"><img src="/api/listings/bhagavansuraj--software-factory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

As a Claude Code plugin:

claude plugin marketplace add bhagavansuraj/software-factory
claude plugin install software-factory@software-factory

Or copy `skills/*` into `.claude/skills/` and `agents/*` into `.claude/agents/`, either in your repo (so the factory travels with the code) or in `~/.claude/` (so every project can use it).

Then, in your project:

/factory init        # once per repo: .factory.json, docs/factory.md, RFC template, ADR index, labels
/factory ISSUE-42    # run or resume an issue

Companion skills

The Grill station uses `/grill-with-docs`, `/grilling` and `/domain-modeling` from [Matt Pocock's skills](https://github.com/mattpocock/skills). I didn't write them, so they aren't included here. Install them separately:

claude plugin install mattpocock-skills@claude-plugins-official

If you don't have them installed, the factory skips the Grill station and starts at Design.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "software-factory",
  3. "owner": { "name": "Suraj Bhagavan", "url": "https://github.com/bhagavansuraj" },
  4. "description": "The Software Factory, as an installable Claude Code plugin.",
  5. "plugins": [
  6. {
  7. "name": "software-factory",
  8. "source": "./",
  9. "description": "Approval-gated delivery pipeline: RFC design, TDD, adversarial review, resumable handoffs.",
  10. "category": "engineering",
  11. "keywords": ["factory", "rfc", "adr", "tdd", "code-review"]
  12. }
  13. ]
  14. }
README.md · README · 123 lines
  1. # Software Factory
  2. An approval-gated delivery pipeline for building software with Claude Code. Every issue moves
  3. through the same stations, and nothing advances past a ✋ gate without a human saying so:
  4. ```
  5. Grill → ✋ → RFC design → ✋ → TDD test plan → ✋ → Code (sandboxed worktree)
  6. → PR + test evidence → Adversarial review → ✋ → Deploy → Verify in prod
  7. ```
  8. I built this to run a production SaaS product (a Cloudflare Workers + React app) where I wanted myself and another person, who has a product background to be able to safely make contributions, while retaining ownership on the system design.Claude did most of the typing. Over several hundred PRs it became the
  9. part I'd most want to take to the next project.
  10. ## Why it exists
  11. Agents write code fast, and they forget decisions just as fast. The factory is built around four
  12. ideas:
  13. - **Decide in writing before writing code.** Each issue gets an RFC. Decisions that cut across
  14. issues are promoted to ADRs, and the design station has to read **every** ADR before it proposes
  15. anything. Six months in, the agent still knows why the system looks the way it does. This is a method I have used myself with my teams, and it applies equally to agents.
  16. - **Tests are the spec.** The TDD station turns the approved RFC into a categorised test plan with
  17. failing skeletons. A requirement with no test isn't in the plan.
  18. - **Assume the PR is wrong.** A separate read-only `adversarial-reviewer` agent hunts for bugs,
  19. RFC deviations and vacuous tests, then posts its findings on the PR. It's told to assume tests can
  20. lie.
  21. - **Resumable by construction.** Pipeline state is kept outside the session: a `stage:*` label on
  22. the issue, the artifacts on disk, and a `HANDOFF.md` snapshot. `/factory ISSUE-42` picks up at
  23. the correct station in any fresh session.
  24. ## What's in here
  25. | Path | What it is |
  26. |---|---|
  27. | [`skills/factory/`](skills/factory/SKILL.md) | The orchestrator. `/factory init` scaffolds a repo; `/factory <ISSUE>` runs or resumes an issue. |
  28. | [`skills/tdd/`](skills/tdd/SKILL.md) | Turns an approved RFC into a test plan and failing-test skeletons. |
  29. | [`skills/handoff/`](skills/handoff/SKILL.md) | Writes the `HANDOFF.md` state snapshot at every gate. |
  30. | [`agents/adversarial-reviewer.md`](agents/adversarial-reviewer.md) | The skeptical PR reviewer, also as a [Codex agent](codex/agents/adversarial-reviewer.toml). |
  31. | [`docs/factory.md`](docs/factory.md) | The pipeline contract: the stations, the gates, model policy, state tracking. |
  32. | [`docs/field-notes.md`](docs/field-notes.md) | Production incidents that shaped the rules, and the rule each one produced. |
  33. | [`docs/adr/0001-…`](docs/adr/0001-structured-observability-with-one-error-owner.md) | A worked example ADR: the error-ownership and log-privacy contract the TDD and review stations enforce. |
  34. | [`enforcement/`](enforcement/) | ADR 0001 as code. An ESLint rule that fails any `catch` or `.catch()` that doesn't rethrow, log through the closed logger, or give an `expected-failure:` reason, plus the closed logger itself. Both are tested against hostile, secret-shaped input. |
  35. | [`docs/rfcs/TEMPLATE.md`](docs/rfcs/TEMPLATE.md) | The RFC template. |
  36. | [`templates/factory.json`](templates/factory.json) | Per-project wiring: commands, tracker, stage labels. |
  37. ## Install
  38. As a Claude Code plugin:
  39. ```bash
  40. claude plugin marketplace add bhagavansuraj/software-factory
  41. claude plugin install software-factory@software-factory
  42. ```
  43. Or copy `skills/*` into `.claude/skills/` and `agents/*` into `.claude/agents/`, either in your
  44. repo (so the factory travels with the code) or in `~/.claude/` (so every project can use it).
  45. Then, in your project:
  46. ```
  47. /factory init # once per repo: .factory.json, docs/factory.md, RFC template, ADR index, labels
  48. /factory ISSUE-42 # run or resume an issue
  49. ```
  50. ### Companion skills
  51. The Grill station uses `/grill-with-docs`, `/grilling` and `/domain-modeling` from
  52. [Matt Pocock's skills](https://github.com/mattpocock/skills). I didn't write them, so they aren't
  53. included here. Install them separately:
  54. ```bash
  55. claude plugin install mattpocock-skills@claude-plugins-official
  56. ```
  57. If you don't have them installed, the factory skips the Grill station and starts at Design.
  58. ## Rules the agent can't skip
  59. Agents follow a rule more reliably when CI enforces it than when a prompt asks for it. The
  60. factory's TDD and review stations check error ownership and log privacy. [`enforcement/`](enforcement/)
  61. makes the first line of that check mechanical:
  62. ```js
  63. // eslint.config.js
  64. import requireObservableErrorHandling from "./enforcement/require-observable-error-handling.mjs";
  65. export default [{
  66. plugins: { local: { rules: { "require-observable-error-handling": requireObservableErrorHandling } } },
  67. rules: { "local/require-observable-error-handling": "error", "no-console": "error" },
  68. }];
  69. ```
  70. ```ts
  71. try { await sendEmail(); }
  72. catch { return null; } // ✗ lint error: silent failure
  73. catch (error) { // ✓ recovered: this site owns it
  74. logger.warn({ operation: "email.send_failed", errorName: safeErrorName(error) });
  75. return null;
  76. }
  77. catch { /* expected-failure: malformed cookie → anonymous */ return null; } // ✓ quiet, with a reason
  78. ```
  79. Writing the hostile-input tests for the logger turned up two real gaps in the logger I'd been
  80. running in production. Its error-name check let a JWT through, and its diagnostic redactor
  81. missed JWTs entirely. Tests that use realistic secrets catch leaks that tests using obvious
  82. fake secrets don't.
  83. Run the tests with `npm install && npm run check`.
  84. ## Adapting it
  85. The skills don't depend on any one project. The project-specific parts live in `.factory.json`
  86. and your own ADRs. Two places name a stack:
  87. - The reviewer's **platform footguns** section and the TDD station's test categories use
  88. Cloudflare Workers as the worked example. Replace them with your platform's sharp edges.
  89. - [`docs/field-notes.md`](docs/field-notes.md) is specific to Cloudflare. Keep the rules that
  90. generalise and replace the rest with your own incidents. That file is where most of the value builds up.
  91. ## License
  92. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.