@cluesmith/codev 1.5.25 → 1.5.27

package/skeleton/resources/spikes.md

@@ -0,0 +1,118 @@
+# Spikes: De-risking Technical Unknowns
+
+**Spikes are short, focused experiments that validate technical assumptions before full implementation.**
+
+## What is a Spike?
+
+The term comes from Extreme Programming (XP), coined in the late 1990s. The metaphor: a spike is like driving a railroad spike through all layers of a problem to see what's underneath. You're not building the whole foundation - you're just poking through to answer a specific question.
+
+**Key characteristics:**
+- **Time-boxed** - Typically 1-2 hours; check in if taking longer
+- **Throwaway** - The code is discarded; only the knowledge is kept
+- **Focused** - Answers ONE specific question
+- **Reduces risk** - Done before committing to full implementation
+
+| Type | Question |
+|------|----------|
+| Spike | "Can we?" / "Does it work?" |
+| Implementation | "Build it" |
+
+## Time-Boxing
+
+**Spikes should typically take 1-2 hours.** If you're spending significantly longer, consider:
+
+1. **Is the question too big?** Break it into smaller spikes
+2. **Is the answer "not easily"?** That's valuable information - document it
+3. **Do you need more time?** That's fine, but check in with the user first
+
+Time-boxing helps prevent spikes from becoming open-ended research. The goal is a quick answer, not perfection.
+
+## When to Use Spikes
+
+Use spikes when a spec has:
+- **Untested external APIs** - Will the API actually behave as documented?
+- **Architectural uncertainty** - Will this pattern work for our use case?
+- **Integration questions** - Can these components work together?
+- **Performance unknowns** - Will this approach be fast enough?
+
+**Rule of thumb:** If the spec says "we believe X will work" or "according to docs, Y should happen" - that's a spike candidate.
+
+## Spike Structure
+
+Store spikes in `codev/spikes/{spec-number}/`:
+
+```
+codev/spikes/
+└── 0062/
+    ├── spike-api-behavior.ts
+    ├── spike-event-handoff.ts
+    └── spike-storage-roundtrip.ts
+```
+
+Each spike file should:
+
+```typescript
+/**
+ * Spike: [Clear Name]
+ *
+ * Purpose: [What assumption are we validating?]
+ * Time Box: 1-2 hours
+ *
+ * Tests:
+ * 1. [Specific test case]
+ * 2. [Another test case]
+ * 3. [Edge case]
+ *
+ * Run with: npx tsx codev/spikes/0062/spike-name.ts
+ */
+
+// Self-contained, runnable code that validates the assumption
+// Mock/simulate infrastructure where needed
+// Print clear PASS/FAIL for each test
+```
+
+## Spike Workflow
+
+1. **Identify unknowns** during Plan phase - what could break our assumptions?
+2. **Create spikes** for each high-risk unknown (1-2 hours each)
+3. **Run spikes** and document results in spec/plan
+4. **Adjust plan** based on spike findings
+5. **Include spike results** in spec as "Research Findings"
+
+## Example Spike Questions
+
+| Unknown | Spike Purpose |
+|---------|---------------|
+| "Gemini 3 requires thought signatures" | Validate signature storage and replay works |
+| "Two Inngest functions can hand off" | Test event emission and separate invocation |
+| "Frontend handles sequence gaps" | Simulate gap and verify realignment |
+| "Raw payload survives database round-trip" | Store and reconstruct exact API format |
+
+## Spike vs Prototype vs POC
+
+| Type | Scope | Output | Kept? | Time |
+|------|-------|--------|-------|------|
+| **Spike** | Single question | PASS/FAIL + learnings | No (throwaway) | 1-2 hours |
+| **Prototype** | Feature shape | Working UI/flow | Sometimes | Days |
+| **POC** | System viability | Minimal working system | Often becomes v1 | Weeks |
+
+Spikes are deliberately disposable - they exist to answer a question, not to become production code.
+
+## Build Exclusion
+
+**Always exclude spikes from the project's TypeScript build:**
+
+```json
+// tsconfig.json
+{
+  "exclude": ["node_modules", "codev/spikes"]
+}
+```
+
+Why:
+- Spikes use experimental/mock code that may not compile cleanly
+- Spikes may import packages not in production dependencies
+- Keeps build fast and focused on production code
+- Prevents spike code from accidentally shipping
+
+Run spikes directly: `npx tsx codev/spikes/0062/spike-name.ts`

