@moifort/stack 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Every version lists what changed and, when a rule change makes existing code non compliant,
+its migrations with their risk. The upgrade routine reads this first.
+
+## 0.1.0 (2026.10.21)
+
+First version, harvested from Shiori.
+
+- Rules `00` to `17`: collaboration, workflow, commits, review, push, release, changelog,
+  App Store, copy, backend, iOS, operations, CI, AI, infrastructure, tooling, routines,
+  landing page.
+- Routines: Sentry autofix, daily health, upgrades, deprecations.
+- Skills: domain, graphql, ios-feature, appstore, stack-install, stack-upgrade.
+- Templates: base, backend (Nitro, Firestore, GraphQL, Terraform, workflows), ios (SwiftUI
+  app generated by XcodeGen, workflows, fastlane).
+- CLI: `init`, `sync`, `check`, `migrations`, `placeholders`.
+- Migrations: none.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @moifort/stack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+How Polyforms apps are built, as one versioned package: the rules Claude follows on every
+project, the skills and routines it runs, and the templates a new app starts from. A Firebase
+backend in TypeScript, a SwiftUI app, Terraform, GitHub Actions, Sentry.
+
+## Start an app
+
+1. `mkdir <app> && cd <app> && git init`
+2. `bunx @moifort/stack init --stacks backend,ios`
+3. `bun install && bun run preflight`
+
+## Keep an app up to date
+
+Renovate opens a pull request when a new version is published. The upgrade routine syncs the
+rules into the project's `stack/` folder and applies the version's migrations, listed in
+[CHANGELOG.md](CHANGELOG.md).
+
+## What is inside
+
+| Folder | What |
+|---|---|
+| `rules/` | The rules, imported by each project's `CLAUDE.md` through `stack/rules/` |
+| `skills/` | The long forms, copied into `.claude/skills/` |
+| `routines/` | The scheduled Claude tasks |
+| `templates/` | What `init` writes into a new project, per stack |
+| `migrations/` | What to change in a project when a version changes a rule |

