3.5Copy-paste template for Claude Code

You are scaffolding an initial Playwright + TypeScript UI and API automation harness for mostly autonomous agentic development.

Read these files first and treat them as the source of truth:

Required:
- playwright-scaffolding.md
- docs/specs/product-under-test.md
- docs/specs/ui-journeys.md
- docs/specs/api-endpoints.md

Optional, if present:
- docs/discovery/site-map-notes.md
- docs/discovery/navigation-notes.md
- docs/discovery/api-notes.md
- docs/discovery/auth-notes.md
- docs/discovery/open-questions.md

Your job is to create an initial repository state that is customized to the real application under test.

Important rules:
- If playwright-scaffolding.md exists, it overrides generic assumptions.
- Use real page names, real route groupings, real feature domains, real API client domains, and real journey names.
- Keep architectural principles from the generic harness, but customize naming and structure to the actual application.
- Do not preserve generic placeholder names if the artifacts provide real names.
- Prefer a repo that another agent can resume from after context loss.

Tech and tooling defaults:
- Node.js
- TypeScript
- Playwright Test
- npm
- ESLint
- Prettier
- dotenv
- zod

Primary harness requirements:
- UI automation with Playwright
- API automation with Playwright APIRequestContext by default
- shared auth/session helpers where appropriate
- environment-aware configuration
- local development support
- CI-aware structure
- artifact and debugging support
- strong repo memory via docs and plans

Create the repository with this top-level structure as a strong default, adapting names where the application-specific artifacts justify it:

.
├── AGENTS.md
├── CHANGELOG.md
├── CLAUDE.md
├── README.md
├── package.json
├── tsconfig.json
├── playwright.config.ts
├── .gitignore
├── .editorconfig
├── .env.example
├── .worktreeinclude
├── .claude/
│   ├── settings.json
│   ├── rules/
│   │   ├── page-objects.md
│   │   ├── api-clients.md
│   │   ├── test-writing.md
│   │   └── selectors.md
│   ├── agents/
│   │   ├── planner.md
│   │   ├── generator.md
│   │   ├── evaluator.md
│   │   └── reviewer.md
│   └── skills/
│       ├── new-page-object/SKILL.md
│       ├── new-test-spec/SKILL.md
│       ├── run-evaluator/SKILL.md
│       └── log/SKILL.md
├── scripts/
│   ├── bootstrap.ts
│   ├── validate.ts
│   ├── smoke-ui.ts
│   ├── smoke-api.ts
│   ├── doc-check.ts
│   ├── plan-init.ts
│   └── new-spec.ts
├── config/
│   ├── env/
│   ├── projects/
│   └── test-data/
├── src/
│   ├── core/
│   ├── ui/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── flows/
│   │   └── assertions/
│   ├── api/
│   │   ├── clients/
│   │   ├── builders/
│   │   ├── helpers/
│   │   ├── schemas/
│   │   └── assertions/
│   ├── shared/
│   │   ├── data/
│   │   ├── factories/
│   │   ├── utils/
│   │   └── state/
│   └── fixtures/
├── tests/
│   ├── ui/
│   │   ├── smoke/
│   │   ├── regression/
│   │   └── accessibility/
│   ├── api/
│   │   ├── smoke/
│   │   ├── regression/
│   │   └── contract/
│   ├── hybrid/
│   └── setup/
├── artifacts/
│   ├── reports/
│   ├── screenshots/
│   ├── videos/
│   ├── traces/
│   └── logs/
├── docs/
│   ├── index.md
│   ├── architecture/
│   ├── standards/
│   ├── runbooks/
│   ├── specs/
│   ├── plans/
│   │   ├── active/
│   │   ├── completed/
│   │   ├── handoffs/
│   │   └── templates/
│   ├── agents/
│   └── decisions/
└── .github/
    └── workflows/

