chore: sync spec-driven workflows

Author: nirukk52

.claude-skills/backend-debugging_skill/SKILL.md

@@ -0,0 +1,15 @@
+# Common Failures
+
+| Symptom | Likely Cause | Resolution |
+| --- | --- | --- |
+| Run stuck in `queued` | Worker subscription not imported | Add `import "../agent/orchestrator/subscription";` at top of test. |
+| Service call hangs | Required service module not imported | Import relevant services, e.g. `../artifacts/store`, `../graph/encore.service.ts`. |
+| `~encore/clients` alias missing | Vitest config lacks alias | Update `backend/vitest.config.ts` with `resolve.alias['~encore'] = resolve(__dirname, './encore.gen')`. |
+| `projectedScreens: 0` | Projector queried before finishing | Poll status until `completed`, then wait ~5s before reading projector results. |
+| `budget_exhausted` after few steps | `maxSteps` too low | Increase `maxSteps` (e.g., to 20) to allow retries/backtracking. |
+
+## Fast-Fail Checks
+1. Confirm `task backend:logs` shows structured log entries for the run.
+2. Ensure Appium/device is running when the scenario requires the agent.
+3. Re-run with `encore test ./run/start.integration.test.ts -- --runInBand` for consistent reproduction.
+4. Document root cause and fix in Graphiti once resolved.

.claude-skills/backend-debugging_skill/references/common-failures.md

@@ -0,0 +1,68 @@
+# Debug Queries
+
+Use these queries inside `task backend:db:shell` or via `encore-mcp_query_database`.
+
+## Run Status & Ownership
+```sql
+SELECT run_id, status, worker_id, stop_reason, created_at, updated_at
+FROM runs
+WHERE run_id = '<runId>';
+```
+- Confirms worker claimed the run (`worker_id IS NOT NULL`).
+- Check `stop_reason` for early exits.
+
+## Event Timeline
+```sql
+SELECT seq, kind, node_name, created_at
+FROM run_events
+WHERE run_id = '<runId>'
+ORDER BY seq;
+```
+- Expect contiguous `seq` values.
+- Missing events indicate a stalled worker or failed subscription.
+
+## Graph Projector Outcomes
+```sql
+SELECT outcome_id, upsert_kind, screen_id, step_ordinal, created_at
+FROM graph_persistence_outcomes
+WHERE run_id = '<runId>'
+ORDER BY step_ordinal;
+```
+- At least one `upsert_kind = 'discovered'` when screens exist.
+
+## Projection Lag Analysis
+```sql
+SELECT
+  r.run_id,
+  r.status,
+  COUNT(re.seq)          AS events_count,
+  COUNT(gpo.outcome_id)  AS projections_count,
+  (COUNT(re.seq) - COUNT(gpo.outcome_id)) AS lag
+FROM runs r
+LEFT JOIN run_events re ON r.run_id = re.run_id
+LEFT JOIN graph_persistence_outcomes gpo ON r.run_id = gpo.run_id
+WHERE r.run_id = '<runId>'
+GROUP BY r.run_id, r.status;
+```
+- Non-zero `lag` indicates projector backlog.
+
+## Agent Snapshot
+```sql
+SELECT snapshot->>'nodeName' AS node,
+       snapshot->>'status'   AS status,
+       created_at
+FROM run_state_snapshots
+WHERE run_id = '<runId>'
+ORDER BY step_ordinal DESC
+LIMIT 1;
+```
+- Validates the last known agent state before failure.
+
+## Recent Runs
+```sql
+SELECT run_id, status, stop_reason
+FROM runs
+ORDER BY created_at DESC
+LIMIT 5;
+```
+- Quickly compare recent outcomes for pattern spotting.

.claude-skills/backend-debugging_skill/references/debug-queries.md

@@ -0,0 +1,56 @@
+# Detailed Debugging Examples
+
+## Case Study: "0 Screens Discovered"
+```typescript
+// 1. Confirm completion
+const run = await db.queryRow`
+  SELECT status, stop_reason FROM runs WHERE run_id = ${runId}
+`;
+
+// 2. Inspect events
+const events = await db.queryAll`
+  SELECT seq, kind FROM run_events WHERE run_id = ${runId} ORDER BY seq
+`;
+
+// 3. Ensure perception event exists
+const perceived = events.find((event) => event.kind === 'agent.event.screen_perceived');
+
+// 4. Check projector outcomes
+const outcomes = await db.queryAll`
+  SELECT upsert_kind FROM graph_persistence_outcomes WHERE run_id = ${runId}
+`;
+```
+**Diagnosis:** Projector lagged behind event stream.
+**Fix:** Increase polling window or delay projector assertions by ~5 seconds.
+
+## Case Study: Subscription Not Loaded
+- Symptom: Run remains `queued` and no events emitted.
+- Fix: Import worker subscription inside the test file **before** calling the service.
+
+```typescript
+import '../agent/orchestrator/subscription';
+
+it('dispatches work to the agent', async () => {
+  await start({ runId });
+  await expectRunToComplete(runId);
+});
+```
+
+## Case Study: Path Alias Missing
+- Symptom: `Error: Failed to load ~encore/clients`.
+- Fix: Update `backend/vitest.config.ts`:
+```typescript
+resolve: {
+  alias: {
+    '~encore': resolve(__dirname, './encore.gen')
+  }
+}
+```
+
+## RCA Template
+1. **Symptom:** Brief description + log snippet
+2. **Impact:** Tests affected / services failing
+3. **Root Cause:** What broke (missing import, bad config, etc.)
+4. **Fix:** Code/infra change applied
+5. **Prevention:** Follow-up actions (tests, scripts, docs)
+6. **Graphiti Entry:** Add episode with log excerpts + links

