Workspace Organization System

Architecture

Global Layer

Shared Templates

~/.claude/

doc-templates/ 14

feature-spec.mdFeature specification
bug-investigation.mdBug triage + root cause
implementation-plan.mdStep-by-step build plan
api-endpoint-design.mdREST/API route design
database-migration.mdSchema change + rollback
adr.mdArchitecture Decision Record
+ 8 more...UI, deploy, PR, retro, etc.

prep-templates/ 7

architecture-research.mdSystem design exploration
api-evaluation.mdService/API evaluation
tech-stack-evaluation.mdTechnology comparison
cost-analysis.mdInfrastructure cost modeling
+ 3 more...Competitor, security

generators/ 8

new-task.shCreate task file
new-feature.shFeature spec + branch
new-bug.shBug investigation
new-prep.shResearch document
new-adr.shArchitecture decision
done-task.shArchive to .done/

Per-Project Layer

Project Workspace

<project>/workspace/

tasks/ active work

2026-02-08-add-email.mdActive task
.done/Completed archive

prep/ research

2026-02-08-tech-stack-*.mdInvestigation docs

decisions/ ADRs

0001-use-supabase-rls.mdAuto-numbered

Other directories

scratch/Experiments (gitignored)
ideas/Future concepts

Initialized Projects

Homer~/Development/Homer/workspace/
Pause~/Development/id8/products/pause/workspace/
DeepStack~/Development/id8/products/deepstack/workspace/

Workflows

New Feature

feature

01

Tell Claude what you want

Say /task Add email notifications for Homer

02

Claude interviews you

Asks priority, type, acceptance criteria. You answer by voice or text. No brackets to fill in.

03

Generator creates the file

new-task.sh creates workspace/tasks/2026-02-08-add-email-notifications.md

04

Claude fills in your answers

All sections populated from the conversation. Ready to reference while building.

05

When done, archive it

done-task.sh moves to .done/ with completion date in metadata.

Research / Prep

research

01

Start a research doc

Say /prep Evaluate PartyKit vs Liveblocks for real-time

02

Claude asks what matters

Type of research, evaluation criteria, what you already know. Different questions per type.

03

Pre-filled document created

Context filled in, criteria set, [TODO: Research needed] markers for actual investigation.

04

Research and fill

Work through the TODOs. The structure guides your investigation.

Architecture Decision

ADR

01

Record a decision

Say /adr Use Supabase RLS instead of API middleware

02

Claude walks through the "why"

Context, decision, alternatives considered, consequences. The most valuable part: rejected alternatives.

03

Auto-numbered ADR created

workspace/decisions/0002-use-supabase-rls.md — permanent record.

Bug Investigation

bug

01

Log the bug

Run new-bug.sh "IDOR vulnerability in amendments API" --severity critical

02

Structured investigation template

Steps to reproduce, expected vs actual, root cause analysis, fix plan, verification steps.

03

Fix and archive

done-task.sh moves to .done/ — bug history preserved.

Visualize Anything

visual

01

Ask to see it visually

Say /visualize Homer architecture or just ask "can you show me how X works?"

02

Claude builds an interactive HTML page

Factory-inspired design. Dark theme, warm neutrals, orange accents. Tabs, expandable sections, real data.

03

Opens in your browser

Like this page you're looking at right now.

File System

Global Layer: ~/.claude/

/doc-templates/14 work templates

-README.mdIndex: when to use each

-feature-spec.mdFeature specification

-bug-investigation.mdBug triage + root cause

-implementation-plan.mdStep-by-step build plan

-api-endpoint-design.mdREST/API route design

-database-migration.mdSchema change + rollback

-ui-component-spec.mdComponent design

-deployment-checklist.mdDeploy verification

-pr-review-checklist.mdStructured PR review

-adr.mdArchitecture Decision Record

-integration-plan.mdThird-party integration

-post-mortem.mdIncident analysis

-daily-plan.mdDaily session plan

-weekly-retro.mdWeekly retrospective

/prep-templates/7 research templates

-architecture-research.mdSystem design exploration

-api-evaluation.mdService/API evaluation

-competitor-analysis.mdCompetition landscape

-tech-stack-evaluation.mdTechnology comparison

-cost-analysis.mdCost modeling

-security-review.mdSecurity posture

/prompts/10 thinking frameworks

-code-review.mdReview framework

-debug-systematic.mdSystematic debugging

-refactor-plan.mdRefactoring strategy

-+ 7 more...Performance, migration, test, etc.

/generators/8 bash scripts

-_workspace-utils.shShared utilities

-new-project-workspace.shInit workspace dirs

-new-task.shCreate task

-new-feature.shFeature spec + branch

-new-bug.shBug investigation

-new-prep.shResearch doc

-new-adr.shArchitecture decision

-done-task.shArchive completed

/commands/Slash commands

-task.md/task — conversational task creation

-prep.md/prep — research doc creation

-adr.md/adr — architecture decision

-visualize.md/visualize — interactive HTML visuals

Per-Project: <project>/workspace/

/workspace/Project workspace root

-README.mdHow to use this workspace

/tasks/Active task files

/.done/Completed archive

/prep/Research + investigation docs

/scratch/Quick experiments (gitignored)

/ideas/Future concepts

/decisions/Architecture Decision Records

Quick Reference

Slash Commands (Conversational)

/task "Add email alerts"

Claude interviews you, fills the template, creates task file

/prep "Evaluate PartyKit"

Research doc with type-specific questions

/adr "Use RLS over middleware"

Architecture decision with alternatives + consequences

/visualize Homer architecture

Interactive HTML visualization in the browser

Generator Scripts (Direct CLI)

new-task.sh "Title" --priority high