Create meaningful starter content, not empty placeholders, for these files:
- README.md
- CLAUDE.md
- AGENTS.md
- docs/index.md
- docs/architecture/repo-map.md
- docs/architecture/test-layering.md
- docs/architecture/ui-harness.md
- docs/architecture/api-harness.md
- docs/architecture/data-and-state.md
- docs/standards/coding-standards.md
- docs/standards/test-writing-standards.md
- docs/standards/selector-strategy.md
- docs/standards/api-contract-strategy.md
- docs/standards/logging-and-redaction.md
- docs/standards/flaky-test-policy.md
- docs/runbooks/local-dev.md
- docs/runbooks/ci.md
- docs/runbooks/debugging.md
- docs/runbooks/traces-and-screenshots.md
- docs/runbooks/incident-response-for-failing-tests.md
- docs/agents/planner.md
- docs/agents/generator.md
- docs/agents/evaluator.md
- docs/agents/reviewer.md
- docs/agents/doc-gardener.md
- docs/plans/templates/sprint-contract-template.md
- docs/plans/templates/execution-plan-template.md
- docs/plans/templates/evaluator-report-template.md
- docs/decisions/0001-initial-harness-architecture.md
- .claude/settings.json
- .claude/rules/page-objects.md
- .claude/rules/api-clients.md
- .claude/rules/test-writing.md
- .claude/rules/selectors.md
- .claude/agents/planner.md
- .claude/agents/generator.md
- .claude/agents/evaluator.md
- .claude/agents/reviewer.md
- .claude/skills/new-page-object/SKILL.md
- .claude/skills/new-test-spec/SKILL.md
- .claude/skills/run-evaluator/SKILL.md
- .claude/skills/log/SKILL.md
- .worktreeinclude
- CHANGELOG.md

Root instruction rules:
- CLAUDE.md must be under 200 lines. Keep it navigational — use @path/to/file.md imports to reference detailed docs.
- CLAUDE.md should import key docs: @playwright-scaffolding.md, @docs/specs/product-under-test.md, @docs/standards/coding-standards.md, @AGENTS.md, etc.
- CLAUDE.md must include a "Work log" section near the top: "ALWAYS update CHANGELOG.md before committing" with the required entry format (date, summary, files changed, why). This advisory rule is backed by the PreToolUse commit hook.
- AGENTS.md must define the collaboration model and handoff rules. CLAUDE.md imports it via @AGENTS.md.
- Do not create one giant monolithic instruction file.
- Future agents should be able to continue from repo files alone.

Path-scoped rules (.claude/rules/):
Create rule files with YAML frontmatter `paths:` fields so rules only load when Claude works with matching files:
- .claude/rules/page-objects.md (paths: src/ui/pages/**/*.ts) — selector strategy, page object patterns, waitForReady requirement
- .claude/rules/api-clients.md (paths: src/api/**/*.ts) — APIRequestContext usage, schema validation, redaction
- .claude/rules/test-writing.md (paths: tests/**/*.ts) — test naming, assertion style, no hardcoded waits, smoke test time limits
- .claude/rules/selectors.md (paths: src/ui/**/*.ts) — getByRole first, getByTestId second, never CSS selectors for user-facing elements

Native subagents (.claude/agents/):
Create subagent definitions so Claude can delegate specialized tasks:
- .claude/agents/planner.md — tools: Read, Grep, Glob. Creates sprint contracts before implementation.
- .claude/agents/generator.md — tools: Read, Grep, Glob, Edit, Write, Bash. Implements the current sprint scope.
- .claude/agents/evaluator.md — tools: Read, Grep, Glob, Bash. Verifies implementation against sprint contract, writes PASS/FAIL report.
- .claude/agents/reviewer.md — tools: Read, Grep, Glob. Reviews code for quality, patterns, and security.
Each subagent must have a description field that tells Claude when to delegate to it automatically.

Skills (.claude/skills/):
Create reusable workflow definitions:
- .claude/skills/new-page-object/SKILL.md — create a new page object from a page name
- .claude/skills/new-test-spec/SKILL.md — create a new test file from a journey description
- .claude/skills/run-evaluator/SKILL.md — invoke the evaluator against the current sprint contract
- .claude/skills/log/SKILL.md — update CHANGELOG.md with a summary of recent work (invoke with /log)

Hooks (.claude/settings.json):
Configure hooks for automated quality enforcement:
- PostToolUse hook on Edit|Write: run eslint --fix on changed files
- PreToolUse hook on Bash(git commit*): block commits unless CHANGELOG.md is staged — this is the only guaranteed way to enforce work logging
- Notification hook: notify when Claude needs attention (useful during long scaffolding runs)

Worktree support:
- Create .worktreeinclude listing .env and .env.local so environment files are copied into worktrees automatically
- Add .claude/worktrees/ to .gitignore

Agent workflow requirements:
- Make Planner → Generator → Evaluator the default core loop.
- Planner defines scope and acceptance criteria before coding.
- Generator implements only the current sprint scope.
- Evaluator verifies against the sprint contract and writes PASS/FAIL with evidence.
- Also include Reviewer and Doc-gardener role docs as secondary roles.

Planning requirements:
Create a planning system with:
- docs/plans/active/
- docs/plans/completed/
- docs/plans/handoffs/
- docs/plans/templates/

The plan templates must support:
- sprint contract
- execution plan
- evaluator report

