compound-workflow 0.1.1

package/src/.agents/skills/process-metrics/assets/monthly-template.md

@@ -0,0 +1,21 @@
+---
+month: YYYY-MM
+---
+
+# Monthly Metrics
+
+## Summary
+
+- sessions: <int>
+- success: <int>
+- partial: <int>
+- failed: <int>
+- avg_minutes: <int>
+
+## Trends
+
+- <trend>
+
+## Actions
+
+- <action> (target: command|skill|agent|config)

package/src/.agents/skills/process-metrics/assets/weekly-template.md

@@ -0,0 +1,25 @@
+---
+week: YYYY-WW
+---
+
+# Weekly Metrics
+
+## Summary
+
+- sessions: <int>
+- success: <int>
+- partial: <int>
+- failed: <int>
+- avg_minutes: <int>
+
+## Top Failure Modes
+
+- <failure mode> (count)
+
+## Top Blockers
+
+- <blocker> (count)
+
+## Actions
+
+- <action> (target: command|skill|agent|config)

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

@@ -0,0 +1,83 @@
+---
+name: technical-review
+description: Use when a feature approach or plan doc has passed document review and must be checked for technical correctness before build. Triggers on "technical review", "tech review", or as next step after document review in pre-build gate.
+---
+
+# Technical Review
+
+Review a feature approach or plan document for technical alignment with architecture, code standards, and quality. Output risk level, three options with justifications, and a recommendation. Do not approve for build until the plan is updated via a second document review.
+
+## When to Use
+
+- After **document review** on a feature approach doc (pre-build gate flow).
+- When the user asks for "technical review" or "tech review" of a plan.
+- Input: document path if provided; otherwise discover latest in `docs/brainstorms/` or `docs/plans/`.
+
+## Step 1: Get the Document
+
+**If a document path is provided:** Read it, then proceed to Step 2.
+
+**If no document is specified:** Use the doc just reviewed in document review, or look for the most recent feature approach/plan in `docs/brainstorms/` or `docs/plans/` (e.g. by date prefix).
+
+## Step 2: Assess Against Technical Criteria
+
+Evaluate the plan against:
+
+| Criterion               | What to Check                                                                                                                                 |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Architecture**        | Alignment with repo architecture and patterns: layers, controllers, routing, encapsulation; no conflicting or missing patterns.            |
+| **Code standards**      | Conventions, file layout (`app/`), naming, patterns used in the repo; no conflicting patterns.                                              |
+| **Quality**             | Testability, observability, error handling, dependencies; feasibility and scope realism.                                                    |
+| **Stack and libraries** | Expo, React Native, expo-router; existing deps and APIs used correctly; no unsupported or conflicting choices.                                |
+
+Note findings. Do not fix the doc in this skill—output options and recommendation.
+
+## Step 3: Categorize Risk Level
+
+Assign one **overall** risk level for the plan:
+
+| Level      | Definition                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| **Low**    | Aligned with architecture and standards; no material unknowns; can build as described.                        |
+| **Medium** | Minor gaps or deviations; fixable in the doc or during implementation with small adjustments.                 |
+| **High**   | Material misalignment, missing patterns, or feasibility concerns; doc or approach should change before build. |
+
+State the risk level and one-line rationale.
+
+## Step 4: Three Options with Justifications
+
+For each option, provide 2–3 sentences justification:
+
+- **Option A — Proceed as-is** — When risk is low. Justify why no changes are needed.
+- **Option B — Proceed with changes** — When risk is medium. List specific doc or code changes; justify why this is sufficient.
+- **Option C — Rework or spike** — When risk is high or uncertain. Say what to rework or spike; justify why build should wait.
+
+## Step 5: Recommendation
+
+State the **preferred option** and clear rationale (e.g. "Recommend Option B because …"). Tie to the risk level and findings.
+
+## Step 6: Output and Handoff
+
+- **If pass (Option A or B with changes agreed):** Say "Approved for build" and optional notes. **Handoff:** Run **document review again** to update the plan with technical review findings (recommendation, agreed changes). Then build.
+- **If issues (Option C or B with open changes):** List issues to fix in the doc; do not approve for build until addressed. Handoff: update the plan (or re-run document review to incorporate fixes), then optionally re-run technical review.
+
+## Required Output
+
+End every technical review with:
+
+- `Risk level:` low | medium | high (plus one-line rationale)
+- `Options A/B/C:` 2–3 sentences each
+- `Recommendation:` preferred option and rationale
+- `Approved for build:` yes | no
+- `Handoff:` re-run document review to update plan with findings before build (when approved), or list issues to fix (when not approved)
+
+## What NOT to Do
+
+- Do not rewrite the plan in this skill.
+- Do not add scope or new requirements.
+- Do not approve for build when risk is high and no rework is agreed.
+- Do not skip the second document review—the plan must be updated with technical review findings before build.
+
+## Integration
+
+- **Repo:** Reference stack (Expo, React Native, expo-router) and `app/` layout from AGENTS.md when checking code standards and stack.

