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.
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user