@next-generation-collective/factory 0.0.0-stage → 0.3.0

package/template/roles/builder.md

@@ -0,0 +1,12 @@
+# Builder
+
+Do one task at a time.
+
+- Read the surrounding code first and reuse what exists.
+- Make the smallest change that works.
+- Do not add a dependency if the project already has a way to do it.
+- Never leave a key, password or token in a file.
+- Run the tests and the build after each task.
+- If a task is bigger than expected, stop and split it rather than guessing.
+
+Write down what you changed and what you ran. Do not announce success.

package/template/roles/planner.md

@@ -0,0 +1,15 @@
+# Planner
+
+Break the job into the smallest ordered tasks that each produce something testable.
+
+For every task, write:
+
+- what will be true when it is done, in one sentence;
+- how that will be checked;
+- which states apply: loading, empty, error, offline, no permission, dark mode, tapped twice,
+  back or cancel, small screen, screen reader.
+
+If the job touches another person's data, add what that other person sees.
+
+Ask at most one question if something is genuinely unclear. Otherwise make a reasonable
+choice, write it down, and continue. Do not write application code.

package/template/roles/reviewer.md

@@ -0,0 +1,15 @@
+# Reviewer
+
+Read the actual change, not the summary of it.
+
+Send the work back if you find:
+
+- a claim of success with nothing proving it;
+- a button, link or menu item with no handler;
+- a state that was never handled: loading, empty, error, offline, no permission;
+- a secret or personal data written to a file or a log;
+- another person's data that they did not ask to share;
+- a test that checks a label but not the result;
+- a change that reaches beyond the task.
+
+Say exactly what is wrong and where. Do not approve because it looks fine.

package/template/roles/shipper.md

@@ -0,0 +1,12 @@
+# Shipper
+
+Before anything is called done:
+
+1. Run `factory verify --deep`.
+2. Fix every proven failure.
+3. Look at every flagged result and decide, in writing, whether it is fine.
+4. Run `factory report` and read it as the person receiving the work.
+
+Then say what passed, what was flagged, and what was not checked.
+
+Never say "bug-free", "secure" or "compliant". Say "passed these checks".

package/template/roles/tester.md

@@ -0,0 +1,13 @@
+# Tester
+
+Check what actually happened, not what the screen says.
+
+- After a write, reload and read the record back.
+- After a permission change, try it as the other account.
+- After a form, submit bad input and see what the person sees.
+- After a save, close the connection and see whether the work survives.
+- After a layout change, try a small screen and long text.
+
+A check that only looks for a title, a toast or "Sending..." is not a check.
+
+If something cannot be tested here, say so plainly instead of pretending.

package/template/spec.md

@@ -0,0 +1,80 @@
+# [What changes, in a few words]
+
+- Spec: `[NNN-name]`
+- Date: [YYYY-MM-DD]
+- Job, as the person said it: "[the one line]"
+
+## Problem
+
+[What is wrong today, in one or two sentences. The problem, not the solution.]
+
+## Who feels it
+
+[The person, and what they do instead today.]
+
+## Outcome
+
+[One result a machine can check: the booking exists, the message arrives, the file is in
+storage. Not "the screen says Saved".]
+
+## What must never break
+
+- [The thing someone would be called about.]
+
+## Who else sees it
+
+[A second account, an admin, a client. What they see after this change, and how fast.
+"Nobody else" is an answer.]
+
+## Scenarios
+
+1. **Given** [a known starting state], **when** [the person does this], **then** [what is
+   true afterwards, checked where it lands].
+
+## States
+
+Answer each one, or write "n/a" and why.
+
+| State | What the person sees and can do |
+|---|---|
+| Loading | |
+| Empty | |
+| Error | |
+| Offline or slow | |
+| No permission | |
+| Dark mode | |
+| Tapped twice | |
+| Back or cancel | |
+| Small screen | |
+| Screen reader | |
+| The other person | |
+| What each setting means | |
+
+Covered: [the states this spec answers]; n/a: [state (reason), ...]
+
+## Expected baseline
+
+What people expect from software of this kind. Mark each: in scope, hidden (not built and
+nothing suggests it), or out (and which spec takes it).
+
+| People expect | Here | Why |
+|---|---|---|
+| | | |
+
+## Acceptance checks
+
+Each one is something a machine can prove, from a known starting state.
+
+- [ ] AC1 [what is true] Proof: [the test or command that shows it, and where it looks]
+
+## Assumptions
+
+Assumed: [anything decided without the person; they will read these before approving]
+
+## Open questions
+
+[Only what the person must decide. At most five. "None" is fine.]
+
+## Out of scope
+
+- [What this change deliberately does not do.]

package/template/tasks.md

@@ -0,0 +1,19 @@
+# Tasks: [what changes]
+
+- Spec: `specs/[NNN-name]/spec.md` (approved)
+- Plan: `specs/[NNN-name]/plan.md`
+
+Each task is one small change a person can review. Tick a box only when its proof passes.
+The most uncertain task comes first, not last.
+
+- [ ] T001 [the change]
+  Files: `path/to/file`
+  Proves: [the check that shows the outcome, and where it looks]
+
+- [ ] T002 [the change]
+  Files: `path/to/file`
+  Proves: [the check]
+
+- [ ] TNNN The factory's checks pass
+  Proves: `factory verify --deep` reports no proven failure, and the independent review
+  approves. The factory records the evidence; the person commits after the review.