@davidbyoung/software-factory 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +205 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. package/workflows/factory-review.yml +75 -0
@@ -0,0 +1,106 @@
1
+ # Glossary
2
+
3
+ The words these docs use, in plain terms. The factory works through a few
4
+ kinds of tool, each behind one interface, and these pages name the kind,
5
+ not the tool. Where a word stands for a tool, its entry says which one it
6
+ is today.
7
+
8
+ ## The tools
9
+
10
+ **Code host.** Where your repository lives, with its pull requests, their
11
+ reviews, the checks on each commit, and the secrets your CI reads. Today:
12
+ GitHub. `code-host.type` names it.
13
+
14
+ **Ticket system.** Where your tickets live. Today: GitHub Issues.
15
+ `tickets.type` names it.
16
+
17
+ **Board.** A view of every ticket's state, one column per state, which the
18
+ factory keeps up to date. Optional. Today: a GitHub Project.
19
+
20
+ **Cloud runner.** Where work runs with no one at a keyboard: cloud builds,
21
+ the automated review, the board sync, and the factory's other CI jobs.
22
+ Today: GitHub Actions. `builds.runner` names it.
23
+
24
+ **Coding agent.** The AI tool that runs sessions: it reads your code,
25
+ follows the factory's skills, and writes the change. Today: Claude Code.
26
+
27
+ ## The words
28
+
29
+ **Acceptance criteria.** The list in a ticket that says what "done" means,
30
+ written so each item can be checked. Refining a ticket produces it.
31
+
32
+ **Agent (reviewer).** A separate reviewer that a session launches to read
33
+ something and report back. It changes nothing. The factory brings three,
34
+ and you can add your own.
35
+
36
+ **Approver.** A person whose comments a session treats as instructions,
37
+ and who can approve a ticket for building. By default, the repository's
38
+ owner.
39
+
40
+ **Automated review.** A review of every pull request by the coding agent,
41
+ run in CI once the pull request is marked ready. It comments on what it
42
+ finds and gives a verdict. Optional.
43
+
44
+ **Board sync.** The job that sets each ticket's column and fields on the
45
+ board. It is the only thing that writes to the board.
46
+
47
+ **Build.** One session taking one approved ticket to a pull request.
48
+
49
+ **Claim.** A comment a session posts on a ticket before it starts, so no
50
+ other session builds the same one.
51
+
52
+ **Cloud build.** A build that runs on the cloud runner instead of your
53
+ machine. You start one with a command, or by moving a ticket to Ready on
54
+ your board.
55
+
56
+ **Copied files.** The factory's skills, agents, rules, and CI workflows,
57
+ written into your repository by `factory sync`. You do not
58
+ edit them.
59
+
60
+ **Dependency bot.** A tool that opens pull requests when a dependency has
61
+ a new version.
62
+
63
+ **Follow-ups ticket.** One ordinary ticket whose body is a checklist of
64
+ small problems sessions noticed while doing other work.
65
+
66
+ **Gate.** The commands that must pass before a session calls a task done,
67
+ such as your tests and linter. Yours, named in your instructions for the
68
+ agent; without any, a session checks with the tests it wrote.
69
+
70
+ **Hook.** A command the coding agent runs at a set moment in a session,
71
+ such as before a shell command. The factory uses hooks to block risky
72
+ commits.
73
+
74
+ **Local session.** A session on your own machine.
75
+
76
+ **Marker.** A hidden line in a comment the factory posts on a ticket,
77
+ recording what happened. The board is worked out from these.
78
+
79
+ **OpenSpec.** A tool that keeps a written description of what a project
80
+ does, in the repository. Optional.
81
+
82
+ **Plug-in.** One of your own skills or agents that the factory calls at a
83
+ set moment.
84
+
85
+ **Poller.** A small program that watches your board and starts a cloud
86
+ build for each ticket moved to Ready.
87
+
88
+ **Refine.** To turn a ticket into acceptance criteria, settling the
89
+ decisions with you along the way.
90
+
91
+ **Review verdict.** A status on a pull request that says whether the
92
+ automated review of the newest commit found it ready.
93
+
94
+ **Session.** One conversation with the coding agent in your repository, on
95
+ your machine or in the cloud.
96
+
97
+ **Skill.** A set of instructions a session follows, named `factory-...`
98
+ for the factory's own. You call one by asking a session in plain words,
99
+ such as "refine ticket 12".
100
+
101
+ **Spec.** A written statement of what a change must do. For most tickets
102
+ that is the acceptance criteria. With OpenSpec turned on, a change your
103
+ users will see also gets its behavior recorded in the repository.
104
+
105
+ **Ticket.** One item in the ticket system: a piece of work, with what,
106
+ why, and when it is done.
@@ -0,0 +1,115 @@
1
+ # Limitations
2
+
3
+ What the factory does not do, what it assumes that nobody has tested, and
4
+ the risks that come with it. Read this before relying on it.
5
+
6
+ The limits that come from today's tools rather than from the factory, such
7
+ as a code host's billing or what its workflows can see, are in
8
+ [the GitHub and Claude Code reference](github/reference.md#limits).
9
+
10
+ ## What it does not do
11
+
12
+ - **One tool of each kind.** The factory reaches the code host, the ticket
13
+ system, the board, and the cloud runner each through one interface, and
14
+ the settings name which one you use (`code-host.type`, `tickets.type`,
15
+ and `builds.runner`). Each has one implementation today, GitHub's, and no
16
+ other is planned. The skills are written for one coding agent, Claude
17
+ Code. [The glossary](glossary.md) says which tool each word means today.
18
+ - **It needs Node and a `package.json`,** even in a repository written in
19
+ another language.
20
+ - **A build never changes the coding agent's settings files,** which hold
21
+ the hooks that guard the run. It may write the factory's other files
22
+ there. A change to those settings is a person's to make.
23
+ - **One ticket, one repository.** A change that spans repositories is two
24
+ tickets.
25
+ - **It is written for one approver.** `approvers` lets a team list several
26
+ people (_[Planned](developing.md#what-is-built)_), but review by teams, required reviewers per folder, and monorepos
27
+ with several owners are not designed.
28
+ - **The order of the workflow is fixed.** You can turn written specs off and
29
+ add reviewers. You cannot add a state or reorder them.
30
+ - **On a board with no refining column, a ticket cannot be sent back to the
31
+ backlog by moving its card.** The card already shows in the backlog column
32
+ while a ticket is being refined, so the move says nothing.
33
+ - **The UI reviewer needs Playwright.** The repository installs it, and its
34
+ browser.
35
+ - **It cannot see a page behind a sign-in.** It compares one site at one
36
+ address.
37
+ - **What the measurements do not cover.** Elements that overlap or are cut
38
+ off, and how far a page moves while it loads, are for the pictures and the
39
+ agent. The contrast of a control's edge is not measured, since axe-core has
40
+ no rule for it. Frames inside a page are left out, and so is a view whose
41
+ pictures did not change. axe-core's target size is WCAG 2.5.8's 24 px, not a
42
+ larger floor of your own.
43
+ - **A state that takes a click to reach is the agent's to drive,** not the
44
+ command's.
45
+ - **No budgets.** What each ticket cost is recorded. Nothing caps it.
46
+ - **Without the global install, the command needs `--no-install`.**
47
+ Another package on npm is called `factory`. Where this one is not
48
+ installed, `npx` without `--no-install` offers to download and run that
49
+ one instead, so `npx --no-install factory` fails rather than run another
50
+ package.
51
+ - **Nothing retries on its own.** A build that stops waits for you.
52
+ - **A cloud build's commits are unsigned unless you give it a signing
53
+ key.** [Signed commits from cloud builds](github/setup.md#signed-commits-from-cloud-builds)
54
+ says how.
55
+ - **A cloud build cannot be steered.** You can read its log as it runs, and
56
+ cancel it, but not answer it: where it would ask, it stops and reports.
57
+ - **Nothing watches a pull request after its cloud build ends.** Your own
58
+ review comments are answered by a session you open, or by a cloud session
59
+ started for your review, which has only the pull request and the ticket
60
+ to go on.
61
+ - **A cloud build runs for up to 230 minutes by default**
62
+ ([`session-minutes`](configuration.md#session-minutes)), and its minutes
63
+ may cost money, depending on your cloud runner and plan.
64
+
65
+ ## What nobody has tested
66
+
67
+ - **A board owned by an organization.** It is read the same way as a
68
+ person's, but the factory has only run against a person's.
69
+ - **Your board's own automations,** such as moving a closed ticket to Done.
70
+ They may fight the board sync.
71
+ - **Installing an unpublished or private package** in CI and from a
72
+ dependency bot.
73
+ - **Glob patterns standing in for today's regular expressions** in the
74
+ merge policy. They could match differently. The switch compares the old and new
75
+ decision on recent pull requests.
76
+ - **A scheduled job as the poller,** including what it costs.
77
+ - **Windows.** The tool and its hooks need only Node, but nothing here has
78
+ been run on Windows.
79
+ - **Adding the factory's columns to a board you already have.**
80
+ - **Whether your coding agent's plan permits automated builds this way.**
81
+ The automated review runs on a subscription token in the one repository
82
+ that uses it. Check your plan's terms.
83
+
84
+ ## What was tested, and found not to work
85
+
86
+ - **Node will not run TypeScript from inside `node_modules`.** A published
87
+ package has to ship compiled JavaScript.
88
+
89
+ ## Risks that do not go away
90
+
91
+ - **"Universal" is a guess until a second repository uses it.** Everything
92
+ here was drawn out of one repository.
93
+ - **A session acts as you.** That is the design: your agent writes the
94
+ commits, and they go out under your account. It also means the guard
95
+ against a session approving its own work is a tripwire, not a lock. Your
96
+ read of the pull request is the control.
97
+ - **The skills are prose, and prose is hard to test.** A change of wording
98
+ changes behavior in every repository that updates. The checks are a traced
99
+ read by a fresh agent, one real ticket, and your read of the update.
100
+ - **Rules that need judgment cannot be enforced.** CI can require that a
101
+ reviewer ran or was skipped with a reason. It cannot check the reason was
102
+ a good one.
103
+ - **It amplifies the checks it is given.** A repository with weak tests gets
104
+ confident, wrong pull requests faster.
105
+ - **Ticket text, review comments, and changelogs are read by sessions.**
106
+ Only an approver's comments are treated as instructions, and that rests on
107
+ one account's login.
108
+ - **An update delivers instructions that run with your tokens.** Read update
109
+ pull requests as carefully as code.
110
+ - **The poller keeps its hourly cap in memory.** A restart forgets how many
111
+ builds it started in the last hour.
112
+ - **It sits on tools that change.** Several parts work around how today's
113
+ coding agent and code host behave.
114
+ - **Publishing cannot be undone.** A public release needs a history and
115
+ examples free of the host repository's private tickets first.
@@ -0,0 +1,192 @@
1
+ # Plug-ins
2
+
3
+ The factory knows how to refine, build, and review a ticket. It does not
4
+ know your project. A plug-in is one of your own skills or agents that the
5
+ factory calls at a set moment, so what only your project knows is part of
6
+ every build.
7
+
8
+ ## The idea
9
+
10
+ You write a skill or an agent the way your coding agent expects one, in
11
+ the folder it reads them from
12
+ ([on Claude Code](github/reference.md#skills-in-claude-code)). Then you add
13
+ a few lines to `.claude/factory.yaml` saying what job it does:
14
+
15
+ ```yaml
16
+ plugins:
17
+ - agent: migration-reviewer
18
+ role: reviewer
19
+ files:
20
+ - db/migrations/**
21
+ ```
22
+
23
+ That is the whole of it. The factory never copies over your files, and an
24
+ update never touches them.
25
+
26
+ ## The three roles
27
+
28
+ A role is a moment in the workflow where the factory hands off. There are
29
+ three. A repository can have several plug-ins in one role, or none.
30
+
31
+ ### `reviewer`
32
+
33
+ Reads a finished change and reports problems.
34
+
35
+ | | |
36
+ | ------------------- | -------------------------------------------------------------------------------------------- |
37
+ | **Called** | By `factory-build`, after the change is built and before the pull request opens |
38
+ | **Considered when** | The change touches a file matching one of its `files` patterns |
39
+ | **Handed** | The branch, and which files changed |
40
+ | **Returns** | Findings, each with where it is and why it matters. It changes nothing |
41
+ | **Then** | The building session fixes what holds up, and the pull request says what each reviewer found |
42
+
43
+ Good candidates: database migrations, anything touching authentication or
44
+ payments, a public API that must stay backward compatible, accessibility
45
+ of your components, copy that has to follow a style guide.
46
+
47
+ ### `mockups`
48
+
49
+ Makes pictures to choose from when a decision changes how something looks.
50
+
51
+ A repository with `site` in its settings has one already: the factory's
52
+ own `factory-design` skill, which `factory sync` writes, is its `mockups`
53
+ plug-in unless you list one of your own with this role.
54
+
55
+ | | |
56
+ | --------------- | ----------------------------------------------------------------------------------- |
57
+ | **Called** | By `factory-refine`, when one of the decisions it would bring you is about the look |
58
+ | **Handed** | The ticket and the decision |
59
+ | **Returns** | Screenshots of each option, with one recommended |
60
+ | **Then** | You choose, and the choice goes into the ticket |
61
+ | **Without one** | The decision is described in words |
62
+
63
+ ### `builder`
64
+
65
+ Builds a kind of ticket the general build would do badly.
66
+
67
+ | | |
68
+ | ------------- | -------------------------------------------------------------------------- |
69
+ | **Called** | By `factory-build`, in place of its own build step |
70
+ | **Used when** | The ticket carries one of its `labels` |
71
+ | **Handed** | The ticket, already claimed, on its branch |
72
+ | **Returns** | The change, and a report for the pull request body |
73
+ | **Then** | `factory-build` carries on as usual: reviewers, the gate, the pull request |
74
+
75
+ Good candidates: work your project always does the same way, such as a new
76
+ API endpoint with its route, handler, schema, and docs, or a new
77
+ translation added to every locale file.
78
+
79
+ ## `files` filters; the agent decides
80
+
81
+ `files` answers "could this reviewer matter here?" It cannot answer "does
82
+ it?" That judgment belongs in the agent's own description, the lines at the
83
+ top of its file that say when to use it:
84
+
85
+ ```yaml
86
+ ---
87
+ name: migration-reviewer
88
+ description: >-
89
+ Use when a change adds or alters a database migration's SQL or schema
90
+ operations. Not for a change to comments or formatting alone.
91
+ ---
92
+ ```
93
+
94
+ So a change that only fixes a typo in a migration's comment matches the
95
+ reviewer's files, and the building session, reading that description,
96
+ skips it. It says so in the pull request:
97
+
98
+ ```text
99
+ migration-reviewer: skipped, only a comment changed.
100
+ ```
101
+
102
+ Every matched reviewer ends up with either a run or a line like that. You
103
+ read the skips when you read the pull request.
104
+
105
+ **Write the description as a condition.** "Reviews database migrations"
106
+ says what the agent is. "Use when a change adds or alters a migration's
107
+ SQL" says when to call it, which is what the factory needs.
108
+
109
+ ## A worked example
110
+
111
+ A team runs a web application with a large database. A migration can pass
112
+ every test and still take the site down: it locks a busy table, or drops a
113
+ column the code still running in production reads. No test catches that.
114
+ So the team has an agent, `migration-reviewer`, that reads a migration the
115
+ way their most careful database engineer would.
116
+
117
+ **1. The agent** is an ordinary agent file of the team's coding agent,
118
+ named `migration-reviewer`. Its description says when it applies. Its body says what to check: can it be rolled back, will it lock
119
+ a large table, and does it still work with the code that is live while it
120
+ runs.
121
+
122
+ **2. The settings** name it:
123
+
124
+ ```yaml
125
+ plugins:
126
+ - agent: migration-reviewer
127
+ role: reviewer
128
+ files:
129
+ - db/migrations/**
130
+ ```
131
+
132
+ **3. A session builds a ticket** that removes an unused column.
133
+ `factory-build` sees the change touched `db/migrations/`, reads the
134
+ reviewer's description, finds it applies, and launches it. The agent
135
+ reports that the live code still selects that column, so the migration
136
+ would break requests during the deploy. The session splits the work: this
137
+ change stops reading the column, and a follow-up drops it.
138
+
139
+ **4. The pull request** says: "`migration-reviewer`: one finding, the
140
+ column is still read by the running code. Split into two changes."
141
+
142
+ A second ticket fixes a typo in a migration's comment. The files match
143
+ again, the description does not, and the pull request says:
144
+ "`migration-reviewer`: skipped, only a comment changed."
145
+
146
+ The team's rules for what makes a migration safe stay in their own
147
+ instructions for the agent and in the agent itself. The factory holds none of them.
148
+
149
+ ## Adding one
150
+
151
+ 1. Write the skill or agent, and try it by hand until it does its job.
152
+ 2. Give it a description that states when it applies.
153
+ 3. Add it under `plugins` with its `role`, and `files` or `labels`.
154
+ 4. Run `factory config check`. It fails if the file is missing or the
155
+ role is not one of the three.
156
+ 5. Run `factory plugins` to see the list the factory will use.
157
+
158
+ No sync is needed. Plug-ins are read from your settings each time.
159
+
160
+ ## What is not a plug-in
161
+
162
+ - **A skill you call yourself.** If nothing in refining, building, or
163
+ reviewing a ticket should call it, it needs no entry. It stays an
164
+ ordinary skill.
165
+ - **A skill another of your skills calls.** A reviewer that only your own
166
+ `builder` launches is that builder's business.
167
+ - **A rule.** "Migrations always wait for me" is `auto-merge`. "Every
168
+ migration needs a rollback" is a sentence in your project's instructions
169
+ for the agent.
170
+
171
+ ## The UI reviewer
172
+
173
+ `factory-ui-reviewer` ships with the factory and is written to any repository
174
+ with `site` in its settings, but runs only where it is listed:
175
+
176
+ ```yaml
177
+ plugins:
178
+ - agent: factory-ui-reviewer
179
+ role: reviewer
180
+ files:
181
+ - src/**
182
+ - public/**
183
+ ```
184
+
185
+ It needs the `site` settings, which say how to start the website.
186
+
187
+ ## Sharing plug-ins between repositories
188
+
189
+ Not planned. A plug-in lives in the repository that uses it. A way to
190
+ package a set of them, such as a design skill and a visual reviewer for
191
+ any website, and install it in several repositories is designed for but
192
+ not scheduled.
@@ -0,0 +1,222 @@
1
+ # Quick start
2
+
3
+ From nothing to a pull request built from one of your tickets. You run a
4
+ few commands, write one ticket, and answer a question or two; your coding
5
+ agent does the rest. This page needs no board, no secrets, and nothing to
6
+ host.
7
+
8
+ A word you do not know is in the [glossary](glossary.md). A step marked
9
+ _[Planned](developing.md#what-is-built)_ is not built yet, and says what to
10
+ do until then.
11
+
12
+ ## You need
13
+
14
+ - A repository on a supported code host, cloned on your machine, with the
15
+ code host's command-line tool signed in.
16
+ - A supported coding agent, signed in.
17
+ - Node 22.18 or later. Check with `node --version`.
18
+
19
+ Which tools are supported, and how to check each is ready, is in
20
+ [What you need](github/setup.md#what-you-need) on the GitHub page.
21
+
22
+ Your repository does not have to be JavaScript. If it is not, read
23
+ [this section](existing-repo.md#a-repository-that-is-not-javascript)
24
+ first: installing adds a small `package.json`.
25
+
26
+ ## 1. Install
27
+
28
+ _[Planned](developing.md#what-is-built)._ Until the package is published,
29
+ it cannot be installed outside the repository it is developed in.
30
+
31
+ Once on your machine, so you can type `factory`:
32
+
33
+ ```bash
34
+ npm install -g @davidbyoung/software-factory
35
+ ```
36
+
37
+ Then in your repository, which keeps its own version:
38
+
39
+ ```bash
40
+ npm install --save-dev @davidbyoung/software-factory
41
+ ```
42
+
43
+ **It worked when** `factory`, run in your repository, prints the list of
44
+ its commands. It exits non-zero, since no command was given; that is
45
+ expected.
46
+
47
+ ## 2. Set it up
48
+
49
+ ```bash
50
+ factory init
51
+ ```
52
+
53
+ It says what it found, asks which optional parts you want, and shows
54
+ everything it will do before it does any of it. For this first ticket,
55
+ uncheck every part: the basics need none.
56
+
57
+ Told to go ahead, it writes your settings file, `.claude/factory.yaml`,
58
+ and the instructions your coding agent follows when it works a ticket. It
59
+ adds hooks: small checks your agent runs on its own, such as refusing a
60
+ commit on your main branch. It adds one line to your agent's instructions
61
+ file, such as `CLAUDE.md`, and the hooks to your agent's settings,
62
+ creating either file if you have none. It changes nothing else of yours,
63
+ and commits nothing. [What it changes](removing.md) lists every item and
64
+ how to undo it.
65
+
66
+ **It worked when** the checks it prints last all show ✓. Run them again at
67
+ any time with `factory doctor`.
68
+
69
+ **To do it by hand instead,** write the shortest settings file, with your
70
+ repository's owner and name, then write the factory's files:
71
+
72
+ ```yaml
73
+ version: 1
74
+ repository: your-name/your-repo
75
+ ```
76
+
77
+ ```bash
78
+ factory sync
79
+ ```
80
+
81
+ A build checks its change with the commands your agent's instructions
82
+ file names, such as your tests and your linter, so say there how to check
83
+ a change. Without any, it checks with the tests it wrote.
84
+
85
+ To have a command run before every commit a session makes, such as your
86
+ linter, list it under `before-commit` in the settings file:
87
+
88
+ ```yaml
89
+ before-commit:
90
+ - npm run lint
91
+ ```
92
+
93
+ ## 3. Merge the setup
94
+
95
+ Commit what `sync` wrote on a branch, push it, then open a pull request for
96
+ it on your code host, as for any change, and merge it:
97
+
98
+ ```bash
99
+ git switch -c set-up-factory
100
+ git add -A
101
+ git commit -m "Set up the software factory"
102
+ git push -u origin set-up-factory
103
+ ```
104
+
105
+ Then bring your main branch up to date:
106
+
107
+ ```bash
108
+ git switch main
109
+ git pull
110
+ ```
111
+
112
+ Your coding agent loads the factory from the files in your repository, so
113
+ start a new session after this step.
114
+
115
+ **It worked when** the new session, asked which skills it has, lists
116
+ `factory-refine` and `factory-build`. A skill is a set of instructions for
117
+ one kind of job, such as refining a ticket.
118
+
119
+ ## 4. Open a ticket
120
+
121
+ A ticket in your ticket system. Say three things: what you want, why, and
122
+ how you will know it is done. A few sentences is enough.
123
+
124
+ ```text
125
+ Title: Show the opening hours in the footer
126
+
127
+ The hours are only on the contact page, and people ask for them.
128
+ Done when: every page's footer shows the same hours the contact page does.
129
+ ```
130
+
131
+ Note its number. This page uses 12.
132
+
133
+ ## 5. Refine it
134
+
135
+ In a session of your coding agent, in your repository, say:
136
+
137
+ ```text
138
+ refine ticket 12
139
+ ```
140
+
141
+ The session reads the ticket and the code it touches. Then it asks you the
142
+ decisions that are yours, each as a choice with its recommendation first:
143
+
144
+ ```text
145
+ Where should the hours come from?
146
+ 1. The settings file the contact page already reads (Recommended)
147
+ 2. A new footer-only setting
148
+ ```
149
+
150
+ **It worked when** the ticket ends with acceptance criteria, a checklist
151
+ that says exactly what "done" means, and the session says it is ready to
152
+ build.
153
+
154
+ ## 6. Build it
155
+
156
+ In the same session, or a new one:
157
+
158
+ ```text
159
+ build ticket 12
160
+ ```
161
+
162
+ Telling a session to build a ticket is how you approve it.
163
+
164
+ You can watch it work. The session:
165
+
166
+ 1. comments on the ticket that it has claimed it, so no other session
167
+ builds the same one;
168
+ 2. makes a branch;
169
+ 3. writes a test, then the change;
170
+ 4. checks each commit with your `before-commit` commands, if you set any;
171
+ 5. opens a pull request that closes the ticket, as a draft, which tells
172
+ people and the automated review it is not finished;
173
+ 6. marks it ready for review once your CI passes on it, or after two
174
+ minutes when no CI runs on it, and answers any review it gets.
175
+
176
+ **It worked when** its last message names the pull request, says what it
177
+ built, and says how it checked it. Expect minutes, not seconds.
178
+
179
+ ## 7. Read it and merge
180
+
181
+ Open the pull request. Its description says what changed, how it was
182
+ verified, and anything the session noticed and left alone. Nothing merges
183
+ without you.
184
+
185
+ To ask for changes, comment on the pull request, then tell a session to
186
+ answer your comments:
187
+
188
+ ```text
189
+ address the review on pull request 15
190
+ ```
191
+
192
+ That is the whole loop: **ticket, refine, build, read, merge.**
193
+
194
+ ## If something goes wrong
195
+
196
+ | What happened | What to do |
197
+ | ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
198
+ | A `before-commit` command fails during the build | Nothing. The session sees the output, fixes the cause, and tries again |
199
+ | The session stops and says it needs you | It says why, in the session and on the ticket. Answer, then ask it to build ticket 12 again |
200
+ | The session was closed or crashed partway | Ask a new session to build ticket 12. It picks up the branch it made |
201
+ | You want to change what was decided | Ask a session to refine ticket 12 again, or edit the ticket |
202
+ | CI fails on the pull request | Ask a session to address the review on pull request 15. It reads the failure and fixes it |
203
+ | The session does not know the factory's skills | The setup is not merged, or the session started before it was. See step 3 |
204
+ | Anything else | Run `factory doctor`. It says what is wrong, and what to do about it |
205
+
206
+ ## What to add next
207
+
208
+ Everything above runs on your machine while you watch. Each part below is
209
+ optional, stands alone, and can come later.
210
+
211
+ | Add | So that | It asks of you |
212
+ | ----------------------------------- | -------------------------------------------------------------------- | --------------------------------------------- |
213
+ | An automated review | Every pull request is read by your coding agent before you read it | Your agent's token, stored on the code host |
214
+ | A board | You see every ticket's state, which session has it, and what it cost | A board, and a token that can write to it |
215
+ | Builds in the cloud | A ticket builds with no session open on your machine | Your agent's token, and a token that can push |
216
+ | Builds that start from the board | Moving a ticket to Ready builds it | A small program, the poller, that you host |
217
+ | Pull requests that merge themselves | Changes to files you list as safe do not wait for you | The list of files, and a token that can merge |
218
+ | Your own reviewers | A change to your content or your design is read by an expert agent | A few lines of settings |
219
+
220
+ Run `factory init` again and turn on the parts you want;
221
+ it sets up each one, tokens included. [Setting up on GitHub](github/setup.md)
222
+ has the same steps by hand, on one page.