Creates workspace/tasks/YYYY-MM-DD-slug.md

new-feature.sh "Name" --branch

Feature spec + optionally creates git branch

new-bug.sh "Desc" --severity critical

Bug investigation with severity levels

new-prep.sh "Topic" --type tech-stack

Research doc (6 types available)

new-adr.sh "Decision title"

Auto-incrementing NNNN-slug.md

done-task.sh <task-file>

Moves to .done/ with completion date

new-project-workspace.sh --project homer

Creates full workspace/ directory structure

proj homer workspace

Show workspace status (tasks, prep, ADRs)

Prep Types

architecture

System architecture exploration

api

API or service evaluation

competitor

Competitive landscape analysis

tech-stack

Technology comparison matrix

cost

Infrastructure cost modeling

security

Security posture assessment

Capabilities

Conversational Templates

No more filling in bracket placeholders. Claude asks you questions by voice or text, then fills in the entire template from your answers. Just talk naturally.

You: /task Add email notifications for Homer

Claude: Got it. How urgent is this? [High / Medium / Low]

You: High priority, it's a feature

Claude: What should "done" look like?

You: Agents get emailed when a lead comes in

Claude: [Creates and fills the entire task file]

Interactive Visualizations

Complex topics explained through interactive HTML pages instead of walls of text. Factory-inspired design language. Tabs, expandable sections, real codebase data. This page is an example.

You: /visualize HYDRA job structure

Claude builds a dark-themed interactive HTML page with tabbed views showing all 23 launchd jobs, their dependencies, costs, and scheduling. Opens in your browser.

Task Lifecycle

File-based task management with no database. Create tasks, track priority, archive when complete. Everything is git-tracked (except scratch/).

Create: new-task.sh "Fix IDOR bug" --priority critical

Work: Reference the task file while building the fix

Archive: done-task.sh workspace/tasks/2026-02-08-fix-idor-bug.md

Moved to .done/ with completion date in metadata

Architecture Decision Records

Capture the WHY behind technical choices so future-you understands the reasoning. Auto-numbered. Permanent records. The most valuable part: rejected alternatives.

You: /adr Use Supabase RLS instead of API middleware

Claude: What led to this? What was the alternative?

You: We kept missing auth checks. Middleware works but RLS is at the database level, so even if we forget in the API, data is protected.

Claude: [Creates 0002-use-supabase-rls.md with full context, decision, alternatives, and trade-offs]

What We Did Right

Strengths

Two-level architecture

Global templates (~/.claude/) shared across every project + per-project workspaces (<project>/workspace/) for local state. Clean separation of concerns: shared knowledge stays global, project context stays local. Change a template once, every future project gets it.

Bash 3.2 compatibility

Zero dependencies beyond what macOS ships. Every generator runs on the stock /bin/bash (3.2) without Homebrew, without Python, without Node. Portable, debuggable, and runs everywhere on macOS out of the box.

Conversational form filling

Templates guide the conversation, conversation fills the templates. Claude uses AskUserQuestion to interview you through each field. No brackets to fill in, no guessing what goes where. The template defines structure; you just talk.

File-based over database

Everything is a markdown file. Git-tracked, portable, readable with any text editor, no infrastructure to maintain. Grep works. Diff works. Backup is just a git push. No server, no schema, no migrations.

What Needs Fixing

Issues

Medium

No automated task cleanup

The .done/ directory accumulates completed tasks forever. No archival, no rotation, no size limit. Over months of use, this becomes a noise problem when searching or browsing.

In ~/.claude/generators/, create a cleanup-done.sh script that archives .done/ tasks older than 30 days into a .done/archive/ folder with YYYY-MM prefix. Keep the 10 most recent in .done/ for quick reference. Bash 3.2 compatible.

Low

No template versioning

Templates evolve as the system grows, but old task files created from earlier versions reference outdated formats. No way to know which version of a template produced a given file, which makes migration harder.

Add a 'template_version: 1' field to each template in ~/.claude/doc-templates/ and ~/.claude/prep-templates/. Update generators to stamp the version into created files. This enables future migration scripts.

Medium

Workspace scratch/ has no size guard

The scratch/ directory is gitignored by design -- experiments live there. But nothing warns you when it grows unbounded. A forgotten prototype or large dataset can silently consume disk space.

In ~/.claude/generators/_workspace-utils.sh, add a check_scratch_size() function that warns when any project's workspace/scratch/ exceeds 50MB. Wire it into the generators as a non-blocking warning.

High-Impact Next Steps

Ordered by Leverage

01

Visualize Homer architecture

The Homer monorepo has dashboard, api, widget, and packages layers with Supabase data flow, proxy whitelists, and API route patterns. A visual map makes onboarding instant and helps spot architectural drift.

/visualize Homer monorepo architecture -- show dashboard, api, widget, and packages layers with Supabase data flow. Include the proxy whitelist and API route patterns.

02

Wire /task into HYDRA Telegram

Create tasks from Telegram via natural language. Say "create a task for fixing the auth bug" and HYDRA routes it to new-task.sh. Removes the need to be at a terminal to capture work.

In ~/.hydra/telegram-listener.sh, add a 'task:' command type that calls new-task.sh with the message content. Add NL parsing examples to telegram-parse-natural.sh: 'create a task for...' and 'new task:...' patterns.

03

Template usage analytics

Track which templates get used most and by which project. Reveals which templates pull their weight and which are dead weight. Data-driven template evolution instead of guessing.

Add a log line to each generator in ~/.claude/generators/ that appends '{date}|{template}|{project}' to ~/.claude/workspace-usage.log. Create a workspace-stats.sh that summarizes usage by template and project.

Prompts Summary

All Prompts

1.

Automated task cleanup script