# Ideas Repo - Project Planning & Scaffolding

This repo is for discussing, planning, and scaffolding project ideas. **No actual development happens here** - once a project is set up, it gets cloned elsewhere for building.

## Related Workspaces

| Workspace  | Path                                             | Purpose                                                                                                                            |
| ---------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Tech Radar | /Users/davidherrera/TeamIDE/dcherrera/tech-radar | Personal tech radar for evaluating tools and technologies. Reference files here when making tech stack decisions for new projects. |

## Purpose

When the user comes here with a project idea:

1. Discuss and refine the idea

2. **Create the project folder FIRST** (e.g., `mkdir ProjectName`)

3. Create planning docs inside the project folder:

   - **App projects:** `build_spec.md` and `build_plan.md`

   - **Research projects:** `goals.md` and optionally `spec.md`

4. Scaffold the rest of the project (CLAUDE.md, structure, etc.)

5. Init git, create GitHub repo, push

6. Delete from this workspace (project now lives in its own repo)

## CRITICAL: Project Folder Rule

**ALWAYS create a project folder FIRST before writing any spec or plan files.**

```
# CORRECT - create folder first, then files inside it
mkdir /path/to/workspace/ProjectName
# App projects: create build_spec.md and build_plan.md INSIDE ProjectName/
# Research projects: create goals.md and spec.md INSIDE ProjectName/

# WRONG - never create spec/plan files at the workspace root
# Don't do: /path/to/workspace/build_spec.md
# Don't do: /path/to/workspace/goals.md
```

Every project gets its own folder from the very beginning. Planning docs (`build_spec.md`/`build_plan.md` for apps, `goals.md`/`spec.md` for research) belong inside that project folder, not at the workspace root.

## Templates Location

```
Ideation/templates/
├── claude.md              # Standard project guidelines (copy + customize)
├── coding-best-practices.md # Coding conventions & style guide (copy as-is, read at Phase 1)
├── README.md              # Standard README structure (copy + customize)
├── LICENSE                # MIT Transparency License (copy as-is)
├── .gitignore             # Standard ignores (copy as-is)
├── build.sh               # Build script template (copy + customize app config)
├── scripts/
│   └── console-logger.ts  # Tauri console logging boot file
├── docs/                  # Documentation templates
│   ├── README.md          # Docs index with table of contents
│   ├── TEMPLATE-feature.md # Template for feature documentation
│   ├── getting-started.md # Installation & setup guide
│   ├── architecture.md    # Tech stack & architecture
│   ├── development.md     # Development workflow guide
│   └── deployment.md      # Build & deployment guide
│
│   # Starter Templates (complete working projects)
├── TauriStarter/          # Tauri + Quasar + Vite desktop app
├── ResearchStarter/       # R&D / research / experimental projects
├── [FutureStarter]/       # More starter templates to come...
│
│   # TeamIDE PM integration
└── teamide/
    ├── project.yml        # .teamide/project.yml template (copy + update name)
    └── README.md          # Explanation of PM file generation
```

### Starter Templates

Starter templates are complete, working projects ready to build immediately. Each includes its own CLAUDE.md with full project guidelines.

| Template        | Use Case                                            |
| --------------- | --------------------------------------------------- |
| TauriStarter    | Cross-platform desktop apps (macOS, Windows, Linux) |
| ResearchStarter | Research, experiments, and R&D investigations       |
| More coming...  | Web apps, native iOS/macOS, etc.                    |

## Workflow: Using a Starter Template

Use this workflow when a starter template exists for your project type (e.g., TauriStarter for desktop apps).

### Phase 1: Planning (in Ideation)

1. **Discuss the idea** - Refine requirements, features, scope

2. **Create the spec** - Write `build_spec.md` covering everything about the app

3. **Create the plan** - Write `build_plan.md` with phased task checklist

**For ResearchStarter projects:** Write `goals.md` (success criteria, anti-goals, kill gates) instead of `build_spec.md`. Optionally write `spec.md` if there's a concrete system to design. Milestone planning uses `docs/TEMPLATE-milestone.md` instead of `build_plan.md`.

### Phase 2: Scaffolding (in Ideation)

#### 1\. Copy the starter template

```
cp -r /Users/davidherrera/Obsidian/Ideation/templates/[StarterTemplate] /Users/davidherrera/Obsidian/Ideation/[ProjectName]
cd /Users/davidherrera/Obsidian/Ideation/[ProjectName]
cp ../templates/coding-best-practices.md ./coding-best-practices.md
```

#### 2\. Add spec and plan files

