@davidbyoung/software-factory 0.0.0-stage → 0.1.1

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 +209 -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,159 @@
1
+ ---
2
+ name: factory-design
3
+ description: Design a visible change to a website, a new page or a redesign, as the designer rather than asking the owner to be one: real-content mockups built from the site itself, pictured at its widths in light and dark, reviewed before anyone sees them, and one recommended design. Use when asked to redesign, restyle, or rethink how a page looks or what it says, when an issue asks for renderings to approve, and as the `mockups` plug-in `factory-refine` calls.
4
+ ---
5
+
6
+ # Designing a change
7
+
8
+ The owner hired an expert. Decide what an expert would decide, and bring
9
+ them a recommendation, not a menu. Each round the owner has to spend
10
+ catching a defect or making a design call is a round this skill exists to
11
+ remove.
12
+
13
+ It works on any site whose `.claude/factory.yaml` has a `site` block:
14
+ `site.start` says how to build and serve it, and `factory site compare`
15
+ pictures it.
16
+
17
+ ## 0. Is there a look to choose?
18
+
19
+ A mockup answers one question: which look does the owner want? When there
20
+ is one acceptable look, there is no question, and a mockup round spends
21
+ the owner's time on nothing. Before drawing, read the issue's acceptance
22
+ criteria and Decisions. Stop here, and say why, when:
23
+
24
+ - the criteria say the page must look the same at rest, or the change is
25
+ to targets, focus rings, contrast, or markup, and no Decision says the
26
+ look changes; or
27
+ - the only choice is one the design guide already makes; or
28
+ - the change is small ("Small changes" in `.claude/factory/rules.md`): its
29
+ pull request carries the built result, and that is the picture.
30
+
31
+ The proof for a change with no look to choose is not a picture of it. It
32
+ is `npx --no-install factory site compare` on the branch, whose
33
+ measurements and the site's own `checks` say whether anything got worse,
34
+ and, for a change to a state such as an open menu or keyboard focus, that
35
+ state measured as section 3 step 4 says. Say so in the report, so the
36
+ issue's acceptance criteria can name it.
37
+
38
+ ## 1. Know the site before drawing
39
+
40
+ - **The design guide.** `npx --no-install factory config get
41
+ site.design-guide` names it. Read it first: its rules, each with its
42
+ check. When it prints `none`, the site has no guide: design from the
43
+ site's own pages, and say in the round that there was no guide.
44
+ - **The audience and the copy's rules.** They are in the project's own
45
+ instructions, which you have read already: who the visitors are, what
46
+ each should do next, and what copy must keep. When they say nothing about
47
+ the visitors, work it out from the site's pages, its home page first,
48
+ and say in the round what you took from them, so the owner can correct
49
+ it.
50
+
51
+ A design that breaks a rule of the guide names the rule and the reason
52
+ under "Decisions" in its issue, for the owner to approve.
53
+
54
+ Then write down, for yourself:
55
+
56
+ - the page's audiences and the one action each should take
57
+ - what a visitor needs to know, in the order they will want it
58
+ - what the page must prove about the business
59
+ - the existing element each new piece copies
60
+
61
+ ## 2. Draft one design, in real content
62
+
63
+ - Use the site's real copy, counts, images, fonts, and colors. Write the
64
+ copy yourself; never leave "lorem" or a generic tagline for the owner to
65
+ fix.
66
+ - **A mockup is a real build of the change,** pictured by `factory site
67
+ compare` (section 3), so it carries the site's own styles. Markup put
68
+ into a running page is for posing a passing state only, such as an open
69
+ menu, with inline styles, never for the design itself: a stylesheet
70
+ built from the source may leave out a class the source has never used.
71
+ - **Nothing in a mockup misleads.** Sample text typed into one says
72
+ nothing false about the site's real content, since a made-up complaint
73
+ about a real page reads as a finding.
74
+ - **Every line of copy the Spec promises is in the mockup,** so no line
75
+ points at a picture that does not exist.
76
+ - Make the calls that have a conventional answer yourself: section order,
77
+ which button is primary, link and label styling, spacing, line length.
78
+ Say what you decided and why in one line each.
79
+ - Offer alternatives only where the choice is genuinely the owner's: brand
80
+ voice, which image, a headline that trades clarity for warmth. At most
81
+ three, each shown, with your pick marked.
82
+
83
+ ## 3. Make the round
84
+
85
+ Each round, fix rounds included, is these steps in this order. Each
86
+ depends on the one before.
87
+
88
+ 1. **A scratch worktree of the default branch**, and the change made in
89
+ it. Note what `git worktree list` shows first. From the checkout this
90
+ session works in, with the repository's default branch in place of
91
+ `main`:
92
+
93
+ ```bash
94
+ git worktree add --detach ../mockup-SLUG origin/main
95
+ ```
96
+
97
+ An option is its own worktree, made the same way. The change need not
98
+ be committed: the comparison pictures the worktree as it stands.
99
+
100
+ 2. **Install it,** from the scratch worktree: `npm ci` where the
101
+ repository has a lock file, then each command `npx --no-install factory
102
+ config get build-setup` prints. The comparison installs the default
103
+ branch's side, not this one, and the factory, the browser, and
104
+ `site.start` all run from here.
105
+ 3. **Picture it,** from the scratch worktree:
106
+
107
+ ```bash
108
+ npx --no-install factory site compare --keep
109
+ ```
110
+
111
+ It builds the change and the default branch, pictures every page at the
112
+ site's widths in light and dark, outlines what changed, measures each
113
+ changed view, and runs the site's own `checks`. It leaves both sites
114
+ running and prints their addresses. Its pictures are under the scratch
115
+ worktree's `node_modules/.cache/factory/site/`.
116
+
117
+ 4. **Pose the states** the design is about, such as a menu open or a form
118
+ with an error, against the two addresses, as `factory-ui-reviewer`'s
119
+ step 3 says, in the same views. Pose each the same way in light and
120
+ dark, so a pair differs only in its scheme: the same content, any
121
+ randomness the page uses seeded, phone emulation for a phone view (so
122
+ no desktop scrollbar shows), and the pointer moved off the page. Picture
123
+ each state, and measure it the way the site's design guide says to
124
+ measure a posed state, when it says.
125
+ 5. **Copy the round out** before anything else goes: the changed views'
126
+ pictures, the posed states' pictures, the comparison's lines, and each
127
+ posed state's measurements, into a folder git ignores in the checkout
128
+ this session works in, `node_modules/.cache/factory/design/` with the
129
+ time in its name.
130
+ 6. **Review it,** as section 4 says, from that folder.
131
+ 7. **Stop and clean up,** from the scratch worktree:
132
+ `npx --no-install factory site stop`, which ends both sites and removes
133
+ the default branch's worktree. Then, from the checkout this session
134
+ works in, `git worktree remove --force ../mockup-SLUG`, and check that
135
+ `git worktree list` shows what it showed before step 1.
136
+
137
+ A round that stops partway still runs step 7.
138
+
139
+ ## 4. Review every round before anyone else sees it
140
+
141
+ 1. Have `factory-ui-reviewer` read the round in its "From screenshots"
142
+ mode, handed the round's folder from step 5: the pictures, every
143
+ `measured:` line and `checks` line the comparison printed, and each
144
+ posed state's measurements. Fix every high and medium finding, or
145
+ record the break as a Decision, then make the round again.
146
+ 2. Put the comparison's lines and what the reviewer found in the round you
147
+ send, quoted.
148
+
149
+ ## 5. Present, then build
150
+
151
+ Show each mockup beside the current design, its before and after pictures
152
+ together, with the recommendation first and a short "what changed and
153
+ why". In a session with the owner, send the pictures rendered; in a
154
+ comment round, attach them. Every option offered to the owner is mocked;
155
+ an option with no picture is not offered. Ask only the question that
156
+ changes direction.
157
+
158
+ Once approved, the build makes it in code, and its pull request carries
159
+ `factory-ui-reviewer`'s pictures of the real page.
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: factory-diagnose
3
+ description: Find the cause of a bug, a failing or flaky test, or a slowdown before changing any code, from one command that fails on the exact symptom. Use when something is broken, failing, flaky, or slow and the cause is not already known.
4
+ ---
5
+
6
+ # Diagnosing a bug
7
+
8
+ Reading code to build a theory before anything fails on demand is the
9
+ failure this skill prevents. A theory with no failing command behind it
10
+ gets a fix that fixes something else.
11
+
12
+ ## 1. Build the loop
13
+
14
+ The loop is one command that fails on this bug and passes once it is
15
+ fixed. Everything after it only spends it, so spend the effort here.
16
+ Reach for the cheapest that gets to the symptom:
17
+
18
+ 1. A unit test at the seam nearest the bug, run alone with the command
19
+ "After every code change" in `CLAUDE.md` gives. A decision buried in a component
20
+ moves into its `.ts` sibling first, as `AGENTS.md` prefers, where a
21
+ unit test reaches it without a DOM.
22
+ 2. A script in the scratchpad that imports the module and calls it with
23
+ the failing input, run with `node`.
24
+ 3. For a script under `scripts/`, the real invocation on a fixture input,
25
+ its output diffed against a known-good copy.
26
+ 4. An end-to-end spec, when the symptom needs a browser, run alone and
27
+ repeated with the command "After every code change" in `CLAUDE.md`
28
+ gives. It builds the site first,
29
+ so it is the slowest loop; never `next dev`, which rewrites
30
+ `AGENTS.md`.
31
+ 5. `git bisect run` with any of the above, when the bug arrived between
32
+ two known commits.
33
+ 6. A CI failure that will not reproduce locally: read the failed job's log
34
+ (`npx --no-install factory pr failed N`), then close the gap between the two
35
+ environments one difference at a time (CI runs Playwright on 2
36
+ workers, against a fresh build, with `CI` set).
37
+
38
+ Then tighten it: faster (one file, one test, a filtered page), sharper (it
39
+ asserts the symptom the report names, not "did not throw"), and steadier
40
+ (`page.clock` or fake timers, a seeded `Math.random`).
41
+
42
+ **A flaky failure** needs a reproduction rate, not a clean repro. Repeat
43
+ it (`--repeat-each=50`, or `{ repeats: 50 }` on a Vitest test), and add
44
+ the load CI has, more workers or a second suite at once, until it fails
45
+ often enough to tell a fix from luck. A 1-in-100 flake cannot be
46
+ debugged; a 1-in-3 can.
47
+
48
+ **Done when** you can show the command and its output, already run, and
49
+ it fails on the symptom the report describes, gives the same verdict
50
+ every run (or a pinned rate for a flake), and runs unattended. When no
51
+ such command can be built, stop and say what was tried, and ask for what
52
+ would make one: a log, a recording, steps, or access.
53
+
54
+ ## 2. Shrink it
55
+
56
+ Check that it fails on the reported symptom, not on a neighbor. Then cut
57
+ the input, the setup, and the steps one at a time, re-running after each
58
+ cut, until removing anything else makes it pass. What is left is the
59
+ regression test in step 5.
60
+
61
+ ## 3. Rank hypotheses
62
+
63
+ Write three to five causes before testing any, each with the prediction
64
+ that would prove it: "if X is the cause, changing Y makes it pass." One
65
+ that predicts nothing is dropped. When the owner is in the session, show
66
+ the list before testing it, since they may rule one out at a glance;
67
+ otherwise go on.
68
+
69
+ ## 4. Test them, one change at a time
70
+
71
+ Each probe tests one prediction. Prefer a breakpoint or a REPL to logs;
72
+ when logging, tag every line `[DEBUG-xxxx]` with one random tag, so
73
+ removing them is one grep. For a slowdown, measure before changing
74
+ anything (a timer, the profiler, Playwright's trace), and bisect against
75
+ the number.
76
+
77
+ ## 5. Fix it
78
+
79
+ Turn the shrunk repro into a test at a seam that runs the real path the
80
+ bug took. Run it red before the fix, then green after, as
81
+ `tests/CLAUDE.md` says. When no seam reaches the bug, the test would pass
82
+ either way: say so in the pull request rather than ship it, and name the
83
+ decision that should move into a plain function.
84
+
85
+ Then run step 1's loop on the original, unshrunk case.
86
+
87
+ ## 6. Clean up
88
+
89
+ - the original loop passes
90
+ - the regression test failed before the fix and passes after
91
+ - `git grep -n 'DEBUG-xxxx'` finds nothing
92
+ - scratch scripts stay in the scratchpad, not the repository
93
+ - the commit message names the cause the evidence confirmed
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: factory-mutate
3
+ description: Prove a test can fail by breaking the code under test one way at a time and watching the test go red. Use for a new or changed test written after the code, or never seen failing on its own symptom, and when asked whether a test locks anything in.
4
+ ---
5
+
6
+ # Checking that a test can fail
7
+
8
+ A test that passes whether or not the fix is there has locked nothing in.
9
+ This has shipped more than once. The check is to break the code and watch
10
+ the test go red.
11
+
12
+ ## 1. Pick the mutations
13
+
14
+ For each behavior the new tests claim to cover, write the smallest edit to
15
+ the **source** (never the test) that removes that behavior:
16
+
17
+ - delete the line that does it
18
+ - invert or drop a condition: `a && b` to `a`, `>` to `>=`
19
+ - return a constant: `return true`, `return []`, `return null`
20
+ - skip a call: `cleanup()`, `setState(x)`, `focus()`
21
+
22
+ One mutation per behavior, except where "Small changes" in `.claude/factory/rules.md`
23
+ says otherwise. A mutation that leaves the code
24
+ not compiling proves nothing; choose another.
25
+
26
+ ## 2. Run them
27
+
28
+ Each one copies the file aside, applies the edit, runs only the relevant test
29
+ file, and restores the original whatever happens. Put the script in the
30
+ scratchpad, not the repo:
31
+
32
+ ```python
33
+ import shutil, subprocess
34
+
35
+ MUTATIONS = [
36
+ # (source file, exact text, replacement, test file)
37
+ ("lib/x.ts", "if (a && b)", "if (a)", "tests/x.test.ts"),
38
+ ]
39
+ for path, old, new, test in MUTATIONS:
40
+ original = open(path).read()
41
+ assert original.count(old) == 1, (path, old)
42
+ try:
43
+ open(path, "w").write(original.replace(old, new))
44
+ failed = subprocess.run(["npx", "vitest", "run", test],
45
+ capture_output=True).returncode != 0
46
+ finally:
47
+ open(path, "w").write(original)
48
+ print("RED " if failed else "GREEN", path, old)
49
+ ```
50
+
51
+ Use the project's own test command. For a coverage-instrumented runner,
52
+ disable coverage for speed. For Playwright, rebuild before each run if the
53
+ tests run against a build. Not `next dev`: it rewrites `AGENTS.md`, and a
54
+ test can time out there with nothing broken, which reads as red.
55
+
56
+ ## 3. Confirm the tree is clean
57
+
58
+ ```bash
59
+ git status --short
60
+ git diff --stat
61
+ ```
62
+
63
+ Only the changes that were there before should show. If a source file is
64
+ still modified, restore it before doing anything else.
65
+
66
+ ## 4. Act on the result
67
+
68
+ - **RED** for every mutation: report it in one line.
69
+ - **GREEN**: the test did not notice the behavior break. Either the test
70
+ asserts something else, the behavior is covered only by a slower suite, or
71
+ the test environment cannot reproduce the condition. Fix the test, or, when
72
+ the environment is the limit, move the decision into a plain function a
73
+ unit test can reach and test it there. Say which.
74
+
75
+ Never weaken a mutation to get a RED. If the honest mutation stays green, the
76
+ test is what needs work.