create-harness-vibe-coding 0.1.9 → 0.2.0

package/templates/common/scripts/validate-harness.mjs

@@ -7,10 +7,11 @@ const args = new Set(process.argv.slice(2));
 const strict = args.has('--strict') || args.has('--post-bootstrap');
 
 if (args.has('--help') || args.has('-h')) {
-  console.log(`Usage: node scripts/validate-harness.mjs [--strict]
+  console.log(`Usage: node Harness/scripts/validate-harness.mjs [--strict]
 
 Default mode checks scaffold structure, links, agents, and skills.
---strict also fails when project fact docs still contain {{...}} placeholders.`);
+--strict also fails when project fact docs still contain unresolved {{TOKEN}} placeholders.
+Literal explanatory {{...}} text is allowed.`);
   process.exit(0);
 }
 
@@ -32,39 +33,53 @@ const commonSkills = [
   'harness-research',
   'harness-context',
   'harness-build-loop',
+  'wf-mode',
+  'subagent-orchestrator',
+  'readme-optimizer',
+];
+
+const memoryFiles = [
+  'Harness/memory/tool-usage-reflections.md',
+  'Harness/memory/user-corrections-preferences.md',
+  'Harness/memory/agent-lessons-patterns.md',
 ];
 
 const required = [
   'AGENTS.md',
   'CLAUDE.md',
-  'MEMORY.md',
+  'README.md',
+  'Harness/MEMORY.md',
+  'Harness/WF.md',
+  ...memoryFiles,
   '.claude/settings.json',
+  '.claude/commands/wf.md',
   '.claude/rules/ecc/common.md',
   ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
   ...commonSkills.map(skill => `.claude/skills/${skill}/SKILL.md`),
-  'docs/README.md',
-  'docs/harness/PLAN.md',
-  'docs/harness/lifecycle.md',
-  'docs/harness/dispatch.md',
-  'docs/harness/extension.md',
-  'docs/harness/context-loading.md',
-  'docs/harness/agent-workflow.md',
-  'docs/harness/architecture.md',
-  'docs/harness/data-flow.md',
-  'docs/harness/state-machines.md',
-  'docs/features/_template.md',
-  'docs/research/README.md',
-  'docs/research/research-results.md',
-  'docs/research/PRD.md',
-  'docs/domain/ports.md',
+  'Harness/README.md',
+  'Harness/PLAN.md',
+  'Harness/lifecycle.md',
+  'Harness/subagents.md',
+  'Harness/dispatch.md',
+  'Harness/extension.md',
+  'Harness/context-loading.md',
+  'Harness/agent-workflow.md',
+  'Harness/architecture.md',
+  'Harness/data-flow.md',
+  'Harness/state-machines.md',
+  'Harness/features/_template.md',
+  'Harness/research/README.md',
+  'Harness/research/research-results.md',
+  'Harness/research/PRD.md',
+  'Harness/domain/ports.md',
 ];
 
 const projectFacts = [
-  'docs/harness/PLAN.md',
-  'docs/research/PRD.md',
-  'docs/research/research-results.md',
-  'docs/harness/architecture.md',
-  'docs/domain/ports.md',
+  'Harness/PLAN.md',
+  'Harness/research/PRD.md',
+  'Harness/research/research-results.md',
+  'Harness/architecture.md',
+  'Harness/domain/ports.md',
 ];
 
 const contextPacks = [
@@ -80,6 +95,13 @@ const contextPacks = [
   'Verifier:',
 ];
 
+const durableCommunicationDocs = [
+  'Harness/README.md',
+  'Harness/subagents.md',
+  'Harness/dispatch.md',
+  'Harness/context-loading.md',
+];
+
 const errors = [];
 
 function read(rel) {
@@ -97,69 +119,193 @@ function frontmatterField(text, field) {
   return match ? match[1].trim() : '';
 }
 
+function listDirectories(rel) {
+  const dir = path.join(root, rel);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name);
+}
+
+function listMarkdownFiles(rel) {
+  const dir = path.join(root, rel);
+  if (!fs.existsSync(dir)) return [];
+  const normalizedRel = rel.replaceAll(path.sep, '/');
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.md'))
+    .map(entry => `${normalizedRel}/${entry.name}`);
+}
+
+function unresolvedTemplatePlaceholders(text) {
+  const placeholders = [];
+  const pattern = /\{\{([^{}\r\n]+)\}\}/g;
+
+  for (const match of text.matchAll(pattern)) {
+    const token = match[1].trim();
+    if (token === '...') continue;
+    placeholders.push(`{{${token}}}`);
+  }
+
+  return [...new Set(placeholders)];
+}
+
+function registeredSkillFiles(...texts) {
+  const files = new Set();
+  const pattern = /(?:\.\.\/)?(\.claude\/skills\/[a-z0-9-]+\/SKILL\.md)/g;
+
+  for (const text of texts) {
+    for (const match of text.matchAll(pattern)) {
+      files.add(match[1]);
+    }
+  }
+
+  return [...files].sort();
+}
+
+function registeredWorkflowFiles(...texts) {
+  const files = new Set();
+  const pattern = /(?:Harness\/)?workflows\/([A-Za-z0-9._-]+\.md)/g;
+
+  for (const text of texts) {
+    for (const match of text.matchAll(pattern)) {
+      files.add(`Harness/workflows/${match[1]}`);
+    }
+  }
+
+  return [...files].sort();
+}
+
 for (const rel of required) {
   if (!fs.existsSync(path.join(root, rel))) {
     errors.push(`missing required file: ${rel}`);
   }
 }
 
-if (fs.existsSync(path.join(root, 'docs/research/scaffolds.md'))) {
-  errors.push('legacy research file should be renamed: docs/research/scaffolds.md -> docs/research/research-results.md');
+if (fs.existsSync(path.join(root, 'Harness/research/scaffolds.md'))) {
+  errors.push('legacy research file should be renamed: Harness/research/scaffolds.md -> Harness/research/research-results.md');
 }
 
 if (strict) {
+  console.log('Strict placeholder scope:');
+  for (const rel of projectFacts) {
+    console.log(`- ${rel}`);
+  }
+
   for (const rel of projectFacts) {
     const text = read(rel);
-    if (text.includes('{{')) {
-      errors.push(`template placeholders remain in project fact file: ${rel}`);
+    for (const placeholder of unresolvedTemplatePlaceholders(text)) {
+      errors.push(`template placeholder remains in project fact file: ${rel}: ${placeholder}`);
     }
   }
 }
 
-const docsReadme = read('docs/README.md');
+const docsReadme = read('Harness/README.md');
 if (docsReadme) {
   for (const marker of ['## Keyword Routing', '## Load By Task', 'When to Read', 'Keywords']) {
-    if (!docsReadme.includes(marker)) errors.push(`docs/README.md missing router marker: ${marker}`);
+    if (!docsReadme.includes(marker)) errors.push(`Harness/README.md missing router marker: ${marker}`);
   }
 }
 
-const plan = read('docs/harness/PLAN.md');
+for (const rel of durableCommunicationDocs) {
+  requireText(rel, 'project files are the only durable communication channel', 'durable filesystem communication invariant');
+  requireText(rel, 'chat/subagent transcript state is non-authoritative', 'non-authoritative transcript invariant');
+}
+
+requireText('CLAUDE.md', 'same tool/use pattern fails 3+ times', 'tool reflection trigger');
+requireText('CLAUDE.md', 'user corrects the same assumption/pattern 2+ times', 'user correction reflection trigger');
+requireText('CLAUDE.md', 'If `Harness/` exists, this repository is governed by the Harness contract', 'Harness binding contract');
+requireText('CLAUDE.md', 'Harness/MEMORY.md` is the memory/resource router', 'memory/resource router');
+requireText('CLAUDE.md', 'Harness/README.md#Load By Task', 'Harness task router');
+requireText('CLAUDE.md', 'Harness/SETUP.md` exists, follow it before normal project work', 'setup bootstrap contract');
+requireText('CLAUDE.md', 'subagent-orchestrator` and `Harness/subagents.md', 'subagent orchestrator entry trigger');
+for (const heading of ['## 2. Think Before Coding', '## 3. Simplicity First', '## 4. Surgical Changes', '## 5. Goal-Driven Execution']) {
+  requireText('CLAUDE.md', heading, `Karpathy-style rule heading: ${heading}`);
+}
+
+const plan = read('Harness/PLAN.md');
 if (plan) {
-  for (const heading of ['## Current Goal', '## Phase', '## Success Criteria', '## Loaded Context', '## Tasks', '## Parallel Dispatch', '## Verification']) {
-    if (!plan.includes(heading)) errors.push(`docs/harness/PLAN.md missing heading: ${heading}`);
+  for (const heading of ['## Current Goal', '## Phase', '## Heartbeat', '## Success Criteria', '## Loaded Context', '## Tasks', '## Parallel Dispatch', '## Subagent Synthesis', '## Verification']) {
+    if (!plan.includes(heading)) errors.push(`Harness/PLAN.md missing heading: ${heading}`);
+  }
+  for (const marker of ['Next beat trigger', 'Recovery action']) {
+    if (!plan.includes(marker)) errors.push(`Harness/PLAN.md missing heartbeat marker: ${marker}`);
   }
 }
 
-const dispatch = read('docs/harness/dispatch.md');
+const dispatch = read('Harness/dispatch.md');
 if (dispatch) {
   for (const agent of commonAgents) {
-    if (!dispatch.includes(`\`${agent}\``)) errors.push(`docs/harness/dispatch.md missing common agent: ${agent}`);
+    if (!dispatch.includes(`\`${agent}\``)) errors.push(`Harness/dispatch.md missing common agent: ${agent}`);
   }
-  if (!dispatch.includes('## Handoff Format')) errors.push('docs/harness/dispatch.md missing heading: ## Handoff Format');
+  if (!dispatch.includes('## Handoff Format')) errors.push('Harness/dispatch.md missing heading: ## Handoff Format');
 }
 
-const contextLoading = read('docs/harness/context-loading.md');
+const contextLoading = read('Harness/context-loading.md');
 if (contextLoading) {
-  if (!contextLoading.includes('docs/README.md` is the primary router')) {
-    errors.push('docs/harness/context-loading.md must declare docs/README.md as the primary router');
+  if (!contextLoading.includes('Harness/README.md` is the primary router')) {
+    errors.push('Harness/context-loading.md must declare Harness/README.md as the primary router');
   }
   for (const pack of contextPacks) {
-    if (!contextLoading.includes(pack)) errors.push(`docs/harness/context-loading.md missing subagent pack: ${pack}`);
+    if (!contextLoading.includes(pack)) errors.push(`Harness/context-loading.md missing subagent pack: ${pack}`);
   }
 }
 
-const memory = read('MEMORY.md');
+const memory = read('Harness/MEMORY.md');
 if (memory) {
   for (const agent of commonAgents) {
     const rel = `.claude/agents/${agent}.md`;
-    if (!memory.includes(rel)) errors.push(`MEMORY.md missing agent registration: ${rel}`);
+    if (!memory.includes(rel)) errors.push(`Harness/MEMORY.md missing agent registration: ${rel}`);
   }
   for (const skill of commonSkills) {
     const rel = `.claude/skills/${skill}/SKILL.md`;
-    if (!memory.includes(rel)) errors.push(`MEMORY.md missing skill registration: ${rel}`);
+    if (!memory.includes(rel)) errors.push(`Harness/MEMORY.md missing skill registration: ${rel}`);
+  }
+  for (const rel of memoryFiles) {
+    const relativeRel = rel.replace(/^Harness\//, '');
+    if (!memory.includes(rel) && !memory.includes(relativeRel)) {
+      errors.push(`Harness/MEMORY.md missing memory file registration: ${rel}`);
+    }
+  }
+}
+
+for (const workflow of listMarkdownFiles('Harness/workflows')) {
+  const relativeWorkflow = workflow.replace(/^Harness\//, '');
+  if (!docsReadme.includes(workflow) && !docsReadme.includes(relativeWorkflow) && !memory.includes(workflow) && !memory.includes(relativeWorkflow)) {
+    errors.push(`workflow is not registered in Harness/README.md or Harness/MEMORY.md: ${workflow}`);
+  }
+}
+
+for (const skillFile of registeredSkillFiles(docsReadme, memory)) {
+  if (!fs.existsSync(path.join(root, skillFile))) {
+    errors.push(`registered skill file is missing: ${skillFile}`);
+  }
+}
+
+for (const workflowFile of registeredWorkflowFiles(docsReadme, memory)) {
+  if (!fs.existsSync(path.join(root, workflowFile))) {
+    errors.push(`registered workflow file is missing: ${workflowFile}`);
+  }
+}
+
+function requireUiSelectorContract(rel) {
+  const text = read(rel);
+  if (!text) return;
+
+  const markers = [
+    'data-testid',
+    'accessible labels/roles',
+    'inputs, buttons, filters, rows, empty/error/loading states',
+  ];
+
+  if (markers.some(marker => !text.includes(marker))) {
+    errors.push(`${rel} missing stable UI selector contract`);
   }
 }
 
+requireUiSelectorContract('Harness/workflows/browser-e2e.md');
+requireUiSelectorContract('Harness/workflows/ts-react-frontend.md');
+requireUiSelectorContract('Harness/features/_template.md');
+
 for (const skill of commonSkills) {
   const rel = `.claude/skills/${skill}/SKILL.md`;
   const text = read(rel);
@@ -168,6 +314,17 @@ for (const skill of commonSkills) {
   if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
 }
 
+for (const skill of listDirectories('.claude/skills')) {
+  if (commonSkills.includes(skill)) continue;
+
+  const rel = `.claude/skills/${skill}/SKILL.md`;
+  const text = read(rel);
+  if (!text) continue;
+
+  if (frontmatterField(text, 'name') !== skill) errors.push(`${rel} frontmatter name does not match directory`);
+  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
+}
+
 for (const agent of commonAgents) {
   const rel = `.claude/agents/${agent}.md`;
   const text = read(rel);
@@ -191,9 +348,23 @@ for (const agent of commonAgents) {
   }
 }
 
-requireText('docs/harness/extension.md', 'Skills should extend the harness');
-requireText('docs/harness/agent-workflow.md', 'docs/harness/PLAN.md');
-requireText('docs/research/README.md', 'research-results.md');
+requireText('Harness/extension.md', 'Skills should extend the harness');
+requireText('Harness/agent-workflow.md', 'Harness/PLAN.md');
+requireText('Harness/research/README.md', 'research-results.md');
+requireText('Harness/WF.md', 'Ralph-style harness loop', 'WF loop description');
+requireText('Harness/WF.md', 'Heartbeat Protocol', 'heartbeat protocol');
+requireText('.claude/skills/wf-mode/SKILL.md', 'Harness/WF.md', 'wf-mode loads WF document');
+requireText('.claude/skills/wf-mode/SKILL.md', 'Harness/subagents.md', 'wf-mode loads subagent orchestration');
+requireText('.claude/skills/subagent-orchestrator/SKILL.md', 'Harness/subagents.md', 'subagent-orchestrator loads subagents doc');
+requireText('.claude/skills/harness-context/SKILL.md', 'Harness/subagents.md', 'harness-context loads subagents doc');
+requireText('.claude/skills/readme-optimizer/SKILL.md', 'README.md', 'readme-optimizer loads README');
+requireText('.claude/skills/readme-optimizer/SKILL.md', 'Harness/architecture.md', 'readme-optimizer links architecture docs');
+requireText('Harness/subagents.md', '## Source Attribution', 'subagent source attribution');
+requireText('Harness/subagents.md', 'npx skills find', 'find-skills discovery attribution');
+requireText('Harness/subagents.md', 'superpowers:dispatching-parallel-agents', 'parallel-agent source attribution');
+requireText('Harness/subagents.md', 'superpowers:subagent-driven-development', 'subagent-driven source attribution');
+requireText('Harness/subagents.md', '## Efficiency Ladder', 'subagent efficiency ladder');
+requireText('Harness/subagents.md', '## Review Gates', 'subagent review gates');
 
 if (errors.length) {
   console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);
@@ -203,5 +374,5 @@ if (errors.length) {
 
 console.log(`Harness validation passed${strict ? ' (strict)' : ''}.`);
 if (!strict) {
-  console.log('Tip: run `node scripts/validate-harness.mjs --strict` after bootstrap to check unresolved project placeholders.');
+  console.log('Tip: run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap to check unresolved project placeholders.');
 }

package/templates/optional/catalog.json

@@ -0,0 +1,43 @@
+{
+  "skills": [
+    {
+      "id": "browser-e2e",
+      "title": "Browser E2E",
+      "description": "Mandatory real-browser smoke workflow using Playwright, Chrome DevTools/CDP, or documented manual evidence.",
+      "files": ["skills/browser-e2e"],
+      "tags": ["e2e", "browser", "playwright", "cdp"]
+    },
+    {
+      "id": "ui-ux-review",
+      "title": "UI/UX Review",
+      "description": "Screenshot-driven responsive, accessibility, and visual polish review workflow.",
+      "files": ["skills/ui-ux-review"],
+      "tags": ["ui", "ux", "accessibility", "review"]
+    },
+    {
+      "id": "github-pr-review",
+      "title": "GitHub PR Review",
+      "description": "GitHub CLI based PR diff, checks, review findings, and CI evidence workflow.",
+      "files": ["skills/github-pr-review"],
+      "tags": ["github", "pr", "review", "ci"]
+    },
+    {
+      "id": "python-backend",
+      "title": "Python Backend",
+      "description": "Python backend workflow for FastAPI or similar APIs with unittest or pytest verification.",
+      "files": ["skills/python-backend"],
+      "tags": ["python", "fastapi", "unittest", "pytest", "api"]
+    },
+    {
+      "id": "ts-react-frontend",
+      "title": "TypeScript React Frontend",
+      "description": "TypeScript React workflow for typecheck, component tests, builds, and browser smoke.",
+      "files": ["skills/ts-react-frontend"],
+      "tags": ["typescript", "react", "vite", "frontend"]
+    }
+  ],
+  "presets": {
+    "web-app": ["ts-react-frontend", "browser-e2e", "ui-ux-review"],
+    "fullstack": ["ts-react-frontend", "python-backend", "browser-e2e", "github-pr-review"]
+  }
+}

package/templates/optional/skills/browser-e2e/.claude/skills/browser-e2e/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: browser-e2e
+description: Mandatory real-browser smoke and end-to-end verification using Playwright, Chrome DevTools/CDP, or documented manual browser evidence.
+---
+
+# Browser E2E
+
+## When To Use
+
+Use this skill when a change affects browser-visible behavior, navigation, forms, routing, layout, or client-side integration. Web/UI acceptance requires loading the app in a real browser before claiming the UI is done.
+
+## Docs To Load
+
+- `Harness/workflows/browser-e2e.md`
+- `Harness/PLAN.md`
+- Existing project test, build, and run instructions.
+
+## Required Inputs
+
+- Target URL or command to start the app.
+- User flows or pages to verify.
+- Expected behavior and supported viewport/browser scope.
+- Selector contract: stable accessible labels/roles and `data-testid` hooks for critical inputs, buttons, filters, rows, empty/error/loading states, and other targetable UI states.
+
+## Allowed Writes
+
+- Browser test files in the project's existing test locations.
+- Evidence artifacts such as screenshots, traces, or reports in existing artifact folders.
+- Notes in `Harness/PLAN.md` when the active task asks for plan tracking.
+
+## Output Format
+
+Return changed files, commands run, browser evidence paths, verified flows, failures, and follow-up risks.
+Include the selectors used for CDP/Playwright/manual verification.
+
+## PLAN.md Updates
+
+Update `Harness/PLAN.md` only when executing a tracked plan item or recording evidence requested by the current task.
+
+## dispatch.md Usage
+
+Use `Harness/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.

package/templates/optional/skills/browser-e2e/docs/workflows/browser-e2e.md

@@ -0,0 +1,42 @@
+# Browser E2E Workflow
+
+## Required Evidence
+
+- App start command and URL.
+- Real-browser load of the changed app before any web/UI acceptance claim.
+- Console, runtime, and network check result, including whether React/Vite/client startup errors or failed requests appeared.
+- Stable accessible labels/roles and stable test hooks such as `data-testid` are required for critical UI controls and states: inputs, buttons, filters, rows, empty/error/loading states.
+- CDP, Playwright, and manual verification must target those selectors for the critical interaction path instead of brittle DOM paths.
+- Viewports and browsers checked.
+- Screenshot, trace, video, or documented manual screenshot artifact for each critical UI flow.
+- Final pass/fail result with exact command output summary.
+
+## Chrome DevTools / CDP / MCP Checklist
+
+- Start the app with the project command and record the URL and port.
+- Open a real browser target through available CDP, MCP, browser automation, or manual tooling.
+- Wait for a stable app selector, route, or page-ready state, not just HTTP 200.
+- Capture runtime exceptions, console errors, and failed network requests before and after the flow.
+- Interact through stable accessible labels/roles or `data-testid`, not brittle DOM paths.
+- Verify at least one critical flow end-to-end in the real browser target.
+- Save screenshot, trace, video, or result artifact paths and record them in `Harness/PLAN.md` or the feature doc.
+- Clean up any dev server or browser processes started for verification.
+
+## Common Commands
+
+```powershell
+npm run dev
+npx playwright test
+npx playwright test --headed
+npx playwright show-report
+```
+
+If Playwright is not installed, prefer an existing browser test command from `package.json`. Chrome DevTools/CDP, manual screenshot evidence, or framework-specific tools are acceptable when the method, URL, flow, console/runtime/network result, and artifacts are documented.
+
+## Fallback
+
+When no browser automation is available, run the app locally in a real browser, inspect critical flows manually, capture screenshots, and report console or network errors. Do not claim web/UI acceptance from typecheck, build, or unit tests alone. Do not install new dependencies unless the user approves.
+
+## Windows Notes
+
+Use PowerShell syntax for environment variables, for example `$env:PORT='3000'; npm run dev`. Quote paths that contain spaces.

package/templates/optional/skills/github-pr-review/.claude/skills/github-pr-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: github-pr-review
+description: GitHub pull request review workflow using available GitHub CLI, local git diff, checks, and CI evidence.
+---
+
+# GitHub PR Review
+
+## When To Use
+
+Use this skill when reviewing a GitHub pull request, responding to PR feedback, checking CI status, or summarizing review findings.
+
+## Docs To Load
+
+- `Harness/workflows/github-pr-review.md`
+- `Harness/PLAN.md`
+- Repository contribution, test, and review guidelines.
+
+## Required Inputs
+
+- PR number, branch, or comparison range.
+- Review goal: bug hunt, approval readiness, CI diagnosis, or feedback response.
+- Expected test and check requirements.
+
+## Allowed Writes
+
+- Local files needed to address approved review feedback.
+- Review notes or evidence in existing docs only when requested.
+- `Harness/PLAN.md` when tracking review work.
+
+## Output Format
+
+Return findings first by severity with file and line references, then open questions, tests/checks run, and change summary if edits were made.
+
+## PLAN.md Updates
+
+Update `Harness/PLAN.md` only when the PR review is part of a tracked implementation plan.
+
+## dispatch.md Usage
+
+Use `Harness/dispatch.md` when independent review areas can be assigned separately, such as backend, frontend, and CI.

package/templates/optional/skills/github-pr-review/docs/workflows/github-pr-review.md

@@ -0,0 +1,28 @@
+# GitHub PR Review Workflow
+
+## Required Evidence
+
+- PR URL or number and base/head refs.
+- Diff or changed-file summary.
+- CI/check status and relevant failing logs.
+- Review findings with exact file and line references when available.
+
+## Common Commands
+
+```powershell
+gh pr view --web
+gh pr view --json number,title,baseRefName,headRefName,mergeStateStatus,statusCheckRollup
+gh pr diff
+git diff --stat
+npm test
+```
+
+Use repository-specific test commands when they differ from npm.
+
+## Fallback
+
+If `gh` is unavailable or unauthenticated, use local git refs, remote URLs, and `git diff` against the target branch. Ask for missing PR context only when it cannot be inferred.
+
+## Windows Notes
+
+Quote branch names containing special characters. In PowerShell, pipe JSON output to tools that are available locally, or read it directly if `jq` is not installed.

package/templates/optional/skills/python-backend/.claude/skills/python-backend/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: python-backend
+description: Python backend workflow for API changes, service logic, FastAPI-style routes, and unittest or pytest verification.
+---
+
+# Python Backend
+
+## When To Use
+
+Use this skill when changing Python API routes, service logic, persistence boundaries, background jobs, or backend tests.
+
+## Docs To Load
+
+- `Harness/workflows/python-backend.md`
+- `Harness/PLAN.md`
+- Project backend README, API docs, dependency files, and test configuration.
+
+## Required Inputs
+
+- Target behavior, endpoint, service, or bug.
+- Existing test command and runtime setup.
+- Database, environment variable, or fixture constraints.
+
+## Allowed Writes
+
+- Python source, tests, fixtures, and backend docs in the task scope.
+- Local evidence artifacts such as test output snippets.
+- `Harness/PLAN.md` when the task requires plan tracking.
+
+## Output Format
+
+Return files changed, API or behavior summary, tests run, important logs, migration/config notes, and remaining risks.
+
+## PLAN.md Updates
+
+Update `Harness/PLAN.md` only when executing a tracked plan item or recording required validation evidence.
+
+## dispatch.md Usage
+
+Use `Harness/dispatch.md` for separable backend work such as API implementation, database changes, and test coverage.

package/templates/optional/skills/python-backend/docs/workflows/python-backend.md

@@ -0,0 +1,34 @@
+# Python Backend Workflow
+
+## Required Evidence
+
+- Python executable, version, and dependency manager detected.
+- Unit/integration test command and result.
+- API smoke evidence for changed endpoints when applicable.
+- Migration, fixture, or environment assumptions.
+
+## Common Commands
+
+```powershell
+python --version
+py --version
+python3 --version
+python -m unittest discover -s tests
+py -m unittest discover -s tests
+python3 -m unittest discover -s tests
+python -m pytest
+python -m pytest tests
+uv run pytest
+poetry run pytest
+python -m uvicorn app.main:app --reload
+```
+
+Prefer commands already documented by the project. When no project-specific command is documented, detect an available Python executable in the current shell (`python`, then `py`, then `python3`) and run the matching `-m unittest discover -s tests` or pytest command. `unittest` is first-class for standard-library test suites; do not require pytest when the project already uses unittest.
+
+## Fallback
+
+If unittest, pytest, or the app runner is unavailable, run targeted Python modules, import checks, or framework-specific tests that already exist. Do not create or install a new backend stack without approval.
+
+## Windows Notes
+
+Virtual environment activation is usually `.\\.venv\\Scripts\\Activate.ps1`. If script execution is blocked, use the environment's Python executable directly, for example `.\\.venv\\Scripts\\python.exe -m unittest discover -s tests` or `.\\.venv\\Scripts\\python.exe -m pytest`.