From 81f70bb2a217f6ff2bbe05047a48bbd1c606f9e2 Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:45:29 +0300 Subject: [PATCH 01/13] feat(html-templates): scaffold HTML template foundation for v2.4.0 SDD migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lay the semantic foundation for the spec-driven development workflow's migration from Markdown to canonical HTML. Each template establishes the data-attribute-based mutation strategy that lets Claude's Edit tool act as the HTML mutator without introducing any external parser dependency. Templates added (core/templates/html/): - tasks.html.template — canonical Option D exemplar. Establishes the data-task-id + data-status contract that /own:done mutates and /own:status counts via pure text operations. - roadmap.html.template — phase-detection contract using data-phase-number + data-phase-name + data-status, consumed by /own:feature for next-incomplete-phase auto-detection. - mission.html.template — project vision template with distinct data-dod-id namespace to prevent /own:done cross-file mutations. - stack.html.template — technology table with data-stack-layer rows and source attribution via data-source-type. - spec.html.template — user stories, acceptance criteria, edge cases, and out-of-scope sections with referenceable data-* IDs. - design.html.template — technical software architecture (NOT UI mockups). Trade-off articles with chosen/rejected/reasoning blocks. - theme-prompt.md.template — default Apple Documentation aesthetic prompt consumed by frontend-design to generate theme.css. - theme-fallback.css — hand-authored production CSS mirroring the default aesthetic. Used when frontend-design plugin is unavailable. Covers every semantic class and data-* selector across all 6 templates with light/dark mode via prefers-color-scheme. Inline HTML comments document mutation contracts in every template for self-discoverability across future Claude sessions. Refs #9 Co-Authored-By: Claude Sonnet 4.6 --- core/templates/html/design.html.template | 126 ++++++ core/templates/html/mission.html.template | 78 ++++ core/templates/html/roadmap.html.template | 96 +++++ core/templates/html/spec.html.template | 109 +++++ core/templates/html/stack.html.template | 137 ++++++ core/templates/html/tasks.html.template | 103 +++++ core/templates/html/theme-fallback.css | 426 +++++++++++++++++++ core/templates/html/theme-prompt.md.template | 62 +++ 8 files changed, 1137 insertions(+) create mode 100644 core/templates/html/design.html.template create mode 100644 core/templates/html/mission.html.template create mode 100644 core/templates/html/roadmap.html.template create mode 100644 core/templates/html/spec.html.template create mode 100644 core/templates/html/stack.html.template create mode 100644 core/templates/html/tasks.html.template create mode 100644 core/templates/html/theme-fallback.css create mode 100644 core/templates/html/theme-prompt.md.template diff --git a/core/templates/html/design.html.template b/core/templates/html/design.html.template new file mode 100644 index 0000000..e7d2887 --- /dev/null +++ b/core/templates/html/design.html.template @@ -0,0 +1,126 @@ + + + + + + + {{FEATURE_TITLE}} — Technical Design + + + + +
+

Phase {{PHASE_N}} — {{PHASE_NAME}} — Technical Design

+

{{FEATURE_TITLE}}

+

Generated: {{ISO_DATE}}

+
+ +
+ +
+

Architecture Overview

+

{{ARCHITECTURE_OVERVIEW}}

+
+ 
{{ARCHITECTURE_DIAGRAM}}
+
{{DIAGRAM_CAPTION}}
+
+
+ +
+

Data Flow

+

{{DATA_FLOW_DESCRIPTION}}

+
    +
  1. {{FLOW_STEP_1}}
    2. +
  2. {{FLOW_STEP_2}}
    3. +
  3. {{FLOW_STEP_3}}
    4. +
+
+ +
+

Component Breakdown

+ + + + + + + + + + + + + + + + +
ComponentResponsibilityOwns
{{COMPONENT_1_NAME}}{{COMPONENT_1_RESPONSIBILITY}}{{COMPONENT_1_OWNS}}
{{COMPONENT_2_NAME}}{{COMPONENT_2_RESPONSIBILITY}}{{COMPONENT_2_OWNS}}
+
+ +
+

Trade-offs & Decisions

+ +
+

{{TRADE_OFF_1_TITLE}}

+

{{TRADE_OFF_1_CONTEXT}}

+

Chosen: {{TRADE_OFF_1_CHOSEN}}

+

Rejected: {{TRADE_OFF_1_REJECTED}}

+

Why: {{TRADE_OFF_1_REASONING}}

+
+ +
+

{{TRADE_OFF_2_TITLE}}

+

{{TRADE_OFF_2_CONTEXT}}

+

Chosen: {{TRADE_OFF_2_CHOSEN}}

+

Rejected: {{TRADE_OFF_2_REJECTED}}

+

Why: {{TRADE_OFF_2_REASONING}}

+
+
+ +
+

File Structure

+ 
{{FILE_TREE}}
+
+ +
+

Open Questions

+

Decisions deferred until implementation:

+
    +
  • {{QUESTION_1}}
    • +
+
+ +
+ + + + + diff --git a/core/templates/html/mission.html.template b/core/templates/html/mission.html.template new file mode 100644 index 0000000..0761b56 --- /dev/null +++ b/core/templates/html/mission.html.template @@ -0,0 +1,78 @@ + + + + + + + {{PROJECT_NAME}} — Mission + + + + +
+

Project Mission

+

{{PROJECT_NAME}}

+

Generated: {{ISO_DATE}}

+
+ +
+ +
+

The Problem

+

{{PROBLEM_STATEMENT}}

+
+ +
+

Who Is This For?

+

{{AUDIENCE}}

+
+ +
+

Definition of Done

+

When these things work, the project is COMPLETE:

+ + +
+ + {{DOD_ITEM_1}} +
+ +
+ + {{DOD_ITEM_2}} +
+ +
+ + {{DOD_ITEM_3}} +
+
+ +
+

Why This Matters

+

{{WHY_THIS_MATTERS}}

+
+ +
+ +
+

OwnYourCode v{{VERSION}} — about

+
+ + + diff --git a/core/templates/html/roadmap.html.template b/core/templates/html/roadmap.html.template new file mode 100644 index 0000000..96a2f6c --- /dev/null +++ b/core/templates/html/roadmap.html.template @@ -0,0 +1,96 @@ + + + + + + + {{PROJECT_NAME}} — Roadmap + + + + +
+

Project Roadmap

+

{{PROJECT_NAME}}

+

Generated: {{ISO_DATE}}

+
+ +
+ +

{{INTRO_PARAGRAPH}}

+ + + +
+

Phase 1: Foundation

+

Priority: HIGH

+

{{PHASE_1_DESCRIPTION}}

+
    +
  • Project structure scaffolded
    • +
  • Core dependencies installed
    • +
  • Development environment verified
    • +
+
+ +
+

Phase 2: Core Features

+

Priority: MEDIUM

+

{{PHASE_2_DESCRIPTION}}

+
    +
  • {{CORE_FEATURE_1}}
    • +
  • {{CORE_FEATURE_2}}
    • +
+
+ +
+

Phase 3: Polish & Deploy

+

Priority: LOW

+

Testing, documentation, deployment.

+
    +
  • Testing and bug fixes
    • +
  • Documentation polished
    • +
  • Deployment ready
    • +
+
+ +
+ +
+

OwnYourCode v{{VERSION}} — about

+
+ + + diff --git a/core/templates/html/spec.html.template b/core/templates/html/spec.html.template new file mode 100644 index 0000000..ee98c5b --- /dev/null +++ b/core/templates/html/spec.html.template @@ -0,0 +1,109 @@ + + + + + + + {{FEATURE_TITLE}} — Spec + + + + +
+

Phase {{PHASE_N}} — {{PHASE_NAME}} — Specification

+

{{FEATURE_TITLE}}

+

Generated: {{ISO_DATE}}

+
+ +
+ +
+

Overview

+

{{OVERVIEW}}

+
+ +
+

Why This Feature?

+

{{MOTIVATION}}

+
+ +
+

User Stories

+ +
+

As a {{ACTOR_1}}

+

I want {{WANT_1}}

+

So that {{SO_THAT_1}}

+
+ +
+

As a {{ACTOR_2}}

+

I want {{WANT_2}}

+

So that {{SO_THAT_2}}

+
+
+ +
+

Acceptance Criteria

+

This feature is "done" when:

+
    +
  • {{CRITERION_1}}
    • +
  • {{CRITERION_2}}
    • +
  • {{CRITERION_3}}
    • +
+
+ +
+

Edge Cases

+

Scenarios the implementation MUST handle:

+
    +
  • {{EDGE_CASE_1}}
    • +
  • {{EDGE_CASE_2}}
    • +
+
+ +
+

Out of Scope

+

Explicitly NOT in this feature (prevents scope creep):

+
    +
  • {{OUT_OF_SCOPE_1}}
    • +
  • {{OUT_OF_SCOPE_2}}
    • +
+
+ +
+

Open Questions

+

Decisions to resolve before/during implementation:

+
    +
  • {{QUESTION_1}}
    • +
+
+ +
+ + + + + diff --git a/core/templates/html/stack.html.template b/core/templates/html/stack.html.template new file mode 100644 index 0000000..86cddb2 --- /dev/null +++ b/core/templates/html/stack.html.template @@ -0,0 +1,137 @@ + + + + + + + {{PROJECT_NAME}} — Stack + + + + +
+

Technology Stack

+

{{PROJECT_NAME}}

+

Generated: {{ISO_DATE}}

+
+ +
+ +
+

Detected / Chosen Stack

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LayerTechnologyVersionSourcePurpose
Frontend{{FRONTEND_NAME}}{{FRONTEND_VERSION}}{{FRONTEND_SOURCE}}{{FRONTEND_PURPOSE}}
Backend{{BACKEND_NAME}}{{BACKEND_VERSION}}{{BACKEND_SOURCE}}{{BACKEND_PURPOSE}}
Database{{DATABASE_NAME}}{{DATABASE_VERSION}}{{DATABASE_SOURCE}}{{DATABASE_PURPOSE}}
+ +
+ Source attribution legend +
+
package.json
+
Version from your installed dependencies (source of truth).
+
MCP verified (YYYY-MM-DD)
+
Confirmed via Context7 / Octocode on this date.
+
Verify at [URL]
+
Could not verify; check official docs for current version.
+
+
+
+ +
+

Package Manager

+

Using: {{PACKAGE_MANAGER}}

+

{{PACKAGE_MANAGER_EDUCATION}}

+
+ +
+

Why These Choices?

+

{{RATIONALE}}

+
+ +
+

Version Notes

+

{{VERSION_NOTES}}

+
+ +
+

Reference Projects (via Octocode)

