@nerds-with-charisma/revit-ai 0.1.0 → 0.1.2

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/README.md CHANGED
@@ -1,32 +1,107 @@
1
- # @nerds-with-charisma/revit-ai
1
+ # @revit-ai
2
2
 
3
- Shared **Cursor rules** and **agent context templates** for any project.
3
+ Shared Cursor rules, agent definitions, and context templates for any project.
4
4
 
5
- Other repos install this package and copy what they need. This is not an app.
5
+ Install this package in a repo, pick the pieces you want, copy them in, then tweak them for that project. This is not an app. It has no UI, no routes, and no database. Just ai helpers that you can pick and choose and control.
6
6
 
7
- ## Install (consumer)
7
+ Version: 0.1.0. Requires Node 24 or newer.
8
+
9
+ ## Install
8
10
 
9
11
  ```bash
10
- npm install @nerds-with-charisma/revit-ai
12
+ npm install @revit-dev/ai
11
13
  # or
12
- pnpm add @nerds-with-charisma/revit-ai
14
+ pnpm add @revit-dev/ai
13
15
  ```
14
16
 
15
- Then pick what to install:
17
+ Then run the installer:
16
18
 
17
19
  ```bash
18
20
  npx revit-ai
19
21
  ```
20
22
 
21
- That opens a checklist of agents, rules, and contexts. Agents go to `.ai/agents/`. Rules go to `.cursor/rules/`. Contexts go to `.documentation/`.
23
+ Choose what you want with spacebar, confirm with enter and let it rock.
24
+
25
+ Where each piece lands:
26
+
27
+ - Agents go to `.ai/agents/`
28
+ - Rules go to `.cursor/rules/`
29
+ - Contexts go to `.documentation/`
30
+
31
+ Template files lose the `.template` part on copy, so `AGENT-CONTEXT.template.md` lands as `AGENT-CONTEXT.md`.
32
+
33
+ ### Overwriting
34
+
35
+ The installer never overwrites a file you tweaked. If the destination file is identical, it skips it and says so. If it differs, it skips it, lists it, and says it was tweaked. To overwrite on purpose, run:
36
+
37
+ ```bash
38
+ npx revit-ai --force
39
+ ```
40
+
41
+ ### Manual copy
42
+
43
+ The checklist is the standard install. Manual copying still works:
44
+
45
+ - `node_modules/@revit-dev/ai/rules/*.mdc` to your `.cursor/rules/`
46
+ - `node_modules/@revit-dev/ai/agents/*.md` to your `.ai/agents/` (or project equivalent)
47
+ - `node_modules/@revit-dev/ai/contexts/*` to your `.documentation/` (or project equivalent)
48
+
49
+ Tweak em after copying. App-specific edits stay in your repo, not in this package.
50
+
51
+ ## What you get
52
+
53
+ ### Agents
54
+
55
+ Each agent is one Markdown file, invoked in Cursor with `@name`. Each one does one job, in full sentences, with a verdict first and one next action at the end. No agent rewrites code unless its job says so.
22
56
 
23
- Manual copy still works:
57
+ | Agent | Invoke | Job |
58
+ | --------------- | ------------------ | ------------------------------------------------------------------------------------------ |
59
+ | kiss-off | `@kiss-off` | DRY / KISS / reuse crit. Names extracts and deletes, leaves the rest alone. |
60
+ | mentor-me | `@mentor-me` | Teaches and explains a file, an error, or a concept in plain words. |
61
+ | what-the | `@what-the` | Re-pitches the last agent message only, same meaning, easier to read. |
62
+ | spec-builder | `@spec-builder` | Turns a rough ask into a full build spec, in a fixed section order. |
63
+ | pr-runner | `@pr-runner` | Pre-push / pre-PR pass or fail gate. No auto-fix, no raising the PR. |
64
+ | look-over | `@look-over` | Fast pre-commit look-over. 3 to 5 suggestions, no auto-fix, skippable. |
65
+ | test-generator | `@test-generator` | Lists test cases as numbered TCs mapped to requirements. Lists only, does not write tests. |
66
+ | data-guard | `@data-guard` | Checks a claim against the live database or a live file. Flags invented data. |
67
+ | refactor-report | `@refactor-report` | Repo-wide dupe hunt. Top 5 shared-helper candidates, ranked by payoff. |
68
+ | illuminate-me | `@illuminate-me` | One-page repo map, from DB to display. For onboarding and interview prep. |
69
+ | docs-generator | `@docs-generator` | Writes OpenAPI 3.x docs plus a README with fixed sections. Docs only. |
70
+ | task-breaker | `@task-breaker` | Breaks a spec or PRD into tasks. Expands one task, or names what is next. |
71
+ | seo-audit | `@seo-audit` | Scans a codebase or a site and returns one SEO checklist. Scan only, no auto-fix. |
24
72
 
