@lvlup-sw/exarchos 2.0.1

package/skills/spec-review/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: spec-review
+description: "Implementation-to-spec compliance verification (code review stage 1). Use when verifying implementation matches design specification (stage 1 of /review). Checks functional completeness, TDD compliance, and test coverage. Do NOT use for code quality checks — use quality-review instead. Do NOT use for debugging."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: review
+---
+
+# Spec Review Skill
+
+## Overview
+
+Stage 1 of two-stage review: Verify implementation matches specification and follows TDD.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/review` command (first stage)
+- Task implementation is complete
+- Need to verify spec compliance before quality review
+- Subagent reports task completion
+
+## Execution Context
+
+This skill runs in a SUBAGENT spawned by the orchestrator, not inline.
+
+The orchestrator provides:
+- State file path (preferred) OR design/plan paths
+- Diff output from `~/.claude/scripts/review-diff.sh` (context-efficient)
+- Task ID being reviewed
+
+The subagent:
+- Reads state file to get artifact paths
+- Uses diff output instead of reading full files
+- Runs verification commands
+- Generates report
+- Returns verdict to orchestrator
+
+### Context-Efficient Input
+
+Instead of per-worktree diffs, receive an integrated diff from the
+integration branch (e.g., `feature/integration-branch`) against main:
+
+```bash
+# Generate integrated diff for review
+git diff main...integration > /tmp/combined-diff.patch
+
+# Alternative: use review-diff script against integration branch
+~/.claude/scripts/review-diff.sh integration main
+```
+
+This provides the complete picture of all changes across all tasks and reduces context consumption by 80-90%.
+
+## Review Scope
+
+### Review Scope: Combined Changes
+
+After delegation completes, spec review examines:
+- The **complete integrated diff** (main...feature/integration branch)
+- All changes across all tasks in one view
+- The full picture of combined functionality
+
+This enables catching:
+- Cross-task interface mismatches
+- Bugs not visible in isolation
+- Combined behavior vs specification
+
+**Spec Review focuses on:**
+- Functional completeness
+- TDD compliance
+- Specification alignment
+- Test coverage
+
+**Does NOT cover (that's Quality Review):**
+- Code style
+- SOLID principles
+- Performance optimization
+- Error handling elegance
+
+## Review Checklist
+
+For the full checklist with verification commands, tables, and report template, see `references/review-checklist.md`.
+
+**Verification:**
+```bash
+npm run test:run
+npm run test:coverage
+npm run typecheck
+scripts/check-tdd-compliance.sh --repo-root <repo-root> --base-branch main
+```
+
+## Fix Loop
+
+If review FAILS:
+
+1. Create fix task with specific issues
+2. Dispatch to implementer (same or new)
+3. Re-review after fixes
+4. Repeat until PASS
+
+```typescript
+// Return to implementer
+Task({
+  model: "opus",
+  description: "Fix spec review issues",
+  prompt: `
+# Fix Required: Spec Review Failed
+
+## Issues to Fix
+1. Missing rate limiting implementation
+   - Add rate limiter middleware
+   - Test: RateLimiter_ExceedsLimit_Returns429
+
+2. Email validation incomplete
+   - Add MX record check
+   - Test: ValidateEmail_InvalidDomain_ReturnsError
+
+## Success Criteria
+- All tests pass
+- Coverage >80%
+- All issues resolved
+`
+})
+```
+
+## Required Output Format
+
+The subagent MUST return results as structured JSON. The orchestrator parses this JSON to populate state. Any other format is an error.
+
+```json
+{
+  "verdict": "pass | fail | blocked",
+  "summary": "1-2 sentence summary",
+  "issues": [
+    {
+      "severity": "HIGH | MEDIUM | LOW",
+      "category": "spec | tdd | coverage",
+      "file": "path/to/file",
+      "line": 123,
+      "description": "Issue description",
+      "required_fix": "What must change"
+    }
+  ],
+  "test_results": {
+    "passed": 0,
+    "failed": 0,
+    "coverage_percent": 0
+  }
+}
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip to quality review | Complete spec review first |
+| Accept incomplete work | Return for fixes |
+| Review code style here | Save for quality review |
+| Approve without tests | Require test coverage |
+| Let scope creep pass | Flag over-engineering |
+
+## Cross-Task Integration Issues
+
+If an issue spans multiple tasks:
+1. Classify as "cross-task integration"
+2. Create fix task specifying ALL affected tasks
+3. Dispatch fix to implementer with context from all affected tasks
+4. Mark original tasks as blocked until cross-task fix completes
+
+## State Management
+
+### On Review Complete
+
+**Pass:**
+```
+action: "set", featureId: "<id>", updates: {
+  "reviews": { "spec": { "status": "pass", "summary": "...", "issues": [] } }
+}
+```
+
+**Fail:**
+```
+action: "set", featureId: "<id>", updates: {
+  "reviews": { "spec": { "status": "fail", "summary": "...", "issues": [{ "severity": "...", "file": "...", "description": "..." }] } }
+}
+```
+
+## Transition
+
+All transitions happen **immediately** without user confirmation:
+
+### Pre-Chain Validation (MANDATORY)
+
+Before invoking quality-review:
+1. Verify `reviews.spec.status === "pass"` in workflow state (all tasks passed)
+2. If not: "Spec review did not pass, cannot proceed to quality review"
+
+### If PASS:
+1. Update state with review results
+2. Output: "Spec review passed. Auto-continuing to quality review..."
+3. Orchestrator dispatches quality-review subagent immediately
+
+### If FAIL:
+1. Update state with failed issues
+2. Output: "Spec review found [N] issues. Auto-continuing to fixes..."
+3. Auto-invoke delegate with fix tasks:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "--fixes <plan-path>" })
+   ```
+
+This is NOT a human checkpoint - workflow continues autonomously.
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Test file not found | Task didn't create expected test | Check plan for test file paths, verify worktree contents |
+| Coverage below threshold | Implementation incomplete or tests superficial | Add missing test cases, verify assertions are meaningful |
+| TDD compliance check fails | Implementation committed before tests | Check git log order — test commits must precede or accompany implementation |
+| Diff too large for context | Many tasks with large changes | Use `review-diff.sh` with `--per-task` flag to review incrementally |
+
+## Performance Notes
+
+- Use the integrated diff (`review-diff.sh`) instead of reading full files — reduces context by 80-90%
+- Review per-task when the combined diff exceeds 2,000 lines
+- Run TDD compliance check (`scripts/check-tdd-compliance.sh`) in parallel with spec tracing

package/skills/spec-review/references/review-checklist.md

@@ -0,0 +1,60 @@
+---
+name: spec-review-checklist
+description: "Validation script invocations and report template for spec compliance verification."
+---
+
+# Spec Review Checklist
+
+## Automated Verification
+
+Run these scripts as the authoritative checks:
+
+```bash
+# TDD compliance (test-first ordering, naming conventions, coverage)
+scripts/check-tdd-compliance.sh --repo-root <repo-root> --base-branch main
+
+# Full test suite
+npm run test:run
+
+# Coverage thresholds (line >80%, branch >70%, function 100% for public APIs)
+npm run test:coverage
+
+# Type safety
+npm run typecheck
+```
+
+## Manual Checks
+
+After scripts pass, verify:
+- All spec requirements implemented (compare to design/plan)
+- No over-engineering beyond spec
+- No missing edge cases
+
+## Report Template
+
+```markdown
+## Spec Review Report
+
+### Summary
+- Status: [PASS | FAIL | NEEDS_FIXES]
+- Tested: [timestamp]
+
+### Compliance Matrix
+| Requirement | Implemented | Test Exists | Notes |
+|-------------|-------------|-------------|-------|
+
+### Issues Found
+1. [Issue] — File: `path` — Fix: [required change]
+
+### Verdict
+[PASS] Ready for quality review
+[FAIL] Return to implementer with fix list
+```
+
+## Completion Criteria
+
+- [ ] `check-tdd-compliance.sh` passes
+- [ ] All tests pass
+- [ ] Coverage meets thresholds
+- [ ] All spec requirements verified
+- [ ] State file updated with review results

package/skills/sync-schemas/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: sync-schemas
+description: "Synchronize TypeScript types from backend OpenAPI specifications. Monorepo-specific to ares-elite-platform. Use when the user says \"sync schemas\", \"update types from API\", or runs /sync-schemas. Generates TypeScript interfaces from OpenAPI spec files and validates type compatibility. Do NOT use for manual type definitions or non-OpenAPI schemas."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  category: utility
+---
+
+# Schema Sync Skill
+
+## Project Requirement
+
+This skill only works in the **ares-elite-platform** monorepo.
+Detection: check for `azure.yaml` and `apps/` directory at repo root.
+If not found: report "This skill requires the ares-elite-platform monorepo" and stop.
+
+## Overview
+
+Synchronize TypeScript types and Zod schemas from backend OpenAPI specifications. This skill can be invoked manually via `/sync-schemas` or automatically after delegation tasks that modify API files.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/sync-schemas` command
+- Subagent completes task that modified API files (auto-chain from delegation)
+- CI schema-check job fails and user wants to regenerate
+
+## Monorepo Detection
+
+Detect monorepo root and verify `azure.yaml` + `apps/` exist. Handle worktrees. See `references/configuration.md` for detection script and API file trigger patterns.
+
+## Process
+
+### Step 1: Detect Working Directory
+
+Find monorepo root via `git rev-parse --show-toplevel`. Handle `.worktrees` paths. See `references/configuration.md`.
+
+### Step 2: Run Schema Sync
+
+```bash
+npm run sync:schemas
+```
+
+This command:
+1. **Builds Aegis API** - Generates `apps/aegis-api/openapi.json`
+2. **Runs Orval** - Generates TypeScript types and Zod schemas for both Aegis and Black Gate
+3. **Rebuilds shared packages** - Compiles the generated code
+
+### Step 3: Verify TypeScript
+
+```bash
+npm run typecheck
+```
+
+### Step 4: Report Results
+
+Report what was regenerated:
+
+```markdown
+## Schema Sync Complete
+
+**OpenAPI Spec:** apps/aegis-api/openapi.json
+**TypeScript Types:** shared/types/src/generated/aegis.ts
+**Zod Schemas:** shared/validation/src/generated/aegis.zod.ts
+**Black Gate Zod:** shared/validation/src/generated/black-gate.zod.ts
+**Black Gate Component Schemas:** shared/validation/src/generated/schemas/black-gate/
+**Frontend Types:** apps/ares-elite-web/src/api/generated/aegis.schemas.ts
+
+Typecheck: PASS
+```
+
+## Auto-Detection for Delegation
+
+After delegation tasks that modify API files, auto-detect and run sync. See `references/configuration.md` for detection script, trigger patterns, and generated file mapping.
+
+## Failure Recovery
+
+### Build Failure
+```bash
+# Check for C# compilation errors
+cd apps/aegis-api && dotnet build src/Aegis.sln
+```
+
+### Orval Failure
+```bash
+# Verify OpenAPI spec exists and is valid
+cat apps/aegis-api/openapi.json | jq . > /dev/null
+```
+
+### TypeScript Errors
+TypeScript errors after sync usually indicate breaking API changes. Review the generated types and update consumers accordingly.
+
+## CI Integration
+
+The `schema-check` CI job verifies schemas are in sync:
+- Regenerates schemas from scratch
+- Compares against committed files
+- Fails if any drift detected
+
+If CI fails on schema-check, run `/sync-schemas` locally and commit the results.
+
+## Usage Examples
+
+See `references/configuration.md` for manual, post-backend-change, and worktree usage examples.
+
+## Completion Criteria
+
+- [ ] OpenAPI spec generated successfully
+- [ ] TypeScript types generated
+- [ ] Zod schemas generated
+- [ ] Black Gate Zod schemas generated
+- [ ] Typecheck passes
+- [ ] No uncommitted generated files (if committing)