package/src/AGENTS.md

@@ -0,0 +1,213 @@
+# Agent Operating Principles
+
+This `.agents` workspace is portable and command-first.
+
+## Contents
+
+- Canonical Workflow
+- Non-negotiables (Structure Integrity)
+- Planning Fidelity Model
+- Routing Rules
+- Repo Configuration (Optional)
+- Directory Layout
+- Implemented Components (Current Scope)
+- Skill Index (When to Use What)
+- Reference Standards Policy (Anti-Skill-Sprawl)
+
+## Core Principles
+
+1. Commands are the public API. Skills and agents are composable internals.
+2. Core workflows stay generic. Domain-specific behavior loads only when context requires it.
+3. Planning quality is explicit via fidelity selection.
+4. Selection must be deterministic and visible: always state which skills/agents were selected and why.
+5. Brainstorm and plan do not write code.
+
+## Canonical Workflow
+
+1. `/workflow:brainstorm` -> clarify what to build
+2. `/workflow:plan` -> define how to build it
+3. `/workflow:work` -> implement
+4. `/workflow:review` -> validate quality
+5. `/workflow:compound` -> capture durable learnings
+
+Supporting command:
+
+- `/workflow:triage` -> approve and prioritize pending todos
+
+Continuous improvement:
+
+- `/metrics` -> log + assess a session and suggest improvements
+- `/assess` -> aggregate daily metrics (weekly/monthly) and propose improvements
+
+Onboarding:
+
+- `/install` -> one action: writes opencode.json, merges AGENTS.md, creates dirs, preserves Repo Config Block (run `npx compound-workflow install` in the project)
+
+This workspace currently implements `brainstorm`, `plan`, `work`, `review`, `compound`, and optional QA utilities.
+
+Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:review`, etc.). This template does not ship aliases.
+
+## Non-negotiables (Structure Integrity)
+
+- **Commands are the public API.** Keep `/workflow:*` command docs stable; add capability via skills/agents, not new command variants.
+- **Brainstorm = WHAT, Plan = HOW.** `/workflow:plan` must not re-litigate decisions already captured in `docs/brainstorms/`.
+- **Local grounding is mandatory.** Every plan must cite at least 1–3 internal file path/line refs (existing patterns) and any relevant `docs/solutions/**` learnings.
+- **Fidelity + confidence are required declarations** in every plan file: always output the Fidelity/Confidence/Research-mode block; the chosen template must include the required sections for that fidelity (Low/Medium/High).
+- **SpecFlow is a validation gate, not a rewrite engine.** High fidelity required; Medium recommended; Low optional. Output must translate into acceptance criteria/edge cases, not new scope.
+- **Skills are invoked only by trigger.** `document-review` only when user selects "Review and refine" (or explicit request); guardrail skills (PII/financial/audit/data) only when the feature touches that domain.
+- **No new files/directories by default** beyond `docs/plans/...` for planning output.
+- **Plan file is the artifact.** Post-generation options are actions on the artifact; they do not change the workflow shape.
+- **Tighten over expand.** Resolve ambiguity, standardize naming, enforce sections—avoid adding new process steps unless they reduce rework.
+
+## Planning Fidelity Model
+
+`/workflow:plan` must always declare:
+
+- `Fidelity selected`: `Low | Medium | High`
+- `Confidence`: `High | Medium | Low`
+- Why this fidelity (2-4 reasons)
+- Research mode used (`local only` or `local + external`)
+- Open questions (if any)
+
+### Selection Rules
+
+- If any high-risk trigger exists, select `High`.
+- If signals are mixed or unclear, default to `Medium`.
+- Otherwise select `Low`.
+
+High-risk triggers include: security, payments, privacy, data migration/backfills, production infra/deployment, or hard rollback.
+
+### Required Output by Fidelity
+
+- `Low`: problem, constraints, acceptance criteria, implementation outline, verification checklist.
+- `Medium`: all Low + alternatives/tradeoffs, dependency/risk table, rollout notes, observability/test notes.
+- `High`: all Medium + failure modes, rollback plan, deployment gates, migration/data safety checks, expanded test matrix.
+
+## Routing Rules
+
+- Prefer existing project patterns before introducing new ones.
+- Always run local repo + institutional learnings research first for planning.
+- Run external best-practice/framework research based on fidelity and risk.
+- For medium/high fidelity plans that touch existing behavior, consider `git-history-analyzer` to understand why the current code is the way it is.
+- Use generic fallback behavior if domain-specific skills are unavailable.
+
+## Repo Configuration (Optional)
+
+To keep this `.agents` bundle portable, prefer configuring repo-specific commands and defaults in this file.
+
+Suggested keys (examples):
+
+- `default_branch: main`
+- `dev_server_url: http://localhost:3000`
+- `test_command: npm test`
+- `test_fast_command: npm test -- --watch=false --runInBand`
+- `lint_command: npm run lint`
+- `format_command: npm run format`
+- `project_tracker: github` (or `linear`)
+- `worktree_dir: .worktrees` (optional; where worktrees are created)
+- `worktree_copy_files: [...]` (optional; env/config files to copy into new worktrees; non-overwriting)
+- `worktree_install_command: <cmd>` (optional; deps install command to run in new worktrees)
+- `worktree_bootstrap_notes: [...]` (optional; prerequisites per worktree: system deps/services/tooling; documented only)
+
+### Repo Config Block (Optional)
+
+If you want commands to read these values deterministically, add a small YAML block under this section:
+
+```yaml
+default_branch: main
+dev_server_url: http://localhost:3000
+test_command: npm test
+test_fast_command: npm test -- --watch=false
+lint_command: npm run lint
+format_command: npm run format
+project_tracker: github
+worktree_dir: .worktrees
+worktree_copy_files:
+  - .env
+  - .env.local
+worktree_install_command: npm ci
+worktree_bootstrap_notes:
+  - Ensure required system deps are installed (e.g. via brew/apt)
+  - Ensure local services are running (e.g. postgres/redis)
+  - If using direnv: run `direnv allow`
+```
+
+## Directory Layout
+
+- Commands: `.agents/commands/*.md` and `.agents/commands/workflow/*.md` (workflow namespace)
+- Skills: `.agents/skills/*/SKILL.md`
+- References: `.agents/references/**`
+- Agents: `.agents/agents/**/*.md`
+
+## Implemented Components (Current Scope)
+
+- Commands: `workflow:brainstorm`, `workflow:plan`, `workflow:work`, `workflow:triage`, `workflow:review`, `workflow:compound` (under `.agents/commands/workflow/`), plus `test-browser`, `metrics`, `assess`, `setup`, `sync` (root commands)
+- Skills: `brainstorming`, `document-review`, `technical-review`, `compound-docs`, `file-todos`, `agent-browser`, `git-worktree`, `process-metrics`, `pii-protection-prisma`, `financial-workflow-integrity`, `audit-traceability`, `data-foundations`
+- Agents:
+  - `repo-research-analyst`
+  - `learnings-researcher`
+  - `git-history-analyzer`
+  - `best-practices-researcher`
+  - `framework-docs-researcher`
+  - `spec-flow-analyzer`
+  - `lint`
+  - `bug-reproduction-validator`
+  - `agent-native-reviewer`
+
+## Skill Index (When to Use What)
+
+Skills fall into two buckets:
+
+1. Workflow skills: invoked by commands to do work (e.g. `/workflow:review`, `/workflow:compound`).
+2. Reference standards: enforce design/build guardrails when the work touches security, privacy, money, or multi-tenant data.
+
+Use reference standards proactively during `/workflow:plan`, `/workflow:work`, and PR review.
+
+## Reference Standards Policy (Anti-Skill-Sprawl)
+
+To keep this workspace usable and portable, reference standards are intentionally limited.
+
+Rules:
+
+- Cap: MAX 12 reference standards skills under `.agents/skills/`.
+- Promotion: create a new reference standard skill only if it meets at least 2 criteria:
+  - introduces MUST/MUST NOT rules that change build decisions
+  - includes required schema/contracts/checklists that can be enforced in review
+  - has operational failure modes/runbooks
+  - applies across multiple features (not one-off project trivia)
+  - prevents a high-cost incident if followed
+- Overlap: each domain has a single "owner" skill; overlapping material MUST be added to the owner skill (as a new section) or demoted to a non-skill reference doc.
+- References location: non-skill references live in `.agents/references/` (this repo: `src/.agents/references/`) and are linked from `src/AGENTS.md` or the owning skill.
+
+Owner skills:
+
+- `data-foundations`: multi-tenant boundaries (views/functions), RLS, grants/revokes, tenant context.
+- `pii-protection-prisma`: PII placement, envelope encryption, key rotation, logging restrictions.
+- `financial-workflow-integrity`: idempotency, concurrency, webhooks, approvals for money-adjacent workflows.
+- `audit-traceability`: append-only audit logs, actor attribution, correlation IDs, privileged access audit.
+
+Maintenance:
+
+- If a reference standard becomes mostly examples/links, demote it into `.agents/references/` (this repo: `src/.agents/references/`) and keep the skill as the enforceable rules/checklists only.
+
+### Workflow skills
+
+| Skill | Use when |
+| --- | --- |
+| `brainstorming` | You need structured idea exploration and clarification without writing code. |
+| `document-review` | You need to review a document/spec and extract issues, gaps, and concrete next actions. |
+| `technical-review` | A plan or feature approach has passed document review and must be checked for technical correctness before build. |
+| `compound-docs` | A non-trivial problem is solved and should be captured as durable institutional knowledge. |
+| `file-todos` | You need a file-backed todo workflow for iterative multi-step changes. |
+| `agent-browser` | You need to inspect available agents/skills and route deterministically. |
+| `git-worktree` | You need isolated parallel work (review/feature) using git worktrees. |
+| `process-metrics` | You want to log and assess session performance and process improvements. |
+
+### Reference standards (guardrails)
+
+| Skill | Use when |
+| --- | --- |
+| `data-foundations` | You are designing multi-tenant schema/access boundaries (views/functions, RLS, grants/revokes). |
+| `pii-protection-prisma` | You store/process PII and need table separation + envelope encryption + rotation + logging rules. |
+| `financial-workflow-integrity` | A workflow has money/regulatory outcomes and must be correct under retries/concurrency/webhooks/approvals. |
+| `audit-traceability` | You need append-only auditing with actor attribution + correlation IDs without leaking PII. |