vector-cadence-skills 0.1.0

package/skills/vc-setup/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: vc-setup
+description: Bootstrap a repository for Vector Cadence by creating or updating project instructions, domain docs, issue-tracker mappings, knowledge folders, validation commands, and optional budget guard. Use when first using Vector Cadence skills in a repo or when skills lack tracker, docs, context, or validation information.
+---
+
+# Vector Cadence Setup
+
+## Purpose
+
+Prepare a repository so Vector Cadence skills know where docs live, what labels mean, which commands validate work, and what project rules agents must follow.
+
+## Operating model
+
+Detect existing conventions first, preserve user/project instructions, ask only for missing setup choices, and create scaffolding lazily unless the user requests full setup.
+
+## When to use
+
+Use when:
+
+- installing Vector Cadence skills in a repo for the first time,
+- issue labels or docs layout are unknown,
+- validation commands are missing,
+- moving from ad-hoc agent use to a structured workflow,
+- setting up the future Vector Cadence harness itself.
+
+## When to skip
+
+Skip when:
+
+- the repo already has correct Vector Cadence setup,
+- the user only wants a one-off edit,
+- you would need to overwrite existing instructions without approval.
+
+## Artifacts
+
+Potential project artifacts:
+
+```text
+AGENTS.md
+CONTEXT.md
+docs/adr/
+docs/align-notes/
+docs/brainstorms/
+docs/plans/
+docs/issues/
+docs/solutions/
+docs/knowledge/
+docs/handoffs/
+.out-of-scope/
+.vc-budget.yml
+```
+
+Create only what is needed unless full scaffold is requested.
+
+## Workflow
+
+### 1. Detect environment
+
+Inspect:
+
+- repo root and package manager,
+- existing `AGENTS.md` / `CLAUDE.md`,
+- existing docs layout,
+- issue tracker availability,
+- test/typecheck/lint commands,
+- branch/worktree support,
+- CI config.
+
+### 2. Ask missing setup choices
+
+Ask only what cannot be inferred:
+
+- issue tracker: GitHub, Linear, local markdown, none,
+- docs mode: separate `docs/plans` + `docs/solutions` or unified `docs/knowledge`,
+- curated vs composable harness behavior,
+- whether to enable budget guard,
+- lazy vs full directory scaffold.
+
+### 3. Update instruction file safely
+
+Add or update a Vector Cadence section in `AGENTS.md` or the project’s chosen instruction file. Preserve existing content and do not replace project rules.
+
+Include:
+
+- Vector Cadence lifecycle summary,
+- artifact locations,
+- triage label mapping placeholders,
+- validation commands,
+- subagent safety policy,
+- privacy/telemetry rule.
+
+### 4. Create domain and docs scaffolding
+
+Create `CONTEXT.md` only if domain terms exist or the user wants scaffolding. Keep it glossary-only.
+
+Create docs directories lazily or as requested.
+
+### 5. Add optional budget guard
+
+If approved, create `.vc-budget.yml` from the template.
+
+### 6. Report readiness
+
+Summarize created/updated files, detected tracker, validation commands, docs mode, and any missing setup.
+
+## Output
+
+```markdown
+## Vector Cadence Setup Complete
+
+**Instruction file:** ...
+**Docs mode:** ...
+**Issue tracker:** ...
+**Triage mapping:** ...
+**Validation commands:** ...
+**Created/updated:** ...
+**Recommended next skill:** vc-align | vc-harness-architect
+```
+
+## Guardrails
+
+- Do not overwrite existing instructions.
+- Do not invent validation commands.
+- Do not put implementation details in `CONTEXT.md`.
+- Do not require GitHub; local markdown issues are valid.
+- Do not lock users into curated mode without choice.

