compound-workflow 0.1.1

package/src/.agents/skills/compound-docs/references/yaml-schema.md

@@ -0,0 +1,87 @@
+# YAML Frontmatter Schema
+
+**See `.agents/skills/compound-docs/schema.yaml` for the core portable schema specification.**
+
+If present, `.agents/skills/compound-docs/schema.project.yaml` acts as an optional repo-specific overlay for stricter enums.
+
+## Required Fields
+
+- **module** (string): Module name (e.g., "EmailProcessing") or "System" for system-wide issues
+- **date** (string): ISO 8601 date (YYYY-MM-DD)
+- **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
+- **component** (string): Free text. Prefer stable slugs like [backend, frontend, database, infra, ci, auth, api, docs, tooling]
+- **symptoms** (array): 1-5 specific observable symptoms
+- **root_cause** (string): Free text. Describe the actual cause (not a symptom). Prefer stable slugs when possible.
+- **resolution_type** (enum): One of [code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update]
+- **severity** (enum): One of [critical, high, medium, low]
+
+## Optional Fields
+
+- **framework** (string): Framework/library name if relevant (e.g., rails, django, react)
+- **framework_version** (string): Framework version in X.Y.Z if known
+- **runtime_version** (string): Runtime version (e.g., ruby 3.3.1, node 20.11.0)
+- **environment** (string): dev|staging|prod|other
+- **tags** (array): Searchable keywords (lowercase, hyphen-separated). Include `spike` when the solution originated from a spike (timeboxed investigation).
+
+## Validation Rules
+
+1. All required fields must be present
+2. Enum fields must match allowed values exactly (case-sensitive)
+3. symptoms must be YAML array with 1-5 items
+4. date must match YYYY-MM-DD format
+5. tags should be lowercase, hyphen-separated
+
+## Example
+
+```yaml
+---
+module: Email Processing
+date: 2025-11-12
+problem_type: performance_issue
+component: backend
+symptoms:
+  - "N+1 query when loading email threads"
+  - "Brief generation taking >5 seconds"
+root_cause: missing_include
+framework: rails
+framework_version: 7.1.2
+resolution_type: code_fix
+severity: high
+tags: [n-plus-one, eager-loading, performance]
+---
+```
+
+Example with spike-origin doc:
+
+```yaml
+---
+module: Auth Service
+date: 2026-02-20
+problem_type: integration_issue
+component: backend
+symptoms:
+  - "Unclear whether OAuth or API keys fit our scale"
+root_cause: spike-recommendation
+resolution_type: documentation_update
+severity: medium
+tags: [spike, oauth, api-keys]
+---
+```
+
+## Category Mapping
+
+Based on `problem_type`, documentation is filed in:
+
+- **build_error** → `docs/solutions/build-errors/`
+- **test_failure** → `docs/solutions/test-failures/`
+- **runtime_error** → `docs/solutions/runtime-errors/`
+- **performance_issue** → `docs/solutions/performance-issues/`
+- **database_issue** → `docs/solutions/database-issues/`
+- **security_issue** → `docs/solutions/security-issues/`
+- **ui_bug** → `docs/solutions/ui-bugs/`
+- **integration_issue** → `docs/solutions/integration-issues/`
+- **logic_error** → `docs/solutions/logic-errors/`
+- **developer_experience** → `docs/solutions/developer-experience/`
+- **workflow_issue** → `docs/solutions/workflow-issues/`
+- **best_practice** → `docs/solutions/best-practices/`
+- **documentation_gap** → `docs/solutions/documentation-gaps/`

package/src/.agents/skills/compound-docs/schema.project.yaml

@@ -0,0 +1,18 @@
+# Optional Project Overlay Schema
+#
+# If you want stricter enums for a specific repository, fill in this file.
+# The `compound-docs` flow should prefer validating against this overlay
+# (in addition to the portable core schema.yaml).
+#
+# Notes:
+# - You can convert `component` or `root_cause` into enums for this repo.
+# - Keep `problem_type`, `severity`, and `resolution_type` aligned with core.
+
+required_fields:
+  component:
+    # Set type to enum to enforce repo-specific taxonomy.
+    type: string
+
+  root_cause:
+    # Set type to enum to enforce repo-specific taxonomy.
+    type: string