+ +
+ +
+

Key Files

+ + + + + + + + +
FilePurpose
{{ENTRY_POINT}}{{ENTRY_POINT_PURPOSE}}
{{CONFIG_FILE}}{{CONFIG_FILE_PURPOSE}}
+
+ +
+ +
+

+ ⚠️ Generated {{ISO_DATE}}. Technology versions change frequently. If this + document is more than 30 days old, re-run /own:init or check + official docs. +

+

OwnYourCode v{{VERSION}} — about

+
+ + + diff --git a/core/templates/html/tasks.html.template b/core/templates/html/tasks.html.template new file mode 100644 index 0000000..9576c7e --- /dev/null +++ b/core/templates/html/tasks.html.template @@ -0,0 +1,103 @@ + + + + + + + {{FEATURE_TITLE}} — Tasks + + + + +
+

Phase {{PHASE_N}} — {{PHASE_NAME}}

+

{{FEATURE_TITLE}} — Tasks

+

Generated: {{ISO_DATE}}

+
+ +
+ + + +
+

Setup

+ + +
+ + Install dependencies +
+ +
+ + Configure environment variables +
+
+ +
+

Implementation

+ +
+ + Build core feature logic +
+ +
+ + Wire UI to logic +
+
+ +
+

Verification

+ +
+ + Write tests covering edge cases +
+ +
+ + Run /own:done with 6-Gates review +
+
+ +
+ +
+

OwnYourCode v{{VERSION}} — about

