vector-cadence-skills 0.1.0

package/skills/vc-architecture/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: vc-architecture
+description: Improve application code architecture by finding deep-module opportunities, better seams, safer refactor paths, and testability improvements. Use when working on module boundaries, refactor strategy, interface design, architecture friction, or making code more maintainable and agent-navigable. Use vc-harness-architect instead for Vector Cadence/pi harness, subagent, extension, provider, or tool architecture.
+---
+
+# Vector Cadence Architecture
+
+## Purpose
+
+Improve application code architecture. This skill finds friction and proposes deeper modules, clearer seams, safer interfaces, and refactor plans.
+
+## Operating model
+
+Ground architecture recommendations in observed code friction, tests, domain language, and ADRs. Prefer changes that improve locality, leverage, and testability.
+
+## When to use
+
+Use for:
+
+- module boundary problems,
+- refactor strategy,
+- interface/API shape decisions inside an app,
+- hard-to-test code,
+- shallow pass-through modules,
+- tangled responsibility or duplicated invariants.
+
+## When to skip
+
+Skip when:
+
+- the request is about Vector Cadence/pi harness, subagents, extensions, providers, code search, or Taste (`vc-harness-architect`),
+- the user only needs a code map (`vc-orient`),
+- the architecture direction is known and needs planning (`vc-plan`).
+
+## Vocabulary
+
+Use these terms:
+
+- **Module** — anything with an interface and implementation.
+- **Interface** — everything callers must know: types, invariants, errors, ordering, config.
+- **Implementation** — code hidden behind the interface.
+- **Depth** — behavior/leverage hidden behind a smaller interface.
+- **Seam** — where behavior can change without editing callers in place.
+- **Adapter** — concrete implementation at a seam.
+- **Locality** — related change/bugs/knowledge concentrated in one place.
+- **Leverage** — many callers benefit from one deep implementation.
+
+Deletion test: if deleting a module makes complexity vanish, it was likely pass-through; if deleting it spreads complexity across callers, it was earning its keep.
+
+## Workflow
+
+### 1. Explore with domain grounding
+
+Read:
+
+- `CONTEXT.md`,
+- relevant ADRs,
+- project instructions,
+- target code and callers,
+- tests around the area,
+- prior solutions/knowledge if relevant.
+
+### 2. Find friction
+
+Look for:
+
+- shallow modules,
+- concepts spread across many files,
+- tests forced to mock internals,
+- no public seam for real behavior,
+- duplicated invariants,
+- hard-to-reason side effects,
+- leaky interfaces.
+
+### 3. Present candidates
+
+For each candidate include:
+
+- files/modules,
+- observed friction,
+- why the current interface is shallow or leaky,
+- proposed deeper module or seam,
+- locality/leverage benefit,
+- testing improvement,
+- ADR/domain conflicts,
+- recommendation strength: Strong, Worth exploring, or Speculative.
+
+Do not finalize interfaces until the user chooses a candidate.
+
+### 4. Design interface when needed
+
+For a chosen candidate:
+
+1. Gather required behaviors and invariants.
+2. Create 2-3 meaningfully different interface shapes.
+3. Compare depth, misuse risk, testability, migration cost, and domain fit.
+4. Recommend one.
+5. Decide whether an ADR is warranted.
+
+### 5. Plan refactor path
+
+If implementation work should proceed, produce or route to a plan with:
+
+- current friction,
+- desired seam/module,
+- compatibility strategy,
+- characterization tests,
+- vertical migration slices,
+- rollback/stop conditions,
+- docs/ADR updates.
+
+## Output
+
+```markdown
+## Architecture Summary
+
+**Top finding:** ...
+**Recommended direction:** ...
+**Why this improves locality/leverage/testability:** ...
+**Risks:** ...
+**Artifacts to write:** plan | ADR | CONTEXT update | issues
+**Recommended next skill:** vc-plan | vc-slice | vc-execute
+```
+
+## Guardrails
+
+- Do not recommend architecture from taste alone.
+- Do not relitigate ADRs without real friction.
+- Do not create seams only for hypothetical future adapters.
+- Do not confuse product scope decisions with code architecture decisions.
+- Do not use this skill for harness architecture; use `vc-harness-architect`.