package/skills/vc-skill-author/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: vc-skill-author
+description: Create or improve Vc-compatible skills with strong triggers, concise runtime instructions, progressive disclosure, safe tool assumptions, and clear integration level. Use when adding new skills, refactoring skill docs, packaging reusable workflows, or deciding whether behavior belongs in a skill, script, extension, or wrapper.
+---
+
+# Vector Cadence Skill Author
+
+## Purpose
+
+Create skills that are easy for agents to load and execute. A good skill is a concise operating procedure, not a giant essay.
+
+## Operating model
+
+Keep runtime instructions in `SKILL.md`, move rationale and examples to references, add scripts only for deterministic work, and never assume tools/extensions that the harness does not provide.
+
+## When to use
+
+Use when:
+
+- adding a new Vector Cadence skill,
+- improving an existing skill,
+- converting a workflow into reusable instructions,
+- deciding whether a feature belongs in skill/script/extension/wrapper,
+- reviewing skill quality.
+
+## When to skip
+
+Skip when:
+
+- the change is ordinary app code,
+- the requested behavior requires a tool but no extension will be built,
+- a reference doc or subroutine would be better than a top-level skill.
+
+## Skill structure
+
+```text
+skill-name/
+  SKILL.md
+  references/   optional
+  scripts/      optional
+```
+
+## Description rules
+
+Frontmatter description should:
+
+- be under 1024 characters,
+- be third person,
+- state capability first,
+- include “Use when...” triggers,
+- mention concrete contexts,
+- avoid vague “helps with”.
+
+## Workflow
+
+### 1. Gather requirements
+
+Clarify:
+
+- task/domain,
+- trigger prompts,
+- inputs and outputs,
+- artifacts read/written,
+- safety constraints,
+- integration level,
+- related or overlapping skills.
+
+### 2. Choose integration level
+
+| Level | Use when |
+|---|---|
+| Skill | instructions, workflows, style rules |
+| Script | deterministic validation/formatting/generation |
+| Extension | new tools, providers, subagents, search, telemetry |
+| Wrapper | install UX, defaults, package orchestration |
+
+Do not put extension behavior into a markdown skill and pretend it exists.
+
+### 3. Write concise `SKILL.md`
+
+Use consistent sections:
+
+- Purpose,
+- Operating model when useful,
+- When to use,
+- When to skip,
+- Inputs,
+- Workflow,
+- Output,
+- Guardrails.
+
+### 4. Split only useful references
+
+Use references for long rationale, schemas, examples, platform-specific details, or comparison tables. Avoid reference sprawl.
+
+### 5. Add scripts only for deterministic tasks
+
+Good scripts validate frontmatter, generate indexes, check links, transform artifacts, or run static checks. Do not script judgment-heavy work.
+
+### 6. Review quality
+
+Check:
+
+- one responsibility,
+- clear triggers,
+- explicit side effects,
+- no invented tools,
+- no duplicated rationale,
+- valid links,
+- examples match actual harness capability,
+- next-skill routing is clear.
+
+## Output
+
+```markdown
+## Skill Drafted
+
+**Path:** ...
+**Integration level:** skill | script | extension | wrapper
+**Triggers:** ...
+**Artifacts touched:** ...
+**Open questions:** ...
+**Recommended next skill:** vc-review | none
+```
+
+## Guardrails
+
+- Do not create huge monolithic skills.
+- Do not hide setup requirements.
+- Do not add a top-level skill unless it owns a distinct lifecycle responsibility.
+- Do not copy upstream skills verbatim; adapt the useful discipline.

