docs: scaffold agent instruction tree
Add AGENTS.md, CLAUDE.md, and the agents-docs/ tree (workflow, lessons, engineering standards, context map, ADR seed, feature template) plus a domain-bearing CONTEXT.md for each of the six subdomains: toju-app, electron, server, e2e, website, docs-site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
101
AGENTS.md
Normal file
101
AGENTS.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# AGENTS.md
|
||||
|
||||
Read these files at the start of every session before doing any work:
|
||||
|
||||
1. `agents-docs/AGENT_WORKFLOW.md` — workflow and operating rules
|
||||
2. `agents-docs/LESSONS.md` — durable rules learned from past corrections; apply any that match this session's work
|
||||
3. `agents-docs/AGENTS_FEATURES.md` — when and how to update feature docs
|
||||
4. `agents-docs/FEATURES.md` — feature index
|
||||
5. `agents-docs/ENGINEERING.md` — engineering standards
|
||||
6. `agents-docs/CONTEXT-MAP.md` — index of bounded contexts in this repo
|
||||
|
||||
Reference on-demand (when the workflow triggers them — see `agents-docs/AGENT_WORKFLOW.md` §§ 4–5):
|
||||
|
||||
- `agents-docs/AGENTS_CONTEXT.md` — contract for updating `CONTEXT.md` / `CONTEXT-MAP.md`
|
||||
- `agents-docs/AGENTS_ADRS.md` — contract for writing architecture decision records
|
||||
|
||||
When working in a subdomain, also read its `CONTEXT.md` first:
|
||||
|
||||
- Product client (Angular 21): `toju-app/CONTEXT.md`
|
||||
- Desktop shell (Electron main + preload): `electron/CONTEXT.md`
|
||||
- Signaling server (Express + WebSocket): `server/CONTEXT.md`
|
||||
- End-to-end tests (Playwright): `e2e/CONTEXT.md`
|
||||
- Marketing site (Angular 19): `website/CONTEXT.md`
|
||||
- Application documentation (Docusaurus): `docs-site/CONTEXT.md`
|
||||
|
||||
---
|
||||
|
||||
MetoYou (also called Toju) is a desktop-first, P2P Discord-style chat application managed as an npm-workspaces monorepo. It bundles an Angular 21 product client, an Electron 39 desktop shell with TypeORM + sql.js for local persistence, a small Node/TypeScript Express signaling server with WebSocket-based realtime, a Playwright end-to-end suite, an Angular 19 marketing site, and a Docusaurus app/plugin documentation site that ships inside the Electron build. Voice and screen-share are WebRTC, with RNNoise denoising via a WASM audio worklet.
|
||||
|
||||
## CRITICAL — Non-negotiable rules for all agents
|
||||
|
||||
### Test-Driven Development (MANDATORY)
|
||||
**Write tests before implementation code.**
|
||||
|
||||
When creating or changing anything:
|
||||
1. STOP — do not write implementation first
|
||||
2. Write failing tests (RED)
|
||||
3. Run tests and confirm failure (`npm run test` for the product client; `npm run test:e2e` for end-to-end; place spec files colocated with source, suffix `.spec.ts`)
|
||||
4. Write minimal code to pass tests (GREEN)
|
||||
5. Refactor while keeping tests green
|
||||
|
||||
This applies to all code — Angular components and services, NgRx effects/reducers, Electron IPC handlers, server CQRS handlers, websocket message handlers, plugin runtime, and domain logic. If the code lives in a package without a configured test runner (server, website, docs-site), surface that gap before adding logic there.
|
||||
|
||||
### Lint correctness (MANDATORY)
|
||||
Before completing any task:
|
||||
1. Run `npm run lint` from the repo root (ESLint 9 flat config in `eslint.config.js` covers every package)
|
||||
2. Fix all errors
|
||||
3. Do not consider work complete until it exits with code 0
|
||||
|
||||
### Type / build correctness (MANDATORY)
|
||||
Type checks live in build scripts:
|
||||
|
||||
- Product client (`toju-app/`): `npm run build` (Angular CLI runs `tsc` with strict settings)
|
||||
- Electron (`electron/`): `npm run build:electron` (invokes `tsc -p tsconfig.electron.json`)
|
||||
- Server (`server/`): `cd server && npm run build` (invokes `tsc`)
|
||||
|
||||
If your change touches one of these packages, run the corresponding build and ensure it exits 0 before marking work complete.
|
||||
|
||||
## Most important rule
|
||||
|
||||
After any change that affects API contracts, schemas, invariants, workflows, or major behavior: update the relevant `agents-docs/features/<slug>.md` as part of the same task — not as a follow-up. New feature area → create `agents-docs/features/<slug>.md` and add an entry to `agents-docs/FEATURES.md` (alphabetical).
|
||||
|
||||
The product client already maintains per-domain READMEs under `toju-app/src/app/domains/<name>/README.md`. When the change is fully internal to one of those bounded contexts and its surface stays the same, the domain README is the right place to update; cross-context contracts (websocket envelopes, IPC channels, server routes, plugin manifests) belong in `agents-docs/features/`.
|
||||
|
||||
## Structure of further instructions
|
||||
|
||||
- **Agent workflow & operating rules:** `agents-docs/AGENT_WORKFLOW.md`
|
||||
- **Agent lessons (durable cross-session rules):** `agents-docs/LESSONS.md`
|
||||
- **Engineering standards:** `agents-docs/ENGINEERING.md`
|
||||
- **Feature documentation contract:** `agents-docs/AGENTS_FEATURES.md`
|
||||
- **CONTEXT documentation contract:** `agents-docs/AGENTS_CONTEXT.md`
|
||||
- **ADR contract:** `agents-docs/AGENTS_ADRS.md`
|
||||
- **Feature index:** `agents-docs/FEATURES.md`
|
||||
- **Feature docs:** `agents-docs/features/`
|
||||
- **Architecture decisions:** `agents-docs/adr/`
|
||||
- **Context map:** `agents-docs/CONTEXT-MAP.md`
|
||||
- **Product-client domain:** `toju-app/CONTEXT.md`
|
||||
- **Desktop-shell domain:** `electron/CONTEXT.md`
|
||||
- **Server domain:** `server/CONTEXT.md`
|
||||
- **E2E suite domain:** `e2e/CONTEXT.md`
|
||||
- **Marketing-site domain:** `website/CONTEXT.md`
|
||||
- **App-docs domain:** `docs-site/CONTEXT.md`
|
||||
|
||||
Keep this file minimal. Do not duplicate detailed rules here.
|
||||
|
||||
## Completion checklist
|
||||
|
||||
Before marking work complete:
|
||||
|
||||
- [ ] Tests written before implementation
|
||||
- [ ] All tests passing (`npm run test`, plus `npm run test:e2e` if behavior is user-visible)
|
||||
- [ ] `npm run lint` passes
|
||||
- [ ] Affected package builds: `npm run build` / `npm run build:electron` / `cd server && npm run build`
|
||||
- [ ] Naming conventions followed (kebab-case files; domain `*.rules.ts` / `*.model.ts` / `*.component.ts` suffixes)
|
||||
- [ ] Errors handled
|
||||
- [ ] Feature docs updated if contract/schema/invariant changed (see `agents-docs/AGENTS_FEATURES.md`)
|
||||
- [ ] `CONTEXT.md` updated if a domain term was resolved or introduced (see `agents-docs/AGENTS_CONTEXT.md`)
|
||||
- [ ] ADR written if a hard-to-reverse decision was made (see `agents-docs/AGENTS_ADRS.md`)
|
||||
- [ ] Lesson recorded in `agents-docs/LESSONS.md` if this session produced a correction, revert, or hidden constraint (see triggers in `agents-docs/AGENT_WORKFLOW.md`)
|
||||
- [ ] PR opened with summary and linked issues (`Fixes #<n>` / `Relates to #<n>`)
|
||||
- [ ] Gitea Workflows checks passing
|
||||
Reference in New Issue
Block a user