telo3-ai 5.0.0

package/scripts/validate-project-context.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+
+#
+# Project Context System Validation Script
+#
+# Validates project context documents for common issues.
+# Usage: ./validate-project-context.sh [context-directory]
+#
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+# Target directory
+TARGET_DIR="${1:-.}"
+
+# Find context directory
+CONTEXT_DIRS=(
+  "$TARGET_DIR/project-context"
+  "$TARGET_DIR/docs/project-context"
+  "$TARGET_DIR"
+)
+
+CONTEXT_DIR=""
+for dir in "${CONTEXT_DIRS[@]}"; do
+  if [ -f "$dir/prd.md" ] || [ -f "$dir/architecture.md" ]; then
+    CONTEXT_DIR="$dir"
+    break
+  fi
+done
+
+if [ -z "$CONTEXT_DIR" ]; then
+  echo -e "${RED}Error: Could not find project context directory${NC}"
+  echo "Looked in:"
+  for dir in "${CONTEXT_DIRS[@]}"; do
+    echo "  - $dir"
+  done
+  exit 1
+fi
+
+echo "======================================"
+echo "Project Context Validation"
+echo "======================================"
+echo ""
+echo "Context directory: $CONTEXT_DIR"
+echo ""
+
+# Required files
+REQUIRED_FILES=(
+  "prd.md"
+  "architecture.md"
+  "rules.md"
+  "design.md"
+  "tasks.md"
+  "memory.md"
+)
+
+ERRORS=0
+WARNINGS=0
+
+# Check for required files
+echo "Checking required files..."
+for file in "${REQUIRED_FILES[@]}"; do
+  if [ -f "$CONTEXT_DIR/$file" ]; then
+    echo -e "${GREEN}✓ Found: $file${NC}"
+  else
+    echo -e "${RED}✗ Missing: $file${NC}"
+    ERRORS=$((ERRORS + 1))
+  fi
+done
+echo ""
+
+# Check for secret patterns
+echo "Checking for accidental secrets..."
+SECRET_PATTERNS=(
+  "api_key"
+  "API_KEY"
+  "apiKey"
+  "secret_key"
+  "SECRET_KEY"
+  "secretKey"
+  "password.*=.*['\"]"
+  "token.*=.*['\"]"
+  "-----BEGIN.*PRIVATE KEY-----"
+)
+
+for file in "${REQUIRED_FILES[@]}"; do
+  if [ -f "$CONTEXT_DIR/$file" ]; then
+    for pattern in "${SECRET_PATTERNS[@]}"; do
+      if grep -i -q "$pattern" "$CONTEXT_DIR/$file" 2>/dev/null; then
+        echo -e "${YELLOW}⚠ Potential secret pattern in $file: $pattern${NC}"
+        WARNINGS=$((WARNINGS + 1))
+      fi
+    done
+  fi
+done
+
+if [ $WARNINGS -eq 0 ]; then
+  echo -e "${GREEN}✓ No obvious secret patterns found${NC}"
+fi
+echo ""
+
+# Check for placeholder content
+echo "Checking for placeholders..."
+PLACEHOLDER_COUNT=0
+for file in "${REQUIRED_FILES[@]}"; do
+  if [ -f "$CONTEXT_DIR/$file" ]; then
+    COUNT=$(grep -c "\[.*\]" "$CONTEXT_DIR/$file" 2>/dev/null || true)
+    if [ $COUNT -gt 5 ]; then
+      echo -e "${YELLOW}⚠ $file has $COUNT placeholder sections${NC}"
+      PLACEHOLDER_COUNT=$((PLACEHOLDER_COUNT + 1))
+    fi
+  fi
+done
+
+if [ $PLACEHOLDER_COUNT -eq 0 ]; then
+  echo -e "${GREEN}✓ Files appear customized${NC}"
+else
+  echo -e "${YELLOW}Note: Some files have many placeholders. Consider customizing them.${NC}"
+fi
+echo ""
+
+# Check file sizes (detect if they're still mostly template)
+echo "Checking file sizes..."
+for file in "${REQUIRED_FILES[@]}"; do
+  if [ -f "$CONTEXT_DIR/$file" ]; then
+    SIZE=$(wc -l < "$CONTEXT_DIR/$file")
+    if [ $SIZE -lt 10 ]; then
+      echo -e "${YELLOW}⚠ $file seems very short ($SIZE lines)${NC}"
+      WARNINGS=$((WARNINGS + 1))
+    fi
+  fi
+done
+echo ""
+
+# Summary
+echo "======================================"
+echo "Validation Summary"
+echo "======================================"
+echo ""
+
+if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
+  echo -e "${GREEN}✓ All checks passed!${NC}"
+  echo ""
+  echo "Your project context appears valid."
+  exit 0
+elif [ $ERRORS -eq 0 ]; then
+  echo -e "${YELLOW}⚠ Warnings: $WARNINGS${NC}"
+  echo -e "${GREEN}✓ Errors: 0${NC}"
+  echo ""
+  echo "Your project context is valid but has some warnings."
+  echo "Review the warnings above and address if needed."
+  exit 0
+else
+  echo -e "${RED}✗ Errors: $ERRORS${NC}"
+  echo -e "${YELLOW}⚠ Warnings: $WARNINGS${NC}"
+  echo ""
+  echo "Please address the errors above."
+  exit 1
+fi

