vector-cadence-skills 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# Vector Cadence Skills
+
+Vector Cadence Skills is a production-ready skill suite for agentic software engineering workflows. It integrates the useful disciplines from Matt Pocock’s skills and Compound Engineering without making runtime skills depend on upstream command names or block-by-block composition.
+
+## Core idea
+
+Each skill owns one lifecycle responsibility:
+
+```text
+setup → orient → align → plan → review → slice → triage → execute → review → learn
+```
+
+Use only the amount of process the task needs. See `references/minimal-mode.md` for lightweight usage.
+
+## Skill catalog
+
+| Skill | Purpose |
+|---|---|
+| `vc-setup` | Bootstrap repo instructions, docs, labels, validation commands, and optional budget guard. |
+| `vc-orient` | Map a codebase area before planning, debugging, or editing. |
+| `vc-align` | Clarify product/domain intent, risks, terminology, and rejected alternatives. |
+| `vc-plan` | Write implementation-ready technical plans with units, files, tests, and verification. |
+| `vc-slice` | Convert plans into vertical issues or agent briefs. |
+| `vc-triage` | Route issues to agent, human, needs-info, or wontfix states. |
+| `vc-prototype` | Build a throwaway artifact to answer one design question. |
+| `vc-execute` | Implement clear work with workspace safety, TDD, and tiered validation. |
+| `vc-debug` | Diagnose bugs with a feedback-loop-first and causal-chain process. |
+| `vc-review` | Review code/docs against Standards and Spec with severity/confidence routing. |
+| `vc-architecture` | Improve application module boundaries, seams, and testability. |
+| `vc-learn` | Capture reusable lessons after verified non-trivial work. |
+| `vc-handoff` | Compact state for another agent or future session. |
+| `vc-harness-architect` | Design Vector Cadence/pi harness, extensions, subagents, providers, search, and permissions. |
+| `vc-skill-author` | Create or improve Vc-compatible skills. |
+
+## Naming convention
+
+Skill folders are named `vc-*`. Slash-command harnesses may expose them as `/vc-*`, but the canonical skill names are the folder/frontmatter names, such as `vc-align`.
+
+## Recommended workflows
+
+### Normal feature
+
+```text
+vc-align → vc-plan → vc-review → vc-slice → vc-triage → vc-execute → vc-review → vc-learn
+```
+
+Use `vc-review` before slicing only for important plans. Use `vc-learn` only when there is a reusable lesson.
+
+### Small known change
+
+```text
+vc-execute → optional vc-review
+```
+
+### Unfamiliar code
+
+```text
+vc-orient → vc-execute
+```
+
+### Bug
+
+```text
+vc-debug → vc-review → optional vc-learn
+```
+
+Use `vc-execute` if the diagnosis produces a plan but the fix has not been applied.
+
+### Harness work
+
+```text
+vc-harness-architect → vc-plan → vc-slice → vc-execute → vc-review
+```
+
+## Artifact model
+
+| Artifact | Question answered |
+|---|---|
+| `AGENTS.md` | How should agents operate in this repo? |
+| `CONTEXT.md` | What are domain things called? |
+| `STRATEGY.md` | What product outcome matters? |
+| `docs/align-notes/` | What did alignment reject, fear, or assume? |
+| `docs/brainstorms/` | What should be built from a product/user view? |
+| `docs/plans/` | How should it be implemented? |
+| issue tracker or `docs/issues/` | What can an agent/human pick up? |
+| `docs/solutions/` | What solved problem should future agents reuse? |
+| `docs/knowledge/` | What was planned, what shipped, and what changed? |
+| `docs/adr/` | Which durable trade-off should future agents respect? |
+| `.out-of-scope/` | Which rejected idea should not be rediscovered? |
+| `docs/handoffs/` | What state should a future agent resume from? |
+
+## Included support files
+
+```text
+templates/AGENTS.md
+templates/CONTEXT.md
+templates/vc-budget.yml
+scripts/validate-skills.mjs
+skills.json
+examples/
+references/
+```
+
+## Validation
+
+From this directory, run:
+
+```bash
+node scripts/validate-skills.mjs
+```
+
+The validator checks frontmatter, name/path consistency, description length, broken markdown links, banned legacy runtime command names, and line-count warnings.
+
+## When not to use full Vector Cadence
+
+Do not run the full lifecycle for:
+
+- typos,
+- formatting-only changes,
+- obvious one-file fixes,
+- mechanical renames,
+- throwaway experiments,
+- changes with exact user instructions and clear validation.
+
+Use minimal mode instead.
+
+## Harness boundary
+
+These markdown skills can guide workflows. They do not by themselves provide tools such as subagents, DeepSeek telemetry, Taste integration, code search indexing, or permission gates. Those belong in future Vector Cadence extensions or the Vector Cadence CLI.
+
+Recommended package split:
+
+```text
+@your-scope/vc-core
+@your-scope/vc-skills
+@your-scope/vc-extensions
+@your-scope/vc-cli
+```
+
+## Documentation
+
+- `DOCUMENTATION.md` — comprehensive architecture documentation.
+- `references/architecture-overview.md` — shorter architecture overview.
+- `references/source-integration-map.md` — why each skill chose its source disciplines.
+- `references/minimal-mode.md` — how to use Vector Cadence without excess process.
+- `references/final-skill-quality-bar.md` — publishing checklist.

