Initial extract: templates + methodology guide from Ideation

Public, version-controlled source of truth for TeamIDE's project templates, coding conventions, and the build-plan → PM scaffolding rules. Mounted read-only by TeamIDE's planner agent at runtime. Extracted from the personal Ideation repo as a precondition for workspace-projects-agent-spec.md §9.4. Personal Ideation stays private; this repo holds only the publishable methodology.
2026-05-16 10:01:25 -05:00
commit 83c52bc011
95 changed files with 13727 additions and 0 deletions
@@ -0,0 +1,50 @@
+# Documentation
+
+> Technical documentation for [Project Name]
+
+## Table of Contents
+
+### Getting Started
+- [Installation & Setup](./getting-started.md)
+
+### Features
+<!-- Add feature docs as they're built. Format: [Feature Name](./feature-name.md) -->
+
+### Architecture
+- [Tech Stack & Architecture](./architecture.md)
+
+### Development
+- [Development Guide](./development.md)
+- [Build & Deployment](./deployment.md)
+
+---
+
+## Documentation Guidelines
+
+### Adding New Documentation
+
+After completing a feature or phase, add documentation:
+
+1. Create a new `.md` file in this folder using the naming convention below
+2. Add a link to the Table of Contents above
+3. Use the appropriate template as a starting point:
+   - [Feature template](./TEMPLATE-feature.md) - For documenting features
+   - [Build plan template](./TEMPLATE-build-plan.md) - For creating structured build plans
+
+### Naming Convention
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Feature docs | `feature-[name].md` | `feature-authentication.md` |
+| Component docs | `component-[name].md` | `component-sidebar.md` |
+| Integration docs | `integration-[name].md` | `integration-nhost.md` |
+| Guide docs | `guide-[topic].md` | `guide-testing.md` |
+| Build plans | `[name]-build-plan.md` | `auth-build-plan.md` |
+
+### Documentation Structure
+
+Each feature doc should include:
+- **Overview** - What the feature does
+- **Usage** - How to use it (with code examples)
+- **Configuration** - Available options/settings
+- **Related** - Links to related features/components
@@ -0,0 +1,121 @@
+# [Project Name] - Build Plan
+
+## Executor Config
+```yaml
+default_branch_prefix: feat/phase
+test_before_commit: true
+require_passing_tests: true
+max_test_retries: 3
+```
+
+## Phase 1: [Phase Name]
+**repo**: [repository-name]
+**branch**: feat/phase-1-[slug]
+
+### 1.1 [Task Name]
+- **task**: [Description of what to do. Be specific and actionable.
+  Include context about existing code to use or patterns to follow.]
+- **test**: `[command to verify success]`
+- **commit**: "[Commit message]"
+
+### 1.2 [Task Name]
+- **task**: [Description]
+- **test**: `[test command]`
+- **commit**: "[Commit message]"
+
+### 1.3 Documentation
+- **task**: Update documentation for phase 1 changes.
+  Add any new files to docs/ folder.
+- **test**: none
+- **commit**: "Document phase 1"
+
+---
+
+## Phase 2: [Phase Name]
+**repo**: [repository-name]
+**branch**: feat/phase-2-[slug]
+**depends_on**: Phase 1
+
+### 2.1 [Task Name]
+- **task**: [Description]
+- **test**: `[test command]`
+- **commit**: "[Commit message]"
+
+### 2.2 Documentation
+- **task**: Update documentation for phase 2 changes.
+- **test**: none
+- **commit**: "Document phase 2"
+
+---
+
+## Current Status
+
+**Phase**: 1 - [Phase Name]
+**Task**: [Current task]
+
+---
+
+## Template Instructions
+
+> Remove this section when using this template
+
+### Plan Format
+
+Each plan consists of:
+
+1. **Executor Config** (optional) - YAML block with settings
+2. **Phases** - Major milestones (`## Phase N: Name`)
+3. **Tasks** - Individual work items (`### N.N Task Name`)
+
+### Phase Metadata
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `**repo**` | Yes | Repository to work in |
+| `**branch**` | No | Branch to create (default: `{prefix}-{N}`) |
+| `**depends_on**` | No | Phase that must complete first |
+
+### Task Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `- **task**` | Yes | What the agent should do |
+| `- **test**` | No | Command to verify (`none` to skip) |
+| `- **commit**` | No | Commit message (agent decides if omitted) |
+
+### Writing Good Tasks
+
+**Be specific:**
+```markdown
+# Bad
+- **task**: Add authentication
+
+# Good
+- **task**: Add JWT authentication with /api/login and /api/logout endpoints.
+  Use bcrypt for password hashing. Store tokens in httpOnly cookies.
+```
+
+**Include context:**
+```markdown
+- **task**: Create dashboard component at /dashboard showing:
+  - User's recent activity (last 10 items)
+  - Account settings link
+  Use the existing UserCard component for the header.
+```
+
+**Use testable tests:**
+```markdown
+# Bad
+- **test**: Check that it works
+
+# Good
+- **test**: `pnpm test && pnpm build`
+```
+
+### Tips
+
+1. **One thing per task** - Don't combine unrelated work
+2. **Tests are checkpoints** - Use them to verify progress
+3. **Commits are savepoints** - Small, focused commits
+4. **Phases are milestones** - Each should be independently useful
+5. **End phases with docs** - Document as you go
@@ -0,0 +1,60 @@
+# Feature Name
+
+> Brief one-line description of what this feature does
+
+## Overview
+
+Explain what this feature does and why it exists. Include:
+- The problem it solves
+- Key capabilities
+- When to use it
+
+## Usage
+
+### Basic Example
+
+```typescript
+// Code example showing basic usage
+```
+
+### Advanced Example
+
+```typescript
+// Code example showing advanced/common patterns
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | `string` | `""` | Description of option |
+| `option2` | `boolean` | `false` | Description of option |
+
+## Components
+
+List the main components involved in this feature:
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `ComponentName` | `src/components/ComponentName.vue` | Brief description |
+
+## Data Flow
+
+Describe how data flows through this feature (if applicable):
+
+```
+User Action → Component → Store → API → Database
+                ↑                    ↓
+              UI Update ← ← ← ← Response
+```
+
+## Related
+
+- [Related Feature](./feature-related.md)
+- [Related Component](./component-related.md)
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Initial implementation |
@@ -0,0 +1,61 @@
+# Architecture
+
+> Technical architecture and design decisions for [Project Name]
+
+## Tech Stack
+
+| Layer | Technology | Purpose |
+|-------|------------|---------|
+| Frontend | Vue 3 + Quasar | UI framework |
+| State | Pinia | State management |
+| Routing | Vue Router | Client-side routing |
+| Desktop | Tauri | Native desktop wrapper |
+| Backend | Nhost | Auth, database, storage |
+
+## Project Structure
+
+```
+app/
+├── src/
+│   ├── boot/           # Initialization scripts
+│   ├── components/     # Reusable Vue components
+│   ├── composables/    # Vue composables (shared logic)
+│   ├── layouts/        # Page layouts
+│   ├── pages/          # Route pages
+│   ├── router/         # Route definitions
+│   ├── stores/         # Pinia stores
+│   ├── services/       # API services
+│   └── types/          # TypeScript types
+├── src-tauri/          # Tauri/Rust code
+└── build.sh            # Build script
+```
+
+## Key Design Decisions
+
+### [Decision 1]
+
+**Context**: [Why this decision was needed]
+
+**Decision**: [What was decided]
+
+**Consequences**: [Trade-offs and implications]
+
+### [Decision 2]
+
+...
+
+## Data Model
+
+[Describe main entities and relationships]
+
+```
+Entity1 ──────< Entity2
+    │
+    └──────< Entity3
+```
+
+## External Integrations
+
+| Service | Purpose | Documentation |
+|---------|---------|---------------|
+| [Service] | [Purpose] | [Link] |
@@ -0,0 +1,78 @@
+# Build & Deployment
+
+> Build process and deployment instructions for [Project Name]
+
+## Build Commands
+
+```bash
+cd app
+
+# Development build
+./build.sh -dev -open
+
+# Production build (installs to ~/Applications)
+./build.sh -prod
+
+# Clean build artifacts
+./build.sh clean
+```
+
+## Build Output
+
+```
+app/build/
+├── dev/
+│   └── [AppName].app    # Development build
+├── prod/
+│   └── [AppName].app    # Production build
+├── logs/
+│   └── build_latest.log # Build output
+└── console/
+    └── console_latest.log # Runtime logs
+```
+
+## Production Build
+
+### macOS
+
+1. Build the production version:
+   ```bash
+   ./build.sh -prod
+   ```
+
+2. The app is automatically installed to `~/Applications/`
+
+### Distribution
+
+[Add distribution instructions - notarization, signing, etc.]
+
+## TeamIDE Deployment
+
+If using TeamIDE for hosting:
+
+```bash
+# Deploy changes
+teamide_deploy
+
+# Set environment variables
+teamide_set_env_vars
+
+# Check logs
+teamide_get_logs
+```
+
+**Workspace ID**: `[your-workspace-id]`
+
+## Environment Variables
+
+### Required for Production
+
+```env
+# List production environment variables
+```
+
+### Optional
+
+```env
+# List optional environment variables
+```
@@ -0,0 +1,72 @@
+# Development Guide
+
+> Development workflow and practices for [Project Name]
+
+## Development Workflow
+
+### Build and Run
+
+This project uses a **build-and-run** approach (not hot reload):
+
+```bash
+cd app
+./build.sh -dev -open    # Build and launch
+./build.sh logs          # View console output
+```
+
+### Why Build-and-Run?
+
+- **Dev = Prod** - What you test is what ships
+- **Full logging** - Console output captured to files
+- **No dev-only bugs** - Identical to production environment
+
+## Making Changes
+
+### Adding a New Feature
+
+1. Create components in `src/components/`
+2. Add pages in `src/pages/`
+3. Register routes in `src/router/`
+4. Add state management in `src/stores/`
+5. **Rebuild to test**: `./build.sh -dev -open`
+6. **Document the feature** in `docs/`
+
+### Adding a Tauri Command
+
+1. Add the command in `src-tauri/src/main.rs`
+2. Register it in the `invoke_handler`
+3. Call from frontend with `invoke('command_name', { args })`
+
+## Debugging
+
+### Console Logs
+
+```bash
+./build.sh logs              # Last 100 lines
+cat build/console/console_latest.log  # Full log
+```
+
+### Build Errors
+
+```bash
+cat build/logs/build_latest.log
+```
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Build fails with cache errors | `./build.sh clean && ./build.sh -dev -open` |
+| Changes not appearing | Rebuild - this is build-and-run, not hot reload |
+| Console logs missing | Check `console-logger.ts` is in boot files |
+
+## Code Style
+
+- **Components**: PascalCase (`UserProfile.vue`)
+- **Composables**: camelCase with `use` prefix (`useAuth.ts`)
+- **Stores**: camelCase (`userStore.ts`)
+- **Types**: PascalCase (`UserProfile.ts`)
+
+## Testing
+
+[Add testing instructions when implemented]
@@ -0,0 +1,52 @@
+# Getting Started
+
+> Installation and initial setup guide for [Project Name]
+
+## Prerequisites
+
+- Node.js 18+
+- npm
+- [Additional prerequisites]
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/dcherrera/[ProjectName].git
+cd [ProjectName]/app
+
+# Install dependencies
+npm install
+```
+
+## Configuration
+
+1. Copy the environment template:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Configure required environment variables:
+   ```env
+   # Required
+   VARIABLE_NAME=value
+   ```
+
+## Running the App
+
+### Development
+
+```bash
+./build.sh -dev -open
+```
+
+### Production
+
+```bash
+./build.sh -prod
+```
+
+## Next Steps
+
+- [Architecture Overview](./architecture.md) - Understand the codebase structure
+- [Development Guide](./development.md) - Learn the development workflow