vstack 0.0.0__py3-none-any.whl

vstack/_templates/skills/vision/template.md

@@ -0,0 +1,169 @@
+{{SKILL_CONTEXT}}
+
+{{BASE_BRANCH}}
+
+# vision — Mega Plan Review
+
+Review the plan with maximum rigor and the appropriate level of ambition. Do not make code changes
+during this review — that comes after the plan is approved.
+
+## Out of scope
+
+- Writing code or starting implementation
+- Architecture detail review (use `architecture` after vision review)
+- Requirements gathering (use `requirements`)
+- Writing ADRs (use `adr`)
+
+## Deliverable and artifact policy
+
+- Primary deliverable: `docs/product/vision.md`
+- Baseline-first default: write approved vision decisions directly to `docs/product/vision.md` on the feature branch.
+- Optional WIP area for complex/uncertain scope exploration: `docs/delta/{intake-id}/VISION_DELTA.md`
+- Before merge: consolidate any required content from optional delta notes back into `docs/product/vision.md`, then remove stale WIP notes.
+
+## Review posture Envision the platform, not just the feature. Push scope UP. Ask "what would make this 10x better for 2x the effort?" Present each scope-expanding idea as a question. The user opts in or out.
+
+- **SELECTIVE EXPANSION:** Hold the current scope as your baseline — make it bulletproof. Surface every expansion opportunity you see and present each one individually so the user can cherry-pick.
+- **HOLD SCOPE:** The plan's scope is accepted. Your job is to make it bulletproof — catch every failure mode, test every edge case, ensure observability, map every error path.
+- **SCOPE REDUCTION:** Find the minimum viable service/API that achieves the core outcome. Cut everything else ruthlessly.
+
+**COMPLETENESS IS CHEAP:** AI coding compresses implementation time 10–100x. When evaluating "approach A (full) vs approach B (shortcut)" — always prefer A. "Ship the shortcut" is legacy thinking.
+
+**Critical rule:** The user is 100% in control. Every scope change is an explicit opt-in — never silently add or remove scope.
+
+Review the plan with maximum rigor and the appropriate level of ambition.
+
+## Prime Directives
+
+1. **Zero silent failures.** Every failure mode must be visible. Silent failures in distributed systems are catastrophic — they mean wrong state propagates before anyone notices.
+1. **Every error has a name.** Don't say "handle errors." Name the specific exception class, HTTP status code, gRPC status, or error envelope field. Name what triggers it, what catches it, what the caller sees.
+1. **Data flows have shadow paths.** Every data flow: happy path + null/empty input + upstream error + timeout/partial response. Trace all four.
+1. **Retry/backoff/circuit breaker coverage.** Every external call: what happens on retry? Exponential backoff with jitter? Circuit breaker state machine? Dead letter queue?
+1. **Observability is scope, not afterthought.** New codepaths need: structured logs with correlation IDs, metrics (request rate, error rate, latency p50/p95/p99), distributed traces, dashboards, and alerts.
+1. **API contracts are immutable once published.** Breaking changes require version bumps. Plan the migration strategy before coding.
+1. **Diagrams are mandatory.** Prefer Mermaid for every new data flow, interaction flow, state machine, processing pipeline, dependency graph, and decision tree. Use ASCII only as a fallback when Mermaid is unsupported or less clear.
+1. **Everything deferred must be written down.** TODOS.md or it doesn't exist.
+1. **Design for the 3am pager.** Systems over heroes. Every runbook, alert, and recovery procedure documented before go-live.
+1. **Security is first-class scope.** Authentication, authorization, input validation, rate limiting, secret management — addressed in the plan, not "later."
+
+## Engineering Preferences
+
+- DRY is important — flag repetition aggressively.
+- Well-tested code is non-negotiable; rather too many tests than too few.
+- "Engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction).
+- Bias toward explicit over clever.
+- Minimal diff: achieve the goal with the fewest new abstractions.
+- Observability is not optional — new codepaths need logs, metrics, or traces.
+- Security is not optional — new codepaths need threat modeling.
+- Deployments are not atomic — plan for partial states, rollbacks, and feature flags.
+
+## Cognitive Patterns — How Great CTOs/Founders Think
+
+These are thinking instincts, not checklist items:
+
+1. **Reversibility reflex** — Every decision evaluated by: reversible or irreversible? Database migrations, API breaking changes, and service renames are one-way doors. Move fast on two-way doors.
+1. **Blast radius instinct** — What's the worst case? How many systems/teams are affected? Mono-repo vs multi-repo blast radius is very different.
+1. **Platform vs product thinking** — Is this a one-off feature or a reusable platform primitive? Platform thinking means building once for N consumers.
+1. **Data is your crown jewel** — Never design a system where data integrity can be silently corrupted. Idempotency keys, optimistic locking, event sourcing where appropriate.
+1. **Boring by default** — Innovation tokens are precious. Proven technology wins 90% of the time. Reserve innovation for the 10% where it truly creates competitive advantage.
+1. **API-first design** — Design the API contract before implementation. The contract is the product.
+1. **Failure as information** — Blameless postmortems, error budgets, chaos engineering. Design systems to fail gracefully, not to not fail.
+1. **Org structure IS architecture** — Conway's Law. Cross-cutting services create cross-cutting coordination. Design both intentionally.
+1. **Temporal depth** — Think in 12–36 month arcs. Will this schema decision haunt you in 18 months? Will this service boundary create a migration project?
+1. **Developer experience is product quality** — Slow CI, bad DX, painful deploys → worse software, higher attrition. DX is a leading indicator.
+
+## Priority Hierarchy Under Context Pressure
+
+Step 0 > System audit > Error/failure map > Contract review > Observability plan > Test strategy > Opinionated recommendations > Everything else.
+
+## PRE-REVIEW SYSTEM AUDIT (before Step 0)
+
+Run before doing anything else:
+
+```bash
+git log --oneline -20                         # Recent history
+git diff <base> --stat                         # What's already changed
+cat TODOS.md 2>/dev/null | head -40           # Outstanding work
+ls -la openapi.yaml openapi.json asyncapi.yaml 2>/dev/null  # API contracts
+find . -name '*.proto' 2>/dev/null | head -5  # Protobuf contracts
+cat README.md 2>/dev/null | head -30          # Project overview
+```
+
+## Step 0: Mode Selection
+
+Ask the user which review mode they want:
+
+> **Question:** Which review mode?
+> **Options:**
+> A) SCOPE EXPANSION — Dream big, push scope up
+> B) SELECTIVE EXPANSION — Hold scope + surface expansion opportunities
+> C) HOLD SCOPE — Maximum rigor, make the plan bulletproof
+> D) SCOPE REDUCTION — Strip to minimum viable
+> **Default if no response:** HOLD SCOPE
+
+## Step 1: Problem Framing
+
+1. What is the **root problem** this plan is solving? (Not the stated solution — the underlying problem.)
+1. Is this the right level of abstraction to solve it? Could it be solved at a higher/lower level?
+1. Who are the consumers of this API/service/library? What is their actual need?
+1. What does "success" look like in 6 months? What metrics will you track?
+
+## Step 2: Scope & Ambition Review
+
+1. **What existing code already partially or fully solves each sub-problem?**
+1. Does the plan solve the complete problem or a shortcut version?
+1. Is the scope expansion opportunity larger than estimated? (Platform thinking)
+1. Is the scope reduction possible without sacrificing correctness?
+
+## Step 3: API & Contract Review
+
+1. What APIs or contracts does this plan introduce, change, or deprecate?
+1. Are there breaking changes? If so, what is the migration plan?
+1. Is the API design opinionated and consistent with existing conventions?
+1. Does the contract handle all error cases (not just happy path)?
+
+## Step 4: Reliability & Resilience Review
+
+1. What happens when each external dependency is unavailable?
+1. What happens under load (10x, 100x)?
+1. What are the retry semantics? Are all operations idempotent?
+1. What is the rollback strategy if a deployment fails?
+1. What is the blast radius of a failure?
+
+## Step 5: Observability Review
+
+1. What new metrics does this introduce? Are SLOs defined?
+1. What structured log events are emitted? Do they include correlation IDs?
+1. Are distributed traces created for cross-service calls?
+1. Are there new alerts? Are runbooks documented?
+
+## Step 6: Security Review
+
+1. What new attack surface does this introduce?
+1. Authentication: how is identity established for new endpoints?
+1. Authorization: what RBAC/ABAC rules apply?
+1. Input validation: is all user-controlled input validated and sanitized?
+1. Secret management: are secrets in secure storage (not env files)?
+1. OWASP Top 10: any obvious risks?
+
+## Step 7: Test Strategy Review
+
+1. What unit tests cover the happy path?
+1. What tests cover every error path and edge case?
+1. Are there contract tests for new API boundaries?
+1. Is there a smoke test plan for post-deployment verification?
+1. Is test coverage adequate for the complexity?
+
+## Step 8: Opinionated Recommendations
+
+For each finding: explain the tradeoff, give an opinionated recommendation, ask before assuming direction.
+
+## Step 9: Final Verdict
+
+- **READY TO IMPLEMENT:** Here's what to do first.
+- **NEEDS REVISION:** These specific issues must be resolved before coding.
+- **SCOPE CHANGE NEEDED:** Here's the revised scope I recommend.
+
+Present as: "Overall assessment: [READY/NEEDS REVISION/SCOPE CHANGE] because [1-2 sentence reason]."
+
+______________________________________________________________________

