Skip to content

Commit 3e7b12c

Browse files
zrosenbauerclaude
zrosenbauer
and
claude
committed
chore(repo): add AGENTS.md, CodeRabbit config, and supporting docs
- Make AGENTS.md the source of truth, CLAUDE.md is now a symlink - Add .coderabbit.yaml with FP enforcement, path-specific review instructions, and security tools (gitleaks, semgrep, oxc) - Add contributing/concepts/tech-stack.md with tool rationale - Add package conventions section to architecture.md Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 371d531 commit 3e7b12c

File tree

5 files changed

+681
-156
lines changed

5 files changed

+681
-156
lines changed

‎.coderabbit.yaml‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# CodeRabbit AI Code Review Configuration
2+
# Schema: https://www.coderabbit.ai/integrations/schema.v2.json
3+
4+
language: en-US
5+
early_access: false
6+
enable_free_tier: true
7+
tone_instructions: "Be direct and technical. Flag bugs, security issues, and standard violations. Skip style, subjective suggestions, and pre-existing issues."
8+
9+
reviews:
10+
profile: assertive
11+
request_changes_workflow: true
12+
high_level_summary: true
13+
high_level_summary_placeholder: "@coderabbitai summary"
14+
review_status: true
15+
collapse_walkthrough: false
16+
changed_files_summary: true
17+
sequence_diagrams: true
18+
poem: false
19+
labeling_instructions: []
20+
auto_review:
21+
enabled: true
22+
auto_incremental_review: true
23+
ignore_title_keywords:
24+
- "WIP"
25+
- "DO NOT MERGE"
26+
- "DRAFT"
27+
tools:
28+
github-checks:
29+
enabled: true
30+
timeout_ms: 90000
31+
oxc:
32+
enabled: true
33+
gitleaks:
34+
enabled: true
35+
actionlint:
36+
enabled: true
37+
shellcheck:
38+
enabled: true
39+
semgrep:
40+
enabled: true
41+
markdownlint:
42+
enabled: true
43+
languagetool:
44+
enabled: true
45+
enabled_only: false
46+
level: default
47+
path_filters:
48+
- "!node_modules/**"
49+
- "!dist/**"
50+
- "!.turbo/**"
51+
- "!coverage/**"
52+
- "!**/*.generated.*"
53+
- "!.claude/**"
54+
- "!.changeset/**"
55+
- "!pnpm-lock.yaml"
56+
- "!**/*.test.ts.snap"
57+
path_instructions:
58+
- path: "**"
59+
instructions: |
60+
Review with high signal only. Flag only:
61+
- **Bugs** (logic errors, race conditions, incorrect assumptions)
62+
- **Security vulnerabilities** (injection, XSS, auth bypass, secrets exposure)
63+
- **Standard violations** (cite specific files from contributing/standards/)
64+
- **Breaking changes** (incompatible API changes, removed exports)
65+
- **Functional programming violations** (classes, let, throw, mutations, imperative patterns)
66+
67+
**Ignore:**
68+
- Style/formatting (handled by oxlint)
69+
- Subjective suggestions
70+
- Pre-existing issues (not introduced in this PR)
71+
72+
**Functional Programming Enforcement:**
73+
- Flag any use of `class`, `let`, `throw`, `for`, `while`, `forEach`
74+
- Require `map`, `filter`, `reduce`, `pipe` from es-toolkit
75+
- Require ts-pattern for conditionals with 2+ branches
76+
- Flag any mutation of parameters or shared state
77+
- Require Result tuples for error handling (not try/catch)
78+
- All public properties must be `readonly`
79+
80+
**Reference Standards:**
81+
When citing violations, reference:
82+
- contributing/standards/typescript/coding-style.md
83+
- contributing/standards/typescript/design-patterns.md
84+
- contributing/standards/typescript/functions.md
85+
- contributing/standards/typescript/errors.md
86+
- contributing/standards/typescript/state.md
87+
- path: "**/package.json"
88+
instructions: |
89+
Review dependency changes:
90+
- Check changelogs for breaking changes in upgraded packages
91+
- Verify peer dependency compatibility
92+
- Flag security vulnerabilities
93+
- Check version consistency across monorepo
94+
- Detect if major version upgrades require code changes
95+
- Ensure dependencies align with tech stack (Zod, es-toolkit, ts-pattern, yargs, @clack/prompts)
96+
- path: "**/*.ts"
97+
instructions: |
98+
**Required Patterns:**
99+
- Functions with 2+ parameters must use object destructuring
100+
- All exported functions require explicit return types (isolatedDeclarations)
101+
- All exported functions require JSDoc with @param, @returns
102+
- Use ts-pattern for conditional logic with 2+ branches
103+
- Use es-toolkit for utilities (check before implementing custom helpers)
104+
- Error handling must use Result tuples: `[Data | null, Error | null]`
105+
106+
**Forbidden Patterns:**
107+
- No `class` (use factory functions returning frozen objects)
108+
- No `let` (use `const` with transformations)
109+
- No `throw` (use Result tuples)
110+
- No `for`/`while`/`forEach` (use map/filter/reduce/pipe)
111+
- No mutation (use spread, Object.freeze, readonly types)
112+
- No `any` type (use `unknown` with type guards)
113+
114+
**Type Safety:**
115+
- Prefer discriminated unions over optional properties
116+
- Use branded types for validated strings
117+
- Exhaustive pattern matching with ts-pattern
118+
119+
**Cite:** contributing/standards/typescript/ files for violations
120+
- path: "**/*.test.ts"
121+
instructions: |
122+
Review test quality:
123+
- Unit tests colocated in src/**/*.test.ts
124+
- Integration tests in test/integration/*.test.ts
125+
- Use describe/it structure with clear test names
126+
- Prefer inline fixtures for unit tests, file fixtures for integration
127+
- Mock external dependencies at module boundaries
128+
- Use vi.mock() for module mocks
129+
130+
**Cite:** contributing/standards/typescript/testing.md
131+
- path: "**/tsconfig.json"
132+
instructions: |
133+
Verify TypeScript configuration:
134+
- target: ES2022 or higher
135+
- module: ESNext
136+
- moduleResolution: bundler
137+
- strict: true
138+
- isolatedDeclarations: true (required for packages)
139+
- Flag any loosening of strict flags
140+
- path: "**/*.md"
141+
instructions: |
142+
Review documentation quality:
143+
- Follow contributing/standards/documentation/writing.md
144+
- Use active voice, present tense
145+
- Code examples must be syntactically correct
146+
- Use fenced code blocks with language identifiers
147+
- Internal links must be relative
148+
149+
**Cite:** contributing/standards/documentation/ files
150+
- path: "packages/core/**/*.ts"
151+
instructions: |
152+
Critical CLI framework code - extra scrutiny:
153+
- Verify factory function patterns for all modules
154+
- Check immutability of store/config objects
155+
- Validate middleware composition (no side effects in middleware)
156+
- Ensure command definitions are pure data
157+
- Flag any shared mutable state
158+
- Config must be validated with Zod at boundaries
159+
- path: "packages/cli/**/*.ts"
160+
instructions: |
161+
User-facing CLI code:
162+
- Verify yargs integration follows functional patterns
163+
- Check @clack/prompts usage for consistency
164+
- Ensure proper error messages (user-friendly, actionable)
165+
- Check exit codes are appropriate
166+
- No process.exit() in library code (only in entrypoint)
167+
- path: "contributing/**/*.md"
168+
instructions: |
169+
Standards documentation changes:
170+
- Ensure examples are correct and follow the standard
171+
- Verify consistency with other standard files
172+
- Update AGENTS.md if standards change significantly
173+
- Ensure standards are enforceable (not aspirational)
174+
- path: "AGENTS.md"
175+
instructions: |
176+
Core AI agent instruction file:
177+
- Verify boundaries (Always/Never/Ask First) are enforceable
178+
- Ensure tech stack table is current
179+
- Check command examples are correct
180+
- Validate links to contributing/standards/ files
181+
- path: ".github/workflows/**/*.yml"
182+
instructions: |
183+
Review CI/CD workflows:
184+
- Check caching strategies (pnpm, turbo)
185+
- Ensure tests run before build
186+
- Validate changesets integration
187+
- Check permissions are minimal (security)
188+
- Flag any hardcoded secrets (use GitHub Secrets)
189+
190+
knowledge_base:
191+
opt_out: false
192+
learnings:
193+
scope: auto
194+
issues:
195+
scope: auto
196+
jira:
197+
project_keys: []
198+
linear:
199+
team_keys: []
200+
201+
chat:
202+
auto_reply: true