+
+ + + diff --git a/core/templates/html/theme-fallback.css b/core/templates/html/theme-fallback.css new file mode 100644 index 0000000..eb25ff5 --- /dev/null +++ b/core/templates/html/theme-fallback.css @@ -0,0 +1,426 @@ +/* ════════════════════════════════════════════════════════════════════ + OwnYourCode — Default Fallback Theme + ════════════════════════════════════════════════════════════════════ + Used when the `frontend-design` plugin is NOT installed. + Mirrors the bundled Apple Documentation aesthetic so users without + the plugin still get an acceptable, premium-feeling experience. + + Covers every semantic class and data-* selector emitted by the 6 + bundled HTML templates. Light and dark modes via prefers-color-scheme. + ════════════════════════════════════════════════════════════════════ */ + +/* ─── CSS Custom Properties (tokens) ─── */ + +:root { + /* Light mode defaults */ + --bg: #FAFAFA; + --bg-elevated: #FFFFFF; + --bg-subtle: #F2F2F4; + --text: #1D1D1F; + --text-secondary: #515154; + --text-tertiary: #86868B; + --accent: #0066CC; + --accent-soft: rgba(0, 102, 204, 0.08); + --border: #E5E5E7; + --shadow: 0 1px 3px rgba(0, 0, 0, 0.04), 0 1px 2px rgba(0, 0, 0, 0.06); + + --success: #34A853; + --warn: #D97706; + --danger: #DC2626; + + /* Typography */ + --font-sans: ui-sans-serif, -apple-system, "SF Pro Display", "Segoe UI", system-ui, sans-serif; + --font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace; + + /* Layout */ + --content-max: 720px; + --radius: 8px; + --radius-sm: 4px; + + /* Motion */ + --transition: 0.2s ease; +} + +@media (prefers-color-scheme: dark) { + :root { + --bg: #1A1A1F; + --bg-elevated: #232328; + --bg-subtle: #2A2A30; + --text: #F5F5F7; + --text-secondary: #B4B4B8; + --text-tertiary: #86868B; + --accent: #0A84FF; + --accent-soft: rgba(10, 132, 255, 0.12); + --border: #38383D; + --shadow: 0 1px 3px rgba(255, 255, 255, 0.04), 0 1px 2px rgba(255, 255, 255, 0.06); + } +} + +/* ─── Reset + base ─── */ + +*, *::before, *::after { box-sizing: border-box; } + +html { font-size: 16px; -webkit-font-smoothing: antialiased; } + +body { + font-family: var(--font-sans); + font-size: 1rem; + font-weight: 400; + line-height: 1.6; + color: var(--text); + background: var(--bg); + margin: 0; + padding: 4rem 2rem; + transition: background var(--transition), color var(--transition); +} + +main { + max-width: var(--content-max); + margin: 0 auto; +} + +/* ─── Typography ─── */ + +h1, h2, h3, h4 { + font-weight: 600; + letter-spacing: -0.015em; + line-height: 1.25; + margin: 0 0 1rem; +} + +h1 { font-size: 2.5rem; } +h2 { font-size: 1.75rem; margin-top: 3rem; } +h3 { font-size: 1.25rem; margin-top: 2rem; } + +p { margin: 0 0 1.25rem; } + +code { + font-family: var(--font-mono); + font-size: 0.875em; + background: var(--bg-subtle); + padding: 0.125rem 0.375rem; + border-radius: var(--radius-sm); + color: var(--text); +} + +pre { + font-family: var(--font-mono); + font-size: 0.875rem; + background: var(--bg-subtle); + padding: 1.25rem; + border-radius: var(--radius); + border: 1px solid var(--border); + overflow-x: auto; + line-height: 1.5; +} + +a { + color: var(--accent); + text-decoration: none; + border-bottom: 1px solid transparent; + transition: border-color var(--transition); +} +a:hover { border-bottom-color: var(--accent); } + +/* ─── Document chrome ─── */ + +.document-header { + max-width: var(--content-max); + margin: 0 auto 3rem; + padding-bottom: 2rem; + border-bottom: 1px solid var(--border); +} + +.document-eyebrow { + font-size: 0.875rem; + font-weight: 600; + letter-spacing: 0.02em; + text-transform: uppercase; + color: var(--accent); + margin: 0 0 0.5rem; +} + +.document-meta { + font-size: 0.875rem; + color: var(--text-tertiary); + margin: 0.5rem 0 0; +} + +.document-footer { + max-width: var(--content-max); + margin: 4rem auto 0; + padding-top: 2rem; + border-top: 1px solid var(--border); + font-size: 0.875rem; + color: var(--text-tertiary); +} + +.section-intro { + color: var(--text-secondary); + margin-bottom: 1.5rem; +} + +/* ─── Tasks (Option D contract) ─── */ + +.task, +.dod-item { + display: flex; + align-items: center; + gap: 0.875rem; + padding: 0.875rem 1rem; + background: var(--bg-elevated); + border: 1px solid var(--border); + border-radius: var(--radius); + margin-bottom: 0.625rem; + box-shadow: var(--shadow); + transition: background var(--transition), opacity var(--transition); +} + +.task input[type="checkbox"], +.dod-item input[type="checkbox"] { + appearance: none; + width: 24px; + height: 24px; + border: 2px solid var(--border); + border-radius: var(--radius-sm); + cursor: pointer; + position: relative; + flex-shrink: 0; + transition: border-color var(--transition), background var(--transition); +} + +.task input[type="checkbox"]:checked, +.dod-item input[type="checkbox"]:checked { + background: var(--accent); + border-color: var(--accent); +} + +.task input[type="checkbox"]:checked::after, +.dod-item input[type="checkbox"]:checked::after { + content: ""; + position: absolute; + left: 6px; top: 2px; + width: 6px; height: 12px; + border: solid #fff; + border-width: 0 2px 2px 0; + transform: rotate(45deg); +} + +.task[data-status="completed"], +.dod-item[data-status="completed"] { + opacity: 0.65; +} + +.task[data-status="completed"] .task-text, +.dod-item[data-status="completed"] .dod-text { + text-decoration: line-through; + color: var(--text-tertiary); +} + +.task-text, .dod-text { font-size: 1rem; } + +/* ─── Phase groups (tasks.html) ─── */ + +.phase-group { + margin-bottom: 2.5rem; +} + +.phase-group h2 { + font-size: 1.25rem; + color: var(--text-secondary); + margin-bottom: 1rem; + padding-bottom: 0.5rem; + border-bottom: 1px solid var(--border); +} + +/* ─── Roadmap phases ─── */ + +.phase { + margin-bottom: 2.5rem; + padding: 1.5rem; + background: var(--bg-elevated); + border: 1px solid var(--border); + border-radius: var(--radius); +} + +.phase[data-status="complete"] { + opacity: 0.7; +} + +.phase[data-status="complete"] h2::before { + content: "✓ "; + color: var(--success); +} + +.phase-priority { + display: inline-block; + font-size: 0.75rem; + font-weight: 600; + letter-spacing: 0.05em; + text-transform: uppercase; + padding: 0.25rem 0.625rem; + border-radius: 999px; + margin-bottom: 0.75rem; +} + +.phase-priority[data-priority="high"] { background: rgba(220, 38, 38, 0.12); color: var(--danger); } +.phase-priority[data-priority="medium"] { background: rgba(217, 119, 6, 0.12); color: var(--warn); } +.phase-priority[data-priority="low"] { background: rgba(52, 168, 83, 0.12); color: var(--success); } + +.phase-description { + color: var(--text-secondary); + margin-bottom: 0.75rem; +} + +.phase-items { + margin: 0; + padding-left: 1.25rem; +} +.phase-items li { + color: var(--text-secondary); + margin-bottom: 0.375rem; +} + +/* ─── Tables ─── */ + +table { + width: 100%; + border-collapse: collapse; + margin-bottom: 1.5rem; + font-size: 0.9375rem; +} + +thead th { + text-align: left; + font-weight: 600; + color: var(--text-secondary); + border-bottom: 1px solid var(--border); + padding: 0.75rem 1rem; +} + +tbody td { + padding: 0.75rem 1rem; + border-bottom: 1px solid var(--border); + vertical-align: top; +} + +tbody tr:nth-child(even) { background: var(--bg-subtle); } +tbody tr:last-child td { border-bottom: none; } + +/* ─── Spec & Design sections ─── */ + +.mission-section, +.stack-section, +.spec-section, +.design-section { + margin-bottom: 3rem; +} + +.user-story { + padding: 1.25rem; + background: var(--bg-elevated); + border-left: 3px solid var(--accent); + border-radius: var(--radius); + margin-bottom: 1rem; +} +.user-story p { margin-bottom: 0.5rem; } +.user-story p:last-child { margin-bottom: 0; } + +.trade-off { + padding: 1.5rem; + background: var(--bg-elevated); + border: 1px solid var(--border); + border-radius: var(--radius); + margin-bottom: 1.5rem; + box-shadow: var(--shadow); +} + +.trade-off h3 { margin-top: 0; } +.trade-off-chosen { color: var(--success); } +.trade-off-rejected { color: var(--text-tertiary); } +.trade-off-reasoning { + margin-top: 1rem; + padding-top: 1rem; + border-top: 1px solid var(--border); + color: var(--text-secondary); +} + +.architecture-diagram pre, +pre[data-file-tree] { + background: var(--bg-subtle); +} + +.architecture-diagram figcaption { + font-size: 0.875rem; + color: var(--text-tertiary); + margin-top: 0.5rem; + text-align: center; +} + +/* ─── Lists with data-IDs ─── */ + +.acceptance-criteria, +.edge-cases, +.out-of-scope, +.open-questions, +.data-flow-steps { + margin: 0 0 1.5rem; + padding-left: 1.5rem; +} + +.acceptance-criteria li, +.edge-cases li, +.out-of-scope li, +.open-questions li, +.data-flow-steps li { + margin-bottom: 0.5rem; + color: var(--text-secondary); +} + +.out-of-scope li { color: var(--text-tertiary); text-decoration: line-through; opacity: 0.7; } + +/* ─── Misc utilities ─── */ + +.source-legend { + font-size: 0.875rem; + color: var(--text-secondary); + margin-top: 1rem; +} +.source-legend summary { + cursor: pointer; + font-weight: 600; + color: var(--text); +} +.source-legend dl { margin-top: 0.75rem; } +.source-legend dt { font-weight: 600; margin-top: 0.5rem; } +.source-legend dd { margin: 0 0 0.5rem 1rem; color: var(--text-secondary); } + +.reference-projects { padding-left: 1.5rem; } +.reference-projects li { margin-bottom: 0.5rem; } + +.version-freshness { + display: block; + padding: 0.875rem 1rem; + background: rgba(217, 119, 6, 0.08); + border: 1px solid rgba(217, 119, 6, 0.2); + border-radius: var(--radius); + color: var(--warn); + font-size: 0.875rem; + margin-bottom: 1rem; +} + +.spec-nav { + display: flex; + gap: 1.5rem; + margin-bottom: 1rem; +} + +/* ─── Responsive ─── */ + +@media (max-width: 640px) { + body { padding: 2rem 1rem; } + h1 { font-size: 2rem; } + h2 { font-size: 1.5rem; } + table { font-size: 0.875rem; } + thead th, tbody td { padding: 0.5rem; } +} diff --git a/core/templates/html/theme-prompt.md.template b/core/templates/html/theme-prompt.md.template new file mode 100644 index 0000000..4dc3ab4 --- /dev/null +++ b/core/templates/html/theme-prompt.md.template @@ -0,0 +1,62 @@ + + +# Default OwnYourCode Theme — "Apple Documentation" + +# TODO(daniel): Review this draft. Rewrite in your own voice if it doesn't match +# your vision for OwnYourCode's default aesthetic. The taste here defines what +# every user sees on first /own:init. + +Generate a premium, calm, technical-document aesthetic inspired by Apple +Developer Documentation (developer.apple.com). + +## Visual System + +- **Typography:** SF Pro Display (system-ui, -apple-system, "Segoe UI" fallback) + - Headings: weight 600, generous letter-spacing + - Body: weight 400, 1.6 line-height for readability + - Code: SF Mono (ui-monospace fallback) + +- **Color Modes:** Auto-detect via prefers-color-scheme + - Light mode: background #FAFAFA, text #1D1D1F, accent #0066CC + - Dark mode: background #1A1A1F, text #F5F5F7, accent #0A84FF + - Smooth transitions between modes (0.3s ease) + +- **Layout:** + - Generous whitespace — 4rem section spacing, 2rem paragraph spacing + - Max content width 720px (centered) for readability + - Soft 8px corners on cards, no harsh borders + - Subtle shadows — 0 1px 3px rgba(0,0,0,0.04) light / 0 1px 3px rgba(255,255,255,0.04) dark + +- **Components:** + - Task checkboxes: large, satisfying (24px), animated check on transition to data-status="completed" + - Code blocks: subtle tinted background, soft border + - Tables: zebra striping, no harsh grid lines + - Headings: weight contrast, no underlines + - Phase priority badges: small pills colored by data-priority (high/medium/low) + +## Vibe + +Calm, premium, opinionated. Not flashy. The reader should feel like they're +reading a real product document, not a generated artifact. From 81f68fa34aeb2b715d763afb211a2364c2ada58b Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:45:41 +0300 Subject: [PATCH 02/13] feat(own:theme): introduce theme command with frontend-design plugin integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the v2.4.0 /own:theme slash command that lets developers manage the visual styling of their generated HTML SDD files independently of the workflow itself. The theme is a single CSS file referenced by all six HTML templates, so changing themes is instant and lossless — no HTML files need regenerating. The command exposes four actions through AskUserQuestion: - Change theme prompt — free-text custom prompt for frontend-design - Pick a preset — bundled aesthetic presets (apple-light/dark, etc.) - Regenerate current — re-roll CSS using the existing prompt - View full prompt — read-only inspection of theme-prompt.md Every write is backup-first: the prior prompt and CSS are copied to ownyourcode/.theme/.history/[ISO-timestamp]/ before overwrite, enabling non-destructive iteration. The accompanying /own:theme --revert flow restores from any timestamped backup. frontend-design is treated as a soft dependency: when the plugin is unavailable, the command falls back to the bundled theme-fallback.css and writes theme.fallback_mode = true to the manifest. Users without the plugin still get an acceptable themed output instead of an error. Hard constraint enforced in the command's instructions: theme prompts that attempt to alter SDD workflow semantics (e.g., "hide the checkboxes") must be rejected with a warning. The theme is visual styling only — never workflow. Refs #9 Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/own/theme.md | 309 ++++++++++++++++++++++++++++++++++ 1 file changed, 309 insertions(+) create mode 100644 .claude/commands/own/theme.md diff --git a/.claude/commands/own/theme.md b/.claude/commands/own/theme.md new file mode 100644 index 0000000..7a61972 --- /dev/null +++ b/.claude/commands/own/theme.md @@ -0,0 +1,309 @@ +--- +name: theme +description: View, change, or regenerate the visual theme of your OwnYourCode HTML files (v2.4.0+) +allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion, Skill +--- + +# /own:theme + +> ⚠️ **PLAN MODE WARNING:** Toggle plan mode off before running this command (`shift+tab`). OwnYourCode commands don't work correctly with plan mode. + +Manage the visual styling of your project's HTML files (mission, stack, roadmap, spec, design, tasks). + +## Overview + +This command lets you: + +1. **View** the current theme prompt +2. **Change** the theme by giving a custom design prompt +3. **Pick** a bundled preset (apple-light, apple-dark, terminal, paper, brutalist) +4. **Regenerate** the theme CSS using the existing prompt (re-roll the design) +5. **Revert** to a previous theme via `/own:theme --revert` + +**The theme is a single CSS file.** All 6 HTML files reference it via ``, so changing the theme is instant — no HTML files need regenerating. + +## Files affected + +- `ownyourcode/.theme/theme-prompt.md` — the active theme prompt +- `ownyourcode/.theme/theme.css` — the generated CSS (overwritten on each run) +- `ownyourcode/.theme/.history/[ISO-timestamp]/` — backup of previous theme prompt + CSS (created on every write) +- `.claude/ownyourcode-manifest.json` — `theme.fallback_mode` flag, `theme.last_updated` timestamp + +## Hard constraints + +- **Theme = visual styling ONLY.** This command must never alter the workflow, the SDD purpose of any HTML file, or any data-* contract used by other commands. If the user's custom prompt suggests workflow changes, reject those modifications and surface a warning. +- **Backup-before-write is non-negotiable.** Always copy current `theme-prompt.md` and `theme.css` to `.history/[timestamp]/` BEFORE generating new ones. Enables revert. +- **Frontend-design plugin is a soft dependency.** If unavailable, fall back to `theme-fallback.css` (shipped with the install) but never block the user. + +--- + +## Execution Flow + +### Phase 0: Argument detection + +Check if the user invoked with `--revert`: + +- `/own:theme --revert` → jump to **Revert Flow** section below +- `/own:theme` (no args) → continue to Phase 1 + +### Phase 1: Pre-flight check + +Run these checks silently: + +1. **Verify install:** `ownyourcode/.theme/` directory exists. + - If not, this project isn't yet on v2.4.0+ HTML mode. Tell the user: + > "Your project is still using Markdown SDD files. To use themed HTML output, run `/own:migrate` first." + - **STOP execution.** + +2. **Read current state:** Read `ownyourcode/.theme/theme-prompt.md` (first 8 lines for preview). + +3. **Detect frontend-design plugin:** Run silently: + ```bash + ls ~/.claude/plugins/cache/claude-plugins-official/frontend-design 2>/dev/null + ``` + - Exists → `plugin_available = true` + - Missing → `plugin_available = false`. Note: fallback CSS will be used. + +### Phase 2: Show current state + action menu + +Display: + +``` +🎨 Current theme prompt (preview): + + [first 8 lines of theme-prompt.md, indented] + ... + +Plugin status: [✓ frontend-design installed | ⚠️ using fallback CSS] +Last updated: [theme.last_updated from manifest] +``` + +Then use `AskUserQuestion` to present the action menu: + +``` +Question: "What do you want to do?" + +Options: +1. Change theme prompt — Provide your own design description (free text) +2. Pick a preset — Choose from bundled presets (apple-light, apple-dark, etc.) +3. Regenerate current — Re-roll the CSS using the existing prompt +4. View full prompt — Read-only display of the current theme-prompt.md +``` + +Branch to the matching phase below. + +### Phase 3a: Change theme prompt (free text) + +Ask the user in chat (NOT AskUserQuestion — free text required): + +> "Describe how you want OwnYourCode to look. +> +> Tip: be specific. Mention typography, exact colors, vibe, dark/light mode behavior. Vague prompts ('modern and clean') produce generic AI-looking output. +> +> Example: +> 'A warm paper-like document. Serif headings (Charter or Georgia). Soft cream background (#F8F4E8). No dark mode. Slim 1px borders in #D4CFC0. Inline tables with no zebra striping.' +> +> Your prompt:" + +Wait for the user's free-text response. Then: + +1. Run **Phase 5: Backup-before-write** +2. Write the new prompt to `ownyourcode/.theme/theme-prompt.md` +3. Run **Phase 6: Regenerate CSS** +4. Run **Phase 7: Confirm + preview** + +### Phase 3b: Pick a preset + +Use AskUserQuestion to list the bundled presets. (Presets are stored in `ownyourcode/templates/html/presets/[name].md` — load names by listing that directory.) + +``` +Question: "Pick a preset:" + +Options (load dynamically from ownyourcode/templates/html/presets/): +1. apple-light — Light-mode Apple Documentation aesthetic +2. apple-dark — Dark-mode Apple Documentation aesthetic +3. terminal — Retro terminal aesthetic (mono, green-on-black) +4. paper — Print-document aesthetic (serif, paper background) +``` + +(If presets don't yet exist in the install — v2.4.0 may ship without all presets — only show those that exist.) + +When the user picks one: + +1. Run **Phase 5: Backup-before-write** +2. Copy `ownyourcode/templates/html/presets/[name].md` → `ownyourcode/.theme/theme-prompt.md` +3. Run **Phase 6: Regenerate CSS** +4. Run **Phase 7: Confirm + preview** + +### Phase 3c: Regenerate current + +No prompt change — use the existing `theme-prompt.md`. Useful for re-rolling when frontend-design produces a result the user doesn't love. + +1. Run **Phase 5: Backup-before-write** +2. (No prompt copy — leave `theme-prompt.md` unchanged) +3. Run **Phase 6: Regenerate CSS** +4. Run **Phase 7: Confirm + preview** + +### Phase 3d: View full prompt + +Read-only display. Read `ownyourcode/.theme/theme-prompt.md` and show the entire content: + +``` +📄 Current theme prompt (ownyourcode/.theme/theme-prompt.md): + +[full file content, fenced as a code block] + +To change this prompt, re-run /own:theme and pick "Change theme prompt". +``` + +**STOP execution.** No backup, no regeneration. + +--- + +### Phase 5: Backup-before-write + +Generate a timestamp: `BACKUP_TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")`. + +Create backup directory and copy current state: + +```bash +BACKUP_DIR="ownyourcode/.theme/.history/${BACKUP_TS}" +mkdir -p "$BACKUP_DIR" +cp ownyourcode/.theme/theme-prompt.md "$BACKUP_DIR/theme-prompt.md" 2>/dev/null +cp ownyourcode/.theme/theme.css "$BACKUP_DIR/theme.css" 2>/dev/null +``` + +Tell the user (briefly): `"📦 Previous theme backed up to .theme/.history/${BACKUP_TS}/"` + +### Phase 6: Regenerate CSS + +**If `plugin_available = true`:** + +Invoke the `frontend-design` skill with the prompt: + +``` +Skill: frontend-design (from plugin claude-plugins-official:frontend-design) +Input: contents of ownyourcode/.theme/theme-prompt.md +Output target: ownyourcode/.theme/theme.css +Additional constraint to inject into the skill's prompt: + "Generate ONLY a CSS file. The CSS must style the following semantic + classes used by OwnYourCode HTML templates: [list selectors from + theme-fallback.css]. Do NOT generate HTML, JS, or any other files. + Honor prefers-color-scheme if the prompt mentions dark mode." +``` + +**If `plugin_available = false`:** + +Tell the user: + +> "⚠️ The `frontend-design` plugin isn't installed. Using the bundled fallback CSS, which approximates the prompt's aesthetic but isn't custom-generated. +> +> To get a fully custom theme based on your prompt, install the plugin: +> /plugin install frontend-design@claude-plugins-official +> +> Then re-run /own:theme." + +Then copy `ownyourcode/templates/html/theme-fallback.css` → `ownyourcode/.theme/theme.css`. + +Update manifest: `theme.fallback_mode = true`. + +### Phase 7: Confirm + preview offer + +Display: + +``` +✅ Theme updated. + + Prompt: ownyourcode/.theme/theme-prompt.md + CSS: ownyourcode/.theme/theme.css + Backup: ownyourcode/.theme/.history/${BACKUP_TS}/ + +All 6 HTML files now use the new theme (no regeneration needed — +they reference theme.css via ). + +To revert: /own:theme --revert +``` + +Then ask: + +``` +Question: "Want to preview the new theme in your browser?" + +Options: +1. Yes — open mission.html now +2. No — I'll check it later +``` + +If yes: +```bash +open ownyourcode/product/mission.html # macOS +# (cross-platform: xdg-open on Linux, start on Windows) +``` + +Update manifest: `theme.last_updated = [ISO timestamp]`. + +**END.** + +--- + +## Revert Flow (`/own:theme --revert`) + +### Step 1: List available backups + +```bash +ls -1t ownyourcode/.theme/.history/ 2>/dev/null +``` + +If empty: +> "No theme backups found. Nothing to revert to." + +**STOP.** + +### Step 2: Present backups via AskUserQuestion + +Show up to 4 most recent backups (newer first). Format each label as the ISO timestamp + first 30 chars of that backup's prompt for context: + +``` +Question: "Which theme do you want to restore?" + +Options: +1. 2026-05-28T14-12-30Z — "A warm paper-like document. Serif…" +2. 2026-05-27T22-08-15Z — "Default OwnYourCode Theme — Apple…" +... +``` + +If more than 4 exist, add a "Show more" option that lists all in chat. + +### Step 3: Restore selected backup + +Copy backup files back to active location (and backup CURRENT state first, so user can undo a revert): + +```bash +CURRENT_TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ") +mkdir -p "ownyourcode/.theme/.history/${CURRENT_TS}-pre-revert" +cp ownyourcode/.theme/theme-prompt.md "ownyourcode/.theme/.history/${CURRENT_TS}-pre-revert/" +cp ownyourcode/.theme/theme.css "ownyourcode/.theme/.history/${CURRENT_TS}-pre-revert/" + +cp "ownyourcode/.theme/.history/${SELECTED_TS}/theme-prompt.md" ownyourcode/.theme/theme-prompt.md +cp "ownyourcode/.theme/.history/${SELECTED_TS}/theme.css" ownyourcode/.theme/theme.css +``` + +### Step 4: Confirm + +``` +✅ Theme reverted to ${SELECTED_TS}. + +Your previous theme was backed up to .history/${CURRENT_TS}-pre-revert/ +in case you want to undo this revert. +``` + +**END.** + +--- + +## Important Notes + +1. **Never edit theme.css by hand.** Edit `theme-prompt.md` and re-run `/own:theme`. Hand-edits will be overwritten next regenerate. +2. **The theme prompt is a CSS spec, not a Markdown formatting choice.** It tells `frontend-design` how to generate CSS rules — be specific. +3. **History grows.** `.theme/.history/` can accumulate. Future enhancement: `/own:theme --gc` to prune backups older than N days. Not in v2.4.0. +4. **Custom prompts that try to change semantics (e.g., "hide the checkboxes") MUST be rejected.** The theme is visual only — never alter the data-* contracts. Surface a warning if a prompt seems to violate this. From 71c4a333409a7fecb9063d642c477320a8d4df2f Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:45:54 +0300 Subject: [PATCH 03/13] feat(own:init): add Phase 0.5 for HTML theme setup with soft plugin dependency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Insert a new Phase 0.5 between the existing MCP check (Phase 0) and the project detection step (Phase 1) so that every fresh OwnYourCode project starts with a working visual theme for its eventual HTML SDD files. The phase is idempotent — it detects an existing .theme/ directory and skips entirely, so re-running /own:init never overwrites a user's customized theme. The new flow: 1. Skip if ownyourcode/.theme/ already exists. 2. Detect the frontend-design plugin via the marketplace cache. 3. If missing, surface a single AskUserQuestion with an explicit permission request to install it — Daniel does not want users discovering plugin dependencies via cryptic failures later. 4. Honor the user's choice: install on yes, set fallback_mode on skip. 5. Create ownyourcode/.theme/ with history directory pre-seeded. 6. Copy the default theme prompt from ownyourcode/templates/html/. 7. Generate theme.css via frontend-design (or copy fallback CSS). 8. Record theme metadata in .claude/ownyourcode-manifest.json. This phase ships in PR 1 ahead of the HTML output activation (planned for PR 2 in /own:feature). Until then, theme.css sits ready and is harmlessly inactive — no existing functionality breaks. When PR 2 flips /own:init's Phase 6 to write HTML, the theme is already in place. Refs #9 Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/own/init.md | 117 ++++++++++++++++++++++++++++++++++- 1 file changed, 116 insertions(+), 1 deletion(-) diff --git a/.claude/commands/own/init.md b/.claude/commands/own/init.md index 64fa11d..03256fd 100644 --- a/.claude/commands/own/init.md +++ b/.claude/commands/own/init.md @@ -730,7 +730,122 @@ To install (takes 30 seconds each): 📖 Full setup guide: ownyourcode/guides/context7-setup.md ``` -3. **If available:** Continue silently to Phase 1. +3. **If available:** Continue silently to Phase 0.5. + +--- + +### Phase 0.5: HTML Theme Setup (v2.4.0+) + +Set up the visual theme that all generated HTML files will use. This phase +runs ONCE per project (idempotent: detects existing `.theme/` and skips). + +#### Step 1: Detect existing theme + +```bash +test -d ownyourcode/.theme && echo "exists" || echo "missing" +``` + +- **Exists:** Skip the entire Phase 0.5. Continue to Phase 1. +- **Missing:** Continue to Step 2. + +#### Step 2: Check frontend-design plugin + +Run silently: + +```bash +ls ~/.claude/plugins/cache/claude-plugins-official/frontend-design 2>/dev/null +``` + +- **Found:** Set `plugin_available = true`. Skip Step 3. +- **Not found:** Continue to Step 3. + +#### Step 3: Offer to install the plugin + +Use AskUserQuestion: + +``` +Question: "OwnYourCode uses Anthropic's frontend-design plugin to generate + premium HTML styling for your spec files. Want me to install it? + (Free, official Anthropic plugin, takes ~5 seconds.)" + +Options: +1. Yes, install it — Best output quality, recommended +2. Skip — Use the bundled fallback styling instead +``` + +**If "Yes":** + +```bash +# Use Claude Code's plugin install mechanism. +# Note: this may require user-side confirmation; surface any output. +claude plugin install frontend-design@claude-plugins-official 2>&1 +``` + +After install, re-check availability. If install succeeded, set `plugin_available = true`. + +**If "Skip" (or install failed):** + +Set `plugin_available = false`. Note this in the manifest as `theme.fallback_mode = true`. Continue without error — the fallback CSS will be used. + +#### Step 4: Create the `.theme/` directory and seed files + +```bash +mkdir -p ownyourcode/.theme/.history +``` + +Copy the default theme prompt from the install: + +```bash +cp ownyourcode/templates/html/theme-prompt.md.template \ + ownyourcode/.theme/theme-prompt.md +``` + +(The HTML templates were copied into the user's project during install — see `scripts/project-install.sh` STEP 7.5. They live at `ownyourcode/templates/html/` relative to the project root.) + +#### Step 5: Generate `theme.css` + +**If `plugin_available = true`:** + +Invoke the `frontend-design` skill with the contents of `theme-prompt.md` as input. Constrain output to CSS only: + +> "Generate a single CSS file matching this design prompt. Style only the semantic classes used by OwnYourCode HTML templates (refer to `core/templates/html/theme-fallback.css` for the complete selector list). Do NOT generate HTML, JS, or any other files. Honor `prefers-color-scheme` if the prompt mentions dark mode." + +Write the output to `ownyourcode/.theme/theme.css`. + +**If `plugin_available = false`:** + +```bash +cp ownyourcode/templates/html/theme-fallback.css \ + ownyourcode/.theme/theme.css +``` + +#### Step 6: Update manifest + +Record in `.claude/ownyourcode-manifest.json`: + +```json +{ + "theme": { + "fallback_mode": false, + "last_updated": "[ISO timestamp]", + "prompt_source": "default" + } +} +``` + +(`fallback_mode: true` if plugin unavailable; `prompt_source: "default"` for the bundled prompt, `"custom"` after the user runs `/own:theme`.) + +#### Step 7: Inform the user + +``` +🎨 Theme set up: ownyourcode/.theme/ + ├── theme-prompt.md (default — change with /own:theme) + └── theme.css ([generated by frontend-design | from fallback]) + +All HTML files generated by /own:feature will use this theme. +``` + +Continue silently to Phase 1. --- From 2b3aaf268a11198b958fd4c56cbb7100e0f7a337 Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:46:03 +0300 Subject: [PATCH 04/13] chore(install): copy HTML templates to user projects during install Extend both the POSIX (bash) and Windows (PowerShell) install scripts with a STEP 7.5 that propagates the v2.4.0 HTML template bundle from the OwnYourCode source repo into each user's installed project. The new step runs between the existing guides copy (STEP 7) and the product-templates heredoc generation (STEP 8), preserving the established ordering convention. Templates land at ownyourcode/templates/html/ inside the user's project so commands like /own:init Phase 0.5, /own:feature, and /own:theme can resolve them via relative project-root paths instead of needing a separately-discovered install location. Both glob copies are made safe on older source repos: missing files or directories are silently skipped (POSIX uses 2>/dev/null || true; PowerShell uses Test-Path guards). Existing installations that upgrade by re-running the installer get the new templates added without overwriting anything they already have. Refs #9 Co-Authored-By: Claude Sonnet 4.6 --- scripts/project-install.ps1 | 23 +++++++++++++++++++++++ scripts/project-install.sh | 14 ++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/scripts/project-install.ps1 b/scripts/project-install.ps1 index 1138aad..119abd2 100644 --- a/scripts/project-install.ps1 +++ b/scripts/project-install.ps1 @@ -283,6 +283,29 @@ if (Test-Path $srcGuides) { Write-Info "No guides to copy" } +# ============================================================================ +# STEP 7.5: Copy HTML templates (v2.4.0+) +# ============================================================================ +# These templates power the HTML-canonical SDD workflow. They are read at +# runtime by /own:init (Phase 0.5), /own:feature, and /own:theme. +# Safe on older source repos: missing templates are silently skipped. + +Write-Info "Copying HTML templates..." + +$srcHtml = Join-Path $BASE_DIR "core/templates/html" +$destHtml = Join-Path $PROJECT_DIR "ownyourcode/templates/html" + +if (Test-Path $srcHtml) { + New-Item -ItemType Directory -Force -Path $destHtml | Out-Null + $htmlFiles = Get-ChildItem -Path $srcHtml -Include "*.template","*.css" -Recurse -ErrorAction SilentlyContinue + foreach ($file in $htmlFiles) { + Copy-Item $file.FullName -Destination $destHtml -Force + } + Write-OK "HTML templates copied" +} else { + Write-Info "No HTML templates to copy (older source repo)" +} + # ============================================================================ # STEP 8: Create product templates # ============================================================================ diff --git a/scripts/project-install.sh b/scripts/project-install.sh index 522b34b..c126f9d 100755 --- a/scripts/project-install.sh +++ b/scripts/project-install.sh @@ -251,6 +251,20 @@ info "Copying guides..." cp "$BASE_DIR/guides/"*.md "$PROJECT_DIR/ownyourcode/guides/" 2>/dev/null || true success "Guides copied" +# ============================================================================ +# STEP 7.5: Copy HTML templates (v2.4.0+) +# ============================================================================ +# These templates power the HTML-canonical SDD workflow. They are read at +# runtime by /own:init (Phase 0.5), /own:feature, and /own:theme. +# Safe on older source repos: missing templates are silently skipped. + +info "Copying HTML templates..." + +mkdir -p "$PROJECT_DIR/ownyourcode/templates/html" +cp "$BASE_DIR/core/templates/html/"*.template "$PROJECT_DIR/ownyourcode/templates/html/" 2>/dev/null || true +cp "$BASE_DIR/core/templates/html/"*.css "$PROJECT_DIR/ownyourcode/templates/html/" 2>/dev/null || true +success "HTML templates copied" + # ============================================================================ # STEP 8: Create product templates # ============================================================================ From 8835af722e7c1eaae0e21336ef0a5d5b429b8793 Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:52:10 +0300 Subject: [PATCH 05/13] docs: add v2.4.0 PR 1 changelog entry and /own:theme to README command table Pre-emptively address the documentation sync gap before the reviewer finds it. Document the v2.4.0 PR 1 scope explicitly so future readers of the changelog understand the foundation-only nature of this PR and the four subsequent PRs that will activate HTML output, mutation contracts, and the migration command. CHANGELOG additions land in [Unreleased] under a dedicated v2.4.0 sub-heading rather than under Repository Infrastructure, because this is a product-surface change (templates, command, init phase) rather than internal tooling. README's slash-command table now lists /own:theme between /own:profile and /own:test, tagged with the v2.4.0+ availability marker so users who land on the README without context can see at a glance that this command requires a later release. Refs #9, #10 Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 9 +++++++++ README.md | 1 + 2 files changed, 10 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6691dc0..acf1368 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ All notable changes to OwnYourCode will be documented in this file. ### Added +#### v2.4.0 — HTML SDD Migration (Foundation — PR 1 of 5) +- **HTML Template Bundle:** Six `.html.template` files in `core/templates/html/` defining the semantic structure of the v2.4.0 HTML-canonical SDD workflow (`mission`, `stack`, `roadmap`, `spec`, `design`, `tasks`). Each template encodes a `data-*` mutation contract so Claude's existing `Edit` tool — not an external HTML parser — performs all state mutations and progress counts (Option D design from #9). +- **Default Theme Assets:** `theme-prompt.md.template` shipping an Apple Documentation aesthetic as the default prompt consumed by the `frontend-design` plugin, plus a hand-authored `theme-fallback.css` covering every semantic class and `data-*` selector for users without the plugin. Light + dark mode parity via `prefers-color-scheme`. +- **`/own:theme` Command:** New slash command for managing the visual styling of HTML SDD files. Four user actions (change prompt / pick preset / regenerate / view) plus `/own:theme --revert` for restoring any timestamped backup. Every write is backup-first via `ownyourcode/.theme/.history/[ISO-timestamp]/`. +- **`/own:init` Phase 0.5:** New idempotent phase inserted between the MCP Check and Detection phases that detects the `frontend-design` plugin, offers auto-install with explicit user permission, seeds `ownyourcode/.theme/`, and generates the project's initial `theme.css`. Soft-dependency model — declining the install falls back to bundled CSS, never blocks. +- **Install Script Updates:** New STEP 7.5 in both `project-install.sh` and `project-install.ps1` copies the HTML template bundle from the OwnYourCode source repo to `ownyourcode/templates/html/` inside each user's project. + +> Note: PR 1 ships **infrastructure only**. `/own:init` Phase 6 and `/own:feature` still write Markdown until PR 2 and PR 3 activate HTML output. Existing projects see zero behavior change. + #### Repository Infrastructure - **Claude PR Review Gate:** Every PR targeting `main` is now automatically reviewed by Claude against the OwnYourCode standards (P/S/T/X/D rule set across Philosophy, Structure, Tooling, Security, and Documentation), the 4 Protocols, and the universal-audience product mission. The reviewer's system prompt lives in `.github/CLAUDE_REVIEWER.md` and is isolated from the workflow YAML for fast iteration. Reviewer enforces an explicit `VERDICT:` contract (`APPROVE` / `REQUEST_CHANGES` / `COMMENT`) so branch protection can gate merges on the verdict. - **`@claude` Tag Responder:** Any write-access user can now mention `@claude` in a PR/issue comment, an inline review comment, or a formal PR review to summon Claude for in-thread Q&A with full context (latest PR diff, full comment thread, PR/issue description). Complementary to the auto-review gate — different concern, different workflow file (`.github/workflows/claude-tag.yml`), no system prompt (uses the action's default conversational tag mode). Tool surface is read-and-comment only (no `Edit`/`Write`/shell-wildcards) and the trigger is gated by the action's built-in write-access check. diff --git a/README.md b/README.md index 5b7c691..8e900d2 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,7 @@ Learnings compound across projects. Patterns that worked. Mistakes you won't rep | -------------- | ---------------------------------- | | `/own:status` | Check progress, tasks, and career stats | | `/own:profile` | View or change your profile | +| `/own:theme` | Manage HTML theme styling (v2.4.0+) | | `/own:test` | Guide through writing tests | | `/own:docs` | Guide through writing documentation | From 2dc45f2eeb6a52fc513e9044bac350d74a6b3d96 Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:54:36 +0300 Subject: [PATCH 06/13] fix(own:init): correct plugin install from shell command to /plugin slash command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #10 review caught a real correctness bug in Phase 0.5 Step 3: the "Yes, install it" branch invoked `claude plugin install ...` as a shell command, but Claude Code's plugin marketplace install is a slash command (`/plugin install`). The shell form silently fails and downgrades every opt-in user to the bundled fallback CSS, defeating the purpose of the install prompt. Slash commands cannot directly invoke other slash commands from within their flow, so the corrected behavior is to instruct the user to run `/plugin install frontend-design@claude-plugins-official` themselves, then re-run `/own:init`. The re-run hits Step 2's plugin detection, finds the now-installed plugin, and skips the install prompt entirely — clean idempotent handoff. Surfacing the slash-command invocation also gives the user explicit visibility into what's being installed, which fits OwnYourCode's evidence-based-engineering principle better than a hidden shell exec. Addresses MAJOR finding (P3/S4) on PR #10. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/own/init.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/.claude/commands/own/init.md b/.claude/commands/own/init.md index 03256fd..9edcca5 100644 --- a/.claude/commands/own/init.md +++ b/.claude/commands/own/init.md @@ -775,13 +775,19 @@ Options: **If "Yes":** -```bash -# Use Claude Code's plugin install mechanism. -# Note: this may require user-side confirmation; surface any output. -claude plugin install frontend-design@claude-plugins-official 2>&1 +Plugin installs in Claude Code happen via the **`/plugin install` slash command**, not a shell command. You cannot run `/plugin install` from inside a slash-command flow — the user must invoke it themselves. Tell the user: + +``` +To install the plugin, run this in your Claude Code session: + + /plugin install frontend-design@claude-plugins-official + +Then re-run /own:init to continue setup. ``` -After install, re-check availability. If install succeeded, set `plugin_available = true`. +**STOP execution.** When the user re-runs `/own:init`, the plugin detection in Step 2 will succeed and the install prompt will not re-appear. + +(Rationale: a slash command cannot invoke another slash command directly. The handoff is intentional — it gives the user explicit consent and visibility into what's being installed.) **If "Skip" (or install failed):** From 960dec3a52f1275772aca82228eb5b2b384e2646 Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:54:47 +0300 Subject: [PATCH 07/13] fix(own:theme): soften /own:migrate forward reference + cross-platform preview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two minor review findings addressed in a single touch on theme.md: 1. The Phase 1 pre-flight error message that fires when ownyourcode/.theme/ is missing previously told the user to "run /own:migrate first" — but /own:migrate ships in PR 5 and does not exist when PR 1 lands alone. The message now explains both paths honestly: new v2.4.0+ projects should run /own:init; existing Markdown projects acknowledge that /own:migrate is forthcoming and offer a manual workaround in the meantime. Users reading the message during the PR-1-only window get accurate guidance instead of a dead-end command name. 2. The Phase 7 preview action previously hardcoded macOS's `open` with a comment promising cross-platform support but no actual branching. Linux and Windows users hit a silent no-op. The corrected flow detects the platform via `uname -s` and dispatches to `open` on macOS, `xdg-open` on Linux, and `start` on Cygwin/MSYS/MinGW. A PowerShell-equivalent `Start-Process` snippet is documented for PowerShell sessions where `uname` is absent. If no opener is available, the file path is surfaced so the user can open it manually rather than nothing happening. Addresses MINOR findings S4 and T1 on PR #10. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/own/theme.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/.claude/commands/own/theme.md b/.claude/commands/own/theme.md index 7a61972..70d1cae 100644 --- a/.claude/commands/own/theme.md +++ b/.claude/commands/own/theme.md @@ -51,8 +51,11 @@ Check if the user invoked with `--revert`: Run these checks silently: 1. **Verify install:** `ownyourcode/.theme/` directory exists. - - If not, this project isn't yet on v2.4.0+ HTML mode. Tell the user: - > "Your project is still using Markdown SDD files. To use themed HTML output, run `/own:migrate` first." + - If not, this project doesn't have a theme set up yet. Tell the user: + > "Your project doesn't have an HTML theme configured. + > + > - If this is a new project on v2.4.0+, run `/own:init` to set up the theme. + > - If you have an existing Markdown project to convert, `/own:migrate` will land in a future v2.4.0 PR — until then, you can manually create `ownyourcode/.theme/` by running `/own:init` in a clean copy." - **STOP execution.** 2. **Read current state:** Read `ownyourcode/.theme/theme-prompt.md` (first 8 lines for preview). @@ -234,12 +237,26 @@ Options: 2. No — I'll check it later ``` -If yes: +If yes, open the file using the platform-appropriate command. Detect the OS and branch: + ```bash -open ownyourcode/product/mission.html # macOS -# (cross-platform: xdg-open on Linux, start on Windows) +# Detect platform and open mission.html in the default browser. +case "$(uname -s)" in + Darwin*) open ownyourcode/product/mission.html ;; + Linux*) xdg-open ownyourcode/product/mission.html ;; + CYGWIN*|MINGW*|MSYS*) start ownyourcode/product/mission.html ;; + *) echo "Open this file manually: ownyourcode/product/mission.html" ;; +esac ``` +On Windows PowerShell sessions (where `uname` may be absent), use: + +```powershell +Start-Process "ownyourcode/product/mission.html" +``` + +If no preview tool is available on the host, surface the path so the user can open it themselves rather than silently no-op. + Update manifest: `theme.last_updated = [ISO timestamp]`. **END.** From 08cc6be4032bfb46dfc8f524b2f5232b43d7c50d Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:54:58 +0300 Subject: [PATCH 08/13] fix(install): make HTML template copy recursive in .sh for cross-shell parity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The PowerShell variant of STEP 7.5 was already using -Recurse to copy the HTML template bundle, so it would automatically pick up any subdirectory that lands later (e.g., a planned presets/ folder for bundled theme presets). The bash variant only globbed *.template and *.css at the top level, which would silently skip future subdirectories — a real parity gap waiting to bite the moment presets/ ships. The fixed bash version uses `cp -R "$SRC/." "$DEST/"` to recursively copy the entire html/ directory contents, mirroring the PowerShell semantics exactly. The trailing `/.` ensures contents are copied (not the directory itself), keeping the destination flat the way the PowerShell version produces it. A guard checks for the source directory's existence first so older OwnYourCode source repos (where the templates don't yet exist) still install cleanly. Addresses MINOR finding T1 on PR #10. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- scripts/project-install.sh | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/scripts/project-install.sh b/scripts/project-install.sh index c126f9d..d2cc220 100755 --- a/scripts/project-install.sh +++ b/scripts/project-install.sh @@ -261,9 +261,14 @@ success "Guides copied" info "Copying HTML templates..." mkdir -p "$PROJECT_DIR/ownyourcode/templates/html" -cp "$BASE_DIR/core/templates/html/"*.template "$PROJECT_DIR/ownyourcode/templates/html/" 2>/dev/null || true -cp "$BASE_DIR/core/templates/html/"*.css "$PROJECT_DIR/ownyourcode/templates/html/" 2>/dev/null || true -success "HTML templates copied" +# Recursive so future subdirectories (e.g., presets/) are copied automatically. +# Mirrors the -Recurse semantics of the PowerShell variant for cross-platform parity. +if [ -d "$BASE_DIR/core/templates/html" ]; then + cp -R "$BASE_DIR/core/templates/html/." "$PROJECT_DIR/ownyourcode/templates/html/" 2>/dev/null || true + success "HTML templates copied" +else + info "No HTML templates to copy (older source repo)" +fi # ============================================================================ # STEP 8: Create product templates From ab01c750a1f23ef841ffaa673134dd7884fd04ca Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 14:55:03 +0300 Subject: [PATCH 09/13] fix(templates): remove leaked TODO(daniel) note from default theme prompt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The default theme prompt previously embedded a TODO(daniel) note as a Markdown comment immediately after the H1 heading. The note was intended as an editor-time reminder for the project author but was inside the file content itself, so it would ship into every user's ownyourcode/.theme/theme-prompt.md on install — visible whenever they opened the file to edit their theme, even though the personal addressing applies only to the upstream repo. Removing the lines entirely. The HTML comment block at the top of the file (explaining how the prompt is consumed) is unchanged — that guidance is genuinely useful for users editing their own theme. Addresses MINOR finding D4/T2 on PR #10. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- core/templates/html/theme-prompt.md.template | 4 ---- 1 file changed, 4 deletions(-) diff --git a/core/templates/html/theme-prompt.md.template b/core/templates/html/theme-prompt.md.template index 4dc3ab4..396abdb 100644 --- a/core/templates/html/theme-prompt.md.template +++ b/core/templates/html/theme-prompt.md.template @@ -24,10 +24,6 @@ # Default OwnYourCode Theme — "Apple Documentation" -# TODO(daniel): Review this draft. Rewrite in your own voice if it doesn't match -# your vision for OwnYourCode's default aesthetic. The taste here defines what -# every user sees on first /own:init. - Generate a premium, calm, technical-document aesthetic inspired by Apple Developer Documentation (developer.apple.com). From 2417cc3ca479b72d46b1d0c811a54afb9b6e7b3d Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 15:10:39 +0300 Subject: [PATCH 10/13] fix(own:init): pause-and-resume plugin install flow without restarting Phase 0.5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous fix correctly switched the plugin install invocation from a shell command to the /plugin install slash command, but it forced every opt-in user to STOP /own:init and re-run from Phase -1, throwing away their already-completed profile selection, MCP check, and any other in-flight progress. Real correctness, real UX regression. The corrected design uses two AskUserQuestion calls to hold the slash command's flow in place while the user runs /plugin install in a separate message. The first AskUserQuestion asks whether to install at all; the second is the actual pause — it stays open while the user types the install command elsewhere in the conversation, and resumes Phase 0.5 from exactly the point it paused when they pick "Done." After the user reports "Done," Phase 0.5 re-runs the plugin detection silently. On success, it continues to Step 4 (.theme/ creation) with plugin_available = true. On failure (install didn't register, command mistyped, plugin cache not refreshed), it loops up to two retries before forcing the skip path so no user ever ends up stuck. The "Cancel — use fallback" branch at every prompt level preserves the soft-dependency contract: every user keeps all their progress and ends up with a working theme regardless of whether the plugin lands. Why this works: AskUserQuestion in Claude Code holds the conversation turn open until the user answers. Other slash commands invoked in between (like /plugin install) don't destroy the parent command's context — when the user picks an option, the original /own:init flow resumes where it paused. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/own/init.md | 53 ++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/.claude/commands/own/init.md b/.claude/commands/own/init.md index 9edcca5..3068711 100644 --- a/.claude/commands/own/init.md +++ b/.claude/commands/own/init.md @@ -775,19 +775,62 @@ Options: **If "Yes":** -Plugin installs in Claude Code happen via the **`/plugin install` slash command**, not a shell command. You cannot run `/plugin install` from inside a slash-command flow — the user must invoke it themselves. Tell the user: +Plugin installs in Claude Code happen via the **`/plugin install` slash command**, not a shell command, and slash commands cannot directly invoke other slash commands. The user must type the install command themselves — but `/own:init` does NOT have to restart. Instead, pause via a second `AskUserQuestion` and resume when the user confirms. + +Tell the user (plain message, then immediately use AskUserQuestion): ``` -To install the plugin, run this in your Claude Code session: +Got it. In a separate message, run: /plugin install frontend-design@claude-plugins-official -Then re-run /own:init to continue setup. +I'll wait here. When the install finishes, come back to this message +and pick the appropriate option below. +``` + +Then use AskUserQuestion (this is the "pause"): + +``` +Question: "Plugin install status?" + +Options: +1. Done — I installed the plugin, continue +2. Install failed or canceled — use fallback CSS instead +``` + +**If "Done":** + +Re-run the detection from Step 2: + +```bash +ls ~/.claude/plugins/cache/claude-plugins-official/frontend-design 2>/dev/null ``` -**STOP execution.** When the user re-runs `/own:init`, the plugin detection in Step 2 will succeed and the install prompt will not re-appear. +- **Detection succeeds:** Set `plugin_available = true`. Continue to Step 4. The user keeps all the profile / MCP work they already did. +- **Detection fails:** The install didn't register (most commonly because the user hit a permission prompt and dismissed it, or typed the command wrong). Tell the user: + ``` + I can't see the plugin yet. This usually means: + - The install needed confirmation that wasn't accepted, OR + - The command name had a typo, OR + - Claude Code's plugin cache hasn't refreshed yet (try once more). + + What do you want to do? + ``` + + Use AskUserQuestion again: + ``` + Options: + 1. Try installing again — I'll re-check after + 2. Skip and use fallback CSS instead + ``` + + Loop on "try again" up to 2 retries (3 total attempts). After 3 failed checks, force the skip path to avoid an infinite loop. + +**If "Install failed or canceled":** + +Set `plugin_available = false`. Note `theme.fallback_mode = true` in the manifest. Continue to Step 4 — the user keeps all their progress and the fallback CSS will be used. -(Rationale: a slash command cannot invoke another slash command directly. The handoff is intentional — it gives the user explicit consent and visibility into what's being installed.) +(Rationale: `AskUserQuestion` holds the slash-command flow in place. The user types `/plugin install ...` in a separate message between the prompt and their answer, and `/own:init` resumes from the pause when they pick an option. No restart, no work lost.) **If "Skip" (or install failed):** From 827c1995cf8ccce7fc17494aa292e300545aa854 Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 16:34:24 +0300 Subject: [PATCH 11/13] fix(own:init): force Phase 0.5 to actually run bash detection commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Manual /own:init runtime testing in /tmp/owntest-pr1 surfaced a real correctness bug that no static review caught. When the user uninstalled the frontend-design plugin to exercise the install prompt, Phase 0.5 silently bypassed Step 3 entirely and went straight to creating the .theme/ directory with fallback CSS — while telling the user "plugin is available so I'll use it for premium styling." The user- facing claim and the manifest's fallback_mode: true value disagreed about the same runtime fact, and the install prompt the user actually wanted to test never appeared. Root cause was instruction ambiguity in our own prompt: "Run silently:" above the plugin detection bash command was interpreted as "skip running the command" rather than "do not narrate the command." Without the actual bash output, the implementing agent fell back to assuming the plugin existed (which happened to be the most common case), then correctly used fallback CSS in Step 5 once it discovered there was no real signal — but never reconciled the contradictory message it had already shown the user. Fixed by adding an EXECUTION CONTRACT block at the top of Phase 0.5 that establishes two non-negotiable rules: (1) every bash command in the phase MUST be executed via the Bash tool, with branching decisions driven by the literal stdout, and (2) any user-facing message about plugin availability MUST match the manifest's fallback_mode value — the two cannot disagree. Step 1 and Step 2 are rewritten with imperative "Execute this bash command via the Bash tool" headers and explicit "do NOT assume" guidance. Step 2's bash command now produces an unambiguous "plugin:found" / "plugin:missing" marker via `&& echo / || echo` so the decision input is text-deterministic rather than empty-string-versus-something. This is the same category of bug as the prior MAJOR finding on the shell-vs-slash plugin install — a P3 (Evidence-Based Engineering) slip where the spec made a confident claim that wasn't backed by an executed verification. Found by Daniel's own runtime test rather than the static reviewer, which is exactly what runtime tests exist for. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/own/init.md | 41 ++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/.claude/commands/own/init.md b/.claude/commands/own/init.md index 3068711..75bcdff 100644 --- a/.claude/commands/own/init.md +++ b/.claude/commands/own/init.md @@ -739,25 +739,54 @@ To install (takes 30 seconds each): Set up the visual theme that all generated HTML files will use. This phase runs ONCE per project (idempotent: detects existing `.theme/` and skips). +**🚨 EXECUTION CONTRACT (read before proceeding):** + +Every bash command in this phase **MUST be executed** via the Bash tool. The +detection results are required inputs to the branching decisions below — they +cannot be assumed, inferred from context, or skipped. "Run silently" elsewhere +in OwnYourCode means *do not narrate the command to the user* — it does NOT +mean *skip the command*. + +Any user-facing message you produce (especially around plugin availability +and `fallback_mode`) **MUST reflect the actual bash detection result**, not an +assumption. The manifest's `theme.fallback_mode` value and the message you +show the user MUST agree — if one says "fallback," the other cannot say +"premium styling." + #### Step 1: Detect existing theme +**Execute this bash command via the Bash tool:** + ```bash test -d ownyourcode/.theme && echo "exists" || echo "missing" ``` -- **Exists:** Skip the entire Phase 0.5. Continue to Phase 1. -- **Missing:** Continue to Step 2. +**Decide based on the literal stdout of the command above:** + +- Output is `exists` → Skip the entire Phase 0.5. Continue to Phase 1. +- Output is `missing` → Continue to Step 2. + +Do NOT assume the directory's state. Run the command, read the output, branch. #### Step 2: Check frontend-design plugin -Run silently: +**Execute this bash command via the Bash tool. The output determines +`plugin_available` — there is no alternative source of truth:** ```bash -ls ~/.claude/plugins/cache/claude-plugins-official/frontend-design 2>/dev/null +ls ~/.claude/plugins/cache/claude-plugins-official/frontend-design 2>/dev/null && echo "plugin:found" || echo "plugin:missing" ``` -- **Found:** Set `plugin_available = true`. Skip Step 3. -- **Not found:** Continue to Step 3. +**Decide based on the literal stdout:** + +- Output contains `plugin:found` → Set `plugin_available = true`. Skip Step 3, continue to Step 4. +- Output is exactly `plugin:missing` (no `plugin:found` line) → Set `plugin_available = false`. Continue to Step 3. + +Do NOT assume the plugin is installed. Do NOT skip the bash command. The user +may have explicitly uninstalled the plugin to test the install flow, and +assuming "probably installed" would silently bypass Step 3 (the install prompt). +The `&& echo "plugin:found" || echo "plugin:missing"` pattern produces an +unambiguous marker so the decision is reliable. #### Step 3: Offer to install the plugin From 8da392d703fafb91813fec40419b7b20b5f95e89 Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 16:46:08 +0300 Subject: [PATCH 12/13] =?UTF-8?q?refactor(own:init):=20simplify=20Phase=20?= =?UTF-8?q?0.5=20=E2=80=94=20drop=20plugin=20detection,=20always=20seed=20?= =?UTF-8?q?fallback?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two consecutive rounds of runtime testing in /tmp/owntest-pr1 demonstrated that the original Phase 0.5 design — programmatically detect the frontend-design plugin, optionally pause-and-resume for an install handoff, then invoke the plugin as a Skill mid-flow to generate theme.css — is not reliably deliverable inside a Claude Code slash command. Three failure modes converged: 1. Stale cache directories from prior /plugin uninstall left the check command returning "directory exists" even when the plugin was effectively gone. Tightening the bash check to use && echo "plugin:found" markers didn't help because the cache dir genuinely existed. 2. The implementing agent repeatedly skipped the plugin-detection bash command despite explicit EXECUTION CONTRACT instructions to run it, defaulting to "plugin probably available" assumptions. Even the second round of hardening (Step 2 explicitly imperative, "do NOT assume" warnings, deterministic markers) did not produce the desired execution behavior. 3. The agent's own narration in the test runs reported the plugin could not be invoked as a Skill mid-flow at all, which makes Step 5's "Invoke the frontend-design skill" instruction architecturally undeliverable from inside this slash command — regardless of whether the plugin is installed. Rather than continue layering reliability fixes on a fundamentally fragile mid-flow integration, this commit removes the entire plugin detection / install / skill-invocation path and replaces it with a deterministic "always seed the bundled fallback CSS" design. The fallback CSS was already independently praised by the PR reviewer as "real engineering taste — token-driven, full light/dark parity, covers every semantic class," so making it the universal default rather than a degradation path is honest about what we can actually ship. Phase 0.5 went from 7 steps and ~190 lines to 4 steps and ~80 lines. The user-facing summary now ends with a prominent, opt-in upgrade hint that explains how to install the plugin manually and how /own:theme regenerates theme.css. This shifts the plugin from "automatic mid-flow dependency we try to install for you" to "optional polish the user opts into when they want it" — and stops the slash-command flow from making confident claims it cannot back up. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/own/init.md | 189 ++++++++--------------------------- 1 file changed, 42 insertions(+), 147 deletions(-) diff --git a/.claude/commands/own/init.md b/.claude/commands/own/init.md index 75bcdff..1979f67 100644 --- a/.claude/commands/own/init.md +++ b/.claude/commands/own/init.md @@ -739,188 +739,83 @@ To install (takes 30 seconds each): Set up the visual theme that all generated HTML files will use. This phase runs ONCE per project (idempotent: detects existing `.theme/` and skips). -**🚨 EXECUTION CONTRACT (read before proceeding):** - -Every bash command in this phase **MUST be executed** via the Bash tool. The -detection results are required inputs to the branching decisions below — they -cannot be assumed, inferred from context, or skipped. "Run silently" elsewhere -in OwnYourCode means *do not narrate the command to the user* — it does NOT -mean *skip the command*. - -Any user-facing message you produce (especially around plugin availability -and `fallback_mode`) **MUST reflect the actual bash detection result**, not an -assumption. The manifest's `theme.fallback_mode` value and the message you -show the user MUST agree — if one says "fallback," the other cannot say -"premium styling." +**Design note:** This phase deliberately does NOT check for or attempt to +install the `frontend-design` plugin. Runtime testing during PR 1 demonstrated +that programmatic plugin detection inside a slash-command flow is unreliable +(stale cache directories from previous uninstalls, agent assumptions, no +in-flow Skill invocation). Instead, this phase always seeds the bundled +fallback CSS — which the PR reviewer praised as production-quality — and +surfaces an optional upgrade path in the user-facing summary. Users who +want premium styling install the plugin themselves and run `/own:theme` +to regenerate. #### Step 1: Detect existing theme -**Execute this bash command via the Bash tool:** +**Execute this bash command via the Bash tool. Decide based on the literal stdout:** ```bash test -d ownyourcode/.theme && echo "exists" || echo "missing" ``` -**Decide based on the literal stdout of the command above:** - - Output is `exists` → Skip the entire Phase 0.5. Continue to Phase 1. - Output is `missing` → Continue to Step 2. -Do NOT assume the directory's state. Run the command, read the output, branch. - -#### Step 2: Check frontend-design plugin - -**Execute this bash command via the Bash tool. The output determines -`plugin_available` — there is no alternative source of truth:** - -```bash -ls ~/.claude/plugins/cache/claude-plugins-official/frontend-design 2>/dev/null && echo "plugin:found" || echo "plugin:missing" -``` - -**Decide based on the literal stdout:** - -- Output contains `plugin:found` → Set `plugin_available = true`. Skip Step 3, continue to Step 4. -- Output is exactly `plugin:missing` (no `plugin:found` line) → Set `plugin_available = false`. Continue to Step 3. - -Do NOT assume the plugin is installed. Do NOT skip the bash command. The user -may have explicitly uninstalled the plugin to test the install flow, and -assuming "probably installed" would silently bypass Step 3 (the install prompt). -The `&& echo "plugin:found" || echo "plugin:missing"` pattern produces an -unambiguous marker so the decision is reliable. - -#### Step 3: Offer to install the plugin - -Use AskUserQuestion: - -``` -Question: "OwnYourCode uses Anthropic's frontend-design plugin to generate - premium HTML styling for your spec files. Want me to install it? - (Free, official Anthropic plugin, takes ~5 seconds.)" - -Options: -1. Yes, install it — Best output quality, recommended -2. Skip — Use the bundled fallback styling instead -``` - -**If "Yes":** - -Plugin installs in Claude Code happen via the **`/plugin install` slash command**, not a shell command, and slash commands cannot directly invoke other slash commands. The user must type the install command themselves — but `/own:init` does NOT have to restart. Instead, pause via a second `AskUserQuestion` and resume when the user confirms. - -Tell the user (plain message, then immediately use AskUserQuestion): - -``` -Got it. In a separate message, run: - - /plugin install frontend-design@claude-plugins-official - -I'll wait here. When the install finishes, come back to this message -and pick the appropriate option below. -``` - -Then use AskUserQuestion (this is the "pause"): - -``` -Question: "Plugin install status?" - -Options: -1. Done — I installed the plugin, continue -2. Install failed or canceled — use fallback CSS instead -``` - -**If "Done":** +#### Step 2: Create `.theme/` directory and seed files from the bundle -Re-run the detection from Step 2: - -```bash -ls ~/.claude/plugins/cache/claude-plugins-official/frontend-design 2>/dev/null -``` - -- **Detection succeeds:** Set `plugin_available = true`. Continue to Step 4. The user keeps all the profile / MCP work they already did. -- **Detection fails:** The install didn't register (most commonly because the user hit a permission prompt and dismissed it, or typed the command wrong). Tell the user: - ``` - I can't see the plugin yet. This usually means: - - The install needed confirmation that wasn't accepted, OR - - The command name had a typo, OR - - Claude Code's plugin cache hasn't refreshed yet (try once more). - - What do you want to do? - ``` - - Use AskUserQuestion again: - ``` - Options: - 1. Try installing again — I'll re-check after - 2. Skip and use fallback CSS instead - ``` - - Loop on "try again" up to 2 retries (3 total attempts). After 3 failed checks, force the skip path to avoid an infinite loop. - -**If "Install failed or canceled":** - -Set `plugin_available = false`. Note `theme.fallback_mode = true` in the manifest. Continue to Step 4 — the user keeps all their progress and the fallback CSS will be used. - -(Rationale: `AskUserQuestion` holds the slash-command flow in place. The user types `/plugin install ...` in a separate message between the prompt and their answer, and `/own:init` resumes from the pause when they pick an option. No restart, no work lost.) - -**If "Skip" (or install failed):** - -Set `plugin_available = false`. Note this in the manifest as `theme.fallback_mode = true`. Continue without error — the fallback CSS will be used. - -#### Step 4: Create the `.theme/` directory and seed files +Execute these bash commands via the Bash tool: ```bash mkdir -p ownyourcode/.theme/.history -``` - -Copy the default theme prompt from the install: - -```bash -cp ownyourcode/templates/html/theme-prompt.md.template \ - ownyourcode/.theme/theme-prompt.md +cp ownyourcode/templates/html/theme-prompt.md.template ownyourcode/.theme/theme-prompt.md +cp ownyourcode/templates/html/theme-fallback.css ownyourcode/.theme/theme.css ``` (The HTML templates were copied into the user's project during install — see `scripts/project-install.sh` STEP 7.5. They live at `ownyourcode/templates/html/` relative to the project root.) -#### Step 5: Generate `theme.css` - -**If `plugin_available = true`:** - -Invoke the `frontend-design` skill with the contents of `theme-prompt.md` as input. Constrain output to CSS only: - -> "Generate a single CSS file matching this design prompt. Style only the semantic classes used by OwnYourCode HTML templates (refer to `core/templates/html/theme-fallback.css` for the complete selector list). Do NOT generate HTML, JS, or any other files. Honor `prefers-color-scheme` if the prompt mentions dark mode." - -Write the output to `ownyourcode/.theme/theme.css`. - -**If `plugin_available = false`:** - -```bash -cp ownyourcode/templates/html/theme-fallback.css \ - ownyourcode/.theme/theme.css -``` +#### Step 3: Update manifest -#### Step 6: Update manifest - -Record in `.claude/ownyourcode-manifest.json`: +Add this block to `.claude/ownyourcode-manifest.json`: ```json { "theme": { - "fallback_mode": false, + "fallback_mode": true, "last_updated": "[ISO timestamp]", "prompt_source": "default" } } ``` -(`fallback_mode: true` if plugin unavailable; `prompt_source: "default"` for the bundled prompt, `"custom"` after the user runs `/own:theme`.) +- `fallback_mode` is `true` until the user regenerates `theme.css` via `/own:theme` with the `frontend-design` plugin installed. +- `prompt_source` is `"default"` for the bundled prompt; it becomes `"custom"` if the user supplies their own prompt through `/own:theme`. + +#### Step 4: Inform the user with the optional upgrade hint -#### Step 7: Inform the user +Show this message exactly: ``` 🎨 Theme set up: ownyourcode/.theme/ - ├── theme-prompt.md (default — change with /own:theme) - └── theme.css ([generated by frontend-design | from fallback]) + ├── theme-prompt.md (default Apple Documentation aesthetic) + └── theme.css (bundled fallback CSS — production-quality default) + +All HTML files generated by /own:feature will reference this theme. + +──────────────────────────────────────────────────────────────────── +✨ Make it even better (optional, recommended for portfolio work) +──────────────────────────────────────────────────────────────────── + +OwnYourCode ships with a hand-authored fallback CSS that already looks +great. For *fully custom* styling generated from your theme prompt — with +Anthropic's official design framework — install the `frontend-design` +plugin yourself in a separate message: + + /plugin install frontend-design@claude-plugins-official + +Then run `/own:theme` to regenerate `theme.css` based on your prompt. +You can change the prompt and re-roll the design anytime. -All HTML files generated by /own:feature will use this theme. +Skip this for now if you're just trying things out — the bundled fallback +is ready to use. ``` Continue silently to Phase 1. From cb4c55b174452c692c93f90a7afc38ca0e15f73f Mon Sep 17 00:00:00 2001 From: Daniel Podolsky Date: Thu, 28 May 2026 17:34:00 +0300 Subject: [PATCH 13/13] docs(changelog): sync Phase 0.5 entry to the simplified design shipped in 8da392d MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The [Unreleased] CHANGELOG entry for /own:init Phase 0.5 still described the original design — programmatic plugin detection, autonomous install prompt, and theme.css generation via the frontend-design plugin — none of which actually ship after the 8da392d simplification. Replace that paragraph with an accurate description of the deterministic fallback-first design: Phase 0.5 seeds ownyourcode/.theme/ with the bundled theme prompt and theme-fallback.css unconditionally, then surfaces an opt-in upgrade hint pointing users to /plugin install frontend-design@claude-plugins-official followed by /own:theme. This addresses the D2 finding from the latest CI review pass. Refs #10 Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index acf1368..063a9fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ All notable changes to OwnYourCode will be documented in this file. - **HTML Template Bundle:** Six `.html.template` files in `core/templates/html/` defining the semantic structure of the v2.4.0 HTML-canonical SDD workflow (`mission`, `stack`, `roadmap`, `spec`, `design`, `tasks`). Each template encodes a `data-*` mutation contract so Claude's existing `Edit` tool — not an external HTML parser — performs all state mutations and progress counts (Option D design from #9). - **Default Theme Assets:** `theme-prompt.md.template` shipping an Apple Documentation aesthetic as the default prompt consumed by the `frontend-design` plugin, plus a hand-authored `theme-fallback.css` covering every semantic class and `data-*` selector for users without the plugin. Light + dark mode parity via `prefers-color-scheme`. - **`/own:theme` Command:** New slash command for managing the visual styling of HTML SDD files. Four user actions (change prompt / pick preset / regenerate / view) plus `/own:theme --revert` for restoring any timestamped backup. Every write is backup-first via `ownyourcode/.theme/.history/[ISO-timestamp]/`. -- **`/own:init` Phase 0.5:** New idempotent phase inserted between the MCP Check and Detection phases that detects the `frontend-design` plugin, offers auto-install with explicit user permission, seeds `ownyourcode/.theme/`, and generates the project's initial `theme.css`. Soft-dependency model — declining the install falls back to bundled CSS, never blocks. +- **`/own:init` Phase 0.5:** New idempotent phase inserted between the MCP Check and Detection phases. Seeds `ownyourcode/.theme/` with the bundled theme prompt and `theme-fallback.css` as the project's initial `theme.css`, then surfaces a prominent opt-in upgrade hint pointing users to `/plugin install frontend-design@claude-plugins-official` followed by `/own:theme` for fully custom styling. Phase deliberately does not attempt programmatic plugin detection or auto-install — runtime testing during PR 1 showed those paths are unreliable inside a slash-command flow (stale plugin cache directories, no in-flow Skill invocation). The deterministic fallback-first design ships instead; plugin-generated styling is a user-driven upgrade, not an automatic mid-flow dependency. - **Install Script Updates:** New STEP 7.5 in both `project-install.sh` and `project-install.ps1` copies the HTML template bundle from the OwnYourCode source repo to `ownyourcode/templates/html/` inside each user's project. > Note: PR 1 ships **infrastructure only**. `/own:init` Phase 6 and `/own:feature` still write Markdown until PR 2 and PR 3 activate HTML output. Existing projects see zero behavior change.