**App projects:** \`\`\`bash

# Move/copy the spec and plan we created during planning

mv ../build_spec.md ./build_spec.md mv ../build_plan.md ./build_plan.md \`\`\`

**Research projects (ResearchStarter):** The template already includes `goals.md` and `spec.md` — just fill them in with the content from Phase 1 planning. No need to move files.

#### 2.5. Generate TeamIDE PM files

Generate `.teamide/` project management files from `build_plan.md` so the project arrives at its dev repo with a ready-made task board. See the **TeamIDE PM Files** section below for the full conversion rules.

1. Copy `templates/teamide/project.yml` to `[ProjectName]/.teamide/project.yml` and update the `name:` field

2. Create `.teamide/plans/` and `.teamide/tasks/` directories

3. For each Phase heading in `build_plan.md`, create a plan file in `.teamide/plans/`

4. For each task line in `build_plan.md`, create a task file in `.teamide/tasks/` linked to its plan

**Research projects:** Use milestones from `docs/` instead of phases from `build_plan.md`. Each milestone becomes a plan, each task within it becomes a task file.

#### 3\. Customize the project

Each starter template has a **Customization Checklist** in its CLAUDE.md. Follow that checklist to update project name, identifiers, etc.

#### 4\. Customize CLAUDE.md

Edit the "Project-Specific Configuration" section at the bottom with:

- Project name

- Description

- Backend URLs (if applicable)

- Database schema (if applicable)

- TeamIDE workspace ID (if applicable)

#### 5\. Configure .gitignore for repo visibility

See "Project Dev Files" section below for private vs public repos.

#### 6\. Initialize git and create GitHub repo

```
git init
git add -A
git commit -m "Initial project setup"
gh repo create dcherrera/[ProjectName] --private --source=. --push --description "Brief description"
```

**Note**: All repos are created under `dcherrera` and are **private** by default.

### Phase 3: Development (outside Ideation)

#### 1\. Clone to development folder

```
cd ~/Software  # or wherever you do development
git clone https://github.com/dcherrera/[ProjectName].git
cd [ProjectName]
```

#### 2\. Install dependencies and start building

Follow the starter template's README or CLAUDE.md for build instructions.

**From this point on, all development happens in the cloned repo, not in Ideation.**

#### 3\. Clean up Ideation

After cloning, remove the scaffolded project from Ideation:

```
rm -rf /Users/davidherrera/Obsidian/Ideation/[ProjectName]
```

Ideation's job is done - the project now lives in its own repo.

## Workflow: Creating a Project Without a Starter Template

Use this when no starter template exists for your project type. You'll copy individual template files instead.

### Phase 1: Planning (in Ideation)

Same as above - discuss, create spec, create plan.

### Phase 2: Scaffolding (in Ideation)

#### 1\. Create the project folder

```
mkdir /Users/davidherrera/Obsidian/Ideation/[ProjectName]
cd /Users/davidherrera/Obsidian/Ideation/[ProjectName]
```

#### 2\. Copy base templates

```
cp ../templates/claude.md ./CLAUDE.md
cp ../templates/coding-best-practices.md ./coding-best-practices.md
cp ../templates/README.md ./README.md
cp ../templates/LICENSE ./LICENSE
cp ../templates/.gitignore ./.gitignore
cp -r ../templates/docs ./docs
mkdir -p screenshots app InternalDocs
touch app/.gitkeep
```

#### 3\. Add spec and plan, customize, create repo

Same as starter template workflow steps 2-6 (including step 2.5 — generate TeamIDE PM files).

### Phase 3: Development (outside Ideation)

Same as starter template workflow - clone to dev folder, build there, clean up Ideation.

## Project Structure (Required)

Every project follows this structure for future modularity:

```
ProjectName/              # git root
├── README.md             # Public-facing documentation (for GitHub + portfolio)
├── LICENSE               # MIT Transparency License
├── CLAUDE.md             # Project guidelines + config
├── coding-best-practices.md # Coding conventions (read before Phase 1)
├── build_spec.md         # Full project specification
├── build_plan.md         # Phased task checklist
├── .gitignore
├── docs/                 # Public-facing documentation (parsed to HTML for website)
│   ├── README.md         # Docs index with table of contents
│   ├── getting-started.md
│   ├── architecture.md
│   ├── development.md
│   ├── deployment.md
│   └── feature-*.md      # Feature documentation (added per phase)
├── InternalDocs/         # Internal development documentation (not public)
│   └── ...               # Design decisions, technical debt, internal API docs
├── screenshots/          # Project screenshots
│   ├── hero.png          # Main screenshot (used in portfolio card)
│   ├── demo.gif          # Animated demo (optional)
│   └── feature-*.png     # Feature-specific screenshots
└── app/                  # ALL project code lives here
    ├── src/
    ├── src-tauri/        # For Tauri apps
    ├── nhost/            # For Nhost backend
    ├── docker-compose.yml
    └── ...
