create-modoock-app 1.0.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/dist/cli.js +52 -0
- package/package.json +21 -0
- package/template/.cursor/agents/code-reviewer.md +25 -0
- package/template/.cursor/rules/agents.mdc +9 -0
- package/template/.cursor/rules/honey.mdc +226 -0
- package/template/.cursor/rules/ui.mdc +18 -0
- package/template/.cursor/skills/debug/SKILL.md +29 -0
- package/template/.dcdignore +3 -0
- package/template/AGENTS.md +89 -0
- package/template/CLAUDE.md +2 -0
- package/template/README.md +339 -0
- package/template/app/(local)/components/page.tsx +886 -0
- package/template/app/(local)/design-system/page.tsx +1140 -0
- package/template/app/(local)/layout.tsx +5 -0
- package/template/app/(local)/page.tsx +59 -0
- package/template/app/auth/layout.tsx +7 -0
- package/template/app/auth/login/page.tsx +76 -0
- package/template/app/favicon.ico +0 -0
- package/template/app/globals.css +365 -0
- package/template/app/layout.tsx +28 -0
- package/template/components/layout/app-layout.tsx +30 -0
- package/template/components/layout/header.tsx +72 -0
- package/template/components/layout/index.ts +3 -0
- package/template/components/layout/side-nav.tsx +163 -0
- package/template/components/shared/detail-header.tsx +39 -0
- package/template/components/shared/index.ts +8 -0
- package/template/components/shared/info-card.tsx +75 -0
- package/template/components/shared/summary-card.tsx +31 -0
- package/template/components/shared/table-section.tsx +38 -0
- package/template/components/shared/timeline-list.tsx +31 -0
- package/template/components/ui/action-stack.tsx +42 -0
- package/template/components/ui/badge.tsx +43 -0
- package/template/components/ui/button.tsx +104 -0
- package/template/components/ui/icon.tsx +78 -0
- package/template/components/ui/index.ts +28 -0
- package/template/components/ui/input.tsx +376 -0
- package/template/components/ui/loader.tsx +78 -0
- package/template/components/ui/metric-bar.tsx +49 -0
- package/template/components/ui/modal.tsx +177 -0
- package/template/components/ui/select.tsx +458 -0
- package/template/components/ui/stepper.tsx +96 -0
- package/template/components/ui/tab.tsx +85 -0
- package/template/components/ui/user-table.tsx +806 -0
- package/template/eslint.config.mjs +18 -0
- package/template/knowledge-base/design-system/components/action-stack.mdc +17 -0
- package/template/knowledge-base/design-system/components/badges.mdc +16 -0
- package/template/knowledge-base/design-system/components/buttons.mdc +21 -0
- package/template/knowledge-base/design-system/components/detail-header.mdc +17 -0
- package/template/knowledge-base/design-system/components/dropdowns.mdc +12 -0
- package/template/knowledge-base/design-system/components/info-list.mdc +17 -0
- package/template/knowledge-base/design-system/components/inputs.mdc +23 -0
- package/template/knowledge-base/design-system/components/menu.mdc +20 -0
- package/template/knowledge-base/design-system/components/modals.mdc +24 -0
- package/template/knowledge-base/design-system/components/selects.mdc +39 -0
- package/template/knowledge-base/design-system/components/stepper.mdc +18 -0
- package/template/knowledge-base/design-system/components/tables.mdc +59 -0
- package/template/knowledge-base/design-system/components/tabs.mdc +17 -0
- package/template/knowledge-base/design-system/components.mdc +91 -0
- package/template/knowledge-base/design-system/tokens.mdc +24 -0
- package/template/knowledge-base/examples/bad/README.md +8 -0
- package/template/knowledge-base/examples/good/README.md +13 -0
- package/template/knowledge-base/metadata/catalog.yaml +245 -0
- package/template/knowledge-base/patterns/components/reuse-existing.mdc +26 -0
- package/template/knowledge-base/patterns/data-fetching/local-data.mdc +20 -0
- package/template/knowledge-base/patterns/layouts/app-shell.mdc +20 -0
- package/template/knowledge-base/patterns/pages/data-table-page.mdc +31 -0
- package/template/knowledge-base/patterns/pages/workflow-page.mdc +27 -0
- package/template/knowledge-base/rules/accessibility/responsive.mdc +31 -0
- package/template/knowledge-base/rules/architecture/layout.mdc +52 -0
- package/template/knowledge-base/rules/architecture/single-screen.mdc +62 -0
- package/template/knowledge-base/rules/code-quality/jsx.mdc +19 -0
- package/template/knowledge-base/rules/global/naming.mdc +12 -0
- package/template/knowledge-base/rules/global/technology.mdc +19 -0
- package/template/knowledge-base/rules/global/ui-copy.mdc +20 -0
- package/template/knowledge-base/rules/performance/client.mdc +20 -0
- package/template/knowledge-base/rules/ui/information-density.mdc +36 -0
- package/template/knowledge-base/rules/ui/interaction.mdc +47 -0
- package/template/knowledge-base/rules/ui/simple-ui.mdc +58 -0
- package/template/knowledge-base/validation/accessibility.mdc +13 -0
- package/template/knowledge-base/validation/architecture.mdc +10 -0
- package/template/knowledge-base/validation/ast-grep/do-what-brooooooklyn-said.yml +15 -0
- package/template/knowledge-base/validation/ast-grep/no-nested-links.yml +12 -0
- package/template/knowledge-base/validation/ast-grep/rewrite-svg-attribute.yml +19 -0
- package/template/knowledge-base/validation/code-quality.mdc +18 -0
- package/template/knowledge-base/validation/performance.mdc +11 -0
- package/template/knowledge-base/validation/ui.mdc +26 -0
- package/template/next.config.ts +21 -0
- package/template/package-lock.json +6938 -0
- package/template/package.json +30 -0
- package/template/postcss.config.mjs +7 -0
- package/template/public/identity/full_logo_black.svg +27 -0
- package/template/public/identity/full_logo_color.svg +38 -0
- package/template/public/identity/full_logo_white.svg +34 -0
- package/template/public/identity/logo_icon_black.svg +6 -0
- package/template/public/identity/logo_icon_color.svg +13 -0
- package/template/public/identity/logo_icon_white.svg +13 -0
- package/template/public/login-hero.png +0 -0
- package/template/sgconfig.yml +11 -0
- package/template/tsconfig.json +43 -0
package/dist/cli.js
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
4
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
5
|
+
};
|
|
6
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
7
|
+
const fs_1 = __importDefault(require("fs"));
|
|
8
|
+
const path_1 = __importDefault(require("path"));
|
|
9
|
+
const child_process_1 = require("child_process");
|
|
10
|
+
const projectName = process.argv[2];
|
|
11
|
+
if (!projectName) {
|
|
12
|
+
console.error("Usage: npx create-modoock-app <project-name>");
|
|
13
|
+
process.exit(1);
|
|
14
|
+
}
|
|
15
|
+
const templatePath = path_1.default.resolve(__dirname, "../template");
|
|
16
|
+
const projectPath = path_1.default.resolve(process.cwd(), projectName);
|
|
17
|
+
if (fs_1.default.existsSync(projectPath)) {
|
|
18
|
+
console.error(`Error: "${projectName}" already exists.`);
|
|
19
|
+
process.exit(1);
|
|
20
|
+
}
|
|
21
|
+
console.log(`\nCreating ${projectName}...`);
|
|
22
|
+
// Copy template
|
|
23
|
+
fs_1.default.cpSync(templatePath, projectPath, {
|
|
24
|
+
recursive: true,
|
|
25
|
+
});
|
|
26
|
+
// Update package.json
|
|
27
|
+
const packageJsonPath = path_1.default.join(projectPath, "package.json");
|
|
28
|
+
if (fs_1.default.existsSync(packageJsonPath)) {
|
|
29
|
+
const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, "utf-8"));
|
|
30
|
+
packageJson.name = projectName;
|
|
31
|
+
fs_1.default.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
|
|
32
|
+
}
|
|
33
|
+
// Update package-lock.json
|
|
34
|
+
const packageLockPath = path_1.default.join(projectPath, "package-lock.json");
|
|
35
|
+
if (fs_1.default.existsSync(packageLockPath)) {
|
|
36
|
+
const packageLock = JSON.parse(fs_1.default.readFileSync(packageLockPath, "utf-8"));
|
|
37
|
+
packageLock.name = projectName;
|
|
38
|
+
if (packageLock.packages?.[""]) {
|
|
39
|
+
packageLock.packages[""].name = projectName;
|
|
40
|
+
}
|
|
41
|
+
fs_1.default.writeFileSync(packageLockPath, JSON.stringify(packageLock, null, 2) + "\n");
|
|
42
|
+
}
|
|
43
|
+
// Install dependencies
|
|
44
|
+
console.log("\nInstalling dependencies...\n");
|
|
45
|
+
(0, child_process_1.execSync)("npm ci", {
|
|
46
|
+
cwd: projectPath,
|
|
47
|
+
stdio: "inherit",
|
|
48
|
+
});
|
|
49
|
+
console.log(`\n✓ ${projectName} created successfully!`);
|
|
50
|
+
console.log(`\nNext steps:`);
|
|
51
|
+
console.log(` cd ${projectName}`);
|
|
52
|
+
console.log(` npm run dev\n`);
|
package/package.json
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "create-modoock-app",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Project starter and boilerplate generator",
|
|
5
|
+
"main": "dist/cli.js",
|
|
6
|
+
"bin": {
|
|
7
|
+
"create-modoock-app": "dist/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"dist",
|
|
11
|
+
"template"
|
|
12
|
+
],
|
|
13
|
+
"scripts": {
|
|
14
|
+
"build": "tsc"
|
|
15
|
+
},
|
|
16
|
+
"devDependencies": {
|
|
17
|
+
"@types/node": "^24.0.0",
|
|
18
|
+
"typescript": "^5.0.0"
|
|
19
|
+
},
|
|
20
|
+
"license": "MIT"
|
|
21
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: code-reviewer
|
|
3
|
+
description: Reviews a diff or set of changed files for correctness and knowledge-base violations. Use after changes and before considering the work done. Read-only — it reports, it does not edit.
|
|
4
|
+
model: inherit
|
|
5
|
+
readonly: true
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are a meticulous, blunt code reviewer. Lead with the findings, then give a concrete, prioritized action plan. Do not edit files.
|
|
9
|
+
|
|
10
|
+
## How to review
|
|
11
|
+
|
|
12
|
+
1. Identify what actually changed. Review only that plus the code it directly touches.
|
|
13
|
+
2. Open `knowledge-base/validation/` and check the files that match the change (`ui.mdc`, `accessibility.mdc`, `architecture.mdc`, `performance.mdc`, `code-quality.mdc`). Do not copy those checks into this file.
|
|
14
|
+
3. For each issue, decide whether it is the root cause or a symptom. Flag the class, not only the instance.
|
|
15
|
+
|
|
16
|
+
## Severity ladder
|
|
17
|
+
|
|
18
|
+
- **P0 — Security & data loss.** Exposed secrets, destructive commands, data corruption. Never recommend an auto-fix for a security finding — it needs human review.
|
|
19
|
+
- **P1 — Correctness / knowledge-base.** Wrong behavior, or a fail listed in `knowledge-base/validation/`.
|
|
20
|
+
- **P2 — Maintainability.** Duplicated blocks, dead code, unclear naming, unnecessary wrappers.
|
|
21
|
+
|
|
22
|
+
## Report format
|
|
23
|
+
|
|
24
|
+
For each finding: `file:line — [P0/P1/P2] — what's wrong and the concrete fix.`
|
|
25
|
+
Then a plan grouped as **Fix today / This week / Later**. If a severity has no real finding, say so. Do not invent filler.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Cursor pointer to AGENTS.md (canonical router)
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Follow `AGENTS.md`. If it is already in this conversation, do not re-open it.
|
|
7
|
+
`.cursor/rules/honey.mdc` is required; if it is already in this conversation, do not re-open it.
|
|
8
|
+
Do not treat `CLAUDE.md` as a second rulebook.
|
|
9
|
+
Then `knowledge-base/metadata/catalog.yaml`.
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Honey — write less code and say less about it. A reflexive minimal-code (YAGNI/stdlib-first) and terse-prose discipline that cuts token cost while keeping code, commands, and safety-critical paths exact.
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Honey (I Shrunk the AI)
|
|
7
|
+
|
|
8
|
+
Three levers cut what an LLM emits. Volume is cost; most volume is waste.
|
|
9
|
+
|
|
10
|
+
1. **Less code** — most code needn't exist. The cheapest line is the one never written.
|
|
11
|
+
2. **Less prose** — most words around code are filler. The reader wants the answer.
|
|
12
|
+
3. **Denser agent-to-agent messages** — when the reader is another agent, use the
|
|
13
|
+
most token-efficient wire format it parses losslessly.
|
|
14
|
+
|
|
15
|
+
Levers 1–2 apply to everything you emit; Lever 3 only when output feeds another agent.
|
|
16
|
+
|
|
17
|
+
**Apply reflexively, as a writing style — not a problem to analyze.** Don't
|
|
18
|
+
deliberate which mode or rung applies; don't spend reasoning tokens on the skill
|
|
19
|
+
itself. Reasoning is for the user's task. (On reasoning models, "think about how
|
|
20
|
+
to comply" inflates the bill — defeating the purpose.)
|
|
21
|
+
|
|
22
|
+
## Intensity
|
|
23
|
+
|
|
24
|
+
Pick by keyword on the first cue; don't weigh it. `full` is the default and the
|
|
25
|
+
fallback when unsure. User can pin (`honey ultra`). Mixed signals ("write X and
|
|
26
|
+
explain it") → keep the explanation.
|
|
27
|
+
|
|
28
|
+
| Mode | Trigger | Prose |
|
|
29
|
+
|------|---------|-------|
|
|
30
|
+
| **lite** | "explain", "how/why", "should I", design/tradeoff Qs | keep — the explanation *is* the deliverable |
|
|
31
|
+
| **full** | "write/add/fix/implement/build", or unsure | terse, fragments over paragraphs |
|
|
32
|
+
| **ultra** | "just/quick/one-liner", trivial | answer-only, near-zero |
|
|
33
|
+
|
|
34
|
+
Lever 1 (code ladder) never turns off, in any mode. **ultra** still keeps one line
|
|
35
|
+
naming the main edge case (e.g. "raises `KeyError` on a missing key — use `.get`")
|
|
36
|
+
— answer-only ≠ edge-case-blind.
|
|
37
|
+
|
|
38
|
+
**Step up a mode, not down, when terseness would drop correctness** — a subtle bug,
|
|
39
|
+
a tradeoff, a correctness argument, or a learner who needs the explanation. Keep
|
|
40
|
+
Lever 1, ease Lever 2. Brevity that forces a follow-up round-trip costs more than it saved.
|
|
41
|
+
|
|
42
|
+
## Lever 1 — minimum code that needs to exist
|
|
43
|
+
|
|
44
|
+
Understand the problem *before* you climb — read the task and the code it touches,
|
|
45
|
+
trace the real flow end to end, then pick a rung. A small diff in the wrong place
|
|
46
|
+
isn't lazy, it's a second bug.
|
|
47
|
+
|
|
48
|
+
Then walk the ladder; stop at the first rung that works:
|
|
49
|
+
|
|
50
|
+
1. **Needs to exist?** Best move is no code — config, an existing call site, or
|
|
51
|
+
deleting the need. Say so instead of building.
|
|
52
|
+
2. **Already in this repo?** Search before you write: the helper, util, validator,
|
|
53
|
+
or pattern is often already here. Reusing it is the cheapest rung there is —
|
|
54
|
+
zero new lines, and it stays consistent with the codebase.
|
|
55
|
+
3. **Stdlib** — don't hand-roll `itertools`/`pathlib`/`collections`/`datetime`.
|
|
56
|
+
4. **Language native** — operator/comprehension/idiom over a helper; dict lookup over an if-ladder.
|
|
57
|
+
5. **Installed dependency** — use what the project has; don't add one for four
|
|
58
|
+
lines, don't reimplement one you already have.
|
|
59
|
+
6. **One line** before a block.
|
|
60
|
+
7. **Minimum block** — no speculative params, no "might need it later" branches, no single-caller abstraction.
|
|
61
|
+
|
|
62
|
+
A Design System primitive (generic UI a second page would copy) is not a
|
|
63
|
+
single-caller abstraction. Ask per AGENTS.md human validation; if yes, put it
|
|
64
|
+
in `components/`. Keeping it page-local to skip the question is waste, not Honey.
|
|
65
|
+
|
|
66
|
+
Prefer editing what exists over adding; a new function/file/class/layer must earn
|
|
67
|
+
its place. Speculative generality is the costliest agent habit — code for imagined
|
|
68
|
+
requirements is pure overhead, and the requirement usually never arrives.
|
|
69
|
+
|
|
70
|
+
**Fix the cause, not the symptom — it's also the smaller diff.** A bug report names
|
|
71
|
+
a symptom. Grep the callers of the function you're about to touch: one guard in the
|
|
72
|
+
shared function is fewer lines than one guard per call site, *and* it fixes the
|
|
73
|
+
sibling callers the ticket didn't mention. Patching only the named path leaves the
|
|
74
|
+
bug alive and the diff bigger.
|
|
75
|
+
|
|
76
|
+
**Mark deliberate shortcuts.** A simplification with a known ceiling (global lock,
|
|
77
|
+
O(n²) scan, naive heuristic) gets a `honey:` comment naming the ceiling *and* the
|
|
78
|
+
trigger to revisit — `honey: O(n²), fine under ~1k rows; index if it grows`. Without
|
|
79
|
+
a trigger, "later" means never. `honey-debt` harvests these into a ledger.
|
|
80
|
+
|
|
81
|
+
**Bulk is generated, never typed.** Asked for N similar files/cases/fixtures/locales:
|
|
82
|
+
write the small generator and run it — template once, not the bulk. Skip when the
|
|
83
|
+
generator would outweigh what it generates.
|
|
84
|
+
|
|
85
|
+
### Never cut (lazy ≠ broken)
|
|
86
|
+
|
|
87
|
+
Minimal code missing its safety-critical parts isn't minimal — it's unfinished.
|
|
88
|
+
Never simplify away:
|
|
89
|
+
|
|
90
|
+
- **Input validation** at trust boundaries (user input, network, files, env).
|
|
91
|
+
- **Error handling** that prevents data loss or corruption.
|
|
92
|
+
- **Security** — auth checks, escaping, secrets handling.
|
|
93
|
+
- **Accessibility basics** — labels, roles, keyboard paths.
|
|
94
|
+
- **Visual/UX design when the deliverable is user-facing** — for landing pages,
|
|
95
|
+
marketing sites, and UI components, polish (layout depth, hero composition,
|
|
96
|
+
motion, responsive richness, on-brand visual hierarchy) *is* the requirement,
|
|
97
|
+
not "speculative." Markup that looks unfinished isn't minimal. The ladder still
|
|
98
|
+
trims *structure* (no dead markup, no unused framework), never how it looks.
|
|
99
|
+
- **Anything the user explicitly asked for.**
|
|
100
|
+
- **The ask for a Design System primitive** — do not skip it to write less code.
|
|
101
|
+
|
|
102
|
+
Leave one runnable check (test/assert/invocation) behind for non-trivial logic.
|
|
103
|
+
"Lazy" = no wasted code, not no proof it works.
|
|
104
|
+
|
|
105
|
+
## Lever 2 — say less about it
|
|
106
|
+
|
|
107
|
+
Fewest words that stay clear. Cut the scaffolding:
|
|
108
|
+
|
|
109
|
+
- **Drop wind-up/wind-down** — no "Great question!", no "hope this helps!", no
|
|
110
|
+
restating the prompt, no announcing what you're about to do.
|
|
111
|
+
- **Drop hedging** — "use X", not "you might possibly consider perhaps X". State real uncertainty once, briefly.
|
|
112
|
+
- **Fragments and lists** over paragraphs when they carry the same info faster.
|
|
113
|
+
- **Don't narrate readable code** — explain the *why* and the non-obvious, skip the *what*.
|
|
114
|
+
- **Answer first**; context only if load-bearing.
|
|
115
|
+
|
|
116
|
+
**Keep exact — never compress** (precision, not prose):
|
|
117
|
+
|
|
118
|
+
- **Code blocks** — verbatim, runnable; never "..." shorthand the user must expand.
|
|
119
|
+
- **Identifiers, paths, commands, versions, error messages** — exact. "the auth middleware" ≠ `requireAuth()`.
|
|
120
|
+
- **Anything to copy, paste, or run.**
|
|
121
|
+
|
|
122
|
+
**Don't abbreviate prose words, at any intensity.** `cfg` / `impl` / `req` / `res` /
|
|
123
|
+
`fn` / `auth` / `env` cost the *same* number of tokens as `config` / `implementation`
|
|
124
|
+
/ `request` / `response` / `function` / `authentication` / `environment` — measured, one
|
|
125
|
+
token each, on both the Claude and o200k tokenizers. Same for `→` versus a comma. You
|
|
126
|
+
pay nothing and charge the reader to decode. Terseness comes from **dropping words**,
|
|
127
|
+
never from shortening them. Well-known acronyms already in the domain (API, HTTP, DB,
|
|
128
|
+
URL) are fine; inventing new ones is not.
|
|
129
|
+
|
|
130
|
+
If compressing makes the reader work to recover the meaning, you moved cost, not removed it. Stop there.
|
|
131
|
+
|
|
132
|
+
## Lever 3 — compress agent-to-agent messages
|
|
133
|
+
|
|
134
|
+
When the reader is **another agent, not a human** (subagent return, orchestrator↔worker
|
|
135
|
+
handoff, LLM-read payload), drop human formatting for the densest format the receiver
|
|
136
|
+
parses losslessly. Fires **only** here — never emit a wire format as a user-facing answer.
|
|
137
|
+
|
|
138
|
+
**These beat any format choice** — measured equal across formats, frontier models included:
|
|
139
|
+
|
|
140
|
+
- **Compact, never pretty.** Minified over indented JSON — pretty-printing is ~+55% tokens for nothing.
|
|
141
|
+
- **Address records by stable key, never by position.** "the finding with `id` X", not "the 37th" — ordinal lookup fails in every format, frontier models too.
|
|
142
|
+
- **Aggregate in code, never make the model count rows.** "how many match X" scores ~0% even on frontier models. Same class: sort, dedupe, diff, date math — any deterministic transform runs in the program; pass the model the result.
|
|
143
|
+
- **Number rows only if positional access is unavoidable** — an explicit `n` field restores it at ~+8% tokens.
|
|
144
|
+
- **Long pipes: legend once, ids after.** Paths/names recurring across a multi-message pipe get short ids in a one-time legend (`F1=src/pipeline/export.ts`); reference ids thereafter. Loses on short pipes — two mentions don't pay for a legend.
|
|
145
|
+
|
|
146
|
+
**Then pick the format by shape** (token rank is secondary — comprehension ties for real lookups):
|
|
147
|
+
|
|
148
|
+
- **Default → compressed JSON.** Minified; for a uniform record array go columnar —
|
|
149
|
+
keys once, then value rows (`{"c":["sev","issue"],"r":[["H","token never expires"],…]}`).
|
|
150
|
+
~−25% vs plain JSON, still valid JSON: every model and stdlib parses it, nothing to teach.
|
|
151
|
+
- **Opt-in → ESON** ([spec + primer](https://github.com/Green-PT/honey-eson)), only for
|
|
152
|
+
high-volume, **cached**, record-array-heavy pipes you own end-to-end. Buys a further
|
|
153
|
+
~6–10%, but costs a ~120-token format primer plus the bundled
|
|
154
|
+
`eson` codec, and *loses* below a few messages or on small/scalar payloads:
|
|
155
|
+
```
|
|
156
|
+
!eson/1
|
|
157
|
+
findings[2]{sev,issue}
|
|
158
|
+
H\ttoken never expires
|
|
159
|
+
M\tno rate limiting
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
**Verify on read:** a dense misparse is *silent* — the reader may confabulate. Treat the
|
|
163
|
+
declared count (`[N]`) as a checksum. **Safety carve-out:** auth/money/migrations/deletes/
|
|
164
|
+
irreversible handoffs stay explicit and schema-validated.
|
|
165
|
+
|
|
166
|
+
### Lever 3b — request less *input*
|
|
167
|
+
|
|
168
|
+
Levers 1–3 cut what you emit; this cuts what you pull in. The cheapest input token is the
|
|
169
|
+
one that never enters context. You can't out-compress a token you already paid for — so ask
|
|
170
|
+
for less, don't crush what you fetched.
|
|
171
|
+
|
|
172
|
+
- **Locate before reading.** `Grep`/`Glob` to the lines you need; `Read` with `offset`/`limit`
|
|
173
|
+
for one function — don't pull a whole 800-line file to answer about a 10-line body.
|
|
174
|
+
- **Outline first, bodies on demand.** Unfamiliar big file: `Grep` its declaration
|
|
175
|
+
lines (`def`/`class`/`function`/`export`) for a skeleton, then `Read` only the bodies
|
|
176
|
+
you need — the outline answers most where/what questions without paying for the file.
|
|
177
|
+
- **Don't re-read or re-paste what's already in context** — reference it. The harness already
|
|
178
|
+
tracks file state; re-Reading an unchanged file just re-pays for it.
|
|
179
|
+
- **Offload bulk you must keep but mostly skim.** `cmd | eson stash` → a `<<honey:HASH>>` handle;
|
|
180
|
+
`eson retrieve <hash>` restores it verbatim when a detail is needed. (Lossy-skim variant for
|
|
181
|
+
huge uniform arrays: `eson crush`.) Reference the handle instead of pasting the blob again.
|
|
182
|
+
- **Subagents: aggregate before returning** — N matching rows + the count, not all rows. Their
|
|
183
|
+
return is itself a Lever-3 handoff: columnar/minified.
|
|
184
|
+
- **ultra only — image-rendered reads (PX).** At ultra intensity, read big dense *read-only*
|
|
185
|
+
bulk (≥~6k chars you'll skim but never edit or byte-copy) as PNG pages:
|
|
186
|
+
`npx pxpipe-proxy export --json --out <tmp> <target>`, then `Read` the `page-*.png` **and**
|
|
187
|
+
`factsheet.txt` (~5× cheaper; Fable-class readers only). Lossy on exact strings — `Grep`-verify
|
|
188
|
+
anything exact before acting on it, and never PX a file you will `Edit`. Guards: `honey-px`.
|
|
189
|
+
|
|
190
|
+
Carve-outs inherit Lever 3: never elide auth/secrets/migrations/deletes or anything the user
|
|
191
|
+
asked for, and never drop a payload about to be written back verbatim.
|
|
192
|
+
|
|
193
|
+
## Loops — cost compounds per tick
|
|
194
|
+
|
|
195
|
+
A `/loop` multiplies per-tick cost by tick count, so waste compounds. The levers
|
|
196
|
+
above still apply each tick; loops add two leaks the single-shot levers don't cover
|
|
197
|
+
— re-paying for context every wake-up, and re-doing work that didn't change:
|
|
198
|
+
|
|
199
|
+
- **Pace to the prompt cache (5-min TTL).** Interval `<270s` stays warm; `≥1200s`
|
|
200
|
+
amortizes one cache miss over a long idle wait. **Never ~300s** — it pays the miss
|
|
201
|
+
without amortizing. Idle default **1200–1800s**.
|
|
202
|
+
- **Don't poll harness-tracked work.** Background `Bash`/`Agent`/`Workflow` re-invoke
|
|
203
|
+
you on completion; set a long fallback heartbeat and let the notification drive.
|
|
204
|
+
Poll only external state the harness can't see (CI, deploy, remote queue).
|
|
205
|
+
- **Short-circuit no-change ticks.** Cheap check first (hash/timestamp/`git rev-parse`);
|
|
206
|
+
unchanged → one status line, reschedule, skip the redo. Per-tick output defaults to
|
|
207
|
+
**ultra**; step up only on the tick that needs the user.
|
|
208
|
+
- **Define done, then stop** — omit the reschedule when the exit condition is met.
|
|
209
|
+
|
|
210
|
+
Full version: the `honey-loop` skill.
|
|
211
|
+
|
|
212
|
+
## Examples
|
|
213
|
+
|
|
214
|
+
Read a JSON file's key:
|
|
215
|
+
> ```python
|
|
216
|
+
> import json
|
|
217
|
+
> def read_json_value(path, key):
|
|
218
|
+
> return json.load(open(path))[key]
|
|
219
|
+
> ```
|
|
220
|
+
> Raises `KeyError`/`FileNotFoundError` — fine for a trusted path. `.get(key, default)` if optional.
|
|
221
|
+
|
|
222
|
+
Stdlib already does it → no code:
|
|
223
|
+
> `copy.deepcopy(d)` — no utility needed.
|
|
224
|
+
|
|
225
|
+
Precision kept, prose gone:
|
|
226
|
+
> `pytest tests/ -q` · `-k <name>` runs one test, `-x` stops on first failure.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: UI load — same procedure as AGENTS.md (all agents)
|
|
3
|
+
globs: app/**/*.tsx,components/**/*.tsx
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# UI context
|
|
8
|
+
|
|
9
|
+
Same load as `AGENTS.md`. Cursor injects this reminder; it is not a second rulebook.
|
|
10
|
+
|
|
11
|
+
1. Open `knowledge-base/metadata/catalog.yaml`.
|
|
12
|
+
2. Open every `path` with `load: ui`.
|
|
13
|
+
3. Open any other `path` whose `description` matches the need, then that entry's `open:`.
|
|
14
|
+
4. What exists: `components/*/index.ts`. Open a component `.mdc` only if the catalog lists it.
|
|
15
|
+
|
|
16
|
+
List page → `data-table-page` (then its `open:`). Workflow / dossier → `workflow-page` (then its `open:`).
|
|
17
|
+
|
|
18
|
+
Do not open `knowledge-base/validation/` until verification.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: debug
|
|
3
|
+
description: A systematic debugging procedure. Use when stuck on a bug, a regression, or a failure whose cause is not obvious.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Debug
|
|
7
|
+
|
|
8
|
+
A loop for finding root causes instead of guessing. Use this when the obvious fix has not worked.
|
|
9
|
+
|
|
10
|
+
This is a procedure. UI constraints stay in `knowledge-base/`. Do not duplicate them here.
|
|
11
|
+
|
|
12
|
+
## Triage first
|
|
13
|
+
|
|
14
|
+
- Is the error message clear, or is it masking the real failure?
|
|
15
|
+
- Can I reproduce it consistently? If not, that is the first problem to solve.
|
|
16
|
+
- Did it work before? What changed recently?
|
|
17
|
+
- Is it environment-specific?
|
|
18
|
+
|
|
19
|
+
## The loop
|
|
20
|
+
|
|
21
|
+
1. **Reproduce** — smallest reliable repro before changing anything.
|
|
22
|
+
2. **Isolate** — shrink to the smallest failing case.
|
|
23
|
+
3. **Diagnose** — find the root cause, not the symptom.
|
|
24
|
+
4. **Fix** — smallest change that addresses the root cause. Change one thing at a time.
|
|
25
|
+
5. **Verify** — reproduce the original failure and confirm it is gone. Run `npm run lint`. If the change is UI, also check `knowledge-base/validation/`.
|
|
26
|
+
|
|
27
|
+
## Time-box
|
|
28
|
+
|
|
29
|
+
About 5 minutes on the obvious checks, then about 15 minutes of systematic isolation. Then step back, ask for help, or write down what has been ruled out.
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Development instructions
|
|
2
|
+
|
|
3
|
+
This file is the canonical router. Product constraints live in `knowledge-base/`. Do not copy them here. Only open the files that match the task.
|
|
4
|
+
|
|
5
|
+
`CLAUDE.md` imports this file (`@AGENTS.md`) and `.cursor/rules/honey.mdc`. `.cursor/rules/agents.mdc` is a Cursor pointer — do not copy this procedure there. A Next.js footer may be appended here by `next dev`; do not copy it.
|
|
6
|
+
|
|
7
|
+
## Context load
|
|
8
|
+
|
|
9
|
+
| Layer | When | What |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| Always | every turn | this file, `.cursor/rules/honey.mdc` |
|
|
12
|
+
| UI files | `app/**` or `components/**` | every catalog `path` with `load: ui`, then `components/*/index.ts` |
|
|
13
|
+
| On demand | `description` matches the need | that `path`, then its `open:` |
|
|
14
|
+
| After coding | verification | `knowledge-base/validation/` for the change type |
|
|
15
|
+
|
|
16
|
+
Do not load the whole knowledge-base. `load: ui` is an agent hint in `catalog.yaml`, not Cursor injection.
|
|
17
|
+
|
|
18
|
+
`.cursor/rules/honey.mdc` is required every turn for every agent (one file, do not copy, do not split). If it is already in context, do not re-open it. If it is not, open it once.
|
|
19
|
+
|
|
20
|
+
## Knowledge Base layout
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
knowledge-base/
|
|
24
|
+
├── rules/ # constraints (global, architecture, ui, accessibility, …)
|
|
25
|
+
├── patterns/ # how this repo solves a class of problem
|
|
26
|
+
├── examples/ # good/ and bad/
|
|
27
|
+
├── design-system/ # tokens + component constraints
|
|
28
|
+
├── validation/ # how to detect a violation
|
|
29
|
+
└── metadata/ # catalog.yaml — the need → path index
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Which file to open
|
|
33
|
+
|
|
34
|
+
Open `knowledge-base/metadata/catalog.yaml`. UI edit: every `load: ui` `path`. Then any `description` that matches — exact `path` (no `.mdc` guess). After each catalog `path`, also open that entry's `open:`. What exists: `components/*/index.ts` (no `.mdc` required).
|
|
35
|
+
|
|
36
|
+
If no file covers the need, follow **New rules**. Missing `.mdc` for an existing export is not a gap.
|
|
37
|
+
|
|
38
|
+
## Before coding
|
|
39
|
+
|
|
40
|
+
- Inspect the existing code. Reproduce a failure before fixing it. Change one thing at a time, then verify.
|
|
41
|
+
- Open the catalog paths that match the task and apply those files. Nothing else.
|
|
42
|
+
- Reuse and page composition: `knowledge-base/design-system/components.mdc`. Public APIs: `components/*/index.ts`.
|
|
43
|
+
- Do not invent rules. Do not add a dependency, Design System component, token, or architecture change until the developer has answered yes.
|
|
44
|
+
- If a decision is not covered by the request or an existing rule, stop that part and ask. Do not assume preferences.
|
|
45
|
+
|
|
46
|
+
## Mandatory human validation
|
|
47
|
+
|
|
48
|
+
Human validation is a question to the developer. If they say yes, complete that part. If they say no, leave it out.
|
|
49
|
+
|
|
50
|
+
- Ask before any modification not covered by the existing rules, the prompt, or the provided context.
|
|
51
|
+
- If several solutions are possible and none is imposed, present the options and wait.
|
|
52
|
+
- Required questions (do not skip): a new Design System component (`components/ui/`, `components/layout/`, `components/shared/`), a new dependency, a new token or color, a knowledge-base rule, or a global architecture change. A page that follows an existing pattern does not need a question.
|
|
53
|
+
- Question format (one block, then wait):
|
|
54
|
+
- **What:** ComponentName
|
|
55
|
+
- **Where:** `components/ui` | `components/layout` | `components/shared`
|
|
56
|
+
- **Why:** existing `index.ts` exports that do not fit
|
|
57
|
+
- **Reuse:** one sentence (which other page would copy this JSX)
|
|
58
|
+
- Do not replace the question with a weaker workaround (for example keeping a reusable UI piece in the page file so you do not have to ask).
|
|
59
|
+
- After yes: implement in the same turn (create the component in `components/`, export it, wire the page). After no: stop that part.
|
|
60
|
+
- Distinguish what is requested, what the rules cover, and what is a new decision. Do not extend the scope. Suspend the uncovered part until the developer confirms.
|
|
61
|
+
|
|
62
|
+
## New rules
|
|
63
|
+
|
|
64
|
+
When a recurring case is not covered:
|
|
65
|
+
|
|
66
|
+
- Propose a new rule, why it is recurring, and where it belongs (`knowledge-base/` or `components/`).
|
|
67
|
+
- Do not add or modify a rule until the developer says yes. Then add it.
|
|
68
|
+
|
|
69
|
+
## Verification
|
|
70
|
+
|
|
71
|
+
Layers (do not mix): `npm run lint` = ESLint. `npm run typecheck` = TypeScript, including JSX props on the public type. `npm run sg:scan` = structural facts the scanner can prove — keep it strict and dumb. `knowledge-base/validation/` = Design System / UX / architecture. The agent = context and judgment.
|
|
72
|
+
|
|
73
|
+
After a modification:
|
|
74
|
+
|
|
75
|
+
- Check the change against `knowledge-base/validation/` for the files that match. For a read-only pass on the diff, use `.cursor/agents/code-reviewer.md`.
|
|
76
|
+
- Check that existing features are not unnecessarily affected.
|
|
77
|
+
- If a new component has been created, export it from the folder `index.ts` (`components/ui/`, `components/layout/` or `components/shared/`).
|
|
78
|
+
- Run `npm run lint`, `npm run typecheck` and `npm run sg:scan` and fix any **error** before finishing. `typecheck` proves JSX props exist on the component type. Do not apply catalog auto-fixes (`ast-grep scan -U`) and do not rewrite existing app JSX to silence catalog warnings.
|
|
79
|
+
- Report any problems or hypotheses that require a decision from the developer.
|
|
80
|
+
|
|
81
|
+
<!-- BEGIN:nextjs-agent-rules -->
|
|
82
|
+
|
|
83
|
+
# This is NOT the Next.js you know
|
|
84
|
+
|
|
85
|
+
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
|
|
86
|
+
|
|
87
|
+
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
|
|
88
|
+
|
|
89
|
+
<!-- END:nextjs-agent-rules -->
|