package/src/.agents/skills/compound-docs/schema.yaml

@@ -0,0 +1,119 @@
+# Portable Solution Documentation Schema
+#
+# This schema defines a portable, repo-agnostic frontmatter contract for
+# `docs/solutions/**` documentation.
+#
+# Repos may optionally provide a stricter overlay at:
+#   .agents/skills/compound-docs/schema.project.yaml
+
+required_fields:
+  module:
+    type: string
+    description: "Product area, subsystem, or module affected"
+    examples:
+      - "Authentication"
+      - "Billing"
+      - "Search"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date when this problem was solved (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - developer_experience
+      - workflow_issue
+      - best_practice
+      - documentation_gap
+    description: "Primary category of the problem"
+
+  component:
+    type: string
+    description: "Component area (free text). Prefer stable slugs."
+    examples:
+      - "backend"
+      - "frontend"
+      - "database"
+      - "infra"
+      - "ci"
+      - "auth"
+      - "api"
+      - "docs"
+      - "tooling"
+
+  symptoms:
+    type: array[string]
+    min_items: 1
+    max_items: 5
+    description: "Observable symptoms (exact error messages, behavior)"
+
+  root_cause:
+    type: string
+    description: "Actual underlying cause (free text or stable slug)"
+
+  resolution_type:
+    type: enum
+    values:
+      - code_fix
+      - migration
+      - config_change
+      - test_fix
+      - dependency_update
+      - environment_setup
+      - workflow_improvement
+      - documentation_update
+      - tooling_addition
+      - seed_data_update
+    description: "Type of fix applied"
+
+  severity:
+    type: enum
+    values:
+      - critical
+      - high
+      - medium
+      - low
+    description: "Impact severity"
+
+optional_fields:
+  tags:
+    type: array[string]
+    max_items: 8
+    description: "Searchable keywords (lowercase, hyphen-separated)"
+
+  framework:
+    type: string
+    description: "Framework/library involved (if relevant)"
+
+  framework_version:
+    type: string
+    description: "Framework version (if known)"
+
+  runtime_version:
+    type: string
+    description: "Runtime version (if known)"
+
+  environment:
+    type: string
+    description: "dev|staging|prod|other"
+
+validation_rules:
+  - "module must be non-empty"
+  - "date must be in YYYY-MM-DD format"
+  - "problem_type must match one of the enum values"
+  - "severity must match one of the enum values"
+  - "resolution_type must match one of the enum values"
+  - "symptoms must be specific and observable (not vague)"
+  - "root_cause must be the actual cause, not a symptom"
+  - "tags should be lowercase, hyphen-separated"

package/src/.agents/skills/data-foundations/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: data-foundations
+description: Enforce DB access boundaries, multi-tenant isolation (RLS), and mutation integrity patterns for scalable SaaS (Postgres + Prisma).
+---
+
+# Data Foundations (Multi-Tenant SaaS)
+
+## Purpose
+
+Establish enforceable, minimal, and scalable database patterns for multi-tenant SaaS systems.
+
+These foundations are designed to:
+
+- prevent architectural entropy
+- enforce clear data boundaries
+- preserve long-term velocity
+- reduce security and compliance risk
+- eliminate ambiguous implementation decisions
+
+These patterns are non-negotiable in greenfield systems.
+
+---
+
+## Core Foundations
+
+## 1. Data Access Boundary
+
+### Principle
+
+Tables are internal implementation details.
+
+### Rules
+
+- Reads occur only through `v_*` views.
+- Writes occur only through `fn_*` functions.
+- Application roles cannot directly access base tables.
+- Base tables are not part of the public contract.
+
+### Enforcement
+
+- `REVOKE` direct table privileges from app roles.
+- `GRANT SELECT` on views only.
+- `GRANT EXECUTE` on mutation functions only.
+
+Notes:
+
+- If `fn_*` functions use `SECURITY DEFINER`, they MUST set a safe `search_path` and MUST enforce tenant/actor context inside the function.
+
+### Naming Conventions
+
+- Tables: `snake_case`
+- Views: `v_<entity>`
+- Functions: `fn_<verb>_<entity>`
+- Primary keys: `id uuid`
+- Tenant tables include: `workspace_id`
+
+---
+
+## 2. Multi-Tenant Isolation
+
+### Principle
+
+Tenant isolation is enforced at the database layer.
+
+### Requirements
+
+- Every tenant table includes `workspace_id`.
+- RLS is enabled on all tenant tables.
+- Policies validate membership using `app.user_id` (request-scoped context).
+
+### Application Requirement
+
+Every request MUST:
+
+1. Verify JWT.
+2. Begin a transaction.
+3. Set `app.user_id` using `set_config(..., true)` (transaction-local).
+4. Execute queries inside that transaction.
+
+Failure to set context MUST result in failure.
+
+Implementation notes:
+
+- Prefer `SELECT set_config('app.user_id', '<uuid>', true);` at the start of each transaction.
+- Policies should use `current_setting('app.user_id', true)` and fail closed when missing.
+
+---
+
+## 3. Mutation Integrity
+
+### Principle
+
+All writes must be safe, auditable, and repeatable.
+
+### Required Patterns
+
+#### Audit Logging
+
+- Single append-only `audit_log` table.
+- Every mutation function inserts an audit record.
+- Logs survive soft deletes and anonymisation.
+
+Minimum audit fields:
+
+- actor_user_id
+- workspace_id
+- entity_type
+- entity_id
+- action
+- occurred_at
+
+#### Idempotency
+
+- External mutations require idempotency keys.
+- Enforced with unique constraints.
+- Replays return stored result.
+
+#### Concurrency Control
+
+Use one of:
+
+- optimistic locking (version column)
+- advisory locks for serialized workflows
+
+Concurrency control MUST live inside mutation functions.
+
+---
+
+## Schema Conventions
+
+All tenant tables MUST include:
+
+- `id uuid primary key`
+- `workspace_id uuid`
+- `created_at timestamptz`
+- `updated_at timestamptz`
+- optional: `deleted_at timestamptz`
+
+Indexes:
+
+- index `workspace_id`
+- unique constraints for business invariants
+- partial indexes for active rows when soft deleting
+
+---
+
+## Sensitive Data Strategy (Optional Foundation)
+
+If handling PII:
+
+- store PII in a separate table (e.g. `user_pii`)
+- restrict access via roles
+- never expose PII through general views
+- use anonymisation instead of hard delete
+- introduce field-level encryption only if required by threat model or regulation
+
+---
+
+## Definition of Done for New Entity
+
+For every new tenant entity:
+
+1. Base table created.
+2. RLS enabled with policy.
+3. View created (`v_<entity>`).
+4. Mutation functions created (`fn_*`).
+5. Audit logging integrated.
+6. Grants/revokes applied.
+7. Required indexes added.
+
+No entity is considered complete without all of the above.
+
+---
+
+## Philosophy
+
+These foundations are designed to:
+
+- remove ambiguity
+- reduce regression risk
+- protect tenant data
+- enable long-term speed
+- prevent multi-year architectural decay
+
+Clear boundaries enable compounding velocity.

package/src/.agents/skills/document-review/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: document-review
+description: This skill should be used to refine brainstorm or plan documents before proceeding to the next workflow step. It applies when a brainstorm or plan document exists and the user wants to improve it.
+---
+
+# Document Review
+
+Improve brainstorm or plan documents through structured review.
+
+## Step 1: Get the Document
+
+**If a document path is provided:** Read it, then proceed to Step 2.
+
+**If no document is specified:** Ask which document to review, or look for the most recent brainstorm/plan in `docs/brainstorms/` or `docs/plans/`.
+
+## Step 2: Assess
+
+Read through the document and ask:
+
+- What is unclear?
+- What is unnecessary?
+- What decision is being avoided?
+- What assumptions are unstated?
+- Where could scope accidentally expand?
+
+These questions surface issues. Don't fix yet—just note what you find.
+
+## Step 3: Evaluate
+
+Score the document against these criteria:
+
+| Criterion        | What to Check                                                                    |
+| ---------------- | -------------------------------------------------------------------------------- |
+| **Clarity**      | Problem statement is clear, no vague language ("probably," "consider," "try to") |
+| **Completeness** | Required sections present, constraints stated, open questions flagged            |
+| **Specificity**  | Concrete enough for next step (brainstorm → can plan, plan → can implement)      |
+| **YAGNI**        | No hypothetical features, simplest approach chosen                               |
+
+If invoked within a workflow (after `/workflow:brainstorm` or `/workflow:plan`), also check:
+
+- **User intent fidelity** — Document reflects what was discussed, assumptions validated
+
+For plan documents, also verify:
+
+- **Fidelity and confidence** — Declared and matches the plan depth (Low/Medium/High fidelity with High/Medium/Low confidence)
+- **Fidelity fit** — Required sections exist for the selected fidelity (e.g., rollback/failure modes for high fidelity)
+- **Confidence honesty** — Any remaining unknowns are captured as open questions (not hidden as assumptions)
+
+## Step 4: Identify the Critical Improvement
+
+Among everything found in Steps 2-3, does one issue stand out? If something would significantly improve the document's quality, this is the "must address" item. Highlight it prominently.
+
+## Step 5: Make Changes
+
+Present your findings, then:
+
+1. **Auto-fix** minor issues (vague language, formatting) without asking
+2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning)
+3. **Update** the document inline—no separate files, no metadata sections
+
+If the document is a plan file, ensure its frontmatter includes:
+
+- `fidelity: low|medium|high`
+- `confidence: high|medium|low`
+
+### Simplification Guidance
+
+Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.
+
+**Simplify when:**
+
+- Content serves hypothetical future needs, not current ones
+- Sections repeat information already covered elsewhere
+- Detail exceeds what's needed to take the next step
+- Abstractions or structure add overhead without clarity
+
+**Don't simplify:**
+
+- Constraints or edge cases that affect implementation
+- Rationale that explains why alternatives were rejected
+- Open questions that need resolution
+
+## Step 6: Offer Next Action
+
+After changes are complete, ask:
+
+1. **Refine again** - Another review pass
+2. **Review complete** - Document is ready
+
+### Iteration Guidance
+
+After 2 refinement passes, recommend completion—diminishing returns are likely. But if the user wants to continue, allow it.
+
+Return control to the caller (workflow or user) after selection.
+
+## Required Output
+
+End every review with:
+
+- `Ready for next step: yes|no`
+- `Top blocker:` one sentence
+
+## What NOT to Do
+
+- Do not rewrite the entire document
+- Do not add new sections or requirements the user didn't discuss
+- Do not over-engineer or add complexity
+- Do not create separate review files or add metadata sections

