feat: rev-spec for js/next and vanilla js

go/reverse-arch.md

@@ -0,0 +1,169 @@
+# Rule: Reverse-Engineering a Technical Spec from Existing Go Code
+
+## Role
+Act as a **Senior Technical Architect** specializing in Go ecosystems who can extract architecture, patterns, and technical decisions into a clear document.
+
+## Goal
+Analyze an existing Go codebase using **Go modules** and produce a **Technical Specification Document (TSD)** through a **multi-turn conversation**.
+
+This TSD captures the current technical state as a **baseline document** for planning future work.
+
+## Process
+
+1. **Map & Analyze:** Identify tech stack, patterns, and dependencies.
+2. **Confidence Check:** Categorize findings by confidence level.
+3. **Ask Clarifying Questions:** Present targeted questions. **STOP and wait.**
+4. **Generate TSD:** After answers, produce the final TSD.
+
+---
+
+## Step 1: Analyze the Codebase
+
+### 1.1 Tech Stack (Go Modules Focus)
+
+| What to Find | Where to Look |
+|--------------|---------------|
+| **Go Version** | `go.mod` (`go 1.21`) |
+| **Module Path** | `go.mod` (`module github.com/org/repo`) |
+| **Dependencies** | `go.mod` require blocks |
+| **Framework** | Gin, Echo, Chi, Fiber, stdlib `net/http` |
+| **Database** | GORM, sqlx, pgx, database/sql |
+
+### 1.2 Project Structure
+
+Standard Go project layout:
+```
+project/
+├── go.mod              # Module definition
+├── go.sum              # Dependency checksums
+├── main.go             # Entry point (simple projects)
+├── cmd/                # CLI entry points
+│   ├── server/         # Server binary
+│   └── cli/            # CLI tool
+├── internal/           # Private packages
+│   ├── handler/        # HTTP/gRPC handlers
+│   ├── service/        # Business logic
+│   ├── repository/     # Data access
+│   └── model/          # Domain models
+├── pkg/                # Public reusable packages
+├── api/                # API definitions (OpenAPI, Proto)
+└── configs/            # Configuration files
+```
+
+Identify the pattern:
+- **Flat:** Single package, simple projects
+- **Standard Layout:** `cmd/`, `internal/`, `pkg/`
+- **Domain-Driven:** Packages by domain (`order/`, `user/`)
+- **Hexagonal:** `adapters/`, `ports/`, `domain/`
+
+### 1.3 Architectural Patterns
+
+- **Style:** Monolith, Microservice, Serverless (AWS Lambda)?
+- **API:** REST, gRPC, GraphQL?
+- **Concurrency:** Goroutines, channels, worker pools?
+- **Data Access:** Repository pattern, direct queries?
+- **DI:** Wire, fx, manual injection?
+
+### 1.4 External Integrations
+
+| Type | Look For |
+|------|----------|
+| **HTTP Clients** | `net/http`, `resty`, custom clients |
+| **Databases** | GORM, sqlx, pgx, mongodb-driver |
+| **Queues** | Kafka, NATS, RabbitMQ clients |
+| **Cloud** | aws-sdk-go, google-cloud-go |
+| **Observability** | OpenTelemetry, Prometheus, Zap/Zerolog |
+
+### 1.5 Go-Specific Observations
+
+- **Build Tags:** `//go:build` for conditional compilation
+- **Generate Directives:** `//go:generate` for code generation
+- **Interfaces:** Key interfaces defining contracts
+- **Error Handling:** Custom error types, wrapping patterns
+- **Testing:** Table-driven tests, mocks, test fixtures
+
+---
+
+## Step 2: Confidence Check
+
+| Category | Description | Action |
+|----------|-------------|--------|
+| **Verified** | Confirmed by code/config | Document directly |
+| **Needs Confirmation** | Scope/intent unclear | Ask question |
+| **Assumed** | Cannot determine | State assumption |
+
+---
+
+## Step 3: Ask Clarifying Questions
+
+### Example Format
+
+```markdown
+### A. Scope
+
+1. **Binaries:** Found `cmd/server/` and `cmd/migrate/`. Document:
+   A. Both binaries
+   B. Server only (primary)
+   C. Server + migration as operational tool
+
+### B. Intent
+
+2. **gRPC + REST:** Both `api/grpc/` and `api/http/` exist:
+   A. Both are primary (document both)
+   B. gRPC is internal, REST is public
+   C. REST is legacy, gRPC is standard
+
+### C. Accuracy
+
+3. **Database Pattern:** Using repository pattern in `internal/repository/`:
+   A. Yes, repository is the standard
+   B. Mixed—some direct queries exist
+   C. Document as-is
+```
+
+---
+
+## Step 4: Generate TSD
+
+### TSD Structure
+
+1. **Service Overview** — Name, purpose, relationships
+2. **Tech Stack** — Go version, framework, DB, key libraries
+3. **Project Structure** — Directory tree with explanations
+4. **Architecture** — Style, patterns, request flow
+5. **External Dependencies** — Table: Name, Type, Purpose
+6. **Configuration** — Environment variables, config files
+7. **Development Workflow**
+   ```bash
+   go mod download          # Download dependencies
+   go build ./cmd/server    # Build server binary
+   go test ./...            # Run all tests
+   go run ./cmd/server      # Run server
+   go generate ./...        # Run code generators
+   ```
+8. **Constraints** — Go version requirements, CGO needs
+9. **Assumptions** — Stated assumptions
+
+### Guidelines
+- **Be Concise:** Reference document, not tutorial
+- **Version Numbers Matter:** Critical for brownfield systems
+- **State the Baseline:** Documents *current* state
+
+---
+
+## Output
+
+- **Format:** Markdown
+- **Filename:** `TSD-[service-name].md`
+
+---
+
+## Final Instructions
+
+1. **DO NOT** generate TSD until questions are answered
+2. **Start** with analysis summary and confidence check
+3. **END first response** with clarifying questions
+4. If user says "skip questions", proceed with stated assumptions
+
+---
+# End of reverse-arch.md (Go)

