40 KiB

Raw Blame History

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.

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:

Discuss and refine the idea
Create the project folder FIRST (e.g., mkdir ProjectName)
Create planning docs inside the project folder:
- App projects: build_spec.md and build_plan.md
- Research projects: goals.md and optionally spec.md
Scaffold the rest of the project (CLAUDE.md, structure, etc.)
Init git, create GitHub repo, push
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)

Discuss the idea - Refine requirements, features, scope
Create the spec - Write build_spec.md covering everything about the app
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.

Copy templates/teamide/project.yml to [ProjectName]/.teamide/project.yml and update the name: field
Create .teamide/plans/ and .teamide/tasks/ directories
For each Phase heading in build_plan.md, create a plan file in .teamide/plans/
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:

Run ./build.sh logs to see last 100 lines of console output
Full logs: cat build/console/console_latest.log
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:

Document — Update both docs/ (public) and InternalDocs/ (internal) as appropriate
Update build plan — Check off completed tasks in build_plan.md, note any scope changes, deferred items, or new tasks discovered during the phase
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// (folder)
`## Phase N: <name>` heading	plans//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:

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

Copy templates/teamide/project.yml to [ProjectName]/.teamide/project.yml
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:

Create public feature docs — For each significant feature, create docs/feature-[name].md using the template
Update the docs index — Add links to new docs in docs/README.md table of contents
Update related public docs — Keep architecture.md, development.md current as the project evolves
Update internal docs — Add design decisions, internal API docs, technical debt notes to InternalDocs/
Update build plan — Check off completed tasks in build_plan.md, note scope changes, deferred items, or new tasks discovered
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

Identify what to document - New features, components, integrations
Create feature docs - Copy TEMPLATE-feature.md to feature-[name].md
Update the index - Add links to docs/README.md table of contents
Update core docs - Keep architecture.md, development.md current
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:

GitHub documentation - For visitors and contributors
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:

Add the files to .gitignore
Remove them from git tracking: git rm --cached CLAUDE.md coding-best-practices.md build_spec.md build_plan.md (or the research equivalents)
Keep the local copies (they're now untracked)
Commit the .gitignore change
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.

40 KiB Raw Blame History

Ideas Repo - Project Planning & Scaffolding

Related Workspaces

Purpose

CRITICAL: Project Folder Rule

Templates Location

Starter Templates

Workflow: Using a Starter Template

Phase 1: Planning (in Ideation)

Phase 2: Scaffolding (in Ideation)

1. Copy the starter template

2. Add spec and plan files

Move/copy the spec and plan we created during planning

2.5. Generate TeamIDE PM files

3. Customize the project

4. Customize CLAUDE.md

5. Configure .gitignore for repo visibility

6. Initialize git and create GitHub repo

Phase 3: Development (outside Ideation)

1. Clone to development folder

2. Install dependencies and start building

3. Clean up Ideation

Workflow: Creating a Project Without a Starter Template

Phase 1: Planning (in Ideation)

Phase 2: Scaffolding (in Ideation)

1. Create the project folder

2. Copy base templates

3. Add spec and plan, customize, create repo

Phase 3: Development (outside Ideation)

Project Structure (Required)

Research Project Variant

Standard Tech Stack (Default)

Starter Template: TauriStarter

Build Script (build.sh)

Console Logging

Starter Template: ResearchStarter

Key Differences from App Templates

build_spec.md Format

build_plan.md Format

TeamIDE PM Files

Directory Structure

Conversion Rules

Multi-Plan Projects

Plan File Format

Task File Format

System-managed timestamps

User-editable date fields

Soft-deleted files (deleted_at)

project.yml Setup

Example

Phase Closing Tasks

Documentation Workflow

docs/ vs InternalDocs/

Documentation Structure

After Each Phase

Naming Convention

Documentation vs README vs InternalDocs

README Guidelines

README Structure

When to Update README

Screenshots

Naming Convention

Image URLs in README

Screenshot Tips

Commit Rules (for all projects)

Project Dev Files

Private Repos (Default)

Open Source / Public Repos

Summary

Dockerized Frontend for Production

1. Create app/Dockerfile.frontend

2. Create app/nginx.conf

3. Add frontend service to docker-compose.yml

TeamIDE Hosting

40 KiB

Raw Blame History

Soft-deleted files (`deleted_at`)

1. Create `app/Dockerfile.frontend`

2. Create `app/nginx.conf`

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