package/skills/sync-schemas/references/configuration.md

@@ -0,0 +1,73 @@
+# Schema Sync Configuration
+
+Project-specific to **ares-elite-platform** monorepo.
+
+## Monorepo Detection
+
+```bash
+MONOREPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+
+if [[ ! -f "$MONOREPO_ROOT/azure.yaml" ]] || [[ ! -d "$MONOREPO_ROOT/apps" ]]; then
+  echo "ERROR: Not in ares-elite-platform monorepo"
+  exit 1
+fi
+```
+
+Handle worktrees: if `pwd` contains `.worktrees`, use the worktree root as monorepo root.
+
+## API File Trigger Patterns
+
+Schema sync is needed after modifying files matching these patterns:
+
+| Pattern | Description |
+|---------|-------------|
+| `apps/aegis-api/src/**/*Endpoints.cs` | API endpoint definitions |
+| `apps/aegis-api/src/**/Models/*.cs` | Request/response DTOs |
+| `apps/aegis-api/src/**/Requests/*.cs` | Request models |
+| `apps/aegis-api/src/**/Responses/*.cs` | Response models |
+| `apps/aegis-api/src/**/Dtos/*.cs` | Data transfer objects |
+| `apps/black-gate/src/**/*.ts` | Black Gate route definitions |
+
+## Generated Files
+
+| File | Purpose |
+|------|---------|
+| `apps/aegis-api/openapi.json` | OpenAPI specification |
+| `shared/types/src/generated/aegis.ts` | TypeScript types |
+| `shared/validation/src/generated/aegis.zod.ts` | Zod validation schemas |
+| `shared/validation/src/generated/black-gate.zod.ts` | Black Gate Zod schemas |
+| `shared/validation/src/generated/schemas/black-gate/` | Black Gate component schemas |
+| `apps/ares-elite-web/src/api/generated/aegis.schemas.ts` | TypeScript schema types |
+
+## Auto-Detection for Delegation
+
+```bash
+git diff --name-only HEAD~1 | grep -E "(Endpoints|Models|Requests|Responses|Dtos).*\.cs$"
+
+if [[ $? -eq 0 ]]; then
+  echo "API files modified - running schema sync..."
+  npm run sync:schemas
+fi
+```
+
+## Usage Examples
+
+### After Backend Changes
+```bash
+# After editing PatientEndpoints.cs
+/sync-schemas
+
+# Verify and commit via Graphite
+git add shared/ apps/ares-elite-web/src/api/generated/
+gt create chore/schema-sync -m "chore: regenerate TypeScript types from OpenAPI"
+gt submit --no-interactive --publish
+```
+
+**NEVER use `git commit` or `git push`** — always use `gt create` and `gt submit`.
+
+### In Worktree
+```bash
+cd .worktrees/task-001
+# ... make backend changes ...
+/sync-schemas
+```