```

**Why this structure?** The goal is modularity - eventually enabling drag-and-drop of components between projects. The `app/` subfolder keeps code separate from planning docs. `docs/` is public-facing (parsed to HTML for the website). `InternalDocs/` is for internal development context only.

### Research Project Variant

Research projects (using ResearchStarter) follow a different structure:

```
ProjectName/              # git root
├── README.md             # Project overview
├── LICENSE               # MIT Transparency License
├── CLAUDE.md             # Project guidelines + config
├── coding-best-practices.md # Coding conventions (read before Phase 1)
├── goals.md              # Success criteria (replaces build_spec.md)
├── spec.md               # Technical specification (optional)
├── conclusions.md         # Living findings document
├── open_questions.md      # Unresolved questions tracker
├── .gitignore
├── experiments/           # Experiment code (numbered runs)
├── results/               # Experiment results documentation
├── data/                  # Datasets (gitignored)
├── literature/            # Paper notes & prior art
├── src/                   # Implementation code (when research produces software)
├── tests/                 # Test suite
├── docs/                  # Public-facing documentation (parsed to HTML for website)
│   ├── README.md
│   ├── getting-started.md
│   └── architecture.md
├── InternalDocs/          # Internal development documentation (not public)
│   └── ...
└── screenshots/           # Visuals for README / portfolio
```

**Key differences from app projects:** `experiments/` + `src/` replace `app/`, `goals.md` replaces `build_spec.md`, milestone-based planning replaces `build_plan.md`, and `results/`/`literature/`/`conclusions.md`/`open_questions.md` support the research workflow.

## Standard Tech Stack (Default)

**Tauri Desktop Apps (use TauriStarter):**

- **Frontend**: Quasar Framework (Vue 3) + Vite

- **Desktop**: Tauri (Rust) - Cross-platform builds (macOS, Windows, Linux)

- **State**: Pinia

- **Backend** (optional): Nhost (self-hosted or cloud)

**Web Apps:**

- **Frontend**: Quasar Framework (Vue 3) - SPA mode

- **Backend**: Nhost (self-hosted via Docker)

  - PostgreSQL, Hasura GraphQL, Auth, Storage, Functions

- **Containerization**: Docker / Docker Compose

**Native Apps (when needed):**

- **macOS/iOS**: Swift, SwiftUI, AppKit/UIKit

- **Cross-platform**: Evaluate per project

## Starter Template: TauriStarter

For cross-platform desktop apps (macOS, Windows, Linux).

The TauriStarter template includes:

- **Working Tauri + Quasar + Vite setup** - Ready to build immediately

- **Console logging** - Frontend `console.log()` captured to log files

- **Build script** - `./build.sh -dev -open` for consistent builds

- **Placeholder icons** - All platform icons included (replace with your own)

- **Full CLAUDE.md** - Complete project guidelines including:

  - Build script documentation

  - Testing changes reminders

  - Database/Nhost rules (if using backend)

  - Commit rules

  - Customization checklist

### Build Script (build.sh)

All Tauri projects use the standardized `build.sh` script:

```
cd app
./build.sh -dev -open    # Build dev and open app
./build.sh -prod         # Build prod and install to ~/Applications
./build.sh logs          # View latest console log (last 100 lines)
./build.sh clean         # Clean build artifacts (preserves logs)
./build.sh clean-logs    # Remove all logs
```

**Key features:**

- **Build-and-run** - No hot reload, but dev = prod (what you test = what ships)

- **Separate dev/prod** - Different bundle IDs, can run simultaneously

- **Automatic logging** - All build and console output saved to `build/logs/` and `build/console/`

- **Non-blocking** - Script exits after launching app

### Console Logging

Frontend `console.log()` is automatically captured:

```
console.log() → console-logger.ts → invoke('log_to_stdout') → Rust println!() → stdout → build.sh logs
```

**When debugging issues:**

1. Run `./build.sh logs` to see last 100 lines of console output

2. Full logs: `cat build/console/console_latest.log`

3. Build errors: `cat build/logs/build_latest.log`

## Starter Template: ResearchStarter

For research, experiments, and R&D investigations.

The ResearchStarter template includes:

- **Full R&D methodology** - Hypothesis-first workflow, kill gates, experiment tracking

- **Structured experiment tracking** - Numbered runs, results docs, literature reviews

- **Research planning files** - `goals.md`, `spec.md`, `conclusions.md`, `open_questions.md`

- **Templates for everything** - Experiment plans, results docs, paper reviews, milestones

- **Full CLAUDE.md** - Complete research methodology including:

  - Research pipeline and document layers

  - 11 key principles (hypothesis-first, kill gates, constraint-driven design, etc.)

  - Experiment naming conventions and results documentation rules

  - Milestone format with dependency graphs

  - Customization checklist

### Key Differences from App Templates

| Aspect        | App Templates (TauriStarter)  | ResearchStarter                                    |
| ------------- | ----------------------------- | -------------------------------------------------- |
| Planning      | build_spec.md + build_plan.md | goals.md + milestone plans                         |
| Code location | app/                          | experiments/ + src/                                |
| Feature docs  | docs/feature-*.md             | results/experiment_N_results.md                    |
| Doc templates | TEMPLATE-feature.md           | TEMPLATE-experiment-plan.md, TEMPLATE-milestone.md |
| Extra files   | —                             | conclusions.md, open_questions.md, literature/     |
| Methodology   | Build-and-ship                | Hypothesis → experiment → analyze → conclude       |

## build_spec.md Format

> **Research projects:** Use `goals.md` instead. It covers success criteria, anti-goals, kill gates, and fallback plans. See the ResearchStarter template.

The spec should cover everything about the app:

- Problem it solves

- Target users

- All features and functionality

- User flows

- Data model / entities

- Integrations

- UI/UX requirements

- Any constraints or requirements

## build_plan.md Format

> **Research projects:** Use milestone-based planning instead. See `docs/TEMPLATE-milestone.md` in the ResearchStarter template for the format, including dependency graphs and kill gates.

Phased task list with checkboxes. **Each phase ends with documentation and a plan update.**

**Every phase MUST end with these three steps:**

1. **Document** — Update both `docs/` (public) and `InternalDocs/` (internal) as appropriate

2. **Update build plan** — Check off completed tasks in `build_plan.md`, note any scope changes, deferred items, or new tasks discovered during the phase

3. **Update PM tasks** — Mark completed `.teamide/tasks/` files as `status: done`. When all tasks in a plan are done, update the plan's status. If new tasks were discovered, create new task files and add them to the plan.

```
# Build Plan: [Project Name]

