codecruise 0.1.0

package/config/commands/architect-discuss.md

@@ -0,0 +1,366 @@
+---
+name: architect-discuss
+description: Interactive discussion on specific architecture phase or feature with expert analysis
+disable-model-invocation: true
+tools: Read, Glob, Grep, WebSearch
+model: opus
+---
+
+# /architect-discuss — Architecture Discussion
+
+## Goal
+
+Facilitate peer-to-peer discussion on a specific phase or feature of the architecture. Provide summary, expert analysis, and engage in discussion until finalized.
+
+## Workflow
+
+`/architect` → `/architect-list` → **`/architect-discuss`** ← YOU ARE HERE → `/architect-review` → `/plan`
+
+## When to Use
+
+| Situation | Use /architect-discuss? |
+|-----------|------------------------|
+| Review specific phase before planning | ✅ Yes |
+| Deep dive on database/api/security design | ✅ Yes |
+| Want expert analysis on a feature | ✅ Yes |
+| Stakeholder walkthrough | ✅ Yes |
+| Quick question about one decision | ❌ Use architect agent |
+| Full architecture validation | ❌ Use /architect-review |
+
+## Usage
+
+```
+/architect-discuss "Phase 1"        # Discuss entire phase by name
+/architect-discuss "1"              # Discuss phase by number
+/architect-discuss "database"       # Discuss specific feature by name
+/architect-discuss "1.2"            # Discuss feature by number (e.g., auth)
+/architect-discuss "api" --validate # Include validation in analysis
+```
+
+### Arguments
+
+| Argument | Description | Example |
+|----------|-------------|---------|
+| (positional) | Phase name/number or feature name/number | `"Phase 1"`, `"database"`, `"1.2"` |
+| `--validate` | Include architect-reviewer validation | `/architect-discuss "api" --validate` |
+| `--brief` | Show summary only, skip expert analysis | `/architect-discuss "Phase 1" --brief` |
+
+### Target Resolution
+
+| Input | Resolves To |
+|-------|-------------|
+| `"Phase 1"` | Phase 1 (all features) |
+| `"1"` | Phase 1 |
+| `"database"` | Feature: database |
+| `"1.2"` | Phase 1, Feature 2 (e.g., auth) |
+| `"auth"` | Feature: auth |
+
+## Cost Estimate
+
+| Scope | Estimated Cost |
+|-------|----------------|
+| Single feature | $0.30 - $0.50 |
+| Entire phase (3-4 features) | $0.50 - $1.00 |
+| With validation | +$0.20 - $0.30 |
+
+*Opus model for expert-level analysis.*
+
+## Inputs (read-only)
+
+**Required:**
+- `docs/architecture/*.md` — Architecture documents
+- Target phase or feature specified
+
+**Context (automatically loaded):**
+- `docs/canon/spec.md` — Requirements to reference
+- `docs/context/*.yaml` — Feature constraints/decisions
+- `docs/canon/decisions.md` — Existing ADRs
+
+## Outputs
+
+Discussion is conversational. Changes are applied to architecture files only with explicit user approval.
+
+Optional output:
+- Updates to `docs/canon/decisions.md` — New ADRs from discussion
+
+## Process
+
+### 1) Pre-flight Check
+
+```bash
+# Verify architecture exists
+[ -d docs/architecture ] || echo "ERROR: Run /architect first"
+
+# Verify target exists
+# Parse argument to identify phase/feature
+```
+
+### 2) Load Context
+
+```yaml
+loaded_context:
+  target:
+    type: phase | feature
+    id: "Phase 1" | "database"
+
+  architecture:
+    relevant_sections: [overview.md, database.md, ...]
+
+  spec:
+    relevant_requirements: [FR-001, FR-012, NFR-002, ...]
+
+  decisions:
+    relevant_adrs: [ADR-001, ADR-003, ...]
+```
+
+### 3) Present Summary
+
+**For Phase:**
+
+```markdown
+## Phase 1: Foundation — Summary
+
+**Features:**
+  1.1 database     - PostgreSQL schema, Prisma models
+  1.2 auth         - JWT + session, OAuth providers
+  1.3 api-core     - tRPC routers, REST endpoints
+
+**Tech Stack:**
+- Database: PostgreSQL 16 + Prisma ORM
+- Auth: JWT access + session refresh, OAuth (Google, Apple)
+- API: tRPC (internal) + REST (auth, uploads)
+
+**Spec Coverage:**
+- FR-001 to FR-015 (15 requirements)
+- NFR-001 to NFR-003 (3 non-functional)
+- UC-001 to UC-005 (5 use cases)
+
+**Key Decisions:**
+- ADR-001: Hybrid tRPC + REST
+- ADR-003: PostgreSQL over MySQL
+- ADR-005: UUID primary keys
+```
+
+**For Feature:**
+
+```markdown
+## Feature: database — Summary
+
+**Phase:** 1 (Foundation)
+**Architecture File:** docs/architecture/database.md
+
+**Tech:**
+- PostgreSQL 16
+- Prisma ORM
+- 12 tables, 18 indexes
+
+**Key Entities:**
+- users, wallets, transactions, budgets, categories
+- groups, settlements, receipts
+
+**Spec Coverage:**
+  ✅ FR-012: Multi-wallet support
+  ✅ FR-015: Transaction history with pagination
+  ✅ FR-018: Budget tracking per category
+  ✅ NFR-002: Query response < 100ms
+
+**Related Decisions:**
+- ADR-003: PostgreSQL for JSONB support
+- ADR-005: UUID primary keys for distributed-friendly IDs
+```
+
+### 4) Provide Expert Analysis
+
+```markdown
+## Expert Analysis
+
+### ✅ Strengths
+
+1. **Schema Design**
+   - All spec entities properly modeled
+   - Relationships correctly normalized
+   - Good use of enums for fixed values
+
+2. **Index Strategy**
+   - Compound index on `transactions(user_id, date)` supports history queries
+   - Foreign keys indexed for join performance
+
+3. **Future-Proofing**
+   - UUID keys allow distributed scaling
+   - Extensibility notes for v2 features documented
+
+### ⚠️ Concerns
+
+1. **Connection Pooling**
+   - Not documented in architecture
+   - NFR-001 mentions 10k+ concurrent users
+   - **Recommendation:** Add PgBouncer or Prisma connection pooling
+
+2. **Soft Deletes**
+   - Not specified for any entities
+   - GDPR requires data deletion capability
+   - **Recommendation:** Add `deleted_at` to users, transactions (audit trail)
+
+3. **Missing Index**
+   - Budget queries filter by `user_id + category_id`
+   - No compound index exists
+   - **Recommendation:** Add `idx_budget_user_category`
+
+### 🔍 Version Check
+
+| Component | Current | Latest | Status |
+|-----------|---------|--------|--------|
+| PostgreSQL | 16 | 17 | ⚠️ Consider upgrade |
+| Prisma | 5.x | 6.x | ⚠️ Major version available |
+
+*Searched: "PostgreSQL latest version 2025", "Prisma ORM latest version 2025"*
+
+### 🎯 Spec Alignment
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| FR-012 | ✅ Covered | wallets table with user_id FK |
+| FR-015 | ✅ Covered | Proper indexes for pagination |
+| FR-022 | ⚠️ Partial | Recurring transactions schema exists, no trigger |
+| NFR-002 | ⚠️ Unclear | Indexes present but no benchmark targets |
+
+### 💡 Suggestions
+
+1. Document connection pooling strategy (PgBouncer config)
+2. Add soft delete columns for GDPR compliance
+3. Consider PostgreSQL 17 for improved performance
+4. Add performance benchmark targets to verify NFR-002
+```
+
+### 5) Open Discussion
+
+```markdown
+---
+
+What would you like to discuss or change?
+
+You can:
+- Ask questions about any aspect
+- Request changes (I'll note them)
+- Ask me to elaborate on concerns
+- Request validation with architect-reviewer
+- Move on when satisfied
+```
+
+### 6) Handle Discussion
+
+**User asks question:**
+- Provide detailed answer with references to spec/architecture
+- Offer expert opinion when relevant
+
+**User requests change:**
+- Confirm understanding
+- Ask if they want it applied now or noted for later
+- If applied: Update architecture file with their approval
+
+**User says "done" or "satisfied":**
+- Summarize any changes made or noted
+- Suggest next steps
+
+### 7) Discussion Summary (on completion)
+
+```markdown
+## Discussion Summary: database
+
+**Duration:** ~10 minutes
+
+**Changes Applied:**
+1. Added connection pooling section to database.md
+2. Added soft delete columns to users and transactions
+
+**Changes Noted (apply later):**
+1. Consider PostgreSQL 17 upgrade
+
+**Decisions Made:**
+- DD-001: Use PgBouncer for connection pooling
+- DD-002: Soft deletes for users and transactions only
+
+**Next Steps:**
+- /architect-discuss "auth" → Continue with next feature
+- /architect-review --section database → Validate changes
+```
+
+## Expert Analysis Components
+
+### 1. Strengths Identification
+
+Look for:
+- Good patterns followed
+- Proper normalization
+- Index coverage
+- Security considerations
+- Scalability provisions
+
+### 2. Concerns Identification
+
+Check for:
+- Missing patterns (caching, pooling, rate limiting)
+- Spec gaps (requirements not covered)
+- Security gaps (auth, validation, encryption)
+- Scalability issues (N+1, missing indexes)
+- Version currency (outdated dependencies)
+
+### 3. Version Validation
+
+**Required searches:**
+```
+"[technology] latest stable version 2025"
+"[technology] LTS version current"
+```
+
+Report:
+- Current version in architecture
+- Latest stable available
+- Recommendation (upgrade/keep)
+
+### 4. Spec Alignment Check
+
+Cross-reference:
+- Functional requirements (FR-XXX)
+- Non-functional requirements (NFR-XXX)
+- Use cases (UC-XXX)
+
+Report status: ✅ Covered | ⚠️ Partial | ❌ Missing
+
+### 5. Cross-Section Consistency
+
+Check for misalignments:
+- Types match between database and API schemas
+- Security model consistent across components
+- Naming conventions consistent
+
+## Quality Bar
+
+- Expert analysis is specific and actionable
+- All relevant spec requirements referenced
+- Version checks performed with web search
+- Concerns include concrete recommendations
+- Discussion is collaborative, not one-sided
+- Changes are confirmed before applying
+
+## Error Handling
+
+### Target Not Found
+
+```
+❌ Feature "payments" not found in architecture
+
+Available features:
+  Phase 1: database, auth, api-core
+  Phase 2: transactions, budgets, categories
+
+Try: /architect-discuss "transactions"
+```
+
+### Architecture Not Found
+
+```
+❌ No architecture found
+
+Run /architect first to generate architecture documentation.
+```