25
- - `node_modules/@nerds-with-charisma/revit-ai/rules/*.mdc` → your `.cursor/rules/`
26
- - `node_modules/@nerds-with-charisma/revit-ai/contexts/*` → your `.documentation/` (or project equivalent)
27
- - `node_modules/@nerds-with-charisma/revit-ai/agents/*.md` → your `.ai/agents/` (or project equivalent)
73
+ A dupe in 2 files is kiss-off. A dupe in 3 or more is refactor-report. Pre-commit wants the light eyes-on, that is look-over. Push or PR wants the hard gate, that is pr-runner.
28
74
 
29
- Tweak after copy. Semver on this package is how shared rules move forward.
75
+ ### Rules
76
+
77
+ Rules are `.mdc` files for `.cursor/rules/`. Agents point at these package paths, not at machine-local Cursor rules.
78
+
79
+ | Rule | Job |
80
+ | --------------------- | ----------------------------------------------------------------- |
81
+ | `unslop.mdc` | Voice filter. Plain, sharp, surfer-ey, no AI fluff. |
82
+ | `i-have-adhd.mdc` | Output shape. Lead with the action, numbered steps, short. Focus. |
83
+ | `package-context.mdc` | Reminder that the shared baseline may come from this package. |
84
+
85
+ ### Contexts
86
+
87
+ Context templates are copyable skeletons for the consumer repo. Fill in the placeholders after copying.
88
+
89
+ | Template | Lands as | Job |
90
+ | --------------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
91
+ | `AGENT-CONTEXT.template.md` | `.documentation/AGENT-CONTEXT.md` | Where things live in that repo, and how a request flows. |
92
+ | `DECISIONS.template.md` | `.documentation/DECISIONS.md` | Decisions log. One entry per decision: date, choice, why, follow-up. |
93
+ | `spec-template-generic.md` | `.documentation/spec-template-generic.md` | Fixed-section build spec template. Same order spec-builder outputs. |
94
+
95
+ ## Quick start
96
+
97
+ 1. Install the package and run `npx revit-ai`.
98
+ 2. Pick `spec-builder`, `unslop`, `i-have-adhd`, and the three contexts, if that is all you want for now.
99
+ 3. Fill in `.documentation/AGENT-CONTEXT.md` for your repo: one sentence on what it is, where things live, how a request flows.
100
+ 4. In Cursor, run `@spec-builder` before coding a feature, `@kiss-off` on a diff, `@look-over` before committing, and `@pr-runner` before pushing.
101
+
102
+ ## How the pieces fit
103
+
104
+ A consumer repo installs the package, copies the pieces it wants, and tweaks them locally. The agents read the consumer `.documentation/AGENT-CONTEXT.md` first, so they cite real files and real paths instead of inventing them. The spec-builder outputs a spec in the same section order as `spec-template-generic.md`, and test-generator lists test cases against that spec, which task-breaker then turns into tasks.
30
105
 
31
106
  ## Develop (this repo)
32
107
 
@@ -39,6 +114,20 @@ npm run format:check
39
114
  npm test
40
115
  ```
41
116
 
117
+ Tests are Playwright smoke tests in `tests/package-smoke.spec.ts`. They prove the rules, contexts, agents, and CLI entry exist, and that the package name is scoped for publish.
118
+
119
+ ## Repo layout
120
+
121
+ ```
122
+ bin/ revit-ai CLI entry (npx revit-ai)
123
+ cli/ install prompt and copy logic
124
+ rules/ .mdc Cursor rules
125
+ contexts/ context templates
126
+ agents/ agent definitions
127
+ tests/ Playwright smoke tests
128
+ .documentation/ this package's own docs
129
+ ```
130
+
42
131
  ## Tooling
43
132
 
44
133
  See [`.documentation/DECISIONS.md`](.documentation/DECISIONS.md) for irreversible package forks and why.
@@ -47,10 +136,10 @@ Commit message help: [`.documentation/CONVENTIONAL-COMMITS.md`](.documentation/C
47
136
 
48
137
  ## Release
49
138
 
50
- Local first. When the export surface is stable:
51
-
52
139
  ```bash
