crewly 1.0.0

package/config/task_starters/prompts/build_spec_step2_technical_design.md

@@ -0,0 +1,147 @@
+TECHNICAL DESIGN DOCUMENTATION - STEP 2
+
+You are a **principal systems architect**. Using the Step 1 PRD (`project.md`) as your single source of truth, perform a **technical design pass** that selects and generates the **right set of design documents** (not from a fixed list) and details a **phased, testable path to scale**. Output a manifest and the design docs in the **`*_design.md`** format.
+
+**Inputs:**
+
+PROJECT GOAL:
+{INITIAL_GOAL}
+
+USER JOURNEY:
+{USER_JOURNEY}
+
+## Task: Create Technical Design Documentation
+
+Based on the project requirements in project.md, analyze what technical design documents are needed and create them.
+
+## Technical Design Analysis
+
+Review the project.md file and determine which technical components require design documentation:
+
+## Design Document Type Dynamic Selection Logic (no fixed list)
+
+1. Parse the PRD (project.md) to extract: capabilities, user-facing surfaces, domain boundaries, integrations, data needs, NFRs, risks.
+2. Build a **Component Inventory** (UI surfaces, services, workflows, data domains, ML/AI, messaging, observability, CI/CD, security).
+3. Group related items into **Design Areas**. Create **one design doc per Design Area** that materially affects risk, scope, or scale.
+4. Name each file descriptively in snake_case, ending with `_design.md` (e.g., `customer_portal_frontend_design.md`, `order_domain_backend_design.md`, `auth_security_design.md`, `observability_platform_design.md`, `genai_rag_design.md`).
+5. Produce the **minimal sufficient set** to fully express the solution (typically **2–6 docs**, but create more if clearly required by PRD complexity).
+
+**Hard Constraints**
+
+-   ❌ No subdirectories under `specs/`
+-   ✅ Place **all** files directly in `{PROJECT_PATH}/.crewly/specs/`
+-   ✅ All filenames end with `_design.md`
+-   ✅ Each doc must be **specific, justified, and testable** (no generic filler)
+
+## Design Document Requirements (strict output contract)
+
+1. **MANIFEST (JSON)** — first code block:
+
+    - `project_name`
+    - `selected_docs`: array of filenames
+    - `design_areas`: map of filename → 1–2 line scope summary
+    - `rationale`: per file, how it maps to PRD goals, risks, NFRs
+    - `assumptions_tbd`: explicit gaps found in PRD (owner if known)
+    - `traceability`: PRD objectives/KPIs each doc supports
+    - `phase_plan_overview`: high-level phases with goals & exit criteria
+
+2. **Design Documents** — one **markdown code block per file**, content only.
+   Each block must start with an HTML comment containing the **absolute path**, e.g.:
+
+    ```markdown
+    <!-- {PROJECT_PATH}/.crewly/specs/order_domain_backend_design.md -->
+    ```
+
+## Required Content for _each_ `*_design.md`
+
+Tailor deeply to the PRD. Include at least **one diagram** (Mermaid). Prefer specifics over options; when uncertain, state **Assumptions (TBD)**.
+
+```markdown
+# [Component/Area] Design Document
+
+## Architecture Overview
+
+-   Context tied to PRD objectives/NFRs
+-   Component interactions & data flow (**Mermaid C4** context/container or sequence diagram)
+-   Technology choices with trade-offs & constraints
+
+## Research & Stack Selection
+
+-   Problem-fit criteria (latency/throughput, team skill, cost, ecosystem, compliance)
+-   3–5 candidate options with a **comparison table** (pros/cons, risks, cost/latency rough order of magnitude)
+-   Decision & rationale (why chosen, why not others)
+
+## Detailed Design
+
+-   Core components & responsibilities (and key alternatives rejected)
+-   Data structures/models (ER diagram or schema tables where applicable)
+-   Key algorithms/business rules (pseudocode/flows; edge cases & failure modes)
+-   Interaction contracts (request/response schemas, events, idempotency, rate limits)
+
+## Infrastructure & Operations
+
+-   Environments, topology, tenancy, **scaling model** (horizontal/vertical), capacity assumptions
+-   Networking, messaging, storage classes; backup/restore, DR objectives (RPO/RTO)
+-   Observability (logs/metrics/traces), SLOs & alerting rules; feature flags & config strategy
+
+## Security & Compliance
+
+-   AuthN/AuthZ model (roles/claims), session/secret management
+-   Data protection (in transit/at rest), PII handling, retention
+-   Threat model (**STRIDE/OWASP**) with mitigations
+
+## Performance & Scalability
+
+-   Budgets/targets (e.g., p95 latencies, throughput, availability) linked to PRD NFRs
+-   Caching/indexing strategies, batching/pagination, back-pressure
+-   Load shedding, degradation behavior, hotspot analysis
+
+## Integration Points
+
+-   External systems & protocols; retries, timeouts, circuit breakers
+-   API contracts or **OpenAPI/GraphQL SDL excerpts** (where relevant)
+-   Eventing/analytics plan (key events & properties; privacy notes)
+
+## Phased Design & Test Gates
+
+-   **Phase 0 – Spike/Prototype**: scope, thin slice architecture, KPIs, exit criteria, test plan
+-   **Phase 1 – MVP**: scope, deltas vs Phase 0, KPIs, test plan (unit/contract/e2e; perf baseline)
+-   **Phase 2 – Scale-Up**: sharding/queueing/caching/search, infra upgrades, KPIs, load tests
+-   **Phase 3 – Hardening/Optimizations**: resilience patterns, cost/perf tuning, SRE runbook updates
+-   Each phase is independently deployable & **good for testing** (clear entry/exit gates)
+
+## Testing Strategy
+
+-   Test pyramid (unit/integration/contract/e2e) & required fixtures
+-   Non-functional tests (perf, chaos, security, accessibility where applicable)
+-   Data migration/rollback tests; sandbox/staging validation plan
+
+## Risks, Trade-offs & Decisions
+
+-   Top risks with likelihood/impact/owner; mitigations & triggers
+-   ADR-style decisions (context, decision, consequences)
+-   Open questions & next steps with owners/dates
+
+## Assumptions (TBD)
+
+-   Explicit gaps inferred from PRD (owner, resolution plan)
+```
+
+**Document-Type Guidance (non-exhaustive examples; pick what the PRD actually needs):**
+
+-   `*_frontend_design.md` (web/desktop), `*_mobile_design.md`, `*_backend_design.md`, `*_api_design.md`, `*_database_design.md`,
+    `*_genai_design.md` (LLM/RAG/evals), `*_messaging_design.md` (Kafka/SQS/etc.), `*_security_auth_design.md`,
+    `*_observability_platform_design.md`, `*_devops_infra_design.md`, `*_analytics_tracking_design.md`, `*_data_pipeline_design.md`.
+
+---
+
+## Authoring Rules
+
+-   Ground every choice in the PRD’s **users, objectives, KPIs, NFRs** (maintain traceability).
+-   Prefer concrete specs (schemas, limits, timeouts) over vague guidelines.
+-   Include **Mermaid** diagrams (C4/sequence/ER) where appropriate.
+-   Keep vendor choices justified by the **Research & Stack Selection** analysis.
+-   Output only: **1 JSON manifest block**, followed by **N markdown blocks** (one per file). **No extra commentary.**
+-   All files go directly in `{PROJECT_PATH}/.crewly/specs/`.
+
+**Create the appropriate technical design documents now based on your analysis of the project requirements.**

