added 260907 version of worker toolkit
This commit is contained in:
125
.codex/skills/codebase-overview/evals/evals.json
Normal file
125
.codex/skills/codebase-overview/evals/evals.json
Normal file
@@ -0,0 +1,125 @@
|
||||
{
|
||||
"skill_name": "codebase-overview",
|
||||
"evals": [
|
||||
{
|
||||
"id": 0,
|
||||
"prompt": "prime on this app and create an OVERVIEW.md",
|
||||
"expected_output": "A well-structured OVERVIEW.md file written to the project root covering purpose, tech stack, directory structure, architecture, integrations, database/data layer, connectivity/config, and key entry points.",
|
||||
"files": [],
|
||||
"assertions": [
|
||||
{
|
||||
"id": "file_exists",
|
||||
"text": "OVERVIEW.md file was created and is non-empty (at least 300 characters)"
|
||||
},
|
||||
{
|
||||
"id": "has_tech_stack_section",
|
||||
"text": "Document contains a tech stack or technology section with at least Vite and TypeScript mentioned"
|
||||
},
|
||||
{
|
||||
"id": "mentions_preact_or_react",
|
||||
"text": "Document mentions Preact or preact/compat (the core framework) and the React alias or migration"
|
||||
},
|
||||
{
|
||||
"id": "has_directory_structure",
|
||||
"text": "Document includes a directory/file structure section showing the monorepo layout (packages/client and packages/shared)"
|
||||
},
|
||||
{
|
||||
"id": "mentions_connectivity",
|
||||
"text": "Document mentions the API proxy or backend connectivity (localhost:4000 or /api proxy)"
|
||||
},
|
||||
{
|
||||
"id": "has_integrations",
|
||||
"text": "Document mentions at least one external integration (Argyle, or similar third-party service)"
|
||||
},
|
||||
{
|
||||
"id": "no_database_false_positive",
|
||||
"text": "Document correctly notes this is a frontend-only project with no database layer (does not claim there is a database)"
|
||||
},
|
||||
{
|
||||
"id": "mentions_migration_context",
|
||||
"text": "Document mentions the Preact-to-React migration context or the renderer directives system as a notable gotcha"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "glean all the salient details of the code. Create a markdown file called OVERVIEW.md with your understanding of the app/folder, file structure, integrations, database and connectivity.",
|
||||
"expected_output": "OVERVIEW.md written to project root with sections covering app purpose, directory/file structure, integrations, database info, and connectivity/env config.",
|
||||
"files": [],
|
||||
"assertions": [
|
||||
{
|
||||
"id": "file_exists",
|
||||
"text": "OVERVIEW.md file was created and is non-empty (at least 300 characters)"
|
||||
},
|
||||
{
|
||||
"id": "has_tech_stack_section",
|
||||
"text": "Document contains a tech stack or technology section with at least Vite and TypeScript mentioned"
|
||||
},
|
||||
{
|
||||
"id": "mentions_preact_or_react",
|
||||
"text": "Document mentions Preact or preact/compat (the core framework) and the React alias or migration"
|
||||
},
|
||||
{
|
||||
"id": "has_directory_structure",
|
||||
"text": "Document includes a directory/file structure section showing the monorepo layout (packages/client and packages/shared)"
|
||||
},
|
||||
{
|
||||
"id": "mentions_connectivity",
|
||||
"text": "Document mentions the API proxy or backend connectivity (localhost:4000 or /api proxy)"
|
||||
},
|
||||
{
|
||||
"id": "has_integrations",
|
||||
"text": "Document mentions at least one external integration (Argyle, or similar third-party service)"
|
||||
},
|
||||
{
|
||||
"id": "no_database_false_positive",
|
||||
"text": "Document correctly notes this is a frontend-only project with no database layer (does not claim there is a database)"
|
||||
},
|
||||
{
|
||||
"id": "mentions_migration_context",
|
||||
"text": "Document mentions the Preact-to-React migration context or the renderer directives system as a notable gotcha"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "I just cloned this repo and have no idea what it is. Can you explore it and write an OVERVIEW.md so I can get oriented?",
|
||||
"expected_output": "OVERVIEW.md written to project root that a new developer could read to understand the project from scratch — purpose, stack, structure, how it's connected.",
|
||||
"files": [],
|
||||
"assertions": [
|
||||
{
|
||||
"id": "file_exists",
|
||||
"text": "OVERVIEW.md file was created and is non-empty (at least 300 characters)"
|
||||
},
|
||||
{
|
||||
"id": "has_tech_stack_section",
|
||||
"text": "Document contains a tech stack or technology section with at least Vite and TypeScript mentioned"
|
||||
},
|
||||
{
|
||||
"id": "mentions_preact_or_react",
|
||||
"text": "Document mentions Preact or preact/compat (the core framework) and the React alias or migration"
|
||||
},
|
||||
{
|
||||
"id": "has_directory_structure",
|
||||
"text": "Document includes a directory/file structure section showing the monorepo layout (packages/client and packages/shared)"
|
||||
},
|
||||
{
|
||||
"id": "mentions_connectivity",
|
||||
"text": "Document mentions the API proxy or backend connectivity (localhost:4000 or /api proxy)"
|
||||
},
|
||||
{
|
||||
"id": "has_integrations",
|
||||
"text": "Document mentions at least one external integration (Argyle, or similar third-party service)"
|
||||
},
|
||||
{
|
||||
"id": "no_database_false_positive",
|
||||
"text": "Document correctly notes this is a frontend-only project with no database layer (does not claim there is a database)"
|
||||
},
|
||||
{
|
||||
"id": "mentions_migration_context",
|
||||
"text": "Document mentions the Preact-to-React migration context or the renderer directives system as a notable gotcha"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
130
.codex/skills/codebase-overview/skill.md
Normal file
130
.codex/skills/codebase-overview/skill.md
Normal file
@@ -0,0 +1,130 @@
|
||||
---
|
||||
name: codebase-overview
|
||||
description: >
|
||||
Deeply explores a codebase or folder to understand its purpose, architecture, and
|
||||
connectivity, then writes a comprehensive OVERVIEW.md file to the project root.
|
||||
Use this skill whenever the user says "prime on", "understand the app", "document
|
||||
the codebase", "create an overview", "what does this app do", or asks for an
|
||||
OVERVIEW.md or similar documentation of a project. Trigger even if the user just
|
||||
says "prime" in the context of an active codebase. This skill is the right choice
|
||||
any time the user wants a durable, readable summary of how a project is structured
|
||||
and connected.
|
||||
---
|
||||
|
||||
|
||||
# Codebase Overview Skill
|
||||
|
||||
**If OVERVIEW.md already exists:** read it and stop. Do not read any other files, do not explore the directory tree, do not check git history. Just read OVERVIEW.md and summarize its contents to the user. That is the complete task.
|
||||
|
||||
**If OVERVIEW.md does not exist:** deeply explore the current working directory (or a path the user specifies), extract the most salient facts about the codebase, and write them to **OVERVIEW.md** in the project root.
|
||||
|
||||
The goal is a document a new developer could read on day one to understand *what the app does*, *how it's structured*, *what it connects to*, and *where the interesting parts are*. Be specific and factual — avoid vague summaries. If you find a concrete detail (a database URL format, an API endpoint, a notable architectural pattern), include it.
|
||||
|
||||
## Exploration strategy
|
||||
|
||||
Use the tools available to you to explore in parallel where possible. Here's what to look for:
|
||||
|
||||
**Start with the high-level anchors:**
|
||||
- `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` — dependencies, scripts, metadata
|
||||
- `README.md` if it exists — stated purpose
|
||||
- Main entry point (e.g. `src/main.tsx`, `app.py`, `cmd/main.go`, `index.js`)
|
||||
- Build/config files (e.g. `vite.config.*`, `webpack.config.*`, `docker-compose.yml`, `.env.example`)
|
||||
|
||||
**File and directory structure:**
|
||||
- Walk the top 2–3 levels of the directory tree
|
||||
- Identify major groupings (e.g. `routes/`, `components/`, `api/`, `db/`, `services/`)
|
||||
- Note any monorepo structure (workspaces, `packages/`, `apps/`)
|
||||
|
||||
**Tech stack:**
|
||||
- Framework(s) and runtime
|
||||
- Language(s)
|
||||
- Build tooling
|
||||
- Test framework
|
||||
|
||||
**Integrations:**
|
||||
- Third-party APIs and SDKs (look for imports, env var names, config keys)
|
||||
- Authentication providers
|
||||
- Analytics, monitoring, feature flags
|
||||
- Payment processors, messaging services, etc.
|
||||
|
||||
**Database and data layer:**
|
||||
- ORM or query library in use
|
||||
- Database type (Postgres, MySQL, SQLite, MongoDB, etc.)
|
||||
- Schema files or migration directories
|
||||
- Connection config (env var names, config files)
|
||||
|
||||
**Connectivity and configuration:**
|
||||
- `.env.example` or similar — what env vars are expected
|
||||
- API proxy config (e.g. Vite's `server.proxy`, nginx config)
|
||||
- Port numbers, base URLs, service addresses
|
||||
- Any hardcoded endpoints or service URLs in source
|
||||
|
||||
**Architecture patterns:**
|
||||
- State management approach
|
||||
- Routing strategy
|
||||
- Notable design patterns (e.g. provider pattern, command/event bus, repository pattern)
|
||||
- Anything non-obvious that would trip up a new developer
|
||||
|
||||
## OVERVIEW.md format
|
||||
|
||||
Write the file to the project root. Use this structure, but adapt section depth and detail to what's actually present — don't include empty sections:
|
||||
|
||||
```markdown
|
||||
# [App/Project Name] — Overview
|
||||
|
||||
> One-sentence description of what this app does and who uses it.
|
||||
|
||||
## Purpose
|
||||
|
||||
2–4 sentences on the domain, user-facing purpose, and any important context
|
||||
(e.g. "phase 0 of a migration from Preact to React").
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|-----------|
|
||||
| ... | ... |
|
||||
|
||||
## Directory Structure
|
||||
|
||||
Brief annotated tree of the top 2–3 levels. Only include directories and files
|
||||
that are meaningful — skip `node_modules`, lockfiles, build output, etc.
|
||||
|
||||
## Architecture
|
||||
|
||||
Key architectural patterns, data flow, and anything non-obvious. This section
|
||||
is where you explain the *how* rather than just listing what exists.
|
||||
|
||||
## Integrations
|
||||
|
||||
For each external service or API: what it is, what it's used for, and where
|
||||
in the codebase it appears.
|
||||
|
||||
## Database & Data Layer
|
||||
|
||||
ORM/library, database type, schema location, migration approach, connection config.
|
||||
If there's no database, say so (e.g. "Frontend-only — no database layer").
|
||||
|
||||
## Connectivity & Configuration
|
||||
|
||||
Expected environment variables, API proxy setup, service endpoints, ports.
|
||||
Use a table or list with variable name + purpose.
|
||||
|
||||
## Key Entry Points
|
||||
|
||||
The files a new developer should read first to understand how the app boots
|
||||
and how requests/events flow through it.
|
||||
|
||||
## Notes & Gotchas
|
||||
|
||||
Anything that would surprise a new developer: non-standard patterns, in-progress
|
||||
migrations, known tech debt worth knowing about, Preact internals being used, etc.
|
||||
```
|
||||
|
||||
## Quality bar
|
||||
|
||||
- Be specific. "Uses Postgres via Drizzle ORM, schema defined in `packages/db/schema.ts`" is better than "uses a database."
|
||||
- If something is unclear (e.g. you can see a dependency but can't find where it's used), say so briefly rather than omitting it.
|
||||
- Keep the file readable — a developer should be able to scan it in 5 minutes.
|
||||
- Don't reproduce large code blocks; reference file paths instead.
|
||||
- After writing the file, confirm to the user what was created and where.
|
||||
Reference in New Issue
Block a user