@codewithjuber/forgekit 0.8.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.
Files changed (140) hide show
  1. package/.claude-plugin/marketplace.json +12 -0
  2. package/.claude-plugin/plugin.json +20 -0
  3. package/.codex-plugin/plugin.json +29 -0
  4. package/.mcp.json +8 -0
  5. package/ARCHITECTURE.md +314 -0
  6. package/CHANGELOG.md +467 -0
  7. package/LICENSE +21 -0
  8. package/ONBOARDING.md +180 -0
  9. package/README.md +286 -0
  10. package/bin/claude-init.sh +90 -0
  11. package/bin/claude-taste.sh +33 -0
  12. package/bin/learn-consolidate.sh +51 -0
  13. package/brand.json +15 -0
  14. package/global/CLAUDE.md +31 -0
  15. package/global/crew/frontend-verifier.md +36 -0
  16. package/global/crew/independent-reviewer.md +29 -0
  17. package/global/crew/scout.md +24 -0
  18. package/global/crew/verifier.md +28 -0
  19. package/global/guards/_guardlib.sh +36 -0
  20. package/global/guards/cortex.sh +14 -0
  21. package/global/guards/cost-budget.sh +41 -0
  22. package/global/guards/doom-loop.sh +25 -0
  23. package/global/guards/format-on-edit.sh +32 -0
  24. package/global/guards/lean-guard.sh +20 -0
  25. package/global/guards/protect-paths.sh +45 -0
  26. package/global/guards/recall-load.sh +22 -0
  27. package/global/guards/secret-redact.sh +18 -0
  28. package/global/guards/session-learner.sh +72 -0
  29. package/global/recall/MEMORY.md +7 -0
  30. package/global/rules/self-correction.md +17 -0
  31. package/global/rules/stack-notes.md +24 -0
  32. package/global/rules/tech-currency.md +19 -0
  33. package/global/settings.template.json +183 -0
  34. package/global/statusline.sh +51 -0
  35. package/global/taste/brutalist.json +9 -0
  36. package/global/taste/brutalist.md +19 -0
  37. package/global/taste/corporate.json +9 -0
  38. package/global/taste/corporate.md +19 -0
  39. package/global/taste/editorial.json +9 -0
  40. package/global/taste/editorial.md +19 -0
  41. package/global/taste/minimalist.json +9 -0
  42. package/global/taste/minimalist.md +20 -0
  43. package/global/taste/playful.json +9 -0
  44. package/global/taste/playful.md +19 -0
  45. package/global/tools/atlas/SKILL.md +27 -0
  46. package/global/tools/code-modernization/SKILL.md +275 -0
  47. package/global/tools/code-modernization/references/cost-impact-preflight.md +54 -0
  48. package/global/tools/code-modernization/references/design-patterns-cheatsheet.md +24 -0
  49. package/global/tools/code-modernization/references/research-protocol.md +42 -0
  50. package/global/tools/code-modernization/scripts/preflight_scan.py +190 -0
  51. package/global/tools/cognitive-substrate/SKILL.md +56 -0
  52. package/global/tools/cognitive-substrate/references/capability-map.md +17 -0
  53. package/global/tools/cost-guard/SKILL.md +50 -0
  54. package/global/tools/design-md/SKILL.md +54 -0
  55. package/global/tools/dev-radar/SKILL.md +56 -0
  56. package/global/tools/explore-plan-code/SKILL.md +24 -0
  57. package/global/tools/lean/SKILL.md +41 -0
  58. package/global/tools/recall/SKILL.md +31 -0
  59. package/global/tools/reuse-first/SKILL.md +64 -0
  60. package/global/tools/self-improve/SKILL.md +44 -0
  61. package/global/tools/taste/SKILL.md +26 -0
  62. package/global/tools/tech-selector/SKILL.md +35 -0
  63. package/global/tools/ui-workflow/SKILL.md +44 -0
  64. package/hooks/hooks.json +107 -0
  65. package/install.sh +88 -0
  66. package/package.json +93 -0
  67. package/public/index.html +45 -0
  68. package/scripts/build-pages.mjs +180 -0
  69. package/scripts/bump.mjs +322 -0
  70. package/skills/cognitive-substrate/SKILL.md +56 -0
  71. package/skills/cognitive-substrate/references/capability-map.md +17 -0
  72. package/source/mcp.json +10 -0
  73. package/source/rules.json +106 -0
  74. package/source/substrate.json +41 -0
  75. package/src/adjudicate.js +84 -0
  76. package/src/anchor.js +210 -0
  77. package/src/atlas.js +487 -0
  78. package/src/brain.js +84 -0
  79. package/src/brand.js +25 -0
  80. package/src/cli.js +1509 -0
  81. package/src/context.js +273 -0
  82. package/src/cortex.js +251 -0
  83. package/src/cortex_distill.js +55 -0
  84. package/src/cortex_features.js +81 -0
  85. package/src/cortex_hook.js +197 -0
  86. package/src/cortex_hook_main.js +139 -0
  87. package/src/cortex_mcp.js +352 -0
  88. package/src/cost_report.js +271 -0
  89. package/src/dash.html +396 -0
  90. package/src/dash.js +220 -0
  91. package/src/diagnose.js +0 -0
  92. package/src/doctor.js +315 -0
  93. package/src/embed.js +244 -0
  94. package/src/emit/_shared.js +39 -0
  95. package/src/emit/aider.js +22 -0
  96. package/src/emit/claude.js +44 -0
  97. package/src/emit/codex.js +17 -0
  98. package/src/emit/continue.js +28 -0
  99. package/src/emit/copilot.js +12 -0
  100. package/src/emit/cursor.js +23 -0
  101. package/src/emit/gemini.js +40 -0
  102. package/src/emit/mcp.js +94 -0
  103. package/src/emit/windsurf.js +22 -0
  104. package/src/emit/zed.js +34 -0
  105. package/src/eval.js +47 -0
  106. package/src/extract.js +82 -0
  107. package/src/harden.js +44 -0
  108. package/src/imagine.js +301 -0
  109. package/src/init.js +178 -0
  110. package/src/lean.js +149 -0
  111. package/src/ledger.js +475 -0
  112. package/src/ledger_bridge.js +279 -0
  113. package/src/ledger_read.js +152 -0
  114. package/src/ledger_store.js +360 -0
  115. package/src/lessons.js +185 -0
  116. package/src/lessons_store.js +137 -0
  117. package/src/metrics.js +54 -0
  118. package/src/model_tiers.js +17 -0
  119. package/src/model_tiers.json +39 -0
  120. package/src/predictor.js +143 -0
  121. package/src/preflight.js +410 -0
  122. package/src/providers.js +320 -0
  123. package/src/recall.js +103 -0
  124. package/src/reuse.js +0 -0
  125. package/src/route.js +323 -0
  126. package/src/scope.js +122 -0
  127. package/src/skillgate.js +89 -0
  128. package/src/speclock.js +64 -0
  129. package/src/substrate.js +492 -0
  130. package/src/sync.js +132 -0
  131. package/src/taste.js +55 -0
  132. package/src/uicheck.js +96 -0
  133. package/src/uifingerprint.js +861 -0
  134. package/src/uivisual.js +334 -0
  135. package/src/util.js +71 -0
  136. package/src/verify.js +117 -0
  137. package/templates/project-layer/.claude/settings.json +22 -0
  138. package/templates/project-layer/.claude/skills/hostlelo-deploy/SKILL.md +38 -0
  139. package/templates/project-layer/AGENTS.md +28 -0
  140. package/templates/project-layer/CLAUDE.md +40 -0
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: cost-guard
3
+ description: Reduce token/cost burn on large or exploratory tasks. Use when a task will touch many files, involves broad codebase search, a big migration, or when the user asks to keep cost/context low.
4
+ ---
5
+
6
+ # Cost guard
7
+
8
+ Playbook for high-performance, low-cost runs. The constraint is the context
9
+ window: performance degrades as it fills, and tokens cost money. Spend context
10
+ deliberately.
11
+
12
+ ## Rules of thumb
13
+ - **Search, don't read.** Use `rg`/`grep`/`glob` to locate, then read only the
14
+ relevant lines/ranges — not whole files or directories.
15
+ - **Delegate exploration.** For "how does X work / where is Y" questions across
16
+ many files, spawn the `scout` subagent. It reads in its own context and returns
17
+ a summary, keeping the main thread lean.
18
+ - **Verify with a fresh model.** For non-trivial diffs, use the `verifier`
19
+ subagent instead of re-reading everything yourself.
20
+ - **Clear between tasks.** Unrelated work → `/clear`. Long single problems can
21
+ keep context; switching topics should not.
22
+ - **Compact with intent.** When near limits, `/compact Focus on <the thing that
23
+ matters>` beats a generic compaction.
24
+ - **Prefer CLIs** (`gh`, cloud CLIs) over pasting large outputs or fetching pages.
25
+ - **Scope investigations.** Never say "investigate X" unbounded — name the files
26
+ or the question, or hand it to `scout`.
27
+
28
+ ## Model choice + measurement
29
+ - `forge route "<task>"` names the cheapest capable tier before you pick a model;
30
+ escalate only after an external verifier fails.
31
+ - Cheap model (`scout`) for search/triage/enumeration; reserve the top model for
32
+ genuinely hard reasoning, not routine edits.
33
+ - `forge cost` shows real per-day spend; **`forge cost --stages`** shows the
34
+ measured per-stage savings (gate / cache / route / context) from
35
+ `.forge/metrics.jsonl` — a stage with no events says "no data", never a default.
36
+ - `forge reuse query "<spec>"` before regenerating: a hit is verified code you
37
+ already paid for.
38
+
39
+ ## Prompt-cache hygiene
40
+ Claude Code caches by exact request *prefix*; a change high in the prefix
41
+ recomputes everything after it. Pick model + MCP servers at session start
42
+ (switching mid-task busts the cache); save `/compact` for natural breaks and
43
+ prefer `/rewind` to abandon a path; don't add bare-tool deny rules mid-session
44
+ (scoped rules like `Bash(rm *)` are cache-safe); watch the status line's `⚡NN%`
45
+ indicator — if it stays low turn after turn, your prefix keeps changing.
46
+
47
+ ## Fan-out for big batches
48
+ For repetitive edits across many files, generate the file list first, test the
49
+ prompt on 2–3 files, then loop `claude -p "<prompt>" --allowedTools "Edit,Bash(git commit *)"`
50
+ over the rest rather than doing all of it in one bloated session.
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: design-md
3
+ description: Create and maintain a per-project DESIGN.md that pins the ONE visual direction so UI stays consistent across sessions and screens. Use when starting UI on a project, when look feels inconsistent, or the user mentions design system / DESIGN.md / visual guidelines.
4
+ ---
5
+
6
+ # DESIGN.md
7
+
8
+ The fix for "UI comes out inconsistent" is a single written source of visual
9
+ truth per project. `ui-workflow` says pick one direction — `DESIGN.md` is where
10
+ that direction lives so every session and screen obeys the same rules.
11
+ `forge taste <style>` writes a managed one from Forge's menu; hand-write it only
12
+ for a bespoke direction.
13
+
14
+ Create it at the start of UI work, or the first time output drifts. One file at
15
+ repo root; reference it from the project `CLAUDE.md` (`See @DESIGN.md for visual
16
+ rules`) so Claude loads it. Keep it tight: concrete rules and tokens, not
17
+ adjectives — "Primary #4F46E5, 8pt spacing scale, Inter", not "modern and clean".
18
+
19
+ ## Template
20
+ ```markdown
21
+ # DESIGN.md — <project>
22
+
23
+ ## Direction
24
+ One sentence + 1-2 reference links/screenshots. The single aesthetic. Don't mix.
25
+
26
+ ## Tokens
27
+ - Color: primary / bg / surface / text / border / success / warn / danger (hex)
28
+ - Type: font family; scale (e.g. 12/14/16/20/24/32); weights
29
+ - Spacing: base unit (e.g. 4px) + scale; radius; shadow levels
30
+ - Breakpoints: mobile / tablet / desktop widths
31
+
32
+ ## Components
33
+ - Library: <project components / component system> — reuse, don't hand-roll
34
+ - Buttons/inputs/cards: variants + states (default/hover/focus/disabled) rules
35
+ - Density, alignment, and layout grid rules
36
+
37
+ ## Do / Don't
38
+ - Do: <3-5 concrete rules>
39
+ - Don't: <3-5 concrete anti-patterns for THIS project>
40
+
41
+ ## Accessibility baseline
42
+ Contrast ≥ 4.5:1 body; visible focus rings; labels on inputs; keyboard nav;
43
+ hit targets ≥ 44px.
44
+
45
+ ## References
46
+ Links to the reference site(s)/Figma this design matches.
47
+ ```
48
+
49
+ ## Enforce it (prose steers; the gate checks)
50
+ Once real UI matches the direction, mint its fingerprint:
51
+ `forge uicheck fingerprint <ui files> --mint`. Then `forge uicheck design <files>
52
+ --taste <style>` gates new UI against the taste constraints + project fingerprint
53
+ (a Forge-managed DESIGN.md is picked up automatically). When the user approves a
54
+ new visual decision, update DESIGN.md and re-mint so it sticks.
@@ -0,0 +1,56 @@
1
+ ---
2
+ name: dev-radar
3
+ description: Pull current, real-world software-dev signal on demand from GitHub trending, Reddit, research papers, and blogs — filtered to the user's stack, hype-filtered, with verified sources. Use when the user asks "what's new/trending", "latest in <tech>", "should I adopt X", or wants a dev digest. Coding topics only.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # Dev radar
8
+
9
+ On-demand scan of what's actually happening in software dev right now — not
10
+ training-data recall. Signal over noise, coding topics only.
11
+
12
+ ## Sources (fetch live each run)
13
+
14
+ - **GitHub trending** — [https://github.com/trending?since=daily](https://github.com/trending?since=daily) | weekly | monthly
15
+ (add `&spoken_language_code=` / language filters). Best for real traction.
16
+ Cross-check a repo's health before recommending (last commit, releases, issues,
17
+ license) — trending ≠ maintained.
18
+ - **Reddit** (via WebSearch / old.reddit JSON) — r/programming, r/webdev,
19
+ r/ExperiencedDevs, r/nextjs, r/node, r/LocalLLaMA, r/MachineLearning. Read the
20
+ top comments, not just the headline — Reddit's value is the critique.
21
+ - **Papers** — arXiv (cs.SE, cs.AI), Hugging Face papers (HF MCP), Context7 for
22
+ library docs. Use for AI/ML and algorithmic topics.
23
+ - **Blogs** — WebSearch for Medium/eng-blog posts; treat as opinion, verify claims.
24
+
25
+
26
+
27
+ ## Method
28
+
29
+ 1. Scope to the user's stack unless they widen it: Next.js/React, Node, Postgres +
30
+ pgvector, TypeScript, Python, LLM/agent tooling. Ignore unrelated trends.
31
+ 2. Gather from 2-3 sources in parallel; dedupe.
32
+ 3. **Hype filter** — drop "X is dead" / "just switch to Y" posts unless there's
33
+ real evidence (adoption, benchmarks, maintainer signal). Note the counter-view.
34
+ 4. For anything actionable, hand it to `tech-selector` before recommending adoption.
35
+
36
+
37
+
38
+ ## Output (dated)
39
+
40
+ A short digest: **What's moving** (3-6 items: repo/paper/thread · one line · link ·
41
+ why it matters to your stack) → **Worth a real look** (1-2, with the trade-off) →
42
+ **Skip / hype** (things being overhyped, and why). Every claim links its source and
43
+ states the date. End with: which items (if any) warrant a `tech-selector` pass.
44
+
45
+ ## Guardrails
46
+
47
+ - Software/coding only — no general news.
48
+ - Cite sources; never assert currency from memory. If a source didn't load, say so.
49
+ - Trending is a starting signal, not a recommendation. Adoption still needs the
50
+ fit/maintenance/license check.
51
+
52
+
53
+
54
+ ## Optional: recurring digest
55
+
56
+ For a weekly cadence, the user can wire a scheduled run (`claude -p "/dev-radar weekly, my stack"`) via cron or their scheduler, output appended to a notes file.
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: explore-plan-code
3
+ description: Structured workflow for non-trivial features or unfamiliar code — explore, then plan, then implement, then verify. Use when a change spans multiple files, the approach is uncertain, or the user asks for a spec/plan first.
4
+ ---
5
+
6
+ # Explore → Plan → Code → Verify
7
+
8
+ Separate research from execution so you don't build the wrong thing.
9
+
10
+ 1. **Explore (read-only).** Enter plan mode or use the `scout` subagent. Read the
11
+ relevant files and existing patterns. Answer: where does this live, what
12
+ conventions apply, what will change. No edits yet.
13
+ 2. **Plan.** Produce a concrete plan naming the exact files/interfaces to touch,
14
+ what's out of scope, and an end-to-end verification step. For big features,
15
+ interview the user with `AskUserQuestion`, then write it to `SPEC.md` and start
16
+ a fresh session to implement against it.
17
+ 3. **Code.** Implement against the plan. Follow existing patterns; add no new deps
18
+ without cause.
19
+ 4. **Verify.** Run the check (tests/build/lint) and show the output. For risky
20
+ diffs, hand to the `verifier` subagent. Iterate until it actually passes —
21
+ don't assert success without evidence.
22
+
23
+ Skip this whole flow for one-line or obviously-scoped fixes; the ceremony isn't
24
+ worth it there.
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: lean
3
+ description: Forge's minimalism discipline. Use for any "add X" / "build Y" / refactor / bug-fix — before writing code, to choose the smallest change that actually solves the problem. Reuse over rewrite, delete over add, boring over clever.
4
+ ---
5
+
6
+ # lean — the smallest change that works
7
+
8
+ The best code is the code you never write; the second best already exists in this
9
+ repo. `lean` is a reflex applied AFTER you understand the problem, never instead of
10
+ understanding it.
11
+
12
+ ## The Lean Path (stop at the first step that holds)
13
+ 1. **Need?** Does this need to exist at all? Speculative "for later" → skip it and
14
+ say so in one line. (YAGNI)
15
+ 2. **Here already?** A util, component, type, or pattern that already lives in this
16
+ repo → reuse or extend it. Look before you write.
17
+ 3. **Platform / stdlib?** The language stdlib, a native platform feature, or an
18
+ already-installed dependency covers it → use it. Never add a dependency for what
19
+ a few lines do.
20
+ 4. **One small change.** The smallest diff that fits the file's style. Fewest files.
21
+ Boring over clever — clever is what someone decodes at 3am.
22
+ 5. **Root, not symptom.** A report names a symptom. Fix it once in the shared
23
+ function all callers route through — not in each caller.
24
+
25
+ ## Rules
26
+ - No unrequested abstraction: no interface with one implementation, no factory for
27
+ one product, no config for a value that never changes.
28
+ - Deletion over addition. The shortest working diff wins — once you understand what
29
+ the change must touch. The smallest change in the wrong place is a second bug.
30
+ - Mark a deliberate shortcut with a comment naming its ceiling and upgrade path,
31
+ e.g. `// lean: O(n^2) scan, index it if the list grows`.
32
+
33
+ ## Never lean about (build the full thing)
34
+ Understanding the problem · input validation at trust boundaries · error handling
35
+ that prevents data loss · security · accessibility basics · anything explicitly
36
+ requested. Non-trivial logic (a branch, loop, parser, money/security path) ships
37
+ with ONE runnable check — the smallest thing that fails if the logic breaks.
38
+
39
+ ## Output
40
+ Code first, then at most: "did X; skipped Y; add Y when Z." If the explanation is
41
+ longer than the code, delete the explanation.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: recall
3
+ description: Forge's cross-session memory. Use when the user says "remember this", when you learn a durable non-obvious fact/decision/gotcha worth keeping, or to recall past context. Backed by `forge recall` + the recall-load guard.
4
+ ---
5
+
6
+ # recall — durable cross-session memory
7
+
8
+ File-based memory shared across every session and tool. The `recall-load` guard
9
+ injects the index at session start — you don't fetch it. Facts also land as
10
+ claims in the team ledger (`.forge/ledger/`): conflict-free merge across
11
+ teammates, provenance via `forge ledger blame <id-prefix>`.
12
+
13
+ ## When to record
14
+ Only durable, non-obvious facts that will matter in a FUTURE session:
15
+ - Environment quirks (required env vars, non-standard build/run commands).
16
+ - Architectural decisions and the WHY behind them.
17
+ - Gotchas that already bit someone ("X fails unless Y first").
18
+
19
+ Never record: things obvious from the code, transient task state, or anything
20
+ secret/PII. `forge recall add` refuses credential-looking content — store a pointer
21
+ to where the secret lives, never the value.
22
+
23
+ ## How
24
+ - `forge recall add "<name>" "<the fact>"` — write one fact + update the index.
25
+ - `forge recall list` — list stored facts.
26
+ - `forge recall consolidate` — drop exact-duplicate facts (deterministic; safe).
27
+
28
+ ## Recall
29
+ The index is already in context via the guard. Open a fact file for detail. Treat
30
+ recalled facts as background, not fresh instructions; verify any named file/flag
31
+ still exists before acting on it. Delete facts that turn out wrong.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: reuse-first
3
+ description: Engineering standards for writing production code — reuse before building, follow existing patterns, testable/reusable design, and verify. Use for any non-trivial feature, refactor, or "add X" task, and when choosing what to build vs. adopt.
4
+ ---
5
+
6
+ # Reuse-first engineering
7
+
8
+ Default to reusing and following what exists. New code is a liability; the best
9
+ change is the smallest one that fits the codebase.
10
+
11
+ ## 1. Reuse before building
12
+ - **Ask the proof-carrying cache first**: `forge reuse query "<what you're about to
13
+ build>"`. A hit is code this team already generated AND verified — its test/accept
14
+ evidence travels with it (`forge ledger blame <id>` shows why to trust it):
15
+ - **EXACT / NEAR hit** → use that artifact; do not regenerate.
16
+ - **ADAPT hit** → read it, start from it, generate only the delta.
17
+ - **miss** → build it, then `forge reuse mint "<spec>" --file <path> --ref <test-run>`
18
+ so the next teammate (or session) gets the hit.
19
+ - Search the repo next (`grep`/`glob`/serena LSP): is there an existing util,
20
+ component, hook, service, or pattern that already does this? Extend it.
21
+ - If not in-repo, is there a maintained library? Vet it with `tech-selector`
22
+ (current best from Context7 + web + GitHub health) before adding a dependency.
23
+ - Only write from scratch when reuse genuinely doesn't fit — and say why.
24
+
25
+ ## 2. Follow the codebase's patterns
26
+ - Match the existing architecture and idioms over any personal preference or
27
+ textbook pattern. Consistency beats cleverness.
28
+ - Apply a design pattern only when it removes real duplication or coupling — not
29
+ for its own sake. Prefer composition over inheritance; keep modules cohesive and
30
+ loosely coupled; push side effects to the edges.
31
+
32
+ ## 3. Design for reuse + testability
33
+ - Small, single-purpose functions with typed inputs/outputs. Separate pure logic
34
+ from I/O so the logic is testable without mocks.
35
+ - No hidden globals; pass dependencies in. Name things for intent.
36
+
37
+ ## 4. Test
38
+ - Write tests with the code, not after. Unit-test the pure logic; cover the edge
39
+ cases the task named (empty, error, boundary). Prefer real inputs over heavy
40
+ mocking.
41
+ - For a bug fix, first write a failing test that reproduces it, then fix.
42
+
43
+ ## 5. Verify (don't assert "done")
44
+ - Run the project's tests + typecheck + lint and show the output. UI → screenshot
45
+ check via `ui-workflow`. Non-trivial diff → `verifier` subagent.
46
+ - Fix root causes; never suppress an error to make a check pass.
47
+
48
+ ## Per-stack starting points (verify currency with `tech-selector` before adopting)
49
+ The dated verified baseline lives in `~/.claude/rules/stack-notes.md` (refresh via
50
+ `/dev-radar`). Quick defaults below — treat as candidates, confirm live per use case:
51
+ - **Web app**: Next.js (App Router) / React; SvelteKit or Astro for content-led.
52
+ - **Styling/UI**: Tailwind + shadcn/ui (Radix) — pull real component code via the
53
+ shadcn MCP, don't hand-roll.
54
+ - **Data/state**: TanStack Query for server state; Zustand for light client state.
55
+ - **Forms/validation**: React Hook Form + Zod (Zod schemas shared client↔server).
56
+ - **DB/ORM (Node + Postgres/pgvector)**: Drizzle or Prisma; raw SQL for hot paths.
57
+ - **Auth**: the framework's first-party option or a maintained provider — don't
58
+ roll your own crypto/session logic.
59
+ - **Testing**: Vitest (unit) + Playwright (e2e) for JS; pytest for Python.
60
+ - **Python**: `uv` for env/deps, `ruff` (lint+format), `pydantic` for schemas.
61
+ - **Deploy**: match the project (Vercel for Next.js; your VPS + Cloudflare for
62
+ Hostlelo services).
63
+ Never present these as settled because they were popular at training time — run
64
+ `tech-selector` and cite the version + date.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: self-improve
3
+ description: Self-correction and cross-session learning loop. Use when a check fails and needs iterating to green, when the user corrects the same thing more than once, or when a non-obvious fix/gotcha is worth remembering for next time.
4
+ ---
5
+
6
+ # Self-improve
7
+
8
+ Honest scope: you can't reinforcement-learn a hosted model's weights in a config.
9
+ What works is **experiential learning** — correct within the session, persist
10
+ durable lessons for the next one. Two loops:
11
+
12
+ ## Loop A — self-correct (within a session)
13
+ Close the loop yourself instead of waiting for the user to catch errors:
14
+ 1. Run a check that returns pass/fail: tests, build, typecheck, lint, or a
15
+ screenshot diff (UI).
16
+ 2. On fail, read the actual error and diagnose the **root cause** — don't patch
17
+ the symptom or suppress it. Record it: `forge diagnose "<error>" --file <f>`.
18
+ 3. Fix, then re-run the same check. Show the evidence (command + result).
19
+ 4. Cap it: `forge diagnose` counts recurrences — the 3rd identical failure
20
+ signature mints a **diagnosis claim** in the team ledger and says STOP.
21
+ Don't keep retrying: state the diagnosis (`forge ledger show <id>`), add what
22
+ you tried, and escalate ONE model tier with the diagnosis at the head of the
23
+ new prompt — never a bare "try again, but more expensive". Repeated failed
24
+ patches pollute context and make it worse.
25
+ Use the `verifier` / `frontend-verifier` subagents for an independent check on
26
+ non-trivial diffs.
27
+
28
+ ## Loop B — capture the lesson (across sessions)
29
+ When something was non-obvious — the user corrected you twice on the same point,
30
+ or a fix depended on a project gotcha — record it so it's not re-learned next time:
31
+ - Cortex captures recurring corrections on its own as you work; for explicit
32
+ facts, `forge recall add "<name>" "<fact>"` (or a one-line entry in the repo's
33
+ `AGENTS.md`).
34
+ - Keep it a rule, not a story: "In <project>, X fails unless Y — do Y first."
35
+ - Never store secrets/PII. Delete lessons that turn out wrong.
36
+ Lessons and facts land as claims in `.forge/ledger/` — confidence moves only when
37
+ independent oracles (tests, CI, human accept/revert) confirm or refute them, and
38
+ `forge ledger blame <id>` shows that history.
39
+
40
+ ## What "self-evolving" honestly means here
41
+ Code knowledge stays current via the atlas (`forge atlas build`); behaviour
42
+ improves through Loop B, and the ledger demotes lessons that stop earning
43
+ confirmations. Anything promising weight-level RL from a local config is
44
+ overstating it — treat those claims with `tech-selector` skepticism.
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: taste
3
+ description: Pick a visual design direction for a repo from Forge's menu (minimalist, brutalist, editorial, playful, corporate). Use when starting UI work or when the user wants a specific look. Sets DESIGN.md, which every AI tool then follows.
4
+ ---
5
+
6
+ # taste — choose one design direction
7
+
8
+ Forge ships a MENU of visual directions; each repo pins exactly ONE.
9
+
10
+ - `forge taste` — list the available styles.
11
+ - `forge taste <style>` — write that style's spec to this repo's `DESIGN.md`.
12
+
13
+ The shared rules tell every tool to "follow DESIGN.md if present," so setting a
14
+ taste once steers Claude Code, Cursor, Codex, Gemini, and the rest. Switch anytime
15
+ with `forge taste <other>` (it regenerates DESIGN.md).
16
+
17
+ Styles: minimalist (restraint) · brutalist (raw/high-contrast) · editorial
18
+ (magazine/typographic) · playful (friendly/rounded) · corporate (trustworthy/AA).
19
+
20
+ Each style ships machine-readable constraints: prose steers generation, but
21
+ `forge uicheck design <files> --taste <style>` *checks* the result (style
22
+ auto-detected from a Forge-managed DESIGN.md). Mint the project fingerprint from
23
+ approved UI — `forge uicheck fingerprint <files> --mint` — to gate conformance too.
24
+
25
+ Don't hand-edit a Forge-managed DESIGN.md — re-run `forge taste`, or delete the
26
+ marker line to take it over yourself.
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: tech-selector
3
+ description: Choose a library, framework, or tool by verifying the CURRENT best option from live sources — not from training data. Use whenever picking a dependency, starting a project, or the user asks "what's the best X for Y", "latest", "which library", or wants an unbiased/current recommendation.
4
+ ---
5
+
6
+ # Tech selector
7
+
8
+ Training data is stale and biased toward what was popular at cutoff. For any
9
+ "what should I use" decision, verify against live sources before recommending.
10
+
11
+ ## Verify before recommending (don't skip)
12
+ 1. **Docs (Context7 MCP)** — `resolve-library-id` then `get-library-docs` for the
13
+ candidates. Confirms the API is current and the library still exists.
14
+ 2. **Web search** — "<use-case> best library <current year>", release notes,
15
+ "X vs Y". Look for recency; ignore posts older than ~18 months unless canonical.
16
+ 3. **GitHub health** (via `gh` or GitHub MCP) — for each finalist check:
17
+ last commit date, release cadence, open-vs-closed issue ratio, maintainer
18
+ count, and license. A popular-but-abandoned repo is a trap.
19
+
20
+ ## Decision rubric (fit first, not stars)
21
+ Score finalists on: **fit** to the actual use case > **maintenance** (active,
22
+ recent releases) > **license** compatibility > **DX / docs quality** > **bundle
23
+ / runtime cost** > **ecosystem & types** > popularity. Popularity breaks ties, it
24
+ doesn't win them.
25
+
26
+ ## Anti-bias rules
27
+ - Don't default to the framework you "know" — name ≥2 real alternatives and say
28
+ why the pick wins for *this* case.
29
+ - Prefer what the project already uses over introducing a new dependency.
30
+ - State the date of the evidence and the version you verified. If you couldn't
31
+ verify, say so — don't assert currency from memory.
32
+
33
+ ## Output
34
+ A short table: option · fit · maintenance (last release) · license · why/why-not,
35
+ then a one-line pick with the specific version and the trade-off you accepted.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: ui-workflow
3
+ description: Reliable workflow for building or fixing UI so results look intentional, not generic. Use for any frontend/UI task — new screen, component, redesign, "make it look better", layout, styling, or when the user says UI is the pain point.
4
+ ---
5
+
6
+ # UI workflow
7
+
8
+ UI is unreliable when taste is vague and there's no check. Fix both: lock ONE
9
+ visual direction, build on the project's real components, then verify with the
10
+ deterministic design gate and a screenshot instead of guessing.
11
+
12
+ ## 0. Pick ONE direction — don't stack taste sources
13
+ Competing taste/design skills produce muddy, inconsistent output. Per project,
14
+ choose **one** source of visual truth: the repo's `DESIGN.md` (create it with
15
+ `forge taste <style>` or the `design-md` tool), or a reference URL/screenshot
16
+ from the user. If none exists, ask.
17
+
18
+ ## 1. Ground the components (current APIs, not memory)
19
+ - Reuse the project's existing components and design tokens first —
20
+ `forge atlas query <Component>` finds them.
21
+ - Confirm any library's props/API against current docs, not recall; vet new
22
+ dependencies with `tech-selector`.
23
+
24
+ ## 2. Build
25
+ - Match the project's stack and component system over bespoke CSS.
26
+ - Accessibility is not optional: labels, focus states, contrast, keyboard nav.
27
+
28
+ ## 3. Verify (the step that makes UI reliable)
29
+ - **Deterministic gate first:** `forge uicheck design <files> --taste <style>`
30
+ (exit 1 on fail) — slop distance to generic templates must stay HIGH,
31
+ conformance to the project's minted fingerprint must stay LOW, spacing/radius/
32
+ shadow on scale. Failures are per-feature edits, not a score. If the repo has
33
+ no fingerprint yet, mint one from approved UI:
34
+ `forge uicheck fingerprint <files> --mint`.
35
+ - `forge uicheck contrast <fg> <bg>` for exact WCAG math — never eyeball it.
36
+ - **Then screenshot:** render at desktop AND mobile widths, compare against the
37
+ reference/DESIGN.md, list concrete differences (spacing, hierarchy, color,
38
+ alignment) and fix. For a second opinion, hand the screenshot + reference to
39
+ the `frontend-verifier` subagent.
40
+
41
+ ## Done =
42
+ Passes `forge uicheck design`, matches the reference at both breakpoints, passes
43
+ accessibility checks, uses the project's tokens/components, and you've shown the
44
+ final screenshot as evidence.
@@ -0,0 +1,107 @@
1
+ {
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "matcher": "startup|resume|clear",
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/recall-load.sh"
10
+ },
11
+ {
12
+ "type": "command",
13
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cortex.sh session-start"
14
+ }
15
+ ]
16
+ }
17
+ ],
18
+ "UserPromptSubmit": [
19
+ {
20
+ "hooks": [
21
+ {
22
+ "type": "command",
23
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cortex.sh prompt"
24
+ },
25
+ {
26
+ "type": "command",
27
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cortex.sh preflight"
28
+ }
29
+ ]
30
+ }
31
+ ],
32
+ "PreToolUse": [
33
+ {
34
+ "matcher": "Edit|Write|MultiEdit|Bash",
35
+ "hooks": [
36
+ {
37
+ "type": "command",
38
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/protect-paths.sh"
39
+ },
40
+ {
41
+ "type": "command",
42
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cost-budget.sh"
43
+ },
44
+ {
45
+ "type": "command",
46
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/doom-loop.sh"
47
+ }
48
+ ]
49
+ },
50
+ {
51
+ "matcher": "Edit|Write|MultiEdit",
52
+ "hooks": [
53
+ {
54
+ "type": "command",
55
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cortex.sh pre-edit"
56
+ }
57
+ ]
58
+ }
59
+ ],
60
+ "PostToolUse": [
61
+ {
62
+ "matcher": "Edit|Write|MultiEdit",
63
+ "hooks": [
64
+ {
65
+ "type": "command",
66
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/format-on-edit.sh"
67
+ },
68
+ {
69
+ "type": "command",
70
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cortex.sh capture"
71
+ }
72
+ ]
73
+ },
74
+ {
75
+ "matcher": "Bash|Read|Grep",
76
+ "hooks": [
77
+ {
78
+ "type": "command",
79
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/secret-redact.sh"
80
+ },
81
+ {
82
+ "type": "command",
83
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cortex.sh capture"
84
+ }
85
+ ]
86
+ }
87
+ ],
88
+ "Stop": [
89
+ {
90
+ "hooks": [
91
+ {
92
+ "type": "command",
93
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/lean-guard.sh"
94
+ },
95
+ {
96
+ "type": "command",
97
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/session-learner.sh"
98
+ },
99
+ {
100
+ "type": "command",
101
+ "command": "\"${CLAUDE_PLUGIN_ROOT}\"/global/guards/cortex.sh stop"
102
+ }
103
+ ]
104
+ }
105
+ ]
106
+ }
107
+ }