@sniper.ai/core 1.0.1 → 2.0.0

package/framework/commands/sniper-workspace-feature.md

@@ -0,0 +1,267 @@
+# /sniper-workspace feature -- Plan and Execute a Cross-Repo Feature
+
+You are executing the `/sniper-workspace feature` command. Your job is to plan and orchestrate a feature that spans multiple repositories in the workspace. Follow every step below precisely.
+
+The user's arguments are provided in: $ARGUMENTS
+
+---
+
+## Step 0: Pre-Flight Checks
+
+1. Verify `workspace.yaml` exists in the current directory
+   - If not, print:
+     ```
+     ERROR: No workspace found. Run /sniper-workspace init first.
+     ```
+     Then STOP.
+
+2. Read `workspace.yaml` and validate:
+   - All repository paths are accessible
+   - All repos have `.sniper/config.yaml`
+   - Dependency graph is a valid DAG
+
+3. Parse `$ARGUMENTS`:
+   - First positional argument: feature description (required)
+   - `--resume WKSP-{XXXX}`: resume an existing workspace feature
+   - `--skip-to {phase}`: skip to a specific phase (contracts | stories | sprint | validate)
+   - `--wave {N}`: resume from a specific wave
+   - `--list`: list active workspace features
+
+4. If `--list`, display active features and STOP.
+
+5. If `--resume`, load the existing feature state and skip to the appropriate phase.
+
+6. If new feature: assign the next `WKSP-{XXXX}` ID from `state.feature_counter`. Increment the counter.
+
+---
+
+## Step 1: Phase 1 — Scoping
+
+### 1a: Read Workspace Context
+1. Read `workspace.yaml` for repository topology and dependency graph
+2. For each repo, read `docs/architecture.md` (or equivalent from SNPR-0003 ingestion)
+3. Read existing contracts from `contracts/` directory
+4. Read workspace memory from `memory/` directory
+
+### 1b: Create Feature Directory
+```
+features/WKSP-{XXXX}/
+  repo-stories/
+```
+
+### 1c: Compose Orchestrator
+Compose the workspace orchestrator spawn prompt:
+```
+/sniper-compose --process workspace-orchestrator --cognitive systems-thinker --name "Workspace Orchestrator"
+```
+
+### 1d: Generate Workspace Brief
+The orchestrator agent produces the workspace feature brief:
+- Which repos are affected and why
+- What interfaces need to be created or modified
+- Wave ordering based on dependency graph
+- Written to: `features/WKSP-{XXXX}/brief.md`
+
+### 1e: Brief Review Gate
+Present the workspace brief to the user for approval.
+- If approved, proceed to Step 2
+- If rejected, revise based on feedback and re-present
+
+---
+
+## Step 2: Phase 2 — Contract Design
+
+### 2a: Read Team Definition
+Read `.sniper/teams/workspace-feature.yaml` for the team composition.
+
+### 2b: Compose Contract Designer
+```
+/sniper-compose --process contract-designer --technical api-design --cognitive systems-thinker --name "Contract Designer"
+```
+
+### 2c: Generate Contracts
+The contract designer reads the approved brief and produces:
+- Interface contracts for all cross-repo communication
+- Saved to: `contracts/{contract-name}.contract.yaml`
+- Each contract includes: endpoints, shared types, events, versioning
+
+### 2d: Contract Review Gate
+Present the contracts to the user for approval.
+- If approved, proceed to Step 3
+- If rejected, revise and re-present
+- **This is a strict gate** — contracts cannot change once approved (immutable during sprints)
+
+---
+
+## Step 3: Phase 3 — Per-Repo Story Generation
+
+For each affected repository (from the workspace brief):
+
+### 3a: Generate Repo Feature
+1. Change working context to the repo directory
+2. Run a scoped `/sniper-feature` with:
+   - The workspace feature brief as context
+   - The relevant contracts as interface specifications
+   - The repo's own architecture docs
+3. This generates stories within the repo's own `.sniper/` structure
+
+### 3b: Record Story References
+Save story references in the workspace:
+```yaml
+# features/WKSP-{XXXX}/repo-stories/{repo-name}.yaml
+repo: {repo-name}
+feature_ref: "SNPR-{XXXX}"
+stories:
+  - id: "STORY-XXX"
+    title: "{story title}"
+    contract_refs: [{contract-name}/{item}]
+```
+
+### 3c: Verify Coverage
+Check that every contract item has at least one story referencing it across all repos.
+If coverage gaps exist, flag them and ask the user whether to generate additional stories.
+
+---
+
+## Step 4: Phase 4 — Wave-Based Sprint Orchestration
+
+### 4a: Compute Wave Assignment
+From the dependency graph, assign repos to waves:
+1. Wave 1: repos with no dependencies (leaf nodes)
+2. Wave 2: repos that depend only on Wave 1 repos
+3. Wave 3: repos that depend on Wave 2 repos
+4. Continue until all repos are assigned
+
+Repos in the same wave can sprint in parallel.
+
+### 4b: Execute Each Wave
+
+For each wave (starting from Wave 1):
+
+#### Sprint Execution
+1. For each repo in the wave:
+   - Change working context to the repo directory
+   - Run `/sniper-sprint` with the feature's stories for this repo
+   - After sprint, run the repo's review gate (`/sniper-review`)
+2. If multiple repos in the wave, they can sprint in parallel
+
+#### Contract Validation (between waves)
+After all repos in the wave complete:
+1. Compose the integration validator:
+   ```
+   /sniper-compose --process integration-validator --technical backend --cognitive devils-advocate --name "Integration Validator"
+   ```
+2. Run contract validation for contracts involving repos in this wave
+3. Write validation report to: `features/WKSP-{XXXX}/validation-wave-{N}.md`
+
+#### Wave Gate
+- If validation passes: proceed to next wave
+- If validation fails:
+  1. Display the mismatches
+  2. Auto-generate fix stories in the affected repos
+  3. Run a corrective sprint for the fix stories
+  4. Re-validate
+  5. If still failing after 2 correction attempts, STOP and ask the user for guidance
+
+### 4c: Track Wave Progress
+Update the workspace feature state:
+```yaml
+state:
+  features:
+    - id: "WKSP-{XXXX}"
+      phase: sprint
+      sprint_wave: {current_wave}
+```
+
+---
+
+## Step 5: Phase 5 — Final Integration Validation
+
+After all waves complete:
+
+### 5a: Full Contract Validation
+Run contract validation across ALL contracts (not just per-wave):
+1. Check all endpoints match between producers and consumers
+2. Check all shared types are compatible
+3. Check all events have matching producer/consumer schemas
+
+### 5b: Integration Report
+Produce a final integration validation report:
+```
+============================================
+  Workspace Feature Integration Validation
+============================================
+
+  Feature: WKSP-{XXXX} — {title}
+  Waves completed: {N}
+  Repos: {list}
+
+  Contract Validation:
+    {contract-1}  v{version}  ✅ All {N} items passed
+    {contract-2}  v{version}  ✅ All {N} items passed
+
+  Overall: PASS / FAIL
+============================================
+```
+
+### 5c: Final Gate
+If PASS: proceed to Step 6
+If FAIL: present mismatches, generate fix stories, run corrective sprint
+
+---
+
+## Step 6: Feature Complete
+
+### 6a: Update Workspace State
+```yaml
+state:
+  features:
+    - id: "WKSP-{XXXX}"
+      phase: complete
+      completed_at: "{ISO 8601}"
+```
+
+### 6b: Update Contract Versions
+Bump versions on any contracts that were modified by this feature.
+
+### 6c: Trigger Workspace Memory Update
+If workspace memory is enabled:
+1. Run retros for each repo that sprinted (if not already run)
+2. Check for cross-repo conventions (patterns consistent across 2+ repos)
+3. Promote qualifying conventions to workspace memory
+
+### 6d: Present Results
+```
+============================================
+  Workspace Feature Complete
+============================================
+
+  Feature: WKSP-{XXXX} — {title}
+  Repos:   {count} repositories
+  Waves:   {count} waves
+  Stories: {count} total across all repos
+
+  Contracts Updated:
+    {contract-name} v{old} → v{new}
+
+  Memory Updates:
+    {N} workspace conventions added
+    {N} workspace anti-patterns added
+
+  All integration checks passed. Feature is complete.
+============================================
+```
+
+---
+
+## IMPORTANT RULES
+
+- **Contracts are immutable during sprint waves** — once approved, they do not change until the wave completes
+- **Wave ordering is mandatory** — never sprint a repo before its dependency wave completes
+- **Contract validation runs between every wave** — do not skip validation
+- **Each repo sprints independently** — agents in one repo do not modify files in another repo
+- **Fix stories are scoped** — corrective sprints only address specific contract mismatches
+- **The workspace orchestrator coordinates but does not code** — it stays in delegate mode
+- **Parallel execution within waves is optional** — if resources are limited, repos can sprint sequentially within a wave
+- **Always update workspace state** — the feature's phase and wave must be tracked for resume capability
+- **Workspace memory promotion requires user confirmation** unless `auto_promote: true` in workspace config

