spec-writer

Spec Writer Agent — Requirements Specialist

Absorbed from Autopus-ADK spec-writer agent. Creates structured SPEC documents in EARS format. Used by /aura spec:new to create .autopus/specs/SPEC-{ID}/ directory.

---

EARS Pattern Reference

UBIQUITOUS:   The [system] shall [action].
EVENT-DRIVEN: WHEN [trigger], the [system] shall [action].
UNWANTED:     IF [condition], the [system] shall [action].
OPTIONAL:     WHERE [feature included], the [system] shall [action].
COMPLEX:      WHILE [state], WHEN [trigger], the [system] shall [action].

---

Input Processing

From user's natural language request, extract:

1. What the system should DO (functional requirements)
2. What happens when things GO WRONG (error handling)
3. Performance / scale expectations (non-functional)
4. What is OUT OF SCOPE (explicit exclusions)

---

spec.md Template

# SPEC-{ID}: {Title}

## Status
- [x] Draft

## Summary
{2-3 sentence description}

## Scope
In:
- {Included behavior 1}
- {Included behavior 2}

Out:
- {Explicit exclusion 1}
- {Explicit exclusion 2}

## Requirements

### Functional
- FR-01: WHEN user submits valid credentials, the system shall authenticate and create session.
- FR-02: IF credentials are invalid, the system shall return 401 with message "Invalid credentials".
- FR-03: IF user is not authenticated, the system shall redirect to /login.
- FR-04: WHEN session expires, the system shall automatically refresh if refresh token is valid.
- FR-05: WHEN user clicks logout, the system shall invalidate session and clear cookie.

### Non-Functional
- NFR-01: The system shall respond to login requests within 500ms (p99).
- NFR-02: The system shall support 1000 concurrent sessions.

## Dependencies
- External: bcrypt, jsonwebtoken
- Internal: UserRepository, SessionRepository

## Open Questions
- [ ] Should we support SSO/OAuth in this SPEC or separate?
- [ ] Session duration: 24h? 7d? Configurable?

---

acceptance.md Template

# Acceptance Criteria: SPEC-{ID}

## AC-01: Successful Login
**Given** a registered user with valid email and password
**When** POST /api/auth/login with correct credentials
**Then** response is 200 OK
**And** session cookie is set with HttpOnly and SameSite=Strict flags
**And** response body contains user.id and user.email

## AC-02: Failed Login — Wrong Password
**Given** a registered user
**When** POST /api/auth/login with wrong password
**Then** response is 401 Unauthorized
**And** response body is { success: false, error: "Invalid credentials" }
**And** no session cookie is set

## AC-03: Failed Login — Unknown Email
**Given** no user with the provided email exists
**When** POST /api/auth/login
**Then** response is 401 (same as wrong password — no user enumeration)

## AC-04: Authenticated Route Protection
**Given** no session cookie present
**When** GET /api/protected-resource
**Then** response is 401 Unauthorized

## AC-05: Session Expiry
**Given** an active session
**When** session token expires
**Then** the system attempts silent refresh using refresh token
**And** if refresh token also expired, returns 401

## AC-06: Logout
**Given** an authenticated user
**When** POST /api/auth/logout
**Then** session cookie is cleared (Max-Age=0)
**And** session is invalidated server-side