package/skills/vc-slice/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: vc-slice
+description: Break a plan, PRD, or requirements document into independently shippable vertical slices and issue-ready agent briefs. Use when turning a plan into tracker issues, preparing AFK work, checking issue granularity, or preventing horizontal backend/frontend/test ticket splits.
+---
+
+# Vector Cadence Slice
+
+## Purpose
+
+Turn plans into vertical, independently useful work items. This skill prevents implementation plans from becoming horizontal layer tickets.
+
+## Operating model
+
+A plan unit can be a technical chunk; an issue slice should be a narrow end-to-end outcome that is demoable or verifiable on its own.
+
+## When to use
+
+Use when:
+
+- converting a plan/PRD/requirements doc into issues,
+- preparing AFK agent work,
+- checking whether issue breakdown is too horizontal,
+- creating local markdown issues when no tracker is configured.
+
+## When to skip
+
+Skip when:
+
+- work is a single small direct task,
+- the plan still needs technical decisions (`vc-plan`),
+- the issue needs readiness classification only (`vc-triage`).
+
+## Inputs
+
+Accept:
+
+- `docs/plans/*-plan.md`,
+- `docs/knowledge/<feature>.md`,
+- requirements doc,
+- PRD,
+- issue reference,
+- user-provided plan text.
+
+Read source requirements, scope boundaries, implementation units, test scenarios, and deferred notes.
+
+## Workflow
+
+### 1. Gather context
+
+Confirm domain terms, relevant ADRs, source requirements/U-IDs, existing implementation/test patterns, and whether plan units are vertical or preparatory.
+
+### 2. Draft vertical slices
+
+A valid slice creates a narrow complete path through the system.
+
+Good:
+
+> User can create one saved search and see it in the saved-search list.
+
+Bad:
+
+- Create database schema.
+- Build backend API.
+- Build frontend UI.
+- Write tests.
+
+For each slice define title, type, tier, confidence, blockers, source trace, acceptance criteria, test expectations, and agent safety.
+
+### 3. Reject horizontal leakage
+
+For every slice ask:
+
+- Can it be demoed or verified alone?
+- Does it cross the real integration seam?
+- Does it reduce user/system risk?
+- Is it only setup for later work?
+
+Merge horizontal setup into the first vertical slice that needs it, unless the setup is an explicit risk-reduction spike.
+
+### 4. Classify AFK/HITL/Manual
+
+AFK requires clear scope, known verification, no unresolved human judgment, and safe edit scope.
+
+HITL means design, architecture, access, legal, security, privacy, money, or confidence issues need human input.
+
+Manual means the real task must happen outside the agent/harness.
+
+### 5. Review with the user
+
+Before publishing, show a numbered list with title, type, tier, confidence, blockers, source trace, and why each slice is vertical. Ask whether granularity, dependencies, and AFK/HITL classifications are correct.
+
+### 6. Publish or write local issues
+
+If a tracker is available, create issues in dependency order. Otherwise write local markdown issues under:
+
+```text
+docs/issues/<slug>-<nn>.md
+```
+
+Issue body should include parent, type, tier/confidence, what to build, acceptance criteria, test expectations, source trace, blockers, and agent brief.
+
+## Output
+
+```markdown
+## Slices Ready
+
+**Created:** ...
+**AFK:** ...
+**HITL:** ...
+**Manual:** ...
+**Blocked first:** ...
+**Recommended next skill:** vc-triage | vc-execute
+```
+
+## Guardrails
+
+- Do not publish without approval unless running in an explicit headless pipeline.
+- Do not close or mutate the parent issue/plan.
+- Do not create layer tickets.
+- Do not mark low-confidence work as AFK.
+- Avoid brittle file-by-file implementation scripts in issue bodies.

