Development Workflow

Development Workflow

Structured approach to software development ensuring requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented with proper contribution practices.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

Project Planning & Requirements:

• Starting new features or phases of work
• Defining requirements using structured notation
• Creating technical designs and architecture documents
• Managing implementation plans from concept to completion
• Ensuring thorough documentation before coding
• Understanding project structure and existing patterns

Repository Contributions:

• Creating issues, commits, or pull requests in a repository
• Needing to follow repository guidelines before making contributions
• Creating PRs, pushing code, or following contribution workflows
• Following project-specific contribution guidelines

Quality Assurance:

• Ensuring two-stage review (spec compliance first, then code quality) standards are met
• Validating tests and requirements before implementation
• Managing project decisions and trade-offs documentation
• Tracking progress and blockers

Part 1: Spec-Driven Development

Core Artifacts

Maintain these artifacts throughout the project lifecycle:

EARS Notation for Requirements

EARS = Easy Approach to Requirements Syntax

Basic EARS Patterns

1. Universal Requirements Apply to all entities without condition

• "The system shall validate all user input."
• "Each user shall have a unique email address."

2. State-Driven Requirements Apply only in specific system states

• "When the user is authenticated, the system shall display the dashboard."
• "If the payment fails, the system shall retry up to 3 times."

3. Event-Driven Requirements Triggered by specific events

• "When the user clicks 'Submit', the system shall validate the form."
• "Upon receiving a new message, the chat application shall update the conversation view."

4. Optional-Feature Requirements Describing optional or conditional features

• "The system may provide offline access if supported."
• "The user may choose to receive email notifications."

5. Unwanted Behavior Specifying what should not happen

• "The system shall not store passwords in plain text."
• "The application shall not allow simultaneous sessions from different locations unless configured."

6. AI-Agent Requirements Specifying agent-visible constraints, handoff evidence, and autonomous execution limits

• "The agent shall run the documented verification command before claiming completion."
• "The agent shall not modify files outside the task scope without explicit approval."

Complete EARS Example

# User Authentication Requirements

## Universal Requirements
- U-001: The system **shall** require users to provide an email address and password for login.
- U-002: The system **shall** validate email addresses using RFC 5322 format.

## Event-Driven Requirements
- E-001: **When** the user clicks "Forgot Password", the system **shall** send a password reset link to the registered email.
- E-002: **Upon** successful authentication, the system **shall** generate a session token valid for 24 hours.

## State-Driven Requirements
- S-001: **If** the user has enabled two-factor authentication, the system **shall** prompt for the verification code.
- S-002: **When** the account is locked due to too many failed attempts, the system **shall** unlock it after 30 minutes.

## Unwanted Behavior
- N-001: The system **shall not** reveal whether an email address is registered during password reset.
- N-002: The system **shall not** allow the same account to be used from more than 3 IP addresses simultaneously.

## Optional Features
- O-001: The system **may** support social login providers (Google, Facebook, GitHub).

## AI-Agent Requirements
- A-001: The agent **shall** report changed files, commands run, and unresolved risks before handoff.

EARS Grammar and Parser Example

requirement = id ":" [trigger ","] subject "shall" action "." ;
trigger = ("When" | "If" | "While" | "Upon") condition ;
id = ("U" | "E" | "S" | "N" | "O" | "A") "-" digit digit digit ;

const earsRequirement =
  /^(?<id>[UESNOA]-\d{3}):\s(?:(?<keyword>When|If|While|Upon)\s(?<condition>.+?),\s)?(?<subject>The system|The user|The agent)\sshall\s(?<action>.+)\.$/;

Overview

High-level description of what this feature does and why it's needed.

Architecture

System Diagram

User → Frontend → API Gateway → Service → Database
                              ↓
                         Cache Layer

Component Structure

src/
├── components/
│   └── FeatureName/
│       ├── FeatureComponent.tsx
│       ├── SubComponent.tsx
│       └── styles.css
├── services/
│   └── featureService.ts
├── api/
│   └── featureApi.ts
└── types/
    └── feature.types.ts

Data Models

entities/Feature.ts

interface FeatureEntity {
  id: string;
  name: string;
  status: 'active' | 'inactive';
  createdAt: Date;
  // ... other fields
}

API Contracts

POST /api/features

interface CreateFeatureRequest {
  name: string;
  /* ... other fields */
}

interface CreateFeatureResponse {
  id: string;
  status: 'created';
}

Error Handling

Sequence Diagram

User → Frontend: Click "Create Feature"
Frontend → API: POST /api/features
API → Validator: Validate data
Validator → API: Valid / Invalid
API → Database: Insert feature
Database → API: Created
API → Frontend: Return feature ID
Frontend → User: Show success message

Security Considerations

• Authentication required for all mutations
• Input validation on all endpoints
• Rate limiting on create operations
• Audit logging for all changes

Performance Considerations

• Caching strategy for read operations
• Database indexing requirements
• CDN for static assets

Agentic Considerations

• Files or directories agents may modify
• Commands agents must run before completion
• Decisions that require human approval
• Handoff evidence required for review

Implementation Phases

1. Phase 1: Core CRUD operations 2. Phase 2: Validation and error handling 3. Phase 3: Caching layer 4. Phase 4: Testing and documentation

### Implementation Task Tracking

Tasks: [Feature Name] Implementation

Phase 1: Foundation

• [ ] Confirm scope, dependencies, and agent boundaries
• [ ] Create data model and migration scaffold

Phase 2: Core Functionality

• [ ] Implement core API or service path
• [ ] Add validation, errors, and persistence

Phase 3: Frontend Integration

• [ ] Build main component
• [ ] Cover loading, empty, error, and success states

