Build farish — AI 3D model generator (web app, API, specs, CI)

.biome/README.md

@@ -0,0 +1,25 @@
+# `.biome/`
+
+Custom lint rules for the farish codebase, written as
+[Biome GritQL plugins][grit].
+
+Biome ships 200+ built-in rules; `biome.json` turns the strict ones on. This
+directory holds **farish-specific** rules — patterns we want banned that no
+built-in rule covers.
+
+## Plugins
+
+| Plugin                      | Bans                                                    |
+| --------------------------- | ------------------------------------------------------- |
+| `plugins/no-as-any.grit`    | `x as any` casts — they silently disable type-checking. |
+
+## Adding a rule
+
+1. Write a `.grit` file under `plugins/`.
+2. Register it in the `plugins` array of `biome.json`.
+3. Run `mise run lint` to confirm it loads and fires.
+
+See [`docs/monorepo/lint-format.md`](../docs/monorepo/lint-format.md) for the
+full lint/format guide and the rationale for choosing Biome.
+
+[grit]: https://biomejs.dev/linter/plugins/

.biome/plugins/no-as-any.grit

@@ -0,0 +1,18 @@
+// no-as-any.grit — custom Biome lint rule (GritQL plugin).
+//
+// Bans the `x as any` escape hatch anywhere in the farish codebase. `as any`
+// silently disables type-checking for an expression and is the single most
+// common way strictness is defeated. The built-in `noExplicitAny` rule catches
+// bare `any` annotations; this plugin closes the cast-shaped hole it leaves.
+//
+// Pattern we do NOT want:   const v = something as any;
+// Do this instead:         narrow with a type guard, or cast to `unknown`
+//                          first and then to a precise type.
+//
+// Docs: docs/monorepo/lint-format.md
+`$expr as any` where {
+  register_diagnostic(
+    span = $expr,
+    message = "farish/no-as-any: `as any` defeats type-checking — narrow the type or cast through `unknown` to a precise type instead."
+  )
+}

.claude/hooks/session-start.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# SessionStart hook for Claude Code on the web.
+#
+# Onboards the `farish` repo: installs the pinned toolchain and workspace
+# dependencies so linters, tests and builds work inside a web session.
+#
+# It is intentionally idempotent and forward-looking: the repo starts with no
+# code, so each install step is guarded by the presence of its manifest. As the
+# monorepo is scaffolded (mise.toml, package.json, ...) the matching steps begin
+# to run automatically with no edit to this hook required.
+set -euo pipefail
+
+cd "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}"
+
+echo "[session-start] onboarding farish in ${PWD}"
+
+# Toolchain install (mise) is handled by the mise plugin's own SessionStart
+# hook — intentionally NOT duplicated here.
+
+# bun — install workspace dependencies once a manifest exists. bun is provided
+# by mise (pinned in mise.toml), so route through `mise exec` so bun resolves
+# even before mise's shims reach PATH on a first run — rather than assuming bun
+# is already on PATH. Project-specific; a future bun-utils plugin could own it.
+if [ -f package.json ]; then
+  if command -v mise >/dev/null 2>&1; then
+    echo "[session-start] bun install (via mise exec)"
+    mise exec -- bun install || echo "[session-start] bun install failed (continuing)"
+  elif command -v bun >/dev/null 2>&1; then
+    echo "[session-start] bun install"
+    bun install || echo "[session-start] bun install failed (continuing)"
+  else
+    echo "[session-start] package.json present but neither mise nor bun on PATH — skipping"
+  fi
+fi
+
+# Keep local-checkout plugin marketplaces fresh. farish's `agents-local` and
+# `ai-mktpl-local` marketplaces are `directory` sources pointing at local git
+# checkouts; a directory marketplace serves whatever is in the checkout's
+# working tree, so each checkout must be pulled forward to stay current with
+# its branch. Best-effort — failures never abort onboarding.
+for repo in /home/user/agents /home/user/ai-mktpl; do
+  if [ -d "$repo/.git" ]; then
+    echo "[session-start] refreshing local marketplace checkout: $repo"
+    git -C "$repo" fetch --quiet origin || echo "[session-start] fetch failed for $repo (continuing)"
+    git -C "$repo" pull --ff-only --quiet || echo "[session-start] pull skipped/failed for $repo (continuing)"
+  fi
+done
+
+echo "[session-start] done"
+exit 0

