vector-cadence-skills 0.1.0

package/skills/vc-learn/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: vc-learn
+description: Capture durable lessons after verified work so future agents can reuse solved problems, conventions, decisions, and implementation reality. Use when finishing non-trivial bug fixes, shipped features, refactors, architecture decisions, harness improvements, or review findings with reusable lessons.
+---
+
+# Vector Cadence Learn
+
+## Purpose
+
+Make future work cheaper and safer by capturing only reusable lessons. This skill prevents both knowledge loss and documentation spam.
+
+## Operating model
+
+Write learning only when the problem is solved or diagnosed, the lesson is reusable, overlap has been checked, and the right artifact type is clear.
+
+## When to use
+
+Use after:
+
+- hard bug diagnosis/fix,
+- non-obvious implementation pattern,
+- feature shipped with lessons,
+- architecture decision,
+- harness/tool/subagent integration,
+- systemic review finding.
+
+## When to skip
+
+Skip when:
+
+- the fix is trivial,
+- the solution is unverified,
+- no reusable lesson can be stated in one sentence,
+- an existing doc already covers it and needs no update.
+
+## Inputs
+
+Use:
+
+- execution/debug/review summary,
+- commits/diff,
+- tests added,
+- linked issue/plan/requirements,
+- existing `docs/solutions/`, `docs/knowledge/`, ADRs, and `CONTEXT.md`.
+
+## Reusable lesson gate
+
+Do not write a learning doc unless the lesson can be stated in one sentence and is likely to be searched for later.
+
+Good:
+
+> Webhook handlers must use provider event ID as the idempotency key, not invoice ID.
+
+Bad:
+
+> Fixed bug in webhook handler.
+
+## Artifact routing
+
+| Lesson type | Artifact |
+|---|---|
+| domain term | `CONTEXT.md` |
+| durable trade-off | ADR |
+| solved technical problem | `docs/solutions/<category>/<slug>.md` |
+| feature lifecycle reality | `docs/knowledge/<feature>.md` |
+| global agent convention | `AGENTS.md` |
+| recurring rejected idea | `.out-of-scope/<slug>.md` |
+
+## Workflow
+
+### 1. Gather evidence
+
+Read source artifacts and actual changes. Do not write from memory alone.
+
+### 2. Check overlap
+
+Search for similar docs by symptom, root cause, framework, module, and pattern. Update or consolidate existing docs when overlap is high.
+
+### 3. Choose artifact
+
+Pick the narrowest artifact that answers the future question. Do not collapse glossary, ADR, solution, and feature lifecycle information into one document.
+
+### 4. Write concise learning
+
+Solution docs should include:
+
+- symptom,
+- root cause,
+- working solution,
+- why it works,
+- tests/verification,
+- prevention,
+- related files/docs,
+- search keywords.
+
+### 5. Update instructions sparingly
+
+Update `AGENTS.md` only for conventions every future agent should follow. Link to detailed docs instead of embedding long narratives.
+
+### 6. Refresh stale docs when needed
+
+If docs drift or overlap, keep, update, consolidate, replace, or delete after checking retrieval value and inbound links.
+
+## Output
+
+```markdown
+## Learning Summary
+
+**Captured:** yes | no
+**Lesson:** ...
+**Artifacts changed:** ...
+**Overlap handled:** none | updated | consolidated | superseded
+**Future retrieval keywords:** ...
+**Recommended next skill:** none | vc-align
+```
+
+## Guardrails
+
+- Do not document trivial work.
+- Do not put implementation decisions in `CONTEXT.md`.
+- Do not create ADRs unless the sparse ADR rule passes.
+- Do not preserve stale docs just because deletion feels risky.
+- Do not write multiple draft docs from subagents; write one final artifact.

