Speckit Project Agent
AI coding agent instructions for working productively in Speckit repositories that use TypeScript/Node backends and React frontends.
Overview
This skill helps you follow Speckit project conventions when contributing code to repositories using the TypeScript/Node + React stack. It covers architecture patterns, coding standards, testing requirements, and when to escalate decisions to maintainers.
Architecture Patterns
Backend (Node.js + TypeScript)
Source code lives under `server/` or `src/`Use Express or minimal frameworkless approachEntry point typically `src/index.ts` or `server/index.ts`Organize code into `controllers/`, `services/`, and `repositories/`Frontend (React + TypeScript)
Source code under `web/`, `frontend/`, or `packages/web/`Prefer Vite for new projects (minimal free-tier deployment)Alternative: create-react-app or Next.js depending on scaleMonorepo Layout
For projects with both backend and frontend:
```
/server (Node/TS backend)
/web (React/TS frontend)
package.json (root orchestration)
```
Step-by-Step Instructions
1. Initial Repository Assessment
Before making any changes:
1. Search the workspace for:
- `package.json`
- `tsconfig.json`
- `src/` or `server/` directories
- `web/` or `frontend/` directories
- `README.md`
- Test files
2. If core files are missing:
- Create minimal scaffolding aligned with TypeScript/Node + React architecture
- Ask maintainers for framework preferences before proceeding
2. Code Organization Standards
**Types and DTOs:**
Define shared types in `packages/types` or `src/types`Use explicit DTO objects for HTTP endpointsNever use implicit `any` types**Environment Configuration:**
Read config from `process.env`Provide `.env.example` or `config.example` at repository root**HTTP API Patterns:**
Use resource-based routes: `/api/items`, `/api/items/:id`Return consistent JSON structure: ```typescript
{
data: ...,
error?: {
code: string,
message: string
}
}
```
**Error Handling:**
Create centralized error middleware in Express (`src/middleware/error.ts`)Map internal errors to HTTP status codesLog errors as structured JSON3. Development Commands
**Install dependencies:**
```bash
npm install
```
**Backend development:**
```bash
cd server
npm run dev # ts-node-dev --respawn src/index.ts
```
**Frontend development:**
```bash
cd web
npm run dev # vite or react-scripts start
```
**Run tests:**
```bash
npm test # Run from root to test all packages
```
**Lint and format:**
```bash
npm run lint
npm run format
```
4. Testing Requirements
**Backend tests:**
Place tests in `tests/` directoryUse `jest` + `ts-jest` or `vitest`Test controllers, services, and repositories separately**Frontend tests:**
Use `jest` + `@testing-library/react` or `vitest` with Testing LibraryTest components in isolationMock API calls appropriately5. Code Quality Guidelines
**Do:**
Export small, well-typed functions from modulesAdd JSDoc/TSDoc comments for public functionsUse `async/await` consistently (avoid mixing callbacks and promises)Create typed client wrappers in `web/src/api/` for backend routesAdd structured logging with JSON formatInclude `requestId` headers for cross-service tracing**Don't:**
Add large dependencies without reviewMix callbacks and promisesUse dependencies incompatible with free-tier deployments6. Database Migrations
When creating database migrations:
Place migration files in `server/migrations/`Document how to run migrations in `README.md`Include rollback instructions7. CI/CD Requirements
Before creating a PR:
Run `npm run lint` locallyRun `npm test` locallyEnsure all tests passCheck that integration tests (if any) are properly gatedCI pipeline should:
Run lint checksRun all testsGate cloud service integration tests behind opt-in workflows8. Pull Request Standards
When creating PRs:
Use focused, single-purpose PRsWrite clear title and descriptionInclude checklist linking to relevant `speckit.constitution` itemsRun unit tests and linters before creating PRAssign a human reviewer**Never merge without at least one human approval**9. When to Ask Maintainers
**Scaffolding new projects:**
Preferred framework (Express/Koa/Nest/Vite/Next)CI provider choiceCoding style (Prettier/ESLint config)**Design decisions:**
Adding databases or services that increase runtime costMajor architectural changesNew framework or dependency additions**Process:**
Open a short issue or draft PRRequest guidance from maintainersFor time-sensitive infrastructure or security changes, ping on-call maintainer10. Extending These Instructions
When adding frameworks or major dependencies:
Update this documentation with canonical commandsAdd specific examples from the repositoryKeep examples minimal and focusedNotify maintainers of documentation updatesExamples
Adding a New API Route
**Backend** (`server/src/controllers/itemsController.ts`):
```typescript
export async function getItems(req: Request, res: Response) {
const items = await itemService.findAll();
res.json({ data: items });
}
```
**Frontend** (`web/src/api/items.ts`):
```typescript
export async function fetchItems(): Promise<Item[]> {
const response = await fetch('/api/items');
const { data } = await response.json();
return data;
}
```
Error Middleware
**Backend** (`server/src/middleware/error.ts`):
```typescript
export function errorHandler(
err: Error,
req: Request,
res: Response,
next: NextFunction
) {
const statusCode = err.statusCode || 500;
res.status(statusCode).json({
error: {
code: err.code || 'INTERNAL_ERROR',
message: err.message
}
});
}
```
Important Constraints
Prefer TypeScript/Node and React patterns per maintainer requestIf existing code uses a different stack, adapt to that stack and notify maintainersKeep all changes minimal and well-documentedFocus on free-tier compatible solutionsMaintain structured logging with JSON formatNever bypass human review for mergesContact & Escalation
For decisions requiring human input:
1. Open a short issue or draft PR
2. Tag relevant maintainers
3. For urgent infrastructure or security issues, contact on-call maintainer