Spec Template: Login Flow

This is a ready-to-use intent.md for a standard email and password login flow. Copy it into the root of your repository, adapt it to your stack, and run the preflight before your coding agent builds from it.

It covers the parts of the 8-part IntentSpec you write yourself. The eighth, Evidence, is the research behind the claims; it lives in your workspace, and the file lists it under ## Supporting Evidence once it is linked.

The Template

---
status: draft
---

# Email and Password Login

## Objective
Returning users sign in with their email and password and reach their dashboard.
Nobody who lacks the password gets in, and a failed attempt never reveals whether
the email has an account.

## Current State
[What happens today. For a new product: "There is no sign-in; every page is public."]

## Outcomes
- [ ] A user with valid credentials is signed in and lands on the dashboard
- [ ] Invalid credentials show "Invalid email or password", whichever field was wrong
- [ ] A signed-in user who reloads the page stays signed in

## Scope
**In scope:**
- The sign-in form, the sign-in endpoint, and session creation
**Out of scope:**
- Sign-up, password reset, and social sign-in

## Constraints
- Passwords are never logged or stored in plaintext
- Every authentication endpoint is served over HTTPS only
- Session state goes through the existing AuthContext; no second auth store

## Edge Cases
- **The email is not verified yet**: show "Email not verified" and offer to resend the link
- **The request times out**: show a retryable error; the form keeps the email the user typed
- **Five failed attempts in ten minutes**: slow further attempts for that email and say so

## Health Metrics
- Sign-in success rate for existing users does not drop
- Median sign-in response time stays under 500 ms

## Verification
**Fastest check**:
- [ ] Unit test: the password comparison rejects a wrong password and never logs the input
**Shipped signal**:
- [ ] Failed sign-ins per active user stay at or below the week before release
**Regression guard**:
- [ ] Users signed in before the release are not signed out by it
**Manual check**:
- [ ] Sign in with a real account, reload, and confirm the session survives
**Automated test**:
- [ ] End-to-end: valid credentials reach the dashboard; invalid ones show the generic error

How to Use This Template

1. Copy it into your repository root as intent.md.
2. Fill in Current State with what sign-in does today, and adjust the outcomes to your product's rules.
3. Add your stack's constraints: auth provider, framework, design system.
4. Preflight it. Run /preflight with the Pathmode plugin for Claude Code, or paste the file into the browser preflight. It grades six gates (title, objective, outcomes, constraints, edge cases, verification) and names anything missing.
5. Hand it to your agent. Coding agents read intent.md from the repository. With a workspace connected, a teammate can review and authorize the exact revision before the agent builds.

Customization Ideas

• OAuth sign-in: Add outcomes for "Sign in with Google" and "Sign in with GitHub", and move social sign-in into scope.
• Two-factor authentication: Add an outcome for code entry after the password, and an edge case for a lost device.
• Magic link: Replace the password outcomes with an email-only form and a "Send magic link" button, and add an edge case for an expired link.

Why Structured Specs Beat Loose Prompts

"Build a login page" leaves every product decision to the agent. It will pick an error message, a lockout rule, and a session lifetime, and it will be confident about all three.

This file makes those calls before the agent starts:

• The security rules are written down. "Passwords are never logged" is the kind of constraint that disappears from a conversational prompt. In the spec, it is a line the agent reads and a reviewer can check.
• The boundaries are explicit. Scope says sign-up and password reset are out, so the agent does not build them on the way.
• Done has a definition. The outcomes are finite and testable, so the agent knows when it is finished, and the verification says how you will know it held after release.

A loose prompt produces code that works. A spec produces code that does what you decided, because you made the call up front instead of the agent.

Ready to write your own? Start from a real request: have your coding agent propose the intent.md, then review it, answer its open questions, and back each claim with the research that justifies it.