package/config/task_starters/prompts/build_spec_step3_integration_testing.md

@@ -0,0 +1,196 @@
+INTEGRATION & E2E TESTING PLAN - STEP 3
+
+You are a **Staff QA Architect / SDET Lead**. Using the **Step 1 PRD (`project.md`)** and **Step 2 technical design docs (`*_design.md`)** as your single sources of truth, produce a **comprehensive Integration, E2E & Unit Testing Plan** and save it as `integration_tests.md`.
+
+**Inputs:**
+PROJECT GOAL:
+{INITIAL_GOAL}
+
+USER JOURNEY:
+{USER_JOURNEY}
+
+## Task: Create Comprehensive Integration & E2E Testing Plan
+
+Based on the project requirements (project.md), user journey, and technical design documents (\*\_design.md), create a comprehensive integration and end-to-end testing plan.
+
+### Create integration_tests.md
+
+Create the file at: `{PROJECT_PATH}/.crewly/specs/integration_tests.md`
+
+## Authoring Rules
+
+-   Derive scenarios directly from **PRD objectives, user journeys, NFRs**, and **design docs**.
+-   When information is missing, **infer sensible defaults** and label as **Assumptions (TBD)** with owners/dates.
+-   Include **specific tools and runnable commands** matched to the stack (Playwright/Cypress, Appium, Postman/Newman, k6/Artillery, Pact/Prism, OWASP ZAP, plus a unit test framework per language).
+-   Provide **phase-aligned testing** (Prototype → MVP → Scale → Hardening), each independently valuable and testable.
+-   Favor **tables, Gherkin (Given/When/Then)**, and **Mermaid diagrams** for clarity.
+-   **Unit tests are mandatory** and must be **detailed and comprehensive**.
+-   **Placement policy:** Co-locate unit tests next to the source file (e.g., `some_code.ts` → `some_code.test.ts`). If the tech stack conventionally forbids co-location (e.g., Java/Maven `src/test/java`), follow the **idiomatic layout** for that stack and state the exception.
+
+## Required `integration_tests.md` Structure & Quality Bar
+
+Tailor all content to the PRD and design docs—no generic filler. Include concrete commands.
+
+```markdown
+<!-- {PROJECT_PATH}/.crewly/specs/integration_tests.md -->
+
+# {PROJECT_NAME} - Integration, E2E & Unit Testing Plan
+
+## 1) Testing Overview
+
+-   Strategy & approach: risk-based, **test pyramid** (Unit > Integration > E2E) aligned to PRD NFRs
+-   Scope: what’s in/out for Unit, Integration, E2E (map to features/domains)
+-   Environment model: Local, CI, Staging, Prod-like (capabilities, data, restrictions)
+-   Tooling stack & **selection rationale** per layer
+-   Assumptions (TBD) with owner & due date
+
+## 2) Traceability & Coverage Matrix
+
+-   **Objectives/KPIs → Features → Tests** mapping (table)
+-   Layer targets: Unit (≥ X% lines/branches), Integration (≥ Y% critical paths), E2E (≥ Z% primary journeys)
+-   Risk tags per feature (H/M/L) → required depth & negative testing
+
+## 3) Unit Testing Strategy (Co-Located by Default)
+
+### 3.1 Placement & Naming Policy
+
+-   Preferred: tests live next to source (e.g., `module.ts` → `module.test.ts` / `module.spec.ts`); similar for other languages
+-   Allowed exception: stacks that enforce separate test roots (e.g., Java `src/test/java`, .NET `*Tests` projects). Document the exception and equivalent patterns
+
+### 3.2 Framework & Patterns
+
+-   Language → Framework(s) → Runner/Assertion/Mocking
+-   Patterns: **AAA (Arrange–Act–Assert)**, property-based tests where valuable, snapshot tests (stable-only), deterministic time/UUID/network via fakes
+-   Test doubles policy: mock external boundaries; avoid mocking domain logic
+
+### 3.3 Coverage Requirements & Depth
+
+-   Targets: lines, branches, mutation score (if used)
+-   For each **public function/class**: happy path, error paths, boundary conditions, idempotency, concurrency/time-sensitive behavior
+
+### 3.4 Example File Conventions by Stack
+
+| Stack   | Framework        | File Pattern                              | Command                               |
+| ------- | ---------------- | ----------------------------------------- | ------------------------------------- |
+| Node/TS | Vitest/Jest      | `*.test.ts` or `*.spec.ts` next to source | `npx vitest run --coverage`           |
+| Python  | pytest           | `test_*.py` next to source or `/tests`    | `pytest -q --maxfail=1 --cov`         |
+| Java    | JUnit5 + AssertJ | `src/test/java/...*Test.java`             | `mvn -q -Dtest=*Test test`            |
+| Go      | `go test`        | `*_test.go` next to source                | `go test ./... -cover`                |
+| .NET    | xUnit/NUnit      | `*Tests` project                          | `dotnet test /p:CollectCoverage=true` |
+| Rust    | cargo test       | `#[cfg(test)]` mod + `tests/`             | `cargo test`                          |
+
+### 3.5 Property & Mutation Testing (if applicable)
+
+-   Tools: fast-check (Node), Hypothesis (Python), jqwik (JVM), Stryker (JS/TS/JVM/.NET)
+-   Thresholds & commands
+
+### 3.6 Sample Command Matrix (TPM-friendly)
+
+-   Local & CI commands for unit suites per stack; env vars & caching notes
+
+## 4) End-to-End (E2E) Testing (User-Journey–Driven)
+
+-   **Primary Journeys** from `{USER_JOURNEY}` with rationale
+-   **E2E Scenario Catalog** (≥8 scenarios; happy/alt/error) using Gherkin:
+    -   ID, Name, Preconditions, Data, Steps (**G/W/T x2+**), Expected Results, Priority, Phase (P0–P3), Owner
+-   Cross-browser/device matrix (web/mobile); Playwright/Cypress/Appium configs
+-   Environment setup (secrets, seeded users), data strategy (synthetic vs masked)
+-   **Mermaid sequence diagram** for at least one critical journey
+
+## 5) System Integration Tests
+
+-   Component interaction map; service-to-service scenarios; retries/idempotency; sagas/transactions
+-   Contract tests via **Pact** (CDC) or schema validation
+-   Runnable example: `npm run test:integration` / language-specific equivalents
+
+## 6) API Integration Tests
+
+-   Endpoint coverage table (CRUD, filters, pagination, errors)
+-   Request/response **contracts**; versioning/back-compat rules
+-   Negative & edge cases (timeouts, rate limits, auth failures)
+-   Tools: Postman/Newman, REST Assured, Supertest; example commands
+
+## 7) Database Integration Tests
+
+-   Persistence & transaction integrity; isolation levels
+-   Migration tests; data backfill/archival paths
+-   Query performance checks & indexing; p95/p99 targets
+-   Data lifecycle: seed → mutate → assert → teardown
+
+## 8) External System Integration
+
+-   3rd-party services: SLAs/quotas; sandbox usage policy
+-   Mocks/stubs (Prism, WireMock, MSW); when to hit live sandboxes
+-   Chaos/failure injection (timeouts, jitter, packet loss) & expected fallbacks
+
+## 9) Performance Integration Tests
+
+-   Workload models & SLIs (throughput, latency, error rate) tied to NFRs
+-   Test types: baseline, load, stress, soak, spike; capacity assumptions
+-   Thresholds & **quality gates** (e.g., p95 < X ms @ Y RPS)
+-   Tools & example scripts: k6/Artillery/JMeter
+
+## 10) Security Integration Tests
+
+-   AuthN/AuthZ flows, session/MFA; access control matrices
+-   Data protection validation; secrets scanning
+-   DAST/SAST/Dep scans (OWASP ZAP, Semgrep, Snyk) & triage workflow
+-   Privacy & compliance checks (consent, retention)
+
+## 11) Accessibility, i18n, & UX Validation (if applicable)
+
+-   Automated a11y (axe, Lighthouse) + manual keyboard/screen reader runs
+-   Localization & formatting; RTL; error/empty/loading states
+
+## 12) Test Automation Architecture
+
+-   Repo layout; co-location rules; naming & tagging (@unit @integration @e2e @smoke)
+-   Orchestration: parallel vs sequential; retries & flake control
+-   CI/CD integration: jobs, caches, artifacts, dashboards; gating thresholds
+-   Reporting: Allure/HTML/JUnit; trend charts; triage SLAs
+
+## 13) Test Execution Plan
+
+-   Execution sequence & dependencies (graph/table)
+-   **Phased execution** aligned to delivery:
+    -   **Phase 0 (Prototype/Spike)**: thin-slice unit + E2E smoke; exit criteria
+    -   **Phase 1 (MVP)**: critical-path unit coverage + key integrations/E2E; exit criteria
+    -   **Phase 2 (Scale-Up)**: perf/chaos/resiliency; exit criteria
+    -   **Phase 3 (Hardening)**: regression, a11y, security depth; exit criteria
+-   Environment provisioning & teardown; data lifecycle & privacy
+
+## 14) Success Criteria & Quality Gates
+
+-   Unit coverage (lines, branches), mutation score; integration/E2E adequacy
+-   Pass/fail per test type; SLO/SLA thresholds
+-   Release gates per environment/phase
+
+## 15) How to Run (TPM-Friendly)
+
+-   Copy/paste commands for **unit**, integration, E2E, API, perf, security
+-   CI commands & env var matrix; tmux pane suggestions
+-   Artifacts & dashboards; how to interpret reports
+
+## 16) Risks, Assumptions (TBD), and Open Questions
+
+-   Risk register (likelihood/impact/owner/mitigation)
+-   Assumptions with owner & due date
+-   Open questions with decision deadlines
+
+## 17) Appendix
+
+-   Glossary; references to PRD & design docs
+-   Example fixtures/factories, seed scripts, data catalogs
+```
+
+**IMPORTANT REQUIREMENTS (enforced in the document):**
+
+-   ✅ Base E2E scenarios primarily on `{USER_JOURNEY}` and PRD flows
+-   ✅ Include **unit tests** that are **detailed, comprehensive**, and **co-located by default** (with documented exceptions)
+-   ✅ Provide specific **tooling recommendations + runnable commands** for **unit**, integration, E2E, perf, security
+-   ✅ Plan for TPM tmux execution (clear, copy/paste-friendly commands)
+-   ✅ Cover both automated and targeted manual strategies (exploratory/a11y/security)
+-   ✅ Provide **phase-aligned** tests so each stage is independently shippable & testable
+-   ✅ Include **rationales** for tool choices and **explicit quality gates**
+
+**Focus on creating comprehensive integration and E2E tests that validate the complete user journey and all technical components identified in the previous steps.**

package/config/task_starters/prompts/build_tasks_step1_milestone_structure.md

@@ -0,0 +1,274 @@
+You are a **Principal PM + TPM** specializing in agent-friendly backlogs. Using all specs in `{PROJECT_PATH}/.crewly/specs/` — especially `project.md`, any `*_design.md`, and (if present) `integration_tests.md` — **analyze**, **plan**, and **generate** a feature- and platform-structured task system with **ultra-granular, agent-executable** tasks that ladder up to a coherent, shippable product.
+
+**Inputs:**
+Project: {PROJECT_NAME}
+Path: {PROJECT_PATH}
+
+PROJECT GOAL:
+{INITIAL_GOAL}
+
+USER JOURNEY:
+{USER_JOURNEY}
+
+## Output Contract (strict)
+
+Produce output in **this exact order**:
+
+1.  **MANIFEST (JSON)** — first code block:
+
+    -   `project_name`
+    -   `features`: `{key, name, description, priority, complexity, depends_on[], journey_stage, objective_kpi}`
+    -   `platforms`: detected (web, backend, mobile_ios, mobile_android, desktop, devops)
+    -   `stack_summary`: derived from `*_design.md` (frontend, backend, data, infra, integrations)
+    -   `milestones`: ordered `{id, dir_name, feature_keys[], platform, phase, rationale}`
+    -   `dependency_graph`: edges among milestones
+    -   `task_counts`: per milestone `{open, in_progress, blocked, done}`
+    -   `traceability`: PRD/Design anchors → features → milestones
+    -   `assumptions_tbd`: gaps with owner & due date (TBD allowed)
+    -   `limits`: `max_tasks_total`, `min_tasks_per_milestone`
+    -   `naming_rules`: confirm `m[number]_[feature/area]_[platform]` and status folders
+
+2.  **DIRECTORY BOOTSTRAP (bash)** — second code block:
+
+    -   Create `{PROJECT_PATH}/.crewly/tasks`
+    -   Create **all** milestone directories and required status subfolders `{open,in_progress,blocked,done}`
+
+3.  **TASK FILES (one markdown block per task)** — then N code blocks:
+
+    -   Each block begins with an **HTML comment** of the absolute path, e.g.
+        \`\`
+    -   Content follows the **Agent-Grade Task Template** (below) with filled-in specifics.
+    -   Generate a reasonable number of tasks per milestone to build the component atomically.
+    -   **Safety cap:** If tasks would exceed **60**, emit top-priority tasks; summarize the remainder in `MANIFEST.backlog_summary`.
+
+**No extra commentary** outside these code blocks.
+
+---
+
+## How to Analyze (follow strictly)
+
+1.  **Identify Core Features (from `project.md`)**
+
+    -   Map to user journey stages and objectives/KPIs.
+    -   Score priority via **RICE** (Reach/Impact/Confidence/Effort) or **MoSCoW**.
+    -   Note dependencies (data, services, UX).
+
+2.  **Extract Tech Stack & Constraints (from `*_design.md`)**
+
+    -   Platforms, frameworks, languages, versions.
+    -   Integration points and contracts (APIs, events).
+    -   NFRs (perf, security, a11y) that affect task scope.
+
+3.  **Define Feature Boundaries (all specs)**
+
+    -   Shared components/utilities.
+    -   Cross-platform variance.
+    -   Testing expectations per feature/platform.
+
+---
+
+## Milestone Strategy (dynamic)
+
+-   Always start with **foundation & infra**:
+    `m1_foundation_setup`, `m2_infrastructure_backend` (if backend), `m3_infrastructure_frontend` (if web).
+-   Then add **feature milestones** per platform in priority order (e.g., `m4_auth_backend`, `m5_auth_web`, `m6_auth_mobile_ios`).
+-   Add **testing/integration** and **deployment** milestones **only as required** by detected platforms/services.
+-   Phase each milestone: **Foundation → MVP → Scale → Hardening**.
+-   Conclude each feature milestone with a dedicated **integration testing task** responsible for verifying the milestone's deliverables.
+
+---
+
+## Granularity & Agent-Facing Rules
+
+-   **Size**: each task ≤ **2 hours** OR ≤ **150 LOC** touched; one primary file/folder focus.
+-   **Single responsibility**: one clear outcome; avoid “and/also”.
+-   **Deterministic**: all commands **idempotent**; include env vars and paths; prefer `bash -euo pipefail`.
+-   **Executable**: provide copy-paste commands, file scaffolds, and minimal compiling stubs.
+-   **Co-located unit tests** by default (`x.ts` → `x.test.ts`), or idiomatic per stack (document exception).
+-   **Traceable**: link to PRD/Design anchors; list upstream/downstream impacts.
+-   **Rollback**: include revert notes (files/commands) and cleanup.
+
+---
+
+## Agent-Grade Task Template (use verbatim structure; fill concretely)
+
+````markdown
+---
+id: [m#_area_platform.NN]
+feature: [key]
+platform: [web|backend|mobile_ios|mobile_android|desktop|devops]
+type: [frontend|backend|api|db|infra|security|qa|docs]
+priority: [P0|P1|P2]
+estimate_hours: [0.5–2.0]
+owner: [TBD]
+depends_on: [m#_area_platform.MM, ...]
+labels: [auth, accessibility, performance, ...]
+phase: [Foundation|MVP|Scale|Hardening]
+spec_refs:
+    - project.md#anchor
+    - design_doc.md#section
+objective_kpi: [explicit KPI tie-in]
+---
+
+# [Milestone].[Task Number]: [Precise, outcome-based title]
+
+## Definition of Ready (DoR)
+
+-   [ ] Repo checked out; branch created: `feat/[short]`
+-   [ ] Runtime & package manager installed (versions)
+-   [ ] Env vars available/secrets set: [list]
+-   [ ] Dependencies done: [task IDs]
+
+## Objective (Single Sentence)
+
+What will exist or pass at the end (code + tests).
+
+## Files & Locations (Absolute from repo root)
+
+-   `apps/web/src/components/LoginForm.tsx` (new)
+-   `apps/web/src/components/__tests__/LoginForm.test.tsx` (new)
+-   `apps/web/src/styles/forms.css` (modified)
+
+## Scaffolding (Run exactly in order; idempotent)
+
+```bash
+set -euo pipefail
+cd {REPO_ROOT}
+mkdir -p apps/web/src/components/__tests__
+touch apps/web/src/components/LoginForm.tsx
+touch apps/web/src/components/__tests__/LoginForm.test.tsx
+```
+
+## Code Skeletons (compile-safe stubs)
+
+```tsx
+// apps/web/src/components/LoginForm.tsx
+export type LoginFormProps = { onSubmit(email: string, password: string): Promise<void> };
+export function LoginForm({ onSubmit }: LoginFormProps) {
+	return null;
+} // TODO: replace with implementation
+```
+
+## Interface / Contract Snapshots
+
+-   Events: `auth:login.requested` `{ email: string }`
+-   API: POST `/api/auth/login` → 200 `{ token }` | 401 `{ error }`
+
+## Unit Test Blueprint (write first)
+
+-   `renders form fields and submit disabled until valid`
+-   `submits valid credentials and calls onSubmit`
+-   `shows error on 401 response`
+
+```tsx
+// apps/web/src/components/__tests__/LoginForm.test.tsx
+describe('LoginForm', () => {
+	it('disables submit until valid', async () => {
+		/* ... */
+	});
+	it('calls onSubmit on valid input', async () => {
+		/* ... */
+	});
+	it('handles 401 error', async () => {
+		/* ... */
+	});
+});
+```
+
+## Implementation Steps
+
+### Phase A — Structure (15–20 min)
+
+-   Implement markup with labeled inputs; basic state.
+-   Add validation (email format, min password length).
+
+### Phase B — Logic (30–50 min)
+
+-   Wire `onSubmit`; loading/error states; a11y (ARIA, focus).
+-   Telemetry event on submit; rate-limit guard.
+
+### Phase C — Tests (20–30 min)
+
+-   Complete unit tests (happy, edge, error).
+-   Add contract mock for `/api/auth/login`.
+
+## Acceptance Criteria (Definition of Done)
+
+-   [ ] Unit: ≥ 85% lines, ≥ 75% branches for touched files; tests named as above
+-   [ ] Lint/format pass (ESLint/Prettier rules)
+-   [ ] A11y: keyboard nav and labels validated
+-   [ ] Contract compatibility with API design doc
+-   [ ] Commit created: `feat(auth): add LoginForm skeleton + tests`
+
+## Run & Verify (Local/CI)
+
+```bash
+pnpm install
+pnpm lint && pnpm typecheck
+pnpm test --filter web -- --run
+```
+
+Expected: 3 tests pass; coverage thresholds met.
+
+## Rollback Plan
+
+-   `git restore -SW apps/web/src/components/LoginForm.tsx apps/web/src/components/__tests__/LoginForm.test.tsx`
+
+## Risks & Mitigations
+
+-   Validation libs conflict → use lightweight inline checks.
+-   Flaky async tests → add `await screen.findBy...` and fake timers.
+
+## Links
+
+-   Upstream: \[project.md#auth], \[backend_design.md#login]
+-   Downstream: m5_auth_web.03 (wire to API)
+````
+
+---
+
+## Integration Testing Task Guidelines (special task type)
+
+This special task type concludes each feature milestone. It uses the standard `Agent-Grade Task Template` but with a specific structure and objective.
+
+-   **Title:** Must be named like `[Milestone].[Task Number]: Verify [Feature] Integration`.
+-   **`type`:** `qa`.
+-   **`depends_on`:** All other implementation tasks within the same milestone.
+-   **Objective:** "Create and execute an integration test script to validate the functionality delivered in this milestone; create bug-fix tasks for any failures."
+-   **Scaffolding:** Commands to create a new test script file, e.g., `touch {PROJECT_PATH}/integration_tests/test_m5_auth.sh`.
+-   **Implementation Steps:** This section must have three distinct phases.
+    1.  **Write Test Script:** Detail the shell commands, API calls (`curl`), or framework commands (`cypress run`) needed to test the milestone's features. The script must have clear pass/fail exit codes. Store the script in `{PROJECT_PATH}/integration_tests/`.
+    2.  **Execute Test Script:** Provide the exact command to run the script and capture its output and exit code.
+    3.  **Analyze & Remediate:** Include a conditional logic block for the agent to follow.
+        -   **On Success (exit code 0):** Document the successful output. The task is considered complete.
+        -   **On Failure (non-zero exit code):**
+            -   Document the full error output.
+            -   Define the **exact follow-up tasks** needed to fix the bugs. For each bug, specify the title, objective, and files to be modified. These new tasks **must be created as new files** in the current milestone's `open/` directory.
+
+---
+
+## Platform Guidelines
+
+-   **Multi-platform**: distinct milestones per platform.
+-   **Full-stack**: split backend/frontend tasks.
+-   **Microservices**: one milestone per service.
+-   **Mobile**: separate iOS/Android unless cross-platform.
+
+---
+
+## Task Rules (strong)
+
+-   Generate **one or more tasks per milestone**. The number should be dictated by the work's natural atomic units, not an arbitrary minimum. Each task must still be atomic and independently shippable.
+-   Every feature milestone **must culminate in an integration testing task**. This task follows the specific guidelines detailed above. Its primary responsibility is to verify the milestone and generate new bug-fix tasks if verification fails.
+-   Every task must include: **Scaffolding commands**, **compile-safe stubs**, **unit test blueprint**, **exact run commands**, **DoR/DoD**, and a **rollback plan**.
+-   Use explicit paths, versions, and commands; avoid vague instructions like “update X”.
+-   For stacks that don’t support test co-location, state the idiomatic alternative and mirror the same structure under that root.
+
+---
+
+## Constraints
+
+-   Create directories only under `{PROJECT_PATH}/.crewly/tasks` with status folders `{open,in_progress,blocked,done}`.
+-   Do **not** create other folder levels.
+-   Filename pattern: `m[number]_[feature/area]_[platform]`.
+-   New tasks go into each milestone’s `open/` folder.