package/skills/vc-debug/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: vc-debug
+description: Diagnose and fix bugs with a feedback-loop-first process, environment sanity checks, causal-chain gates, test-first fixes, and structured handoff. Use when handling hard bugs, failing tests, regressions, stack traces, flaky behavior, performance problems, or repeated failed fixes.
+---
+
+# Vector Cadence Debug
+
+## Purpose
+
+Find the root cause before fixing. This skill prevents patching symptoms by requiring a reproduction loop, evidence-backed hypotheses, and a complete causal chain.
+
+## Operating model
+
+Build a fast feedback loop, reproduce the reported symptom, verify environment sanity, test ranked hypotheses one at a time, then fix test-first only after the causal chain is clear.
+
+## When to use
+
+Use for:
+
+- failing tests,
+- stack traces,
+- production or user-reported bugs,
+- regressions,
+- flaky or non-deterministic behavior,
+- performance regressions,
+- “I tried fixes but it still fails”.
+
+## When to skip
+
+Skip when:
+
+- the task is a new feature (`vc-align` or `vc-plan`),
+- root cause is already proven and only implementation remains (`vc-execute`),
+- the user only wants codebase orientation (`vc-orient`).
+
+## Inputs
+
+Use:
+
+- issue or bug report,
+- full comment thread if available,
+- stack traces/logs,
+- reproduction steps,
+- environment details,
+- prior failed attempts,
+- linked PRs/deployments.
+
+## Workflow
+
+### 1. Build the feedback loop
+
+Prefer:
+
+1. failing test at the real seam,
+2. focused command or CLI repro,
+3. HTTP/curl script,
+4. headless browser script,
+5. captured trace replay,
+6. throwaway harness,
+7. fuzz/property loop,
+8. bisection/differential loop,
+9. structured human-in-the-loop script.
+
+The loop should be fast, specific, deterministic or high-reproduction-rate, and agent-runnable. If no loop is possible, stop and ask for missing access/artifacts/setup.
+
+### 2. Verify environment sanity
+
+Check likely false leads:
+
+- branch and uncommitted changes,
+- dependencies,
+- runtime version,
+- env vars,
+- stale build artifacts,
+- local services,
+- config differences.
+
+### 3. Reproduce the real symptom
+
+Confirm the loop matches the user’s reported failure, not a nearby unrelated failure. Capture the exact signal.
+
+### 4. Trace the code path
+
+Trace backward from symptom to where valid state becomes invalid. Use observed values, not assumptions. For performance, measure before changing code.
+
+### 5. Form hypotheses
+
+Create 3-5 ranked hypotheses. Each includes:
+
+- suspected cause and location,
+- supporting observation,
+- causal chain,
+- prediction for uncertain links.
+
+Review what has already been ruled out before forming new hypotheses.
+
+### 6. Probe one variable
+
+Use debugger/REPL, targeted logs, temporary assertions, focused test variations, or bisect/diff probes. Tag temporary logs with a unique prefix and remove them before finishing.
+
+Never “log everything and grep”.
+
+### 7. Pass the causal-chain gate
+
+Do not fix until you can explain:
+
+```text
+trigger → code path → invalid state starts → symptom appears
+```
+
+If stuck after 2-3 hypotheses, diagnose why: wrong mental model, environment mismatch, design problem, contradictory evidence, or insufficient observability.
+
+### 8. Fix test-first
+
+If fixing:
+
+1. Check workspace safety.
+2. Write or keep a failing regression test at the correct seam.
+3. Verify it fails for the right reason.
+4. Apply the minimal root-cause fix.
+5. Verify the test passes.
+6. Re-run the original loop.
+7. Run broader affected tests.
+8. Self-review the diff.
+
+If no correct test seam exists, document that and recommend `vc-architecture` after the immediate fix/diagnosis.
+
+### 9. Cleanup and prevention
+
+Remove debug logs, delete or mark throwaway harnesses, record the confirmed root cause, and offer `vc-learn` only for reusable lessons.
+
+## Output
+
+```markdown
+## Debug Summary
+
+**Problem:** ...
+**Reproduction:** ...
+**Root cause:** ...
+**Causal chain:** ...
+**Fix:** ... or Diagnosis only
+**Tests:** ...
+**Prevention:** ...
+**Confidence:** High | Medium | Low
+**Recommended next skill:** vc-execute | vc-review | vc-architecture | vc-learn
+```
+
+## Guardrails
+
+- Do not hypothesize without a feedback loop unless impossible, and then say so.
+- Do not fix before the causal-chain gate.
+- Do not batch unrelated changes.
+- Do not retry variants of a failed hypothesis without invalidating it.
+- Do not leave instrumentation behind.