## Phase 1: Foundation
- ☐ **Read `coding-best-practices.md`** before writing any code
- ☐ Initialize project from TauriStarter
- ☐ Customize app name and icons
- ☐ Set up backend (if needed)
- ☐ ...
- ☐ **Document**: Update `docs/getting-started.md` and `docs/architecture.md`. Add initial design decisions to `InternalDocs/`
- ☐ **Update plan & tasks**: Check off completed tasks in this file. Update `.teamide/tasks/` statuses to `done`. Note any changes or deferred items.

## Phase 2: Core Features
- ☐ Task 1
- ☐ Task 2
- ☐ ...
- ☐ **Document**: Create `docs/feature-[name].md`, update docs index. Add internal API docs or design decisions to `InternalDocs/`
- ☐ **Update plan & tasks**: Check off completed tasks in this file. Update `.teamide/tasks/` statuses to `done`. Note any changes or deferred items.

## Phase 3: [Feature Name]
- ☐ Task 1
- ☐ Task 2
- ☐ ...
- ☐ **Document**: Create `docs/feature-[name].md`, update docs index. Add internal API docs or design decisions to `InternalDocs/`
- ☐ **Update plan & tasks**: Check off completed tasks in this file. Update `.teamide/tasks/` statuses to `done`. Note any changes or deferred items.

## Phase N: Polish & Release
- ☐ Final testing
- ☐ ...
- ☐ **Document**: Review and finalize all `docs/`. Review `InternalDocs/` for accuracy, update `docs/deployment.md`
- ☐ **Update plan & tasks**: Final review — all tasks checked off and marked `done`, deferred items documented, plan status updated to `complete`
```

## TeamIDE PM Files

When scaffolding a project, generate `.teamide/` files from `build_plan.md` so the project has a ready-made task board when cloned.

### Directory Structure

Every phase lives inside a **plan group folder** under `plans/`. The group folder represents the larger plan (e.g. "initial build", "v2 refactor") that owns those phases. TeamIDE's Plans tab renders one card per group; clicking the card drills into the phase list.

```
ProjectName/.teamide/
├── project.yml              # Project config (from template)
├── plans/
│   └── <plan-group-slug>/   # One folder per larger plan
│       ├── phase-1-slug.md  # One per build_plan.md phase
│       └── phase-2-slug.md
└── tasks/
    ├── task-slug-a.md        # One per checkbox line (flat — tasks are not nested)
    └── task-slug-b.md
