vector-cadence-skills 0.1.0

package/references/minimal-mode.md

@@ -0,0 +1,50 @@
+# Minimal Vector Cadence Mode
+
+Vector Cadence should not feel heavy for small tasks. Use the minimum process that makes the work safe.
+
+## For tiny known changes
+
+```text
+vc-execute → optional vc-review
+```
+
+Examples:
+
+- copy tweak,
+- obvious one-file bug,
+- mechanical rename,
+- small config change with known validation.
+
+## For unfamiliar code
+
+```text
+vc-orient → vc-execute → optional vc-review
+```
+
+Use orientation only long enough to avoid guessing.
+
+## For meaningful features
+
+```text
+vc-align → vc-plan → vc-execute → vc-review → optional vc-learn
+```
+
+Add `vc-slice` and `vc-triage` when work becomes a queue of issues or AFK tasks.
+
+## For bugs
+
+```text
+vc-debug → vc-execute → vc-review → optional vc-learn
+```
+
+Do not start with planning when the root cause is unknown.
+
+## When not to use the full lifecycle
+
+Skip full Vector Cadence for:
+
+- typos,
+- formatting-only changes,
+- obvious dependency bumps,
+- throwaway experiments,
+- changes where the user supplied exact instructions and validation is clear.

package/references/source-integration-map.md