package/config/commands/architect-list.md

@@ -0,0 +1,160 @@
+---
+name: architect-list
+description: List phases and features from existing architecture
+disable-model-invocation: true
+tools: Read, Glob
+model: haiku
+---
+
+# /architect-list — Architecture Quick Reference
+
+## Goal
+
+Display phases and features from existing architecture documentation. Quick reference without regenerating anything.
+
+## Workflow
+
+`/architect` → **`/architect-list`** ← YOU ARE HERE → `/architect-discuss` → `/architect-review`
+
+## When to Use
+
+| Situation | Use /architect-list? |
+|-----------|---------------------|
+| Need quick reference of architecture | ✅ Yes |
+| Forgot what phases/features exist | ✅ Yes |
+| Before running /architect-discuss | ✅ Yes |
+| No architecture exists yet | ❌ Run /architect first |
+
+## Usage
+
+```
+/architect-list
+```
+
+No arguments needed.
+
+## Cost Estimate
+
+| Architecture Size | Estimated Cost |
+|-------------------|----------------|
+| Any size | < $0.05 |
+
+*Haiku model - fast and cheap.*
+
+## Inputs (read-only)
+
+**Required:**
+- `docs/architecture/overview.md` — Contains phases/features structure
+
+**Optional:**
+- `docs/architecture/*.md` — Other architecture documents
+
+## Outputs
+
+None - display only.
+
+## Process
+
+### 1) Pre-flight Check
+
+```bash
+# Verify architecture exists
+[ -d docs/architecture ] || echo "ERROR: Run /architect first"
+[ -f docs/architecture/overview.md ] || echo "ERROR: No architecture found"
+```
+
+### 2) Extract Phases & Features
+
+Read `overview.md` and extract:
+- Project name and version
+- Generation date
+- Phases with features
+- Architecture sections
+
+### 3) Display Overview
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                    ARCHITECTURE OVERVIEW                       ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                                ║
+║  Project: {name}                                               ║
+║  Version: {version}                                            ║
+║  Generated: {date}                                             ║
+║                                                                ║
+╠═══════════════════════════════════════════════════════════════╣
+║  PHASES & FEATURES                                             ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                                ║
+║  Phase 1: Foundation                                           ║
+║    1.1 database     - PostgreSQL schema, Prisma models         ║
+║    1.2 auth         - JWT + session, OAuth providers           ║
+║    1.3 api-core     - tRPC routers, REST endpoints             ║
+║                                                                ║
+║  Phase 2: Core Features                                        ║
+║    2.1 transactions - CRUD, receipts, OCR integration          ║
+║    2.2 budgets      - Limits, alerts, tracking                 ║
+║    2.3 categories   - User-defined, default set                ║
+║                                                                ║
+║  Phase 3: Advanced                                             ║
+║    3.1 analytics    - Reports, charts, insights                ║
+║    3.2 groups       - Shared expenses, settlements             ║
+║                                                                ║
+╠═══════════════════════════════════════════════════════════════╣
+║  ARCHITECTURE SECTIONS                                         ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                                ║
+║  overview.md       System context, tech stack, principles      ║
+║  database.md       Schema, indexes, migrations                 ║
+║  api.md            Endpoints, contracts, OpenAPI               ║
+║  components.md     Module structure, dependencies              ║
+║  security.md       Auth, encryption, access control            ║
+║  data-flow.md      Transaction flows, sync patterns            ║
+║  integrations.md   External services, webhooks                 ║
+║  decisions.md      Architecture Decision Records               ║
+║  extensibility.md  Future feature extension points             ║
+║                                                                ║
+╠═══════════════════════════════════════════════════════════════╣
+║  COMMANDS                                                      ║
+╠═══════════════════════════════════════════════════════════════╣
+║                                                                ║
+║  /architect-discuss "Phase 1"  → Discuss entire phase          ║
+║  /architect-discuss "database" → Discuss specific feature      ║
+║  /architect-discuss "1.2"      → Discuss by number (auth)      ║
+║  /architect-review             → Full architecture validation  ║
+║                                                                ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+## Error Handling
+
+### No Architecture Found
+
+```
+❌ No architecture found
+
+Run /architect first to generate architecture documentation.
+
+Required: docs/architecture/overview.md
+```
+
+### Partial Architecture
+
+```
+⚠️ Partial architecture found
+
+Available sections:
+  ✓ overview.md
+  ✓ database.md
+  ✗ api.md (missing)
+  ✗ security.md (missing)
+
+Run /architect to regenerate, or /architect --section api to add missing sections.
+```
+
+## Quality Bar
+
+- Fast execution (< 2 seconds)
+- Clear, scannable output
+- Shows all phases/features with numbers
+- Includes helpful next commands

