| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 14 | 6 | 0% |
| Commands | 0 | 25 | 0 | 0% |
| Section tags | 1 | 7 | 0 | 13% |
What each file covers
Sections
0 shared · 14 only in A · 6 only in B- − HASH Development Guide
- − Repository Structure and Navigation
- − Common Commands
- − Development
- − Starting Services
- − Testing
- − Linting and Fixing
- − For Specific Packages
- − For TypeScript/JavaScript packages
- − For Rust packages
- − Monorepo wiring for Rust crates
- − Documentation Maintenance
- − Petrinaut user-facing docs
- − Contextual Rules
- + Guidelines for AI Assistants
- + Core Principles
- + Things to avoid
- + Self-Checking Process
- + Effective Rule Application
- + Common Pitfalls to Avoid
Commands
0 shared · 25 only in A · 0 only in B- − turbo run <command> --filter '<package-name>'
- − cargo nextest run --package <package-name>
- − cargo test --package <package-name> --doc
- − cargo clippy --all-features --package <package-name>
- − mise run sync:turborepo
- − yarn dev
- − yarn dev:backend
- − yarn dev:backend:api
- − yarn dev:frontend
- − yarn start
- − yarn start:graph
- − yarn start:backend
- − yarn start:frontend
- − yarn start:worker
- − yarn test:unit
- − yarn test:integration
- − yarn lint
- − yarn lint:tsc
- − yarn lint:eslint
- − yarn lint:format
- − yarn fix:eslint
- − yarn fix:format
- − cargo-hack
- − cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo
- − mise run fix:package-json
Section tags
1 shared · 7 only in A · 0 only in B- − test
- − lint-format
- − architecture
- − types
- − dependencies
- − monorepo
- − docs
- do-not
Line diff
hashintel/hash · AGENTS.md
@@ −1 @@
1# HASH Development Guide
2
3## Repository Structure and Navigation
4
5The HASH repository is organized into several key directories:
6
7- `/apps` - Core applications powering HASH
8 - `/hash-api` - Backend API service
9 - `/hash-frontend` - Web frontend application
10 - `/hash-graph` - Graph database service
11 - `/hash-ai-worker-ts` - AI worker services
12 - `/hash-integration-worker` - Integration worker services
13
14- `/infra/compose` - Docker Compose stack for external services (Postgres, Kratos, Hydra, Temporal, observability)
15
16- `/blocks` - Block Protocol components (each subfolder contains a self-contained block)
17
18- `/libs` - Shared libraries and packages
19 - `/@blockprotocol` - Block Protocol related libraries
20 - `/@hashintel` - HASH-specific libraries
21 - `/@local` - Internal libraries for the monorepo
22 - Other core libraries (e.g., `error-stack`)
23
24- `/infra` - Deployment and infrastructure code
25 - `/docker` - Docker configurations
26 - `/terraform` - Terraform infrastructure as code
27
28- `/tests` - Test suites spanning multiple components
29
30**Navigation Tips:**
31
32- When exploring a new feature, first identify which app or lib it belongs to
33- Related code is typically co-located within the same directory
34- Check existing implementations before creating new ones
35- For understanding cross-component interactions, look for integration tests in `/tests`
36
37## Common Commands
38
39### Development
40
41- Main development: `yarn dev` (starts API and frontend)
42- Backend only: `yarn dev:backend` or `yarn dev:backend:api`
43- Frontend only: `yarn dev:frontend`
44
45### Starting Services
46
47- Start all services: `yarn start`
48- Start graph only: `yarn start:graph`
49- Start backend only: `yarn start:backend`
50- Start frontend only: `yarn start:frontend`
51- Start workers: `yarn start:worker`
52
53### Testing
54
55- Unit tests: `yarn test:unit`
56- Integration tests: `yarn test:integration`
57
58### Linting and Fixing
59
60- Lint everything: `yarn lint`
61- TypeScript type check: `yarn lint:tsc`
62- ESLint: `yarn lint:eslint`
63- Formatting check: `yarn lint:format`
64
65- Fix ESLint issues: `yarn fix:eslint`
66- Fix formatting: `yarn fix:format`
67
68### For Specific Packages
69
70When working on a specific package, use:
71
72```bash
73# For TypeScript/JavaScript packages
74turbo run <command> --filter '<package-name>'
75
76# For Rust packages
77cargo nextest run --package <package-name>
78cargo test --package <package-name> --doc # For doc tests
79cargo clippy --all-features --package <package-name>
80```
81
82For Rust packages, you can add features as needed with `--all-features`, specific features like `--features=foo,bar`, or use `cargo-hack` with `--feature-powerset` for comprehensive feature testing.
83
84### Monorepo wiring for Rust crates
85
86Each Rust crate has a `package.json` whose **identity and workspace-dependency wiring** — its `@rust/<name>` name, version, and the `dependencies` mirroring its `Cargo.toml` — is generated from `Cargo.toml`. After **adding, removing, or renaming a Rust crate**, or changing its `Cargo.toml` dependencies, re-sync that wiring:
87
88```bash
89mise run sync:turborepo # sync package.json identity + deps from Cargo.toml metadata
90```
91
92`sync:turborepo` only manages that generated wiring — the `scripts` section is hand-maintained and is used by CI and Turborepo (e.g. `test:unit`, `lint:clippy`, `doc:dependency-diagram`), so add or edit scripts by hand. The task wraps the `repo-chores` CLI; the equivalent direct invocation is `cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo`. A related task, `mise run fix:package-json`, sorts `package.json` keys consistently.
93
94## Documentation Maintenance
95
96### Petrinaut user-facing docs
97
98The Petrinaut user guide lives at `libs/@hashintel/petrinaut/docs/*.md` and is the source of truth for end-user behaviour. The in-app AI assistant reads these pages at runtime via the `readPetrinautDoc` tool, so stale docs lead directly to wrong advice in the product.
99
100When you change UI or behaviour in the petrinaut packages (`libs/@hashintel/petrinaut`, `libs/@hashintel/petrinaut-core`), you MUST:
101
1021. Review the user-facing docs that mention the affected feature and update them in the same change.
1032. If you add a brand-new user-facing surface (panel, view, mode, tool, settings dialog, ...), add a corresponding page and link it from `libs/@hashintel/petrinaut/docs/README.md`.
1043. When you add a new doc page, also register it in `petrinautDocNames` and `petrinautDocSummaries` in `libs/@hashintel/petrinaut-core/src/ai.ts`, and add a `?raw` import in `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/petrinaut-docs-content.ts`. The tests in `libs/@hashintel/petrinaut-core/src/ai.test.ts` and `petrinaut-docs-content.test.ts` enforce that every enum value has a summary and a content entry.
1054. Keep the docs end-user-focused: describe what the user sees, what they click, what happens. Do not document Storybook, internal modules, or test setup in the user guide.
1065. If UI are changes that may make screenshots in the docs outdated, you MUST prompt your user to replace the screenshots.
107
108If a change ships without doc updates, call that out in your summary so the user can decide whether to follow up.
109
110## Contextual Rules
111
112CRITICAL: For the files referenced below, use your Read tool to load it on a need-to-know basis, ONLY when relevant to the SPECIFIC task at hand:
113
114- .config/agents/rules/\*.md
115
116Instructions:
117
118- Do NOT preemptively load all references - use lazy loading based on actual need
119- When loaded, treat content as mandatory instructions that override defaults
120- Follow references recursively when needed
121
hashintel/hash · .cursor/rules/ai-assistant-guidelines.mdc
@@ +1 @@
1---
2description: Guidelines for AI Assistants
3globs: "**/*"
4alwaysApply: true
5---
6
7# Guidelines for AI Assistants
8
9This file contains standards for how AI assistants should interact with codebases and follow project guidelines.
10
11## Core Principles
12
131. **Autonomy**: Take responsibility for following all project rules without requiring reminders.
142. **Consistency**: Maintain consistency with the existing codebase and established patterns.
153. **Proactivity**: Anticipate rule requirements before starting work on any task.
164. **Accuracy**: Ensure adherence to all relevant guidelines in every implementation.
17
18## Things to avoid
19
201. Making changes unrelated to the task at hand - if you see other things in a file that could be improved, suggest them to the user!
212. Getting stuck for a long time without asking for help - if you're struggling, just ask.
22
23## Self-Checking Process
24
25When working on any project task:
26
271. **Discovery**:
28 - Identify all relevant rule files for the current context
29 - Scan directories like `.cursor/rules/` for applicable guidelines
30 - Look for language-specific, style, and organizational conventions
31
322. **Preparation**:
33 - Review all applicable guidelines before beginning work
34 - Identify patterns in existing code that demonstrate rule application
35 - Prioritize project-specific conventions over generic best practices
36
373. **Validation**:
38 - Before submitting any changes, verify compliance with ALL project guidelines
39 - Ensure consistency with surrounding code
40 - Detect and correct any rule violations proactively
41
42## Effective Rule Application
43
44For any development task:
45
461. **Context Assessment**:
47 - Determine which rules apply to the current task
48 - Consider the specific file type, language, and component
49
502. **Implementation Guidance**:
51 - Apply relevant rules throughout the implementation process
52 - Use existing code patterns as guidance for ambiguous cases
53 - Maintain the established style and conventions
54
553. **Quality Assurance**:
56 - Verify rule compliance before finalizing work
57 - Ensure consistency across similar components
58 - Validate that all project-specific requirements are met
59
60## Common Pitfalls to Avoid
61
62- Requiring reminders about existing project guidelines
63- Implementing solutions that contradict established patterns
64- Applying inconsistent approaches across similar tasks
65- Overlooking project-specific conventions in favor of generic practices
66- Introducing deviations from standards without explicit justification
67
68AI assistants should consistently enforce project guidelines without being prompted. Your role includes ensuring that all contributions adhere to the established rules of the project.
69
@@ −1 +1 @@
1−# HASH Development Guide
1+---
2+description: Guidelines for AI Assistants
3+globs: "**/*"
4+alwaysApply: true
5+---
26
3−## Repository Structure and Navigation
7+# Guidelines for AI Assistants
48
5−The HASH repository is organized into several key directories:
9+This file contains standards for how AI assistants should interact with codebases and follow project guidelines.
610
7−- `/apps` - Core applications powering HASH
8− - `/hash-api` - Backend API service
9− - `/hash-frontend` - Web frontend application
10− - `/hash-graph` - Graph database service
11− - `/hash-ai-worker-ts` - AI worker services
12− - `/hash-integration-worker` - Integration worker services
11+## Core Principles
1312
14−- `/infra/compose` - Docker Compose stack for external services (Postgres, Kratos, Hydra, Temporal, observability)
13+1. **Autonomy**: Take responsibility for following all project rules without requiring reminders.
14+2. **Consistency**: Maintain consistency with the existing codebase and established patterns.
15+3. **Proactivity**: Anticipate rule requirements before starting work on any task.
16+4. **Accuracy**: Ensure adherence to all relevant guidelines in every implementation.
1517
16−- `/blocks` - Block Protocol components (each subfolder contains a self-contained block)
18+## Things to avoid
1719
18−- `/libs` - Shared libraries and packages
19− - `/@blockprotocol` - Block Protocol related libraries
20− - `/@hashintel` - HASH-specific libraries
21− - `/@local` - Internal libraries for the monorepo
22− - Other core libraries (e.g., `error-stack`)
20+1. Making changes unrelated to the task at hand - if you see other things in a file that could be improved, suggest them to the user!
21+2. Getting stuck for a long time without asking for help - if you're struggling, just ask.
2322
24−- `/infra` - Deployment and infrastructure code
25− - `/docker` - Docker configurations
26− - `/terraform` - Terraform infrastructure as code
23+## Self-Checking Process
2724
28−- `/tests` - Test suites spanning multiple components
25+When working on any project task:
2926
30−**Navigation Tips:**
27+1. **Discovery**:
28+ - Identify all relevant rule files for the current context
29+ - Scan directories like `.cursor/rules/` for applicable guidelines
30+ - Look for language-specific, style, and organizational conventions
3131
32−- When exploring a new feature, first identify which app or lib it belongs to
33−- Related code is typically co-located within the same directory
34−- Check existing implementations before creating new ones
35−- For understanding cross-component interactions, look for integration tests in `/tests`
32+2. **Preparation**:
33+ - Review all applicable guidelines before beginning work
34+ - Identify patterns in existing code that demonstrate rule application
35+ - Prioritize project-specific conventions over generic best practices
3636
37−## Common Commands
37+3. **Validation**:
38+ - Before submitting any changes, verify compliance with ALL project guidelines
39+ - Ensure consistency with surrounding code
40+ - Detect and correct any rule violations proactively
3841
39−### Development
42+## Effective Rule Application
4043
41−- Main development: `yarn dev` (starts API and frontend)
42−- Backend only: `yarn dev:backend` or `yarn dev:backend:api`
43−- Frontend only: `yarn dev:frontend`
44+For any development task:
4445
45−### Starting Services
46+1. **Context Assessment**:
47+ - Determine which rules apply to the current task
48+ - Consider the specific file type, language, and component
4649
47−- Start all services: `yarn start`
48−- Start graph only: `yarn start:graph`
49−- Start backend only: `yarn start:backend`
50−- Start frontend only: `yarn start:frontend`
51−- Start workers: `yarn start:worker`
50+2. **Implementation Guidance**:
51+ - Apply relevant rules throughout the implementation process
52+ - Use existing code patterns as guidance for ambiguous cases
53+ - Maintain the established style and conventions
5254
53−### Testing
55+3. **Quality Assurance**:
56+ - Verify rule compliance before finalizing work
57+ - Ensure consistency across similar components
58+ - Validate that all project-specific requirements are met
5459
55−- Unit tests: `yarn test:unit`
56−- Integration tests: `yarn test:integration`
60+## Common Pitfalls to Avoid
5761
58−### Linting and Fixing
62+- Requiring reminders about existing project guidelines
63+- Implementing solutions that contradict established patterns
64+- Applying inconsistent approaches across similar tasks
65+- Overlooking project-specific conventions in favor of generic practices
66+- Introducing deviations from standards without explicit justification
5967
60−- Lint everything: `yarn lint`
61−- TypeScript type check: `yarn lint:tsc`
62−- ESLint: `yarn lint:eslint`
63−- Formatting check: `yarn lint:format`
64−
65−- Fix ESLint issues: `yarn fix:eslint`
66−- Fix formatting: `yarn fix:format`
67−
68−### For Specific Packages
69−
70−When working on a specific package, use:
71−
72−```bash
73−# For TypeScript/JavaScript packages
74−turbo run <command> --filter '<package-name>'
75−
76−# For Rust packages
77−cargo nextest run --package <package-name>
78−cargo test --package <package-name> --doc # For doc tests
79−cargo clippy --all-features --package <package-name>
80−```
81−
82−For Rust packages, you can add features as needed with `--all-features`, specific features like `--features=foo,bar`, or use `cargo-hack` with `--feature-powerset` for comprehensive feature testing.
83−
84−### Monorepo wiring for Rust crates
85−
86−Each Rust crate has a `package.json` whose **identity and workspace-dependency wiring** — its `@rust/<name>` name, version, and the `dependencies` mirroring its `Cargo.toml` — is generated from `Cargo.toml`. After **adding, removing, or renaming a Rust crate**, or changing its `Cargo.toml` dependencies, re-sync that wiring:
87−
88−```bash
89−mise run sync:turborepo # sync package.json identity + deps from Cargo.toml metadata
90−```
91−
92−`sync:turborepo` only manages that generated wiring — the `scripts` section is hand-maintained and is used by CI and Turborepo (e.g. `test:unit`, `lint:clippy`, `doc:dependency-diagram`), so add or edit scripts by hand. The task wraps the `repo-chores` CLI; the equivalent direct invocation is `cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo`. A related task, `mise run fix:package-json`, sorts `package.json` keys consistently.
93−
94−## Documentation Maintenance
95−
96−### Petrinaut user-facing docs
97−
98−The Petrinaut user guide lives at `libs/@hashintel/petrinaut/docs/*.md` and is the source of truth for end-user behaviour. The in-app AI assistant reads these pages at runtime via the `readPetrinautDoc` tool, so stale docs lead directly to wrong advice in the product.
99−
100−When you change UI or behaviour in the petrinaut packages (`libs/@hashintel/petrinaut`, `libs/@hashintel/petrinaut-core`), you MUST:
101−
102−1. Review the user-facing docs that mention the affected feature and update them in the same change.
103−2. If you add a brand-new user-facing surface (panel, view, mode, tool, settings dialog, ...), add a corresponding page and link it from `libs/@hashintel/petrinaut/docs/README.md`.
104−3. When you add a new doc page, also register it in `petrinautDocNames` and `petrinautDocSummaries` in `libs/@hashintel/petrinaut-core/src/ai.ts`, and add a `?raw` import in `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/petrinaut-docs-content.ts`. The tests in `libs/@hashintel/petrinaut-core/src/ai.test.ts` and `petrinaut-docs-content.test.ts` enforce that every enum value has a summary and a content entry.
105−4. Keep the docs end-user-focused: describe what the user sees, what they click, what happens. Do not document Storybook, internal modules, or test setup in the user guide.
106−5. If UI are changes that may make screenshots in the docs outdated, you MUST prompt your user to replace the screenshots.
107−
108−If a change ships without doc updates, call that out in your summary so the user can decide whether to follow up.
109−
110−## Contextual Rules
111−
112−CRITICAL: For the files referenced below, use your Read tool to load it on a need-to-know basis, ONLY when relevant to the SPECIFIC task at hand:
113−
114−- .config/agents/rules/\*.md
115−
116−Instructions:
117−
118−- Do NOT preemptively load all references - use lazy loading based on actual need
119−- When loaded, treat content as mandatory instructions that override defaults
120−- Follow references recursively when needed
68+AI assistants should consistently enforce project guidelines without being prompted. Your role includes ensuring that all contributions adhere to the established rules of the project.
12169