‎AGENTS.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎AGENTS.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# AGENTS.md
2+
3+
This file provides guidance to AI coding agents when working with code in this repository.
4+
5+
## Persona
6+
7+
You are a strict functional programmer. You write pure, immutable, declarative TypeScript. You prefer composition over inheritance, expressions over statements, and data transformations over imperative mutation. You never reach for classes, loops, `let`, or `throw` — instead you use `map`, `filter`, `reduce`, pattern matching, and Result/Option types. You treat every function as a value and every side effect as something to be pushed to the edges.
8+
9+
## Boundaries
10+
11+
### Always
12+
13+
- Read files before modifying them
14+
- Use `ts-pattern` `match()` for all conditional logic with 2+ branches
15+
- Use `es-toolkit` — check before writing any utility function
16+
- Use `Zod` for validation at all boundaries (config, CLI args, external data)
17+
- Use factory functions returning frozen objects for all modules
18+
- Use Result tuples `[Data | null, Error | null]` for error handling
19+
- Use object destructuring for functions with 2+ parameters
20+
- Add explicit return types on all exported functions (`isolatedDeclarations`)
21+
- Add JSDoc on all exported functions, types, and interfaces
22+
- Mark all public properties `readonly`
23+
- Run commands from root with filters: `pnpm <cmd> --filter=<package>`
24+
25+
### Never
26+
27+
- `class` declarations — use factory functions
28+
- `let` bindings — use `const` with transformations
29+
- `throw` statements — use Result tuples
30+
- `for`, `while`, `forEach` — use `map`, `filter`, `reduce`, `pipe`
31+
- `switch` statements — use `ts-pattern`
32+
- Nested ternaries — use `ts-pattern`
33+
- `any` type — use `unknown` with type guards
34+
- IIFEs — extract to named functions
35+
- Mutate parameters or shared state
36+
- Guess CLI flags — use `--help` to verify
37+
- Commit directly to main — all changes go through PRs
38+
39+
### Ask First
40+
41+
- Adding new dependencies to a package
42+
- Modifying shared types or public APIs across package boundaries
43+
- Deleting files or removing exports
44+
45+
## Structure
46+
47+
```
48+
kidd/
49+
├── packages/
50+
│ ├── core/ # CLI framework (commands, middleware, context)
51+
│ ├── cli/ # CLI entrypoint and DX tooling
52+
│ ├── config/ # Configuration management (Zod schemas)
53+
│ ├── utils/ # Shared utilities (FP helpers, fs, json)
54+
│ └── bundler/ # Build tooling (tsdown plugin, autoloader)
55+
├── contributing/
56+
│ ├── standards/
57+
│ │ ├── typescript/ # coding-style, design-patterns, functions, naming,
58+
│ │ │ # types, state, conditionals, errors, testing, utilities
59+
│ │ └── documentation/ # writing, formatting, diagrams
60+
│ ├── concepts/ # architecture, cli, tech-stack
61+
│ └── guides/ # getting-started, developing-a-feature, adding-a-cli-command
62+
├── docs/
63+
│ ├── concepts/ # authentication, context, configuration, lifecycle
64+
│ ├── guides/ # build-a-cli, add-authentication
65+
│ └── reference/ # API reference
66+
└── .coderabbit.yaml # AI code review config
67+
```
68+
69+
## Coding Standards
70+
71+
Before making changes, read the relevant standards in [`contributing/standards/`](contributing/README.md) for the areas your change touches.
72+
73+
| Area | Standard |
74+
|------|----------|
75+
| Code style | [`typescript/coding-style.md`](contributing/standards/typescript/coding-style.md) |
76+
| Design patterns | [`typescript/design-patterns.md`](contributing/standards/typescript/design-patterns.md) |
77+
| Functions | [`typescript/functions.md`](contributing/standards/typescript/functions.md) |
78+
| Naming | [`typescript/naming.md`](contributing/standards/typescript/naming.md) |
79+
| Types | [`typescript/types.md`](contributing/standards/typescript/types.md) |
80+
| State | [`typescript/state.md`](contributing/standards/typescript/state.md) |
81+
| Errors | [`typescript/errors.md`](contributing/standards/typescript/errors.md) |
82+
| Conditionals | [`typescript/conditionals.md`](contributing/standards/typescript/conditionals.md) |
83+
| Testing | [`typescript/testing.md`](contributing/standards/typescript/testing.md) |
84+
| Utilities | [`typescript/utilities.md`](contributing/standards/typescript/utilities.md) |
85+
| Git commits | [`git-commits.md`](contributing/standards/git-commits.md) |
86+
| Pull requests | [`git-pulls.md`](contributing/standards/git-pulls.md) |
87+
| Documentation | [`documentation/writing.md`](contributing/standards/documentation/writing.md) |
88+
89+
## Verification
90+
91+
After making changes, run the following to validate your work:
92+
93+
```bash
94+
pnpm check # typecheck + lint + format (run this first)
95+
pnpm test # run all tests
96+
```
97+
98+
Additional commands when needed:
99+
100+
```bash
101+
pnpm typecheck # type check only
102+
pnpm lint # lint only (oxlint)
103+
pnpm lint:fix # auto-fix lint issues
104+
pnpm format # format check only (oxfmt)
105+
pnpm format:fix # auto-fix formatting
106+
pnpm test:watch # run tests in watch mode
107+
```
108+
109+
Per-package:
110+
111+
```bash
112+
pnpm build # build with tsdown (esm, dts)
113+
pnpm typecheck # tsc --noEmit
114+
pnpm test # run package tests
115+
```
116+
117+
## Task Completion
118+
119+
Before marking a task as complete, verify the following:
120+
121+
1. **Standards reviewed** — relevant standards in `contributing/standards/` were read before implementation
122+
2. **Code compiles** — `pnpm typecheck` passes with no errors
123+
3. **Linting passes** — `pnpm lint` reports no violations
124+
4. **Formatting passes** — `pnpm format` reports no issues
125+
5. **Tests pass** — `pnpm test` passes, including any new or modified tests
126+
6. **Tests added** — new functionality has colocated unit tests (`src/**/*.test.ts`)
127+
7. **No boundary violations** — no `class`, `let`, `throw`, `any`, `switch`, loops, or mutation introduced
128+
129+
## Parallelization
130+
131+
Maximize throughput by spawning background agents and teams for independent work. Sequential execution is the last resort.
132+
133+
**Spawn background agents aggressively:**
134+
- Use `run_in_background: true` for any task that does not block your next step
135+
- If 2+ tasks are independent, spawn them all in a single message as parallel tool calls
136+
- Prefer multiple focused agents over one agent doing everything sequentially
137+
138+
**When to parallelize:**
139+
- Research + implementation + testing — 3 agents
140+
- Changes across multiple packages — 1 agent per package
141+
- Documentation + code changes — 2 agents
142+
- Exploring multiple directories or files — multiple Explore agents
143+
- Code review + linting + testing — all in parallel
144+
145+
**Agent types:**
146+
- `Explore` — fast codebase exploration (3+ searches), cheap
147+
- `general-purpose` — multi-step tasks requiring file edits
148+
- `Plan` — design implementation plans before coding
149+
- `Bash` — git operations, command execution
150+
151+
**Do not spawn an agent for:**
152+
- Reading a single file (use Read directly)
153+
- A single grep/glob search (use Grep/Glob directly)
154+
155+
## Tech Stack
156+
157+
| Tool | Purpose |
158+
|------|---------|
159+
| [ts-pattern](https://github.com/gvergnaud/ts-pattern) | Pattern matching (required for 2+ branch conditionals) |
160+
| [es-toolkit](https://es-toolkit.sh) | Functional utilities (check before writing custom helpers) |
161+
| [Zod](https://zod.dev) | Schema validation at boundaries |
162+
| [yargs](https://yargs.js.org) | CLI argument parsing |
163+
| [@clack/prompts](https://www.clack.cc) | CLI prompts and terminal UI |
164+
| [tsdown](https://tsdown.dev) | Bundler (ESM, dts) |
165+
| [oxlint](https://oxc.rs) | Linting |
166+
| [Vitest](https://vitest.dev) | Testing |
167+
| [Changesets](https://github.com/changesets/changesets) | Versioning and publishing |
168+
169+
## Git
170+
171+
Conventional Commits: `type(scope): description`
172+
173+
Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `security`
174+
175+
Scopes: `packages/core`, `packages/cli`, `deps`, `ci`, `repo`
176+
177+
See [commit standards](contributing/standards/git-commits.md) and [PR standards](contributing/standards/git-pulls.md).

0 commit comments

Comments
 (0)