@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: tdd
+owner: baseline
+description: Workflow Phase 6 — TDD coordinator. Decides the scenario recipe and the implementation contract in main context, writes them to a state file, seeds per-worker tasks (scenario, implement, verify-tick, design-ui-tick) into the TaskList, and yields with harness_state continue so the harness invokes each worker as its own tick. No subagent delegation; no nested Skill calls.
+argument-hint: "[optional: spec path]"
+---
+
+# tdd — Phase 6 coordinator (post-decomposition)
+
+This skill is a **thin coordinator**. It does not invoke `scenario`, `implement`, or `design-ui` itself. Instead, it writes a recipe + contract state file, seeds per-worker tasks into the TaskList, and yields with `harness_state: "continue"`. The harness's next ticks pick up each worker task in order and invoke the matching skill — one Skill call per tick. The `verify-tick` worker is special: it has no Skill invocation at all; the harness inlines the four mechanical operations from `.claude/skills/verify/SKILL.md` (which is now contract-only, not Skill-tool-invocable).
+
+Main-context decisions live here. Worker execution happens in harness ticks.
+
+# Prereq
+
+Either an approved spec exists (`.claude/state/spec_approvals/<slug>.approval`) OR `entry_phase` in `workflow.json` is `tdd` (quickfix/bugfix direct-to-TDD).
+
+If neither, stop and direct the user to `/triage` first.
+
+# Steps
+
+## 1. Verify prereq
+
+Read `.claude/state/workflow.json`. Confirm `tdd` is the current phase to run (entry_phase is `tdd` for quickfix, OR `spec` is in `completed` AND the spec approval token exists for spec-track).
+
+## 2. Decide the scenario recipe (in main context)
+
+Read the approved spec at `docs/specs/<slug>.md` (or, for direct-TDD, the failing-case description the user supplied). Produce an explicit recipe — one entry per scenario:
+
+- `name` — `test_when_<condition>_then_<outcome>`.
+- `covers` — the spec AC ID, or `"regression"` / `"boundary"` with explanation.
+- `assertion` — what the test checks, in one plain sentence.
+- `fixtures` — the real fixtures to use (paths, factories, helpers).
+
+Also enumerate **out-of-scope scenarios** explicitly. This prevents the worker from over-producing.
+
+Skip categories the spec marks out of scope.
+
+## 3. Decide the implementation contract (in main context)
+
+Produce the recipe the implement worker will execute:
+
+- **Failing test paths** — from the scenarios decided in step 2.
+- **Write set** — the exact source file paths the implementation may touch. For solo `/tdd` use conventional source paths from `project.json → tdd.source_globs`. For `/swarm-dispatch` workers, the write set is fixed by the swarm plan.
+- **Behavior contract** — the §Behavior sequence excerpts from the spec for the ACs in scope, plus §Design data model + contracts. Quote the spec; do not paraphrase.
+- **Project conventions** — `test.cmd`, `lint.cmd`, TDD globs from `.claude/project.json`.
+
+## 4. Read the spec's Design calls (if any)
+
+Parse the `## Design calls` section of `docs/specs/<slug>.md` into a list of rows. For each row, capture `slug`, `intent`, `target_files`, `write_set`, `register_override`, `references`. If the section body is `*(none)*` or the write_set from step 3 does not intersect `project.json → tdd.ui_globs`, the list is empty.
+
+## 5. Write the tdd coordinator state file
+
+Create `.claude/state/tdd/` if missing. Write `.claude/state/tdd/<slug>.json` with shape:
+
+```jsonc
+{
+  "slug": "<workflow slug>",
+  "recipe": [ { "name": "...", "covers": "...", "assertion": "...", "fixtures": "..." }, ... ],
+  "contract": {
+    "failing_test_paths": ["..."],
+    "write_set": ["..."],
+    "behavior_excerpts": ["..."],
+    "project_conventions": { "test_cmd": "...", "lint_cmd": "..." }
+  },
+  "design_calls_rows": [ { "slug": "...", "intent": "...", "target_files": "...", "write_set": "...", "register_override": "...", "references": "..." }, ... ]
+}
+```
+
+This file is the handoff: each subsequent harness tick reads the relevant slice and feeds it to its worker.
+
+## 6. Seed worker tasks into the TaskList
+
+Create tasks via `TaskCreate`; wire `addBlockedBy` so the chain is sequential. Use these canonical entries:
+
+- **Task A — scenario-tick**: subject `"Run /scenario for <slug>"`; metadata `{phase: "scenario-tick", slug}`; activeForm `"Running scenario"`.
+- **Task B — implement-tick**: subject `"Run /implement for <slug>"`; metadata `{phase: "implement-tick", slug}`; activeForm `"Running implement"`; `addBlockedBy [A]`.
+- **Task C — verify-tick**: subject `"Run inline verify for <slug>"`; metadata `{phase: "verify-tick", slug}`; activeForm `"Running verify (inlined)"`; `addBlockedBy [B]`. The harness, when this task becomes next-pending, inlines the four mechanical operations from `.claude/skills/verify/SKILL.md` rather than invoking that skill via the Skill tool (the verify skill is contract-only after the harness-auto-continuation refactor).
+- **Tasks D₁..D_N — design-ui-tick (post-verify design implementation step; only when design_calls_rows is non-empty AND the implement write_set intersects `tdd.ui_globs`)**: one task per row. Subject `"Run /design-ui for <row.slug>"`; metadata `{phase: "design-ui-tick", slug, row_index: i}`; activeForm `"Running design-ui row <i>"`; `addBlockedBy [C]` for D₁, then chained `addBlockedBy [D_{i-1}]`. The design-ui worker handles the design implementation per the spec's `## Design calls` rows. After every D_i completes, the harness inlines a second verify pass (re-stamps `last_test_result`) to confirm the design work did not break behavior tests.
+- **Task Z — tdd-finalize**: subject `"Finalize tdd for <slug>"`; metadata `{phase: "tdd-finalize", slug}`; activeForm `"Finalizing tdd"`; `addBlockedBy` the last D_i (or C if no design-ui). On execution, the harness appends `"tdd"` to `workflow.json → completed`, writes `harness_state: continue` with reason "tdd green; next: simplify", and proceeds.
+
+## 7. Write harness_state and yield
+
+Marker FIRST: `echo "<slug>" > .claude/state/.harness_active` (the harness loop is in flight; the active marker stays set across the worker chain). Then write `.claude/state/harness_state` with `{state: "continue", slug, reason: "tdd recipe + contract + tasks ready; next: scenario"}` — exactly three keys; no `written_at`, no `tick_count`.
+
+## 8. Emit terminal message and return
+
+Tell the user (one line): `"TDD recipe + contract written to .claude/state/tdd/<slug>.json. N worker tasks seeded. Continuing."` Return. The Stop hook reads `harness_state` and re-fires the harness on the same turn, which picks up Task A (scenario-tick).
+
+# Failure handling (RALPH cap moved to implement-tick)
+
+The RALPH iteration cap (5 attempts) lives inside the implement-tick worker — the harness invokes `Skill(implement)` and `implement` runs its own loop. If implement returns `BLOCKED` after 5 iterations, the harness writes `harness_state: yielded` with the blocker reason; the user investigates and may rerun /tdd with a refined contract.
+
+# Constraints
+
+- **Decisions live here.** The recipe for scenarios and the contract for implement — both are decided in main context BEFORE the state file is written. If you find yourself deferring a decision to a worker, stop and decide it.
+- **No nested Skill invocations.** This skill does not call `scenario`, `implement`, `verify`, or `design-ui`. The harness invokes each worker as its own tick after reading the state file.
+- **Never modify tests inside the implement worker.** If a test seems wrong, the harness will surface it and re-invoke the scenario worker with a corrected recipe. `implement` is forbidden from touching tests (worker SKILL constraint).
+- **Inlined verify is binding.** When the harness runs the verify-tick, it produces the canonical four-line `last_test_result`. The `verify_pass_guard` hook reads line 1; that is the truth.
+- **One Skill call per harness tick.** This is enforced by harness's per-tick atomicity contract. tdd itself emits zero Skill calls and returns after writing state + tasks.