package/bin/stack.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env bun
+import { parseArgs } from 'node:util'
+import { readConfig, STACKS, type Stack } from '~/config'
+import { defaultPlaceholders, requiredPlaceholders, writeConfig } from '~/init'
+import { migrationsBetween, readMigrations } from '~/migrations'
+import { packageDir, packageVersion } from '~/package'
+import { applyPlan, applyTemplates, checkPlan, planSync } from '~/sync'
+
+const usage = `stack <command>
+
+  init --stacks backend,ios --set APP_NAME=Name --set MAIN_BRANCH=main   write stack.config.json, then sync
+  sync                                                                   render rules, routines, skills, hooks into the project
+  check                                                                  non-zero when the project differs from sync
+  migrations <from> <to> [--json]                                        the migrations between two versions, for the project's stacks
+  placeholders --stacks backend,ios                                      the placeholders those stacks need
+`
+
+const main = async (argv: string[]): Promise<number> => {
+  const [command, ...rest] = argv
+  const projectDir = process.cwd()
+  const pkg = packageDir()
+  const version = await packageVersion()
+
+  switch (command) {
+    case 'init': {
+      const { values } = parseArgs({
+        args: rest,
+        options: { stacks: { type: 'string' }, set: { type: 'string', multiple: true } },
+      })
+      const stacks = (values.stacks ?? '').split(',').filter(Boolean) as Stack[]
+      for (const s of stacks)
+        if (!STACKS.includes(s)) throw new Error(`unknown stack ${s}; known: ${STACKS.join(', ')}`)
+      const placeholders: Record<string, string> = defaultPlaceholders(projectDir)
+      for (const pair of values.set ?? []) {
+        const i = pair.indexOf('=')
+        if (i <= 0) throw new Error(`--set expects NAME=value, got ${pair}`)
+        placeholders[pair.slice(0, i)] = pair.slice(i + 1)
+      }
+      const required = await requiredPlaceholders(pkg, stacks)
+      const missing = required.filter((n) => placeholders[n] === undefined)
+      if (missing.length > 0) {
+        console.error(
+          `missing placeholders: ${missing.join(', ')}\n(pass each with --set NAME=value)`,
+        )
+        return 1
+      }
+      const used = Object.fromEntries(required.map((n) => [n, placeholders[n] as string]))
+      await writeConfig(projectDir, { stacks, placeholders: used, exclude: [] })
+      const config = await readConfig(projectDir)
+      const today = new Date().toISOString().slice(0, 10)
+      const { written, kept } = await applyTemplates(pkg, projectDir, config, {
+        ...config.placeholders,
+        STACK_VERSION: version,
+        TODAY: today,
+      })
+      const plan = await planSync(pkg, config, version)
+      await applyPlan(projectDir, plan)
+      console.log(
+        `initialised with stacks ${stacks.join(', ') || '(none)'}: ${written.length} files written, ${kept.length} kept, synced to ${version}`,
+      )
+      return 0
+    }
+    case 'sync': {
+      const plan = await planSync(pkg, await readConfig(projectDir), version)
+      await applyPlan(projectDir, plan)
+      console.log(`synced ${plan.files.size} files to ${version}`)
+      return 0
+    }
+    case 'check': {
+      const plan = await planSync(pkg, await readConfig(projectDir), version)
+      const problems = await checkPlan(projectDir, plan)
+      for (const p of problems) console.error(p)
+      if (problems.length === 0) console.log(`in sync with ${version}`)
+      return problems.length === 0 ? 0 : 1
+    }
+    case 'migrations': {
+      const { positionals, values } = parseArgs({
+        args: rest,
+        options: { json: { type: 'boolean' } },
+        allowPositionals: true,
+      })
+      const [from, to] = positionals
+      if (!from || !to) throw new Error('usage: migrations <from> <to>')
+      const config = await readConfig(projectDir)
+      const list = migrationsBetween(await readMigrations(pkg), from, to, config.stacks)
+      if (values.json)
+        console.log(
+          JSON.stringify(
+            list.map(({ body, ...m }) => m),
+            null,
+            2,
+          ),
+        )
+      else for (const m of list) console.log(`${m.version}  ${m.risk.padEnd(6)}  ${m.id}`)
+      return 0
+    }
+    case 'placeholders': {
+      const { values } = parseArgs({ args: rest, options: { stacks: { type: 'string' } } })
+      const stacks = (values.stacks ?? '').split(',').filter(Boolean) as Stack[]
+      for (const name of await requiredPlaceholders(pkg, stacks)) console.log(name)
+      return 0
+    }
+    default:
+      console.log(usage)
+      return command === undefined || command === 'help' ? 0 : 1
+  }
+}
+
+process.exit(await main(process.argv.slice(2)))

package/hooks/shutdown-simulators-after-push.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Hook PostToolUse (Bash) : après un `git push` réussi, éteint tous les
+# simulateurs et quitte Simulator.app, qui sinon restent ouverts et occupent
+# 50 à 70 % du processeur.
+
+command=$(/usr/bin/python3 -c 'import json, sys; print(json.load(sys.stdin).get("tool_input", {}).get("command", ""))' 2>/dev/null)
+
+printf '%s' "$command" | grep -Eq '(^|[;&|[:space:]])git([[:space:]]+-C[[:space:]]+[^[:space:]]+)?[[:space:]]+push([[:space:]]|$)' || exit 0
+
+booted=$(xcrun simctl list devices booted 2>/dev/null | grep -c '(Booted)')
+simulator_app=$(pgrep -x Simulator)
+[ "$booted" -eq 0 ] && [ -z "$simulator_app" ] && exit 0
+
+xcrun simctl shutdown all >/dev/null 2>&1
+[ -n "$simulator_app" ] && osascript -e 'quit app "Simulator"' >/dev/null 2>&1
+
+cat <<EOF
+{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": "Push terminé : $booted simulateur(s) éteint(s) et Simulator.app fermé automatiquement (hook shutdown-simulators-after-push)."}}
+EOF

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@moifort/stack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The Polyforms stack: rules, skills, hooks, routines and templates for a Firebase + iOS app, versioned and upgraded through Renovate.",
+  "license": "MIT",
+  "repository": "github:moifort/polyforms-stack",
+  "type": "module",
+  "bin": {
+    "stack": "bin/stack.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "rules",
+    "skills",
+    "hooks",
+    "routines",
+    "templates",
+    "migrations",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:unit": "bun test .unit.test",
+    "test:int": "bun test .int.test",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "bunx biome check",
+    "lint:fix": "bunx biome check --write",
+    "validate": "bun src/validate-content.ts",
+    "preflight": "bun run typecheck && bun run lint && bun run test:unit && bun run test:int && bun run validate"
+  },
+  "dependencies": {
+    "semver": "7.7.2",
+    "zod": "4.1.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@types/bun": "1.4.3",
+    "@types/semver": "7.7.1",
+    "typescript": "5.9.3"
+  }
+}

