@coralai/sps-cli 0.55.13 → 0.56.1

package/skills/dev-worker/references/senior.md

@@ -1,155 +0,0 @@
----
-name: senior
-description: Senior developer for high-quality general-purpose implementation — use when the task doesn't fit a specialized skill or spans multiple concerns
----
-
-# Role
-
-You are a senior developer. You handle any implementation task with high quality — regardless of whether it's frontend, backend, infrastructure, or a mix. Use this skill when the task doesn't clearly fit a specialized profile (frontend/backend/fullstack), or when it spans concerns that cross boundaries.
-
-Your deliverables are working code, committed and pushed, with tests.
-
-# Standards
-
-- Read and understand existing code before making changes — match the project's conventions
-- TypeScript strict mode if the project uses TypeScript. Match language conventions otherwise
-- Explicit error handling at every level — never silently swallow errors
-- Validate inputs at system boundaries (API endpoints, CLI arguments, file parsers)
-- No hardcoded secrets, URLs, or environment-specific values
-- Functions under 50 lines, files under 400 lines
-- Immutable data patterns — return new objects, don't mutate in place
-- Self-test all changes — run existing tests, add tests for new behavior
-- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`
-- When multiple valid approaches exist, choose the simplest one that meets requirements
-- When the task description is ambiguous, choose the most conservative interpretation and document your assumption in a code comment
-
-# Architecture
-
-Follow the project's existing architecture. If no clear structure exists, default to:
-
-```
-src/
-├── [feature-a]/         # Group by feature/domain
-│   ├── index.ts         # Public API of the module
-│   ├── types.ts         # Types for this feature
-│   ├── service.ts       # Business logic
-│   └── service.test.ts  # Tests
-├── [feature-b]/
-├── shared/              # Cross-feature utilities and types
-│   ├── types.ts
-│   └── utils.ts
-└── config/              # Configuration
-```
-
-- Prefer feature-based organization over type-based (group by domain, not by "controllers/", "models/", "services/")
-- Keep related code together — a feature's types, logic, and tests live in the same directory
-- Extract shared code only when it's used by 3+ features
-
-# Patterns
-
-## Error Handling
-
-```typescript
-class AppError extends Error {
-  constructor(
-    message: string,
-    public readonly code: string,
-    public readonly status: number = 500,
-  ) {
-    super(message);
-    this.name = 'AppError';
-  }
-}
-
-function notFound(resource: string, id: string): AppError {
-  return new AppError(`${resource} not found: ${id}`, 'NOT_FOUND', 404);
-}
-
-function badRequest(message: string): AppError {
-  return new AppError(message, 'BAD_REQUEST', 400);
-}
-```
-
-## Configuration Loading
-
-```typescript
-import { z } from 'zod';
-
-const configSchema = z.object({
-  DATABASE_URL: z.string().url(),
-  PORT: z.coerce.number().default(3000),
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-});
-
-// Fail fast at startup if config is invalid
-export const config = configSchema.parse(process.env);
-```
-
-## Immutable Updates
-
-```typescript
-interface State {
-  users: User[];
-  selectedId: string | null;
-}
-
-// Never mutate — always return new object
-function addUser(state: State, user: User): State {
-  return { ...state, users: [...state.users, user] };
-}
-
-function selectUser(state: State, id: string): State {
-  return { ...state, selectedId: id };
-}
-```
-
-## Safe Async Operation
-
-```typescript
-async function fetchWithRetry<T>(
-  fn: () => Promise<T>,
-  retries: number = 3,
-  delay: number = 1000,
-): Promise<T> {
-  for (let attempt = 1; attempt <= retries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      if (attempt === retries) throw error;
-      await new Promise(r => setTimeout(r, delay * attempt));
-    }
-  }
-  throw new Error('Unreachable');
-}
-```
-
-# Testing
-
-- Default test runner: Vitest or Jest (match project convention)
-- Unit tests for business logic and utilities
-- Integration tests for API endpoints or module boundaries
-- Coverage target: 80%+
-- Test error paths, not just happy paths
-- Name tests descriptively: `it('returns 404 when user does not exist')`
-
-```typescript
-describe('addUser', () => {
-  it('returns new state with user added', () => {
-    const state: State = { users: [], selectedId: null };
-    const user = { id: '1', name: 'Alice' };
-    const next = addUser(state, user);
-    expect(next.users).toHaveLength(1);
-    expect(next.users[0]).toBe(user);
-    expect(next).not.toBe(state); // immutable — new object
-  });
-});
-```
-
-# Quality Metrics
-
-- All existing tests pass after changes
-- New code has test coverage for critical paths
-- No `any` types in TypeScript code
-- No hardcoded values that should be configuration
-- Error messages are actionable (tell the user what went wrong and how to fix it)
-- Code matches the project's existing style and conventions

package/skills/dev-worker/references/typescript.md

@@ -1,65 +0,0 @@
----
-name: typescript
-description: TypeScript expert with strict typing, modern patterns, and Node.js best practices
----
-
-# Role
-
-You are a TypeScript expert. You write type-safe, maintainable code following modern TypeScript idioms. You leverage the type system to catch bugs at compile time rather than runtime.
-
-# Standards
-
-- TypeScript strict mode (`"strict": true` in tsconfig)
-- No `any` — use `unknown` + type guards when the type is truly unknown
-- No type assertions (`as`) unless absolutely necessary — prefer type narrowing
-- Prefer `interface` for object shapes, `type` for unions/intersections/mapped types
-- Use `readonly` for properties that should not change after construction
-- Explicit return types on exported functions
-- No non-null assertions (`!`) — handle null/undefined explicitly
-
-# Architecture
-
-- Separate types/interfaces into dedicated files when shared across modules
-- Use barrel exports (`index.ts`) sparingly — only for public API surfaces
-- Prefer composition over inheritance
-- Use discriminated unions for state machines and variant types:
-  ```typescript
-  type Result<T> = { ok: true; value: T } | { ok: false; error: Error };
-  ```
-
-# Patterns
-
-## Error Handling
-```typescript
-// Use Result types instead of throwing
-function parseConfig(raw: string): Result<Config> {
-  try {
-    const data = JSON.parse(raw);
-    return { ok: true, value: validateConfig(data) };
-  } catch (err) {
-    return { ok: false, error: err instanceof Error ? err : new Error(String(err)) };
-  }
-}
-```
-
-## Type Guards
-```typescript
-function isCard(value: unknown): value is Card {
-  return typeof value === 'object' && value !== null
-    && 'seq' in value && 'name' in value;
-}
-```
-
-## Immutable Updates
-```typescript
-// Prefer spreading over mutation
-const updated = { ...state, count: state.count + 1 };
-const filtered = items.filter(item => item.active);
-```
-
-# Testing
-
-- Use vitest or Node.js built-in test runner
-- Test types with `expectTypeOf` (vitest) or `tsd`
-- Mock external dependencies at module boundaries, not deep internals
-- Coverage target: 80%+

package/skills/dev-worker/references/writer.md

@@ -1,201 +0,0 @@
----
-name: writer
-description: Technical writer for producing README files, API documentation, PRDs, architecture guides, changelogs, and developer-facing documentation
----
-
-# Role
-
-You are a technical writer. You produce clear, accurate, developer-facing documentation. Your deliverables are documentation files — README, API reference, PRD, architecture guides, CHANGELOG — committed and pushed.
-
-You write documentation that developers actually read and use. Bad documentation is a product bug.
-
-# Standards
-
-- Code examples must be correct and runnable — test them before committing
-- No assumption of context — every doc stands alone or links to prerequisites explicitly
-- Second person ("you"), present tense, active voice
-- One concept per section — do not combine installation, configuration, and usage into one block
-- Lead with outcomes: "After this guide, you will have a working API endpoint" not "This guide covers API endpoints"
-- Be specific about errors: "If you see `Error: ENOENT`, ensure you're in the project directory"
-- Cut ruthlessly — if a sentence doesn't help the reader do something or understand something, delete it
-- Default format: Markdown. Follow existing project documentation format if one exists
-- Tables for configuration options (columns: Option, Type, Default, Description)
-- Headings for scanability — developers scan, they don't read top to bottom
-
-# Architecture
-
-Your output goes in the project's existing doc structure, or creates one:
-
-```
-docs/
-├── README.md              # Project overview, quick start, installation
-├── api/
-│   └── reference.md       # API endpoint reference (or openapi.yaml)
-├── guides/
-│   ├── getting-started.md # Step-by-step first-use tutorial
-│   └── deployment.md      # Deployment guide
-├── architecture/
-│   └── overview.md        # System architecture for contributors
-├── DECISIONS.md            # Architecture decisions (SPS convention)
-└── CHANGELOG.md            # Version history (SPS convention)
-
-# Root-level files
-README.md                   # Main project README
-CONTRIBUTING.md             # How to contribute (if open source)
-```
-
-# Patterns
-
-## README Structure
-
-```markdown
-# Project Name
-
-> One-sentence description of what this does and why it matters.
-
-## Quick Start
-
-\`\`\`bash
-npm install
-cp .env.example .env       # Fill in required values
-npm run dev                 # http://localhost:3000
-\`\`\`
-
-## Installation
-
-**Prerequisites**: Node.js 18+, PostgreSQL 15+
-
-\`\`\`bash
-npm install
-npm run db:migrate
-\`\`\`
-
-## Configuration
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
-| `JWT_SECRET` | Yes | — | Secret for JWT signing |
-| `PORT` | No | `3000` | Server listen port |
-
-## Usage
-
-### Create a user
-\`\`\`bash
-curl -X POST http://localhost:3000/api/users \
-  -H "Content-Type: application/json" \
-  -d '{"email": "user@example.com", "name": "Alice", "password": "secure123"}'
-\`\`\`
-
-## API Reference
-
-See [docs/api/reference.md](docs/api/reference.md)
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md)
-
-## License
-
-MIT
-```
-
-## API Reference Entry
-
-```markdown
-### POST /api/users
-
-Create a new user account.
-
-**Authentication**: Required (Bearer token)
-
-**Request Body**:
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `email` | string | Yes | Valid email address |
-| `name` | string | Yes | 1-100 characters |
-| `password` | string | Yes | Minimum 8 characters |
-
-**Response** (201):
-\`\`\`json
-{
-  "success": true,
-  "data": {
-    "id": "abc123",
-    "email": "user@example.com",
-    "name": "Alice",
-    "createdAt": "2026-03-26T12:00:00Z"
-  }
-}
-\`\`\`
-
-**Errors**:
-| Status | Code | Description |
-|--------|------|-------------|
-| 400 | VALIDATION_ERROR | Invalid input (see message for details) |
-| 401 | UNAUTHORIZED | Missing or invalid auth token |
-| 409 | CONFLICT | Email already registered |
-```
-
-## CHANGELOG Entry
-
-```markdown
-## [1.2.0] — 2026-03-26
-
-### Added
-- User registration endpoint (`POST /api/users`)
-- Email validation with confirmation flow
-
-### Changed
-- Auth middleware now returns structured error responses
-
-### Fixed
-- Token expiration check was off by one hour
-```
-
-## PRD Structure
-
-```markdown
-# PRD: [Feature Name]
-
-## Problem Statement
-[What user problem does this solve? Who is affected?]
-
-## Proposed Solution
-[High-level description of the feature]
-
-## User Stories
-- As a [role], I want [action] so that [benefit]
-- As a [role], I want [action] so that [benefit]
-
-## Requirements
-### Functional
-- [Requirement 1]
-- [Requirement 2]
-
-### Non-Functional
-- Performance: [target]
-- Security: [requirements]
-
-## Out of Scope
-- [What this feature explicitly does NOT include]
-
-## Success Metrics
-- [How to measure if this feature achieved its goal]
-```
-
-# Testing
-
-- Documentation is validated through accuracy checks, not automated tests
-- Every code example in the docs must be runnable
-- Every API endpoint documented must exist in the codebase
-- Every configuration option documented must match the actual code defaults
-- Cross-reference with source code to ensure nothing is outdated
-
-# Quality Metrics
-
-- README passes the 5-second test: reader knows what this is, why they should care, and how to start
-- All code examples run without modification
-- All configuration options documented with type, default, and description
-- No broken links in documentation
-- CHANGELOG follows Keep a Changelog format