package/skills/vc-execute/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: vc-execute
+description: Execute a clear plan, issue, or agent brief with workspace safety, TDD, scoped subagent coordination, continuous verification, and tiered review gates. Use when implementing approved work, running an AFK loop, or turning a plan/issue into tested code.
+---
+
+# Vector Cadence Execute
+
+## Purpose
+
+Implement approved work safely. This skill assumes the target is clear enough to code; if not, route back to alignment, planning, triage, or debugging.
+
+## Operating model
+
+Use branch/worktree safety, task tracking, one-behavior-at-a-time TDD for behavior changes, continuous validation, and scoped subagents only when their file access is safe.
+
+## When to use
+
+Use for:
+
+- implementing a reviewed plan,
+- executing a `ready-for-agent` issue,
+- completing an agent brief,
+- running a bounded AFK implementation loop.
+
+## When to skip
+
+Skip when:
+
+- scope is vague (`vc-align` or `vc-plan`),
+- a bug lacks root cause (`vc-debug`),
+- a human design/security/privacy decision is unresolved,
+- workspace safety cannot be established.
+
+## Inputs
+
+Accept:
+
+- plan path,
+- issue reference,
+- agent brief,
+- small direct task.
+
+## Workflow
+
+### 1. Triage input
+
+Classify:
+
+| Input | Action |
+|---|---|
+| trivial direct edit | implement with focused verification |
+| ready-for-agent issue | execute from brief |
+| plan file | build task list from units |
+| vague/high-risk prompt | route to align/plan |
+| bug without diagnosis | route to debug |
+
+### 2. Check workspace safety
+
+Before editing:
+
+- check branch and uncommitted changes,
+- avoid overwriting user work,
+- avoid committing to default branch unless policy/user permits,
+- prefer feature branch or isolated worktree for non-trivial work.
+
+### 3. Build task list
+
+Preserve source trace:
+
+- U-IDs,
+- requirements,
+- dependencies,
+- execution notes,
+- likely files,
+- test scenarios,
+- verification criteria.
+
+Track progress in the task tracker or summary, not by editing the plan body.
+
+### 4. Choose execution strategy
+
+| Strategy | Use when |
+|---|---|
+| Inline | 1-2 small tasks |
+| Serial subagents | dependent tasks or large context |
+| Parallel read-only subagents | research/review/test probes |
+| Parallel write subagents | isolated worktrees or disjoint file scopes |
+
+If the harness does not provide subagents, execute inline or serially yourself.
+
+Never let shared-checkout subagents stage, commit, or run whole-suite tests concurrently.
+
+### 5. Implement behavior with TDD
+
+For behavior-bearing work:
+
+```text
+choose one behavior
+→ write one failing public-interface test
+→ verify it fails for the right reason
+→ implement minimal code
+→ verify green
+→ repeat
+→ refactor only while green
+```
+
+Test observable behavior through public interfaces. Avoid tests coupled to private implementation. Add integration coverage for callbacks, persistence, permissions, retries, multi-interface parity, and external contract behavior when relevant.
+
+Skip strict test-first for pure styling, mechanical renames, config-only changes, or cases where characterization-first is safer.
+
+### 6. Verify continuously
+
+Before marking a task complete, check:
+
+- what callbacks/middleware/jobs/events fire,
+- whether tests exercise the real chain,
+- whether failure can leave orphaned state,
+- whether other interfaces expose the behavior,
+- whether auth, privacy, payments, or external contracts are touched.
+
+Run focused tests first, then broader affected checks as confidence grows.
+
+### 7. Commit only if allowed
+
+If user/project/harness policy permits commits, commit complete logical units only when tests pass and the message describes real value. Do not create WIP commits or stage unrelated files.
+
+### 8. Apply review gate
+
+| Tier | Gate |
+|---|---|
+| T1 | focused tests + self-review |
+| T2 | affected tests + lightweight review |
+| T3 | broader validation + security/correctness/performance review + human pause before merge |
+
+## Stop conditions
+
+Stop when:
+
+- acceptance criteria are ambiguous,
+- three fix attempts fail,
+- tests fail for unknown reasons after focused diagnosis,
+- implementation reveals an unplanned product/architecture decision,
+- subagent outputs conflict or risk lost work,
+- high-risk behavior differs from the plan.
+
+## Output
+
+```markdown
+## Execution Summary
+
+**Implemented:** ...
+**Source:** ...
+**Tests run:** ...
+**Review gate:** ...
+**Commits:** ...
+**Open risks / follow-ups:** ...
+**Recommended next skill:** vc-review | vc-learn
+```
+
+## Guardrails
+
+- Do not code from vague intent.
+- Do not refactor while tests are red.
+- Do not let subagents write overlapping files in one checkout.
+- Do not leave debug/prototype artifacts unmarked.
+- Do not claim validation passed unless it did.