package/skills/vc-orient/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: vc-orient
+description: Map a codebase area and explain how it fits the system using code, tests, domain docs, ADRs, and prior knowledge. Use when the user is unfamiliar with code, an agent seems too deep in details, or planning/debugging needs a verified system map.
+---
+
+# Vector Cadence Orient
+
+## Purpose
+
+Create a read-only map of a code area so later alignment, planning, debugging, or implementation starts from reality instead of guesses.
+
+## Operating model
+
+Read code first, docs second. Separate verified facts from inferred patterns, stale-doc claims, and unknowns.
+
+## When to use
+
+Use when:
+
+- the user asks how something works,
+- the agent is editing without enough system context,
+- planning needs a local map,
+- debugging needs data/control flow,
+- architecture review needs candidate areas,
+- onboarding to a module.
+
+## When to skip
+
+Skip when:
+
+- the user already provided enough context,
+- the task is a clear small edit,
+- the user wants implementation now and orientation would add no value.
+
+## Inputs
+
+Subject can be:
+
+- file path,
+- symbol/class/function,
+- feature name,
+- domain term,
+- issue/plan requirement,
+- error path.
+
+## Workflow
+
+### 1. Identify subject
+
+If ambiguous, ask one clarifying question or start with the most likely subject and label uncertainty.
+
+### 2. Read in priority order
+
+1. Code around the subject.
+2. Callers/callees and adjacent modules.
+3. Tests exercising the subject.
+4. `CONTEXT.md` terms.
+5. Relevant ADRs.
+6. Knowledge/solution docs if relevant.
+7. Project instructions.
+
+### 3. Build the map
+
+Explain:
+
+- responsibility and non-responsibility,
+- key files/modules,
+- public interfaces and seams,
+- data/control flow,
+- important invariants,
+- tests and verification paths,
+- known risks or historical lessons,
+- likely extension points.
+
+### 4. Label confidence
+
+Separate:
+
+- verified from code,
+- inferred from naming/patterns,
+- stated in docs but not verified,
+- unknown.
+
+## Output
+
+```markdown
+## Orientation Map
+
+**Subject:** ...
+**Responsibility:** ...
+**Key files:** ...
+**Public interfaces / seams:** ...
+**Data/control flow:** ...
+**Domain terms:** ...
+**Relevant tests:** ...
+**Relevant ADRs/knowledge:** ...
+**Risks / gotchas:** ...
+**What to read next:** ...
+**Recommended next skill:** vc-align | vc-plan | vc-architecture | vc-debug
+```
+
+## Guardrails
+
+- Do not mutate files.
+- Do not summarize from docs before reading code.
+- Do not produce giant file inventories unless asked.
+- Do not hide uncertainty.
+- Do not create durable docs unless the user asks or future retrieval value is clear.

package/skills/vc-plan/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: vc-plan
+description: Convert aligned intent into an implementation-ready technical plan with right-sized research, traceable units, file paths, test scenarios, and verification criteria. Use when alignment is complete or when the user asks for a technical plan, PRD-to-plan conversion, implementation strategy, or plan deepening.
+---
+
+# Vector Cadence Plan
+
+## Purpose
+
+Create a technical plan that an implementer can execute confidently. Planning captures decisions, files, dependencies, risks, and test scenarios; it does not write production code.
+
+## Operating model
+
+Use local code research first, add external or multi-agent research only when risk justifies it, and synthesize strategy, domain language, and alignment notes into a portable plan.
+
+## When to use
+
+Use for:
+
+- converting requirements into implementation strategy,
+- planning T2/T3 work,
+- scoping refactors or integrations,
+- preparing work for slicing or execution,
+- deepening an existing plan.
+
+## When to skip
+
+Skip when:
+
+- the user only needs orientation (`vc-orient`),
+- the bug lacks root cause (`vc-debug`),
+- the task is trivial and safe to execute directly,
+- product scope is still unresolved (`vc-align`).
+
+## Inputs
+
+Prefer, in order:
+
+1. requirements doc from alignment,
+2. align notes,
+3. `STRATEGY.md`,
+4. `CONTEXT.md` / `CONTEXT-MAP.md`,
+5. relevant ADRs,
+6. issue/PR/user prompt,
+7. codebase research.
+
+## Workflow
+
+### 1. Classify tier
+
+| Tier | Use for | Research |
+|---|---|---|
+| T1 | known, low-risk work | local scan |
+| T2 | moderate ambiguity, unfamiliar module, integration | local + focused research |
+| T3 | architecture, security, privacy, payments, migrations, harness loop | gated deep research |
+
+Ask before expensive T3 research when the harness has cost implications.
+
+### 2. Gather context
+
+Always inspect:
+
+- relevant modules and public interfaces,
+- nearby tests,
+- project instructions,
+- domain glossary and ADRs,
+- existing plans/solutions/knowledge docs,
+- similar implementations.
+
+Use external research only when local patterns are thin or the topic is high-risk.
+
+### 3. Resolve planning-time questions
+
+Separate:
+
+- planning-time decisions that affect architecture, scope, sequencing, or risk,
+- implementation-time discoveries such as final helper names or exact query shape.
+
+Ask the user only for planning-time decisions that cannot be responsibly inferred.
+
+### 4. Write implementation units
+
+Use stable unit IDs:
+
+```markdown
+### U1. Add saved-search creation path
+```
+
+For each feature-bearing unit include:
+
+- **Goal**
+- **Requirements**
+- **Dependencies**
+- **Files** — repo-relative paths only
+- **Approach** — decisions and boundaries, not code
+- **Execution note** — optional test-first/characterization-first/migration-safe signal
+- **Patterns to follow**
+- **Test scenarios** — happy, edge, error, integration as applicable
+- **Verification** — outcome-based completion signal
+
+Do not turn units into micro-steps or code instructions.
+
+### 5. Check vertical-slice readiness
+
+Mark whether units are:
+
+- independently shippable vertical slices,
+- supporting preparatory units,
+- HITL decision units,
+- risk-reduction prototypes.
+
+This prepares `vc-slice` to create good issues.
+
+### 6. Review before writing
+
+Verify:
+
+- no invented product behavior,
+- domain terms match `CONTEXT.md`,
+- ADR conflicts are surfaced,
+- file paths are repo-relative,
+- feature units have test scenarios,
+- high-risk areas include rollout or operational notes,
+- deferred work is separate from active scope,
+- no implementation code or shell choreography is embedded.
+
+### 7. Save the plan
+
+Default:
+
+```text
+docs/plans/YYYY-MM-DD-NNN-<type>-<slug>-plan.md
+```
+
+Use `feat`, `fix`, or `refactor`. If the repo has chosen unified lifecycle docs, use `docs/knowledge/<slug>.md` with appropriate frontmatter.
+
+## Output
+
+```markdown
+## Plan Ready
+
+**File:** ...
+**Tier:** T1 | T2 | T3
+**Source artifacts:** ...
+**Implementation units:** ...
+**High-risk areas:** ...
+**Recommended next skill:** vc-review | vc-slice | vc-execute
+```
+
+## Guardrails
+
+- Do not code during planning.
+- Do not over-research low-risk work.
+- Do not publish issues automatically.
+- Do not create horizontal units like “backend”, “frontend”, and “tests” unless independently valuable.
+- Do not hide uncertainty as fake certainty.