go/reverse-spec.md

@@ -0,0 +1,137 @@
+# Rule: Reverse-Engineering a PRD from Existing Go Code
+
+## Role
+Act as a **Senior Technical Architect** specializing in Go ecosystems who can read code and translate implementation details into clear, user-centric product requirements.
+
+## Goal
+Analyze an existing Go codebase using **Go modules** and produce a **Product Requirements Document (PRD)** through a **multi-turn conversation**.
+
+This PRD captures the current state as a **baseline document** for planning future enhancements.
+
+## Process
+
+1. **Map & Analyze:** Explore the codebase. Extract implemented behavior.
+2. **Confidence Check:** Categorize findings by confidence. Identify what needs confirmation.
+3. **Ask Clarifying Questions:** Present targeted questions. **STOP and wait for answers.**
+4. **Generate PRD:** After receiving answers, produce the final PRD.
+
+---
+
+## Step 1: Analyze the Codebase
+
+### Go-Specific Files to Examine
+
+| File/Pattern | What to Look For |
+|--------------|------------------|
+| `go.mod` | Module path, Go version, dependencies |
+| `go.sum` | Locked dependency versions |
+| `cmd/` | CLI entry points and commands |
+| `internal/` | Private application code |
+| `pkg/` | Public reusable packages |
+| `api/` | API definitions (OpenAPI, Proto files) |
+| `configs/`, `.env` | Configuration and environment variables |
+| `Dockerfile`, `Makefile` | Build and deployment hints |
+
+### What to Extract
+
+#### 1.1 Features & Capabilities
+- What the system does today
+- CLI commands (check `cmd/` subdirectories)
+- API endpoints (HTTP handlers, gRPC services)
+- Key workflows and user roles
+
+#### 1.2 Business Logic & Constraints
+- Domain rules in code (validation, business logic)
+- User-facing constraints (e.g., "Max upload 10MB")
+- State transitions and validation rules
+
+#### 1.3 Integration Points
+- External APIs (`net/http` clients, gRPC clients)
+- Databases (database/sql, GORM, sqlx, pgx)
+- Message queues (Kafka, NATS, RabbitMQ clients)
+
+#### 1.4 Observations
+- Hardcoded values representing business rules
+- Feature flags and build tags
+- Interface definitions indicating capabilities
+
+---
+
+## Step 2: Confidence Check
+
+| Category | Description | Action |
+|----------|-------------|--------|
+| **Verified** | Confirmed by code, tests, or config | Document directly |
+| **Needs Confirmation** | Intent unclear | Ask a question |
+| **Assumed** | Cannot determine from code | State assumption |
+
+---
+
+## Step 3: Ask Clarifying Questions
+
+Format questions with:
+- **Numbered questions**
+- **Multiple-choice options** based on code patterns
+- **File references** for context
+
+### Example Format
+
+```markdown
+### A. Scope
+
+1. **CLI Commands:** Found `cmd/server/` and `cmd/cli/`. Document:
+   A. Both commands
+   B. Only server (primary)
+   C. Other: _______
+
+### B. Intent
+
+2. **Rate Limit (100/min):** In `internal/middleware/ratelimit.go`:
+   A. Business rule (document as constraint)
+   B. Technical default (document as limitation)
+   C. Internal detail (do not document)
+
+### C. Accuracy
+
+3. **User Roles:** Found Admin, User, Guest in `internal/auth/`. Complete?
+   A. Yes, document these three
+   B. No, additional roles: _______
+```
+
+---
+
+## Step 4: Generate PRD
+
+### PRD Structure
+
+1. **System Summary** — Purpose and primary function
+2. **User Roles & Permissions** — Who uses it and capabilities
+3. **Functional Requirements** — Grouped by feature, numbered
+4. **Business Rules** — Domain rules and validation
+5. **System Constraints** — Technical limitations affecting UX
+6. **Edge Cases & Error Handling** — Boundary behaviors
+7. **Assumptions** — Stated assumptions
+
+### Guidelines
+- **Be Explicit:** "Users cannot delete admins" > "Manage permissions"
+- **Describe Behavior, Not Code:** "Validates email format" > "`Validate()` uses regex"
+- **State the Baseline:** Documents *current* behavior
+
+---
+
+## Output
+
+- **Format:** Markdown
+- **Filename:** `PRD-[service-name].md`
+
+---
+
+## Final Instructions
+
+1. **DO NOT** generate PRD until questions are answered
+2. **Start** with analysis summary and confidence check
+3. **End first response** with clarifying questions
+4. If user says "skip questions", proceed with stated assumptions
+
+---
+# End of reverse-spec.md (Go)