package/src/.agents/skills/file-todos/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: file-todos
+description: Manage a file-based todo tracking system in the todos/ directory. Use to create, triage, and execute persistent work items with status, priority, dependencies, and work logs.
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+---
+
+# File-Based Todo Tracking
+
+## Overview
+
+The `todos/` directory is a persistent tracking system for:
+
+- work items derived from plans
+- code review feedback
+- technical debt
+- feature follow-ups
+
+Each todo is a markdown file with YAML frontmatter and structured sections.
+
+Use this skill when:
+
+- creating new todo files
+- triaging and approving pending work
+- executing todos while maintaining a work log
+- managing dependencies
+
+## File Naming Convention
+
+Todo files follow this pattern:
+
+```
+{issue_id}-{status}-{priority}-{description}.md
+```
+
+Components:
+
+- `issue_id`: sequential (001, 002, 003...) - never reused
+- `status`: `pending` (needs triage), `ready` (approved), `complete` (done), `deferred` (not this cycle; keep as reference)
+- `priority`: `p1` (critical), `p2` (important), `p3` (nice-to-have)
+- `description`: kebab-case, brief
+
+Examples:
+
+```
+001-pending-p1-fix-auth-redirect.md
+002-ready-p2-add-pagination.md
+003-deferred-p3-follow-up-refactor.md
+005-complete-p3-update-docs.md
+```
+
+## File Structure
+
+Use the template at [todo-template.md](./assets/todo-template.md).
+
+Required sections:
+
+- Problem Statement
+- Findings
+- Proposed Solutions
+- Recommended Action
+- Acceptance Criteria
+- Work Log
+
+Frontmatter fields:
+
+```yaml
+---
+status: ready              # pending | ready | complete | deferred
+priority: p1               # p1 | p2 | p3
+issue_id: "002"
+tags: [backend, testing]
+dependencies: ["001"]     # issue_ids this is blocked by
+---
+```
+
+**Deferred:** Items with `status: deferred` are not planned for the current development cycle. Keep Problem Statement, Findings, and Work Log so the item can be re-triaged or picked up later. Only `*-ready-*.md` todos are executed; `pending` and `deferred` are non-executable.
+
+## Common Workflows
+
+### Create a New Todo
+
+1. Ensure `todos/` exists.
+2. Determine next issue id (001-based, zero-padded).
+3. Copy the template into `todos/<id>-pending-<priority>-<description>.md`.
+4. Fill:
+   - Problem Statement
+   - Proposed Solutions (at least 2 if non-trivial)
+   - Acceptance Criteria
+   - Initial Work Log entry
+5. Tag for searchability.
+
+Create a todo when it is non-trivial (>15-20 min), needs research, has dependencies, or should persist across sessions.
+
+### Create Todos From a Plan (Recommended for /workflow:work)
+
+When executing a plan, create persistent todos so progress is trackable across sessions.
+
+Inputs:
+
+- plan file path (required)
+
+Default mapping rules:
+
+1. Read the plan file completely.
+2. Detect whether the plan contains task checkboxes (`- [ ]`).
+3. If checkboxes exist:
+   - create one todo per checkbox by default
+   - group only when tasks are inseparable (e.g., schema change + required migration)
+4. If checkboxes do not exist:
+   - create 3-7 todos based on major plan phases/sections
+5. For every created todo:
+   - include the plan path in `Resources`
+   - include a "Plan checkbox" pointer when derived from a checkbox (exact text)
+   - otherwise include a short "Plan section" pointer (heading name or anchor)
+   - write Acceptance Criteria that is testable
+6. **Discussion Points and Spike Candidates:** If the plan has sections `## Discussion Points (resolve/decide)` or `## Spike Candidates (timeboxed)`:
+   - Checkboxes under **Discussion Points** → create `todos/*-pending-*.md` with `tags: [discussion]` and `status: pending`.
+   - Checkboxes under **Spike Candidates** (including items like `- [ ] Spike: ...`) → create `todos/*-pending-*.md` with `tags: [spike]` and `status: pending`.
+   - These items require triage before execution; do not default them to `ready` unless the plan is explicitly approved and triage has been run.
+
+Status and priority defaults:
+
+- `status`: `ready` when the plan is approved and the todo is not from Discussion Points or Spike Candidates; otherwise `pending`. Todos with `tags: [discussion]` or `tags: [spike]` default to `pending`.
+- `priority`: `p2` unless clearly urgent/high-risk
+
+Dependencies:
+
+- Use `dependencies:` to model sequencing.
+- Only mark a todo ready when all dependencies are complete.
+
+Plan sync expectations:
+
+- When a todo is complete, the executor should update the corresponding plan checkbox when possible.
+
+### Triage Pending Todos
+
+1. List pending todos.
+2. For each todo:
+   - read Problem Statement + Findings
+   - choose a recommended action
+   - set priority and dependencies
+3. Decision:
+   - **Approve:** rename `*-pending-*` -> `*-ready-*`, set frontmatter `status: ready`
+   - **Defer:** rename `*-pending-*` -> `*-deferred-*`, set frontmatter `status: deferred` (typically `p3`). Keep Work Log/Findings so the item is referenceable later; it will not appear in the executable queue until re-triaged to `ready`.
+4. Only `*-ready-*.md` items are executable; `pending` and `deferred` are excluded from the work loop.
+
+If this repo has a `/workflow:triage` command, it may be used. Otherwise, perform triage directly in the todo files.
+
+### Execute a Ready Todo
+
+Consider only `*-ready-*.md` todos. Ignore `pending` and `deferred`.
+
+1. Verify dependencies are complete.
+2. Work in small milestones.
+3. Update the Work Log each session with:
+   - actions (file references + commands)
+   - tests run
+   - results
+   - learnings
+4. Check off Acceptance Criteria as you complete items.
+
+### Complete a Todo
+
+1. Verify all acceptance criteria are checked.
+2. Add a final Work Log entry.
+3. Rename `*-ready-*` -> `*-complete-*`.
+4. Update frontmatter `status: ready` -> `status: complete`.
+
+## Distinctions
+
+- This is persistent, file-based tracking in `todos/`.
+- It is different from any application-level "Todo" model and different from any in-memory session todo tool.