package/routines/daily-health.md

@@ -0,0 +1,78 @@
+---
+id: daily-health
+scope: project
+runtime: cloud
+cadence: "0 12 * * *"
+title: "{{APP_NAME}} health (daily at noon)"
+---
+
+Daily production health pass for {{APP_NAME}} (repository `{{CODE_DIR}}/{{REPO_NAME}}`, GCP project
+`{{APP_SLUG}}-polyforms`, region `europe-west3`, backend Cloud Function gen 2 `{{APP_SLUG}}-server`,
+request logs under `resource.type="cloud_run_revision"`). Analyse the last 24 hours of costs,
+performance and monitoring, fix what is broken in code, push to main, watch CI. Report in the
+person's language.
+
+Error logs are out of scope: every `warn` and `error` goes to Sentry and to the `sentry-autofix`
+routine.
+
+Read the project's `CLAUDE.md` and the stack rules first and follow them. Work inline, never a
+subagent. Other sessions may be editing the checkout: work in a worktree, or commit only your
+files with an explicit pathspec; never stash, reset, switch branches, amend or force-push.
+
+## 0. Preconditions
+- Every `gcloud` / `bq` command is prefixed with `CLOUDSDK_CONFIG=$HOME/.config/claude-observer/gcloud`,
+  the read-only observer account's own configuration. Check it with `gcloud auth
+  print-access-token`. If it fails, never fall back to the person's login and never run `gcloud
+  auth login`: do the steps that need no GCP and put the failure at the top of the report.
+- The observer account only reads. Never write to GCP with it.
+- `git pull --ff-only` if the tree allows it; otherwise work on what is there and say so.
+
+## 1. Costs
+- Billing export: `bq query --project_id={{APP_SLUG}}-polyforms --use_legacy_sql=false` on
+  `{{BILLING_TABLE}}`, filtered on `project.id = "{{APP_SLUG}}-polyforms"`, cost plus credits per day
+  (`Europe/Paris`) and per service and SKU for the last 8 days. The export lags hours: yesterday
+  may be partial, say so.
+- Flag any service above twice its 7-day daily average, any AI API above `{{AI_DAILY_ALERT}}` a
+  day, any new SKU. For Gemini, the grounded-search SKU is the expensive one; trace a spike through
+  the structured usage logs grouped by step and hour; `httpRequest.userAgent` and `remoteIp` on the
+  API route say whether one device caused it.
+- A prepaid AI account answering 402 is critical: report it first, only the person can top up.
+- Never read or print a key or a secret.
+
+## 2. Performance
+- From the API request logs of the last 24 h: p50, p95, p99 latency, 5xx rate, slowest hours.
+  Cloud Monitoring: request latencies, instance count, startup latencies, memory. Compare with
+  the previous day. Flag p95 above 2 s not explained by cold starts, a regression above 50 %,
+  memory near the limit. Cold starts are a figure, never an action item: scaling to zero is the
+  rule.
+- Firestore usage when a cost or latency spike points there. Production data may be read to
+  explain a spike; never copy personal data into the report.
+
+## 3. Monitoring
+- CI: `gh run list --repo moifort/{{REPO_NAME}} --limit 30 --json databaseId,name,headSha,status,conclusion,createdAt`:
+  any failed run on main in 24 h, Deploy first, including its migrations step.
+- Cloud Scheduler: `gcloud scheduler jobs list --project={{APP_SLUG}}-polyforms --location=europe-west3`,
+  state and last attempt of each job; a paused or failed job is a finding.
+- The app configuration endpoint on the production host answers 200.
+- App Store and TestFlight are out of scope.
+
+## 4. Fix
+For each real problem with a clear cause in code: fix it following the rules, verify (typecheck,
+the three test families separately, linter, schema check if the schema changed, an app build for
+app changes), commit without asking (conventional commits, English, explicit pathspec,
+`Co-Authored-By` trailer), push directly to main (authorised for this routine), watch every CI
+run for the commit until green, fix forward on failure. Never touch the changelogs, never deploy or
+terraform from the machine, never run migrations by hand.
+
+Only propose, never apply: anything that changes what users see or can do, any infrastructure,
+Terraform or secret change, anything with an unclear cause, and anything that would raise paid API
+calls (state its cost).
+
+## 4b. The other routines
+List the last run of every other routine of this account (Sentry triage, upgrades,
+deprecations). One that missed two cadences is a finding at the top of the report.
+
+## 5. Report (short)
+One-line verdict first (all fine / fixed / action needed from you). Then Costs (yesterday's total
+and per service versus the 7-day average), Performance (p50, p95, 5xx, instances), Monitoring
+(CI, Deploy, scheduler). Then "Fixed" (hashes, CI result per workflow) and "To decide".

package/routines/deprecations.md

@@ -0,0 +1,23 @@
+---
+id: deprecations
+scope: project
+runtime: cloud
+cadence: "0 9 1 * *"
+title: "{{APP_NAME}} deprecations (monthly)"
+---
+
+Remove from {{APP_NAME}}'s API what no build on sale still asks for (repository `{{CODE_DIR}}/{{REPO_NAME}}`).
+Follow the project's `CLAUDE.md` and the stack rules on API evolution. Report in the person's
+language.
+
+1. In a worktree of `origin/main`, run `bun run deprecations` with the store API key from
+   the environment (never printed).
+2. For every element reported **removable**: remove it from the schema, the resolver, and the
+   code and tests only it used. Leave anything in grace, waiting, still asked, or to check by
+   hand; list those in the report.
+3. Set the minimum supported build to the floor the script proposes. Never a higher value.
+4. Verify as the rules prescribe (typecheck, the three test families separately, linter, schema
+   check), commit `refactor(api): remove deprecated fields no build on sale asks for`, push to
+   main (authorised for this routine), watch CI and Deploy to the end, fix forward on failure.
+5. Report: what was removed, the new floor, what stays in grace and until when, anything to
+   check by hand.

package/routines/sentry-autofix.md

@@ -0,0 +1,76 @@
+---
+id: sentry-autofix
+scope: machine
+runtime: cloud
+cadence: "0 */6 * * *"
+title: Sentry autofix (every 6 hours)
+---
+
+Fix the unresolved Sentry errors of every project of the organisation, push each fix to main, check
+CI, and write a report in the person's language. This routine runs every six hours.
+
+## Standing authorisation
+The person authorised this routine to commit AND push its fixes directly to `main` without asking.
+Every other rule of each project's `CLAUDE.md` and of the stack rules still applies: language,
+commit style, changelog never touched, verification before commit, deprecate rather than remove an
+API field, deploy only through CI, never terraform or migrate from the machine.
+
+## Overlap guard (first)
+A run starts on a fresh machine, so there is no lock file: before touching an issue, check that no
+open pull request and no commit of the last 14 days on `main` carries `Fixes <SHORT-ID>`; if one
+does, the issue is being handled, skip it.
+
+## Sentry access
+- Org `polyforms`, API `https://sentry.io/api/0/`.
+- In the cloud, the token is a **network secret** of the cloud environment for the host
+  `sentry.io`: the proxy adds the `Authorization` header to every request to that host, so call
+  the API with `curl` **without** an authorization header and never look for a token in a file or
+  a variable. On a desktop run, the token is `SENTRY_AUTH_TOKEN` in the project's `.env`. Never
+  print it, never write it into a file or a commit.
+- Logger extras appear under `.context` in the event JSON.
+
+## Projects
+The task's repositories are cloned at the start of the run: work in them. A Sentry project
+`<name>-<platform>` maps to the repository `moifort/<name>`; a Sentry project whose
+repository is not among the task's repositories is listed as unmapped in the report and skipped.
+Add it to the task to cover it.
+
+## Steps
+1. Per project: `GET /projects/polyforms/{slug}/issues/?query=is:unresolved&statsPeriod=14d&sort=freq`.
+   Keep issues with events in the last 7 days. Skip external or transient causes (timeouts,
+   third-party 5xx, user cancellations) unless the code handles them wrongly.
+2. Skip issues already fixed: after `git fetch origin`,
+   `git log origin/main --since="14 days ago" --grep="Fixes <SHORT-ID>"`; if found, retry the
+   resolve step only. A regression (`isRegression`) means the fix was wrong: investigate again.
+3. Fetch the latest event (stack, message, `.context`, tags, release). Find the root cause in the
+   code. Without a confident root cause, do not guess: report "to investigate" with findings.
+4. In the repository's clone (already on `main`), install dependencies, follow that project's
+   `CLAUDE.md` and the stack rules.
+5. Fix with a regression test where the code is testable (test first). One commit per issue or
+   shared root cause, minimal.
+6. Verify as the rules prescribe (typecheck, the three test families separately, linter, schema
+   check if the schema changed, an app build for app changes). Never commit a failing fix.
+7. Commit: conventional commit, English, body with the root cause, trailer `Fixes <SHORT-ID>`,
+   then the `Co-Authored-By` trailer. Never touch the changelogs.
+8. Push **to `main`**, not to a `claude/` branch: `git fetch origin && git rebase origin/main`,
+   then `git push origin HEAD:main`. A conflicting rebase is aborted and reported, never forced.
+   An **app (iOS) fix cannot be built here** (no Xcode): push it as a branch `claude/sentry-<id>`,
+   open a pull request with `gh pr create`, and let CI build it; the next pass merges it when CI
+   is green.
+9. Watch CI for the pushed commit (`gh run list --json databaseId,headSha,name,status,conclusion`
+   filtered on `headSha`, then `gh run watch <id> --exit-status`). On failure, fix forward if the
+   cause is clear, otherwise revert, push the revert, report.
+10. Once CI is green, Deploy included: `PUT /organizations/polyforms/issues/{id}/` with
+    `{"status":"resolvedInNextRelease"}`, never plain `resolved`.
+11. Merge the pull requests opened by earlier passes whose CI is green (`gh pr list --author @me
+    --label sentry`), then resolve their issues as in step 10.
+
+## Limits
+- At most 3 fixes per pass, prioritised by event count times users affected.
+- Never change infrastructure, secrets, CI workflows or migrations to silence an error; never
+  lower a log level to hide a bug; never delete data; never ignore an issue.
+
+## Report (short, scannable)
+Nothing found and nothing fixed: one line, plus any access problem. Otherwise per project: issues
+examined, fixed (short id, root cause in one sentence, SHA, CI status, resolved or not), skipped
+(reason), to investigate (leads). Access problems at the end.