```

For a single-plan project, use a single group folder named after the project's primary plan (default: `build`):

```
.teamide/plans/build/
├── phase-1-foundation.md
├── phase-2-core-features.md
└── phase-3-polish.md
```

For a multi-plan project, use a `# Plan:` H1 divider in `build_plan.md` (see Multi-Plan Projects below) and create one folder per `# Plan:` heading.

### Conversion Rules

**Mapping:**

| build_plan.md                      | .teamide/                                       |
| ---------------------------------- | ----------------------------------------------- |
| `# Plan: <name>` H1 heading        | plans/<plan-slug>/ (folder)                     |
| `## Phase N: <name>` heading       | plans/<plan-slug>/phase-N-slug.md               |
| `- [ ]` task line                  | tasks/task-slug.md                              |
| First phase in any group           | Plan status: active                             |
| Subsequent phases                  | Plan status: draft                              |
| Phase number (N)                   | Plan order: N                                   |
| Task position within phase         | Task order: 1, 2, 3...                          |
| All tasks                          | Task status: backlog                            |
| Sub-bullets / context under a task | Task markdown body                              |

**Slugification:** Lowercase, spaces to hyphens, strip special characters, `.md` extension. Example: `## Phase 3: iCloud Sync` → `phase-3-icloud-sync.md`, `- [ ] Create CameraManager class` → `create-cameramanager-class.md`. Plan group slugs follow the same rule: `# Plan: Initial Build` → `initial-build/`.

**Default group slug:** if `build_plan.md` has no `# Plan:` headings, generate everything under `plans/build/`.

### Multi-Plan Projects

When a project has more than one larger plan (e.g. the initial build *and* a follow-on refactor), use `# Plan:` H1 dividers in `build_plan.md`. Each `# Plan:` opens a new group folder; every `## Phase` below it lands inside that folder.

```
# Plan: Initial Build
## Phase 1: Foundation
- [ ] Set up Tauri project
## Phase 2: Core CRUD
- [ ] Build user model

# Plan: v2 Refactor
## Phase 1: Schema Migration
- [ ] Add new user_roles table
```

Generates:

```
.teamide/plans/
├── initial-build/
│   ├── phase-1-foundation.md
│   └── phase-2-core-crud.md
└── v2-refactor/
    └── phase-1-schema-migration.md
```

Phase numbering restarts within each group. Task back-references (`plan:` frontmatter) still use the phase file's basename — keep phase filenames globally unique across groups for now (e.g. `phase-1-foundation.md` vs `phase-1-schema-migration.md`).

### Plan File Format

`.teamide/plans/phase-N-slug.md`:

```
---
title: "Phase N: Phase Name"
status: active
order: 1
tasks:
  - task-slug-a.md
  - task-slug-b.md
---
Phase description (optional — copy any paragraph text below the phase heading in build_plan.md).
```

- Phase 1 gets `status: active`, all others get `status: draft`

- `order:` matches the phase number (1, 2, 3...) for correct display ordering

- `tasks:` lists all task filenames belonging to this phase

### Task File Format

`.teamide/tasks/task-slug.md`:

```
---
title: Task description from the checkbox line
status: backlog
plan: phase-N-slug.md
order: 1
---
Context and details about this task go here.

- Implementation note or sub-step
- Another detail or consideration
- Any relevant technical context
```

- `title:` is the text after `- [ ]` in build_plan.md

- `plan:` back-references the parent plan filename (bidirectional link)

- `order:` sequential number (1-based) controlling display order within the plan

- All tasks start as `status: backlog`

- **The body MUST contain context** — any sub-bullets, notes, or detail text beneath the task line in `build_plan.md` belongs in the task body. If the plan has context like implementation notes, API details, or technical considerations under a task, that content goes in the markdown body of the task file. Empty task bodies are not acceptable.

### System-managed timestamps

TeamIDE's backend auto-manages four timestamp fields on every PM file. **Scaffolding flows MUST NOT set these** — the backend stamps them on every write. Documented here so you understand the data shape and don't accidentally include them in generated files.