package/skeleton/roles/architect.md

@@ -110,6 +110,34 @@ These rules are **non-negotiable** and must be followed at all times:
 7. **Monitor progress** - Track Builder status, unblock when needed
 8. **Review and integrate** - Review Builder PRs, let builders merge them
 9. **Maintain quality** - Ensure consistency across Builder outputs
+10. **Enforce spec compliance** - Verify implementations match specs exactly
+
+## Spec Compliance Enforcement (CRITICAL)
+
+**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".**
+
+### The Trust Hierarchy
+
+```
+SPEC (source of truth)
+  ↓
+PLAN (implementation guide derived from spec)
+  ↓
+EXISTING CODE (NOT TRUSTED - must be validated against spec)
+```
+
+**Never trust existing code over the spec.** Previous phases may have drifted. The spec is always authoritative.
+
+### Before Each Implementation Phase
+
+Ask yourself:
+1. "Have I read the spec in the last 30 minutes?"
+2. "Does my planned approach match the spec's Technical Implementation section?"
+3. "If the spec has code examples, am I following them?"
+4. "If the spec has 'Traps to Avoid', have I checked each one?"
+5. "Does the existing code I'm building on match the spec?"
+
+If ANY answer is "no" or "I'm not sure" → STOP and verify before proceeding.
 
 ## Project Tracking
 
@@ -225,111 +253,15 @@ The Architect monitors progress and provides guidance when the builder is blocke
 
 ## Spikes: De-risking Technical Unknowns
 
-**Spikes are short, focused experiments that validate technical assumptions before full implementation.**
-
-### What is a Spike?
-
-The term comes from Extreme Programming (XP), coined in the late 1990s. The metaphor: a spike is like driving a railroad spike through all layers of a problem to see what's underneath. You're not building the whole foundation - you're just poking through to answer a specific question.
-
-**Key characteristics:**
-- **Time-boxed** - Has a hard stop, not open-ended research
-- **Throwaway** - The code is discarded; only the knowledge is kept
-- **Focused** - Answers ONE specific question
-- **Reduces risk** - Done before committing to full implementation
-
-| Type | Question |
-|------|----------|
-| Spike | "Can we?" / "Does it work?" |
-| Implementation | "Build it" |
-
-### When to Use Spikes
-
-Use spikes when a spec has:
-- **Untested external APIs** - Will the API actually behave as documented?
-- **Architectural uncertainty** - Will this pattern work for our use case?
-- **Integration questions** - Can these components work together?
-- **Performance unknowns** - Will this approach be fast enough?
-
-**Rule of thumb:** If the spec says "we believe X will work" or "according to docs, Y should happen" - that's a spike candidate.
-
-### Spike Structure
-
-Store spikes in `codev/spikes/{spec-number}/`:
-
-```
-codev/spikes/
-└── 0062/
-    ├── spike-api-behavior.ts
-    ├── spike-event-handoff.ts
-    └── spike-storage-roundtrip.ts
-```
-
-Each spike file should:
-
-```typescript
-/**
- * Spike: [Clear Name]
- *
- * Purpose: [What assumption are we validating?]
- *
- * Tests:
- * 1. [Specific test case]
- * 2. [Another test case]
- * 3. [Edge case]
- *
- * Run with: npx tsx codev/spikes/0062/spike-name.ts
- */
-
-// Self-contained, runnable code that validates the assumption
-// Mock/simulate infrastructure where needed
-// Print clear PASS/FAIL for each test
-```
-
-### Spike Workflow
-
-1. **Identify unknowns** during Plan phase - what could break our assumptions?
-2. **Create spikes** for each high-risk unknown
-3. **Run spikes** and document results in spec/plan
-4. **Adjust plan** based on spike findings
-5. **Include spike results** in spec as "Research Findings"
-
-### Example Spike Questions
-
-| Unknown | Spike Purpose |
-|---------|---------------|
-| "Gemini 3 requires thought signatures" | Validate signature storage and replay works |
-| "Two Inngest functions can hand off" | Test event emission and separate invocation |
-| "Frontend handles sequence gaps" | Simulate gap and verify realignment |
-| "Raw payload survives database round-trip" | Store and reconstruct exact API format |
-
-### Spike vs Prototype vs POC
-
-| Type | Scope | Output | Kept? |
-|------|-------|--------|-------|
-| **Spike** | Single question | PASS/FAIL + learnings | No (throwaway) |
-| **Prototype** | Feature shape | Working UI/flow | Sometimes |
-| **POC** | System viability | Minimal working system | Often becomes v1 |
-
-Spikes are deliberately disposable - they exist to answer a question, not to become production code.
-
-### Build Exclusion
-
-**Always exclude spikes from the project's TypeScript build:**
-
-```json
-// tsconfig.json
-{
-  "exclude": ["node_modules", "codev/spikes"]
-}
-```
+When facing high-risk technical unknowns, use **spikes** - short, time-boxed experiments (1-2 hours max) that validate assumptions before full implementation.
 