.claude-skills/backend-debugging_skill/references/detailed-examples.md

@@ -0,0 +1,39 @@
+# Diagnostic Scripts Arsenal
+
+All scripts live in `backend/scripts/` and can be executed with `bunx tsx`.
+
+## `inspect-run.ts`
+```bash
+bunx tsx backend/scripts/inspect-run.ts <runId>
+```
+Outputs run events, graph outcomes, and cursor state in chronological order. Use to confirm event sequencing and projector activity.
+
+## `check-agent-state.ts`
+```bash
+bunx tsx backend/scripts/check-agent-state.ts <runId>
+```
+Prints agent state snapshots (node name, status, counters, budgets). Ideal for tracking where a state machine stalled.
+
+## `check-cursor-ordering.ts`
+```bash
+bunx tsx backend/scripts/check-cursor-ordering.ts
+```
+Validates graph projector cursor health—identifies stuck cursors or ordering gaps.
+
+## `find-latest-run.ts` / `find-completed-runs.ts`
+```bash
+bunx tsx backend/scripts/find-latest-run.ts
+bunx tsx backend/scripts/find-completed-runs.ts
+```
+Locate recent runs for comparison when debugging regressions.
+
+## `test-projector.ts`
+```bash
+bunx tsx backend/scripts/test-projector.ts <runId>
+```
+Exercises the graph projector in isolation to validate output without rerunning the full agent flow.
+
+## Usage Tips
+- Run scripts from repo root or backend directory.
+- Combine with SQL queries to cross-check database observations.
+- Capture output snippets in Graphiti episodes when documenting RCA.

.claude-skills/backend-debugging_skill/references/diagnostic-scripts.md

@@ -0,0 +1,50 @@
+---
+name: backend-development
+description: Integration-first development patterns for Encore.ts backend services. Focuses on importing subscriptions, polling async flows, verifying database state, and keeping diagnostic tooling close at hand.
+---
+
+# Backend Development Skill
+
+## Mission
+Ship reliable Encore.ts services by exercising the full flow—API call, worker execution, projector persistence, and database validation—inside every test cycle. This skill outlines the core loop and points to detailed playbooks in `references/`.
+
+## When to Use
+- Creating or updating Encore.ts services or subscriptions
+- Writing integration tests that cover PubSub + database interactions
+- Diagnosing flaky backend tests before handing off to QA or FE
+- Preparing backend changes for CI, smoke tests, or release gates
+
+## Development Loop
+1. **Plan the flow** – Identify required subscriptions, services, and database tables; note expectations in Graphiti.
+2. **Import dependencies** – Bring subscriptions/services into the test runtime to mirror production wiring.
+3. **Execute via Encore client** – Call the service using generated types, not manual fetches.
+4. **Poll for completion** – Use polling helpers (no fixed sleeps) until the worker finishes or times out.
+5. **Assert database + logs** – Verify rows, outcomes, and structured log fields against expectations.
+6. **Clean up + document** – Remove test data, note findings in Graphiti, and link any new scripts or helpers.
+
+## Quick Command Set
+```bash
+cd backend && encore dev          # Local dev server
+cd backend && encore test         # Full test suite
+cd backend && encore test path/to.test.ts  # Focused integration test
+cd .cursor && task backend:test   # Automation layer entry point
+cd .cursor && task backend:logs   # Stream structured logs
+```
+
+## Quality Gates
+- Subscriptions imported for every PubSub interaction
+- Services and repositories typed end-to-end (no `any` or untyped SQL results)
+- Polling loops with bounded timeouts instead of `setTimeout`
+- Database cleaned after each integration test run
+- Structured logging uses `encore.dev/log` with `module`, `actor`, and identifiers
+
+## Reference Library
+- `references/integration_test_patterns.md` – Step-by-step pattern for polling, cleanup, and database verification
+- `references/api_testing_examples.md` – Example tests covering multi-service flows and assertions
+- `references/encore_mcp_testing_patterns.md` – How to combine Encore MCP with tests for live introspection
+- `WEBDRIVER_SESSION_ERRORS.md` – Known Appium/WebDriver error catalog used during agent-driven tests
+
+## Related Skills
+- `backend-debugging_skill` – Deep-dive diagnostics when runs stall or regressions persist
+- `e2e-testing_skill` – Playwright automation that consumes backend APIs end-to-end
+- `graphiti-mcp-usage_skill` – Document backend architecture and test discoveries in Graphiti