David
/
TeamIDE-methodology
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
TeamIDE-methodology/claude.md

1049 lines
40 KiB
Markdown
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.
## 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.
Reference in New Issue View Git Blame Copy Permalink