package/skills/vc-handoff/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: vc-handoff
+description: Compact session, plan, debug, review, implementation, or subagent state into a durable handoff for another agent or future session. Use when pausing work, switching agents, context is getting full, resuming later, or preparing bounded subagent/orchestrator context.
+---
+
+# Vector Cadence Handoff
+
+## Purpose
+
+Transfer useful state without dumping the whole conversation. A fresh agent should know what happened, what matters, and exactly what to do next.
+
+## Operating model
+
+Reference existing artifacts instead of duplicating them, preserve failed attempts, redact sensitive data, and end with a concrete next action.
+
+## When to use
+
+Use when:
+
+- context is getting full,
+- switching agents or harnesses,
+- pausing work,
+- handing review findings to a resolver,
+- preparing a subagent brief,
+- leaving a debug or implementation session mid-stream.
+
+## When to skip
+
+Skip when:
+
+- the task is complete and summarized normally,
+- there are no decisions, artifacts, or next actions worth preserving,
+- a source artifact already fully captures the state.
+
+## Handoff types
+
+| Type | Use for |
+|---|---|
+| Alignment | after alignment before planning |
+| Plan | after planning before execution |
+| Execution | mid-implementation |
+| Debug | diagnosis or stuck investigation |
+| Review | unresolved findings |
+| Harness | agent/tool/harness decisions |
+| Subagent brief | bounded delegated task |
+
+## Workflow
+
+### 1. Gather state
+
+Collect only what matters:
+
+- user goal,
+- current branch/worktree,
+- relevant artifact paths,
+- decisions made,
+- open questions,
+- files changed or relevant,
+- tests/commands run and results,
+- blockers,
+- next recommended action.
+
+### 2. Redact and de-risk
+
+Remove secrets, tokens, PII, private customer data, raw sensitive logs, and irrelevant conversation. Reference secure locations instead of copying sensitive details.
+
+### 3. Write compact handoff
+
+Default local path:
+
+```text
+docs/handoffs/YYYY-MM-DD-<slug>-handoff.md
+```
+
+If temporary-only is requested, provide in chat or outside the repo.
+
+## Templates
+
+### General handoff
+
+```markdown
+# Handoff — <topic>
+
+## Goal
+## Current state
+## Decisions made
+## Artifacts
+## Files changed / relevant
+## Validation so far
+## Open questions / blockers
+## Next recommended action
+## Warnings
+```
+
+### Subagent brief
+
+```markdown
+# Subagent Brief — <task>
+
+## Role
+## Task
+## Context artifacts
+## Allowed tools / permissions
+## Files in scope
+## Files out of scope
+## Output contract
+## Constraints
+```
+
+## Output
+
+```markdown
+## Handoff Ready
+
+**Path:** ... or provided in chat
+**Type:** ...
+**Next action:** ...
+**Risks:** ...
+**Recommended next skill:** depends on handoff type
+```
+
+## Guardrails
+
+- Do not duplicate large artifacts already saved.
+- Do not include secrets or raw private data.
+- Do not hide failed attempts.
+- Do not produce a vague “continue from here” handoff.