Phase 4: Verification

• [ ] Add unit/integration/component tests for changed paths
• [ ] Run required verification commands and record evidence

Phase 5: Release Notes

• [ ] Document behavior, migration, and user-facing changes

Full scaffold reference: examples/feature-spec-example.md or scripts/create-spec-scaffold.ps1.

---

## Part 2: Repository Contribution Guidelines

## Anti-Patterns

- Starting work before the plan or gate is clear: Execution drifts when success criteria are implied instead of explicit.
- Treating verification as optional cleanup: The last mile is where regressions and missing updates are usually hiding.
- Mixing planning, implementation, and release work in one jump: You lose the causal chain that explains why a change is safe.

## Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Development Workflow starts from explicit success criteria, constraints, and stop conditions.
2. Pass/fail: Required evidence is collected before any completion, approval, or readiness claim.
3. Pass/fail: The next action follows the documented gate order without skipping review or verification steps.
4. Pressure-test scenario: Apply the workflow under time pressure with one failing check and one tempting shortcut.
5. Success metric: Zero rationalizations; blocked, failed, or unverified work is reported as such.


### Pre-Contribution Checklist

Before creating any PR or making changes:

Pre-Submission Checklist

Repository Understanding

• [ ] Read README.md for project overview
• [ ] Read CONTRIBUTING.md for contribution rules
• [ ] Reviewed issue and PR templates
• [ ] Checked for existing related issues or PRs

Environment Setup

• [ ] forked repository (if required)
• [ ] cloned repository locally
• [ ] setup development environment
• [ ] installed all dependencies

Development Standards

• [ ] Understand coding style conventions
• [ ] Familiar with branching strategy
• [ ] Aware of commit message conventions
• [ ] Know testing requirements

### Issue Creation Workflow

#### When to Create Issues
- New feature requests
- Bug reports
- Documentation gaps
- Security vulnerabilities
- Performance concerns

#### Issue Template

Issue: [Brief Title]

Type: [Feature Request / Bug Report / Question / Documentation]

Priority: [Low / Medium / High / Critical]

Description

[Detailed description of the issue or feature request]

Reproduction Steps (for bugs)

1. [First step] 2. [Second step] 3. [Third step]

Expected Behavior

[What should happen]

Actual Behavior

[What actually happened]

Environment

• OS: [e.g., Windows 10, macOS 12.5]
• Browser: [e.g., Chrome 120, Firefox 115]
• Version: [If applicable]

Additional Context

[Any other information that might be helpful]

• Screenshots
• Error messages
• Logs

### Branching Strategy

Branch Naming Convention

Feature Branches

feature/[JIRA-TICKET]/[short-description] Examples:

• feature/PROJ-123/user-authentication
• feature/PROJ-456/dark-mode-support

Bugfix Branches

bugfix/[JIRA-TICKET]/[issue-description] Examples:

• bugfix/PROJ-789/login-redirect-loop
• bugfix/PROJ-321/memory-leak-report

Hotfix Branches (production issues)

hotfix/[JIRA-TICKET]/[critical-description] Examples:

• hotfix/PROJ-999/security-vulnerability
• hotfix/PROJ-888/database-down

Release Branches

release/v[major].[minor] Examples:

• release/v1.2.0
• release/v2.0.0

Branch Protection Rules

• Protect main and develop branches
• Require pull request reviews (at least 1 approval)
• Require status checks to pass (CI builds, tests)
• Require branches to be up-to-date before merging

### Commit Message Standards (Conventional Commits)

Conventional Commit Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

Breaking Changes

feat(api)!: remove deprecated v1 endpoint

BREAKING CHANGE: v1 endpoints are no longer supported. Use v2.

Good Commit Examples

feat(auth): add refresh token mechanism
- Implement JWT refresh tokens
- Add storage for access tokens
- Update token validation logic

fix(ui): resolve mobile navigation issue
- Mobile menu was not closing after clicking links
- Added event listener to handle link clicks
- Tested on iOS Safari and Chrome Mobile

docs(readme): update installation instructions
- Clarified Node.js version requirement
- Added troubleshooting section