vstack/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Package initialization for vstack.agents."""
+
+from vstack.agents.generator import AgentGenerator
+
+__all__ = ["AgentGenerator"]

vstack/agents/config.py

@@ -0,0 +1,67 @@
+"""Agent artifact type configuration and frontmatter schema.
+
+Defines the :data:`AGENT_SCHEMA` (which frontmatter fields a ``.agent.md`` file
+uses) and the :data:`AGENT_TYPE` descriptor that configures the generator for
+the ``agents`` artifact family.
+"""
+
+from __future__ import annotations
+
+from vstack.agents.constants import AGENT_OUTPUT_SUBDIR, AGENT_OUTPUT_SUFFIX, AGENT_TEMPLATES_SUBDIR
+from vstack.artifacts.config import ArtifactTypeConfig
+from vstack.frontmatter import FieldSpec, FrontmatterSchema
+
+# ── Nested schemas ────────────────────────────────────────────────────────────
+
+#: Schema for a single ``handoffs`` entry.
+HANDOFF_ITEM_SCHEMA = FrontmatterSchema(
+    [
+        FieldSpec("label", required=True),
+        FieldSpec("agent", required=True, quoted=False),
+        FieldSpec("prompt", required=True),
+        FieldSpec("send", type="bool"),
+        FieldSpec("model"),
+    ]
+)
+
+#: Fields recognised in VS Code custom agent files (``.agent.md``).
+AGENT_SCHEMA = FrontmatterSchema(
+    [
+        FieldSpec("description"),
+        FieldSpec("name", quoted=False),
+        FieldSpec("argument-hint"),
+        FieldSpec("tools", type="list"),
+        FieldSpec("agents", type="list"),
+        # Allow model fallback lists (first available model is used).
+        FieldSpec("model", type="list"),
+        FieldSpec("user-invocable", type="bool"),
+        FieldSpec("disable-model-invocation", type="bool"),
+        FieldSpec("target", quoted=False),
+        # Handoff buttons shown after a response completes.
+        # Each entry: label (str), agent (str), prompt (str), send (bool), model (str).
+        FieldSpec("handoffs", type="object-list", item_schema=HANDOFF_ITEM_SCHEMA),
+        # MCP server config (github-copilot target only). Value is a raw YAML mapping
+        # where each key is a server name: type, command, args, tools, env.
+        FieldSpec("mcp-servers", type="raw"),
+        # Per-agent hook commands scoped to this agent (Preview, requires chat.useCustomAgentHooks).
+        # Uses the same nested format as hook config files.
+        FieldSpec("hooks", type="raw"),
+        # Arbitrary string key/value annotations (github-copilot target only).
+        FieldSpec("metadata", type="raw"),
+    ]
+)
+
+#: Type descriptor for the ``agents`` artifact family.
+AGENT_TYPE = ArtifactTypeConfig(
+    type_name="agent",
+    templates_dir=AGENT_TEMPLATES_SUBDIR,
+    output_subdir=AGENT_OUTPUT_SUBDIR,
+    output_pattern=f"{{name}}{AGENT_OUTPUT_SUFFIX}",
+    add_frontmatter=True,
+    artifact_is_dir=False,
+    partials_subdir="_partials",
+    auto_gen_footer=True,
+    fail_on_unresolved=False,
+    frontmatter_schema=AGENT_SCHEMA,
+    preserve_multiline_frontmatter=True,
+)

vstack/agents/constants.py

@@ -0,0 +1,14 @@
+"""Constants for agent template discovery and output paths."""
+
+from vstack.constants import TEMPLATES_ROOT
+
+AGENT_TEMPLATE_GLOB = "*/template.md"
+AGENT_OUTPUT_SUFFIX = ".agent.md"
+
+#: Subdirectory name under ``templates/`` holding agent source templates.
+AGENT_TEMPLATES_SUBDIR = "agents"
+
+#: Subdirectory name under the install root (e.g. ``.github/``) for agent output.
+AGENT_OUTPUT_SUBDIR = "agents"
+
+AGENT_TEMPLATES_DIR = TEMPLATES_ROOT / AGENT_TEMPLATES_SUBDIR

vstack/agents/generator.py

@@ -0,0 +1,20 @@
+"""AgentGenerator — thin wrapper around GenericArtifactGenerator for agents.
+
+Import :class:`AgentGenerator` to get a generator pre-configured for the
+``agents`` artifact type.  All behaviour is inherited from
+:class:`~vstack.artifacts.generator.GenericArtifactGenerator`.
+"""
+
+from __future__ import annotations
+
+from vstack.agents.config import AGENT_TYPE
+from vstack.artifacts.generator import GenericArtifactGenerator
+from vstack.constants import TEMPLATES_ROOT
+
+
+class AgentGenerator(GenericArtifactGenerator):
+    """Generate agent artifacts using the built-in agent type configuration."""
+
+    def __init__(self) -> None:
+        """Create an agent generator bound to the built-in template root."""
+        super().__init__(AGENT_TYPE, TEMPLATES_ROOT)

vstack/artifacts/__init__.py

@@ -0,0 +1,17 @@
+"""vstack.artifacts — shared prompt-artifact models, generator, and protocol."""
+
+from vstack.artifacts.config import INSTRUCTION_SCHEMA as INSTRUCTION_SCHEMA
+from vstack.artifacts.config import PROMPT_SCHEMA as PROMPT_SCHEMA
+from vstack.artifacts.config import ArtifactTypeConfig as ArtifactTypeConfig
+from vstack.artifacts.generator import (
+    GenericArtifactGenerator as GenericArtifactGenerator,
+)
+from vstack.artifacts.models import ArtifactResult as ArtifactResult
+from vstack.artifacts.models import RenderedArtifact as RenderedArtifact
+from vstack.artifacts.protocol import ArtifactGenerator as ArtifactGenerator
+from vstack.frontmatter import FieldSpec as FieldSpec
+from vstack.frontmatter import FieldType as FieldType
+from vstack.frontmatter import FrontmatterContent as FrontmatterContent
+from vstack.frontmatter import FrontmatterParser as FrontmatterParser
+from vstack.frontmatter import FrontmatterSchema as FrontmatterSchema
+from vstack.frontmatter import FrontmatterSerializer as FrontmatterSerializer

vstack/artifacts/config.py

@@ -0,0 +1,111 @@
+"""Artifact configuration types and built-in frontmatter schema registrations.
+
+This module provides:
+
+* :class:`ArtifactTypeConfig` — fully describes one family of prompt artifacts:
+  where to find source templates, how to derive output paths, which frontmatter
+  schema applies, and what to verify.
+* Shared schemas for **prompts** and **instructions**.
+
+Frontmatter field types (:class:`~vstack.frontmatter.FieldSpec`,
+:class:`~vstack.frontmatter.FrontmatterSchema`, :data:`~vstack.frontmatter.FieldType`)
+live in :mod:`vstack.frontmatter`.
+
+Type-specific schemas and descriptors live in their own packages:
+
+* :mod:`vstack.skills.config` — :data:`~vstack.skills.config.SKILL_SCHEMA`, :data:`~vstack.skills.config.SKILL_TYPE`
+* :mod:`vstack.agents.config` — :data:`~vstack.agents.config.AGENT_SCHEMA`, :data:`~vstack.agents.config.AGENT_TYPE`
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from vstack.frontmatter import FieldSpec, FrontmatterSchema
+
+# ── ArtifactTypeConfig ────────────────────────────────────────────────────────
+
+
+@dataclass
+class ArtifactTypeConfig:
+    """Describes a family of prompt artifacts and how to process them.
+
+    Attributes:
+        type_name:         Singular identifier used in log output and internal lookups
+                           (e.g. ``"skill"``).  Not used as a manifest key — see
+                           :attr:`manifest_key` for that.
+        manifest_key:      Key used in the manifest JSON ``artifacts`` dict
+                           (e.g. ``"skills"``).  Defaults to :attr:`output_subdir`
+                           when left empty.
+        templates_dir:     Subdirectory name under ``templates/`` that holds source templates.
+        output_subdir:     Subdirectory under the install root (``.github/``) for output.
+        output_pattern:    Output filename relative to *output_subdir*, with a ``{name}``
+                           placeholder.  Examples: ``"{name}/SKILL.md"``,
+                           ``"{name}.agent.md"``.
+        add_frontmatter:   When ``True`` the generator validates that every artifact has
+                           frontmatter (from the template or from ``config.yaml``).
+        artifact_is_dir:   When ``True`` each artifact occupies its own subdirectory
+                           (like ``skills/<name>/``).  Used by uninstall to remove the
+                           whole directory rather than a single file.
+        partials_subdir:   Subdirectory relative to *templates_dir* that contains
+                           partial snippets.  ``None`` disables partial loading.
+        template_filename: Filename of the source template inside each ``<name>/`` dir.
+        config_filename:   Optional per-artifact YAML metadata file.
+        auto_gen_footer:   When ``True``, appends the shared AUTO-GENERATED footer comment
+                           after the body. ``False`` means no footer is injected or verified.
+        placeholders:      Registry of supported placeholders for this artifact type,
+                   mapping ``TOKEN`` to the template file that defines it
+                   (e.g. ``{"SKILL_CONTEXT": "skill-context.md"}``).
+        fail_on_unresolved:   When ``True``, ``verify_output`` flags any remaining
+                           ``{{TOKEN}}`` occurrences in output files as errors.
+        frontmatter_schema: Schema controlling which fields are emitted and how.
+                           Required when *add_frontmatter* is ``True``.
+        preserve_multiline_frontmatter:
+                   When ``True``, long string fields are emitted as folded
+                   YAML scalars (``>-``) in generated frontmatter.
+    """
+
+    type_name: str
+    templates_dir: str
+    output_subdir: str
+    output_pattern: str
+    add_frontmatter: bool
+    artifact_is_dir: bool = False
+    partials_subdir: str | None = "_partials"
+    template_filename: str = "template.md"
+    config_filename: str = "config.yaml"
+    auto_gen_footer: bool = False
+    placeholders: dict[str, str] = field(default_factory=dict)
+    fail_on_unresolved: bool = False
+    frontmatter_schema: FrontmatterSchema | None = None
+    preserve_multiline_frontmatter: bool = False
+    manifest_key: str = ""
+
+    def __post_init__(self) -> None:
+        """Default ``manifest_key`` to ``output_subdir`` when not explicitly set."""
+        if not self.manifest_key:
+            self.manifest_key = self.output_subdir
+
+
+# ── Frontmatter schemas ───────────────────────────────────────────────────────
+
+#: Fields recognised in VS Code prompt files (``.prompt.md``).
+PROMPT_SCHEMA = FrontmatterSchema(
+    [
+        FieldSpec("description"),
+        FieldSpec("name", quoted=False),
+        FieldSpec("argument-hint"),
+        FieldSpec("agent", quoted=False),
+        FieldSpec("model", quoted=False),
+        FieldSpec("tools", type="list"),
+    ]
+)
+
+#: Fields recognised in VS Code instruction files (``.instructions.md``).
+INSTRUCTION_SCHEMA = FrontmatterSchema(
+    [
+        FieldSpec("name", quoted=False),
+        FieldSpec("description"),
+        FieldSpec("applyTo", quoted=False),
+    ]
+)

vstack/artifacts/constants.py

@@ -0,0 +1,6 @@
+"""Shared constants for the artifacts package."""
+
+from __future__ import annotations
+
+#: Markdown comment appended to every generated artifact that has ``auto_gen_footer=True``.
+AUTO_GEN_FOOTER = "\n<!-- AUTO-GENERATED — maintained by vstack, do not edit directly -->\n"