package/examples/bug-debug-lifecycle.md

@@ -0,0 +1,39 @@
+# Example: Bug Debug Lifecycle
+
+User request:
+
+> Webhook retries are creating duplicate invoices.
+
+Recommended path:
+
+```text
+vc-debug → vc-review → vc-learn
+```
+
+Use `vc-execute` separately if diagnosis produces a clear implementation plan but no fix was applied during debugging.
+
+## Debug
+
+1. Build a replay loop from captured webhook payload.
+2. Reproduce duplicate invoice creation.
+3. Check environment and config.
+4. Trace idempotency key selection.
+5. Form hypotheses.
+6. Prove root cause.
+7. Write failing integration test.
+8. Apply minimal fix.
+9. Re-run original replay loop.
+
+## Review
+
+Because this touches payments, review with security, correctness, reliability, and data-integrity lenses.
+
+## Learn
+
+Good lesson:
+
+> Webhook handlers must use provider event ID as the idempotency key, not invoice ID.
+
+Bad lesson:
+
+> Fixed duplicate invoice bug.

package/examples/feature-lifecycle.md

@@ -0,0 +1,54 @@
+# Example: Feature Lifecycle
+
+User request:
+
+> Add scheduled exports for teams.
+
+Recommended path:
+
+```text
+vc-align → vc-plan → vc-review → vc-slice → vc-triage → vc-execute → vc-review → vc-learn
+```
+
+## 1. Align
+
+Clarify:
+
+- which users need exports,
+- what “scheduled” means,
+- success criteria,
+- rejected alternatives,
+- data retention concerns.
+
+Artifacts:
+
+- `docs/brainstorms/YYYY-MM-DD-scheduled-exports-requirements.md`
+- `docs/align-notes/scheduled-exports-grilled.md`
+
+## 2. Plan
+
+Produce U-IDs, files, patterns, test scenarios, and verification.
+
+## 3. Slice
+
+Good vertical slices:
+
+1. User can schedule one export.
+2. User can see export status.
+3. Failed export retries safely.
+4. Admin can inspect export history.
+
+Bad horizontal slices:
+
+- Create export tables.
+- Build export API.
+- Build export UI.
+- Write tests.
+
+## 4. Execute and review
+
+Implement AFK slices with TDD. Use review to catch missed permissions, data leaks, N+1s, and missing tests.
+
+## 5. Learn
+
+Capture only reusable lessons, such as idempotency or retention rules.

package/examples/harness-subagent-plan.md

@@ -0,0 +1,39 @@
+# Example: Harness Subagent Feature
+
+User request:
+
+> Add read-only research subagents to the Vector Cadence harness.
+
+Recommended path:
+
+```text
+vc-harness-architect → vc-plan → vc-slice → vc-execute → vc-review
+```
+
+## Harness architecture
+
+Decisions:
+
+- integration level: extension package,
+- first implementation: pi RPC subprocess or harness-supported child session,
+- default permission: read-only,
+- required timeout,
+- structured output contract,
+- raw log path for auditability.
+
+## First vertical slices
+
+1. Register `run_subagent` tool with schema and timeout requirement.
+2. Enforce read-only default permissions.
+3. Capture raw log and concise summary.
+4. Add validation tests for malformed output and timeout.
+
+## Review gates
+
+Use agent-native and security lenses:
+
+- no unrestricted file writes,
+- no hidden network/telemetry,
+- no unbounded process execution,
+- clear output contract,
+- cancellation/timeouts tested.

package/examples/vertical-slices.md