package/skills/vc-harness-architect/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: vc-harness-architect
+description: Design or evolve the Vector Cadence/pi harness, including wrapper CLI, extensions, subagents, provider/cache strategy, skill injection, code search, permission gates, and optional Taste integration. Use when working on harness architecture rather than application code architecture; use vc-architecture for app modules and refactors.
+---
+
+# Vector Cadence Harness Architect
+
+## Purpose
+
+Design the Vector Cadence/pi harness and its extension ecosystem. This skill handles tool/runtime architecture, not ordinary application feature work.
+
+## Operating model
+
+Prefer a thin pi-first wrapper, modular packages, primitive extension tools, read-only subagents first, explicit privacy boundaries, and measurement before performance/cache claims.
+
+## When to use
+
+Use for:
+
+- Vector Cadence CLI/wrapper design,
+- skill injection strategy,
+- pi extensions,
+- subagent runtime design,
+- DeepSeek/provider/cache telemetry,
+- code search tools,
+- permission gates,
+- optional Taste/preference integration,
+- harness tests and packaging.
+
+## When to skip
+
+Skip when:
+
+- improving application module boundaries (`vc-architecture`),
+- implementing a planned harness slice (`vc-execute`),
+- writing a prompt-only skill (`vc-skill-author`).
+
+## Default package architecture
+
+```text
+@your-scope/vc-core        # shared types/config/utils
+@your-scope/vc-skills      # markdown skills
+@your-scope/vc-extensions  # pi extensions/tools
+@your-scope/vc-cli         # thin wrapper CLI
+```
+
+Use bare pi as substrate. Borrow little-coder patterns. Avoid a deep fork unless extension/wrapper paths cannot support the requirement.
+
+## Workflow
+
+### 1. Classify harness area
+
+| Area | Examples |
+|---|---|
+| Wrapper CLI | launch, config, curated/composable flags |
+| Skill injection | selection, prompt chunks, stable ordering |
+| Subagents | RPC subprocess, SDK child session, external service |
+| Provider/cache | DeepSeek config, telemetry, Reasonix boundary |
+| Code search | regex, symbol index, semantic search |
+| Taste/preferences | explicit commands, optional prompt summary |
+| Permission gates | approvals, filesystem scopes, dangerous commands |
+| Testing | fake pi objects, extension registration, CLI smoke tests |
+
+### 2. Choose integration level
+
+| Need | Proper layer |
+|---|---|
+| instructions/checklist | skill package |
+| deterministic helper | script |
+| new tool/behavior | extension package |
+| install/default UX | wrapper CLI |
+| cache-first request construction | harness core, SDK loop, or backend |
+
+Do not solve extension problems with markdown-only instructions.
+
+### 3. Apply agent-native checks
+
+Evaluate:
+
+- action parity,
+- primitive tool granularity,
+- composability,
+- dynamic context injection,
+- shared workspace/files,
+- completion signals,
+- permission and approval gates,
+- recovery/resume,
+- agent-native tests.
+
+### 4. Design subagents safely
+
+Default rollout:
+
+1. read-only research/review,
+2. test-running with bounded commands,
+3. serial implementation,
+4. parallel write only with isolated worktrees or disjoint file scopes.
+
+Parent orchestrator owns final merge, validation, conflict handling, and user summary.
+
+### 5. Design provider/cache features honestly
+
+DeepSeek/Reasonix strategy should progress from provider support to telemetry to prompt stability to optional Reasonix backend. Do not promise Reasonix-level prefix-cache behavior without loop-level control and measured telemetry.
+
+### 6. Plan tests
+
+At minimum verify:
+
+- extension registration,
+- schema stability,
+- permission enforcement,
+- timeout/cancellation,
+- output contracts,
+- CLI help/config loading,
+- curated/composable behavior.
+
+## Output
+
+```markdown
+## Harness Architecture Recommendation
+
+**Area:** ...
+**Integration level:** skill | script | extension | wrapper | SDK loop | backend
+**Recommended design:** ...
+**Why:** ...
+**Risks:** ...
+**First vertical slice:** ...
+**Tests:** ...
+**Recommended next skill:** vc-plan | vc-skill-author | vc-execute
+```
+
+## Guardrails
+
+- Do not fork pi/little-coder unless extension/wrapper paths cannot work.
+- Do not allow parallel write subagents in one checkout.
+- Do not imply markdown skills can create tools by themselves.
+- Do not send Taste/telemetry data without opt-in.
+- Do not vary stable prompt prefixes unnecessarily in DeepSeek mode.