@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.
- package/.claude-plugin/plugin.json +5 -0
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/actions/factory-agent/action.yml +218 -0
- package/agents/factory-test-reviewer.md +129 -0
- package/agents/factory-ticket-readiness.md +107 -0
- package/agents/factory-ui-reviewer.md +160 -0
- package/bin/factory.js +45 -0
- package/bin/launch.js +67 -0
- package/dist/board.d.mts +128 -0
- package/dist/board.mjs +456 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.mjs +60 -0
- package/dist/cli.d.mts +17 -0
- package/dist/cli.mjs +264 -0
- package/dist/code-host/github.d.mts +118 -0
- package/dist/code-host/github.mjs +419 -0
- package/dist/code-host/index.d.mts +9 -0
- package/dist/code-host/index.mjs +18 -0
- package/dist/code-host/types.d.mts +205 -0
- package/dist/code-host/types.mjs +12 -0
- package/dist/config.d.mts +166 -0
- package/dist/config.mjs +548 -0
- package/dist/deps.d.mts +32 -0
- package/dist/deps.mjs +126 -0
- package/dist/doctor.d.mts +34 -0
- package/dist/doctor.mjs +188 -0
- package/dist/guard-commit.d.mts +41 -0
- package/dist/guard-commit.mjs +205 -0
- package/dist/guard-permission.d.mts +15 -0
- package/dist/guard-permission.mjs +52 -0
- package/dist/guard-ticket-text.d.mts +27 -0
- package/dist/guard-ticket-text.mjs +288 -0
- package/dist/guard.d.mts +4 -0
- package/dist/guard.mjs +37 -0
- package/dist/init.d.mts +58 -0
- package/dist/init.mjs +556 -0
- package/dist/lib/clock.d.mts +14 -0
- package/dist/lib/clock.mjs +36 -0
- package/dist/lib/gh.d.mts +28 -0
- package/dist/lib/gh.mjs +92 -0
- package/dist/lib/glob.d.mts +2 -0
- package/dist/lib/glob.mjs +41 -0
- package/dist/lib/pricing.d.mts +25 -0
- package/dist/lib/pricing.mjs +77 -0
- package/dist/lib/usage.d.mts +34 -0
- package/dist/lib/usage.mjs +128 -0
- package/dist/lib/work-status.d.mts +251 -0
- package/dist/lib/work-status.mjs +510 -0
- package/dist/merge-policy.d.mts +66 -0
- package/dist/merge-policy.mjs +146 -0
- package/dist/parts.d.mts +39 -0
- package/dist/parts.mjs +138 -0
- package/dist/poller.d.mts +61 -0
- package/dist/poller.mjs +247 -0
- package/dist/pr-watch.d.mts +45 -0
- package/dist/pr-watch.mjs +244 -0
- package/dist/pr.d.mts +65 -0
- package/dist/pr.mjs +571 -0
- package/dist/review-cost.d.mts +18 -0
- package/dist/review-cost.mjs +95 -0
- package/dist/review-tools.d.mts +5 -0
- package/dist/review-tools.mjs +46 -0
- package/dist/review-verdict.d.mts +50 -0
- package/dist/review-verdict.mjs +171 -0
- package/dist/reviewers.d.mts +54 -0
- package/dist/reviewers.mjs +312 -0
- package/dist/runner/github-actions.d.mts +12 -0
- package/dist/runner/github-actions.mjs +97 -0
- package/dist/runner/index.d.mts +9 -0
- package/dist/runner/index.mjs +22 -0
- package/dist/runner/types.d.mts +60 -0
- package/dist/runner/types.mjs +7 -0
- package/dist/session-start.d.mts +20 -0
- package/dist/session-start.mjs +115 -0
- package/dist/site/capture.d.mts +44 -0
- package/dist/site/capture.mjs +114 -0
- package/dist/site/measure.d.mts +83 -0
- package/dist/site/measure.mjs +225 -0
- package/dist/site/pages.d.mts +10 -0
- package/dist/site/pages.mjs +71 -0
- package/dist/site/pixels.d.mts +47 -0
- package/dist/site/pixels.mjs +157 -0
- package/dist/site/servers.d.mts +47 -0
- package/dist/site/servers.mjs +141 -0
- package/dist/site.d.mts +60 -0
- package/dist/site.mjs +341 -0
- package/dist/status.d.mts +100 -0
- package/dist/status.mjs +514 -0
- package/dist/sync.d.mts +59 -0
- package/dist/sync.mjs +292 -0
- package/dist/ticket.d.mts +61 -0
- package/dist/ticket.mjs +562 -0
- package/dist/tickets/github.d.mts +128 -0
- package/dist/tickets/github.mjs +491 -0
- package/dist/tickets/index.d.mts +15 -0
- package/dist/tickets/index.mjs +27 -0
- package/dist/tickets/transport.d.mts +42 -0
- package/dist/tickets/transport.mjs +158 -0
- package/dist/tickets/types.d.mts +191 -0
- package/dist/tickets/types.mjs +76 -0
- package/docs/builds.md +227 -0
- package/docs/cli.md +221 -0
- package/docs/configuration.md +809 -0
- package/docs/design.md +106 -0
- package/docs/developing.md +400 -0
- package/docs/existing-repo.md +138 -0
- package/docs/github/reference.md +288 -0
- package/docs/github/setup.md +312 -0
- package/docs/glossary.md +106 -0
- package/docs/limitations.md +115 -0
- package/docs/plugins.md +192 -0
- package/docs/quick-start.md +222 -0
- package/docs/removing.md +76 -0
- package/docs/skills.md +270 -0
- package/docs/updating.md +108 -0
- package/docs/workflow.md +195 -0
- package/package.json +67 -4
- package/poller.Dockerfile +21 -0
- package/review.md +170 -0
- package/rules.md +313 -0
- package/settings.schema.json +411 -0
- package/skills/factory-address-review/SKILL.md +547 -0
- package/skills/factory-address-review/patch-coverage.py +68 -0
- package/skills/factory-build/SKILL.md +412 -0
- package/skills/factory-deps/SKILL.md +185 -0
- package/skills/factory-design/SKILL.md +159 -0
- package/skills/factory-diagnose/SKILL.md +93 -0
- package/skills/factory-mutate/SKILL.md +76 -0
- package/skills/factory-refine/SKILL.md +417 -0
- package/skills/factory-resolve-conflicts/SKILL.md +235 -0
- package/workflows/factory-board-sync.yml +91 -0
- package/workflows/factory-build.yml +72 -0
- package/workflows/factory-check.yml +37 -0
- package/workflows/factory-claude-review.yml +133 -0
- package/workflows/factory-conflicts.yml +69 -0
- package/workflows/factory-deps-auto-merge.yml +43 -0
- package/workflows/factory-deps.yml +59 -0
- package/workflows/factory-merge-policy.yml +121 -0
- package/workflows/factory-review-verdict.yml +54 -0
- package/workflows/factory-review.yml +75 -0
package/docs/design.md
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Why it works this way
|
|
2
|
+
|
|
3
|
+
The reasons behind the choices a user runs into. You do not need this page
|
|
4
|
+
to use the factory. Read it when something seems odd and you want to know
|
|
5
|
+
whether it is deliberate.
|
|
6
|
+
|
|
7
|
+
## Your agent writes the code; a person approves it
|
|
8
|
+
|
|
9
|
+
A cloud build's commits name your coding agent as their author, and as
|
|
10
|
+
their committer the account whose token the build is given, which is the
|
|
11
|
+
account that signs them. The build pushes and opens its pull request as
|
|
12
|
+
that account too. Working alone, that is usually your own account. A team
|
|
13
|
+
can give it an agent account instead, one account on the code host that
|
|
14
|
+
every cloud build acts as, so the pull request's author is not one of the
|
|
15
|
+
people who must approve it. Nothing else changes between the two.
|
|
16
|
+
|
|
17
|
+
A session on your machine commits as you, since you are the one steering
|
|
18
|
+
it. `factory sync` turns the coding agent's attribution
|
|
19
|
+
lines off, unless your agent's settings already said otherwise, so a
|
|
20
|
+
session's commits carry your name alone.
|
|
21
|
+
|
|
22
|
+
Either way, a person is accountable for every change that merges: the one
|
|
23
|
+
who merges it. The factory's job is to make that person's read of a pull
|
|
24
|
+
request easy, and to hold anything risky for it. When builds act as your
|
|
25
|
+
own account, the guard against a session approving its own work is a
|
|
26
|
+
tripwire that catches accidents, not a wall against the account's owner.
|
|
27
|
+
Your read is the control.
|
|
28
|
+
|
|
29
|
+
## Everything waits for you by default
|
|
30
|
+
|
|
31
|
+
No pull request merges itself until you list the files that may. A tool
|
|
32
|
+
that merges on its own has to earn that one file pattern at a time.
|
|
33
|
+
|
|
34
|
+
## The factory's files are copied into your repository
|
|
35
|
+
|
|
36
|
+
The skills, agents, rules, and CI workflows are written into your
|
|
37
|
+
repository and checked for drift, which is more machinery than loading
|
|
38
|
+
them from the package. A cloud build starts from a fresh checkout, and what
|
|
39
|
+
is committed to the repository is what it reads, so the instructions a
|
|
40
|
+
build follows are the ones the pull request shows. The choice is not
|
|
41
|
+
forced: loading them from the package would also work, and would mean
|
|
42
|
+
one version for every repository.
|
|
43
|
+
|
|
44
|
+
It has one real benefit. Every version of the instructions your sessions
|
|
45
|
+
followed is in your repository's history, beside the code they built, and
|
|
46
|
+
an update shows you exactly which instruction changed.
|
|
47
|
+
|
|
48
|
+
The package is still laid out as a plugin for today's coding agent, so
|
|
49
|
+
that route stays open.
|
|
50
|
+
|
|
51
|
+
## Skill names start with `factory-`
|
|
52
|
+
|
|
53
|
+
The prefix is part of each skill's name. It shows which skill files an
|
|
54
|
+
update will overwrite and which are yours, and keeps the factory's names
|
|
55
|
+
from colliding with your own.
|
|
56
|
+
[The reference](github/reference.md#skills-in-claude-code) says why the
|
|
57
|
+
name is not written with a colon.
|
|
58
|
+
|
|
59
|
+
## The settings hold only what a script computes
|
|
60
|
+
|
|
61
|
+
Every key in `.claude/factory.yaml` is something the tool calculates with:
|
|
62
|
+
a path pattern, a command, a number. Anything that needs judgment, such as
|
|
63
|
+
when a reviewer applies, stays as prose in your instructions for the agent
|
|
64
|
+
or in the agent's own description, where a session reads it.
|
|
65
|
+
|
|
66
|
+
A setting that a session would have to interpret is a setting that behaves
|
|
67
|
+
differently from one day to the next.
|
|
68
|
+
|
|
69
|
+
## The order of the workflow is fixed
|
|
70
|
+
|
|
71
|
+
You can turn parts off and add reviewers. You cannot reorder the states or
|
|
72
|
+
add one. Mapping names is cheap to support. Every extra shape of workflow
|
|
73
|
+
is one more path each skill has to handle correctly, and a skill is
|
|
74
|
+
instructions, which cannot be unit tested.
|
|
75
|
+
|
|
76
|
+
## Small problems go on one checklist
|
|
77
|
+
|
|
78
|
+
A session that notices a small problem adds a line to one follow-ups
|
|
79
|
+
ticket instead of opening a ticket for it. Every ticket costs the same
|
|
80
|
+
steps whatever its size, so twenty small fixes as twenty tickets cost
|
|
81
|
+
twenty approvals and twenty pull requests. On one checklist they cost one
|
|
82
|
+
of each.
|
|
83
|
+
|
|
84
|
+
## Three version numbers
|
|
85
|
+
|
|
86
|
+
They are separate on purpose.
|
|
87
|
+
|
|
88
|
+
| Number | Where it is | Changes when |
|
|
89
|
+
| ------------------- | -------------------------------------------- | ------------------------------------ |
|
|
90
|
+
| The factory's | `package.json` and `.claude/factory.lock` | Every release |
|
|
91
|
+
| The settings file's | `version:` at the top of `factory.yaml` | A key is renamed or moved |
|
|
92
|
+
| The markers' | In the comments the factory posts on tickets | The format of those comments changes |
|
|
93
|
+
|
|
94
|
+
- **Below `1.0.0`, a release may change anything**, and its notes say what.
|
|
95
|
+
`1.0.0` comes when a second repository has run on the factory for a while
|
|
96
|
+
and the settings have stopped moving.
|
|
97
|
+
- **The settings file has its own version** so that a release which does not
|
|
98
|
+
touch its shape never asks you to change it.
|
|
99
|
+
- **The markers have a version** because those comments stay in your
|
|
100
|
+
tickets' history for good, and an old one has to stay readable.
|
|
101
|
+
|
|
102
|
+
## Secrets are named for what they do
|
|
103
|
+
|
|
104
|
+
Everything the factory owns starts with `FACTORY_` and says its purpose:
|
|
105
|
+
`FACTORY_BOARD_TOKEN`, not a name another tool might already use. You can
|
|
106
|
+
tell which secrets it needs and which are safe to delete.
|
|
@@ -0,0 +1,400 @@
|
|
|
1
|
+
# Developing the factory
|
|
2
|
+
|
|
3
|
+
How to work on the factory itself. For using it, start with the
|
|
4
|
+
[quick start](quick-start.md).
|
|
5
|
+
|
|
6
|
+
## Where it lives
|
|
7
|
+
|
|
8
|
+
This repository holds the package, its docs, and its tests, and publishes
|
|
9
|
+
the package to npm as `@davidbyoung/software-factory`. It was developed
|
|
10
|
+
inside the private repository it was drawn out of until 0.1.0, and moved
|
|
11
|
+
here with a fresh history. Its tickets are kept, for now, on that
|
|
12
|
+
repository's board.
|
|
13
|
+
|
|
14
|
+
A change reaches a repository that uses the factory as a release: a new
|
|
15
|
+
version on npm, then Dependabot's pull request there, which `factory-deps`
|
|
16
|
+
completes with the files the version writes ([Updating](updating.md)).
|
|
17
|
+
|
|
18
|
+
## What is built
|
|
19
|
+
|
|
20
|
+
The factory is the npm package `@davidbyoung/software-factory`. Parts not
|
|
21
|
+
marked working below exist only in these docs.
|
|
22
|
+
|
|
23
|
+
| Part | State |
|
|
24
|
+
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
|
|
25
|
+
| Refining, building, and working a pull request's review | Working |
|
|
26
|
+
| The board, its sync, and `status` | Working |
|
|
27
|
+
| Builds from the board, with a poller you host | Working |
|
|
28
|
+
| Builds that run in GitHub Actions, started by a command | Working |
|
|
29
|
+
| Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
|
|
30
|
+
| Who merges, and the review's verdict | Working |
|
|
31
|
+
| The labels `merge: manual` and `verdict: override` | Working |
|
|
32
|
+
| These docs | Working |
|
|
33
|
+
| `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
|
|
34
|
+
| The follow-ups ticket as one checklist | Working |
|
|
35
|
+
| The `factory` tool, `sync`, and the package folder | Working |
|
|
36
|
+
| A global `factory` command that runs each repository's own copy | Working |
|
|
37
|
+
| The automated review as one of the factory's workflows, and `ci-review` | Working |
|
|
38
|
+
| Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
|
|
39
|
+
| The `factory-` names and the `FACTORY_` secrets | Working |
|
|
40
|
+
| Ticket commands that go through one interface | Working |
|
|
41
|
+
| The code host and the runner, each behind one interface | Working |
|
|
42
|
+
| A published package, updated through Dependabot | Planned, next |
|
|
43
|
+
| A second repository using it | Planned, after publishing |
|
|
44
|
+
| Your own column names on a board | Working |
|
|
45
|
+
| A UI reviewer for any website | Working |
|
|
46
|
+
| Built-in measurements for any website | Working |
|
|
47
|
+
| A design skill for any website | Working |
|
|
48
|
+
| `init`, which can be re-run, and `doctor` | Working |
|
|
49
|
+
| `remove` and `config explain` | Planned, not yet scheduled |
|
|
50
|
+
| `approvers` and `rules` in the settings | Planned, not yet scheduled |
|
|
51
|
+
| Starting builds from a scheduled workflow | Planned, not yet scheduled |
|
|
52
|
+
| `factory poller --once`, the scheduled workflow's one pass, and a poller built from an installed package | Planned, not yet scheduled |
|
|
53
|
+
| `factory migrate`, `factory board sync --dry-run`, and the `/factory-trace` skill | Planned, not yet scheduled |
|
|
54
|
+
| Another ticket system, such as Jira | Not planned. The design leaves room |
|
|
55
|
+
| Another code host or runner | Not planned. The design leaves room |
|
|
56
|
+
| Sharing plug-ins between repositories | Not planned |
|
|
57
|
+
|
|
58
|
+
When a part is built, its pull request updates this table, and corrects any
|
|
59
|
+
page the build had to differ from. [The CLI](cli.md) marks each command
|
|
60
|
+
built or planned.
|
|
61
|
+
|
|
62
|
+
## The folder
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
./
|
|
66
|
+
package.json name, version, bin, files, and its own dependencies
|
|
67
|
+
.claude-plugin/plugin.json so the folder is also a valid Claude Code plugin
|
|
68
|
+
bin/factory.js the launcher: plain JavaScript, no logic of its own
|
|
69
|
+
src/cli.mts reads the command and loads only that command's module
|
|
70
|
+
src/ one module per command, and the shared library
|
|
71
|
+
src/tickets/ the ticket interface, its GitHub adapter, and the transports
|
|
72
|
+
src/code-host/ the code host's interface and GitHub's implementation of it
|
|
73
|
+
src/runner/ the runner's interface and GitHub Actions' implementation of it
|
|
74
|
+
skills/factory-*/SKILL.md the skills
|
|
75
|
+
agents/factory-*.md the built-in reviewers
|
|
76
|
+
rules.md the process rules
|
|
77
|
+
review.md the CI reviewer's instructions
|
|
78
|
+
workflows/factory-*.yml the workflows copied into .github/workflows/
|
|
79
|
+
poller.Dockerfile the poller's image
|
|
80
|
+
docs/ these pages
|
|
81
|
+
tests/ the tool's tests and their fixtures
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
It is laid out as a Claude Code plugin even though it is not delivered as
|
|
85
|
+
one. That costs nothing, and it keeps the plugin's own tooling usable on the
|
|
86
|
+
folder. The settings are validated in code, and `settings.schema.json` is the
|
|
87
|
+
editor's copy of their keys. A new key goes in `SETTINGS_KEYS` in
|
|
88
|
+
`src/config.mts`, in the schema, and in `docs/configuration.md`, and a test
|
|
89
|
+
fails when the first two differ.
|
|
90
|
+
|
|
91
|
+
## Running from source
|
|
92
|
+
|
|
93
|
+
The tool is TypeScript, run directly by Node 22.18 or later with no build
|
|
94
|
+
step. In this repository, `npm ci` and then `node bin/factory.js`, or a
|
|
95
|
+
global `factory`, runs the source.
|
|
96
|
+
|
|
97
|
+
Node refuses to run TypeScript from inside `node_modules`, so an installed
|
|
98
|
+
package runs compiled JavaScript. `prepack` compiles `src/` to `dist/` with
|
|
99
|
+
`tsc`, and `src/` and `tests/` are not packed. The launcher, `bin/factory.js`,
|
|
100
|
+
serves both, and carries out what `chooseEntry` in `bin/launch.js` picks, in
|
|
101
|
+
this order:
|
|
102
|
+
|
|
103
|
+
1. The source in the repository it was run from: the first folder at or
|
|
104
|
+
above the current directory that has `.git`, when it has
|
|
105
|
+
`packages/factory/package.json` with this package's name. So a git
|
|
106
|
+
worktree runs its own copy, not the one `npx` finds up the tree.
|
|
107
|
+
2. The copy that repository installed, when that is not this one, so a
|
|
108
|
+
global install runs the repository's own version.
|
|
109
|
+
3. Nothing, with a line saying how to install it, when this copy is outside
|
|
110
|
+
that repository and the repository has none.
|
|
111
|
+
4. `src/cli.mts` beside the launcher, when it exists, and otherwise
|
|
112
|
+
`dist/cli.mjs`. Outside any repository, as in the poller's image, this
|
|
113
|
+
is always the choice.
|
|
114
|
+
|
|
115
|
+
Hooks run the launcher by its path with `node`, not through `npx`, since a
|
|
116
|
+
guard runs before every command a session runs: `npx` took 289 ms a call,
|
|
117
|
+
`node` on the launcher 56 ms.
|
|
118
|
+
|
|
119
|
+
To prove the package works outside its host, CI packs the folder, installs
|
|
120
|
+
the tarball into an empty repository, and runs `sync`, `sync --check`,
|
|
121
|
+
`config check`, and `plugins` there:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
npm run pack-check
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
To try settings against a board without changing the repository's, point
|
|
128
|
+
`FACTORY_SETTINGS` at another settings file. Every command reads that file in
|
|
129
|
+
place of `.claude/factory.yaml`, for as long as the variable is set:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
FACTORY_SETTINGS=/tmp/try.yaml factory board check
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Changing a skill, an agent, or a rule
|
|
136
|
+
|
|
137
|
+
Edit the source here. A repository that uses the factory gets the change
|
|
138
|
+
in the next release, as a copy under its `.claude/` and `.github/` that
|
|
139
|
+
`factory sync` writes; CI there runs `factory sync --check`, which fails
|
|
140
|
+
when a copy differs from its source, so an edit made to a copy by mistake
|
|
141
|
+
cannot merge.
|
|
142
|
+
|
|
143
|
+
A skill, agent, or workflow that the factory's own steps call is its core,
|
|
144
|
+
and every repository gets it. Anything else is written only when a setting
|
|
145
|
+
or a file in the repository turns it on: add it to `NEEDS` in
|
|
146
|
+
`src/sync.mts`, so a repository that does not use it never carries it.
|
|
147
|
+
|
|
148
|
+
A factory file must name nothing that belongs to the host repository: not
|
|
149
|
+
its paths, its commands, its subject, or its own skills. A test fails when
|
|
150
|
+
one does. That is what keeps the folder movable.
|
|
151
|
+
|
|
152
|
+
## Adding a ticket system
|
|
153
|
+
|
|
154
|
+
Only GitHub is built. The factory is built so that a second system is an
|
|
155
|
+
addition, not a rewrite. Four rules keep it that way.
|
|
156
|
+
|
|
157
|
+
**1. Nothing talks to the ticket system except through the tool.** A skill
|
|
158
|
+
never runs `gh issue` or calls GitHub's issues or projects API. It runs
|
|
159
|
+
`factory ticket view 12`, `factory ticket comment 12`, and the other
|
|
160
|
+
commands under [Tickets](cli.md#tickets). A test fails when a factory
|
|
161
|
+
skill, agent, rule, review instruction, or workflow contains a direct call.
|
|
162
|
+
|
|
163
|
+
**2. Three folders are the only code that calls GitHub.**
|
|
164
|
+
`src/tickets/` holds tickets and the board, `src/code-host/` pull
|
|
165
|
+
requests, reviews, and checks, whose conversation comments and labels
|
|
166
|
+
GitHub serves from its issues API, and `src/runner/` builds and their
|
|
167
|
+
runs. Every command reaches a ticket, a pull request, or a build through
|
|
168
|
+
one of them, and a test fails when a file elsewhere under `src/` calls
|
|
169
|
+
GitHub or holds a `github.com` address.
|
|
170
|
+
|
|
171
|
+
**3. The tool reads `tickets.type` and hands the work to that type's
|
|
172
|
+
adapter.** An adapter is one module in `src/tickets/` that implements the
|
|
173
|
+
`Tickets` type in `src/tickets/types.mts`. `github` is the only one; any
|
|
174
|
+
other value fails `factory config check` and every ticket command with
|
|
175
|
+
`tickets.type "X" is not supported. "github" is the only ticket system built.`
|
|
176
|
+
A type that names a package, so a team can write an adapter for a system
|
|
177
|
+
the factory does not ship, is planned, not built.
|
|
178
|
+
|
|
179
|
+
| Operation | In `Tickets` | What it returns or does |
|
|
180
|
+
| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
181
|
+
| Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
|
|
182
|
+
| List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are |
|
|
183
|
+
| Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
|
|
184
|
+
| Write a ticket's body | `writeBody` | |
|
|
185
|
+
| Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
|
|
186
|
+
| Edit a comment | `editComment` | By its ID |
|
|
187
|
+
| Delete a comment | `deleteComment` | By its ID |
|
|
188
|
+
| Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
|
|
189
|
+
| Open a ticket | `open` | With a title, a body, and labels. Returns its number |
|
|
190
|
+
| Add or remove a label | `addLabel`, `removeLabel` | |
|
|
191
|
+
| Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
|
|
192
|
+
| The address of a ticket | `address` | Its page, which the views link a ticket's number to |
|
|
193
|
+
|
|
194
|
+
"Read everything at once" has a default, `readAll` in
|
|
195
|
+
`src/tickets/types.mts`, built from `listOpen` and `read`, so a new adapter
|
|
196
|
+
need not write it; the default returns the open tickets, since a list of
|
|
197
|
+
open tickets cannot name the closed ones. The GitHub adapter overrides it
|
|
198
|
+
with one GraphQL query.
|
|
199
|
+
|
|
200
|
+
**4. An adapter says which optional groups it has.** Each group is there
|
|
201
|
+
whole or not at all, and `factory ticket supports GROUP` prints `yes` or
|
|
202
|
+
`no`. A skill asks before it relies on one; a command that needs a group
|
|
203
|
+
its adapter lacks exits non-zero, names the group, and posts nothing.
|
|
204
|
+
|
|
205
|
+
| Group | In `Tickets` | Operations |
|
|
206
|
+
| --------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
|
|
207
|
+
| `board` | `board` | Read every card and the board's fields; add a ticket to the board; set its fields |
|
|
208
|
+
| `blockers` | `blockers` | List what a ticket waits on; record that it waits on another; remove that |
|
|
209
|
+
| `label-history` | `labelHistory` | Whether a label was ever removed from a ticket, which is how the factory knows the owner took `spec` off |
|
|
210
|
+
| `attachments` | `attachments` | Comment with images attached, or write a body with them |
|
|
211
|
+
|
|
212
|
+
The GitHub adapter has every group, except that `attachments` needs the
|
|
213
|
+
GitHub CLI, so an adapter built without it has none. With
|
|
214
|
+
no board, state lives in the ticket's comments. With no blockers, the build
|
|
215
|
+
order is prose in the ticket and nothing enforces it.
|
|
216
|
+
|
|
217
|
+
**The transport is a parameter.** The GitHub adapter, `src/code-host/`, and
|
|
218
|
+
`src/runner/` take one function for a REST call, one for a GraphQL query,
|
|
219
|
+
and one for an answer in plain text, such as a job's log
|
|
220
|
+
(`src/tickets/transport.mts`). `ghTransport` runs the GitHub CLI, for
|
|
221
|
+
sessions and CI. `fetchTransport` calls the API with a token, for the
|
|
222
|
+
poller, which runs with no `gh` and no install; `poller.Dockerfile` copies
|
|
223
|
+
the adapter, the transport, and what else the poller imports, and a test
|
|
224
|
+
fails when it misses one.
|
|
225
|
+
|
|
226
|
+
What stays above the interface: working out a ticket's state from its
|
|
227
|
+
marker comments, costs, and the formatting of every view, in
|
|
228
|
+
`src/lib/work-status.mts` and the commands. They are the factory's own
|
|
229
|
+
logic, the same for any system.
|
|
230
|
+
|
|
231
|
+
A second adapter exists from the start: an in-memory one,
|
|
232
|
+
`tests/memory-tickets.ts`, that every command's tests run against. It
|
|
233
|
+
keeps the interface honest, since anything the tests need has to go
|
|
234
|
+
through it. The GitHub adapter has its own tests against recorded
|
|
235
|
+
responses.
|
|
236
|
+
|
|
237
|
+
What an adapter does not cover: pull requests, reviews, and checks, which
|
|
238
|
+
are the code host's, and where an unattended build runs, which is the
|
|
239
|
+
runner's. Each has an interface of its own, described next, so a team can
|
|
240
|
+
keep its tickets in one system, its code on another, and run its builds on
|
|
241
|
+
a third.
|
|
242
|
+
|
|
243
|
+
## Adding a code host
|
|
244
|
+
|
|
245
|
+
The code host is where pull requests are. Only GitHub is built. The
|
|
246
|
+
settings name it with `code-host.type`, and `src/code-host/index.mts` hands
|
|
247
|
+
a command the implementation of that name: one module in `src/code-host/`
|
|
248
|
+
that implements the `CodeHost` type in `src/code-host/types.mts`. Any other
|
|
249
|
+
value fails `factory config check`, and every command that reads the
|
|
250
|
+
settings and reaches a pull request, with
|
|
251
|
+
`code-host.type "X" is not supported. "github" is the only code host built.`
|
|
252
|
+
A type that names a package is planned, not built.
|
|
253
|
+
|
|
254
|
+
A command that a workflow also runs, such as `factory pr`, does not read
|
|
255
|
+
the settings there, so an unreadable settings file cannot fail the
|
|
256
|
+
workflow's step; it asks for the default. The poller has no settings at
|
|
257
|
+
all and names its implementations itself.
|
|
258
|
+
|
|
259
|
+
| Operation | In `CodeHost` | What it returns or does |
|
|
260
|
+
| ---------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
261
|
+
| Read a pull request; list the open ones | `get`, `listOpen` | Its number, title, state, whether it is merged or a draft, body, mergeable state, author, labels, head and base (commit, branch, repository), and auto-merge |
|
|
262
|
+
| Open a pull request | `create` | From one branch into another, with a title and a body, as a draft or not. Returns its number, and fails in the code host's own words when the branch has nothing new or already has one open |
|
|
263
|
+
| Find a pull request | `forBranch`, `forCommit` | The open pull request from a branch, or none; the pull requests that hold a commit |
|
|
264
|
+
| What a pull request changes | `files`, `mergeBase` | Each file's path, its path before a rename, and its status; the commit two commits both descend from |
|
|
265
|
+
| The default branch | `defaultBranch` | |
|
|
266
|
+
| The checks on a commit | `checkRuns`, `statuses`, `setStatus` | Check runs and commit statuses, kept apart because `factory deps` reads check runs alone and `factory pr watch` reads both; sets a status by name. A check run carries what the check wrote about its own result, when it wrote anything |
|
|
267
|
+
| Conversation comments | `comments`, `commentView`, `comment`, `editComment` | Each with its ID, author, time, and body. `comment` returns the new comment's ID, and hidden markers pass through unchanged |
|
|
268
|
+
| Not found | `NotFoundError` | Reading a pull request or a comment that does not exist throws this, the same error the ticket interface throws |
|
|
269
|
+
| Add or remove a label | `addLabel`, `removeLabel` | |
|
|
270
|
+
| Reviews | `reviews`, `reviewCommentsOf`, `reviewComments` | Each review's ID, author, body, and time; the comments one review left on lines; every such comment on the pull request. A reply in a thread carries the comment it replies to |
|
|
271
|
+
| Review threads | `threads`, `openThreadCount`, `reply`, `resolve` | Each thread's first comment, file and line, comments, and whether it is resolved or outdated. `reply` and `resolve` take a comment's ID |
|
|
272
|
+
| Write a body; mark ready | `setBody`, `ready` | |
|
|
273
|
+
| Commits not shown as signed | `unverifiedCommits` | One line for each, its short ID and the reason, which `factory pr ready` prints when it refuses |
|
|
274
|
+
| The tickets a pull request closes | `closes` | Their numbers |
|
|
275
|
+
| The pull requests as the views read them | `open`, `linking` | The open ones with their closing links, open threads, and check state; and those, open or not, that link to a ticket, which the board sync reads for cost notes |
|
|
276
|
+
| The address of a pull request | `address` | Its page, which the views link a pull request's number to |
|
|
277
|
+
|
|
278
|
+
There are no optional groups. Every operation is one a command uses
|
|
279
|
+
today, so a group is carved out on the day a second code host lacks one.
|
|
280
|
+
|
|
281
|
+
**No skill, agent, or rule reaches the code host or the runner itself.**
|
|
282
|
+
Each runs a `factory pr` command, and a test fails when one names GitHub's
|
|
283
|
+
CLI, as a command or in a sentence. The review's instructions, `review.md`,
|
|
284
|
+
are the one exception: the review's checkout is the pull request's head, so
|
|
285
|
+
the factory's commands there are the code under review, and its reads go
|
|
286
|
+
through GitHub's CLI on purpose.
|
|
287
|
+
|
|
288
|
+
A commit's checks and statuses belong to the code host, not the runner: a
|
|
289
|
+
pull request shows them whatever ran them. A check run carries `checksId`,
|
|
290
|
+
the ID it shares with the runner's run that reported it, which is how
|
|
291
|
+
`factory pr wait-checks` names the checks of a run that failed.
|
|
292
|
+
|
|
293
|
+
What a command prints or hands on under GitHub's own field names keeps
|
|
294
|
+
those names: `factory pr comments --json` prints each comment's `id`,
|
|
295
|
+
`user.login`, `body`, and `created_at`, and `merge-policy` hands each of
|
|
296
|
+
your commands `filename`, `previous_filename`, and `status`. The command
|
|
297
|
+
turns the interface's answer back into those names, so they hold on any
|
|
298
|
+
code host. Those are all it prints: a field GitHub returns that the
|
|
299
|
+
interface does not carry, such as a comment's `html_url`, is not among
|
|
300
|
+
them.
|
|
301
|
+
|
|
302
|
+
A second implementation exists from the start, `tests/memory-code-host.ts`,
|
|
303
|
+
that the tests of `pr`, `deps`, `build`, and `review cost` run against.
|
|
304
|
+
GitHub's has its own tests against faked replies, which is where a test
|
|
305
|
+
of which call GitHub is sent belongs.
|
|
306
|
+
|
|
307
|
+
## Adding a runner
|
|
308
|
+
|
|
309
|
+
The runner is where an unattended build runs. Only GitHub Actions is
|
|
310
|
+
built. The settings name it with `builds.runner`, and
|
|
311
|
+
`src/runner/index.mts` hands a command the implementation of that name:
|
|
312
|
+
one module in `src/runner/` that implements the `Runner` type in
|
|
313
|
+
`src/runner/types.mts`. Any other value fails `factory config check`, and
|
|
314
|
+
every command that reads the settings and reaches the runner, with
|
|
315
|
+
`builds.runner "X" is not supported. "github-actions" is the only runner built.`
|
|
316
|
+
|
|
317
|
+
| Operation | In `Runner` | What it returns or does |
|
|
318
|
+
| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
319
|
+
| Start a build of a ticket | `startBuild` | On a branch. A refused start throws the runner's own error, whose status and reason the poller's comment on the ticket carries |
|
|
320
|
+
| Find the run a start made | `findBuild` | The page of the ticket's build started at or after a time, or nothing while none shows: a runner may answer a start with no run |
|
|
321
|
+
| The page that lists builds | `buildsPage` | What `factory build` prints when the run is not found |
|
|
322
|
+
| The page of a run | `runPage` | From the run's ID, which a ticket's claim comment records |
|
|
323
|
+
| The run this session is in | `thisRun` | Its ID, its page, and who started it, read from the session's environment; nothing outside a run |
|
|
324
|
+
| The runs for a commit | `runs` | Each run's ID, which set of jobs it is a run of, what started it, its status and conclusion, and its `checksId` |
|
|
325
|
+
| The review's runs for a commit | `reviewRuns` | Their status and conclusion, newest first |
|
|
326
|
+
| Have the review run again | `reviewAgain` | The newest run of a commit's review, run again; false when none has run on it |
|
|
327
|
+
| The jobs that failed in a run | `failedJobs` | Each failed job's name and everything it printed. Which runs count is the caller's: `factory pr failed` takes those `wait-checks` waits on |
|
|
328
|
+
|
|
329
|
+
**A runner also needs its own job files, which no interface covers.** The
|
|
330
|
+
workflows under `workflows/`, the action they share, and their secrets
|
|
331
|
+
are GitHub Actions' own. `factory sync` copies them whatever
|
|
332
|
+
`builds.runner` says, and another runner would need its own set, written
|
|
333
|
+
for it.
|
|
334
|
+
|
|
335
|
+
Three things stay in GitHub Actions' words whatever the runner: the
|
|
336
|
+
factory's messages and comments say "GitHub Actions", the marker comments
|
|
337
|
+
on tickets say `actions`, and the board's "Runs in" field says "Actions".
|
|
338
|
+
The commands only a workflow runs (`review verdict`, `merge-policy`, and
|
|
339
|
+
`review cost`) read GitHub Actions' event file and its `GITHUB_*`
|
|
340
|
+
variables, and reach pull requests through the code host.
|
|
341
|
+
|
|
342
|
+
The in-memory runner is `tests/memory-runner.ts`, and GitHub Actions' has
|
|
343
|
+
its own tests against faked replies.
|
|
344
|
+
|
|
345
|
+
## Checking a change
|
|
346
|
+
|
|
347
|
+
| Check | What it proves |
|
|
348
|
+
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
349
|
+
| The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted |
|
|
350
|
+
| `factory sync --check` | The copies match the source |
|
|
351
|
+
| Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
|
|
352
|
+
| `/factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
|
|
353
|
+
| One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
|
|
354
|
+
|
|
355
|
+
The skills are instructions, and instructions cannot be unit tested. The
|
|
356
|
+
last row is the only real proof that a change to one still works.
|
|
357
|
+
|
|
358
|
+
## Releasing
|
|
359
|
+
|
|
360
|
+
1. Raise `version` in `package.json` in a pull request, and merge it.
|
|
361
|
+
2. Tag the merge commit with the same version and push the tag:
|
|
362
|
+
|
|
363
|
+
```bash
|
|
364
|
+
git tag v0.2.0 && git push origin v0.2.0
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
3. The release workflow checks that the tag matches `package.json`,
|
|
368
|
+
runs the tests and `pack-check`, and publishes the version to npm.
|
|
369
|
+
|
|
370
|
+
The first version, 0.1.0, was published by hand, since npm sets up a
|
|
371
|
+
trusted publisher only for a package that exists:
|
|
372
|
+
|
|
373
|
+
```bash
|
|
374
|
+
npm ci
|
|
375
|
+
npm publish --access public
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
Then, on npmjs.com, the package's settings name this repository's
|
|
379
|
+
`release.yml` as its trusted publisher, so later versions publish with no
|
|
380
|
+
token. Nothing published can be taken back after 72 hours, and
|
|
381
|
+
`pack-check` fails when a packed file names the repository the factory was
|
|
382
|
+
drawn out of.
|
|
383
|
+
|
|
384
|
+
## Writing for the factory
|
|
385
|
+
|
|
386
|
+
- **American English, with the Oxford comma.**
|
|
387
|
+
- **The factory's own words:** ticket, follow-up, the six states, the three
|
|
388
|
+
roles. Not issue, card, or sweep.
|
|
389
|
+
- **A key name must make sense unexplained.** Each reference settings file
|
|
390
|
+
is read cold by a fresh agent that is told only what the factory is. A key
|
|
391
|
+
it explains wrongly, or cannot tell from another, is renamed or given a
|
|
392
|
+
better comment.
|
|
393
|
+
- **A setting has a default, or it has a reason not to.**
|
|
394
|
+
- **A page says what is built.** Anything not built carries the _Planned_
|
|
395
|
+
mark where it is used, linked to "What is built", and a test fails on a
|
|
396
|
+
planned command named without it. When a ticket builds something, its
|
|
397
|
+
pull request removes the mark, and corrects the page where the build had
|
|
398
|
+
to differ.
|
|
399
|
+
- **Examples carry the reason for a rule, without the host's private
|
|
400
|
+
history.**
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# Adopting it in an existing repository
|
|
2
|
+
|
|
3
|
+
Most repositories already have a toolchain, a board, instructions for a
|
|
4
|
+
coding agent, or a team. This page says what the factory does in each case,
|
|
5
|
+
and what it leaves alone.
|
|
6
|
+
|
|
7
|
+
## Try it without committing to it
|
|
8
|
+
|
|
9
|
+
Do the [quick start](quick-start.md) on a branch and do not merge it. Start
|
|
10
|
+
an agent session on that branch and refine and build one ticket. If you
|
|
11
|
+
decide against it, delete the branch. [Removing it](removing.md) covers the
|
|
12
|
+
case where you have already merged.
|
|
13
|
+
|
|
14
|
+
## A repository that is not JavaScript
|
|
15
|
+
|
|
16
|
+
The factory's tool runs on Node and is installed with npm, whatever your
|
|
17
|
+
project is written in. In a PHP, Python, or Go repository that means:
|
|
18
|
+
|
|
19
|
+
- **A `package.json` appears**, holding one development dependency and
|
|
20
|
+
nothing else. `factory init` creates it if you have
|
|
21
|
+
none, marked private so it can never be published.
|
|
22
|
+
- **`package-lock.json` is committed.** It is what keeps everyone on the
|
|
23
|
+
same version of the factory.
|
|
24
|
+
- **`node_modules/` is ignored.** `factory init` adds it
|
|
25
|
+
to your `.gitignore`.
|
|
26
|
+
- **Everyone who works on the repository needs Node 22.18 or later**, and
|
|
27
|
+
runs `npm ci` once after cloning.
|
|
28
|
+
- **Your own CI does not change.** The factory's cloud jobs install Node
|
|
29
|
+
for themselves. If you turn on the automated review, how it installs your
|
|
30
|
+
project, such as `composer install`, is yours to edit.
|
|
31
|
+
- **Your commands stay yours.** `before-commit` in the settings takes any
|
|
32
|
+
command: `composer lint`, `make check`, `go vet ./...`.
|
|
33
|
+
|
|
34
|
+
The factory's hooks run its own tool, so they need nothing beyond Node.
|
|
35
|
+
Someone who only writes code by hand, and never runs an agent session in
|
|
36
|
+
the repository, needs none of this.
|
|
37
|
+
|
|
38
|
+
[Configuration](configuration.md#a-repository-that-is-not-javascript) has a
|
|
39
|
+
complete settings file for a PHP library.
|
|
40
|
+
|
|
41
|
+
## You already have a board
|
|
42
|
+
|
|
43
|
+
`factory init` lists your boards to choose from, and gives
|
|
44
|
+
the one you choose any of the factory's six columns and three fields it
|
|
45
|
+
lacks. A column of yours whose name matches one of the six, whatever its
|
|
46
|
+
case, is used as it is; your other columns stay, after the six. It says
|
|
47
|
+
what it added:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
Added to board 3: Backlog, In refinement, Ready, In review, Session, Runs in, Cost.
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- **It adds; it never renames or removes.** Your "Todo" column stays, with
|
|
54
|
+
its cards.
|
|
55
|
+
- **A card in a column the factory does not know is ignored.** Nothing
|
|
56
|
+
moves it, and nothing builds it. In this example that is everything in
|
|
57
|
+
"Todo": move a card to Backlog when you want the factory to track it,
|
|
58
|
+
or move them all once and retire the column.
|
|
59
|
+
- **The factory's fields are overwritten on every sync.** Do not type into
|
|
60
|
+
Session, Runs in, or Cost. Your own fields are never touched.
|
|
61
|
+
- **Using your own column names** works today: `tickets.columns` in your
|
|
62
|
+
settings says which of your columns shows each state, and `none` says your
|
|
63
|
+
board has none. [Configuration](configuration.md#ticketscolumns) has the
|
|
64
|
+
mapping for a board with Todo, In Progress, and Done. To see what the
|
|
65
|
+
factory will do with your board, run:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
factory board check
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- **Your board's own automations**, such as moving a closed ticket to
|
|
72
|
+
Done, have not been tested alongside the factory. Turn them off if cards
|
|
73
|
+
jump unexpectedly.
|
|
74
|
+
|
|
75
|
+
A board owned by an organization is read the same way as a person's, but
|
|
76
|
+
has not yet been run against a real one. A repository an organization owns
|
|
77
|
+
has one more gap: only the owner's comments count as answers, and the
|
|
78
|
+
owner is read from the repository's name, which there is the
|
|
79
|
+
organization's.
|
|
80
|
+
|
|
81
|
+
## You already have agent instructions, settings, or CI workflows
|
|
82
|
+
|
|
83
|
+
- **Your agent's instructions file:** one line is added at the end,
|
|
84
|
+
importing the factory's rules. Nothing else in it changes. Your own rules
|
|
85
|
+
win where the two disagree.
|
|
86
|
+
- **Your agent's settings:** a few hooks are added, and the agent's
|
|
87
|
+
attribution lines are turned off, so a session's commits and pull
|
|
88
|
+
requests carry no line naming an AI: they are yours. A cloud build's
|
|
89
|
+
commits name the agent as their author instead
|
|
90
|
+
([Builds in the cloud](builds.md)). If your settings already
|
|
91
|
+
say how to attribute, that stays. Your existing hooks, permissions, and
|
|
92
|
+
settings stay as they are.
|
|
93
|
+
- **Your skills and agents:** untouched. Everything the factory adds is
|
|
94
|
+
named `factory-...`, so nothing collides.
|
|
95
|
+
- **Your CI workflows:** untouched. The factory's are named `factory-...`.
|
|
96
|
+
- **`factory init` lists every file** it would write or
|
|
97
|
+
change before it writes, and changes nothing if you say no.
|
|
98
|
+
|
|
99
|
+
On GitHub with Claude Code, [the reference](github/reference.md#what-setup-adds)
|
|
100
|
+
names each file.
|
|
101
|
+
|
|
102
|
+
## A team
|
|
103
|
+
|
|
104
|
+
- **A person's own session acts as that person.** A commit made by a
|
|
105
|
+
teammate's session goes out under that teammate's account. A cloud build
|
|
106
|
+
acts as the one account that owns its token: yours, or an account you
|
|
107
|
+
create for the team's builds
|
|
108
|
+
([Builds in the cloud](github/setup.md#builds-in-the-cloud)).
|
|
109
|
+
- **Say who approves.** By default only the repository's owner can approve
|
|
110
|
+
a ticket for building or give a session instructions in a comment. List
|
|
111
|
+
the others under [`approvers`](configuration.md#approvers), _[Planned](developing.md#what-is-built)_.
|
|
112
|
+
- **One version for everyone.** The version is pinned in
|
|
113
|
+
`package-lock.json`. After an update merges, each person pulls and runs
|
|
114
|
+
`npm ci`. `factory doctor` says so when the installed
|
|
115
|
+
version and the repository's disagree.
|
|
116
|
+
- **One session per ticket.** A session claims a ticket before it starts,
|
|
117
|
+
and a second one is told who holds it.
|
|
118
|
+
- **One person merges updates.** An update changes the instructions
|
|
119
|
+
everyone's sessions follow, so it always waits for a person.
|
|
120
|
+
[Updating](updating.md) describes it.
|
|
121
|
+
- **Check your coding agent's plan** covers the way your team would use
|
|
122
|
+
this, including builds that run without anyone watching.
|
|
123
|
+
|
|
124
|
+
## What it does to your repository, in short
|
|
125
|
+
|
|
126
|
+
[What it changes](removing.md) says what kinds of things the factory adds,
|
|
127
|
+
and how to undo each. The short version:
|
|
128
|
+
|
|
129
|
+
- Files it owns, all named `factory-...`, and its rules.
|
|
130
|
+
- One line in your agent's instructions file, and a few hooks in your
|
|
131
|
+
agent's settings.
|
|
132
|
+
- Hooks that stop a session committing on your main branch or force
|
|
133
|
+
pushing, and that run your `before-commit` commands. They apply to agent
|
|
134
|
+
sessions, not to your own terminal.
|
|
135
|
+
- Its CI workflows: one that checks the factory's files are in step, the
|
|
136
|
+
ones that run a session in the cloud, and one more for each optional part
|
|
137
|
+
you turn on. One that offers you new versions is _[Planned](developing.md#what-is-built)_.
|
|
138
|
+
- Comments on tickets it works, and one "Follow-ups" ticket.
|