@@ -0,0 +1,159 @@
+# Source Integration Map
+
+This document explains which upstream skill ideas were preserved, replaced, or integrated in the Vector Cadence skill suite.
+
+## Summary table
+
+| Vector Cadence skill | Pocock source | Compound source | Decision |
+|---|---|---|---|
+| `vc-setup` | `setup-matt-pocock-skills` | `ce-setup`, `ce-work` assumptions | Integrate |
+| `vc-orient` | `zoom-out` | repo research agents | Integrate, Pocock lightweight posture |
+| `vc-align` | `grill-me`, `grill-with-docs`, `ubiquitous-language` | `ce-brainstorm`, `ce-strategy` ideas | Integrate, Compound shell + Pocock discipline |
+| `vc-plan` | `to-prd`, architecture/testability prompts | `ce-plan`, `ce-doc-review` | Compound base, Pocock quality bar |
+| `vc-slice` | `to-issues` | plan U-IDs/test scenarios | Pocock base, Compound metadata |
+| `vc-triage` | `triage` | issue/debug handoff patterns | Pocock base, Vector Cadence gates |
+| `vc-prototype` | `prototype` | frontend proof/demo ideas | Pocock base |
+| `vc-execute` | `tdd` | `ce-work` | Compound shell + Pocock inner loop |
+| `vc-debug` | `diagnose` | `ce-debug` | Integrated equally |
+| `vc-review` | `review` Standards-vs-Spec | `ce-code-review`, `ce-doc-review` | Compound base |
+| `vc-architecture` | `improve-codebase-architecture`, `design-an-interface` | `ce-agent-native-architecture`, `ce-agent-native-audit` | Route by architecture type |
+| `vc-learn` | ADR/glossary discipline | `ce-compound`, `ce-compound-refresh` | Compound base, Pocock artifact discipline |
+| `vc-handoff` | `handoff` | workflow handoffs | Pocock base, Compound trace IDs |
+| `vc-harness-architect` | setup/TDD/vertical-slice habits | agent-native architecture | Compound + harness strategy |
+| `vc-skill-author` | `write-a-skill` | package/harness needs | Pocock base |
+
+## Key integration decisions
+
+### 1. Alignment is not planning
+
+Pocock grilling and Compound brainstorming both live upstream, but they answer slightly different questions.
+
+- Compound asks: what are we building and why?
+- Pocock asks: are we using the right concepts and have we resolved the hard branches?
+
+Vector Cadence Align integrates these into one alignment workflow. It does not immediately create implementation units. That is planning’s job.
+
+### 2. Planning uses Compound structure, not Pocock PRD as-is
+
+Pocock `to-prd` is strong at synthesizing conversation into a product doc, but Compound `ce-plan` is stronger for technical handoff because it includes:
+
+- U-IDs,
+- repo-relative files,
+- test scenarios,
+- dependencies,
+- implementation posture,
+- verification criteria.
+
+Vector Cadence Plan therefore uses Compound as the shell. Pocock contributes domain grounding, no-code planning discipline, public-interface testing bias, and deep-module awareness.
+
+### 3. Issue slicing remains Pocock-dominant
+
+Compound implementation units are not the same as issue tracker slices. An implementation unit can be atomic but still not independently shippable.
+
+Pocock `to-issues` has the stronger rule: every issue should be a tracer bullet through the system.
+
+Vector Cadence Slice therefore uses Pocock as the base and imports Compound metadata from plans.
+
+### 4. Execution uses Compound orchestration but Pocock TDD
+
+Compound `ce-work` is the better executor because it handles:
+
+- branch/worktree setup,
+- task lists,
+- subagent strategies,
+- incremental commits,
+- continuous tests,
+- shipping workflow.
+
+But Pocock `tdd` has the better coding discipline:
+
+- one behavior at a time,
+- public interface tests,
+- no horizontal test/code phases,
+- refactor only while green.
+
+Vector Cadence Execute embeds Pocock TDD inside Compound orchestration.
+
+### 5. Debugging needs both sources
+
+Pocock `diagnose` has the strongest feedback-loop-first message: build a deterministic loop or stop.
+
+Compound `ce-debug` has the strongest causal-chain and environment discipline.
+
+Vector Cadence Debug combines them because a feedback loop without causal rigor can still patch symptoms, and causal rigor without a loop can become code-reading theater.
+
+### 6. Review is Compound-dominant
+
+Compound `ce-code-review` is much more operationally complete than Pocock review:
+
+- personas,
+- severity,
+- confidence,
+- deduplication,
+- validators,
+- autofix routing,
+- residual handoff.
+
+Pocock’s useful contribution is the Standards-vs-Spec lens. Vector Cadence Review preserves that lens while using Compound’s machinery.
+
+### 7. Architecture is split by problem type
+
+Pocock wins for normal code architecture because the deep-module vocabulary is precise and actionable.
+
+Compound wins for agent-native/harness architecture because it has concepts Pocock does not cover:
+
+- action parity,
+- primitive tools,
+- dynamic context injection,
+- shared workspace,
+- agent-native testing,
+- self-modification.
+
+Vector Cadence Architecture routes instead of forcing one framework to cover both.
+
+### 8. Learning is Compound-dominant but artifact-disciplined
+
+Compound’s compounding system is the best source for solved-problem memory.
+
+But without Pocock’s artifact discipline, it can bloat docs. Vector Cadence Learn keeps:
+
+- domain terms in `CONTEXT.md`,
+- decisions in ADRs,
+- solved problems in `docs/solutions/`,
+- lifecycle reality in `docs/knowledge/`,
+- trivial work undocumented.
+
+## What was intentionally not copied
+
+### Deprecated Pocock skills as standalone commands
+
+- `ubiquitous-language` was folded into `vc-align` and `vc-setup` using `CONTEXT.md`.
+- `design-an-interface` was folded into `vc-architecture` as a subroutine.
+- `request-refactor-plan` was folded into `vc-architecture` + `vc-plan` + `vc-slice`.
+
+### Compound specialty skills not needed yet
+
+Many Compound skills are valuable but not part of the initial integrated suite:
+
+- release notes,
+- Slack research,
+- demo reels,
+- Xcode/browser specialty tests,
+- Rails-specific style,
+- beta dogfood flows,
+- image generation,
+- product pulse.
+
+They can remain optional extensions later. Including all of them now would recreate the “pile of blocks” problem.
+
+## Design rule for future additions
+
+Before adding a new Vector Cadence skill, answer:
+
+1. Is this a distinct lifecycle responsibility?
+2. Does it need a new user-facing command, or is it a subroutine of an existing skill?
+3. Is it prompt-only, extension-backed, or wrapper-level?
+4. What artifact does it read or write?
+5. What upstream skill discipline is actually better for this responsibility?
+
+If the answer is “it is just another checklist,” do not add a top-level skill.

package/references/subagent-policy.md