package/framework/commands/sniper-workspace-init.md

@@ -0,0 +1,252 @@
+# /sniper-workspace init -- Initialize a SNIPER Workspace
+
+You are executing the `/sniper-workspace init` command. Your job is to create a workspace that coordinates multiple SNIPER-enabled repositories. Follow every step below precisely.
+
+---
+
+## Step 0: Pre-Flight Checks
+
+1. Check if a `workspace.yaml` file exists in the current directory.
+   - If yes, print:
+     ```
+     A workspace already exists in this directory.
+
+     Workspace: {name}
+     Repositories: {count}
+
+     To add repos: /sniper-workspace add-repo <path>
+     To view status: /sniper-workspace status
+     ```
+     Then STOP.
+2. The current directory will become the workspace root. It can be:
+   - A dedicated workspace directory (recommended)
+   - An existing repo that will also serve as workspace root
+
+---
+
+## Step 1: Gather Workspace Information
+
+Ask the user for:
+1. **Workspace name** — short identifier (e.g., "my-saas-platform")
+2. **Description** — one-line description of what the workspace coordinates
+
+---
+
+## Step 2: Scan for SNIPER-Enabled Repositories
+
+1. Scan the parent directory and sibling directories for SNIPER-enabled repos:
+   - Check each directory for `.sniper/config.yaml`
+   - Also check immediate subdirectories (for monorepo-adjacent setups)
+2. For each found repo, read its `.sniper/config.yaml` to extract:
+   - `project.name`
+   - `project.type`
+   - `stack.language`
+3. Present the discovered repos:
+   ```
+   Discovered SNIPER-enabled repositories:
+
+     ✅ ../api-service      (API, typescript)
+     ✅ ../web-app           (SaaS, typescript)
+     ✅ ../shared-lib        (Library, typescript)
+     ⬜ ../unrelated-repo    (CLI, python) — not selected
+   ```
+4. Let the user select which repos to include (default: all)
+5. Let the user add additional repo paths manually
+
+---
+
+## Step 3: Auto-Detect Dependencies
+
+For each selected repository:
+
+### 3a: Package Dependencies
+1. Read `package.json` (if exists) and check for cross-repo npm dependencies
+2. If repo A's `package.json` has repo B's package name in `dependencies` or `devDependencies`, record: A depends on B
+
+### 3b: API Specs
+1. Check for `openapi.yaml`, `openapi.json`, `swagger.yaml`, or `swagger.json` in the repo root or `docs/` directory
+2. If found, record it as an exposed API spec
+
+### 3c: Type Exports
+1. Check for shared type packages by looking at `package.json` exports or main fields
+2. If a repo's name appears in another repo's imports, record the relationship
+
+### 3d: Present Detected Dependencies
+```
+Detected dependency graph:
+
+  shared-lib
+    └── api-service
+        └── web-app
+
+  web-app depends on:
+    - api-service (REST API consumer)
+    - shared-lib (npm package: @myapp/shared-types)
+
+  api-service depends on:
+    - shared-lib (npm package: @myapp/shared-types)
+
+  shared-lib depends on:
+    - (none — leaf node)
+```
+
+Let the user confirm or modify the dependency graph.
+
+---
+
+## Step 4: Determine Repository Roles
+
+For each repository, infer its role from the project type and stack:
+
+| Project Type | Inferred Role |
+|-------------|---------------|
+| saas, web | frontend |
+| api | backend |
+| library | library |
+| cli | service |
+| monorepo | service |
+| mobile | frontend |
+
+Let the user confirm or override roles.
+
+Also determine `exposes` and `consumes` for each repo based on the dependency analysis from Step 3.
+
+---
+
+## Step 5: Generate workspace.yaml
+
+Create the workspace manifest:
+
+```yaml
+name: "{workspace_name}"
+description: "{description}"
+version: "1.0"
+
+repositories:
+  - name: {repo_name}
+    path: {relative_path}
+    role: {role}
+    language: {language}
+    sniper_enabled: true
+    exposes:
+      # Auto-detected from Step 3
+      - type: rest_api | npm_package | event_bus | database_schema
+        spec: {path_to_spec}    # optional
+        package: {package_name} # for npm_package type
+    consumes:
+      # Auto-detected from Step 3
+      - from: {repo_name}
+        type: rest_api | npm_package
+        package: {package_name} # for npm_package type
+
+dependency_graph:
+  {repo_name}:
+    - {dependency_repo_name}
+
+config:
+  contract_format: yaml
+  integration_validation: true
+  shared_domain_packs: []
+  memory:
+    workspace_conventions: true
+    auto_promote: false
+
+state:
+  feature_counter: 1
+  features: []
+```
+
+Write the file to `workspace.yaml` in the current directory.
+
+---
+
+## Step 6: Create Workspace Directories
+
+Create the following directory structure:
+
+```
+memory/
+  conventions.yaml    # workspace-level: conventions: []
+  anti-patterns.yaml  # workspace-level: anti_patterns: []
+  decisions.yaml      # workspace-level: decisions: []
+contracts/
+  .gitkeep
+features/
+  .gitkeep
+```
+
+Initialize the memory YAML files with empty arrays.
+
+---
+
+## Step 7: Create Repository Symlinks (Optional)
+
+If the repos are not subdirectories of the workspace:
+
+```
+repositories/
+  api-service -> ../api-service
+  web-app -> ../web-app
+  shared-lib -> ../shared-lib
+```
+
+Ask the user if they want symlinks created. If the repos are already subdirectories, skip this step.
+
+---
+
+## Step 8: Update Per-Repo Configs
+
+For each selected repository:
+1. Read its `.sniper/config.yaml`
+2. Add or update the workspace section:
+   ```yaml
+   workspace:
+     enabled: true
+     workspace_path: "{relative_path_to_workspace}"
+     repo_name: "{this_repo_name}"
+   ```
+3. Write the updated config
+
+---
+
+## Step 9: Display Workspace Summary
+
+```
+============================================
+  SNIPER Workspace Initialized
+============================================
+
+  Name:         {workspace_name}
+  Description:  {description}
+  Location:     {current_directory}
+
+  Repositories ({count}):
+    {repo_name}  ({role}, {language})  {path}
+    ...
+
+  Dependency Graph:
+    {visual representation}
+
+  Directories Created:
+    memory/        Workspace-level memory
+    contracts/     Interface contracts
+    features/      Cross-repo feature plans
+
+  Next Steps:
+    /sniper-workspace feature "{description}"  — Plan a cross-repo feature
+    /sniper-workspace status                   — View workspace status
+
+============================================
+```
+
+---
+
+## IMPORTANT RULES
+
+- The workspace root is the current directory — do NOT create a subdirectory
+- Repository paths in workspace.yaml are always relative to the workspace root
+- Never modify a repo's source code during init — only update .sniper/config.yaml
+- If a repo is not SNIPER-enabled, warn the user and exclude it (they must run `sniper init` first)
+- The dependency graph must be a DAG (directed acyclic graph) — flag circular dependencies as errors
+- Auto-detection is best-effort — always let the user confirm and modify
+- Memory YAML files must be initialized with empty arrays, not null