@@ -0,0 +1,43 @@
+# Example: Vertical Slices
+
+A vertical slice is a narrow complete behavior, not a layer.
+
+## Good
+
+### Saved search creation
+
+User can create a saved search and see it in the saved-search list.
+
+Why vertical:
+
+- crosses UI/API/persistence as needed,
+- has observable acceptance criteria,
+- can be tested end-to-end,
+- reduces integration risk immediately.
+
+## Bad
+
+### Create saved search table
+
+Why horizontal:
+
+- persistence only,
+- not user-visible,
+- cannot prove the feature works,
+- pushes integration risk later.
+
+## Better decomposition
+
+Instead of:
+
+1. database,
+2. API,
+3. UI,
+4. tests,
+
+use:
+
+1. create and list one saved search,
+2. validate duplicate names,
+3. edit saved search query,
+4. delete saved search with confirmation.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "vector-cadence-skills",
+  "version": "0.1.0",
+  "description": "Integrated Vector Cadence skill suite for agentic software engineering workflows.",
+  "main": "skills.json",
+  "scripts": {
+    "validate": "node scripts/validate-skills.mjs"
+  },
+  "keywords": [
+    "vector-cadence",
+    "skills",
+    "agentic",
+    "ai",
+    "coding-agent",
+    "workflows"
+  ],
+  "author": "Mithil Yaganti",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mithilyaganti/skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mithilyaganti/skills/issues"
+  },
+  "homepage": "https://github.com/Mithilyaganti/skills#readme",
+  "files": [
+    "skills",
+    "examples",
+    "references",
+    "scripts",
+    "templates",
+    "skills.json",
+    "README.md",
+    "DOCUMENTATION.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ]
+}

package/references/architecture-overview.md