Bad Commit Examples (Don't use)

update 2
fixed bug
wip
changes
final
work in progress

Commit Workflow

# Stage changes
git add .

# Interactive staging (optional)
git add -i

# Commit with good message
git commit -m "feat(auth): implement OAuth2 login"

# Or use multi-line for body and footer
git commit -m "fix(db): optimize query performance

Added composite index on user_email and created_at
Reduced query time from 500ms to 50ms

Closes issue #123"

---

Part 3: Pull Request Process

Creating Pull Requests

PR Checklist

## Pull Request Checklist

### Before Submitting
- [ ] Branch is up-to-date with target branch
- [ ] Code compiles without errors
- [ ] All tests pass locally
- [ ] Linters pass without errors
- [ ] Documentation updated (README, API docs, code comments)
- [ ] Self-review completed

### PR Description
- [ ] Clear title following conventional commits
- [ ] Description explains "why" not just "what"
- [ ] Screenshots for UI changes included
- [ ] Breaking changes documented
- [ ] Related issues referenced (e.g., "Closes #123")
- [ ] Testing instructions provided

### Code Quality
- [ ] Follows project coding standards
- [ ] No commented-out code
- [ ] No console.log statements
- [ ] meaningful variable and function names
- [ ] No sensitive data exposed

### Testing
- [ ] New features tested
- [ ] Bug fixes verified
- [ ] Edge cases covered
- [ ] Manual testing completed as described

PR Template

## Description
[Provide a brief description of the changes in this PR]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation
- [ ] Refactoring
- [ ] Performance improvement

## Issue
[Closes #xxx] or [Related to #xxx]

## Changes Made
### Main Changes
- [Describe the main changes implemented]

### Technical Details
[Any technical details reviewers should know]

### Breaking Changes
[Any breaking changes and migration steps]

## Testing
### Manual Testing Steps
1. [Step 1]
2. [Step 2]

### Automated Testing
- [ ] Unit tests added and passing
- [ ] Integration tests added and passing
- [ ] E2E tests added and passing

## Screenshots
[Include before/after screenshots for UI changes]

## Checklist
- [ ] I have read the contributing guidelines
- [ ] My code follows the project style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code appropriately
- [ ] Changes have no linting errors
- [ ] All tests are passing
- [ ] Changes do not break existing functionality

two-stage review (spec compliance first, then code quality) Guidelines

For Reviewers

## two-stage review (spec compliance first, then code quality) Principles

### Be Constructive
- Focus on improving code, not criticizing it
- Provide specific examples and suggestions
- Ask questions rather than making demands
- Acknowledge good code and smart solutions

### Review Focus Areas

#### Correctness
- [ ] Logic is correct and handles edge cases
- [ ] Error handling is adequate
- [ ] No obvious bugs or race conditions
- [ ] API contracts are maintained

#### Code Quality
- [ ] Code is readable and maintainable
- [ ] Naming follows conventions
- [ ] Complexity is reasonable
- [ ] No code duplication

#### Architecture
- [ ] Follows established patterns
- [ ] Good separation of concerns
- [ ] Proper abstractions used
- [ ] No tight coupling

#### Security
- [ ] No security vulnerabilities
- [ ] Input validation present
- [ ] Authentication/authorization correct
- [ ] No sensitive data exposure

### Review Priority Comments
🔴 **Blocker**: Must be fixed before merge
🟡 **Concern**: Discuss before merge
🟢 **Suggestion**: Nice to have, not blocking

---

Part 4: Documentation Standards

Documentation Templates

Action Documentation

### [TYPE] - [ACTION] - [TIMESTAMP]

**Objective**: [Goal being accomplished]

**Context**: [Current state, requirements, reference to prior steps]

**Decision**: [Approach chosen and rationale]

**Execution**: [Steps taken with parameters and commands]

**Output**: [Complete results, logs, metrics]

**Validation**: [Success verification and results]

**Next**: [Continuation plan to next action]

Decision Record

### Decision - [TIMESTAMP]

**Decision**: [What was decided]

**Context**: [Situation and driving data]

**Options**:
- Option 1: [Description] - [Pros/Cons]
- Option 2: [Description] - [Pros/Cons]
- Option 3: [Description] - [Pros/Cons]

**Rationale**: [Why selected option is superior]

**Impact**: [Anticipated consequences]

**Review**: [Reassessment conditions]

Summary Formats

Streamlined Action Log (for changelogs): [TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]

Quick Summary (for updates): What: [Brief description] Why: [Context/rationale] How: [Approach taken] Status: [Current state] Next: [Upcoming step]

---

Dependency Management

• Pin the runtime, package manager, and critical libraries in the design doc before implementation starts.
• Record upgrade constraints, required codemods, and any package that needs special review because it changes build, auth, or persistence behavior.
• Prefer a small scheduled update cadence over infrequent large jumps so the test surface stays understandable.

Vulnerability Scanning

• Run dependency scans as part of the normal quality gate, not only before release.
• Triage findings by exploitability and reachability instead of blindly applying every patch immediately.
• Track accepted risks with owners and revisit dates when a fix cannot ship in the current cycle.

Accessibility Testing

• Add keyboard, focus-order, semantic HTML, and screen-reader expectations to the feature definition instead of treating accessibility as a polishing pass.
• Pair automated tooling such as axe or Playwright accessibility checks with manual review of the critical flows.
• Keep accessibility bugs inside the same Definition of Done as functional bugs for the feature.

Internationalization (i18n) Considerations

• Identify translatable strings, locale-aware formatting, and right-to-left layout risks during planning.
• Keep UI copy, date or number formatting, and fallback language behavior outside hard-coded components.
• Verify overflow, truncation, and validation messages in at least one non-default locale before release.

Part 5: Quality Gates

Cross-Skill Gates

• Use systematic-debugging when a build, test, or rollout gate fails and the root cause is not yet proven.
• Use code-quality when the feature works but the gate is blocked by maintainability, readability, duplication, or review-quality concerns.

Definition of Done

## Definition of Done (DoD)

### Development
- [ ] Code written and committed
- [ ] Code follows project style guide
- [ ] Code compiles without errors
- [ ] No console errors or warnings
- [ ] Self-review completed

### Testing
- [ ] Unit tests written and passing
- [ ] Integration tests written and passing
- [ ] Manual testing completed
- [ ] Edge cases identified and handled
- [ ] Test coverage meets project threshold (>80%)

### Documentation
- [ ] README updated if API changed
- [ ] API documentation updated
- [ ] Code comments added/updated
- [ ] User documentation updated if needed

### two-stage review (spec compliance first, then code quality)
- [ ] Pull request created
- [ ] At least one approval received
- [ ] All review comments addressed
- [ ] CI/CD pipeline passes
- [ ] Merged to appropriate branch

### Deployment
- [ ] Deployment tested in staging
- [ ] Smoke tests passed
- [ ] Performance validated
- [ ] Monitoring/alerting configured
- [ ] Rollback procedure documented

Quality Checklist

## Code Quality Checklist

### Functionality
- [ ] All acceptance criteria met
- [ ] Requirements from design document fulfilled
- [ ] Edge cases handled
- [ ] Error states handled gracefully

### Usability
- [ ] User-friendly error messages
- [ ] Clear feedback for actions
- [ ] Accessible (keyboard, screen reader)
- [ ] Responsive design verified

### Performance
- [ ] Meet performance requirements
- [ ] No memory leaks
- [ ] Efficient algorithms used
- [ ] Appropriate caching

### Security
- [ ] Input validation
- [ ] Output encoding (prevent XSS)
- [ ] Authentication/authorization implemented
- [ ] No sensitive data in logs
- [ ] Dependencies audited and up-to-date

### Maintainability
- [ ] Code is readable
- [ ] Good variable/function names
- [ ] Appropriate abstractions
- [ ] No code duplication
- [ ] Adequate comments

### Testing
- [ ] Unit tests for critical paths
- [ ] Integration tests for API
- [ ] E2E tests for user flows
- [ ] Tests are reliable and not flaky

---

Part 6: Project Lifecycle Management

Phase-based Development

## Development Phases

### Phase 1: Requirements & Planning
- Gather requirements from stakeholders
- Document in EARS notation
- Create technical design
- Identify risks and dependencies
- Estimate effort and timeline

### Phase 2: Development
- Set up feature branches
- Implement core functionality
- Write tests alongside code
- two-stage review (spec compliance first, then code quality) and iteration

### Phase 3: Testing & QA
- Run automated tests
- Perform manual testing
- Conduct QA review
- Fix identified issues
- Performance testing

### Phase 4: Deployment
- Deploy to staging
- Execute smoke tests
- Get stakeholder approval
- Deploy to production
- Monitor for issues

### Phase 5: Post-Release
- Monitor metrics and logs
- Collect user feedback
- Address critical bugs
- Document lessons learned
- Update process improvements

Development Workflow Best Practices

Before Coding

• [ ] Requirements clearly defined and reviewed
• [ ] Technical design documented
• [ ] Dependencies identified
• [ ] Acceptance criteria established
• [ ] Testing strategy planned

During Development

• [ ] Small, frequent commits
• [ ] Write tests alongside code
• [ ] Follow coding standards
• [ ] Continuous self-review
• [ ] Request early feedback

Before Release

• [ ] All tests passing
• [ ] two-stage review (spec compliance first, then code quality) completed
• [ ] Documentation updated
• [ ] Security review (if needed)
• [ ] Release notes prepared

After Release

• [ ] Monitor production carefully
• [ ] Be ready to rollback
• [ ] Document issues and fixes
• [ ] Update metrics and dashboards
• [ ] Conduct retrospective

---

References & Resources

Documentation

• EARS Notation Reference — Complete EARS requirement patterns with examples and traceability matrix
• Design Doc Guide — Technical design document writing guide with ADR template

Scripts

• Create Spec Scaffold — PowerShell script to generate requirements, design, and tasks documents

Examples

• Feature Spec Example — Complete spec-driven development example for User Authentication

---

<!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

• GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
• Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
• Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
• Gemini CLI: this repository generates a project command named /skills:development-workflow from this skill. Rebuild commands with python scripts/export-gemini-skill.py development-workflow and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->

MCP Availability And Fallback

Preferred MCP Server: None required

• Fallback prompt: "Use the Development Workflow skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
• Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.

<!-- MCP:END -->

Related Skills

• code-quality: Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.
• systematic-debugging: Use it when the workflow also needs root-cause debugging before proposing fixes.
• test-driven-development: Use it when the workflow also needs test-first implementation and regression safety.
• verification-before-completion: Use it when the workflow also needs final evidence checks before claiming completion.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.
• Added the AI-Agent Requirements EARS pattern.
• Added Agentic Considerations to the design document guidance.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.
• Shortened the implementation task tracking example and pointed to the full scaffold references.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.
• Renamed the internationalization section to explicitly call out i18n considerations.

[2026-04-24] - Post-Refresh Cleanup

Fixed

• Moved the Anti-Patterns section out of the checklist template, added an explicit EARS grammar/parser snippet, and removed duplicated cross-skill quality-gate content.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.
• Added dependency management, vulnerability scanning, accessibility testing, i18n guidance, and a short EARS grammar/parser example, then cross-linked the quality gates to systematic-debugging and code-quality.

[2026-04-24] - Catalog Audit Cleanup

Fixed

• Removed obsolete standalone Skill Paths guidance that duplicated the generated portability section.

All notable changes to this skill will be documented in this file.

[2026-04-04] - Cross-Client Portability Refresh

Changed

• Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
• Clarified that the core workflow does not require a dedicated MCP server and can run with local tools alone.

Tested

• Validated SKILL.md frontmatter, portability sections, and Gemini export readiness with python scripts/validate-skills.py.

[2026-03-09] - Workspace Modernization

Changed

• Removed duplicated related-skill content from SKILL.md to keep the workflow easier to scan

[2026-02-28] — Description Rewrite & Cross-References

Changed

• Rewrote skill description to ~200 characters with clear, specific activation keywords
• Improved keyword specificity to reduce overlap with related skills

Added

• ## Related Skills cross-reference table with 2-4 related skills and "Use When" guidance

Spec-Driven Development Example: User Authentication

Complete example showing requirements (EARS notation), technical design, and implementation plan for a user authentication feature.

---

Part 1: Requirements (EARS Notation)

Metadata

Glossary

Universal Requirements

Event-Driven Requirements

State-Driven Requirements

Optional Feature Requirements

Unwanted Behavior Requirements

Combination Requirements

Non-Functional Requirements

Traceability Matrix

---

Part 2: Technical Design

Metadata

Overview

This design implements email/password authentication with JWT-based sessions for the Kitchen Odyssey application. The system supports registration, login, logout, password reset, account lockout, and optional MFA. JWTs are issued as access tokens (short-lived) with refresh tokens (long-lived) to balance security and user experience.

Goals

• Provide secure email/password authentication with bcrypt hashing and JWT tokens.
• Support password reset via email with time-limited tokens.
• Implement account lockout after repeated failed login attempts.
• Achieve sub-500ms login latency at p95.

Non-Goals

• OAuth/social login (deferred to Phase 2).
• SAML/SSO for enterprise accounts.
• Biometric authentication.
• User profile management (separate feature).

Architecture

sequenceDiagram
    participant C as Client (Browser)
    participant G as API Gateway
    participant A as Auth Service
    participant D as Database
    participant M as Mail Service

    Note over C,M: Registration Flow
    C->>G: POST /api/auth/register
    G->>A: Forward request
    A->>A: Validate input + hash password
    A->>D: INSERT user record
    D-->>A: User created
    A-->>G: 201 Created
    G-->>C: Registration success

    Note over C,M: Login Flow
    C->>G: POST /api/auth/login
    G->>A: Forward request
    A->>D: SELECT user by email
    D-->>A: User record
    A->>A: Verify password (bcrypt)
    A->>A: Check lockout status
    A->>A: Generate JWT + refresh token
    A->>D: INSERT session record
    A-->>G: 200 OK + tokens
    G-->>C: Set cookies + return user

    Note over C,M: Password Reset Flow
    C->>G: POST /api/auth/forgot-password
    G->>A: Forward request
    A->>D: SELECT user by email
    A->>A: Generate reset token (30min expiry)
    A->>D: STORE reset token
    A->>M: Send reset email
    A-->>G: 200 OK (generic message)
    G-->>C: "Check your email"

graph LR
    Client[Browser] --> Gateway[API Gateway<br/>Rate Limiting + TLS]
    Gateway --> Auth[Auth Service]
    Auth --> UserDB[(Users Table)]
    Auth --> SessionDB[(Sessions Table)]
    Auth --> Mail[Mail Service<br/>SendGrid/SES]

Component Responsibilities

Data Model

Entity: User

Entity: Session

Entity: PasswordResetToken

API Design

POST /api/auth/register

Request:

{
  "email": "jane@example.com",
  "password": "SecureP@ss123",
  "display_name": "Jane Doe"
}

Success (201):

{
  "message": "Account created successfully.",
  "user": { "id": "uuid", "email": "jane@example.com", "display_name": "Jane Doe" }
}

Errors: 400 validation_error (invalid fields), 409 generic success (email exists — anti-enumeration).

---

POST /api/auth/login

Request:

{
  "email": "jane@example.com",
  "password": "SecureP@ss123",
  "remember_me": false
}

Success (200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": { "id": "uuid", "email": "jane@example.com", "display_name": "Jane Doe", "role": "user" }
}

Refresh token set as HttpOnly cookie.

Errors: 401 invalid_credentials, 423 account_locked (includes retry_after seconds).

---

POST /api/auth/logout

Headers: Authorization: Bearer <token>

Success (200):

{ "message": "Logged out successfully." }

---

POST /api/auth/refresh

Cookie: refresh_token=<token>

Success (200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Errors: 401 token_expired, 401 token_revoked.

---

POST /api/auth/forgot-password

Request:

{ "email": "jane@example.com" }

Success (200): Always returns { "message": "If an account exists, a reset link has been sent." }

---

POST /api/auth/reset-password

Request:

{
  "token": "reset-token-value",
  "new_password": "NewSecureP@ss456"
}

Success (200):

{ "message": "Password reset successfully. Please log in." }

Errors: 400 token_expired, 400 token_invalid.

Security Considerations

• Passwords: Bcrypt with cost factor 12. Never logged, never returned in API responses.
• Tokens: Access tokens signed with RS256. Refresh tokens hashed (SHA-256) before storage.
• Cookies: Refresh token in HttpOnly, Secure, SameSite=Strict cookie.
• Rate limiting: 20 req/min/IP on all /auth/* endpoints.
• Lockout: 5 failures in 15 min → 30 min lockout. Counter resets on successful login.
• Enumeration: Registration and password reset return generic messages regardless of email existence.
• CSRF: SameSite=Strict cookie + CSRF token for state-changing operations.
• Logging: All auth events logged. Passwords and tokens never appear in logs.

Testing Strategy

Rollout Plan

Feature flag: auth_v2_enabled (default: false)

Alternatives Considered

A. Firebase Auth

• Pros: Managed, quick setup, many providers.
• Cons: Vendor lock-in, limited lockout customization, cost at scale.
• Verdict: Rejected — need full control over lockout and session logic.

B. NextAuth.js

• Pros: Built for Next.js, good DX, supports many providers.
• Cons: Opinionated session handling conflicts with our JWT approach.
• Verdict: Deferred — may adopt for OAuth/social login in Phase 2.

---

Part 3: Implementation Plan

Summary

Implement the user authentication system as designed. Broken into 3 phases: foundation (data model, core services), feature implementation (API endpoints, UI pages), and quality/release (testing, docs, rollout).

Task Breakdown

Phase 1: Foundation (Week 1)

Phase 2: Feature Implementation (Week 2)

Phase 3: Quality & Release (Week 3)

Dependency Graph

graph TD
    T01[T-01 DB Schema] --> T02[T-02 UserService]
    T01 --> T03[T-03 TokenService]
    T01 --> T04[T-04 LockoutService]
    T03 --> T05[T-05 AuthMiddleware]
    
    T02 --> T07[T-07 Register API]
    T02 --> T08[T-08 Login API]
    T03 --> T08
    T04 --> T08
    T03 --> T09[T-09 Logout API]
    T03 --> T10[T-10 Refresh API]
    T02 --> T11[T-11 Forgot Password]
    T11 --> T12[T-12 Reset Password]
    
    T07 --> T13[T-13 Register UI]
    T08 --> T14[T-14 Login UI]
    T11 --> T15[T-15 Password UI]
    T12 --> T15
    T10 --> T16[T-16 Auth Context]
    
    T02 --> T17[T-17 Unit Tests]
    T03 --> T17
    T04 --> T17
    T07 --> T18[T-18 Integration Tests]
    T08 --> T18
    T09 --> T18
    T10 --> T18
    T11 --> T18
    T12 --> T18
    
    T13 --> T19[T-19 E2E Happy Path]
    T14 --> T19
    T16 --> T19
    T15 --> T20[T-20 E2E Password Reset]
    
    T18 --> T21[T-21 Security Scan]
    T08 --> T22[T-22 Perf Test]
    T12 --> T23[T-23 API Docs]
    
    T19 --> T24[T-24 Feature Flag]
    T24 --> T25[T-25 Rollout]

Risk Register

Progress Log

2026-01-20

• Completed Phase 1 foundation tasks (T-01 through T-06).
• All database schemas created and migrated.
• Core services implemented with unit tests.

2026-01-27

• Completed Phase 2 API endpoints (T-07 through T-10) and UI pages (T-13, T-14, T-16).
• Password reset flow (T-11, T-12, T-15) in progress — email integration pending SendGrid API key.

2026-02-01

• Unit tests done (T-17). Integration tests in progress (T-18).
• Password reset email sending works in dev; testing in staging next.
• Remaining: E2E tests, security scan, perf test, feature flag, rollout.

Technical Design Document Guide

A practical guide for writing technical design documents that drive alignment, reduce rework, and create a lasting record of architectural decisions.

When to Write a Design Doc

Write a design doc when:

• A feature requires changes across two or more system boundaries (services, databases, APIs).
• The estimated implementation effort exceeds one sprint / one week.
• Multiple engineers will contribute to the implementation.
• The change introduces a new technology, pattern, or dependency.
• A decision has long-term implications that are expensive to reverse.
• Stakeholders outside the immediate team need visibility.

Skip a design doc when:

• The change is a straightforward bug fix with an obvious solution.
• A well-established pattern already covers the case (just reference it).
• The scope is a single file / single function with no cross-cutting impact.

---

Standard Sections

1. Title & Metadata

# Design: <Feature Name>

| Field       | Value                        |
|-------------|------------------------------|
| Author(s)   | @handle                      |
| Status      | Draft / In Review / Approved |
| Created     | YYYY-MM-DD                   |
| Updated     | YYYY-MM-DD                   |
| Reviewers   | @reviewer1, @reviewer2       |
| Tracking    | JIRA-1234 / GH Issue #42    |

Tips:

• Keep status current — reviewers need to know if they should comment or if the doc is final.
• Link the tracking ticket so the doc stays connected to implementation.

---

2. Overview / Summary

Write 3-5 sentences. Answer:

• What is this feature?
• Why are we building it now?
• What is the high-level approach?

Tips:

• Write this section LAST — it summarizes the entire doc.
• A busy reader should understand the proposal from this section alone.

---

3. Goals and Non-Goals

Goals — concrete, measurable outcomes this design achieves.

Non-Goals — things this design intentionally does NOT address (to prevent scope creep).

### Goals
- Allow users to authenticate via OAuth 2.0 with Google and GitHub providers.
- Reduce login friction to under 3 clicks from landing page to dashboard.
- Support account linking when the same email exists across providers.

### Non-Goals
- Implementing SAML-based SSO for enterprise customers (deferred to Q3).
- Migrating existing password-based users to OAuth-only.
- Building a custom identity provider.

Tips:

• Non-Goals are just as important as Goals — they set boundaries.
• Limit to 3-7 items per section. If you have more, you may need to split the design.

---

4. Architecture

Describe the system components involved and how they interact. Include a diagram.

### Architecture Diagram

​```mermaid
graph LR
    Client[Browser] --> Gateway[API Gateway]
    Gateway --> AuthService[Auth Service]
    AuthService --> UserDB[(User DB)]
    AuthService --> OAuthProvider[OAuth Provider]
    Gateway --> AppService[App Service]
    AppService --> UserDB
​```

### Component Responsibilities

| Component     | Responsibility                              |
|---------------|---------------------------------------------|
| API Gateway   | Route requests, rate limiting, TLS termination |
| Auth Service  | Token issuance, OAuth flow, session management |
| User DB       | User profiles, credentials, linked accounts   |
| App Service   | Business logic, data access                    |

Tips:

• Use Mermaid diagrams for version-control-friendly visuals.
• Show data flow direction with arrows.
• Name every component — no anonymous boxes.
• Call out new components vs. existing ones.

---

5. Data Model

Define entities, relationships, and key fields.

### Entity: User

| Field          | Type       | Constraints              |
|----------------|------------|--------------------------|
| id             | UUID       | PK, auto-generated       |
| email          | string     | unique, indexed          |
| display_name   | string     | max 100 chars            |
| created_at     | timestamp  | default: now()           |
| updated_at     | timestamp  | auto-updated             |

### Entity: OAuthLink

| Field          | Type       | Constraints              |
|----------------|------------|--------------------------|
| id             | UUID       | PK                       |
| user_id        | UUID       | FK → User.id             |
| provider       | enum       | google, github           |
| provider_uid   | string     | unique per provider      |
| access_token   | string     | encrypted at rest        |

### Relationships
- User 1 ←→ N OAuthLink

Tips:

• Include indexes that matter for query patterns.
• Note encryption, PII, and retention policies.
• If using MongoDB, show the document shape instead of tables.

---

6. API Design

Define endpoints, request/response contracts, and error codes.

### POST /api/auth/oauth/callback

Handles the OAuth callback from the identity provider.

**Request Body:**
​```json
{
  "provider": "google",
  "code": "4/0AX4XfWh...",
  "redirect_uri": "https://app.example.com/auth/callback"
}
​```

**Success Response (200):**
​```json
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "display_name": "Jane Doe"
  }
}
​```

**Error Responses:**

| Status | Code               | Description                        |
|--------|--------------------|------------------------------------|
| 400    | invalid_code       | OAuth code is invalid or expired   |
| 409    | email_conflict     | Email already linked to another account |
| 502    | provider_error     | OAuth provider returned an error   |

Tips:

• Use concrete example values in request/response bodies.
• Document error codes — consumers need them to build proper error handling.
• Specify authentication requirements for each endpoint.

---

7. Security Considerations

Address authentication, authorization, data protection, and threat vectors.

### Security

- **Token storage:** Access tokens stored server-side in encrypted format (AES-256-GCM).
  Client receives an opaque session cookie (HttpOnly, Secure, SameSite=Strict).
- **CSRF protection:** State parameter validated in OAuth callback.
- **Rate limiting:** /auth/* endpoints limited to 10 requests/minute per IP.
- **Input validation:** Provider and code parameters validated against allowlists.
- **Audit trail:** All auth events logged with anonymized IP and user agent.

### Threat Model

| Threat                  | Mitigation                                    |
|-------------------------|-----------------------------------------------|
| Token theft via XSS     | HttpOnly cookie, no tokens in localStorage    |
| CSRF on callback        | State parameter with HMAC signature           |
| Brute force on login    | Rate limiting + CAPTCHA after 5 failures      |
| Provider impersonation  | Verify token with provider's public keys      |

Tips:

• If you store PII, mention GDPR/CCPA compliance.
• Think like an attacker — what would you try?
• Reference OWASP Top 10 for common web threats.

---

8. Testing Strategy

Define how the feature will be tested at each level.

### Testing Strategy

| Level        | Scope                           | Tools                |
|--------------|---------------------------------|----------------------|
| Unit         | Auth service logic, token utils | Jest, @testing-library |
| Integration  | OAuth flow end-to-end           | Supertest, MSW        |
| E2E          | Login → Dashboard flow          | Playwright             |
| Security     | OWASP ZAP scan on auth endpoints| OWASP ZAP             |
| Performance  | 1000 concurrent logins          | k6                     |

### Key Test Scenarios
1. Happy path: Google OAuth login → new user created → dashboard loaded.
2. Account linking: Login with GitHub → same email as existing Google user → accounts merged.
3. Token expiry: Session expires → user redirected to login → smooth re-auth.
4. Provider failure: Google returns 500 → user sees friendly error → retry option.

Tips:

• Don't just list tools — describe what each test level covers.
• Include negative / edge-case scenarios.
• Specify performance benchmarks (latency, throughput).

---

9. Rollout Plan

How the feature goes from merged PR to production.

### Rollout Plan

| Phase | Audience         | Duration | Success Criteria            | Rollback Trigger        |
|-------|------------------|----------|-----------------------------|-------------------------|
| 1     | Internal team    | 3 days   | Zero auth errors in logs    | Any P0 bug              |
| 2     | 10% of users     | 1 week   | Error rate < 0.1%           | Error rate > 1%         |
| 3     | 50% of users     | 1 week   | No degradation in login time| P95 latency > 2s        |
| 4     | 100% of users    | —        | Feature flag removed        | —                       |

### Feature Flag
- Flag name: `oauth_login_enabled`
- Default: `false`
- Controlled via: LaunchDarkly / environment variable

### Monitoring
- Dashboard: Grafana "Auth Service" dashboard
- Alerts: PagerDuty for error rate > 1% on /auth/* endpoints
- Key metrics: login success rate, OAuth callback latency, account linking rate

Tips:

• Define rollback triggers before the rollout.
• Always have a feature flag for significant features.
• Link to the monitoring dashboard.

---

10. Alternatives Considered

Document approaches you rejected and why.

### Alternatives Considered

#### A. Firebase Authentication
- **Pros:** Managed service, quick integration, supports many providers.
- **Cons:** Vendor lock-in, limited customization for account linking,
  pricing unpredictable at scale.
- **Verdict:** Rejected — account linking requirements exceed Firebase's capabilities.

#### B. Auth0
- **Pros:** Rich feature set, enterprise-grade, good documentation.
- **Cons:** Cost ($$$), external dependency for core auth flow.
- **Verdict:** Deferred — may revisit when enterprise SSO is needed in Q3.

#### C. Custom OAuth implementation (chosen)
- **Pros:** Full control over flows, no vendor dependency, aligns with
  existing infrastructure.
- **Cons:** More engineering effort, must maintain security ourselves.
- **Verdict:** Accepted — best fit for current requirements and team capabilities.

Tips:

• Include at least 2 alternatives (the "do nothing" option can be one).
• Be honest about trade-offs — this builds reviewer trust.
• A rejected alternative today may become the right choice later; document why for future reference.

---

Review Process

Before Sending for Review

1. All sections are complete (no "TBD" placeholders for critical information). 2. Diagrams render correctly. 3. API examples are valid JSON/YAML. 4. Links to external resources work. 5. Spell-check completed.

Reviewer Checklist

• [ ] Goals are clear and the design achieves them.
• [ ] Non-goals are reasonable and complete.
• [ ] Architecture diagram matches the text description.
• [ ] Data model supports all described API operations.
• [ ] Security considerations address key threats.
• [ ] Rollout plan includes rollback criteria.
• [ ] Alternatives are genuine and fairly evaluated.
• [ ] Testing strategy covers happy paths AND failure modes.

Review Timeline

---

Architecture Decision Record (ADR) — Lightweight Template

For smaller decisions that don't warrant a full design doc, use an ADR.

# ADR-NNN: <Decision Title>

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Deciders:** @person1, @person2

## Context

What is the issue or question we need to decide on?
What constraints and forces are at play?

## Decision

What is the change we are making?
State the decision clearly in one or two sentences.

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Trade-off 1
- Trade-off 2

### Neutral
- Side-effect or observation

## Related
- Links to relevant design docs, issues, or previous ADRs

ADR Naming Convention

docs/adr/
├── 001-use-postgres-for-user-data.md
├── 002-adopt-oauth2-for-authentication.md
├── 003-choose-react-over-vue.md
└── README.md   ← index of all ADRs with status

Tips for ADRs:

• Keep them short (under 1 page).
• Write them at the moment of decision, not after the fact.
• Never delete an ADR — mark it as Deprecated or Superseded.
• Number them sequentially for easy reference.
• Store them in the repository alongside the code they affect.

EARS Notation Reference

Easy Approach to Requirements Syntax — A structured natural-language notation for writing unambiguous, testable requirements.

Overview

EARS eliminates vagueness in requirements by providing five sentence templates. Each template addresses a specific type of system behavior, ensuring every requirement answers when the behavior occurs and what the system shall do.

The Five EARS Patterns

1. Universal (Ubiquitous)

When it applies: Behavior that holds at all times, without any trigger or precondition.

Syntax:

The <system> shall <action>.

Examples:

Tips:

• Use sparingly — most behaviors are not truly universal.
• If you can think of a state or event that gates the behavior, use a different pattern.

---

2. Event-Driven

When it applies: Behavior triggered by a discrete event detected at the system boundary.

Syntax:

When <event>, the <system> shall <action>.

Examples:

Tips:

• The event should be observable and instantaneous (a transition, not a state).
• Use past tense or present simple for the event clause.
• Avoid compound events — split into separate requirements or use combination patterns.

---

3. State-Driven (While)

When it applies: Behavior that holds only while the system is in a particular state.

Syntax:

While <state>, the <system> shall <action>.

Examples:

Tips:

• The state must be a sustained condition, not a fleeting event.
• Make sure entry and exit conditions for the state are defined elsewhere.

---

4. Optional Feature

When it applies: Behavior that depends on a configurable option, license, or feature inclusion.

Syntax:

Where <feature/option is included>, the <system> shall <action>.

Examples:

Tips:

• Clearly define what controls the option (feature flag, config setting, license tier).
• Document how the option is enabled/disabled and who controls it.

---

5. Unwanted Behavior (Exception / Negative)

When it applies: Handling of undesirable situations the system must cope with — errors, faults, edge cases.

Syntax:

If <unwanted condition>, the <system> shall <mitigation>.

Examples:

Tips:

• Focus on what the system does, not what it doesn't do.
• Pair with Event-Driven requirements that define the happy path.

---

Combination Patterns

Real requirements often combine patterns. The order matters: Feature → State → Event → Action.

State + Event (most common combination)

While <state>, when <event>, the <system> shall <action>.

Feature + Event

Where <feature>, when <event>, the <system> shall <action>.

Feature + State + Event

Where <feature>, while <state>, when <event>, the <system> shall <action>.

Feature + Unwanted

Where <feature>, if <unwanted condition>, the <system> shall <mitigation>.

---

Traceability Matrix Template

Use a traceability matrix to link requirements to design, implementation, and test artifacts.

---

Common Mistakes

1. Vague Subjects

BAD:  The system should handle errors.
GOOD: If an unhandled exception occurs during request processing, the system shall return HTTP 500 and log the exception with stack trace.

2. Using "Should" Instead of "Shall"

• Shall = mandatory, testable.
• Should = desirable, ambiguous — avoid in formal requirements.

3. Compound Requirements (More Than One "Shall")

BAD:  When the user logs in, the system shall validate credentials and redirect to the dashboard and send a welcome email.
GOOD: Split into E-01 (validate), E-02 (redirect), E-03 (send email).

4. Missing Measurability

BAD:  The system shall respond quickly.
GOOD: When the user submits a search query, the system shall return results within 500 milliseconds for the 95th percentile.

5. Mixing Problem and Solution

BAD:  The system shall use Redis for caching.
GOOD: The system shall cache frequently accessed data to achieve sub-100ms response times for read operations.

(Redis is a design decision, not a requirement.)

6. Negative Requirements Without Mitigation

BAD:  The system shall not crash on invalid input.
GOOD: If the user provides invalid input, the system shall return a 400 error with a descriptive validation message.

---

Writing Tips

1. One behavior per requirement — if you see "and" joining two actions, split. 2. Start with the pattern keyword — When/While/Where/If — to immediately signal the type. 3. Name the actor — "the system", "the API", "the mobile client" — not just pronouns. 4. Quantify where possible — 500ms, 10 retries, 99.9% uptime. 5. Use consistent terminology — define a glossary and refer to it. 6. Review in pairs — have another person read the requirement aloud; if they ask "what does X mean?", revise. 7. Assign IDs early — use a prefix per pattern (U-, E-, S-, O-, N-, C-) for quick identification. 8. Version your requirements — track changes alongside code in the same repository.

---

Quick Reference Card