@@ -0,0 +1,30 @@
+# Vector Cadence Subagent Policy
+
+Subagents are a harness capability, not a markdown-only feature.
+
+## Rollout stages
+
+1. Read-only research/review subagents.
+2. Test-running subagents with bounded commands.
+3. Serial implementation subagents.
+4. Parallel write subagents with isolated worktrees or disjoint file scopes.
+
+## Rules
+
+- Parent orchestrator owns final merge and final validation.
+- Review/research subagents are read-only by default.
+- Shared-checkout subagents must not stage, commit, or run whole-suite tests concurrently.
+- Parallel write subagents require isolation or provably disjoint scopes.
+- Every subagent needs a bounded task and output contract.
+
+## Suggested output contract
+
+```json
+{
+  "status": "success | failed | timeout",
+  "summary": "...",
+  "filesTouched": [],
+  "evidence": [],
+  "rawLogPath": "..."
+}
+```

package/references/tiering.md

@@ -0,0 +1,23 @@
+# Vector Cadence Tiering
+
+Tiering matches process and cost to risk.
+
+| Tier | Use for | Process |
+|---|---|---|
+| T1 | known, low-risk, small blast radius | lean execution and focused validation |
+| T2 | moderate ambiguity or unfamiliar area | alignment, plan, focused research, review gate |
+| T3 | high-risk or cross-cutting | gated deep research, doc review, human pause, deep review |
+
+## T3 signals
+
+- auth or permissions,
+- payments or billing,
+- PII, privacy, or compliance,
+- data migrations or backfills,
+- public APIs or CLI contracts,
+- multi-service behavior,
+- harness agent loop,
+- subagent write behavior,
+- cache-first provider architecture.
+
+Do not over-process T1 work. Do not under-research T3 work.