| Field | Format | When set |
|---|---|---|
| `created_at` | ISO 8601 UTC (`2026-05-15T14:30:00.000Z`) | Once, at file creation. Never updated. |
| `updated_at` | ISO 8601 UTC | Every write (PUT or PATCH). |
| `status_changed_at` | ISO 8601 UTC | Any write that changes `status`. |
| `finished_at` | ISO 8601 UTC, or absent | Set when `status` transitions to `done`. Cleared when transitioning back off `done`. Reflects current state, not history. |

Scaffolded task files should leave all four absent. The first PATCH or PUT through TeamIDE adds them. For brand-new task files written directly to disk (e.g. an agent creating tasks during a run), TeamIDE will fill `created_at`, `updated_at`, and `status_changed_at` on next read/edit.

### User-editable date fields

Tasks may carry two user-editable date fields, both stored as ISO 8601 UTC:

| Field | Meaning |
|---|---|
| `start_date` | When work on the task is scheduled to begin. Optional. Used by the timeline view to position the start of a task's range. |
| `due_date` | When the task is due. Optional. Used by table / kanban / timeline / calendar for scheduling and urgency colors. Replaces the legacy `due:` field. Both `start_date` and `due_date` are optional — tasks without dates show in "Unscheduled" lanes on the timeline. |

Format examples:

```yaml
start_date: 2026-05-15T00:00:00.000Z   # date only, no specific time
due_date: 2026-05-20T14:30:00.000Z     # specific time
```

When the time component is midnight UTC, TeamIDE renders the chip as date-only ("05/15/2026"). When the time is set, the chip shows date and time ("05/15/2026 2:30 PM"). Storage is always full ISO; display is US format.

**Legacy compatibility**: files using the old `due:` field continue to render correctly. On next save through TeamIDE the field is renamed to `due_date`. No migration script needed.

### Soft-deleted files (`deleted_at`)

TeamIDE's PM views (kanban, table, timeline, calendar, activity feed) recognize an optional `deleted_at` frontmatter field on any plan/task/note file. When set to an ISO timestamp, the file is treated as "trashed" — it stays on disk and in git history but is filtered out of every PM view.

- **Scaffolding** — do NOT include `deleted_at` when generating plan/task files from a build plan. New files start visible.

- **Soft-delete trigger** — only the user can soft-delete (via "Move to Trash" in the PM file editor, the upcoming bulk-delete in the table view, or any other PM surface). Agents and scaffolding flows should never write `deleted_at` themselves.

- **Recovery** — open the file in the Code module's file tree and either remove the entire `deleted_at: ...` line (recommended — cleanest) or blank the value (`deleted_at:` with nothing after it). The filter treats any falsy value as "not deleted" so both work. The file reappears in every view on next reload.

- **Hard delete** — the only path that physically removes a file is the Code module's file tree. PM surfaces always soft-delete.

Example trashed task:

```
---
title: Add caching to /pm/all-tasks
status: in-progress
plan: phase-3-caching.md
order: 2
deleted_at: 2026-05-13T22:14:08Z
---
Task body still here.
```

### project.yml Setup

1. Copy `templates/teamide/project.yml` to `[ProjectName]/.teamide/project.yml`

2. Replace `PROJECT_NAME` with the actual project name

### Example

Given this `build_plan.md`:

```
## Phase 1: Project Setup
- ☐ Create Xcode project
  - Use SwiftUI App lifecycle
  - Set deployment target to iOS 17+
- ☐ Configure bundle ID
  - Format: com.dcherrera.appname
- ☐ Add dependencies
  - AVFoundation, Photos framework

## Phase 2: Camera Engine
- ☐ Create CameraManager class
  - Singleton managing AVCaptureSession
  - Handle authorization flow
- ☐ Implement single-camera recording
```

Generate (no `# Plan:` headings → default `build` group):

```
.teamide/
├── project.yml
├── plans/
│   └── build/
│       ├── phase-1-project-setup.md        # status: active, order: 1, tasks: [...]
│       └── phase-2-camera-engine.md        # status: draft, order: 2, tasks: [...]
└── tasks/
    ├── create-xcode-project.md         # status: backlog, order: 1, plan: phase-1-...
    ├── configure-bundle-id.md          # status: backlog, order: 2, plan: phase-1-...
    ├── add-dependencies.md             # status: backlog, order: 3, plan: phase-1-...
    ├── create-cameramanager-class.md   # status: backlog, order: 1, plan: phase-2-...
    └── implement-single-camera-recording.md  # status: backlog, order: 2, plan: phase-2-...
```