package/skills/synthesis/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: synthesis
+description: "Create pull request from completed feature branch using Graphite stacked PRs. Use when the user says 'create PR', 'submit for review', 'synthesize', or runs /synthesize. Validates branch readiness, creates PR with structured description, and manages merge queue. Do NOT use before review phase completes. Not for draft PRs."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: synthesize
+---
+
+# Synthesis Skill
+
+## Overview
+
+Submit Graphite stack as pull requests after review phase completes.
+
+**Prerequisites:**
+- All delegated tasks complete
+- All reviews (spec + quality) passed — integration must be complete and passing
+- Graphite stack exists with task branches (the integration branch already exists from delegation)
+
+Requires BOTH spec-review PASS AND quality-review APPROVED. If either review is incomplete or failed, do NOT proceed — return to /exarchos:review.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/synthesize` command
+- All reviews have passed successfully
+- Ready to submit PRs
+
+## Simplified Process (Review Already Complete)
+
+Since delegation creates Graphite stack branches and review validates them, synthesis focuses on:
+1. Verifying the stack is ready
+2. Submitting the stacked PRs
+3. Handling PR feedback (if any)
+4. Cleanup after merge
+
+## Synthesis Process
+
+1. **Verify readiness** -- `scripts/pre-synthesis-check.sh` (includes phase readiness check with transition guidance)
+2. **REQUIRED: Verify/reconstruct Graphite stack** -- Run `scripts/reconstruct-stack.sh` before PR creation. If exit 1: stop and report error.
+3. **Quick test verification** -- `npm run test:run && npm run typecheck`
+4. **Check CodeRabbit reviews** -- `scripts/check-coderabbit.sh`
+5. **Write PR descriptions** -- Follow `references/pr-descriptions.md` for title format and body structure
+6. **Submit to merge queue** -- `gt submit --no-interactive --publish --merge-when-ready`
+7. **Apply benchmark label** -- If `verification.hasBenchmarks` is `true` in workflow state, apply label to each PR: `gh pr edit <number> --add-label has-benchmarks`
+8. **Cleanup after merge** -- `gt sync` + remove worktrees
+
+For detailed step instructions, see `references/synthesis-steps.md`.
+
+## Handling Failures
+
+See `references/troubleshooting.md` for test failures, PR check failures, and merge queue rejections.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip review phase | Always run `/exarchos:review` first |
+| Force push stack branches | Use normal push |
+| Delete worktrees before PR approval | Wait for merge confirmation |
+| Create PR with failing tests | Ensure review phase passes first |
+
+## State Management
+
+Call `mcp__exarchos__exarchos_workflow` for all state operations. Full parameter reference: `@skills/workflow-state/SKILL.md` § Update State.
+
+### Read Task State
+
+```
+action: "get", featureId: "<id>", fields: ["tasks", "synthesis"]
+```
+
+### On PR Created
+
+```
+action: "set", featureId: "<id>", updates: {
+  "artifacts": { "pr": ["<url1>", "<url2>"] },
+  "synthesis": { "mergeOrder": ["<branch1>", ...], "prUrl": ["<url1>", ...], "prFeedback": [] }
+}
+```
+
+### On PR Feedback Received
+
+```
+action: "set", featureId: "<id>", updates: {
+  "synthesis": { "prFeedback": [{ "pr": "<url>", "reviewer": "<name>", "status": "<status>" }] }
+}
+```
+
+### On Merge Complete
+
+```
+action: "cleanup", featureId: "<id>", mergeVerified: true, prUrl: ["<url>", ...], mergedBranches: ["<branch>", ...]
+```
+
+## Completion Criteria
+
+- [ ] Graphite stack verified via reconstruct-stack.sh
+- [ ] Quick test verification passed
+- [ ] CodeRabbit reviews checked (no CHANGES_REQUESTED blocking)
+- [ ] PRs enqueued via `--merge-when-ready`
+- [ ] PR links provided to user
+- [ ] State file updated with PR URLs
+
+## Handling PR Feedback
+
+Route to `/exarchos:delegate --pr-fixes [PR_URL]` for automated fix dispatch. See `references/troubleshooting.md` for details.
+
+## Transition
+
+After stacked PRs enqueued in merge queue, this is a **human checkpoint**:
+
+1. Update state: `action: "set", featureId: "<id>", updates: { "synthesis": { "prUrl": ["<urls>"] }, "artifacts": { "pr": ["<urls>"] } }`
+2. Output: "Stacked PRs enqueued: [URLs]. Waiting for CI/merge queue."
+3. **PAUSE for user input**: "Merge stack? (yes/no/feedback)"
+
+This is one of only TWO human checkpoints in the workflow.
+
+Options:
+- **'yes'**: Merge PR, update state to "completed"
+- **'feedback'**: Auto-continue to `/exarchos:delegate --pr-fixes` to address comments, then return here
+- **'no'**: Pause workflow, can resume later with `/exarchos:resume`
+
+## Troubleshooting
+
+See `references/troubleshooting.md` for MCP failures, state desync, PR creation issues, and stack rebase conflicts.

package/skills/synthesis/references/pr-descriptions.md

@@ -0,0 +1,87 @@
+# PR Description Guidelines
+
+Write PR descriptions that help reviewers understand the change quickly. Aim for ~120-200 words. CodeRabbit adds detailed analysis—focus on motivation and high-level changes.
+
+## Title Format
+
+`<type>: <what>` (max 72 chars)
+
+Examples:
+- `feat: Add knowledge ingestion workflow`
+- `fix: Resolve null state in workflow steps`
+- `refactor: Simplify token ledger interface`
+
+## Body Structure
+
+### Summary (required)
+2-3 sentences explaining what changed and why it matters. Include the motivation—what problem does this solve?
+
+### Changes (required)
+Scannable list of key changes. Use `**Bold**` for component names and `—` (em-dash) as separator.
+
+### Test Plan (required)
+Brief description of testing approach. What was tested and how?
+
+### Footer (required)
+Separated by `---`. Contains results, design doc, and related PRs.
+
+## Template
+
+```markdown
+## Summary
+
+[2-3 sentences: What changed, why it matters, what problem it solves]
+
+## Changes
+
+- **Component 1** — Brief description of what changed
+- **Component 2** — Brief description of what changed
+- **Component 3** — Brief description of what changed
+
+## Test Plan
+
+[1-2 sentences: Testing approach and coverage summary]
+
+---
+
+**Results:** Tests X ✓ · Build 0 errors
+**Design:** [design-doc.md](docs/path/design-doc.md)
+**Related:** #123, Continues #456
+```
+
+## Example
+
+```markdown
+## Summary
+
+Completes the Knowledge System foundation for RAG-based agent workflows. The platform needs to ingest documents, extract semantic concepts, and build a linked knowledge graph—this PR delivers that infrastructure.
+
+## Changes
+
+- **LLM Inference** — vLLM client with streaming SSE and LoRA adapter support
+- **Token Accounting** — Multi-dimensional ledger tracking usage across categories
+- **Vector Collections** — Registry with schema versioning for embedding spaces
+- **Knowledge Models** — Core types for representing extracted knowledge
+- **Ingestion Workflow** — 11-step pipeline from parsing to knowledge graph commit
+
+## Test Plan
+
+Added ~180 unit tests covering all new components. Integration tests verify the complete workflow with mocked dependencies.
+
+---
+
+**Results:** Tests 3462 ✓ · Build 0 errors
+**Design:** [shared-infrastructure.md](docs/adrs/workflow-designs/shared-infrastructure.md)
+**Related:** Continues #5
+```
+
+## Anti-Patterns
+
+Avoid these—they bloat descriptions without adding value:
+
+- Bullet lists of every file changed
+- Repeating commit messages in the body
+- Low-level implementation details (class names, method signatures)
+- "Generated with..." footers
+- Phase-by-phase breakdowns
+- Detailed test counts by project