package/scripts/validate-skills.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(scriptDir, "..");
+const indexPath = path.join(root, "skills.json");
+const errors = [];
+const warnings = [];
+
+function read(file) {
+  return fs.readFileSync(file, "utf8");
+}
+
+function exists(file) {
+  return fs.existsSync(file);
+}
+
+function rel(file) {
+  return path.relative(root, file).replaceAll(path.sep, "/");
+}
+
+function parseFrontmatter(text, file) {
+  const normalized = text.replace(/^\uFEFF/, "").replaceAll("\r\n", "\n");
+  if (!normalized.startsWith("---\n")) {
+    errors.push(`${rel(file)}: missing opening frontmatter delimiter`);
+    return null;
+  }
+  const end = normalized.indexOf("\n---\n", 4);
+  if (end === -1) {
+    errors.push(`${rel(file)}: missing closing frontmatter delimiter`);
+    return null;
+  }
+  const raw = normalized.slice(4, end).trim();
+  const data = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) {
+      errors.push(`${rel(file)}: invalid frontmatter line: ${line}`);
+      continue;
+    }
+    data[match[1]] = match[2].trim().replace(/^['"]|['"]$/g, "");
+  }
+  return data;
+}
+
+function checkLinks(file, text) {
+  const dir = path.dirname(file);
+  const linkPattern = /\[[^\]]+\]\(([^)]+)\)/g;
+  for (const match of text.matchAll(linkPattern)) {
+    const target = match[1].trim();
+    if (!target || target.startsWith("#") || /^[a-z]+:/i.test(target)) continue;
+    const clean = target.split("#")[0];
+    if (!clean) continue;
+    const resolved = path.resolve(dir, clean);
+    if (!exists(resolved)) {
+      errors.push(`${rel(file)}: broken link to ${target}`);
+    }
+  }
+}
+
+if (!exists(indexPath)) {
+  errors.push("skills.json missing");
+} else {
+  let index;
+  try {
+    index = JSON.parse(read(indexPath));
+  } catch (error) {
+    errors.push(`skills.json invalid JSON: ${error.message}`);
+  }
+  if (index) {
+    if (!Array.isArray(index.skills))
+      errors.push("skills.json: skills must be an array");
+    for (const entry of index.skills || []) {
+      if (!entry.name || !entry.path) {
+        errors.push("skills.json: every skill entry needs name and path");
+        continue;
+      }
+      const file = path.join(root, entry.path);
+      if (!exists(file)) {
+        errors.push(`skills.json: missing ${entry.path}`);
+        continue;
+      }
+      const dirName = path.basename(path.dirname(file));
+      if (dirName !== entry.name) {
+        errors.push(
+          `${entry.path}: directory name ${dirName} does not match index name ${entry.name}`,
+        );
+      }
+    }
+  }
+}
+
+const skillsRoot = path.join(root, "skills");
+const skillFiles = fs
+  .readdirSync(skillsRoot, { withFileTypes: true })
+  .filter((d) => d.isDirectory())
+  .map((d) => path.join(skillsRoot, d.name, "SKILL.md"));
+
+if (skillFiles.length === 0) errors.push("No vc-*/SKILL.md files found");
+
+const bannedRuntimePatterns = [
+  {
+    pattern: /Integrated source decision/i,
+    label: "Integrated source decision",
+  },
+  { pattern: /\/ce-[A-Za-z0-9_-]+/, label: "legacy /ce-* command" },
+  { pattern: /\/grill-with-docs|\/grill-me/, label: "legacy grill command" },
+  {
+    pattern: /\/to-issues|\/to-prd|\/triage|\/tdd|\/diagnose/,
+    label: "legacy Pocock slash command",
+  },
+  {
+    pattern: /\/vc-spec|\/vc-run|\/vc-judge/,
+    label: "old Vector Cadence command name",
+  },
+];
+
+for (const file of skillFiles) {
+  if (!exists(file)) {
+    errors.push(`${rel(file)} missing`);
+    continue;
+  }
+  const text = read(file);
+  const lines = text.split(/\r?\n/).length;
+  const fm = parseFrontmatter(text, file);
+  const dirName = path.basename(path.dirname(file));
+
+  if (fm) {
+    if (fm.name !== dirName)
+      errors.push(
+        `${rel(file)}: name ${fm.name || "<missing>"} does not match directory ${dirName}`,
+      );
+    if (!fm.description) errors.push(`${rel(file)}: missing description`);
+    if (fm.description && fm.description.length > 1024)
+      errors.push(`${rel(file)}: description exceeds 1024 chars`);
+    if (fm.description && !/Use when/i.test(fm.description))
+      warnings.push(
+        `${rel(file)}: description should include "Use when" trigger language`,
+      );
+  }
+
+  if (lines > 170)
+    warnings.push(
+      `${rel(file)}: ${lines} lines; consider shortening below 170`,
+    );
+  if (!/^## Purpose/m.test(text))
+    warnings.push(`${rel(file)}: missing ## Purpose`);
+  if (!/^## When to use/m.test(text))
+    warnings.push(`${rel(file)}: missing ## When to use`);
+  if (!/^## When to skip/m.test(text))
+    warnings.push(`${rel(file)}: missing ## When to skip`);
+  if (!/^## Workflow/m.test(text))
+    warnings.push(`${rel(file)}: missing ## Workflow`);
+  if (!/^## Output/m.test(text))
+    warnings.push(`${rel(file)}: missing ## Output`);
+  if (!/^## Guardrails/m.test(text))
+    warnings.push(`${rel(file)}: missing ## Guardrails`);
+
+  for (const { pattern, label } of bannedRuntimePatterns) {
+    if (pattern.test(text))
+      errors.push(`${rel(file)}: banned runtime phrase found: ${label}`);
+  }
+
+  checkLinks(file, text);
+}
+
+for (const file of fs.readdirSync(root, { recursive: true })) {
+  const full = path.join(root, file.toString());
+  if (exists(full) && fs.statSync(full).isFile() && full.endsWith(".md")) {
+    checkLinks(full, read(full));
+  }
+}
+
+console.log(`Checked ${skillFiles.length} skills.`);
+if (warnings.length) {
+  console.log(`\nWarnings (${warnings.length}):`);
+  for (const warning of warnings) console.log(`- ${warning}`);
+}
+if (errors.length) {
+  console.error(`\nErrors (${errors.length}):`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+console.log("\nValidation passed.");

package/skills/vc-align/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: vc-align
+description: Align feature, fix, refactor, or harness intent before technical planning by clarifying scope, domain language, risks, and rejected alternatives. Use when starting meaningful work, when scope is fuzzy, when terminology matters, or when a plan needs pressure-testing before implementation.
+---
+
+# Vector Cadence Align
+
+## Purpose
+
+Clarify what should be built and why before technical planning begins. This skill turns fuzzy intent into shared product/domain understanding, without writing implementation code.
+
+## Operating model
+
+Use a right-sized alignment conversation: inspect existing code/docs first, ask one focused question at a time, sharpen domain language, compare real alternatives, and capture both clean requirements and messy guardrails.
+
+## When to use
+
+Use for:
+
+- new features or meaningful product changes,
+- non-trivial fixes where expected behavior is unclear,
+- refactors with user-visible or architectural consequences,
+- harness, tool, provider, or subagent design ideas,
+- requests like “grill this”, “stress-test this”, “is this architecture right?”, or “help me scope this”.
+
+## When to skip
+
+Skip or keep extremely lightweight for:
+
+- typos and mechanical edits,
+- obvious one-file changes,
+- work with an already reviewed requirements document,
+- bugs that first need root-cause diagnosis with `vc-debug`.
+
+## Inputs
+
+Use what exists:
+
+- user prompt or issue,
+- `STRATEGY.md`,
+- `CONTEXT.md` or `CONTEXT-MAP.md`,
+- relevant ADRs,
+- previous requirements/plans/knowledge docs,
+- code paths that can verify claims.
+
+## Workflow
+
+### 1. Classify depth
+
+| Depth | Signals | Behavior |
+|---|---|---|
+| Lightweight | clear low-risk change | short scan, 0-2 questions, concise summary |
+| Standard | feature or meaningful ambiguity | context scan, pressure test, requirements/align notes |
+| Deep | architecture, security, privacy, payments, harness loop | deeper alternatives, explicit risks, ADR candidates |
+
+### 2. Scan existing context
+
+Before asking, inspect what the repo can answer:
+
+1. Read strategy if present.
+2. Read domain glossary and relevant ADRs.
+3. Search for similar code or artifacts.
+4. Verify checkable claims in code.
+5. Label anything inferred or unverified.
+
+Never ask the user a question the repo can answer.
+
+### 3. Pressure-test the idea
+
+Probe only gaps that actually exist:
+
+- evidence: what proves this matters?
+- specificity: who exactly benefits?
+- counterfactual: what happens if nothing ships?
+- attachment: is the proposed shape the smallest useful shape?
+- durability: what future shift could break this bet?
+
+Ask one question at a time. Provide a recommended answer when useful.
+
+### 4. Explore alternatives
+
+When multiple directions are plausible, present 2-3 concrete approaches that differ in product or mechanism shape. For each, include:
+
+- what it is,
+- when it works best,
+- what it simplifies,
+- what it complicates,
+- risks or unknowns.
+
+Then recommend one and ask for confirmation.
+
+### 5. Capture decisions
+
+Write only artifacts that earn their carrying cost:
+
+- update `CONTEXT.md` for durable domain terms only,
+- offer an ADR only for hard-to-reverse, surprising, trade-off decisions,
+- write `docs/align-notes/<slug>-grilled.md` for rejected alternatives, anxiety points, assumptions, and open questions,
+- write `docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md` when durable requirements are useful.
+
+## Output
+
+End with:
+
+```markdown
+## Alignment Summary
+
+**Intent:** ...
+**Target user / actor:** ...
+**Success looks like:** ...
+**Chosen approach:** ...
+**Rejected alternatives:** ...
+**Key risks / assumptions:** ...
+**Artifacts updated:** ...
+**Recommended next skill:** vc-plan | vc-prototype | vc-debug
+```
+
+## Guardrails
+
+- Do not write implementation code.
+- Do not turn `CONTEXT.md` into a spec or task list.
+- Do not create ADRs for obvious or reversible choices.
+- Do not publish issues from this skill.
+- Preserve messy guardrails in align notes instead of flattening them into clean requirements.