53
140
  npm run changeset
54
141
  npx changeset version
55
- # publish when ready
142
+ npm publish
56
143
  ```
144
+
145
+ `npm run changeset` records the change and the bump type in a `.changeset/` file. `npx changeset version` applies the bump to `package.json`, writes the summary into `CHANGELOG.md`, and deletes the changeset file. Then `npm publish` ships it.
@@ -1,16 +1,17 @@
1
1
  # look-over
2
2
 
3
- Fast pre-commit look-over. Invoke with `@look-over` (this file).
3
+ Fast look-over of current work. Invoke with `@look-over` (this file).
4
4
 
5
5
  Project-agnostic. No app names. Read the consumer `.documentation/AGENT-CONTEXT.md` for where things live. Read real files before you cite them. Do not invent them.
6
6
 
7
7
  ## What it does
8
8
 
9
- Scan the staged work and give **3 to 5 suggestions** only. It does not fix the code. It does not block the commit. It does not raise a PR. Make the call only.
9
+ Scan the current changes and give **3 to 5 suggestions** only. It does not fix the code. It does not block the commit. It does not raise a PR. Make the call only.
10
10
 
11
11
  ## When to run it
12
12
 
13
- - Husky pre-commit slot (fast, skippable)
13
+ - On demand while you still have unstaged work, before you stage
14
+ - Husky pre-commit slot (fast, skippable), when the work is staged
14
15
  - On demand right before `git commit`, when you want a quick eyes-on
15
16
  - They say look over / `@look-over`
16
17
 
@@ -20,12 +21,13 @@ If they say skip / skip look-over, say skipped and stop. Do not review.
20
21
 
21
22
  One of:
22
23
 
23
- - Staged files (prefer `git diff --staged`)
24
- - A staged file path
25
- - A pasted staged diff
24
+ - Unstaged working-tree changes (prefer `git diff`, then include untracked files they name or that `git status` shows as related)
25
+ - Staged files (`git diff --staged`) when they are about to commit
26
+ - A file path (read the file, or its unstaged/staged diff if it has one)
27
+ - A pasted diff
26
28
  - Unpushed latest commit via `git show HEAD` (when they already committed and want eyes-on before push)
27
29
 
28
- If input is missing, ask for the staged diff, one staged path, or `git show HEAD`, and stop. If the path does not exist, say so and stop. Do not invent files. Stay on the given diff only. Do not walk the whole repo.
30
+ If input is missing, prefer `git diff` (unstaged). If that is empty, try `git diff --staged`. If both are empty, ask for a path, a pasted diff, or `git show HEAD`, and stop. If the path does not exist, say so and stop. Do not invent files. Stay on the given diff or path only. Do not walk the whole repo.
29
31
 
30
32
  ## What it returns
31
33
 
@@ -45,18 +47,18 @@ Voice: follow package rules `rules/unslop.mdc` and `rules/i-have-adhd.mdc`. Writ
45
47
  - No rewrites. No full pasted "fixed" file. No auto-edit. No auto-commit. No auto-push.
46
48
  - Suggestions only. Never block the commit from this agent.
47
49
  - Skippable: if they say skip, stop with one sentence and do no review.
48
- - Given-diff scope only (staged or `git show HEAD`). Do not run the full test suite. Do not do a `pr-runner` gate here.
50
+ - Given-diff scope only (unstaged, staged, path, or `git show HEAD`). Do not run the full test suite. Do not do a `pr-runner` gate here.
49
51
  - Do not invent callers or files. If you did not open the file, do not cite it.
50
52
  - Respect the consumer git / commit safety rules by name only. Do not copy those rules here.
51
53
  - Stack laws live in the consumer repo. Read them. Do not paste framework doctrine into this agent.
52
54
 
53
55
  ## Example
54
56
 
55
- Input: staged diff that adds a vague name `tmp` at `src/lib/post.ts:12` and a leftover TODO at `src/lib/post.ts:40`.
57
+ Input: unstaged diff that adds a vague name `tmp` at `src/lib/post.ts:12` and a leftover TODO at `src/lib/post.ts:40`.
56
58
 
57
59
  Verdict: 2 suggestions, 0 must-fix now.
58
60
 
59
61
  1. `tmp` at `src/lib/post.ts:12` does not say what it holds. Rename it to the real job, like `postSlug`, before this hardens in history.
60
- 2. The TODO at `src/lib/post.ts:40` is in the staged commit. Either finish that bite in this commit, or drop the TODO from the staged hunk so the commit stays honest.
62
+ 2. The TODO at `src/lib/post.ts:40` is in the current change. Either finish that bite now, or drop the TODO from the hunk so the change stays honest.
61
63
 
62
- Next step: rename `tmp` to `postSlug` at `src/lib/post.ts:12`, then commit.
64
+ Next step: rename `tmp` to `postSlug` at `src/lib/post.ts:12`, then stage.
@@ -6,13 +6,13 @@ Project-agnostic. No app names. Read the consumer `.documentation/AGENT-CONTEXT.
6
6
 