package/framework/commands/sniper-workspace-status.md

@@ -0,0 +1,112 @@
+# /sniper-workspace status -- Show Workspace Status
+
+You are executing the `/sniper-workspace status` command. Your job is to display the current state of the SNIPER workspace, including repository status, active features, contracts, and memory.
+
+---
+
+## Step 0: Pre-Flight
+
+1. Verify `workspace.yaml` exists in the current directory
+   - If not, print:
+     ```
+     ERROR: No workspace found in the current directory.
+     Run /sniper-workspace init to create one.
+     ```
+     Then STOP.
+
+2. Read `workspace.yaml`
+
+---
+
+## Step 1: Repository Status
+
+For each repository in the workspace:
+1. Check if the path is accessible
+2. Read `.sniper/config.yaml` to get current phase and sprint info
+3. Count active features (from the repo's state)
+
+Display:
+```
+Repositories:
+  {name}  {role}  {language}  {phase or "idle"}  {active_features} features  {path}
+```
+
+Use status indicators:
+- ✅ accessible and SNIPER-enabled
+- ⚠️ path exists but not SNIPER-enabled
+- ❌ path not accessible
+
+---
+
+## Step 2: Active Workspace Features
+
+Read workspace `state.features` array.
+
+Display:
+```
+Workspace Features:
+  WKSP-{XXXX}  "{title}"  Phase: {phase}  Wave: {N}/{total}  {repos affected}
+```
+
+If no active features: `No active workspace features.`
+
+---
+
+## Step 3: Contracts
+
+Scan `contracts/` directory for `.contract.yaml` files.
+
+For each contract:
+1. Read the contract metadata (name, version, between, last_updated)
+2. Count endpoints, shared types, and events
+
+Display:
+```
+Contracts:
+  {name}  v{version}  {between[0]} ↔ {between[1]}  {N} endpoints, {M} types, {K} events
+```
+
+If no contracts: `No contracts defined.`
+
+---
+
+## Step 4: Workspace Memory
+
+If `memory/` directory exists:
+1. Read `memory/conventions.yaml` — count entries
+2. Read `memory/anti-patterns.yaml` — count entries
+3. Read `memory/decisions.yaml` — count entries
+
+Display:
+```
+Workspace Memory:
+  Conventions:   {N}
+  Anti-Patterns: {N}
+  Decisions:     {N}
+```
+
+If memory directory doesn't exist: `Workspace memory: not initialized`
+
+---
+
+## Step 5: Dependency Graph
+
+Read the dependency graph from `workspace.yaml`.
+
+Display a visual representation:
+```
+Dependency Graph:
+  shared-lib
+  └── api-service
+      └── web-app
+```
+
+If repos have no dependencies on each other: `All repositories are independent (no cross-dependencies).`
+
+---
+
+## IMPORTANT RULES
+
+- This is a read-only command — do not modify any files
+- If a repo path is inaccessible, show a warning but continue with other repos
+- Always show all sections even if they're empty (use "none" or "not initialized" messages)