package/config/commands/architect-review.md

@@ -0,0 +1,111 @@
+---
+name: architect-review
+description: Audit architecture documents against spec for completeness and consistency
+disable-model-invocation: true
+tools: Read, Write, Edit, Glob, Grep
+model: opus
+---
+
+# /architect-review — Architecture Audit
+
+Validate architecture against spec.md for coverage, consistency, and security.
+
+## Usage
+
+```
+/architect-review                    # Full audit
+/architect-review --section database # Specific section
+/architect-review --check-versions   # Validate tech versions
+/architect-review --strict           # Fail on warnings
+```
+
+## Inputs
+
+**Required**: `docs/canon/spec.md`, `docs/architecture/*.md`
+
+**Optional**: `docs/context/*.yaml`, `docs/canon/decisions.md`
+
+## Audits
+
+### Database Schema
+
+| Check | Criteria |
+|-------|----------|
+| Entity coverage | All spec entities have tables |
+| Field coverage | Entity fields mapped to columns |
+| Relationship support | FKs support use cases |
+| Index coverage | Query patterns have indexes |
+
+### API Contracts
+
+| Check | Criteria |
+|-------|----------|
+| FR coverage | Every FR has endpoint |
+| UC coverage | Use case flows supported |
+| Auth coverage | Protected endpoints require auth |
+| CRUD completeness | Entities have operations |
+
+### Security
+
+| Check | Criteria |
+|-------|----------|
+| Auth flow complete | Login, logout, refresh documented |
+| Encryption | Sensitive data encrypted |
+| Compliance | GDPR, PCI-DSS addressed |
+| Headers | Security headers configured |
+
+### Components
+
+| Check | Criteria |
+|-------|----------|
+| No circular deps | Acyclic graph |
+| Layer violations | Routers don't bypass services |
+| Module boundaries | Clear separation |
+
+### ADRs
+
+| Check | Criteria |
+|-------|----------|
+| Decision coverage | D-XXX have ADRs |
+| Rationale present | Clear reasoning |
+| Consequences documented | Trade-offs explicit |
+
+## Grading
+
+| Grade | Meaning | Action |
+|-------|---------|--------|
+| A+ | Perfect | Proceed to /init |
+| A | Minor polish | Can proceed |
+| B | Few gaps | Fix, re-review |
+| C | Significant gaps | Multiple fixes |
+| D | Major issues | Re-run /architect |
+
+**Minimum to proceed**: B (all critical resolved)
+
+## Output
+
+```
+✓ Architecture audit complete
+
+Grade: B+
+
+Coverage:
+  - Database: 12/12 entities (100%)
+  - API: 43/45 requirements (96%)
+  - Security: 8/9 controls (89%)
+  - ADRs: 13/15 decisions (87%)
+
+Critical: 2 (must fix)
+Warnings: 3 (should fix)
+
+Report: docs/architecture/audit-report.md
+
+Next: Fix critical, re-run
+```
+
+## Quality Bar
+
+- Every spec requirement traced
+- No critical issues for B+
+- Actionable recommendations
+- Clear next steps