package/templates/architecture.md

@@ -0,0 +1,418 @@
+# Architecture Documentation
+
+> **Purpose:** Define HOW the system works — tech stack, structure, data flow, and technical decisions.  
+> **Last Updated:** [Date]
+
+---
+
+## Architecture Overview
+
+### System Summary
+[High-level description of the architecture. Is this a monolith, microservices, JAMstack, serverless, client-server, etc.?]
+
+### Architecture Diagram
+```
+[ASCII diagram or reference to visual architecture diagram]
+
+Example:
+┌─────────────┐      ┌──────────────┐      ┌──────────────┐
+│   Browser   │─────▶│   Frontend   │─────▶│   Backend    │
+│  (Client)   │◀─────│  (Next.js)   │◀─────│  (API)       │
+└─────────────┘      └──────────────┘      └──────────────┘
+                             │                       │
+                             ▼                       ▼
+                     ┌──────────────┐      ┌──────────────┐
+                     │   Vercel     │      │  PostgreSQL  │
+                     └──────────────┘      └──────────────┘
+```
+
+### Core Principles
+[What are the guiding architectural principles?]
+
+- [Principle 1: e.g., "API-first design"]
+- [Principle 2: e.g., "Stateless services"]
+
+---
+
+## Technology Stack
+
+### Runtime & Language
+- **Language:** [e.g., TypeScript, Python, Go]
+- **Runtime:** [e.g., Node.js 20, Python 3.11, Go 1.21]
+- **Package Manager:** [e.g., npm, pnpm, yarn, pip, cargo]
+
+### Frontend
+- **Framework:** [e.g., React 18, Vue 3, Svelte, Solid]
+- **Meta-framework:** [e.g., Next.js 14, Nuxt 3, SvelteKit, none]
+- **Styling:** [e.g., Tailwind CSS, CSS Modules, Styled Components]
+- **UI Library:** [e.g., shadcn/ui, Radix, Headless UI, custom]
+- **State Management:** [e.g., React Context, Zustand, Redux, Pinia, none]
+- **Form Handling:** [e.g., React Hook Form, Formik, native]
+- **Routing:** [e.g., Next.js App Router, React Router, Vue Router]
+
+### Backend
+- **Framework:** [e.g., Express, Fastify, FastAPI, Django, Rails, none]
+- **API Style:** [e.g., REST, GraphQL, tRPC, gRPC]
+- **API Documentation:** [e.g., OpenAPI/Swagger, GraphQL introspection]
+
+### Database
+- **Primary Database:** [e.g., PostgreSQL 16, MySQL, MongoDB, SQLite]
+- **ORM/Query Builder:** [e.g., Prisma, Drizzle, SQLAlchemy, none]
+- **Migrations:** [e.g., Prisma Migrate, Alembic, manual SQL]
+- **Caching:** [e.g., Redis, in-memory, none]
+
+### Authentication & Authorization
+- **Authentication Provider:** [e.g., NextAuth.js, Auth0, Clerk, Supabase Auth, custom]
+- **Session Management:** [e.g., JWT, cookies, sessions]
+- **Authorization Pattern:** [e.g., RBAC, ABAC, simple ownership]
+
+### External Services
+- **Email:** [e.g., Resend, SendGrid, AWS SES, none]
+- **File Storage:** [e.g., AWS S3, Cloudflare R2, local filesystem]
+- **Payment Processing:** [e.g., Stripe, none]
+- **Analytics:** [e.g., Vercel Analytics, Plausible, none]
+- **Error Tracking:** [e.g., Sentry, none]
+- **[Other services]:** [e.g., Algolia for search, Twilio for SMS]
+
+### Deployment & Infrastructure
+- **Hosting:** [e.g., Vercel, AWS, Railway, self-hosted]
+- **Database Hosting:** [e.g., Vercel Postgres, Neon, AWS RDS, self-hosted]
+- **CI/CD:** [e.g., GitHub Actions, none]
+- **Monitoring:** [e.g., Vercel Monitoring, Datadog, none]
+
+### Development Tools
+- **TypeScript:** [Yes/No]
+- **Linting:** [e.g., ESLint, Biome, none]
+- **Formatting:** [e.g., Prettier, Biome, none]
+- **Testing:** [e.g., Vitest, Jest, Playwright, Cypress, none]
+- **Git Hooks:** [e.g., Husky, lint-staged, none]
+
+---
+
+## Project Structure
+
+### Directory Organization
+
+```
+project-root/
+├── project-context/          # Project context documents (Telo3)
+├── src/                      # Source code
+│   ├── app/                  # [Framework-specific structure]
+│   ├── components/           # React/Vue/Svelte components
+│   ├── lib/                  # Shared utilities
+│   ├── styles/               # Global styles
+│   └── types/                # TypeScript type definitions
+├── public/                   # Static assets
+├── tests/                    # Test files
+├── docs/                     # Additional documentation
+├── package.json              # Dependencies
+├── tsconfig.json             # TypeScript configuration
+└── [Other config files]
+```
+
+### Key Directories
+
+| Directory | Purpose | Naming Convention |
+|-----------|---------|-------------------|
+| `/src/app` | [e.g., Next.js App Router pages] | [e.g., kebab-case] |
+| `/src/components` | [e.g., Reusable React components] | [e.g., PascalCase] |
+| `/src/lib` | [e.g., Utility functions, API clients] | [e.g., camelCase] |
+| `/src/types` | [e.g., TypeScript interfaces and types] | [e.g., PascalCase] |
+
+---
+
+## Data Architecture
+
+### Data Model
+[High-level description of core entities and relationships]
+
+```
+User ──< Posts ──< Comments
+ │
+ └──< Profile (1:1)
+```
+
+### Key Entities
+
+#### User
+- **Purpose:** [What this entity represents]
+- **Key Fields:** id, email, passwordHash, createdAt
+- **Relationships:** hasMany Posts, hasOne Profile
+- **Access Control:** [Who can read/write]
+
+#### [Entity Name]
+- **Purpose:** 
+- **Key Fields:** 
+- **Relationships:** 
+- **Access Control:** 
+
+### Data Flow
+
+#### Read Operations
+[How does data flow from database to user?]
+
+1. Client requests data via API
+2. API handler validates request
+3. Database query executed
+4. Data transformed/serialized
+5. Response returned to client
+
+#### Write Operations
+[How does data flow from user to database?]
+
+1. Client submits data via API
+2. API handler validates input
+3. Business logic executed
+4. Database transaction committed
+5. Response returned to client
+
+---
+
+## API Architecture
+
+### API Style
+[REST, GraphQL, tRPC, etc.]
+
+### Base URL
+- **Production:** `https://api.example.com`
+- **Development:** `http://localhost:3000/api`
+
+### API Structure
+
+#### REST Endpoints (if applicable)
+| Endpoint | Method | Purpose | Auth Required |
+|----------|--------|---------|---------------|
+| `/api/users` | GET | List users | Yes |
+| `/api/users/:id` | GET | Get user | Yes |
+| `/api/users` | POST | Create user | No |
+
+#### GraphQL Schema (if applicable)
+[Reference to schema file or high-level schema description]
+
+#### tRPC Routers (if applicable)
+[List of tRPC routers and their purposes]
+
+### API Conventions
+- **Authentication:** [Bearer token, cookies, etc.]
+- **Error Format:** [Standard error response structure]
+- **Pagination:** [Cursor-based, offset-based, etc.]
+- **Rate Limiting:** [Policy if implemented]
+
+---
+
+## Authentication & Authorization
+
+### Authentication Flow
+
+```
+1. User submits credentials
+2. Server validates credentials
+3. Server generates session/token
+4. Client stores session/token
+5. Client includes token in subsequent requests
+```
+
+### Session Management
+- **Storage:** [Where are sessions stored?]
+- **Lifetime:** [How long are sessions valid?]
+- **Refresh:** [How are sessions refreshed?]
+
+### Authorization Strategy
+[How are permissions enforced?]
+
+- **Public routes:** [List or criteria]
+- **Authenticated routes:** [List or criteria]
+- **Role-based access:** [Roles and permissions]
+
+### Security Boundaries
+[What are the security zones in the system?]
+
+- **Public:** [What is accessible without authentication?]
+- **Authenticated:** [What requires login?]
+- **Admin:** [What requires elevated privileges?]
+
+---
+
+## State Management
+
+### Client-Side State
+[How is state managed in the frontend?]
+
+- **Global State:** [Tool/pattern used]
+- **Server State:** [How is server data cached/synchronized?]
+- **Form State:** [How are forms managed?]
+- **URL State:** [Is state stored in URL params?]
+
+### Server-Side State
+[How is state managed on the backend?]
+
+- **Session State:** [Where/how stored]
+- **Application State:** [Any in-memory state?]
+- **Database State:** [How is consistency maintained?]
+
+---
+
+## External Service Integration
+
+### [Service Name]
+- **Purpose:** [Why is this service used?]
+- **Integration Method:** [API, SDK, webhook, etc.]
+- **Configuration:** [Environment variables required]
+- **Data Sharing:** [What data is sent to this service?]
+- **Fallback:** [What happens if service is unavailable?]
+
+---
+
+## Environment Configuration
+
+### Environment Variables
+
+| Variable | Purpose | Required | Default |
+|----------|---------|----------|---------|
+| `DATABASE_URL` | PostgreSQL connection string | Yes | - |
+| `NEXTAUTH_SECRET` | NextAuth.js session secret | Yes | - |
+| `NEXTAUTH_URL` | Application URL | Yes | - |
+| `[OTHER]` | [Description] | Yes/No | [Value] |
+
+### Configuration Files
+- `package.json` — Dependencies and scripts
+- `tsconfig.json` — TypeScript compiler configuration
+- `.env.local` — Local environment variables (not committed)
+- `.env.example` — Environment variable template
+- `[Other config files]`
+
+---
+
+## Build & Deployment
+
+### Build Process
+
+```bash
+# Development
+npm run dev
+
+# Production build
+npm run build
+
+# Start production server
+npm start
+```
+
+### Deployment Strategy
+[How is the application deployed?]
+
+- **Environments:** Development, Staging, Production
+- **Deployment Method:** [Git-based, CI/CD pipeline, manual]
+- **Rollback Strategy:** [How to revert if deployment fails]
+
+### Database Migrations
+[How are database schema changes managed?]
+
+```bash
+# Create migration
+npm run db:migrate:create
+
+# Run migrations
+npm run db:migrate
+
+# Rollback migration
+npm run db:migrate:rollback
+```
+
+---
+
+## Performance Considerations
+
+### Frontend Performance
+- **Code Splitting:** [Strategy used]
+- **Image Optimization:** [How images are optimized]
+- **Lazy Loading:** [What is lazy loaded]
+- **Caching Strategy:** [Browser caching, service workers]
+
+### Backend Performance
+- **Database Indexing:** [Key indexes]
+- **Query Optimization:** [Strategies used]
+- **Caching:** [What is cached and where]
+- **Rate Limiting:** [If implemented]
+
+---
+
+## Security Architecture
+
+### Security Layers
+1. **Network Security:** [HTTPS, CORS, rate limiting]
+2. **Authentication:** [How users are authenticated]
+3. **Authorization:** [How access is controlled]
+4. **Input Validation:** [Where/how validation occurs]
+5. **Output Encoding:** [How XSS is prevented]
+6. **Secrets Management:** [How secrets are stored]
+
+### Known Security Boundaries
+[What are the trust boundaries in the system?]
+
+- [Boundary 1: e.g., "Client code cannot be trusted"]
+- [Boundary 2: e.g., "API validates all inputs"]
+
+---
+
+## Architectural Decisions
+
+[Document important architectural decisions here. Include the decision, rationale, alternatives, and trade-offs.]
+
+### [Decision Date]: [Decision Title]
+**Decision:** [What was decided?]  
+**Context:** [What was the situation?]  
+**Rationale:** [Why was this decided?]  
+**Alternatives Considered:** [What else was considered?]  
+**Trade-offs:** [What are the downsides?]  
+**Status:** [Accepted / Superseded / Deprecated]
+
+---
+
+## Technical Debt
+
+[Document known technical debt that should be addressed]
+
+### High Priority
+- [ ] [Debt item 1] — Impact: [Description]
+
+### Medium Priority
+- [ ] [Debt item 2] — Impact: [Description]
+
+### Low Priority
+- [ ] [Debt item 3] — Impact: [Description]
+
+---
+
+## Known Limitations
+
+[Document known limitations of the current architecture]
+
+- **[Limitation 1]:** [Description and impact]
+- **[Limitation 2]:** [Description and impact]
+
+---
+
+## Future Architectural Considerations
+
+[Things to consider for future scaling or evolution]
+
+- [Consideration 1: e.g., "May need to split into microservices at 10x scale"]
+- [Consideration 2]
+
+---
+
+## References
+
+- [Link to API documentation]
+- [Link to database schema]
+- [Link to deployment documentation]
+- [Link to third-party service documentation]
+
+---
+
+## Document History
+
+| Date | Author | Changes |
+|------|--------|---------|
+| [Date] | [Name] | Initial version |