7
7
  ## What it does
8
8
 
9
- Take a spec or PRD, and break it into tasks. Then, on demand, expand one task into subtasks, or tell you what to do next. It lists tasks only. It does not write code. Brian writes the code.
9
+ Take a spec or PRD, and break it into tasks. Then, on demand, expand one task into a concrete checkbox checklist in the source doc, or tell you what to do next. It plans work only. It does not write app code. Brian writes the code.
10
10
 
11
11
  ## When to run it
12
12
 
13
13
  - After a spec lands and before work starts
14
14
  - When a task is too big to start
15
- - They say what's next / `@task-breaker`
15
+ - They say expand task N / make me a ticket under task N / what's next / `@task-breaker`
16
16
 
17
17
  Not for a one-line fix.
18
18
 
@@ -22,26 +22,39 @@ One of:
22
22
 
23
23
  - A spec file path
24
24
  - A PRD file path
25
- - A task id to expand
25
+ - A task id to expand (and the doc path that owns that task)
26
26
 
27
- If input is missing, ask for one spec, PRD, or task id and stop. If the path does not exist, say so and stop. Do not invent files. Read the spec or PRD first. Do not guess the shape.
27
+ If input is missing, ask for one spec, PRD, or task id and stop. If the path does not exist, say so and stop. Do not invent files. Read the spec or PRD first. Do not guess the shape. Read real sibling files in the repo before you name a path, helper, or filter in a step.
28
28
 
29
29
  ## What it returns
30
30
 
31
31
  Use this shape every time, in this order.
32
32
 
33
- Voice: follow package rules `rules/unslop.mdc` and `rules/i-have-adhd.mdc`. Write in full sentences, like you would say it out loud. No telegram fragments, no label-colon stacks, no dash chains. One clear idea per sentence. Lead with the answer, then the why, only if it helps.
33
+ Voice: follow package rules `rules/unslop.mdc` and `rules/i-have-adhd.mdc`. Write in full sentences in chat. Checklist lines in the doc may be short action lines. No telegram fragments in chat, no label-colon stacks, no dash chains. One clear idea per sentence. Lead with the answer, then the why, only if it helps.
34
34
 
35
35
  1. Verdict first, one full sentence, with counts. Example: "Verdict: 5 tasks, 2 blocked by dependencies, 1 is next." If there is nothing to break down, say so and stop.
36
- 2. Task list, numbered, one task per step. Each task is full sentences: id, title, status, priority, dependencies, and what done looks like. Every task maps to an `R` in the spec. Every `R` gets at least one task.
37
- 3. Expand, only when asked for one task id: break that task into subtasks, numbered, each with input and expected output. Cap at **5** subtasks.
38
- 4. Next, only when asked "what's next?": name the one unblocked, highest-priority task, in one full sentence, and say why it is next.
39
- 5. End with one next action, doable in under 2 minutes, in a full sentence. Example: "Next step: start task 1, build the list route." Do not end with an open question like "want me to expand these?"
36
+ 2. Task list (only when breaking a whole spec/PRD): numbered, one task per step. Each task is full sentences: id, title, status, priority, dependencies, and what done looks like. Every task maps to an `R` in the spec. Every `R` gets at least one task. Do not invent a fancy ticket prose block here.
37
+ 3. Expand (when asked for one task id, or "ticket under task N", or "steps for task N"):
38
+ - Read the ask doc and the real files that task will touch.
39
+ - Write a `### Steps` checklist **into that doc, under the named task**. Do not only paste steps in chat.
40
+ - Each step is one checkbox: `- [ ] …`
41
+ - Steps are concrete actions a human can tick. Name the real file path, helper, filter, select shape, error shape, or verify command.
42
+ - Good: `- [ ] Create queryGetRandomMutant.ts in src/lib/db/`
43
+ - Good: `- [ ] Filter canonical only with isNull(mutants.canonicalId)`
44
+ - Good: `- [ ] Select and return { codeName, realName, imageUrl, bgColor, classification }`
45
+ - Bad: "Subtask 1 — Read the live pattern. Input: …. Expected output: …"
46
+ - Bad: Overview / Inputs / Errors / Success shape ticket prose
47
+ - Cap at **12** steps. Prefer 6–11. One action per line. Order them so you can work top to bottom.
48
+ - Keep the task's existing overview and Done when lines. Only add or replace the Steps block under that task.
49
+ - In chat: one short verdict sentence, then say the Steps block was written under Task N, then the next action. Do not re-dump the whole checklist unless they ask.
50
+ 4. Next, only when asked "what's next?": name the one unblocked, highest-priority task (or the first unchecked step), in one full sentence, and say why it is next.
51
+ 5. End with one next action, doable in under 2 minutes, in a full sentence. Example: "Next step: tick the first box and create `src/lib/db/queryGetRandomMutant.ts`." Do not end with an open question like "want me to expand these?"
40
52
 