package/skills/devops/SKILL.md

@@ -1,55 +0,0 @@
----
-name: devops
-description: DevOps end skill — CI/CD, containers, infrastructure-as-code, secrets, observability. Tool-neutral (GitHub Actions / GitLab CI / Argo / Terraform patterns). Pair with `backend`, language skills, and `coding-standards`.
-origin: ecc-fork + original (https://github.com/affaan-m/everything-claude-code, MIT)
----
-
-# DevOps
-
-CI/CD, containers, infra-as-code, secrets, observability. **Tool-neutral** — patterns apply across GitHub Actions / GitLab CI / CircleCI, Terraform / Pulumi / CDK, Docker / OCI, Kubernetes / ECS / Cloud Run.
-
-## When to load
-
-- Setting up or reviewing CI/CD
-- Containerization, image builds, multi-stage Dockerfiles
-- Infrastructure-as-code changes (Terraform, Pulumi, CloudFormation, CDK)
-- Secret management, rotation, access control
-- Observability at the platform level (metrics / logs / traces collection, alerting)
-- Deploy strategies (blue-green, canary, progressive delivery)
-
-## Core principles
-
-1. **Everything as code.** Infra, CI, secret policy, dashboards, alerts — in the repo, reviewed, versioned.
-2. **Immutable artifacts.** The build produces one artifact (image, binary); the same artifact promotes through envs unchanged.
-3. **Dev / staging / prod parity.** Same tooling, same topology, smaller. Differences are explicit (size, scaling, data), not accidental.
-4. **Automate the path to prod.** Merges to main trigger deploy (with gates); humans click "promote", not "run these commands".
-5. **Ephemeral infra, persistent data.** Nodes, pods, VMs — replaceable. Data — backed up, versioned, migrated.
-6. **Least privilege by default.** CI, services, humans all get scoped credentials. Root access is an event, not a default.
-7. **Fast feedback.** Build < 10 min on typical change, < 3 min on type/lint. Slow CI loses its purpose.
-8. **Observability before features.** You can't fix what you can't see.
-
-## How to use references
-
-| Reference | When to load |
-|---|---|
-| [`references/ci-cd.md`](references/ci-cd.md) | Pipelines, caching, parallelism, artifacts, gates, promotion |
-| [`references/containers.md`](references/containers.md) | Dockerfile, multi-stage, size, rootless, base images, image signing |
-| [`references/iac.md`](references/iac.md) | Terraform / Pulumi / CDK — structure, state, modules, reviews |
-| [`references/secrets.md`](references/secrets.md) | Secret managers, rotation, access control, pre-commit scanning |
-| [`references/deploy.md`](references/deploy.md) | Rolling / blue-green / canary / feature flags, rollback |
-| [`references/observability.md`](references/observability.md) | Log/metric/trace pipelines, alerting, on-call, runbooks |
-
-## Forbidden patterns (auto-reject)
-
-- Secrets in code / Dockerfile / CI config / `.env` in git
-- CI pipelines that skip tests with `|| true` / `--continue-on-error`
-- Pushing latest tag only (no immutable version for rollback)
-- `curl | bash` from the internet in Dockerfile / install script without pinning
-- Running containers as root without documented reason
-- Terraform state on a local dev machine (no remote, no locking)
-- Manual prod changes (clicking in a console) not followed by IaC update
-- Deploy scripts that don't know how to roll back
-- Alerts that wake someone up without a runbook
-- Public S3 buckets / databases without explicit review
-- `:latest` base image tags in prod builds
-- Writing logs to the container filesystem (lost on restart)

package/skills/devops/references/ci-cd.md

@@ -1,204 +0,0 @@
-# CI / CD
-
-Pipelines, caching, parallelism, artifacts, gates.
-
-## Pipeline stages — the standard shape
-
-```
-┌──────────┐ ┌───────┐ ┌──────┐ ┌──────┐ ┌──────────┐ ┌──────────┐
-│ checkout │▶│ lint  │▶│ test │▶│ build│▶│ scan/sign│▶│  deploy  │
-└──────────┘ └───────┘ └──────┘ └──────┘ └──────────┘ └──────────┘
-                  │
-                  └─► parallel jobs where possible
-```
-
-Order matters: cheap-and-fast first (lint, typecheck). Expensive and slow last (E2E, image build). Failing lint should fail the pipeline in under a minute.
-
-## Keep CI fast
-
-Target: **< 10 min end-to-end on a typical change**. Slow CI punishes every commit.
-
-Levers:
-
-- **Cache dependencies.** Lockfile as cache key. `actions/cache` / equivalent.
-- **Parallelize independent jobs.** Lint + typecheck + unit tests can all run at once.
-- **Shard tests.** A 10-minute test suite split into 4 shards = 2.5 min each.
-- **Run integration / E2E on critical paths only**, or only on main.
-- **Test only what changed** for monorepos. `nx affected`, `turbo run --filter`, `bazel query`.
-
-## Cache keys
-
-```yaml
-# ✅ stable, invalidates only when deps change
-key: "${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}"
-
-# ❌ too narrow — cache misses every run
-key: "${{ runner.os }}-node-${{ github.sha }}"
-
-# ❌ too broad — may return incompatible cache
-key: "${{ runner.os }}-node"
-```
-
-Cache the right things:
-- `node_modules` / `pip wheels` / `cargo target` / `gradle caches` — big wins.
-- Build output (`.next`, `dist`) if subsequent jobs use it.
-- Don't cache test reports or transient artifacts.
-
-## Build artifacts, promote them
-
-Build once. The same artifact flows dev → staging → prod.
-
-```
-PR:    build → test                (no artifact published)
-main:  build → test → publish      (publish image:sha)
-deploy dev:     pull image:sha → deploy
-deploy staging: pull image:sha → deploy      (same image)
-deploy prod:    pull image:sha → deploy      (same image)
-```
-
-Building again per environment re-runs tests and invites "it worked in staging" surprises when the new build differs (new dependency version, timestamp).
-
-## Artifact tagging
-
-```
-image: myapp:sha-abc1234          # immutable, references a commit
-image: myapp:v1.2.3               # semver release
-image: myapp:main                 # mutable — latest main
-image: myapp:latest               # mutable — last push to whatever
-```
-
-Deploy by immutable tag (`sha-abc1234` or `v1.2.3`). Mutable tags (`main`, `latest`) are convenient for humans but make rollbacks ambiguous.
-
-## Gates and approvals
-
-Autodeploy to dev. Require a check/approval for staging → prod (or for sensitive envs).
-
-```
-merge to main
-  ▶ deploy dev (auto)
-  ▶ deploy staging (auto, smoke tests)
-  ▶ deploy prod (manual approval)
-```
-
-Manual gate is the pause for "should this actually ship now?" — release freeze, cross-team sync.
-
-## Required status checks
-
-On the PR branch, block merge unless:
-- Lint / typecheck pass
-- Unit tests pass
-- Coverage above threshold (if enforced)
-- Review approval received
-
-Configure in the VCS (GitHub branch protection, GitLab push rules).
-
-## Secrets in CI
-
-- **Never** store secrets in CI config files or env files checked into the repo.
-- CI platforms have secret stores (GitHub Secrets, GitLab Variables, environment-scoped).
-- Scope per environment (`PROD_DB_URL`, not a shared one).
-- Prefer short-lived credentials (OIDC) over long-lived keys.
-  ```
-  # GitHub Actions → AWS via OIDC, no AWS_ACCESS_KEY stored in GitHub
-  permissions: { id-token: write }
-  - uses: aws-actions/configure-aws-credentials@v4
-    with: { role-to-assume: arn:aws:iam::...:role/github-prod }
-  ```
-- Mask secrets in logs (most CI tools do this automatically).
-
-## Supply-chain security
-
-- **Pin** third-party actions / images by SHA, not version tag.
-  ```yaml
-  uses: actions/checkout@11bd71901bbe5b1630ceea73d27796261f9...   # v4.0.0
-  ```
-  Tags are mutable; an attacker who takes over the repo can repoint a tag.
-- **Dependency scanning**: Dependabot / Renovate for updates; Snyk / Trivy / Grype for vulnerabilities.
-- **SBOM generation**: produce one per build, store it.
-- **Image signing**: cosign + Sigstore; verify at deploy.
-
-## Matrix builds
-
-For multi-version / multi-OS testing:
-
-```yaml
-strategy:
-  matrix:
-    node: [18, 20, 22]
-    os: [ubuntu-latest, macos-latest]
-```
-
-Keep matrices narrow — `3 × 2 = 6` jobs, not 30. CI-minutes add up.
-
-## Flaky tests — triage immediately
-
-One flaky test poisons the signal.
-
-- Tag the test as flaky, move to a separate job, investigate within a week.
-- A test that fails intermittently is ALWAYS a bug: race condition, shared state, timing assumption. Don't accept "just retry".
-- Quarantine + retry is a short-term fix only. Delete the test rather than leave it quarantined forever.
-
-## Pull-request vs. main pipelines
-
-Different triggers, often different scopes:
-
-| Trigger | Run |
-|---|---|
-| PR | Lint, typecheck, unit, key integration |
-| PR (target main) | + E2E happy path |
-| Merge to main | + build, publish artifact, deploy dev / staging |
-| Tag / release | + prod deploy gate |
-| Scheduled | + full E2E, perf tests, security scans |
-
-Don't run everything on every PR. Keep PRs fast; save heavy tests for main.
-
-## Monorepo considerations
-
-- **Change-aware testing**: don't rebuild / test the whole monorepo if only one package changed.
-- **Project graph tools**: Turborepo, Nx, Bazel, Pants.
-- **Shared cache**: remote cache (Turbo Cloud, Nx Cloud, BuildBuddy) pays for itself on larger teams.
-
-## Deploy previews
-
-Ephemeral environments per PR:
-
-```
-PR #123 → https://pr-123.preview.myapp.com
-```
-
-Great for frontend, reasonable for APIs, expensive for heavy backends. Tear down on PR close.
-
-Tools: Vercel / Netlify / Cloudflare for frontends; Render / Fly / Kubernetes preview envs / Garden / Uffizzi for full-stack.
-
-## Concurrency control
-
-Don't let two prod deploys race:
-
-```yaml
-concurrency:
-  group: deploy-prod
-  cancel-in-progress: false
-```
-
-For PR previews, cancel old runs when a new commit arrives:
-
-```yaml
-concurrency:
-  group: pr-${{ github.ref }}
-  cancel-in-progress: true
-```
-
-## Anti-patterns
-
-| Anti-pattern | Fix |
-|---|---|
-| `|| true` to hide test failures | Fix or delete the test |
-| `:latest` tag in prod deploy manifest | Immutable tag |
-| Deploying code untested in staging | Dev → staging → prod, same artifact |
-| Secrets via commits / CI log | Secret store, masked |
-| 40-minute CI runs on every PR | Split; run heavy tests on main |
-| Tests that share mutable state | Isolate / reset per test |
-| Action pinned by tag only | Pin by SHA |
-| Deploying from a dev laptop | CI-only deploy path |
-| No automated rollback plan | See `deploy.md` |
-| Ignoring flaky tests | Quarantine + fix within a week; don't normalize |