package/skills/vc-prototype/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: vc-prototype
+description: Build a throwaway prototype to answer one design question before committing to production architecture. Use when exploring uncertain state machines, data models, UI variations, interaction flows, interface shapes, performance feasibility, or harness/tool UX experiments.
+---
+
+# Vector Cadence Prototype
+
+## Purpose
+
+Answer one design question with the smallest safe throwaway artifact. The value is the decision, not the prototype code.
+
+## Operating model
+
+Name the question, build only enough to answer it, evaluate with the user, then delete, mark, or convert the result into a plan/ADR/issue.
+
+## When to use
+
+Use when asking:
+
+- does this state model feel right?
+- which UI shape is better?
+- can this tool workflow work?
+- what is the smallest useful version?
+- should this be a module, command, prompt workflow, or extension?
+
+## When to skip
+
+Skip when:
+
+- the path is already clear,
+- normal TDD implementation is cheaper,
+- the prototype would touch real auth, billing, external effects, or production data without isolation.
+
+## Prototype routes
+
+| Question | Prototype shape |
+|---|---|
+| state/business logic | tiny terminal or script harness |
+| UI/UX | switchable variations on one route/page |
+| API/interface | fake caller exercising proposed shapes |
+| agent/harness workflow | mocked tool loop with recorded inputs/outputs |
+| performance | measurement spike with explicit benchmark |
+
+## Workflow
+
+### 1. Name the question
+
+Write one sentence:
+
+> This prototype answers: “...”
+
+If there are multiple questions, split them or choose the highest-risk one.
+
+### 2. Define disposal policy
+
+Decide before building:
+
+- delete after answer,
+- keep under a clearly marked prototype/temp path,
+- extract selected parts later,
+- capture decision only in plan/ADR.
+
+Default: throw away.
+
+### 3. Build the smallest artifact
+
+Rules:
+
+- one command or page to run/view,
+- obvious fake data,
+- clearly marked prototype code,
+- no broad refactors,
+- no hidden production coupling,
+- no real persistence/external effects unless isolated and necessary.
+
+### 4. Evaluate
+
+Record what worked, what failed, chosen option, changed assumptions, and whether production implementation should proceed.
+
+### 5. Cleanup or capture
+
+Delete the artifact, retain it intentionally under a marked path, or convert the decision into a plan, issue, or ADR.
+
+## Output
+
+```markdown
+## Prototype Result
+
+**Question:** ...
+**Artifact:** ...
+**How to run/view:** ...
+**Findings:** ...
+**Decision:** ...
+**Cleanup status:** deleted | retained intentionally | needs cleanup
+**Recommended next skill:** vc-align | vc-plan | vc-slice | vc-execute
+```
+
+## Guardrails
+
+- Do not prototype five questions at once.
+- Do not treat prototype code as production-ready.
+- Do not leave prototype artifacts unmarked.
+- Do not skip decision capture.