package/skills/vc-triage/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: vc-triage
+description: Triage issues into a safe agent/human workflow using canonical states, confidence, tiering, and subagent-safety gates. Use when reviewing incoming issues, preparing AFK work, routing bugs or enhancements, or deciding what agents can handle next.
+---
+
+# Vector Cadence Triage
+
+## Purpose
+
+Decide what should happen next for issues. Triage routes work to agents, humans, more information, or rejection; it does not implement the work.
+
+## Operating model
+
+Use a small state machine, inspect the full issue context, reproduce bugs when possible, and write durable agent/human briefs only when the issue is ready.
+
+## When to use
+
+Use when:
+
+- reviewing incoming issues,
+- preparing AFK-ready work,
+- auditing stale issue states,
+- moving issues between workflow states,
+- deciding whether a task needs human judgment.
+
+## When to skip
+
+Skip when:
+
+- there is no issue or work queue to triage,
+- the user wants direct implementation from an approved plan (`vc-execute`),
+- the bug first needs root-cause diagnosis (`vc-debug`).
+
+## Canonical states
+
+Each triaged issue should have one category and one state.
+
+Categories:
+
+- `bug`
+- `enhancement`
+
+States:
+
+- `needs-triage`
+- `needs-info`
+- `ready-for-agent`
+- `ready-for-human`
+- `wontfix`
+
+Map actual tracker labels to these names.
+
+## Workflow
+
+### 1. Select scope
+
+Support:
+
+- show issues needing attention,
+- triage a specific issue,
+- move an issue to a target state,
+- audit `needs-info` or `ready-for-agent` queues.
+
+### 2. Gather context
+
+Read:
+
+- full issue body and comments,
+- labels/state,
+- linked plans/PRs/docs,
+- prior triage notes,
+- recent reporter replies,
+- related `.out-of-scope/` entries,
+- relevant code/docs/ADRs.
+
+Do not triage from the opening body alone.
+
+### 3. Reproduce bugs before grilling
+
+For bugs, try to reproduce with existing steps, focused tests, or code-path tracing. Report whether reproduction succeeded, failed, or needs missing setup.
+
+No repro is often a `needs-info` signal unless code evidence is enough.
+
+### 4. Score readiness
+
+Assess:
+
+- scope clarity,
+- acceptance criteria,
+- domain language,
+- existing patterns,
+- verification path,
+- risk surface,
+- confidence,
+- subagent/file safety.
+
+Default readiness threshold for `ready-for-agent`: 70% confidence.
+
+### 5. Recommend state
+
+Present:
+
+```markdown
+## Triage Recommendation
+
+**Category:** bug | enhancement
+**State:** needs-info | ready-for-agent | ready-for-human | wontfix
+**Tier:** T1 | T2 | T3
+**Confidence:** ...
+**Reasoning:** ...
+**Evidence:** ...
+**Missing information:** ...
+```
+
+Wait before mutating tracker state unless the user requested a direct override.
+
+### 6. Apply outcome
+
+If posting tracker comments, prefix AI-generated triage comments with:
+
+```markdown
+> *This was generated by AI during triage.*
+```
+
+- `needs-info`: ask specific actionable questions.
+- `ready-for-agent`: post an agent brief with goal, context, acceptance, likely files/modules, patterns, tests, constraints, tier, subagent safety, and stop conditions.
+- `ready-for-human`: post a human brief and explain why delegation is unsafe.
+- `wontfix`: explain politely; for recurring rejected enhancements, write `.out-of-scope/<slug>.md`.
+- `needs-triage`: apply state and optionally comment partial findings.
+
+## Output
+
+```markdown
+## Triage Complete
+
+**Issue:** ...
+**Category/state:** ...
+**Tier/confidence:** ...
+**Action taken:** ...
+**Recommended next skill:** vc-execute | vc-debug | none
+```
+
+## Guardrails
+
+- Do not assign conflicting state labels.
+- Do not ask questions already answered in comments.
+- Do not route vague or low-confidence work to AFK agents.
+- Do not send sensitive unresolved decisions to autonomous execution.
+- Preserve reusable rejection rationale in `.out-of-scope/`.

package/skills.json

@@ -0,0 +1,98 @@
+{
+  "name": "vc-integrated-skills",
+  "version": "0.1.0",
+  "description": "Integrated Vector Cadence skill suite for agentic software engineering workflows.",
+  "slashCommandConvention": "Skills are named vc-*. Slash-command harnesses may expose them as /vc-*.",
+  "skills": [
+    {
+      "name": "vc-setup",
+      "path": "skills/vc-setup/SKILL.md",
+      "category": "setup",
+      "phase": "setup"
+    },
+    {
+      "name": "vc-orient",
+      "path": "skills/vc-orient/SKILL.md",
+      "category": "workflow",
+      "phase": "orientation"
+    },
+    {
+      "name": "vc-align",
+      "path": "skills/vc-align/SKILL.md",
+      "category": "workflow",
+      "phase": "alignment"
+    },
+    {
+      "name": "vc-plan",
+      "path": "skills/vc-plan/SKILL.md",
+      "category": "workflow",
+      "phase": "planning"
+    },
+    {
+      "name": "vc-slice",
+      "path": "skills/vc-slice/SKILL.md",
+      "category": "workflow",
+      "phase": "issue-decomposition"
+    },
+    {
+      "name": "vc-triage",
+      "path": "skills/vc-triage/SKILL.md",
+      "category": "workflow",
+      "phase": "triage"
+    },
+    {
+      "name": "vc-prototype",
+      "path": "skills/vc-prototype/SKILL.md",
+      "category": "workflow",
+      "phase": "prototyping"
+    },
+    {
+      "name": "vc-execute",
+      "path": "skills/vc-execute/SKILL.md",
+      "category": "workflow",
+      "phase": "execution"
+    },
+    {
+      "name": "vc-debug",
+      "path": "skills/vc-debug/SKILL.md",
+      "category": "workflow",
+      "phase": "debugging"
+    },
+    {
+      "name": "vc-review",
+      "path": "skills/vc-review/SKILL.md",
+      "category": "workflow",
+      "phase": "review"
+    },
+    {
+      "name": "vc-architecture",
+      "path": "skills/vc-architecture/SKILL.md",
+      "category": "workflow",
+      "phase": "application-architecture"
+    },
+    {
+      "name": "vc-learn",
+      "path": "skills/vc-learn/SKILL.md",
+      "category": "workflow",
+      "phase": "learning"
+    },
+    {
+      "name": "vc-handoff",
+      "path": "skills/vc-handoff/SKILL.md",
+      "category": "utility",
+      "phase": "handoff"
+    },
+    {
+      "name": "vc-harness-architect",
+      "path": "skills/vc-harness-architect/SKILL.md",
+      "category": "harness",
+      "phase": "harness-architecture"
+    },
+    {
+      "name": "vc-skill-author",
+      "path": "skills/vc-skill-author/SKILL.md",
+      "category": "authoring",
+      "phase": "skill-authoring"
+    }
+  ]
+}

