diff --git a/AGENTS.md b/AGENTS.md index 7edc2d1..b71a40e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,8 @@ This version has breaking changes — APIs, conventions, and file structure may # AGENTS.md +**Interview Coach** is an AI-powered mock interview platform. Users select an interviewer persona, listen to a spoken question via text-to-speech, record their answer in the browser, and receive structured per-segment feedback on delivery, tone, and answer quality. The frontend (Next.js 16) orchestrates a FastAPI backend that handles all speech, emotion, and LLM processing. + Project-wide conventions, patterns, and agent instructions. `CLAUDE.md` points here. For setup, running both services, and repo structure, see the [root README](README.md). @@ -15,6 +17,31 @@ For system architecture and data flow, see [docs/architecture.md](docs/architect --- +## Development commands + +Run from `frontend/` unless noted. + +| Task | Command | +| ------------ | ------------------- | +| Dev server | `pnpm dev` → :3000 | +| Production | `pnpm build` | +| Start prod | `pnpm start` | +| Lint | `pnpm lint` | +| Type check | `pnpm typecheck` | +| Format | `pnpm format` | +| Format check | `pnpm format:check` | + +Install hooks: `pnpm install` (runs `lefthook install` via `prepare`). + +Git hooks (repo root `lefthook.yml`): + +- **pre-commit:** Prettier and Ruff format **staged** files and re-stage fixes (`stage_fixed: true`). +- **pre-push:** ESLint, Prettier check, and TypeScript on the frontend; Ruff check/format on the backend. + +Backend: `cd backend && uvicorn app:app --reload` — starts at :8000. First run downloads ~1 GB of model weights. + +--- + ## Repository instructions ### Project overview @@ -59,6 +86,7 @@ Interview-Coach/ CLAUDE.md — points to AGENTS.md docs/ architecture.md — system architecture and data flow + workflow-authoring.md — standards and template for writing workflow docs agent-workflows/ — repeatable AI agent workflow guides backend/ — FastAPI (Python), http://localhost:8000 app.py @@ -107,19 +135,63 @@ Call these from the browser via `fetch`. Do not reimplement ML, TTS, or LLM logi - `@/*` maps to the **frontend project root** (see `frontend/tsconfig.json`), e.g. `@/lib/prompts/questions`. - Prefer `@/` over deep relative paths (`../../../`). -### Hard rules (never violate) +--- + +## Architecture Constraints + +These constraints are never negotiable. Each applies project-wide and takes precedence over convenience, speed, or adjacent conventions. + +### Commit and push authorization + +Never run `git commit` or `git push` without explicit user approval. + +### Secret containment + +Do not put backend secrets or API keys in frontend code. All keys belong in `backend/.env` only. Never commit `.env` files. + +### Pipeline logic stays in backend + +Do not duplicate pipeline logic (Whisper, emotion model, TTS, LLM) in the frontend. Call backend endpoints instead. + +### Next.js navigation primitives + +Use `next/image` for images and `next/link` for internal navigation — not raw `` or `` for in-app routes. + +### Path alias preference + +Prefer `@/` imports over long relative paths (`../../../`) when the alias applies. + +### No inline style props + +No inline `style` props in JSX. Exceptions: `*.stories.tsx` for Storybook decorators; dev-only pages under `app/dev/**`. + +### CSS module requirement + +Every new component that has any of its own styles requires `ComponentName.module.css`. + +### Storybook requirement + +Every new reusable component or component with meaningful visual states requires `ComponentName.stories.tsx` with named stories and real mock data. + +### Story and style sync + +If you modify a component's structural JSX, proactively update its `.module.css` and `.stories.tsx` when those files exist. + +### AGENTS.md modification protocol + +Do not modify `AGENTS.md` without proposing the change first when the edit reflects new team conventions. -1. Never run `git commit` or `git push` without explicit user approval. -2. Do not put backend secrets or API keys in frontend code — keys belong in `backend/.env` only. -3. Do not duplicate pipeline logic (Whisper, emotion model, TTS, LLM) in the frontend; use backend endpoints. -4. Use `next/image` for images and `next/link` for internal navigation — not raw `` or `` for in-app routes. -5. Prefer `@/` imports over long relative paths when the alias applies. -6. No inline `style` props in JSX (exception: `*.stories.tsx` for Storybook decorators; dev-only pages under `app/dev/**`). -7. Every new component that has any of its own styles requires `ComponentName.module.css`. -8. Every new reusable component or component with meaningful visual states requires `ComponentName.stories.tsx` with named stories and real mock data. -9. If you modify a component's structural JSX, proactively update its `.module.css` and `.stories.tsx` when those files exist. -10. Do not modify `AGENTS.md` without proposing the change first when the edit reflects new team conventions. -11. Do not modify `backend/services/tone_delivery_analyzer/emotion_model.py` — it is marked do not modify. +### Emotion model is read-only + +Do not modify `backend/services/tone_delivery_analyzer/emotion_model.py` — it is marked do not modify. + +### Authentication (when implemented) + +When authentication is added to any route or API endpoint, the auth check MUST execute before any data access, side effect, or business logic — not at the top of a file, but at the top of the request handler. An auth bypass that is caught only at the data layer is not acceptable. + +### Database security (when implemented) + +When a database is added: always scope queries to the authenticated owner's records. Never interpolate user input into SQL strings — use parameterized queries or ORM methods only. Wrap multi-step writes in transactions. --- @@ -132,7 +204,7 @@ The interviewer voice uses the Groq Orpheus TTS model (`canopylabs/orpheus-v1-en **When to raise this proactively:** - When helping a new user set up the project - When the user reports the interviewer is silent or sees "Could not load audio" -- Before starting the project (see Running the project section below) +- Before starting the project (see below) - Any time a user adds a new `GROQ_API_KEY` to their `.env` **Guidance to give:** @@ -140,9 +212,7 @@ The interviewer voice uses the Groq Orpheus TTS model (`canopylabs/orpheus-v1-en **Symptom if skipped:** backend runs fine, `POST /speech/tts` returns 400, frontend shows "Could not load audio — check the backend is running." Recording and transcription still work; only the voice is affected. ---- - -## Running the project (agent-driven) +### Starting the project When the user says any of the following — **"run the project"**, **"run the interview coach"**, **"start the project"**, **"start interview coach"**, **"start the app"**, **"launch the project"**, or any close variation — the agent must first confirm with the user: @@ -167,31 +237,6 @@ Only after the user confirms, follow `docs/agent-workflows/run-project.md` exact --- -## Development commands - -Run from `frontend/` unless noted. - -| Task | Command | -| ------------ | ------------------- | -| Dev server | `pnpm dev` → :3000 | -| Production | `pnpm build` | -| Start prod | `pnpm start` | -| Lint | `pnpm lint` | -| Type check | `pnpm typecheck` | -| Format | `pnpm format` | -| Format check | `pnpm format:check` | - -Install hooks: `pnpm install` (runs `lefthook install` via `prepare`). - -Git hooks (repo root `lefthook.yml`): - -- **pre-commit:** Prettier and Ruff format **staged** files and re-stage fixes (`stage_fixed: true`). -- **pre-push:** ESLint, Prettier check, and TypeScript on the frontend; Ruff check/format on the backend. - -Backend: `cd backend && uvicorn app:app --reload` — starts at :8000. First run downloads ~1 GB of model weights. - ---- - ## Environment variables All secrets live in `backend/.env` (gitignored). See [backend/.env.example](backend/.env.example). @@ -317,24 +362,50 @@ After features or conventions change, update this file: - New backend endpoints → **Backend integration** - New pnpm scripts → **Development commands** - New env vars → **Environment variables** -- New hard rules or team decisions → **Hard rules** +- New hard rules or team decisions → **Architecture Constraints** -For task-specific reviews, use workflows in `docs/agent-workflows/`. Invoke explicitly, e.g.: +For task-specific reviews, use workflows in `docs/agent-workflows/`. For authoring standards and the required document structure, see [docs/workflow-authoring.md](docs/workflow-authoring.md). + +### Workflow Library + +| Workflow | Use when | +| -------------------- | ---------------------------------------------- | +| `merge-review.md` | Full pre-merge review with phase gates | +| `branch-audit.md` | What changed and regression risks vs `main` | +| `code-review.md` | Correctness, conventions, API integration | +| `css-review.md` | module.css, Tailwind placement, Storybook | +| `test-review.md` | Test simplicity (or Storybook if no tests yet) | +| `qa-checklist.md` | Manual QA for recording/scorecard flows | +| `pr-description.md` | PR title and description from diff | +| `feature-plan.md` | Plan before non-trivial features | +| `flag-review.md` | Env/flag gating completeness | +| `figma-to-code.md` | Implement UI from Figma | +| `run-project.md` | Start backend + frontend from scratch | + +### Invocation + +Invoke workflows explicitly. Examples: ``` -Use docs/agent-workflows/pull-request-description-generator.md for this branch. -``` +Use docs/agent-workflows/merge-review.md and run a complete pre-merge review of this branch. + +Use docs/agent-workflows/branch-audit.md and audit what changed on this branch against main. + +Use docs/agent-workflows/code-review.md and perform a strict code quality review of this branch against main. + +Use docs/agent-workflows/css-review.md and review all styling and component changes in this branch. + +Use docs/agent-workflows/test-review.md and review the existing test suite for simplicity and overengineering. -| Workflow | Use when | -| --------------------------------------- | ---------------------------------------------- | -| `pre-merge-full-review.md` | Full pre-merge review with phase gates | -| `branch-change-impact-audit.md` | What changed and regression risks vs `main` | -| `code-quality-review.md` | Correctness, conventions, API integration | -| `css-and-component-standards-review.md` | module.css, Tailwind placement, Storybook | -| `test-suite-quality-review.md` | Test simplicity (or Storybook if no tests yet) | -| `manual-qa-checklist-generator.md` | Manual QA for recording/scorecard flows | -| `pull-request-description-generator.md` | PR title and description from diff | -| `feature-implementation-planning.md` | Plan before non-trivial features | -| `feature-flag-gating-review.md` | Env/flag gating completeness | -| `figma-design-to-code.md` | Implement UI from Figma | -| `run-project.md` | Start backend + frontend from scratch | +Use docs/agent-workflows/qa-checklist.md and generate a concise manual QA checklist for the current diff. + +Use docs/agent-workflows/pr-description.md and generate PR-ready text for the current branch against main. + +Use docs/agent-workflows/feature-plan.md and create an implementation plan for this feature before writing code. + +Use docs/agent-workflows/flag-review.md and verify that this feature flag fully controls the new behavior and supports rollback. + +Use docs/agent-workflows/figma-to-code.md and implement this Figma design. + +Use docs/agent-workflows/run-project.md and start the project. +``` diff --git a/docs/agent-workflows/README.md b/docs/agent-workflows/README.md index 0004211..5147c10 100644 --- a/docs/agent-workflows/README.md +++ b/docs/agent-workflows/README.md @@ -37,51 +37,54 @@ Tell the agent which workflow file to use and what task to perform. Example: ```md -Use `docs/agent-workflows/pull-request-description-generator.md` and generate PR-ready text for this branch against `main`. +Use `docs/agent-workflows/pr-description.md` and generate PR-ready text for this branch against `main`. ``` ### Copy/paste prompt examples ``` -Use docs/agent-workflows/pre-merge-full-review.md and run a complete pre-merge review of this branch. +Use docs/agent-workflows/merge-review.md and run a complete pre-merge review of this branch. -Use docs/agent-workflows/branch-change-impact-audit.md and audit what changed on this branch against main. +Use docs/agent-workflows/branch-audit.md and audit what changed on this branch against main. -Use docs/agent-workflows/code-quality-review.md and perform a strict code quality review of this branch against main. +Use docs/agent-workflows/code-review.md and perform a strict code quality review of this branch against main. -Use docs/agent-workflows/css-and-component-standards-review.md and review all styling and component changes in this branch. +Use docs/agent-workflows/css-review.md and review all styling and component changes in this branch. -Use docs/agent-workflows/test-suite-quality-review.md and review the existing test suite for simplicity and overengineering. +Use docs/agent-workflows/test-review.md and review the existing test suite for simplicity and overengineering. -Use docs/agent-workflows/feature-flag-gating-review.md and verify that this feature flag fully controls the new behavior and supports rollback. +Use docs/agent-workflows/flag-review.md and verify that this feature flag fully controls the new behavior and supports rollback. -Use docs/agent-workflows/manual-qa-checklist-generator.md and generate a concise manual QA checklist for the current diff. +Use docs/agent-workflows/qa-checklist.md and generate a concise manual QA checklist for the current diff. -Use docs/agent-workflows/pull-request-description-generator.md and generate PR-ready text for the current branch against main. +Use docs/agent-workflows/pr-description.md and generate PR-ready text for the current branch against main. -Use docs/agent-workflows/feature-implementation-planning.md and create an implementation plan for this feature before writing code. +Use docs/agent-workflows/feature-plan.md and create an implementation plan for this feature before writing code. -Use docs/agent-workflows/figma-design-to-code.md and implement this Figma design. +Use docs/agent-workflows/figma-to-code.md and implement this Figma design. + +Use docs/agent-workflows/run-project.md and start the project. ``` ## Workflows -| File | What it does | What it does NOT do | -| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| `pre-merge-full-review.md` | Orchestrates review phases with user checkpoints and a mandatory PR-description decision | Performs review logic itself — delegates to sub-workflows | -| `branch-change-impact-audit.md` | Surveys what changed, behavior impact, regression risks, integration consistency | Assesses code quality, CSS, or test quality | -| `code-quality-review.md` | Reviews implementation correctness, performance, backend API usage, new route security, conventions, architecture, and React patterns | Summarizes what changed; deep CSS review | -| `css-and-component-standards-review.md` | CSS quality, module.css compliance, Tailwind-vs-module.css placement, design token usage, Storybook story coverage | Business logic, JS correctness | -| `test-suite-quality-review.md` | Reviews test simplicity, readability, and appropriate scope | Checks coverage gaps in new code; runs tests | -| `feature-flag-gating-review.md` | Verifies flag fully controls behavior and supports clean rollback | General code quality outside flag gating | -| `manual-qa-checklist-generator.md` | Generates a manual QA checklist scoped to the branch diff | Automates testing; reviews code | -| `pull-request-description-generator.md` | Generates PR-ready text — summary, change-overview table, grouped file-by-file changes, dependency declaration, env var callouts, migration notes, linked tickets | Reviews or recommends anything | -| `feature-implementation-planning.md` | Creates an implementation plan covering scope, schema changes, complete file manifest, implementation order, integration points, and verification steps | Writes code; reviews existing code | -| `figma-design-to-code.md` | Guides Figma design extraction, token mapping, and component implementation | Reviews existing code independently | -| `run-project.md` | Starts backend + frontend from scratch; assesses project state and runs only what is needed; also handles stopping the project | Requires user terminal input | +| File | What it does | What it does NOT do | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | +| `merge-review.md` | Orchestrates review phases with user checkpoints and a mandatory PR-description decision | Performs review logic itself — delegates to sub-workflows | +| `branch-audit.md` | Surveys what changed, behavior impact, regression risks, integration consistency | Assesses code quality, CSS, or test quality | +| `code-review.md` | Reviews implementation correctness, performance, backend API usage, new route security, conventions, architecture, and React patterns | Summarizes what changed; deep CSS review | +| `css-review.md` | CSS quality, module.css compliance, Tailwind-vs-module.css placement, design token usage, Storybook story coverage | Business logic, JS correctness | +| `test-review.md` | Reviews test simplicity, readability, and appropriate scope | Checks coverage gaps in new code; runs tests | +| `flag-review.md` | Verifies flag fully controls behavior and supports clean rollback | General code quality outside flag gating | +| `qa-checklist.md` | Generates a manual QA checklist scoped to the branch diff | Automates testing; reviews code | +| `pr-description.md` | Generates PR-ready text — summary, change-overview table, grouped file-by-file changes, dependency declaration, env var callouts, migration notes, linked tickets | Reviews or recommends anything | +| `feature-plan.md` | Creates an implementation plan covering scope, schema changes, complete file manifest, implementation order, integration points, and verification steps | Writes code; reviews existing code | +| `figma-to-code.md` | Guides Figma design extraction, token mapping, and component implementation | Reviews existing code independently | +| `run-project.md` | Starts backend + frontend from scratch; assesses project state and runs only what is needed; also handles stopping the project | Requires user terminal input | ## Maintenance - Update these files when the team changes the workflow requirements or output formats - Treat these files as the canonical version rather than maintaining separate copies in multiple agent-specific files - When adding a new workflow, add it to this README and the workflow section in `AGENTS.md` +- For authoring standards and the required document structure, see [docs/workflow-authoring.md](../workflow-authoring.md) diff --git a/docs/agent-workflows/branch-change-impact-audit.md b/docs/agent-workflows/branch-audit.md similarity index 86% rename from docs/agent-workflows/branch-change-impact-audit.md rename to docs/agent-workflows/branch-audit.md index 660ec29..8dae944 100644 --- a/docs/agent-workflows/branch-change-impact-audit.md +++ b/docs/agent-workflows/branch-audit.md @@ -1,10 +1,18 @@ -# Branch Change Impact Audit +# Branch Audit ## Purpose -Surveys the current branch against `main` to answer: **what changed, which behavior is affected, and are there regression or integration risks?** Produces a factual map of the change set before any quality review begins. When feature flag changes are detected, offers to run `feature-flag-gating-review.md` before continuing. +Surveys the current branch against `main` to answer: **what changed, which behavior is affected, and are there regression or integration risks?** Produces a factual map of the change set before any quality review begins. When feature flag changes are detected, offers to run `flag-review.md` before continuing. -**Does not:** assess code quality, correctness of implementation, CSS standards, or test quality. Does not propose redesigns or broad fixes — it identifies and describes, it does not prescribe. Code quality is covered by `code-quality-review.md`. +**Does not:** assess code quality, correctness of implementation, CSS standards, or test quality. Does not propose redesigns or broad fixes — it identifies and describes, it does not prescribe. Code quality is covered by `code-review.md`. + +--- + +## Preparation + +- Read `AGENTS.md` to load project conventions, architecture, and pipeline overview. +- Run `git diff --name-only origin/main...HEAD` to enumerate changed files. +- Run `git log --oneline origin/main..HEAD` to understand commit intent. --- @@ -43,7 +51,7 @@ If the diff introduces or modifies `NEXT_PUBLIC_*` env vars used for behavioral - Note which files and call sites are involved - Ask the user: "Behavioral gating changes detected. Would you like me to run the feature flag gating review before continuing the audit?" -- If the user says yes, read and run `docs/agent-workflows/feature-flag-gating-review.md` and include its output as a subsection before continuing +- If the user says yes, read and run `docs/agent-workflows/flag-review.md` and include its output as a subsection before continuing - If the user says no, note it and continue the audit without the flag review This project has no formal feature flag registry. Simple UI state variables like `feedbackMode` do not require this review unless their branching logic is complex. @@ -65,7 +73,7 @@ Check for: - Do not recommend unrelated cleanup - Keep recommendations minimal and limited to what is necessary to restore the intended behavior -## Required output format +## Output ### Branch summary diff --git a/docs/agent-workflows/code-quality-review.md b/docs/agent-workflows/code-review.md similarity index 97% rename from docs/agent-workflows/code-quality-review.md rename to docs/agent-workflows/code-review.md index d3f818b..f4751a1 100644 --- a/docs/agent-workflows/code-quality-review.md +++ b/docs/agent-workflows/code-review.md @@ -1,10 +1,10 @@ -# Code Quality Review +# Code Review ## Purpose Reviews the **quality of the implementation** — correctness, performance, architectural conventions, React patterns, and test coverage gaps. When component or styling files are detected, offers to run the CSS and component standards review. -**Does not:** summarize what changed on the branch (that is `branch-change-impact-audit.md`). Does not audit feature flag gating, generate QA checklists, or perform deep CSS/styling review independently. Those are separate workflows. +**Does not:** summarize what changed on the branch (that is `branch-audit.md`). Does not audit feature flag gating, generate QA checklists, or perform deep CSS/styling review independently. Those are separate workflows. --- @@ -17,7 +17,7 @@ Perform a strict, scoped code quality review of a feature branch. - Do not invent issues - State issues plainly and specifically — do not soften findings with hedging language or qualify every point with "consider" or "you might want to" -## Before review +## Preparation - Read `AGENTS.md` (and [README.md](../../README.md) for full-stack context) to load project conventions, hard rules, and architecture patterns - Read commit messages or the PR description to understand the intent of the changes @@ -205,7 +205,7 @@ Changed files are those returned by `git diff --name-only origin/main...HEAD` (o If a command is unavailable or fails to execute, state which one and why. -## Required output format +## Output ### Context @@ -264,7 +264,7 @@ Check the changed file list for any `.tsx`, `.jsx`, `.module.css`, or `.stories. If any are present, ask the user: "Component or styling files were changed. Would you like me to run the CSS and component standards review now?" -- If yes, read and run `docs/agent-workflows/css-and-component-standards-review.md` and present its output as a separate section. +- If yes, read and run `docs/agent-workflows/css-review.md` and present its output as a separate section. - If no, note that the CSS review was declined and conclude. If no component or styling files are present, state "No component or styling files changed — CSS review not applicable" and conclude. diff --git a/docs/agent-workflows/css-and-component-standards-review.md b/docs/agent-workflows/css-review.md similarity index 98% rename from docs/agent-workflows/css-and-component-standards-review.md rename to docs/agent-workflows/css-review.md index cc617f6..caeafa0 100644 --- a/docs/agent-workflows/css-and-component-standards-review.md +++ b/docs/agent-workflows/css-review.md @@ -1,22 +1,22 @@ -# CSS and Component Standards Review +# CSS Review ## Purpose Reviews **CSS quality, module.css compliance, Tailwind-vs-module.css placement, design token usage, and Storybook story coverage** for new or modified components. Flags missing `module.css` files, missing stories, inline styles, and hard-coded values as critical issues. -**Does not:** review business logic, JS correctness, or anything outside styling and component file compliance. Code correctness is covered by `code-quality-review.md`. +**Does not:** review business logic, JS correctness, or anything outside styling and component file compliance. Code correctness is covered by `code-review.md`. --- Review all styling related to a branch with a strict focus on CSS quality, maintainability, consistency, and correctness. -## Before review +## Preparation - Read `AGENTS.md` to load project styling conventions and hard rules - Run `git diff --name-only origin/main...HEAD` to enumerate changed files (substitute the confirmed target branch if not `main`) - Read adjacent component styles to understand existing patterns before flagging inconsistencies -## Review scope +## Scope From the changed files, review: @@ -180,7 +180,7 @@ Check whether: - Do not accept "it's a simple component" as justification for skipping `.module.css` or stories - When the same issue appears in multiple places, flag it once and note how many occurrences exist — do not list every instance individually -## Required output format +## Output ### Findings diff --git a/docs/agent-workflows/feature-implementation-planning.md b/docs/agent-workflows/feature-plan.md similarity index 64% rename from docs/agent-workflows/feature-implementation-planning.md rename to docs/agent-workflows/feature-plan.md index 5751723..567633c 100644 --- a/docs/agent-workflows/feature-implementation-planning.md +++ b/docs/agent-workflows/feature-plan.md @@ -1,4 +1,4 @@ -# Feature Implementation Planning +# Feature Plan ## Purpose @@ -8,9 +8,10 @@ Produces a **structured implementation plan before any code is written** for non --- -## Before planning +## Preparation -**Confirm tracking (optional).** Before producing the plan, ask whether there is a GitHub issue or ticket to reference. Record it in the plan header if provided. Do not block planning if there is none. +- Read `AGENTS.md` to load project architecture, backend integration contracts, and file/component conventions. +- Confirm tracking (optional): ask whether there is a GitHub issue or ticket to reference. Record it in the plan header if provided. Do not block planning if there is none. --- @@ -42,6 +43,21 @@ Group files by category such as: - Storybook stories (no test runner configured; stories are the coverage mechanism) - docs (`backend/README.md`, `AGENTS.md` if conventions change) -## Usage +## Output -Use this workflow for planning-heavy work. Do not treat it as a requirement for every trivial edit or small isolated fix. +The plan must include, in order: + +1. **Header** — feature name, optional issue/ticket reference +2. **Context** — why the change is being made +3. **Backend API changes** — new or changed routes, schemas, env vars +4. **File manifest** — every new or changed file, grouped by category (see File manifest guidance above) +5. **Implementation order** — phased sequence of work +6. **Integration points** — where the new code connects to existing systems +7. **Verification** — how to validate end to end + +## Constraints + +- Do not write code as part of the plan output +- Do not make implementation decisions without user input on ambiguous scope +- Do not treat this workflow as required for trivial single-file edits +- Do not begin implementation before the plan is presented and confirmed diff --git a/docs/agent-workflows/figma-design-to-code.md b/docs/agent-workflows/figma-to-code.md similarity index 78% rename from docs/agent-workflows/figma-design-to-code.md rename to docs/agent-workflows/figma-to-code.md index 131060a..cc4dba5 100644 --- a/docs/agent-workflows/figma-design-to-code.md +++ b/docs/agent-workflows/figma-to-code.md @@ -1,31 +1,22 @@ -# Figma Design to Code +# Figma to Code ## Purpose Guides **implementation of UI from a Figma design** — extracting designs via MCP tools, adapting reference code to the Interview Coach frontend stack, mapping design tokens to `app/globals.css`, and verifying component compliance before marking work complete. -**Does not:** review existing code, perform standalone CSS review, or assess code quality independently of a design task. Styling and component standards are defined in `AGENTS.md` and `css-and-component-standards-review.md` — this workflow references those standards rather than restating them. +**Does not:** review existing code, perform standalone CSS review, or assess code quality independently of a design task. Styling and component standards are defined in `AGENTS.md` and `css-review.md` — this workflow references those standards rather than restating them. --- Use this workflow when implementing UI from a Figma design, extracting design tokens, or auditing a component against its Figma spec. -## Access +## Preparation +- Read `AGENTS.md` to load component conventions (module.css, stories, Tailwind usage rules). +- Obtain the Figma URL from the user; extract the file key and node ID. - **Token:** `FIGMA_PERSONAL_ACCESS_TOKEN` (or the env var your Figma MCP server expects) — set locally or via your agent secrets; never commit tokens. -- **Design file:** Use the file key and node id from the Figma URL the user provides. This project does not ship a canonical design-system file key in-repo. -- **MCP server:** Prefer Figma MCP tools over direct REST when both can accomplish the task. -- **Token verification:** Before starting, confirm the token works (`GET https://api.figma.com/v1/me` with `X-Figma-Token`, or the MCP equivalent). If access fails, stop and ask the user to confirm project access. - -## Getting a node ID from a Figma URL - -``` -figma.com/design/:fileKey/:fileName?node-id=:nodeId -``` - -Convert `-` to `:` in the node ID (e.g. `123-456` → `123:456`). - -FigJam: `figma.com/board/:fileKey/...` — use `get_figjam`. +- **Token verification:** Confirm the token works (`GET https://api.figma.com/v1/me` with `X-Figma-Token`, or the MCP equivalent). If access fails, stop and ask the user to confirm project access. +- **Node ID format:** from `figma.com/design/:fileKey/:fileName?node-id=:nodeId` — convert `-` to `:` (e.g. `123-456` → `123:456`). For FigJam (`figma.com/board/:fileKey/...`) use `get_figjam`. ## Preferred tools @@ -81,7 +72,7 @@ Wait for user confirmation when reuse vs new component is ambiguous. ### Step 5 — Implement -Follow `AGENTS.md` and `css-and-component-standards-review.md` for file layout, Storybook states (recording, processing, scorecard, errors), and presentational/container split. +Follow `AGENTS.md` and `css-review.md` for file layout, Storybook states (recording, processing, scorecard, errors), and presentational/container split. **Responsive:** Ask how breakpoints should behave; do not infer from fixed-width Figma frames. @@ -102,7 +93,7 @@ Confirm each new component has `module.css` (when styled) and `stories.tsx` with 3. List discrepancies (node id, expected vs actual) 4. Minimal fix in module CSS or Tailwind — no unrelated redesign -## Output format +## Output - Figma file key and node id - Tools used and Code Connect hits/misses @@ -117,3 +108,11 @@ Confirm each new component has `module.css` (when styled) and `stories.tsx` with - [ ] All meaningful visual states have Storybook stories with mock data - [ ] No inline `style` in product JSX - [ ] New components have `.module.css` when they own styles and `.stories.tsx` when they have visual states + +## Constraints + +- Do not review or refactor existing code unrelated to the Figma design task +- Do not commit Figma access tokens or API keys +- Do not hard-code raw hex/spacing values when a CSS token exists in `globals.css` +- Do not infer responsive breakpoints from fixed-width Figma frames — ask the user +- Do not use raw `` or `` tags — use `next/image` and `next/link` diff --git a/docs/agent-workflows/feature-flag-gating-review.md b/docs/agent-workflows/flag-review.md similarity index 89% rename from docs/agent-workflows/feature-flag-gating-review.md rename to docs/agent-workflows/flag-review.md index b7d35da..461dc0a 100644 --- a/docs/agent-workflows/feature-flag-gating-review.md +++ b/docs/agent-workflows/flag-review.md @@ -1,10 +1,10 @@ -# Feature Flag Gating Review +# Flag Review ## Purpose Verifies that a feature flag **fully controls the intended behavior** and supports clean rollback — no bypassed call sites, no partial gating, no hidden dependencies that prevent the flag from acting as a true on/off switch. -**Does not:** review general code quality, correctness of implementation outside flag gating, CSS, or test quality. Only code paths and dependencies related to the flag are in scope. General code quality is covered by `code-quality-review.md`. +**Does not:** review general code quality, correctness of implementation outside flag gating, CSS, or test quality. Only code paths and dependencies related to the flag are in scope. General code quality is covered by `code-review.md`. --- @@ -15,17 +15,25 @@ This project has no formal feature flag system or flag registry. Apply this work - A new `NEXT_PUBLIC_*` env var is introduced that gates behavior (not just configures an API URL like `NEXT_PUBLIC_API_URL`) - A new behavioral mode is added that must cleanly support rollback (e.g., a new `feedbackMode` variant or a new interview flow toggle) -For simple API configuration env vars and pure UI state variables like `feedbackMode` (perQuestion/endOfInterview), this review is optional unless the behavior branch is complex enough to warrant verification. When in doubt, use `code-quality-review.md` instead. +For simple API configuration env vars and pure UI state variables like `feedbackMode` (perQuestion/endOfInterview), this review is optional unless the behavior branch is complex enough to warrant verification. When in doubt, use `code-review.md` instead. When running this review: treat the env var or toggle as the "flag." The flag registry check does not apply — there is no registry in this project. --- +## Preparation + +- Read `AGENTS.md` to load project conventions and pipeline architecture. +- Run `git diff --name-only origin/main...HEAD` to enumerate changed files. +- Identify the flag or env var under review from the diff before proceeding. + +--- + ## Goal Verify that a feature flag cleanly separates the enabled and disabled behaviors without mixed-mode execution, bypassed call sites, or hidden dependencies. -## Review scope +## Scope - Review the current branch against `main` (or the confirmed target branch) - Inspect all changed files and directly affected call sites related to the flagged behavior @@ -76,7 +84,7 @@ Check for: - Do not propose broad redesigns - Keep recommendations limited to the minimal corrections needed for complete gating -## Required output format +## Output ### Flag summary diff --git a/docs/agent-workflows/pre-merge-full-review.md b/docs/agent-workflows/merge-review.md similarity index 97% rename from docs/agent-workflows/pre-merge-full-review.md rename to docs/agent-workflows/merge-review.md index 70ecb6d..5d05e28 100644 --- a/docs/agent-workflows/pre-merge-full-review.md +++ b/docs/agent-workflows/merge-review.md @@ -1,4 +1,4 @@ -# Pre-Merge Full Review +# Merge Review ## Purpose @@ -436,7 +436,7 @@ The principle: silence is the default for unchanged code. Speak about adjacent c --- -## Before starting +## Preparation 1. Read `AGENTS.md` and the root [README.md](../../README.md) to load conventions, hard rules, and architecture. @@ -544,29 +544,29 @@ If any of steps 1–4 are skipped, the phase output is invalid and must be redon --- -## Phase 1 — Branch change impact audit (`branch-change-impact-audit.md`) +## Phase 1 — Branch change impact audit (`branch-audit.md`) Always run. Establishes the scope and intent of the branch before any other review begins. 1. Run the Phase 1 deterministic floor (see Phase deterministic check list above). -2. Read `docs/agent-workflows/branch-change-impact-audit.md` in full and run the branch audit it defines. +2. Read `docs/agent-workflows/branch-audit.md` in full and run the branch audit it defines. 3. Add subjective observations only if the sub-workflow doc calls for them. 4. Print phase narrative + Session State Block + Gate Block (with Coverage report). Stop. Note: if feature flag changes are detected during Phase 1, the branch audit workflow will ask the user whether to run the feature flag gating review inline. If the user accepts, that review runs as part of Phase 1 and Phase 5 will be skipped (record this in the Session State Block). -## Phase 2 — Code quality review (`code-quality-review.md`) +## Phase 2 — Code quality review (`code-review.md`) Always run. Apply to all changed `.ts`, `.tsx`, `.js`, and `.jsx` files. 1. Run the Phase 2 deterministic floor: type-check, lint, prettier (if configured), build (if configured), and the pattern checks listed in the Phase deterministic check list section. Capture every command's exit code and relevant output. -2. Read `docs/agent-workflows/code-quality-review.md` in full and run any additional checks it defines, treating them as additional deterministic items. +2. Read `docs/agent-workflows/code-review.md` in full and run any additional checks it defines, treating them as additional deterministic items. 3. Only after the deterministic floor is complete, add subjective observations (naming, structure, suggested refactors, etc.) — each labeled `Subjective`. 4. Print phase narrative + Session State Block + Gate Block (with Coverage report). Stop. Note: at the end of Phase 2, the code quality review may ask whether to run the CSS and component standards review. If the user accepts, that review runs as part of Phase 2 and Phase 3 will be skipped (record this in the Session State Block). -## Phase 3 — CSS and component standards review (`css-and-component-standards-review.md`) +## Phase 3 — CSS and component standards review (`css-review.md`) If the CSS review was already completed during Phase 2, print the Session State Block, tell the user "Phase 3 already completed during Phase 2 — see CSS review output above," and ask if they are ready to move to Phase 4. Stop. @@ -581,11 +581,11 @@ If not applicable, print the Session State Block, tell the user "Phase 3 skipped Otherwise: 1. Run the Phase 3 deterministic floor (stylelint if configured, inline-style pattern check, hardcoded-color/spacing pattern check). -2. Read `docs/agent-workflows/css-and-component-standards-review.md` in full and run additional checks it defines. +2. Read `docs/agent-workflows/css-review.md` in full and run additional checks it defines. 3. Add subjective observations after deterministic checks, each labeled `Subjective`. 4. Print phase narrative + Session State Block + Gate Block (with Coverage report). Stop. -## Phase 4 — Test suite quality review (`test-suite-quality-review.md`) +## Phase 4 — Test suite quality review (`test-review.md`) Run if any of the following are true: @@ -597,11 +597,11 @@ If not applicable, print the Session State Block, tell the user "Phase 4 skipped Otherwise: 1. Run the Phase 4 deterministic floor: `pnpm test` is not configured — record "not configured — skipped"; run Storybook story coverage check on new/modified components; pattern check for `.skip` / `.only` / `xit` / `xdescribe` in story files. -2. Read `docs/agent-workflows/test-suite-quality-review.md` in full and run any additional checks it defines. +2. Read `docs/agent-workflows/test-review.md` in full and run any additional checks it defines. 3. Add subjective observations after deterministic checks (story naming, state coverage, missing edge-case stories), each labeled `Subjective`. 4. Print phase narrative + Session State Block + Gate Block (with Coverage report). Stop. -## Phase 5 — Feature flag gating review (`feature-flag-gating-review.md`) +## Phase 5 — Feature flag gating review (`flag-review.md`) If the feature flag review was already completed during Phase 1, print the Session State Block, tell the user "Phase 5 already completed during Phase 1 — see flag review output above," and ask if they are ready to move to Phase 6. Stop. @@ -612,7 +612,7 @@ If not applicable, print the Session State Block, tell the user "Phase 5 skipped Otherwise: 1. Run the Phase 5 deterministic floor: flag-off-path verifiability check (grep for flag identifier, confirm else branch exists), new-flag-in-registry check. -2. Read `docs/agent-workflows/feature-flag-gating-review.md` in full and run any additional checks it defines. +2. Read `docs/agent-workflows/flag-review.md` in full and run any additional checks it defines. 3. Add subjective observations after deterministic checks, each labeled `Subjective`. 4. Print phase narrative + Session State Block + Gate Block (with Coverage report). Stop. @@ -629,7 +629,7 @@ Treat documentation inaccuracies as Phase findings under the rules above — fix --- -## Phase 6 — PR description (`pull-request-description-generator.md`) +## Phase 6 — PR description (`pr-description.md`) **Mandatory step. Always ask. Never skip the decision.** This is a pre-merge workflow; the PR-description decision is part of the required flow. The developer may decline generation, but you may not assume they don't want it and you may not end the workflow without an explicit generate-or-skip reply. @@ -658,7 +658,7 @@ I will not generate the PR description and I will not end the workflow until you After printing this prompt, the response ends. Stop. -**If the user says generate:** Confirm the Unresolved count is zero. If it is not, return to the relevant phase gate and resolve those findings first — do not generate a PR description with unresolved findings. Once clear, read `docs/agent-workflows/pull-request-description-generator.md` in full and generate the PR description following that workflow exactly. +**If the user says generate:** Confirm the Unresolved count is zero. If it is not, return to the relevant phase gate and resolve those findings first — do not generate a PR description with unresolved findings. Once clear, read `docs/agent-workflows/pr-description.md` in full and generate the PR description following that workflow exactly. **If the user says skip:** Acknowledge briefly, print a final Session State Block summarizing what was done, and end the workflow. Do not lobby to generate it anyway. diff --git a/docs/agent-workflows/pull-request-description-generator.md b/docs/agent-workflows/pr-description.md similarity index 98% rename from docs/agent-workflows/pull-request-description-generator.md rename to docs/agent-workflows/pr-description.md index 1d110b7..800e6b4 100644 --- a/docs/agent-workflows/pull-request-description-generator.md +++ b/docs/agent-workflows/pr-description.md @@ -1,4 +1,4 @@ -# Pull Request Description Generator +# PR Description ## Purpose @@ -8,6 +8,13 @@ Generates **PR-ready text** — a dependency declaration, a one-paragraph summar --- +## Preparation + +- Read `AGENTS.md` to confirm the project's target branch convention (default: `main`). +- The "Context isolation" and "Inputs required" sections below serve as the operational preparation steps — follow them in order before generating any output. + +--- + ## Context isolation (must happen first) This workflow must operate on the final diff in a clean context. Prior conversation, earlier commits, scratch work, or discussion of approaches that were tried and abandoned must not influence the output. PR reviewers see only the final diff and have no knowledge of what came before — describing anything they cannot see in the diff creates confusion. @@ -68,7 +75,7 @@ Do not ask separate questions for target branch, branch base, or detected ticket --- -## Strict rules +## Constraints - Use only the actual final diff between the current branch and the confirmed target branch - Do not mention anything that may have been added and later removed during development — reviewers only see the final diff and cannot follow references to code that no longer exists @@ -85,7 +92,7 @@ Do not ask separate questions for target branch, branch base, or detected ticket --- -## Required output format +## Output Inside the single markdown code block, format the response exactly like this: diff --git a/docs/agent-workflows/manual-qa-checklist-generator.md b/docs/agent-workflows/qa-checklist.md similarity index 91% rename from docs/agent-workflows/manual-qa-checklist-generator.md rename to docs/agent-workflows/qa-checklist.md index 4ab1aef..cc90132 100644 --- a/docs/agent-workflows/manual-qa-checklist-generator.md +++ b/docs/agent-workflows/qa-checklist.md @@ -1,10 +1,17 @@ -# Manual QA Checklist Generator +# QA Checklist ## Purpose Generates a **practical, scoped manual testing checklist** based on the current branch diff — preconditions, primary success-path scenarios, edge cases, and mode-dependent checks. Produces a guide a developer or reviewer can run by hand. -**Does not:** automate testing, run test commands, review code quality, or produce a comprehensive test plan. Scope is strictly manual verification of the changed behavior — automated test quality is covered by `test-suite-quality-review.md`. +**Does not:** automate testing, run test commands, review code quality, or produce a comprehensive test plan. Scope is strictly manual verification of the changed behavior — automated test quality is covered by `test-review.md`. + +--- + +## Preparation + +- Read `AGENTS.md` to load pipeline architecture and feedback mode definitions. +- Run `git diff --name-only origin/main...HEAD` to enumerate changed files and understand the scope of the diff. --- @@ -55,7 +62,7 @@ Also include checks for the full scorecard rendering path: DeliveryScores (arous - Do not include low-value or purely theoretical checks - Do not expand into a full test plan unless explicitly requested -## Required output format +## Output ### Setup diff --git a/docs/agent-workflows/run-project.md b/docs/agent-workflows/run-project.md index a267577..02f22cf 100644 --- a/docs/agent-workflows/run-project.md +++ b/docs/agent-workflows/run-project.md @@ -1,8 +1,16 @@ -# Run Project Workflow +# Run Project -**Trigger phrases:** "run the project", "run the interview coach", "run the interview project", "start the project", "start interview coach", "start the app", "launch the project", or any close variation. +## Purpose -**Before running anything**, the agent must confirm with the user: +Starts the Interview Coach backend (port 8000) and frontend (port 3000) from a clean state — detecting OS, verifying prerequisites, fixing what is missing, and reporting both URLs once both services are running. + +**Does not:** modify application code, manage deployments, or run tests. Scope is exclusively starting the local development stack. + +--- + +## Preparation + +Before running anything, the agent must confirm with the user: > "Ready to start Interview Coach. This will launch the backend (port 8000) and frontend (port 3000). > Before I start — have you accepted the Groq Orpheus TTS terms for your account? This is required for the interviewer voice. Visit https://console.groq.com/playground?model=canopylabs%2Forpheus-v1-english to accept if you haven't yet. @@ -14,6 +22,17 @@ Only after the user confirms does the agent proceed. The agent starts both servi --- +## Constraints + +- **Hard stop — missing env:** If `backend/.env` is missing or `GROQ_API_KEY` is not set, tell the user and do not start. +- **Hard stop — unknown port occupant:** If port 8000 or 3000 is occupied by an unrecognized process, identify the process and ask the user before killing it. +- **Hard stop — missing OS prerequisites:** Python, Node.js, pnpm, and ffmpeg must all pass before touching project setup. Tell the user and stop if any are missing. +- Do not start the frontend before `Application startup complete` is confirmed from the backend. +- Do not run `git commit` or `git push` as part of this workflow. +- Do not modify `backend/services/tone_delivery_analyzer/emotion_model.py`. + +--- + ## Step 1 — Detect OS and terminal Run this first. Every subsequent step uses platform-specific commands — do not skip this. @@ -317,6 +336,19 @@ If the emotion model is downloading for the first time, note that the backend wi --- +## Output + +Once both services are confirmed running, report exactly: + +``` +Backend: http://localhost:8000 (API docs: http://localhost:8000/docs) +Frontend: http://localhost:3000 +``` + +Include a note if the emotion model is still downloading on first run. No other output is required unless an error or hard stop was encountered. + +--- + ## Stopping the project If the user says "stop the project", "stop the app", or "kill the servers": diff --git a/docs/agent-workflows/test-suite-quality-review.md b/docs/agent-workflows/test-review.md similarity index 90% rename from docs/agent-workflows/test-suite-quality-review.md rename to docs/agent-workflows/test-review.md index fa6f70d..b86af73 100644 --- a/docs/agent-workflows/test-suite-quality-review.md +++ b/docs/agent-workflows/test-review.md @@ -1,15 +1,22 @@ -# Test Suite Quality Review +# Test Review ## Purpose Reviews the **quality and simplicity of the existing test suite** — whether tests are readable, practical, and focused on behavior rather than implementation details. Flags overengineering, unnecessary abstraction, and tests that are too complex for their value. -**Does not:** check for test coverage gaps in newly written code (that is handled by `code-quality-review.md`). Does not run tests or generate new tests. Scope is existing test quality only, not coverage metrics. +**Does not:** check for test coverage gaps in newly written code (that is handled by `code-review.md`). Does not run tests or generate new tests. Scope is existing test quality only, not coverage metrics. **Note:** Interview Coach has no frontend test runner configured. `pnpm test` does not exist in `frontend/package.json`. When invoked, limit this review to **Storybook story quality** — `.stories.tsx` files are the primary coverage mechanism for this project. State "no test runner configured" at the top and proceed directly to story review. --- +## Preparation + +- Read `AGENTS.md` to load project conventions and understand testing expectations (Storybook stories are the primary coverage mechanism; no test runner configured). +- Enumerate story files: `git ls-files frontend/**/*.stories.tsx` or equivalent glob. + +--- + ## Review goal - Review tests that already exist in the codebase @@ -94,7 +101,7 @@ Apply the same standard to every test category that exists in the project: - end-to-end tests that try to do too much in one file or flow - utilities or wrappers that make the suite harder to understand than necessary -## Required output format +## Output ### 1. High-level assessment @@ -142,7 +149,4 @@ For each test file or logical group, explain: - Do not suggest turning the suite into a professional enterprise-grade testing system - The target is not perfection - Err on the side of fewer, simpler, more basic tests even if the suite is less comprehensive than a production-grade strategy - -## Final instruction - -Review the entire test suite like a practical reviewer whose main goal is to keep the tests grounded, readable, simple, and believable. +- Review the entire test suite like a practical reviewer whose main goal is to keep the tests grounded, readable, simple, and believable diff --git a/docs/workflow-authoring.md b/docs/workflow-authoring.md new file mode 100644 index 0000000..d640f2c --- /dev/null +++ b/docs/workflow-authoring.md @@ -0,0 +1,104 @@ +# Workflow Authoring + +This file defines the standards and conventions for writing agent workflow documents in `docs/agent-workflows/`. Consult it when creating a new workflow or significantly restructuring an existing one. + +--- + +## Standards + +Workflow documents in this project conform to three interlocking standards: + +| Standard | Scope | Key requirement | +| -------- | ----- | --------------- | +| [AGENTS.md community spec](https://agents.md/) | File naming, placement, precedence | Flexible Markdown; no mandatory sections; agent-neutral syntax | +| [MCP specification (2025-11-25)](https://modelcontextprotocol.io/specification/2025-11-25) | Document structure | Purpose, inputs, outputs, and constraints sections; RFC 2119 language for requirements | +| [Claude Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) | Discoverability model | Skills use YAML frontmatter (`name`, `description`) and are auto-loaded; workflows here are explicit on-demand only — no YAML frontmatter | + +**AAIF governance:** AGENTS.md and MCP are both governed by the [Agentic AI Foundation (AAIF)](https://lfaidata.foundation/projects/aaif/), a directed fund of the Linux Foundation co-founded by Anthropic, OpenAI, and Block. Both specifications were donated to AAIF in December 2025. Workflows must remain compatible with the AAIF-governed versions of these specs as they evolve. + +--- + +## Authoritative references + +### AGENTS.md community specification + +**URL:** https://agents.md/ + +Defines the `AGENTS.md` file format — a flexible Markdown file placed at the repo root (or any directory) to provide agent instructions. No mandatory sections. The closest file in the directory tree takes precedence. Used by 60,000+ open-source projects and supported by Claude Code, Codex, Copilot, Cursor, Windsurf, and others. This project's `AGENTS.md` is the authoritative source of project conventions. + +### MCP specification (2025-11-25) + +**URL:** https://modelcontextprotocol.io/specification/2025-11-25 + +Defines the Model Context Protocol — the JSON-RPC 2.0-based protocol that underlies tool calls, resource access, and prompt handling. The spec's document structure conventions (purpose, inputs, outputs, constraints) informed the required section layout for workflow documents in this project. Use RFC 2119 language (`MUST`, `SHOULD`, `MAY`) for hard requirements within workflow docs. + +### Claude Agent Skills — Overview + +**URL:** https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview + +Defines the SKILL.md format: YAML frontmatter (`name`, `description`), progressive disclosure (metadata always loaded; SKILL.md on trigger; resources as needed), and auto-discoverability. **This project does not use SKILL.md** — workflows here are explicit on-demand invocations, not auto-discoverable skills. Reference this spec when evaluating whether a workflow should be promoted to a skill. + +### Claude Agent Skills — Best practices + +**URL:** https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices + +Guidance on progressive disclosure, keeping metadata concise, writing clear purpose statements, and scoping outputs. Apply these principles to workflow `## Purpose` and `## Output` sections even though the SKILL.md frontmatter format is not used here. + +--- + +## Conventions template + +Use this structure for every new workflow document: + +```markdown +# [Short imperative title — 1–3 words, Title Case] + +## Purpose + +[One sentence describing what the workflow produces or accomplishes.] + +**Does not:** [one line on what is explicitly out of scope — prevents scope creep] + +--- + +## Preparation + +- Read `AGENTS.md` to load project conventions. +- [Any additional setup steps — git commands to run, files to enumerate, tokens to verify] + +--- + +## Scope ← include only when scope is non-obvious or configurable + +- [What is in scope] +- [What is explicitly excluded] + +--- + +## [Workflow content sections] + +[The substantive how-to content — steps, checks, priorities, formats, etc.] + +--- + +## Output + +[Describe exactly what the agent produces: format, required sections, mandatory vs optional elements.] + +--- + +## Constraints ← include when there are hard rules beyond the purpose/does-not line + +- [Hard rule 1 — phrased as a prohibition or hard stop] +- [Hard rule 2] +``` + +**Key rules:** + +- **Title:** short noun phrase or imperative verb phrase, 1–3 words. Match the filename (e.g., `merge-review.md` → `# Merge Review`). +- **Purpose:** state the output or action, then a `**Does not:**` line. One sentence each. +- **Preparation:** always starts with "Read `AGENTS.md`". Add only what is actually needed before the workflow begins. +- **Section order:** Purpose → Preparation → Scope (if needed) → workflow content → Output → Constraints (if needed). +- **Agent-neutral:** no vendor-specific syntax, no YAML frontmatter, no Claude-only directives. Works identically with any coding agent. +- **Cross-references:** always reference other workflow files by their current filename (e.g., `css-review.md`, not `css-and-component-standards-review.md`). Always reference `AGENTS.md` in uppercase. +- **RFC 2119 language:** use `MUST`, `MUST NOT`, `SHOULD`, `MAY` for hard requirements in Constraints sections.