**Task file with body context** — e.g. `create-xcode-project.md`:

```
---
title: Create Xcode project
status: backlog
plan: phase-1-project-setup.md
order: 1
---
- Use SwiftUI App lifecycle
- Set deployment target to iOS 17+
```

### Phase Closing Tasks

At the end of each phase:

1. **Create public feature docs** — For each significant feature, create `docs/feature-[name].md` using the template

2. **Update the docs index** — Add links to new docs in `docs/README.md` table of contents

3. **Update related public docs** — Keep `architecture.md`, `development.md` current as the project evolves

4. **Update internal docs** — Add design decisions, internal API docs, technical debt notes to `InternalDocs/`

5. **Update build plan** — Check off completed tasks in `build_plan.md`, note scope changes, deferred items, or new tasks discovered

6. **Update PM tasks** — Mark completed `.teamide/tasks/` files as `status: done`. When all tasks in a plan are done, update the plan's status to `complete`. Create new task files for any tasks discovered during the phase.

## Documentation Workflow

**Every phase ends with documentation.** This ensures features are documented while fresh and the docs stay current.

### docs/ vs InternalDocs/

| Directory     | Audience   | Purpose                                                                                         | Parsed for website? |
| ------------- | ---------- | ----------------------------------------------------------------------------------------------- | ------------------- |
| docs/         | Public     | User-facing app documentation — getting started, features, architecture                         | Yes                 |
| InternalDocs/ | Developers | Internal dev context — design decisions, technical debt, internal API contracts, Claude context | No                  |

**`docs/`** contains ONLY what the public needs. It gets parsed into HTML and served on the app website. No internal implementation details, no dev-only context.

**`InternalDocs/`** contains everything internal — design rationale, known technical debt, internal API documentation, integration notes, debugging guides, anything that helps the development team but doesn't belong in public docs.

Both directories are committed to git.

### Documentation Structure

```
docs/                          # Public-facing (parsed to HTML for website)
├── README.md                  # Index with table of contents (MAIN ENTRY POINT)
├── TEMPLATE-feature.md        # Template for new feature docs (don't link this)
├── getting-started.md         # Installation & setup
├── architecture.md            # Tech stack & design decisions
├── development.md             # Development workflow
├── deployment.md              # Build & deployment
└── feature-*.md               # Feature-specific documentation

InternalDocs/                  # Internal development only (not public)
└── ...                        # Design decisions, tech debt, internal API docs
```

### After Each Phase

1. **Identify what to document** - New features, components, integrations

2. **Create feature docs** - Copy `TEMPLATE-feature.md` to `feature-[name].md`

3. **Update the index** - Add links to `docs/README.md` table of contents

4. **Update core docs** - Keep `architecture.md`, `development.md` current

5. **Update internal docs** - Add design decisions, technical debt notes, or internal API docs to `InternalDocs/` as needed

### 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          |

### Documentation vs README vs InternalDocs

| docs/                         | README.md                      | InternalDocs/                 |
| ----------------------------- | ------------------------------ | ----------------------------- |
| Public app documentation      | High-level overview            | Internal dev context          |
| Parsed to HTML for website    | GitHub / portfolio face        | Never published               |
| User-facing features & guides | Features list, getting started | Design decisions, tech debt   |
| How to use the app            | What the app is                | How/why it was built this way |

- **`docs/`** = public documentation, parsed to HTML and served on the app website

- **`README.md`** = the public face of the project for GitHub and portfolio

- **`InternalDocs/`** = internal development context, committed but never published

## README Guidelines

Every project needs a README.md that serves two purposes:

1. **GitHub documentation** - For visitors and contributors

2. **Portfolio content** - Can be pulled into StaticPortfolioGenerator

### README Structure

Use the template from `templates/README.md`. Key sections:

| Section         | Purpose                                           |
| --------------- | ------------------------------------------------- |
| Title + Tagline | Project name and one-line description             |
| Hero Screenshot | Main visual (hero.png)                            |
| Overview        | 2-3 paragraphs explaining what/why                |
| Features        | Bulleted list of key features                     |
| Screenshots     | Additional visuals with captions                  |
| Tech Stack      | Technologies used                                 |
| Getting Started | Prerequisites, installation, usage                |
| Development     | Dev setup instructions                            |
| Status          | Active / Maintained / Paused / Archived / Concept |
| License         | Link to LICENSE file                              |

### When to Update README

- **Project creation** - Initialize from template

- **New features** - Add to Features section

- **UI changes** - Update screenshots