@@ -0,0 +1,279 @@
+# Vector Cadence Skills — Architecture Overview
+
+This is the short architecture document for the new skill suite. It is intentionally smaller than the full research documentation. The full documentation can be written later when requested.
+
+## 1. What changed from the original Vector Cadence document
+
+The original Vector Cadence research doc had the right instinct — combine Pocock’s alignment-first workflow with Compound’s orchestration and review — but the architecture risk was that it composed skills like stacked blocks:
+
+```text
+run Pocock thing
+then run Compound thing
+then save output
+```
+
+That is not integration. It creates duplicated artifacts, duplicated questions, and unclear ownership.
+
+The new suite integrates by assigning each workflow a primary owner:
+
+- **Alignment owns product/domain decisions.** It can use brainstorming and grilling, but its output is intent.
+- **Planning owns technical decisions.** It can use research, but its output is an implementation-ready plan.
+- **Slicing owns issue shape.** It converts plans into vertical, independently useful work.
+- **Triage owns delegation safety.** It decides agent vs human, not implementation.
+- **Execution owns code changes.** It uses TDD and orchestration, not new product discovery.
+- **Review owns confidence.** It checks Standards and Spec with multi-agent help when useful.
+- **Learning owns reusable memory.** It captures only lessons that future agents will retrieve.
+
+This prevents workflow overlap.
+
+## 2. Why Pocock and Compound are not interchangeable
+
+Pocock’s skills are strongest at **engineering judgment close to the work**:
+
+- ask one question at a time,
+- use domain language,
+- create vertical slices,
+- write behavior tests through public interfaces,
+- debug through feedback loops,
+- design deep modules,
+- compact handoffs.
+
+Compound’s skills are strongest at **orchestration and institutional scale**:
+
+- brainstorm → plan → work → review pipelines,
+- multi-agent code/doc review,
+- plan U-IDs and requirements traceability,
+- subagent orchestration and worktree safety,
+- solved-problem knowledge capture,
+- agent-native application architecture.
+
+Vector Cadence uses each where it is structurally better, not where it happens to have a similarly named command.
+
+## 3. The lifecycle
+
+```text
+Setup
+  → Orient
+  → Align
+  → Plan
+  → Review plan when useful
+  → Slice
+  → Triage
+  → Execute
+  → Review code
+  → Learn
+```
+
+### Setup
+
+`vc-setup` creates the repo contract: where domain language lives, where ADRs live, how issue labels map to canonical triage states, and what commands verify work.
+
+Without this, every skill guesses.
+
+### Orient
+
+`vc-orient` is read-only. It maps a code area and separates verified code facts from inferred/documented context.
+
+It exists because many agent mistakes come from editing a local file before understanding the system shape.
+
+### Align
+
+`vc-align` is the product/domain checkpoint.
+
+It integrates Compound’s brainstorm workflow with Pocock’s grilling discipline. It captures:
+
+- clean requirements in `docs/brainstorms/`,
+- messy rejected alternatives and fears in `docs/align-notes/`,
+- canonical domain terms in `CONTEXT.md`,
+- durable trade-offs in ADRs only when warranted.
+
+The major design choice is separating clean requirements from the grilling shadow. Formal docs are good for decisions; raw align notes are good for preventing repeated mistakes.
+
+### Plan
+
+`vc-plan` turns aligned intent into technical design.
+
+It uses Compound’s plan structure because that is stronger than Pocock’s PRD for implementation handoff: U-IDs, files, patterns, dependencies, test scenarios, and verification are explicit.
+
+But Pocock’s rules are injected into the plan quality bar:
+
+- code-first verification,
+- domain language,
+- no implementation code in plans,
+- public-interface tests,
+- deep-module/seam awareness,
+- vertical-slice readiness.
+
+### Slice
+
+`vc-slice` exists because a good technical plan is not automatically a good issue set.
+
+Compound plan units are often atomic implementation units. Pocock tracer-bullet issues are end-to-end vertical slices. Vector Cadence keeps both concepts separate:
+
+- plan unit = coherent implementation decision,
+- slice/issue = independently shippable or verifiable outcome.
+
+This is the main fix to the “adding blocks” problem.
+
+### Triage
+
+`vc-triage` is the delegation gate.
+
+It uses Pocock’s issue state machine but adds Vector Cadence confidence and subagent-safety gates. The important distinction:
+
+- `ready-for-agent` means autonomous execution is safe,
+- `ready-for-human` means human judgment is still the task,
+- `needs-info` means the missing information is specific and actionable.
+
+### Execute
+
+`vc-execute` uses Compound’s work execution shell because it handles real implementation concerns: branch safety, task tracking, subagent execution, incremental commits, and continuous testing.
+
+But the inner coding loop is Pocock TDD:
+
+```text
+one behavior → one failing public-interface test → minimal code → green → repeat
+```
+
+This prevents the Compound-style executor from becoming a generic task machine that writes all tests first or implements layer by layer.
+
+### Debug
+
+`vc-debug` is its own path because bugs should not start with planning.
+
+It combines:
+
+- Pocock’s feedback-loop-first diagnosis,
+- Compound’s causal-chain gate and environment sanity checks.
+
+The rule is simple: no causal chain, no fix.
+
+### Review
+
+`vc-review` is Compound-dominant because Compound’s code review system is much stronger operationally: personas, severity, confidence, deduplication, validators, and routing.
+
+Pocock’s contribution is the two-axis review frame:
+
+- Standards: did we follow repo rules?
+- Spec: did we satisfy the source artifact?
+
+### Architecture
+
+`vc-architecture` has two routes:
+
+- general code architecture → Pocock deep modules,
+- harness/agent architecture → Compound agent-native architecture.
+
+This split matters. “Make this module deeper” and “design an agent-native harness” are not the same problem.
+
+### Learn
+
+`vc-learn` is Compound-dominant because solved-problem compounding is one of Compound’s clearest strengths.
+
+Pocock discipline prevents knowledge bloat:
+
+- `CONTEXT.md` stays glossary-only,
+- ADRs stay sparse,
+- trivial fixes are not documented,
+- artifacts answer distinct future questions.
+
+## 4. Tiering model
+
+Vector Cadence has three tiers:
+
+| Tier | Meaning | Typical workflow |
+|---|---|---|
+| T1 | known, low-risk work | align lightly → plan lightly or execute direct → focused review |
+| T2 | moderate complexity or unfamiliar module | align → plan with focused research → slice/execute → review |
+| T3 | high-risk architecture/security/privacy/migration/harness loop | deep align → deep plan → doc review → gated execution → deep review |
+
+Tiering is not about making the agent fancy. It is cost control.
+
+Most tasks should not spawn many agents. High-risk tasks should not skip research.
+
+## 5. Subagent policy
+
+Vector Cadence assumes subagents will exist in the harness, but does not assume they can safely write anywhere.
+
+Default stages:
+
+1. read-only research subagents,
+2. read-only review subagents,
+3. test-running subagents,
+4. serial implementation subagents,
+5. parallel write subagents only with disjoint scopes or isolated worktrees.
+
+The orchestrator owns:
+
+- final merge,
+- final validation,
+- user-facing summary,
+- conflict handling.
+
+This avoids the common demo trap: impressive parallelism that corrupts the checkout.
+
+## 6. Harness packaging strategy
+
+Recommended package split:
+
+```text
+@your-scope/vc-core
+@your-scope/vc-skills
+@your-scope/vc-extensions
+@your-scope/vc-cli
+```
+
+Build on **bare pi** as the substrate. Borrow little-coder launcher and extension patterns, but avoid a deep fork.
+
+Why:
+
+- easier upstream updates,
+- extensions stay composable,
+- skills can be installed without the full CLI,
+- advanced users can load only the extension package,
+- future Reasonix/cache-first work can evolve without rewriting every skill.
+
+## 7. DeepSeek / Reasonix boundary
+
+A skill suite can improve DeepSeek usage, but it cannot by itself guarantee Reasonix-style cache hit rates.
+
+Reasonix-level caching depends on request construction:
+
+- stable system prompt,
+- stable tool schema order,
+- stable message serialization,
+- append-only history where possible,
+- scratch excluded from future stable prefixes,
+- careful compaction.
+
+That is harness-loop architecture, not just markdown instructions.
+
+So Vector Cadence’s staged plan is:
+
+1. DeepSeek provider support,
+2. cache telemetry,
+3. prompt/tool stability improvements,
+4. Reasonix backend/subagent for selected tasks,
+5. custom pi SDK cache-first loop only if measurements justify it.
+
+## 8. Taste and future tools
+
+Taste, code search, browser tools, and other integrations belong in extensions, not ordinary skills.
+
+A skill can describe when to use them. An extension provides the tool.
+
+Privacy rule: Taste/telemetry must be explicit opt-in.
+
+## 9. Why this architecture should scale
+
+The suite scales because responsibilities are separated:
+
+- alignment does not write code,
+- plans do not become issues automatically,
+- issue slicing enforces verticality,
+- triage decides autonomy,
+- execution respects tests and branch safety,
+- review is confidence-gated,
+- learning captures only reusable knowledge.
+
+Each step reduces uncertainty for the next step instead of piling more process on top.