package/skills/vc-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: vc-review
+description: Review code, plans, requirements, or PRs with Standards-vs-Spec framing, persona selection, severity, confidence gates, and actionable routing. Use when reviewing before merge, after implementation, validating a plan/document, or checking security, correctness, performance, or requirements coverage.
+---
+
+# Vector Cadence Review
+
+## Purpose
+
+Check whether work is correct, complete, and safe. Review can apply to code diffs, PRs, plans, and requirements documents.
+
+## Operating model
+
+Review along two axes: **Standards** (repo conventions and quality bar) and **Spec** (source plan, issue, requirements, or user intent). Use persona-style review and confidence gates when the harness supports subagents.
+
+## When to use
+
+Use for:
+
+- pre-merge code review,
+- T2/T3 implementation gates,
+- plan or requirements review,
+- security/privacy/payments/API/migration changes,
+- resolving whether work satisfies a source artifact.
+
+## When to skip
+
+Skip or keep lightweight for:
+
+- trivial changes with obvious validation,
+- work still being actively implemented,
+- bugs that need root-cause diagnosis first.
+
+## Inputs
+
+Use:
+
+- diff/branch/PR,
+- plan/requirements/issue/agent brief,
+- `AGENTS.md`, `CONTEXT.md`, ADRs,
+- tests and validation results,
+- prior review comments if available.
+
+## Workflow
+
+### 1. Determine scope
+
+Identify changed files, base ref, PR metadata, source artifacts, untracked files, and generated/lockfile exclusions.
+
+### 2. Discover intent
+
+Read the source artifact when available:
+
+- issue agent brief,
+- plan U-IDs and verification criteria,
+- requirements doc,
+- align notes,
+- strategy/domain/ADR constraints.
+
+If no meaningful spec exists, review Standards only and label Spec uncertainty.
+
+### 3. Select review lenses
+
+Always consider:
+
+- correctness,
+- testing,
+- maintainability,
+- project standards,
+- requirements coverage.
+
+Add conditionals:
+
+- security for auth, permissions, public endpoints, user input,
+- performance for queries, caching, async, transformations,
+- API contract for routes, types, serializers, public interfaces,
+- data migration for migrations/backfills/schema,
+- reliability for retries, timeouts, jobs, error handling,
+- adversarial for large or high-risk diffs,
+- agent-native for harness/tool/agent features.
+
+### 4. Dispatch reviewers if available
+
+If the harness provides subagents, reviewer subagents must be read-only. They may inspect files and run non-mutating commands, but must not edit, commit, push, or change branches.
+
+Use bounded parallelism and treat capacity errors as backpressure.
+
+### 5. Merge findings
+
+For each finding record:
+
+- title,
+- severity P0-P3,
+- file/line,
+- confidence 0/25/50/75/100,
+- evidence,
+- reviewer/lens,
+- route.
+
+Suppress low-confidence findings below 75 unless P0 risk warrants attention. Separate pre-existing issues.
+
+### 6. Route actions
+
+| Route | Meaning |
+|---|---|
+| safe_auto | local deterministic fix may be applied if policy allows |
+| gated_auto | concrete fix exists but changes behavior/contracts; ask or hand off |
+| manual | actionable but needs human/downstream resolver |
+| advisory | FYI, rollout, risk, or learning |
+
+Do not auto-fix behavior-changing findings without a gate.
+
+### 7. Present verdict
+
+Use tables for findings. Include:
+
+- scope,
+- intent source,
+- Standards findings,
+- Spec findings,
+- requirements completeness,
+- testing gaps,
+- residual risks,
+- pre-existing issues,
+- verdict.
+
+Verdict options:
+
+- Ready to merge,
+- Ready with fixes,
+- Not ready.
+
+A code-clean PR that misses explicit requirements is not ready unless the omission is intentional.
+
+## Output
+
+```markdown
+## Review Summary
+
+**Scope:** ...
+**Intent source:** ...
+**Verdict:** Ready | Ready with fixes | Not ready
+**Must fix:** ...
+**Should fix:** ...
+**Testing gaps:** ...
+**Residual risks:** ...
+**Recommended next skill:** vc-execute | vc-debug | vc-learn
+```
+
+## Guardrails
+
+- Do not let reviewer subagents mutate project files.
+- Do not flood reports with low-confidence taste opinions.
+- Do not review against imagined requirements when source artifacts exist.
+- Do not silently drop explicit requirements from the verdict.
+- Do not block on inferred requirements alone.