package/obj/template/.claude/skills/technical-tutorials/SKILL.md

@@ -0,0 +1,569 @@
+---
+name: technical-tutorials
+owner: baseline
+description: When the user wants to create step-by-step technical tutorials, quickstarts, or code walkthroughs. Trigger phrases include "tutorial," "quickstart," "getting started guide," "walkthrough," "step by step," "how to guide," "hands-on guide," or "code tutorial."
+metadata:
+  version: 1.0.0
+---
+
+# Technical Tutorials
+
+This skill helps you create step-by-step tutorials that actually work. Covers prerequisite handling, progressive complexity, troubleshooting sections, and creating those satisfying "it works!" moments.
+
+---
+
+## Before You Start
+
+**Establish audience context first.** Before writing, you need to know:
+
+- Developer skill level (beginner, intermediate, senior)
+- Tech stack familiarity (what can you assume they know?)
+- Environment (macOS, Linux, Windows, cloud)
+- Why they're learning (job, side project, curiosity)
+
+See `references/audience-context.md` (consolidated into this skill on 2026-04-28; was a standalone `developer-audience-context` skill upstream) for the audience profile shape and the 10 sections to capture. Either load an existing project-level `audience-context.md`, or elicit the four points above inline. Do not block the tutorial draft on missing audience information — document the assumptions you made at the top of the tutorial so the user can correct them.
+
+---
+
+## Tutorial Types
+
+| Type | Length | Purpose | Example |
+|------|--------|---------|---------|
+| **Quickstart** | 5-10 min | First success ASAP | "Make your first API call" |
+| **Tutorial** | 20-45 min | Learn a concept deeply | "Build a REST API with Node.js" |
+| **Workshop** | 1-3 hours | Comprehensive project | "Build a full-stack app" |
+| **Code walkthrough** | Varies | Explain existing code | "Understanding our SDK architecture" |
+
+---
+
+## The Tutorial Structure
+
+### Anatomy of a Great Tutorial
+
+```
+1. Title & Meta
+   - What you'll build
+   - Time estimate
+   - Prerequisites
+
+2. Overview
+   - What you'll learn
+   - Final result preview
+
+3. Prerequisites Check
+   - Environment setup
+   - Verification commands
+
+4. The Build (Progressive Steps)
+   - Step 1: Simplest foundation
+   - Step 2: Add one concept
+   - Step 3: Add complexity
+   - [Checkpoint: "It works!" moment]
+   - Step 4: Continue building
+   - ...
+   - [Final checkpoint]
+
+5. What You Built
+   - Recap
+   - Complete code
+
+6. Troubleshooting
+   - Common errors
+   - Debugging tips
+
+7. Next Steps
+   - Where to go from here
+   - Related tutorials
+```
+
+---
+
+## Prerequisites Handling
+
+### The Prerequisites Section
+
+Be explicit. Don't make developers guess what they need.
+
+```markdown
+## Prerequisites
+
+Before starting, make sure you have:
+
+| Requirement | Version | Check Command |
+|-------------|---------|---------------|
+| Node.js | 18+ | `node --version` |
+| npm | 9+ | `npm --version` |
+| Git | Any | `git --version` |
+
+You should also be comfortable with:
+- Basic JavaScript (variables, functions, async/await)
+- Command line basics (cd, mkdir, running commands)
+- REST API concepts (HTTP methods, JSON)
+
+**New to any of these?** Check out [link to prerequisite tutorial].
+```
+
+### Environment Setup Section
+
+Make setup foolproof:
+
+```markdown
+## Setting Up Your Environment
+
+### 1. Create Project Directory
+
+\`\`\`bash
+mkdir my-awesome-project
+cd my-awesome-project
+\`\`\`
+
+### 2. Initialize the Project
+
+\`\`\`bash
+npm init -y
+\`\`\`
+
+You should see output like:
+\`\`\`json
+{
+  "name": "my-awesome-project",
+  "version": "1.0.0",
+  ...
+}
+\`\`\`
+
+### 3. Install Dependencies
+
+\`\`\`bash
+npm install express dotenv
+\`\`\`
+
+### 4. Verify Installation
+
+\`\`\`bash
+node -e "require('express'); console.log('Express installed!')"
+\`\`\`
+
+Expected output: `Express installed!`
+```
+
+---
+
+## Progressive Complexity
+
+### The Layer Cake Approach
+
+Build up in understandable layers:
+
+| Layer | What It Does | Example |
+|-------|--------------|---------|
+| **1. Skeleton** | Minimum viable code that runs | "Hello World" server |
+| **2. Core feature** | Primary functionality | Add one API endpoint |
+| **3. Real data** | Replace hardcoded values | Connect to database |
+| **4. Error handling** | Production-ready patterns | Add try/catch, validation |
+| **5. Polish** | Nice-to-haves | Logging, config, tests |
+
+### Show Progress, Not Perfection
+
+**Wrong approach** (overwhelming):
+```javascript
+// Here's the complete file with everything
+const express = require('express');
+const { Pool } = require('pg');
+const helmet = require('helmet');
+const rateLimit = require('express-rate-limit');
+const winston = require('winston');
+// ... 200 more lines
+```
+
+**Right approach** (progressive):
+
+**Step 1: Basic server**
+```javascript
+const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => {
+  res.send('Hello World!');
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+**Step 2: Add your first route**
+```javascript
+// Add this below your existing route
+app.get('/api/users', (req, res) => {
+  res.json([{ id: 1, name: 'Jane' }]);
+});
+```
+
+---
+
+## Copy-Paste Friendly Code
+
+### The Copy-Paste Checklist
+
+Every code block must pass these tests:
+
+| Test | How to Verify |
+|------|---------------|
+| **Runs standalone** | Copy into new file, execute, it works |
+| **Imports included** | All `require`/`import` statements present |
+| **No undefined variables** | No references to code from other steps without showing it |
+| **Environment agnostic** | Works on Mac/Linux/Windows |
+| **Comments explain why** | Not what (code shows what), but why |
+
+### Code Block Patterns
+
+**File context is critical:**
+
+```javascript
+// server.js - Add this to your existing file
+const rateLimit = require('express-rate-limit');
+
+// Add this BEFORE your routes
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100 // limit each IP to 100 requests per window
+});
+
+app.use(limiter);
+```
+
+**Show file structure:**
+
+```
+my-project/
+├── src/
+│   ├── index.js      ← You're editing this
+│   ├── routes/
+│   │   └── users.js
+│   └── db/
+│       └── connection.js
+├── package.json
+└── .env
+```
+
+**Highlight changes in context:**
+
+```javascript
+// src/index.js
+const express = require('express');
+const app = express();
+
+// ✅ ADD THIS: Import your new route
+const userRoutes = require('./routes/users');
+
+// ✅ ADD THIS: Use the route
+app.use('/api/users', userRoutes);
+
+app.listen(3000);
+```
+
+---
+
+## "It Works!" Moments
+
+### Checkpoints Create Motivation
+
+Every 3-5 steps, give developers a win:
+
+```markdown
+## Checkpoint: Test Your API
+
+Let's make sure everything works before continuing.
+
+**Start your server:**
+\`\`\`bash
+node server.js
+\`\`\`
+
+**In a new terminal, test the endpoint:**
+\`\`\`bash
+curl http://localhost:3000/api/users
+\`\`\`
+
+**You should see:**
+\`\`\`json
+[{"id": 1, "name": "Jane"}]
+\`\`\`
+
+🎉 **It works!** Your API is returning data.
+
+If you don't see this output, check the [Troubleshooting](#troubleshooting) section.
+```
+
+### Visual Confirmation
+
+When possible, show what success looks like:
+
+| Output Type | How to Show |
+|-------------|-------------|
+| **Terminal output** | Code block with expected text |
+| **Browser result** | Screenshot or description |
+| **API response** | Formatted JSON |
+| **Logs** | Code block with log output |
+
+---
+
+## Troubleshooting Sections
+
+### Common Error Template
+
+```markdown
+## Troubleshooting
+
+### "Error: Cannot find module 'express'"
+
+**Cause:** Dependencies weren't installed.
+
+**Fix:**
+\`\`\`bash
+npm install
+\`\`\`
+
+---
+
+### "EADDRINUSE: address already in use :::3000"
+
+**Cause:** Another process is using port 3000.
+
+**Fix (macOS/Linux):**
+\`\`\`bash
+# Find the process
+lsof -i :3000
+
+# Kill it (replace PID with actual number)
+kill -9 PID
+\`\`\`
+
+**Or use a different port:**
+\`\`\`javascript
+app.listen(process.env.PORT || 3001);
+\`\`\`
+
+---
+
+### "SyntaxError: Unexpected token"
+
+**Cause:** Likely a typo or missing bracket.
+
+**Debug steps:**
+1. Check the line number in the error
+2. Look for missing `,`, `}`, or `)`
+3. Verify all strings are closed with matching quotes
+```
+
+### Proactive Error Prevention
+
+Add warnings before common pitfalls:
+
+```markdown
+⚠️ **Windows users:** Use `set` instead of `export`:
+\`\`\`bash
+# macOS/Linux
+export API_KEY=your_key
+
+# Windows Command Prompt
+set API_KEY=your_key
+
+# Windows PowerShell
+$env:API_KEY="your_key"
+\`\`\`
+```
+
+---
+
+## Tutorial Templates
+
+### Quickstart Template (5-10 minutes)
+
+```markdown
+# [Product] Quickstart: [What You'll Do] in 5 Minutes
+
+Get [specific outcome] in under 5 minutes.
+
+## Prerequisites
+
+- [Requirement 1]
+- [Requirement 2]
+
+## Step 1: Install
+
+\`\`\`bash
+npm install your-package
+\`\`\`
+
+## Step 2: Configure
+
+Create a `.env` file:
+\`\`\`
+API_KEY=your_key_here
+\`\`\`
+
+## Step 3: Write Code
+
+Create `index.js`:
+\`\`\`javascript
+// Complete, working code
+\`\`\`
+
+## Step 4: Run It
+
+\`\`\`bash
+node index.js
+\`\`\`
+
+Expected output:
+\`\`\`
+[Output here]
+\`\`\`
+
+## 🎉 You Did It!
+
+You just [accomplished thing].
+
+**Next steps:**
+- [Link to full tutorial]
+- [Link to API docs]
+- [Link to examples repo]
+```
+
+### Full Tutorial Template (20-45 minutes)
+
+```markdown
+# Build a [Thing] with [Technology]
+
+Learn how to [outcome] by building [specific project].
+
+| | |
+|---|---|
+| **Time** | 30 minutes |
+| **Level** | Intermediate |
+| **Prerequisites** | Node.js 18+, basic JavaScript |
+
+## What You'll Build
+
+[Screenshot or diagram of final result]
+
+By the end, you'll have:
+- ✅ [Capability 1]
+- ✅ [Capability 2]
+- ✅ [Capability 3]
+
+## Prerequisites
+
+### Required Software
+
+| Tool | Version | Verify |
+|------|---------|--------|
+| Node.js | 18+ | `node -v` |
+
+### Required Knowledge
+
+- [Concept 1] — [link to learn]
+- [Concept 2] — [link to learn]
+
+## Step 1: Project Setup
+
+[Setup instructions with verification]
+
+**Checkpoint:** You should see `[expected output]`.
+
+## Step 2: [First Feature]
+
+[Instructions]
+
+**Checkpoint:** Test with `[command]`.
+
+## Step 3: [Second Feature]
+
+[Instructions]
+
+## Step 4: [Third Feature]
+
+[Instructions]
+
+**Checkpoint:** Your app should now [do thing].
+
+## Complete Code
+
+Here's everything together:
+
+\`\`\`javascript
+// Full final code
+\`\`\`
+
+## Troubleshooting
+
+### [Common Error 1]
+[Solution]
+
+### [Common Error 2]
+[Solution]
+
+## What You Learned
+
+- [Key concept 1]
+- [Key concept 2]
+- [Key concept 3]
+
+## Next Steps
+
+- **Go deeper:** [Link to advanced tutorial]
+- **Explore:** [Link to related feature]
+- **Get help:** [Link to Discord/community]
+```
+
+---
+
+## Quality Checklist
+
+Before publishing, verify:
+
+### Code Quality
+- [ ] Every code block runs without modification
+- [ ] All imports/requires are included
+- [ ] Expected output is shown
+- [ ] Error handling is included
+- [ ] Environment variables use `.env` pattern
+
+### Structure Quality
+- [ ] Prerequisites are explicit
+- [ ] Time estimate is accurate (test it!)
+- [ ] Checkpoints every 3-5 steps
+- [ ] Final complete code is provided
+- [ ] Troubleshooting covers likely errors
+
+### Accessibility
+- [ ] Works on Mac, Linux, AND Windows
+- [ ] Commands work in bash/zsh/PowerShell
+- [ ] File paths use correct separators
+- [ ] No assumptions about installed tools
+
+---
+
+## Tools
+
+| Tool | Use Case |
+|------|----------|
+| **[Octolens](https://octolens.com)** | Find common questions and errors developers encounter. Monitor Stack Overflow and GitHub issues for troubleshooting content. |
+| **Replit/CodeSandbox** | Embed runnable examples |
+| **Carbon/Ray.so** | Beautiful code screenshots |
+| **Excalidraw** | Architecture diagrams |
+| **Terminalizer** | Record terminal sessions |
+| **Loom** | Quick video supplements |
+
+---
+
+## Related Skills
+
+These four are upstream companion skills (from the `claude-code-setup` plugin family) and **do not ship with this baseline**. Listed here for reference only; if you need their capabilities, ask the user inline or install the plugin separately.
+
+- `developer-audience-context` — Understand skill level and environment
+- `devrel-content` — General technical writing principles
+- `developer-onboarding` — Optimize time to first success
+- `developer-seo` — Get tutorials found via search