package/references/artifact-model.md

@@ -0,0 +1,20 @@
+# Vector Cadence Artifact Model
+
+Each artifact answers one future question.
+
+| Artifact | Question |
+|---|---|
+| `AGENTS.md` | How should agents operate in this repo? |
+| `CONTEXT.md` | What are domain things called? |
+| `STRATEGY.md` | What product outcome matters? |
+| `docs/align-notes/` | What did alignment reject, fear, or assume? |
+| `docs/brainstorms/` | What should be built from a product/user view? |
+| `docs/plans/` | How should it be implemented? |
+| `docs/issues/` or tracker | What can an agent/human pick up? |
+| `docs/solutions/` | What solved problem should future agents reuse? |
+| `docs/knowledge/` | What was planned, what shipped, and what changed? |
+| `docs/adr/` | Which durable trade-off should future agents respect? |
+| `.out-of-scope/` | Which rejected idea should not be rediscovered? |
+| `docs/handoffs/` | What state should a future agent resume from? |
+
+Do not create an artifact unless it has future retrieval value.

package/references/final-skill-quality-bar.md

@@ -0,0 +1,33 @@
+# Final Skill Quality Bar
+
+Use this checklist before publishing any Vector Cadence skill.
+
+## Required
+
+- [ ] One lifecycle responsibility.
+- [ ] Frontmatter has `name` and `description`.
+- [ ] `name` matches directory.
+- [ ] Description is under 1024 characters.
+- [ ] Description includes concrete `Use when` triggers.
+- [ ] Skill has Purpose, When to use, When to skip, Workflow, Output, and Guardrails.
+- [ ] Side effects are explicit.
+- [ ] Optional tools are phrased as “if the harness provides...”.
+- [ ] No invented tools, commands, paths, or APIs.
+- [ ] Runtime skill does not contain upstream source-rationale sections.
+- [ ] Links resolve.
+- [ ] Next-skill routing is clear.
+
+## Preferred
+
+- [ ] Normal skills stay under 150 lines where practical.
+- [ ] Complex orchestration skills stay under 170 lines where practical.
+- [ ] Examples are minimal and behavior-shaping.
+- [ ] Long rationale lives in references or documentation.
+- [ ] Deterministic checks live in scripts.
+
+## Do not publish if
+
+- The skill duplicates an existing skill without a clear boundary.
+- The behavior really requires an extension but is described as markdown-only.
+- It encourages autonomous work without stop conditions.
+- It writes to project files without stating when and why.