create-adrs

Skill Type: Actuator (Design Documentation) Purpose: Document architecture decisions acknowledging ecosystem E(t) Prerequisites: Strategic technical decision needed

Agent Instructions

You are creating Architecture Decision Records (ADRs) that acknowledge ecosystem E(t) constraints.

Critical: ADRs document GIVEN constraints (E(t)), not just CHOSEN solutions.

Format: "Given E(t), we chose X" (not "we chose X")

ADR Structure

Template

# ADR-{ID}: {Decision Title}

**Date**: {YYYY-MM-DD}
**Status**: Accepted | Rejected | Superseded | Deprecated
**Deciders**: {Who made this decision}

---

## Context

**Requirements**:
- <REQ-ID>: User authentication
- REQ-NFR-SEC-001: Secure password storage

**Problem**:
We need to choose a password hashing algorithm that is secure
against brute force attacks while maintaining acceptable performance.

**Ecosystem E(t) Constraints**:
- Team Experience: Team familiar with bcrypt
- Infrastructure: Running on AWS (bcrypt supported)
- Compliance: PCI-DSS recommends strong hashing
- Performance: Login response must be < 500ms (REQ-NFR-PERF-001)
- Libraries Available: bcrypt, argon2, scrypt available

---

## Decision

**Selected**: bcrypt with cost factor 12

**Rejected Alternatives**:
- SHA256: ❌ Too fast (vulnerable to brute force)
- MD5: ❌ Cryptographically broken
- Argon2: ⚠️ Better security but team unfamiliar, migration risk
- scrypt: ⚠️ Good security but less widely supported

**Rationale**:
1. bcrypt is industry standard (acknowledged E(t))
2. Team has experience with bcrypt (acknowledge E(t) - team capabilities)
3. Cost factor 12 balances security and performance
4. Meets PCI-DSS requirements (acknowledge E(t) - compliance)
5. Login tests show 200ms average (well within 500ms SLA)

---

## Ecosystem Constraints Acknowledged

**Team** (E(t)):
- Team knows: bcrypt, SHA256
- Team doesn't know: Argon2 implementation
- Risk: Learning curve with Argon2

**Infrastructure** (E(t)):
- Platform: AWS Lambda + RDS PostgreSQL
- bcrypt: Native support, no additional dependencies
- Argon2: Would need custom layer

**Compliance** (E(t)):
- PCI-DSS: Requires strong, salted hashing
- bcrypt: Explicitly mentioned in PCI guidelines
- Audit: External auditors familiar with bcrypt

**Performance** (E(t)):
- Requirement: Login < 500ms (REQ-NFR-PERF-001)
- bcrypt (cost 12): ~200ms (acceptable)
- Argon2: ~250ms (acceptable but no experience)

**Timeline** (E(t)):
- Sprint: 2 weeks
- bcrypt: No learning curve (immediate)
- Argon2: 2-3 days research + testing

---

## Constraints Imposed Downstream

**Code Stage** (constraints for implementation):
- MUST use bcrypt library (not custom hashing)
- MUST use cost factor 12 (not lower)
- MUST salt passwords (bcrypt does this automatically)

**Runtime Stage** (constraints for deployment):
- Infrastructure: bcrypt library must be available
- Performance monitoring: Track hash time (should be ~200ms)

**Testing Stage**:
- Test hash time (ensure < 500ms)
- Test bcrypt version (security updates)

---

## Consequences

**Positive**:
- ✅ Team productive immediately (no learning curve)
- ✅ Proven security (industry standard)
- ✅ PCI-DSS compliant (audit-friendly)
- ✅ Performance acceptable (< 500ms)

**Negative**:
- ⚠️ Not latest algorithm (Argon2 is newer)
- ⚠️ Vendor lock-in to bcrypt (migration costly)

**Neutral**:
- Cost factor 12 is balance (could be 10 for faster, 14 for stronger)

---

## Related Decisions

- ADR-001: Database selection (PostgreSQL)
- ADR-003: Session management (JWT)

**Supersedes**: None
**Superseded By**: None

---

## References

- PCI-DSS Password Requirements: https://www.pcisecuritystandards.org/
- bcrypt Documentation: https://en.wikipedia.org/wiki/Bcrypt
- OWASP Password Storage: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html

ADR Numbering

Sequential: ADR-001, ADR-002, ADR-003, ...

Categories:

• Infrastructure: Cloud provider, hosting, databases
• Security: Authentication, encryption, authorization
• Architecture: Patterns, frameworks, languages
• Integration: APIs, external services
• Data: Storage, schemas, migration

When to Create ADRs

Create ADR for:

• ✅ Cloud provider choice (AWS vs GCP vs Azure)
• ✅ Language/framework choice (Python vs Node vs Java)
• ✅ Database choice (PostgreSQL vs MySQL vs MongoDB)
• ✅ Authentication approach (JWT vs sessions vs OAuth)
• ✅ API style (REST vs GraphQL vs gRPC)
• ✅ Architectural pattern (monolith vs microservices)

Don't create ADR for:

• ❌ Implementation details (already covered by code)
• ❌ Tactical decisions (variable names, file structure)
• ❌ Obvious choices (using standard library)

Output Format

[CREATE ADR - bcrypt Password Hashing]

Decision: Use bcrypt for password hashing

Context:
  Requirements: <REQ-ID>, REQ-NFR-SEC-001
  Problem: Need secure password hashing
  Ecosystem E(t): Team knows bcrypt, PCI-DSS compliant, AWS supported

Decision:
  Selected: bcrypt (cost factor 12)
  Rejected: SHA256 (too fast), Argon2 (team unfamiliar)

Ecosystem Constraints Acknowledged:
  - Team capabilities: knows bcrypt ✓
  - Compliance: PCI-DSS requires strong hashing ✓
  - Performance: Must be < 500ms ✓
  - Infrastructure: AWS supports bcrypt ✓

Constraints Imposed:
  - Code must use bcrypt library
  - Code must use cost factor 12
  - Runtime must have bcrypt available

Created: docs/adrs/ADR-002-password-hashing.md

✅ ADR Created!
   Architecture decision documented
   Ecosystem E(t) acknowledged
   Downstream constraints clear

Notes

Why ADRs?

• Document "why": Explains reasoning behind decisions
• Acknowledge E(t): Shows we understand ecosystem constraints
• Prevent re-litigation: Decision made, recorded, done
• Onboarding: New team members understand past decisions

ADRs vs Constraints (C-*):

• C-*: Given constraints we MUST work within
• ADR: Chosen solutions GIVEN those constraints

Example:

C-001: PCI-DSS requires strong password hashing (GIVEN)
ADR-002: We chose bcrypt (GIVEN C-001 and team skills)

Homeostasis Goal:

desired_state:
  all_strategic_decisions_documented: true
  ecosystem_constraints_acknowledged: true
  rationale_clear: true

"Excellence or nothing" 🔥