Cline rules

1# Project Configuration
2 
3> **Bootstrapped by `analyze_project`**, then hand-tuned for this repo.
4> **Project:** my_project
5> **Type:** library / teaching repo (Vercel AI SDK agent masterclass + VitePress docs)
6 
7---
8 
9## 🚨 MANDATORY: Load CodeOps Rules Before Any Work
10 
11**Before ANY planning or implementation, the AI agent MUST load these rules
12using the codeops-mcp tools:**
13 
141. `get_rule("agents")` — Load agent behavior rules **(REQUIRED FIRST)**
152. `get_rule("code")` — Load coding standards
163. `get_rule("testing")` — Load testing workflows
174. `get_rule("git-commands")` — Load git commit protocols
18 
19These rules are **mandatory** and must be consulted before every task.
20**Do NOT skip this step. Do NOT proceed without reading these documents.**
21 
22---
23 
24## Project Overview
25 
26- **Name:** my_project
27- **Description:** A hands-on masterclass repo for building production-grade AI
28  agents in TypeScript with the Vercel AI SDK (`ai@6` + `@ai-sdk/openai@3`).
29  Ships 10+ runnable single-concept tutorials under `src/agents/` plus a
30  VitePress documentation site deployed to GitHub Pages.
31- **Type:** library
32 
33## Toolchain
34 
35- **Language(s):** TypeScript (ESM, `type: module`, `module: nodenext`,
36  `target: esnext`, `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`)
37- **Framework(s):** Vercel AI SDK (`ai`), VitePress (docs), Vitest (tests)
38- **Package Manager:** yarn (1.22)
39- **Test Framework:** Vitest
40 
41**Manifest files found:** package.json, tsconfig.json
42 
43## Commands
44 
45All commands assume execution from the project root. Prefix all shell commands with `clear && sleep [delay] &&` (see Terminal Delay below).
46 
47### Terminal Delay
48 
49- **Delay (seconds):** 3
50- The `clear` ensures a clean terminal; the `sleep` gives VS Code time to initialize the terminal before the command runs.
51- Adjust the delay for your environment: `1` for fast machines, `3` (default) for normal, `5` for slower environments.
52 
53### Run a tutorial
54 
55```bash
56clear && sleep 3 && yarn dev &lt;n&gt;   # <n> = source file number under src/agents
57```
58 
59### Build
60 
61```bash
62clear && sleep 3 && yarn build
63```
64 
65### Test
66 
67```bash
68# Run all tests
69clear && sleep 3 && yarn test
70```
71 
72### Docs
73 
74```bash
75clear && sleep 3 && yarn docs:build     # build the VitePress site
76clear && sleep 3 && yarn docs:dev       # local docs preview
77```
78 
79### Verify (before commit)
80 
81```bash
82# Full verification — run this before any git commit
83clear && sleep 3 && yarn test && yarn docs:build
84```
85 
86## Project Structure
87 
88### Type: Single repository
89 
90### Directory Layout
91 
92```
93docs/        # VitePress documentation site (built to docs/.vitepress/dist)
94plans/       # CodeOps plan artifacts
95src/         # TypeScript sources
96  agents/    # numbered single-concept tutorials (01..)
97  tools.ts   # shared tools (getWeather, calculator/safeEvaluate)
98  index.ts   # CLI launcher (yarn dev <n>)
99  markdown.ts
100dist/        # tsc output (git-ignored)
101coverage/    # vitest coverage output (git-ignored)
102```
103 
104## Coding Conventions
105 
106### Naming
107 
108- **Files:** kebab-case, numbered for tutorials (e.g. `01-oneshot.ts`)
109- **Components/Classes:** PascalCase
110- **Functions/Methods:** camelCase
111- **Constants:** UPPER_SNAKE_CASE
112 
113### Dependencies
114 
115- New build/test/docs tooling (Vitest, VitePress, Mermaid) goes under a
116  **`devDependencies`** block — not needed at runtime; CI installs frozen.
117- See `.clinerules/ai-sdk.md` for Vercel AI SDK conventions and gotchas
118  (use `generateText`/`streamText` + `Output`, not the deprecated
119  `generateObject`/`streamObject`).
120 
121## Git & Commit Conventions
122 
123### Commit Scope
124 
125```
126# Use module/feature as scope:
127# feat(agents): ...   fix(tools): ...   docs(plans): ...   chore(ci): ...
128```
129 
130### Branch Strategy
131 
132- **Main branch:** `main`
133- **Feature branches:** `feature/[name]`
134 
135## Special Rules (Project-Specific)
136 
137```
138- Docs must never drift from code: import real source via VitePress <<< snippets.
139- No live OpenAI/embedding calls in tests; CI must be deterministic (mock model).
140- Never commit secrets; OPENAI_API_KEY lives in .env (git-ignored).
141```
142 
143## Cross-References
144 
145The generic rule files that read this `project.md`:
146 
147- **make_plan.md** — Uses verify command, file paths, commit scope, task file path patterns
148- **code.md** — Uses language conventions, architecture rules
149- **testing.md** — Uses test commands, test locations, test framework
150- **git-commands.md** — Uses commit scope, verify command
151- **agents.md** — Uses shell commands, verify command
152- **preflight.md** — Uses project type, tech stack, and conventions for grounded quality audits
153