@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 +105 -16
- package/agents/look-over.md +13 -11
- package/agents/task-breaker.md +44 -17
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -1,32 +1,107 @@
|
|
|
1
|
-
# @
|
|
1
|
+
# @revit-ai
|
|
2
2
|
|
|
3
|
-
Shared
|
|
3
|
+
Shared Cursor rules, agent definitions, and context templates for any project.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
Version: 0.1.0. Requires Node 24 or newer.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
8
10
|
|
|
9
11
|
```bash
|
|
10
|
-
npm install @
|
|
12
|
+
npm install @revit-dev/ai
|
|
11
13
|
# or
|
|
12
|
-
pnpm add @
|
|
14
|
+
pnpm add @revit-dev/ai
|
|
13
15
|
```
|
|
14
16
|
|
|
15
|
-
Then
|
|
17
|
+
Then run the installer:
|
|
16
18
|
|
|
17
19
|
```bash
|
|
18
20
|
npx revit-ai
|
|
19
21
|
```
|
|
20
22
|
|
|
21
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
package/agents/look-over.md
CHANGED
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
# look-over
|
|
2
2
|
|
|
3
|
-
Fast
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
24
|
-
-
|
|
25
|
-
- A
|
|
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,
|
|
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:
|
|
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
|
|
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
|
|
64
|
+
Next step: rename `tmp` to `postSlug` at `src/lib/post.ts:12`, then stage.
|
package/agents/task-breaker.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
37
|
-
3. Expand
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
-
|
|
44
|
-
-
|
|
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:
|
|
65
|
+
Input: expand task 1 in `.documentation/challenge-practice-db-routes.md` (random mutant endpoint).
|
|
53
66
|
|
|
54
|
-
Verdict:
|
|
67
|
+
Verdict: Task 1 expanded into 11 checkbox steps under Task 1 in that doc.
|
|
55
68
|
|
|
56
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
},
|