-Why:
-- Spikes use experimental/mock code that may not compile cleanly
-- Spikes may import packages not in production dependencies
-- Keeps build fast and focused on production code
-- Prevents spike code from accidentally shipping
+**Full guide:** See [codev/resources/spikes.md](../resources/spikes.md)
 
-Run spikes directly: `npx tsx codev/spikes/0062/spike-name.ts`
+**Quick reference:**
+- Store in `codev/spikes/{spec-number}/`
+- Typically 1-2 hours; check in if taking longer
+- Output: PASS/FAIL + learnings (code is throwaway)
+- Use when: Untested APIs, architectural uncertainty, integration questions
 
 ## Communication with Builders
 

package/templates/dashboard/css/files.css

@@ -498,6 +498,24 @@
   text-align: center;
 }
 
+/* Action items for creating new shells/worktrees */
+.dashboard-tab-action {
+  border: 1px dashed var(--border);
+  margin-bottom: 4px;
+  color: var(--text-muted);
+}
+
+.dashboard-tab-action:hover {
+  border-style: solid;
+  border-color: var(--accent);
+  color: var(--text-secondary);
+}
+
+.dashboard-tab-action .tab-icon {
+  color: var(--accent);
+  font-weight: 500;
+}
+
 /* Status indicators in dashboard tab list */
 .dashboard-status-indicator {
   width: 8px;

package/templates/dashboard/js/main.js

@@ -116,10 +116,6 @@ function renderDashboardTabContent() {
         <div class="dashboard-section section-tabs ${sectionState.tabs ? '' : 'collapsed'}">
           <div class="dashboard-section-header" onclick="toggleSection('tabs')">
             <h3><span class="collapse-icon">▼</span> Tabs</h3>
-            <div class="header-actions" onclick="event.stopPropagation()">
-              <button onclick="spawnBuilder()" title="New Worktree">+ Worktree</button>
-              <button onclick="spawnShell()" title="New Shell">+ Shell</button>
-            </div>
           </div>
           <div class="dashboard-section-content">
             <div class="dashboard-tabs-list" id="dashboard-tabs-list">
@@ -173,11 +169,23 @@ function renderDashboardTabContent() {
 function renderDashboardTabsList() {
   const terminalTabs = tabs.filter(t => t.type !== 'dashboard' && t.type !== 'files');
 
+  // Action items at the top of the list
+  const actionItems = `
+    <div class="dashboard-tab-item dashboard-tab-action" onclick="spawnShell()">
+      <span class="tab-icon">+</span>
+      <span class="tab-name">Create new shell</span>
+    </div>
+    <div class="dashboard-tab-item dashboard-tab-action" onclick="spawnBuilder()">
+      <span class="tab-icon">+</span>
+      <span class="tab-name">Create new worktree + shell</span>
+    </div>
+  `;
+
   if (terminalTabs.length === 0) {
-    return '<div class="dashboard-empty-state">No tabs open</div>';
+    return actionItems;
   }
 
-  return terminalTabs.map(tab => {
+  const tabItems = terminalTabs.map(tab => {
     const isActive = tab.id === activeTabId;
     const icon = getTabIcon(tab.type);
     const statusIndicator = getDashboardStatusIndicator(tab);
@@ -190,6 +198,8 @@ function renderDashboardTabsList() {
       </div>
     `;
   }).join('');
+
+  return actionItems + tabItems;
 }
 
 // Get status indicator for dashboard tab list