Code design requirements:
- Use Playwright with TypeScript for UI and API automation.
- Use Playwright APIRequestContext as the default API transport layer.
- Keep selectors inside the owning page objects by default.
- Keep reusable page behavior in page objects.
- Keep multi-page business behavior in flow helpers.
- Use component objects only for repeated page fragments.
- Use assertion helpers for reusable expectations.
- Prefer simple fixtures over clever abstractions.
- Prefer explicit readable code over heavy indirection.

UI harness requirements:
- Create page-object files named from the actual application pages where possible.
- Create flow helpers for the most important journeys from docs/specs/ui-journeys.md.
- Create starter smoke coverage for the most critical UI paths.
- Add at least one accessibility-oriented starter test where the product makes sense for it.

API harness requirements:
- Organize API clients by the real endpoint domains from docs/specs/api-endpoints.md.
- Use wrapper client classes and schema validation.
- Add starter smoke coverage for auth and one major business domain.
- Add one contract-style example using schema validation.
- Add explicit status/body/header assertions where meaningful.

Hybrid test requirements:
- Add one example test that seeds or prepares state via API and validates via UI.

Fixtures and auth requirements:
- Create environment-aware fixtures.
- Include storageState support where appropriate.
- Reflect the auth/session model from docs/specs/product-under-test.md.
- Do not hardcode secrets.
- Create .env.example with representative non-secret placeholders.

Validation requirements:
Add npm scripts for:
- bootstrap
- lint
- format
- format:check
- typecheck
- test
- test:ui
- test:api
- test:smoke
- test:contract
- test:a11y
- docs:check
- validate
- report
- plan:init
- new:spec

Recommended validate behavior:
- format check
- lint
- typecheck
- smoke tests

Playwright config requirements:
- separate UI and API projects
- environment selection through env vars
- trace retention on failure
- screenshots on failure
- video retention on failure for UI
- HTML report output under artifacts/reports/playwright-report
- test results output under artifacts/reports/test-results
- sensible retries
- base URL configurable via env
- storageState support
- tags or project targeting for smoke, regression, contract, and accessibility
- global setup / teardown hooks

Artifacts and debugging requirements:
Use predictable artifact locations:
- artifacts/reports
- artifacts/screenshots
- artifacts/videos
- artifacts/traces
- artifacts/logs

Write runbooks that explain:
- how to run a single test
- how to open the Playwright report
- how to inspect traces
- how to regenerate auth state
- how to run only API tests
- how to switch environments

Redaction requirements:
- never log raw secrets
- never log raw auth tokens
- redact auth headers
- redact cookies
- redact PII and session values where practical

CI requirements:
Create:
- .github/workflows/ci.yml
- .github/workflows/smoke.yml
- .github/workflows/docs-check.yml

Expected CI behavior:
- lint
- typecheck
- run smoke UI and API tests
- upload Playwright report and failure artifacts when needed
- validate docs structure where practical

Starter test requirements:
Create a minimal but meaningful starter suite aligned to the application-specific artifacts:
- UI smoke test(s)
- UI regression sample
- one accessibility sample
- API auth smoke test
- API major-domain sample
- API contract-style sample
- one hybrid example

Do not generate generic nonsense tests. Use the discovered journeys and feature names.

Definition of done for the scaffold:
The scaffold is not done unless:
- required structure exists
- key docs contain meaningful starter content
- CLAUDE.md exists and is under 200 lines, using @imports for detailed docs
- .claude/rules/ contains path-scoped rules for page objects, API clients, tests, and selectors
- .claude/agents/ contains native subagent definitions for planner, generator, evaluator, and reviewer
- .claude/skills/ contains at least new-page-object, new-test-spec, and run-evaluator workflows
- .claude/settings.json contains hooks for lint-on-edit, changelog-on-commit, and notifications
- CHANGELOG.md exists with the initial scaffold entry
- .worktreeinclude lists .env files for worktree support
- root instruction files exist
- plan templates exist
- package scripts exist
- Playwright config exists and is coherent
- starter tests exist
- docs and naming reflect the real application where known
- no secrets are committed
- the repo is understandable to a future agent with no chat history

Bootstrap order:
1. create folder structure
2. create root config files
3. create package scripts and dependencies
4. create Playwright config
5. create core utilities and fixtures
6. create sample UI/API/hybrid tests aligned to the product
7. create docs index and architecture docs
8. create agent role docs
9. create plan templates
10. create CI workflows
11. run validation and fix scaffold issues
12. update README with exact getting-started steps

At the end, provide:
1. a concise summary of what was created
2. a short list of follow-up tasks
3. any assumptions that still need human confirmation

Do not ask to continue later. Perform the scaffolding now from the provided artifacts.