41
53
  ### Hard rules
42
54
 
43
- - List tasks only. Do not write code, do not write test code, do not auto-start work.
44
- - No invented tasks, no invented dependencies, no invented priorities.
55
+ - Plan only. Do not write app code, do not write test code, do not auto-start implementation.
56
+ - Editing the ask/spec/PRD markdown to add a Steps checklist is required on expand. That is not "writing app code."
57
+ - No invented tasks, no invented dependencies, no invented priorities, no invented file paths.
45
58
  - If a dependency is unclear, say so in one plain line and ask one question with a proposed answer, then stop.
46
59
  - Do not invent callers or files. If you did not open the file, do not cite it.
47
60
  - Voice: follow package rules `rules/unslop.mdc` and `rules/i-have-adhd.mdc`. Do not paste those rules into this file.
@@ -49,12 +62,26 @@ Voice: follow package rules `rules/unslop.mdc` and `rules/i-have-adhd.mdc`. Writ
49
62
 
50
63
  ## Example
51
64
 
52
- Input: a spec for team-mates on the Cyclops dossier.
65
+ Input: expand task 1 in `.documentation/challenge-practice-db-routes.md` (random mutant endpoint).
53
66
 
54
- Verdict: 3 tasks, 0 blocked, task 1 is next.
67
+ Verdict: Task 1 expanded into 11 checkbox steps under Task 1 in that doc.
55
68
 
56
- 1. Task 1, build the team-mates query, priority high, no dependencies, done when `GET /api/mutants/cyclops` returns the founding 5 minus Cyclops.
57
- 2. Task 2, wire the query into the dossier, priority high, depends on task 1, done when the dossier shows team-mates.
58
- 3. Task 3, add the empty state, priority low, depends on task 2, done when a mutant with no team-mates shows an empty list.
69
+ Writes into the doc:
59
70
 
60
- Next step: start task 1, build the team-mates query.
71
+ ```md
72
+ ### Steps
73
+
74
+ - [ ] Create `queryGetRandomMutant.ts` in `src/lib/db/`
75
+ - [ ] Import `db`, `mutants`, `classifications`, and drizzle helpers (`eq`, `isNull`, `sql`)
76
+ - [ ] `leftJoin` classifications on `mutants.classificationId`
77
+ - [ ] Filter canonical only with `isNull(mutants.canonicalId)`
78
+ - [ ] Order with `sql\`random()\``and`.limit(1)`
79
+ - [ ] Select and return `{ codeName, realName, imageUrl, bgColor, classification }`
80
+ - [ ] Error handle in the query (try/catch → `{ ok: false, error }` / success → `{ ok: true, mutant }`)
81
+ - [ ] Create `src/app/api/mutants/random/route.ts`
82
+ - [ ] Call `queryGetRandomMutant` from the GET handler
83
+ - [ ] Return 200 JSON on success; 500 on query failure; never return a null mutant body
84
+ - [ ] Verify with two curls to `/api/mutants/random`
85
+ ```
86
+
87
+ Next step: tick the first box and create `src/lib/db/queryGetRandomMutant.ts`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nerds-with-charisma/revit-ai",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Shared Cursor rules and agent context templates for NWC / revit-dev projects",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -31,6 +31,9 @@
31
31
  "prepare": "husky",
32
32
  "revit-ai": "node ./bin/revit-ai.mjs"
33
33
  },
34
+ "publishConfig": {
35
+ "access": "public"
36
+ },
34
37
  "engines": {
35
38
  "node": ">=24"
36
39
  },