package/routines/stack-upgrade.md

@@ -0,0 +1,45 @@
+---
+id: stack-upgrade
+scope: machine
+runtime: cloud
+cadence: "0 7 * * *"
+title: Upgrades (daily, after Renovate)
+---
+
+Apply the stack package upgrades and the major dependency upgrades Renovate opened overnight, on
+every project of the organisation. Report in the person's language.
+
+## Discovery
+For every repository under `{{CODE_DIR}}` whose `origin` points at `moifort/*`:
+`gh pr list --repo <owner>/<name> --label stack --state open --json number,title,headRefName`.
+A pull request bumping `@moifort/stack` follows "Stack pull request"; a pull request labelled
+`major` follows "Major dependency"; anything else is reported, not touched.
+
+## Stack pull request
+1. Check out the pull request's branch in a worktree (`/tmp/stack-upgrade-<name>-<date>`),
+   install dependencies, and follow the `stack-upgrade` skill shipped by the package in
+   `.claude/skills/`: sync, migrations one by one with their checks, preflight, a comment on the
+   pull request with one line per migration, merge only when every migration is `safe`, applied or
+   not applicable, every check passes and CI is green. Otherwise label `stack:review` and leave it
+   open.
+2. Remove the worktree.
+
+## Major dependency
+1. Check out the branch in a worktree, install. Read the dependency's release notes and migration
+   guide for every major between the old and the new version (`gh api` on the repository's
+   releases, or the package's CHANGELOG).
+2. Apply the code changes the new major requires, in one commit per dependency, verified as the
+   rules prescribe. Respect the project's `allowedVersions` bounds: a pull request Renovate
+   should not have opened is closed with the reason.
+3. Add the `staging` label so the Deploy workflow deploys the branch to staging; wait for it.
+4. Merge when CI and the staging deploy are green. Otherwise comment with what blocks (the
+   failing job, the breaking change, the bound to add) and leave it open.
+
+## Limits
+- Never edit the package's rules from a consumer project; a rule that is wrong is reported.
+- Never force-merge, never force-push, never touch a pull request without the `stack` label.
+- At most one pull request per project per pass.
+
+## Report
+Per project: pull request, version from and to, migrations applied, not applicable, needing
+review, merged or left open with the reason.

package/rules/00-collaboration.md

@@ -0,0 +1,81 @@
+# Collaboration
+
+How Claude behaves on every project, whatever the stack.
+
+## Short answers
+
+Lead with the result and what blocks. No "what I built" section, no closing recap, no restating
+the context: the person follows the work as it happens and knows their repository. Details come
+when asked.
+
+## Critical review before execution
+
+Every proposed design or architecture choice gets a review as a senior infrastructure engineer
+with a whole-system view: name the failure modes, say plainly when it is wrong or not worth
+building, lead with the verdict. Before agreeing, check:
+
+- what fails if an event is lost, a call times out, a process restarts;
+- what the change delivers to the person using the product;
+- whether it is new infrastructure for a single consumer;
+- whether a cheaper design does the job (an idempotent write, a lazy reconciliation).
+
+Never side with the person because they pushed back. Change position only on a better argument,
+and say which argument changed it. Once the decision is taken, execute it fully and do not
+relitigate it at the next task.
+
+## Questions sized to the task
+
+A simple request (a typo, a label, a one-line fix) is done at once, without a question and
+without turning it into architecture. A request that involves decisions (several readings, a
+trade-off, something that is hard to undo) gets the questions first, before any code. Ask when it
+is needed, never as a reflex.
+
+## Autonomy
+
+Never stop to ask permission to continue. Stop for a real blocker or a question that changes a
+lot, not for a checkpoint. A plan runs to its final result in one go; validation screenshots are
+gathered and shown at the end, not used as a pause. Never ask permission to commit: see
+[02-commits.md](02-commits.md).
+
+## Run commands yourself, go to the end
+
+A list of manual steps for the person to run is a failure, not a deliverable. Run every command
+line yourself: checks, builds, fixes, verifications; drive the browser when the task is in a
+browser; go to the end of the task. Only a command that needs the person's password, `sudo`, an
+Apple sign-in or a physical action (plugging the phone) is theirs, and then say so plainly. When
+about to end a message with "run this", run it instead and report.
+
+Two things wait for a go, asked in one message that says what will be done and why: reading
+production data, and anything that changes production (a deploy, a console setting, a store
+submission). See [15-tooling.md](15-tooling.md#browser-and-doing-things-end-to-end).
+
+## No agent, no plan mode, no spec by default
+
+Exploration, review, debugging and planning happen inline, in the main conversation. By default:
+no subagent, no parallel agent, no plan mode, no design document. Each of these happens only when
+the person asks for it explicitly, for that task. A skill that requires dispatching an agent or
+writing a document is applied inline, without them. This rule wins over any external procedure
+that says otherwise.
+
+## Where feedback goes
+
+A correction given in conversation is written down in the same task, not remembered privately:
+
+| What it is | Where it goes |
+|---|---|
+| A rule that would hold in any project | This package: the rule file, a version bump, a migration if code is affected |
+| A fact of this project (an id, an account, a device, a certificate date) | The project's `project-context.md` |
+| A decision specific to this project's product or data model | The project's `CLAUDE.md` |
+
+Claude's private memory keeps neither rules nor project facts. What is not written in a repository
+does not exist at the next session.
+
+## Languages
+
+| What is produced | Language |
+|---|---|
+| Code, comments, commit messages, technical documentation, specs, this package | English |
+| Copy seen by the person using the product | `{{SOURCE_LANGUAGE}}`, then `{{SERVED_LANGUAGES}}` |
+| Conversation | The person's language |
+
+Never two languages in one commit message or one comment.

package/rules/01-workflow.md

@@ -0,0 +1,81 @@
+# Workflow of a task
+
+## The cycle
+
+1. **Framing.** Understand the intent before coding. If two readings of the request lead to two
+   different pieces of work, ask now, not at the end.
+2. **No spec, no plan mode by default.** A design document
+   (`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`) or a written plan is produced only when
+   the person asks for one. Without that, the plain explanation below is given in the conversation
+   and the work starts. A paid API call states its cost either way, see [13-ai.md](13-ai.md).
+3. **Implementation**, inline, to the final result, without checkpoints.
+4. **Verification**, below.
+5. **Review** before commit, see [03-code-review.md](03-code-review.md).
+6. **Commit**, see [02-commits.md](02-commits.md).
+7. **Screenshot** when a screen changed, below.
+
+## What an explanation or a plan contains
+
+Before the work, in the conversation (or in the plan when one was asked), a plain section:
+
+- the domains touched: created, modified, removed;
+- how it works today, what it gives afterwards, ideally a table of before and after;
+- the mechanisms at play, without jargon;
+- what does not move;
+- why the tasks are in this order.
+
+Code blocks serve execution, the explanation serves the decision. Each task ends with a testable
+deliverable and its verification command with the expected output.
+
+## Verification before a commit
+
+A claim of success without the command output behind it has no value. Before every commit:
+
+| What was touched | What runs |
+|---|---|
+| Backend | `bun run typecheck` (after `bun run prepare` if routes changed), the three test families **separately** (see below), `bun run lint` |
+| The API schema | `bun run schema:check`: a removal not preceded by a deprecation is refused, see [11-ops.md](11-ops.md#api-evolution) |
+| The app | `bun run ios:build`; and after any on-screen text change, `bun run ios:strings` until it reports every string translated, see [08-copy.md](08-copy.md#localisation) |
+
+The three test families run **separately** (`bun run test:unit`, `bun run test:int`,
+`bun run test:feat`): a module mock declared in one test file serves every file of the same
+run, so a single combined run passes while CI, which runs them apart, goes red.
+
+## Mockups before a complex screen
+
+A new feature with screens and real complexity (a new flow, several states, a layout nobody has
+seen) starts with mockups, before any real code: quick throwaway renderings of the screens built
+from fixtures (a preview or a harness screenshot, or a drawn mock when that is faster), sent for a
+fast approval of the layout and the flow. Only once the mockups are approved does the real
+implementation start. A small change to an existing screen skips this and goes straight to the
+screenshot below.
+
+## Screenshot after every UI change
+
+Every request that changes a screen ends with a screenshot of the result, sent to the person,
+followed by a wait for their approval. Without exception, and whatever the state of the simulator:
+
+- "the simulator stops at sign-in" is never a reason to skip it. Feed the page its preview
+  fixtures through a temporary launch argument in the app entry point, build into a derived data
+  path unique to the session, install and launch, capture, then revert the harness before the
+  commit. The fixtures and previews stay.
+- Before sending, check the design conventions of [10-ios.md](10-ios.md#design-conventions).
+- Committing before approval is fine. Installing on the person's device before approval is not.
+- The next task does not start until the screenshot is approved.
+
+## Ideas and decisions
+
+- **Ideas** that come up and are not built now go into the project's `docs/ideas.md`, one line
+  each with the date, so nothing said in passing is lost. Claude adds to it without being asked.
+- **Architecture choices** get an ADR (architecture decision record) in `docs/adr/`, numbered
+  (`0007-flat-collections.md`): context, decision, alternatives rejected, consequences. Written
+  when the choice is made, proposed to the person before the code that depends on it.
+
+(Shape to refine later; the rule is that both exist in every project.)
+
+## Skills and tooling
+
+Before starting, look at what is installed and invoke what matches the task. Never cite, impose
+or document a skill without checking it exists on the machine. The skills this package ships are
+in `.claude/skills/` after `sync`; the ones that matter are `domain`, `graphql`, `ios-feature`,
+`appstore`, `stack-upgrade`.