- **Status changes** - Update Status section

- **Before making public** - Full review and polish

## Screenshots

Screenshots live in the `screenshots/` folder at the project root.

### Naming Convention

| Filename           | Purpose                                                     |
| ------------------ | ----------------------------------------------------------- |
| hero.png           | Main screenshot - used in portfolio cards and README header |
| demo.gif           | Animated demo showing the app in action (optional)          |
| feature-[name].png | Feature-specific screenshots (e.g., feature-dashboard.png)  |

### Image URLs in README

Use raw GitHub URLs so images work everywhere:

```
![Hero](https://raw.githubusercontent.com/dcherrera/ProjectName/main/screenshots/hero.png)
```

### Screenshot Tips

- **Dimensions**: Aim for 16:9 or 16:10 aspect ratio

- **Resolution**: 1920x1080 or 1280x720 recommended

- **Format**: PNG for UI screenshots, GIF for animations

- **Content**: Show real/realistic data, not lorem ipsum

- **Dark mode**: Match the app's default theme

## Commit Rules (for all projects)

- Never mention Claude, AI, or generated code in commits

- Write as the developer, first person

- Concise and descriptive

## Project Dev Files

**App projects:** `CLAUDE.md`, `coding-best-practices.md`, `build_spec.md`, `build_plan.md` **Research projects:** `CLAUDE.md`, `coding-best-practices.md`, `goals.md`, `spec.md`, `conclusions.md`, `open_questions.md`

These files contain project planning and AI assistant context. How to handle them depends on repo visibility:

### Private Repos (Default)

**Commit these files to git.** Since the repo is private, there's no risk of exposing internal documentation.

```
# .gitignore - DO NOT ignore these files
# CLAUDE.md - tracked
# build_spec.md - tracked
# build_plan.md - tracked
```

### Open Source / Public Repos

**Add these files to .gitignore.** They contain internal development context that shouldn't be public.

```
# .gitignore - ADD these lines (app projects)
CLAUDE.md
coding-best-practices.md
build_spec.md
build_plan.md

# .gitignore - ADD these lines (research projects)
CLAUDE.md
coding-best-practices.md
goals.md
spec.md
conclusions.md
open_questions.md
```

**Before making a private repo public:**

1. Add the files to `.gitignore`

2. Remove them from git tracking: `git rm --cached CLAUDE.md coding-best-practices.md build_spec.md build_plan.md` (or the research equivalents)

3. Keep the local copies (they're now untracked)

4. Commit the `.gitignore` change

5. Then change repo visibility

### Summary

**App projects:**

| Repo Type  | CLAUDE.md  | coding-best-practices.md | build_spec.md | build_plan.md |
| ---------- | ---------- | ------------------------ | ------------- | ------------- |
| Private    | Commit     | Commit                   | Commit        | Commit        |
| Public/OSS | .gitignore | .gitignore               | .gitignore    | .gitignore    |

**Research projects:**

| Repo Type  | CLAUDE.md  | coding-best-practices.md | goals.md   | spec.md    | conclusions.md | open_questions.md |
| ---------- | ---------- | ------------------------ | ---------- | ---------- | -------------- | ----------------- |
| Private    | Commit     | Commit                   | Commit     | Commit     | Commit         | Commit            |
| Public/OSS | .gitignore | .gitignore               | .gitignore | .gitignore | .gitignore     | .gitignore        |

## Dockerized Frontend for Production

When deploying a fully dockerized web project (not Tauri), the frontend needs its own service in docker-compose:

### 1\. Create `app/Dockerfile.frontend`

```
# Build stage
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

### 2\. Create `app/nginx.conf`

```
server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

### 3\. Add frontend service to `docker-compose.yml`

```
frontend:
  build:
    context: .
    dockerfile: Dockerfile.frontend
  depends_on:
    graphql:
      condition: service_healthy
    auth:
      condition: service_healthy
  labels:
    traefik.enable: "true"
    traefik.http.routers.frontend.rule: Host(`${FRONTEND_URL:-app.localhost}`)
    traefik.http.routers.frontend.entrypoints: web
    traefik.http.services.frontend.loadbalancer.server.port: "80"
  restart: always
```

## TeamIDE Hosting

Projects are deployed via TeamIDE to teamide.dev.

- Use `teamide_deploy` to deploy changes

- Use `teamide_set_env_vars` to configure environment variables

- Use `teamide_get_logs` to check build status

To get workspace IDs, run: `bash teamide workspace list `

Each project should document its workspace ID in the project-specific CLAUDE.md.