package/templates/AGENTS.md

@@ -0,0 +1,82 @@
+# Agent Instructions
+
+## Vector Cadence skills
+
+Use Vector Cadence skills to match process to risk. Do not run the full lifecycle for trivial work.
+
+### Default lifecycle
+
+```text
+vc-orient      # optional, when unfamiliar
+vc-align       # clarify meaningful intent
+vc-plan        # technical plan for non-trivial work
+vc-review      # optional plan/doc review for risky work
+vc-slice       # create vertical issues/briefs
+vc-triage      # decide agent vs human readiness
+vc-execute     # implement clear work
+vc-review      # pre-merge review
+vc-learn       # capture reusable lessons only
+```
+
+### Bug lifecycle
+
+```text
+vc-debug → vc-execute → vc-review → vc-learn
+```
+
+### Harness lifecycle
+
+```text
+vc-harness-architect → vc-plan → vc-slice → vc-execute
+```
+
+## Canonical artifacts
+
+- `CONTEXT.md` is a domain glossary only. Do not put implementation plans there.
+- ADRs live in `docs/adr/`.
+- Alignment notes live in `docs/align-notes/`.
+- Requirements live in `docs/brainstorms/`.
+- Technical plans live in `docs/plans/` unless this repo uses `docs/knowledge/`.
+- Solved-problem learnings live in `docs/solutions/`.
+- Handoffs live in `docs/handoffs/`.
+- Rejected recurring enhancements live in `.out-of-scope/`.
+
+## Triage label mapping
+
+Map tracker labels to these canonical roles:
+
+- `bug`: <label>
+- `enhancement`: <label>
+- `needs-triage`: <label>
+- `needs-info`: <label>
+- `ready-for-agent`: <label>
+- `ready-for-human`: <label>
+- `wontfix`: <label>
+
+## Validation commands
+
+Fill these in during setup:
+
+- Test: `<command>`
+- Typecheck: `<command>`
+- Lint: `<command>`
+- Format/check: `<command>`
+
+Do not invent commands. If unknown, say unknown.
+
+## Subagent policy
+
+- Review/research subagents are read-only by default.
+- Parallel write subagents require isolated worktrees or disjoint file scopes.
+- Shared-checkout subagents must not stage, commit, or run whole-suite tests concurrently.
+- Parent/orchestrator owns final merge, final validation, and user-facing summary.
+
+## Privacy and telemetry
+
+Do not send Taste, telemetry, private code, secrets, customer data, or preference data to external services without explicit opt-in.
+
+## Tiering
+
+- T1: known low-risk work; keep process lean.
+- T2: moderate ambiguity or unfamiliar area; use focused planning/review.
+- T3: security, privacy, payments, migrations, public contracts, or harness core loops; require explicit approval for expensive/deep work.