.claude/plugins.settings.yaml

@@ -0,0 +1,22 @@
+# Plugin settings for the farish project.
+# Schema: each top-level key is a plugin name; see that plugin's skill docs.
+
+1pass:
+  enabled: true
+  # Download the 1Password CLI (`op`) when not on PATH. The session provides
+  # OP_SERVICE_ACCOUNT_TOKEN (vault: AI-Jack), so `op` auto-authenticates.
+  autoInstall: true
+  # Inject the GitHub App credentials from 1Password so the github-app plugin
+  # can mint an installation token on SessionStart. Item: github--app--jack.
+  secrets:
+    - envVar: GITHUB_APP_ID
+      reference: "op://AI-Jack/github--app--jack/GITHUB_APP_ID"
+    - envVar: GITHUB_INSTALLATION_ID
+      reference: "op://AI-Jack/github--app--jack/GITHUB_INSTALLATION_ID"
+    - envVar: GITHUB_APP_PRIVATE_KEY
+      reference: "op://AI-Jack/github--app--jack/GITHUB_APP_PRIVATE_KEY"
+
+github-app:
+  enabled: true
+  # Configure git identity to the GitHub App bot user automatically.
+  autoGitConfig: true

.claude/rules/always-keep-improving.md

@@ -0,0 +1,122 @@
+# Always keep improving
+
+1. The initial prompt that started this all can be found at
+   [docs/INITIAL_PROMPT.md](../../docs/INITIAL_PROMPT.md) and should be reviewed
+   to ensure progress is being made accurately.
+
+You can do literally anything. The skills you will make and have made make what
+you do possible. To do something new, all you need to do is make a skill. Always
+check your skills before during and after Tasks to see if there's any helpful
+skills. Use `Agent(run_in_background:true)` carefully to parallelize tasks where
+you can. These skills are only as good as their instructions.
+
+CRITICAL: Changes to your configuration/rules/code/skills/hooks/agents must be
+committed IMMEDIATELY after making them.
+
+CRITICAL: Commits for this project MUST be atomic (only change one thing) using
+the conventional commit style. Push often. Use CI to your advantage, but local
+is always faster.
+
+CRITICAL: NEVER execute `Bash(do && a && bunch || of ; things)` or
+`Bash(python -c "a big python script")`. If the Bash tool call is doing more
+than 1 or 2 things, it needs to be turned into a script (build a logical
+hierarchy with proper CLAUDE.md documentation throughout in
+`.claude/scripts/paths/to/categorize/meaningful-name.sh`. ALWAYS check to see if
+a script exists before creating a new one. ALWAYS know which scripts you'll need
+before executing a plan. ALWAYS make sure the scripts are tested. ALWAYS share
+code between scripts when possible. ALWAYS prefer bun/ts/compiled tool (but
+scripts are okay). ALWAYS use monorepo tooling, even in the scripts, they're
+code too!
+
+CRITICAL: Try to prefer behavior modifications in the following priority order:
+  1. Hooks in claude configs (remember don't keep any in settings.local.json
+     they're not saved!)
+  2. `Skill(context:fork)`
+  3. `Agent()` - don't forget they're resumable! Work iteratively with them,
+     don't make them do everything in one go, guide them not to, they don't
+     share the conversation context, ANY outputs should go to file that you can
+     review. ALWAYS run them in the background AND check their work.
+    - even better if they have their own hooks, which can help contain
+      specialized behavior
+  4. Hookify hooks - these help fine tune behaviors and keep things consistent.
+     Anytime there's a regression in behavior, consider using these or a skill!
+  5. Skills still, with scripts to encapsulate behavior
+  6. Scripts
+  7. Rules. These take up context and aren't really actually enforceable.
+Use hooks to ensure something actually happens, skills on how to use tools,
+Agents to encapsulate a recurring behavior where only the ins/outs are needed.
+
+CRITICAL: NEVER use the general-purpose agent. ALWAYS see if you have an agent or
+skill specialized in that task, and if not, make one or add it to an existing
+one.
+
+CRITICAL: KEEP SKILLS SMALL. Keep examples in supplementary documentation that
+are mentioned (not @mentioned). Make most skills an ordered list of
+instructions. Delegate shared knowledge to shared skills (eg don't describe how
+to use git in making-a-pr, make a tool-cli-git skill that describes how to do
+it). Disambiguate skills to make it easy to find the right skill without reading
+one skill that does everything. If the skill is more than 5 paragraphs, it
+probably needs to be broken up (including ones that were already too big before
+you touched it). Always break things into maintainable and shareable chunks.
+
+CRITICAL: Set up a cron for every 15 minutes to do a full review of your
+configuration using "audit-verify-improve-agent" (create if it doesn't exist).
+When you eventually go idle, set up a stop hook to do one final audit, make any
+final adjustments, and push any remaining changes. This skill MUST be
+context:fork, and review conversation transcripts to get the full picture,
+iteratively, don't rely on memory. Use a haiku agent to scan logs since the last
+time it ran (store in file somewhere using skill
+`` !`date | tee .claude/state/self-improvement-last-ran` `` syntax within the
+skill to write it everytime the skill is called) for instances where trouble
+occurred, and note it by appropriate IDs for beginning and end of the issue. use
+a script to extract the conversation transcript between those IDs, then another
+script to convert it from JSONL to a more readable, chat-style output (like one
+that you'd get from claude-stream from nsheaps/claude-utils).
+
+CRITICAL: Be verbose in the data you give an Agent, explicit about the actions
+you want it to take and not to take, requirements (including what you want for
+the outputs and details about what you want them to contain), validation steps,
+restrictions, other-notes. It will make stuff up if you don't tell it how to do
+it's thing, including using skills. Use resuming to your advantage. Make sure it
+understands the task (it needs to Stop to confirm with you) before it does the
+task if the task is complex. Check it's outputs, don't always assume they're
+right.
+
+CRITICAL: You AND all Agents (subagents, et al) are EXPECTED to use
+github-footnote-style references in ALL documents, issues, PRs, markdown docs,
+etc to link to sources that support your claim. Claims made without sources or
+significant data to back it up will be rejected. Use the repo's
+`.claude/sources/xxx/yyy/zzz.abc` to store sources that can't directly be linked
+to (eg scrubbed+humanified transcripts) and link to those. Always reference
+files inside the repo using `github.com/…` links, NEVER filesystem paths. Review
+your claims before making them, if you feel anywhere _might_ deserve a
+`[citation needed]`, then you MUST add a citation, or update the claim BEFORE
+you send it.
+
+CRITICAL: Always consult with claude-code-guide running as sonnet or opus to
+help with updating/changing agent configs. Encourage it to always be thorough in
+it's research. Don't believe github issues about claude-code unless they have
+significant community support or confirmation from anthropic.
+
+CRITICAL: If you ever achieve undesired, unplanned, failed, or errored results
+when executing tools, skills, following rules, being guided by hooks, executing
+agents, you MUST update the appropriate configuration/code/document/skill.
+
+CRITICAL: After completing every task, THINK HARD about what you did during the
+task (use an Agent to review the transcript if necessary) and which skills you
+executed during the task. Update configs/rules/code/skills/agents as necessary
+to improve them for the next time.
+
+CRITICAL: ALWAYS USE SKILLS AND AGENTS, EVEN IF YOU THINK YOU KNOW HOW TO DO
+SOMETHING.
+
+CRITICAL: ALWAYS use `/scm-utils:commit` to commit code.
+
+CRITICAL: images use up insane amounts of context. ONLY use them within an
+`Agent()`. Be explicit about what you want to know about the image.
+
+EXTRA SUPER CRITICAL: As soon as you can, run the audit-verify-improve-agent when
+you see this, which should start with improving the rules, including this file
+if you deem fit. Make sure you're only keeping things in rules that need to be
+visible all the time, and REALLY encouraging the use of Hooks, Skills, and
+Agents.

.claude/settings.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "defaultMode": "bypassPermissions"
+  },
+  "env": {
+    "TASK_UTILS_TASK_DIR": "/home/user/farish/.claude/tasks",
+    "CLAUDE_CODE_ENABLE_TASKS": "1",
+    "CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH": "1",
+    "CLAUDE_AUTO_BACKGROUND_TASKS": "1",
+    "CLAUDE_CODE_DISABLE_CRON": "0",
+    "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS": "0",
+    "CLAUDE_CODE_EXIT_AFTER_STOP_DELAY": "60000",
+    "FORCE_AUTOUPDATE_PLUGINS": "1"
+  },
+  "extraKnownMarketplaces": {
+    "agents": {
+      "source": {
+        "source": "github",
+        "repo": "nsheaps/agents"
+      }
+    },
+    "ai-mktpl": {
+      "source": {
+        "source": "github",
+        "repo": "nsheaps/ai-mktpl"
+      }
+    },
+    "agents-local": {
+      "source": {
+        "source": "directory",
+        "path": "/home/user/agents"
+      }
+    },
+    "ai-mktpl-local": {
+      "source": {
+        "source": "directory",
+        "path": "/home/user/ai-mktpl"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "cron-utils@agents-local": true,
+    "task-utils@agents-local": true,
+    "shared-lib@ai-mktpl-local": true,
+    "dangerous-bypass@ai-mktpl-local": true,
+    "agentic-behavior@ai-mktpl-local": true,
+    "common-sense@ai-mktpl-local": true,
+    "deep-research@ai-mktpl-local": true,
+    "edit-utils@ai-mktpl-local": true,
+    "github@ai-mktpl-local": true,
+    "github-app@ai-mktpl-local": true,
+    "1pass@ai-mktpl-local": true,
+    "mise@ai-mktpl-local": true,
+    "scm-utils@ai-mktpl-local": true,
+    "sequential-thinking@ai-mktpl-local": true,
+    "hookify@claude-plugins-official": true,
+    "plugin-dev@claude-plugins-official": true
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/build-confidence-by-trying-to-prove-incorrect/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: build-confidence-by-trying-to-prove-incorrect
+description: Resolve a decision, claim, or plan you are not fully confident in by dispatching an adversarial Agent whose job is to disprove it. Use before committing to a non-trivial or hard-to-reverse next step while ambiguity or low confidence remains. Trigger phrases — "I have a feeling but want to be sure", "is this the right next step?", "prove this wrong before I act", "I keep wanting to second-guess this".
+context: fork
+---
+
+# Build confidence by trying to prove it incorrect
+
+When you have a hypothesis, plan, or next step you are not fully confident in,
+do not guess and do not proceed. Dispatch an adversarial `Agent()` whose
+explicit job is to **disprove** it. Proceed only once the claim survives a
+genuine attack.
+
+## Steps
+
+1. Write the claim/plan as a single falsifiable statement, plus the concrete
+   next step it would justify and why the step is hard to reverse.
+2. Dispatch `Agent(run_in_background: true)` with an adversarial brief: its job
+   is to prove the claim wrong, unsafe, or that a better option exists — NOT to
+   agree. Instruct it to verify empirically wherever possible, cite official or
+   primary sources, and to state explicitly if it cannot disprove the claim.
+3. Require the agent to write its findings to a file and return a short
+   verdict: which claims survived, which were disproven, and the corrected
+   next step.
+4. If a claim is disproven, adopt the correction. If confidence is still not
+   sufficient, repeat from step 1 on the corrected claim.
+5. If the claim survives a genuine attack, confidence is sufficient — proceed.
+
+## Stop condition
+
+You are done debating when you no longer feel you would need another round to
+prove the next step wrong. Lingering "do nothing until proven correct"
+hesitation means another round is needed.
+
+## Notes
+
+- The adversary must genuinely attack — an agreeable reviewer gives false
+  confidence. Frame the brief so agreement is failure.
+- Empirical disproof beats argument: prefer an agent that can run a test.
+- This is for uncertainty, not for every decision — skip it when the next step
+  is obvious and easily reversible.