@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.
- package/.claude-plugin/marketplace.json +12 -0
- package/.claude-plugin/plugin.json +20 -0
- package/.codex-plugin/plugin.json +29 -0
- package/.mcp.json +8 -0
- package/ARCHITECTURE.md +314 -0
- package/CHANGELOG.md +467 -0
- package/LICENSE +21 -0
- package/ONBOARDING.md +180 -0
- package/README.md +286 -0
- package/bin/claude-init.sh +90 -0
- package/bin/claude-taste.sh +33 -0
- package/bin/learn-consolidate.sh +51 -0
- package/brand.json +15 -0
- package/global/CLAUDE.md +31 -0
- package/global/crew/frontend-verifier.md +36 -0
- package/global/crew/independent-reviewer.md +29 -0
- package/global/crew/scout.md +24 -0
- package/global/crew/verifier.md +28 -0
- package/global/guards/_guardlib.sh +36 -0
- package/global/guards/cortex.sh +14 -0
- package/global/guards/cost-budget.sh +41 -0
- package/global/guards/doom-loop.sh +25 -0
- package/global/guards/format-on-edit.sh +32 -0
- package/global/guards/lean-guard.sh +20 -0
- package/global/guards/protect-paths.sh +45 -0
- package/global/guards/recall-load.sh +22 -0
- package/global/guards/secret-redact.sh +18 -0
- package/global/guards/session-learner.sh +72 -0
- package/global/recall/MEMORY.md +7 -0
- package/global/rules/self-correction.md +17 -0
- package/global/rules/stack-notes.md +24 -0
- package/global/rules/tech-currency.md +19 -0
- package/global/settings.template.json +183 -0
- package/global/statusline.sh +51 -0
- package/global/taste/brutalist.json +9 -0
- package/global/taste/brutalist.md +19 -0
- package/global/taste/corporate.json +9 -0
- package/global/taste/corporate.md +19 -0
- package/global/taste/editorial.json +9 -0
- package/global/taste/editorial.md +19 -0
- package/global/taste/minimalist.json +9 -0
- package/global/taste/minimalist.md +20 -0
- package/global/taste/playful.json +9 -0
- package/global/taste/playful.md +19 -0
- package/global/tools/atlas/SKILL.md +27 -0
- package/global/tools/code-modernization/SKILL.md +275 -0
- package/global/tools/code-modernization/references/cost-impact-preflight.md +54 -0
- package/global/tools/code-modernization/references/design-patterns-cheatsheet.md +24 -0
- package/global/tools/code-modernization/references/research-protocol.md +42 -0
- package/global/tools/code-modernization/scripts/preflight_scan.py +190 -0
- package/global/tools/cognitive-substrate/SKILL.md +56 -0
- package/global/tools/cognitive-substrate/references/capability-map.md +17 -0
- package/global/tools/cost-guard/SKILL.md +50 -0
- package/global/tools/design-md/SKILL.md +54 -0
- package/global/tools/dev-radar/SKILL.md +56 -0
- package/global/tools/explore-plan-code/SKILL.md +24 -0
- package/global/tools/lean/SKILL.md +41 -0
- package/global/tools/recall/SKILL.md +31 -0
- package/global/tools/reuse-first/SKILL.md +64 -0
- package/global/tools/self-improve/SKILL.md +44 -0
- package/global/tools/taste/SKILL.md +26 -0
- package/global/tools/tech-selector/SKILL.md +35 -0
- package/global/tools/ui-workflow/SKILL.md +44 -0
- package/hooks/hooks.json +107 -0
- package/install.sh +88 -0
- package/package.json +93 -0
- package/public/index.html +45 -0
- package/scripts/build-pages.mjs +180 -0
- package/scripts/bump.mjs +322 -0
- package/skills/cognitive-substrate/SKILL.md +56 -0
- package/skills/cognitive-substrate/references/capability-map.md +17 -0
- package/source/mcp.json +10 -0
- package/source/rules.json +106 -0
- package/source/substrate.json +41 -0
- package/src/adjudicate.js +84 -0
- package/src/anchor.js +210 -0
- package/src/atlas.js +487 -0
- package/src/brain.js +84 -0
- package/src/brand.js +25 -0
- package/src/cli.js +1509 -0
- package/src/context.js +273 -0
- package/src/cortex.js +251 -0
- package/src/cortex_distill.js +55 -0
- package/src/cortex_features.js +81 -0
- package/src/cortex_hook.js +197 -0
- package/src/cortex_hook_main.js +139 -0
- package/src/cortex_mcp.js +352 -0
- package/src/cost_report.js +271 -0
- package/src/dash.html +396 -0
- package/src/dash.js +220 -0
- package/src/diagnose.js +0 -0
- package/src/doctor.js +315 -0
- package/src/embed.js +244 -0
- package/src/emit/_shared.js +39 -0
- package/src/emit/aider.js +22 -0
- package/src/emit/claude.js +44 -0
- package/src/emit/codex.js +17 -0
- package/src/emit/continue.js +28 -0
- package/src/emit/copilot.js +12 -0
- package/src/emit/cursor.js +23 -0
- package/src/emit/gemini.js +40 -0
- package/src/emit/mcp.js +94 -0
- package/src/emit/windsurf.js +22 -0
- package/src/emit/zed.js +34 -0
- package/src/eval.js +47 -0
- package/src/extract.js +82 -0
- package/src/harden.js +44 -0
- package/src/imagine.js +301 -0
- package/src/init.js +178 -0
- package/src/lean.js +149 -0
- package/src/ledger.js +475 -0
- package/src/ledger_bridge.js +279 -0
- package/src/ledger_read.js +152 -0
- package/src/ledger_store.js +360 -0
- package/src/lessons.js +185 -0
- package/src/lessons_store.js +137 -0
- package/src/metrics.js +54 -0
- package/src/model_tiers.js +17 -0
- package/src/model_tiers.json +39 -0
- package/src/predictor.js +143 -0
- package/src/preflight.js +410 -0
- package/src/providers.js +320 -0
- package/src/recall.js +103 -0
- package/src/reuse.js +0 -0
- package/src/route.js +323 -0
- package/src/scope.js +122 -0
- package/src/skillgate.js +89 -0
- package/src/speclock.js +64 -0
- package/src/substrate.js +492 -0
- package/src/sync.js +132 -0
- package/src/taste.js +55 -0
- package/src/uicheck.js +96 -0
- package/src/uifingerprint.js +861 -0
- package/src/uivisual.js +334 -0
- package/src/util.js +71 -0
- package/src/verify.js +117 -0
- package/templates/project-layer/.claude/settings.json +22 -0
- package/templates/project-layer/.claude/skills/hostlelo-deploy/SKILL.md +38 -0
- package/templates/project-layer/AGENTS.md +28 -0
- 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.
|
package/hooks/hooks.json
ADDED
|
@@ -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
|
+
}
|