From 34c1ba2f9f61fe8bd26dc127af61ea29b513e2b4 Mon Sep 17 00:00:00 2001 From: Mac Tichner Date: Fri, 17 Apr 2026 11:39:59 -0400 Subject: [PATCH] Update Archon configuration and setup documentation - Added a new configuration option to copy local .env files into isolated worktrees for Scout MCP compatibility. - Removed outdated note regarding Claude Code binary path from setup documentation. - Renumbered subsequent steps in the setup guide for clarity. --- .../defaults/scout-consolidate-perf-plan.md | 96 ++++ .../defaults/scout-discover-routes.md | 67 +++ .archon/config.yaml | 3 + .../defaults/archon-scout-perf-roadmap.yaml | 488 ++++++++++++++++++ .claude/skills/archon/guides/setup.md | 6 +- .../hooks/state/continual-learning-index.json | 11 + .cursor/hooks/state/continual-learning.json | 8 + .cursor/mcp.json | 12 + AGENTS.md | 6 + 9 files changed, 693 insertions(+), 4 deletions(-) create mode 100644 .archon/commands/defaults/scout-consolidate-perf-plan.md create mode 100644 .archon/commands/defaults/scout-discover-routes.md create mode 100644 .archon/workflows/defaults/archon-scout-perf-roadmap.yaml create mode 100644 .cursor/hooks/state/continual-learning-index.json create mode 100644 .cursor/hooks/state/continual-learning.json create mode 100644 .cursor/mcp.json create mode 100644 AGENTS.md diff --git a/.archon/commands/defaults/scout-consolidate-perf-plan.md b/.archon/commands/defaults/scout-consolidate-perf-plan.md new file mode 100644 index 0000000000..7d5f12e9b3 --- /dev/null +++ b/.archon/commands/defaults/scout-consolidate-perf-plan.md @@ -0,0 +1,96 @@ +--- +description: Merge per-route Scout profiles into a single implementation plan (plan.md) +argument-hint: (no arguments) +--- + +# Consolidate Scout performance plan + +**Workflow ID**: $WORKFLOW_ID +**Artifacts**: $ARTIFACTS_DIR + +--- + +## Mission + +Read: + +- `$ARTIFACTS_DIR/routes.json` +- `$ARTIFACTS_DIR/routes-summary.md` +- `$ARTIFACTS_DIR/profile-00.md` … `$ARTIFACTS_DIR/profile-09.md` (include only files that exist; skipped indices may say SKIPPED) + +Produce **one** implementation plan at **`$ARTIFACTS_DIR/plan.md`** that `archon-plan-setup` / `archon-confirm-plan` / `archon-implement-tasks` can consume. + +--- + +## Plan template (required sections) + +Use this structure (fill with real content from profiles): + +```markdown +# Performance: Scout hot-route optimizations + +## Summary +{1–2 sentences} + +## Mission +{Single goal statement} + +## NOT Building (Scope Limits) +- {Explicit non-goals — e.g. unrelated refactors, new features} +- Do not change behavior except latency/resource usage unless noted. + +## Success Criteria +- [ ] Each targeted route has measurable improvement or documented tradeoff +- [ ] Project validation suite passes (see CLAUDE.md) +- [ ] Scout shows no new regressions for these endpoints after deploy (verification note) + +## Files to Change + +| File | Action | +|------|--------| +| `{path}` | UPDATE | + +## Patterns to Mirror + +| Pattern | Source File | Lines | +|---------|-------------|-------| +| {name} | `{path}` | {lines} | + +## Task List + +### Task 1: {title} +**Action**: UPDATE +**Details**: {specific changes} +**Route**: `{METHOD} {path}` +**Validate**: {command} + +### Task 2: ... + +(Add one or more tasks per route or grouped fix.) + +## Validation Commands +1. Commands from CLAUDE.md / package.json (typecheck, lint, test). + +## Risks + +| Risk | Impact | Mitigation | +|------|--------|------------| +| {risk} | {H/M/L} | {mitigation} | +``` + +--- + +## Rules + +1. **Deduplicate** overlapping tasks if multiple profiles touch the same file. +2. **Order** tasks by dependency (models before handlers, shared utils first). +3. **Reference** actual symbols/files from the profile markdown files. +4. If profiles disagree, prefer the most evidence-backed recommendation and note the conflict in **Risks**. +5. Ignore profiles that are SKIPPED or empty. + +--- + +## Output + +- Write **`$ARTIFACTS_DIR/plan.md`** only (plan-setup will create `plan-context.md`). +- Stdout: `Plan written to $ARTIFACTS_DIR/plan.md with {N} tasks.` diff --git a/.archon/commands/defaults/scout-discover-routes.md b/.archon/commands/defaults/scout-discover-routes.md new file mode 100644 index 0000000000..d6a11ee320 --- /dev/null +++ b/.archon/commands/defaults/scout-discover-routes.md @@ -0,0 +1,67 @@ +--- +description: Query Scout APM for top slow + high-traffic routes and write routes.json +argument-hint: "[optional app name or app id — else first active app]" +--- + +# Scout route discovery + +**User message**: $ARGUMENTS +**Artifacts**: $ARTIFACTS_DIR + +--- + +## Mission + +Use **Scout MCP** tools to identify **up to 10 HTTP routes** to optimize. Combine: + +- **Slowest** endpoints (p95 / mean response time), and +- **Most hit** (throughput / request volume) + +Dedupe by route identity (method + path). If you have fewer than 10 distinct hot/slow routes, include the next candidates by severity. If Scout returns fewer than 10, use all available. + +--- + +## Prerequisites + +1. **MCP**: Scout tools should be available (`list_apps`, `get_app_endpoints`, `get_endpoint_metrics`, etc.). If MCP is unavailable, ask the user to set `SCOUT_API_KEY`, ensure Docker can run `scoutapp/scout-mcp-local`, or paste a Scout endpoints export into `$ARTIFACTS_DIR/scout-endpoints-export.json` (array of endpoint objects) and continue from that file. + +2. **App selection**: If `$ARGUMENTS` names an app or numeric id, use that. Otherwise call `list_apps` and pick the production app that matches this repo (name/hostname) or the most recently active app. State which app you chose. + +--- + +## Steps + +1. Call Scout MCP to list endpoints with metrics for the chosen app (`get_app_endpoints` or equivalent). + +2. Rank and select up to **10** routes using a clear rule, e.g.: + - Take top **5** by p95 latency (or worst mean response time if p95 missing). + - Take top **5** by throughput. + - Union, dedupe, then fill remaining slots by composite score: `latency × log(throughput)` or similar. + +3. Write **`$ARTIFACTS_DIR/routes.json`** — JSON array of exactly the chosen routes, each object including at least: + + - `rank` (1–10) + - `method` (e.g. `GET`) + - `path` (e.g. `/api/foo`) + - `scout_name` or endpoint id if the API exposes one + - `p95_ms`, `mean_ms` (numbers or null) + - `rpm` or throughput (number or null) + - `error_rate` if available + +4. Write **`$ARTIFACTS_DIR/routes-summary.md`** — human-readable table: rank, method, path, p95, throughput, notes. + +5. Print a one-line stdout summary: `Discovered N routes for app {name} (id {id}).` + +--- + +## Error handling + +- If no endpoints are returned: write `routes.json` as `[]`, explain in summary, and STOP with a clear error in stdout so the workflow can fail visibly. + +--- + +## Success criteria + +- `routes.json` exists and is valid JSON. +- `routes-summary.md` exists. +- At most 10 routes; each profile step can rely on fixed indices `0..N-1`. diff --git a/.archon/config.yaml b/.archon/config.yaml index beadf10287..fc7d70da71 100644 --- a/.archon/config.yaml +++ b/.archon/config.yaml @@ -1,5 +1,8 @@ worktree: baseBranch: dev + # Copy local .env into isolated worktrees so Scout MCP sees SCOUT_API_KEY when cwd is ~/.archon/workspaces/... + copyFiles: + - .env docs: path: packages/docs-web/src/content/docs diff --git a/.archon/workflows/defaults/archon-scout-perf-roadmap.yaml b/.archon/workflows/defaults/archon-scout-perf-roadmap.yaml new file mode 100644 index 0000000000..e5b561ea81 --- /dev/null +++ b/.archon/workflows/defaults/archon-scout-perf-roadmap.yaml @@ -0,0 +1,488 @@ +name: archon-scout-perf-roadmap +description: | + Use when: Optimizing app performance using Scout APM. + Does: + 1. Scout MCP — top 10 slow + high-traffic HTTP routes + 2. Parallel analysis (10 nodes) — profile each route in the codebase + traces + 3. Consolidated optimization plan + 4. Interactive plan review until user approves + 5. Implement via plan pipeline (draft PR) + 6. Multi-agent code review + self-fix + 7. Mark PR ready when review satisfied + + Requires: SCOUT_API_KEY (self-hosted Docker MCP) or Scout endpoints export; Docker for scout-mcp-local. + Input: Optional app name/id after workflow message; e.g. "My App Name" or leave default. + + NOT for: Performance work without Scout (use archon-assist) or non-HTTP routes only. + +provider: claude +model: sonnet +interactive: true + +nodes: + # ═══════════════════════════════════════════════════════════════ + # PHASE 1 — Scout discovery + # ═══════════════════════════════════════════════════════════════ + + - id: discover-routes + command: scout-discover-routes + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-00 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 0 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-00.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 0, write to `$ARTIFACTS_DIR/profile-00.md` a single line `SKIPPED: no route at index 0` and stop. + 2. Otherwise take the route object at index 0. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-00.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-01 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 1 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-01.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 1, write to `$ARTIFACTS_DIR/profile-01.md` a single line `SKIPPED: no route at index 1` and stop. + 2. Otherwise take the route object at index 1. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-01.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-02 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 2 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-02.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 2, write to `$ARTIFACTS_DIR/profile-02.md` a single line `SKIPPED: no route at index 2` and stop. + 2. Otherwise take the route object at index 2. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-02.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-03 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 3 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-03.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 3, write to `$ARTIFACTS_DIR/profile-03.md` a single line `SKIPPED: no route at index 3` and stop. + 2. Otherwise take the route object at index 3. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-03.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-04 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 4 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-04.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 4, write to `$ARTIFACTS_DIR/profile-04.md` a single line `SKIPPED: no route at index 4` and stop. + 2. Otherwise take the route object at index 4. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-04.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-05 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 5 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-05.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 5, write to `$ARTIFACTS_DIR/profile-05.md` a single line `SKIPPED: no route at index 5` and stop. + 2. Otherwise take the route object at index 5. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-05.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-06 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 6 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-06.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 6, write to `$ARTIFACTS_DIR/profile-06.md` a single line `SKIPPED: no route at index 6` and stop. + 2. Otherwise take the route object at index 6. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-06.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-07 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 7 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-07.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 7, write to `$ARTIFACTS_DIR/profile-07.md` a single line `SKIPPED: no route at index 7` and stop. + 2. Otherwise take the route object at index 7. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-07.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-08 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 8 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-08.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 8, write to `$ARTIFACTS_DIR/profile-08.md` a single line `SKIPPED: no route at index 8` and stop. + 2. Otherwise take the route object at index 8. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-08.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + - id: profile-09 + prompt: | + You are **one of ten parallel profilers** for the Scout performance roadmap. + + **Assigned index**: 9 (0-based). **Profile file**: `$ARTIFACTS_DIR/profile-09.md` + + ## Steps + + 1. Read `$ARTIFACTS_DIR/routes.json`. If there is **no** element at index 9, write to `$ARTIFACTS_DIR/profile-09.md` a single line `SKIPPED: no route at index 9` and stop. + 2. Otherwise take the route object at index 9. Map it to this codebase (routers, handlers, middleware, DB). + 3. Use **Scout MCP** when available: `get_endpoint_metrics`, `get_app_endpoint_traces`, `get_app_insights` for this app/endpoint to explain **where** time is spent (N+1, slow queries, external I/O, etc.). + 4. Read CLAUDE.md and search the codebase for the implementation path. + 5. Write **`$ARTIFACTS_DIR/profile-09.md`** with: + - Route identity (method + path) + - Scout metrics summary + - Code path (files + symbols) + - Root causes of slowness + - Concrete optimization ideas (caching, batching, indexes, async, etc.) + + Keep stdout to a short summary line for logs. + depends_on: [discover-routes] + context: fresh + mcp: .archon/mcp/scout-apm.json + + # ═══════════════════════════════════════════════════════════════ + # PHASE 2 — Single plan from profiles + # ═══════════════════════════════════════════════════════════════ + + - id: consolidate-plan + command: scout-consolidate-perf-plan + depends_on: [profile-00, profile-01, profile-02, profile-03, profile-04, profile-05, profile-06, profile-07, profile-08, profile-09] + context: fresh + + # ═══════════════════════════════════════════════════════════════ + # PHASE 3 — Interactive plan review (human edits) + # ═══════════════════════════════════════════════════════════════ + + - id: refine-plan + depends_on: [consolidate-plan] + loop: + prompt: | + # Scout perf roadmap — Plan review + + The consolidated plan lives at `$ARTIFACTS_DIR/plan.md`. + + **User's latest message**: $LOOP_USER_INPUT + + --- + + ## If the first iteration (no user input yet): + + 1. Read `$ARTIFACTS_DIR/plan.md` and `$ARTIFACTS_DIR/routes-summary.md`. + 2. Present a clear summary: goals, tasks, risks, and what will change. + 3. Ask for feedback (scope, ordering, risk tradeoffs). + + **Do not** emit `PLAN_APPROVED` on the first iteration. + + ## If the user gave feedback: + + 1. Edit `$ARTIFACTS_DIR/plan.md` to incorporate changes (tasks, scope, exclusions). + 2. Show what changed. + 3. Ask for more feedback or approval. + + ## If the user gave **explicit approval** (e.g. "approved", "looks good", "implement", "ship it"): + + Output: "Plan approved. Proceeding to implementation setup." + Then emit: `PLAN_APPROVED` + + **CRITICAL**: Never emit `PLAN_APPROVED` unless the latest user message clearly approves. Questions are not approval. + until: PLAN_APPROVED + max_iterations: 15 + interactive: true + gate_message: | + Review the plan. Request changes, or say "approved" to implement (draft PR next). + + # ═══════════════════════════════════════════════════════════════ + # PHASE 4 — Plan execution pipeline (same as plan-to-pr) + # ═══════════════════════════════════════════════════════════════ + + - id: plan-setup + command: archon-plan-setup + depends_on: [refine-plan] + context: fresh + + - id: confirm-plan + command: archon-confirm-plan + depends_on: [plan-setup] + context: fresh + + - id: implement-tasks + command: archon-implement-tasks + depends_on: [confirm-plan] + context: fresh + model: claude-opus-4-6[1m] + + - id: validate + command: archon-validate + depends_on: [implement-tasks] + context: fresh + + # ═══════════════════════════════════════════════════════════════ + # PHASE 5 — Draft PR (not ready for review yet) + # ═══════════════════════════════════════════════════════════════ + + - id: create-draft-pr + prompt: | + Create a **draft** pull request for the current branch (Scout perf optimizations). + + 1. Ensure all changes are committed; push `git push -u origin HEAD`. + 2. Read `$ARTIFACTS_DIR/plan.md` and `$ARTIFACTS_DIR/routes-summary.md` for context. + 3. If a PR already exists: `gh pr list --head $(git branch --show-current)` — report URL and skip creation. + 4. Else use the repo PR template if present; fill every section. + 5. Create with: `gh pr create --draft --base $BASE_BRANCH` — title like `perf: Scout hot-route optimizations`. + 6. Save `gh pr view --json number,url` to `$ARTIFACTS_DIR/.pr-url` if helpful. + + Summarize PR URL and draft status. + depends_on: [validate] + context: fresh + + # ═══════════════════════════════════════════════════════════════ + # PHASE 6 — Code review (same pattern as archon-fix-github-issue) + # ═══════════════════════════════════════════════════════════════ + + - id: review-scope + command: archon-pr-review-scope + depends_on: [create-draft-pr] + context: fresh + + - id: review-classify + prompt: | + You are a PR review classifier for a Scout performance PR. + + ## PR scope + $review-scope.output + + Rules: + - **Code review**: ALWAYS run (`true`). + - **Error handling**: run if diff touches try/catch, async error paths, or new failure modes. + - **Test coverage**: run if diff touches non-test source. + - **Comment quality**: run if diff changes comments/docstrings meaningfully. + - **Docs impact**: run if public APIs, env vars, or user-facing behavior docs change. + + Provide brief reasoning. + depends_on: [review-scope] + model: haiku + allowed_tools: [] + context: fresh + output_format: + type: object + properties: + run_code_review: + type: string + enum: ["true", "false"] + run_error_handling: + type: string + enum: ["true", "false"] + run_test_coverage: + type: string + enum: ["true", "false"] + run_comment_quality: + type: string + enum: ["true", "false"] + run_docs_impact: + type: string + enum: ["true", "false"] + reasoning: + type: string + required: + - run_code_review + - run_error_handling + - run_test_coverage + - run_comment_quality + - run_docs_impact + - reasoning + + - id: code-review + command: archon-code-review-agent + depends_on: [review-classify] + context: fresh + + - id: error-handling + command: archon-error-handling-agent + depends_on: [review-classify] + when: "$review-classify.output.run_error_handling == 'true'" + context: fresh + + - id: test-coverage + command: archon-test-coverage-agent + depends_on: [review-classify] + when: "$review-classify.output.run_test_coverage == 'true'" + context: fresh + + - id: comment-quality + command: archon-comment-quality-agent + depends_on: [review-classify] + when: "$review-classify.output.run_comment_quality == 'true'" + context: fresh + + - id: docs-impact + command: archon-docs-impact-agent + depends_on: [review-classify] + when: "$review-classify.output.run_docs_impact == 'true'" + context: fresh + + - id: synthesize + command: archon-synthesize-review + depends_on: [code-review, error-handling, test-coverage, comment-quality, docs-impact] + trigger_rule: one_success + context: fresh + + - id: self-fix + command: archon-self-fix-all + depends_on: [synthesize] + context: fresh + + - id: simplify + command: archon-simplify-changes + depends_on: [self-fix] + context: fresh + + # ═══════════════════════════════════════════════════════════════ + # PHASE 7 — Mark PR ready (review concerns addressed) + # ═══════════════════════════════════════════════════════════════ + + - id: mark-pr-ready + prompt: | + Scout perf workflow — finalize the PR. + + 1. Run validation: `bun run validate` or the repo's full check from CLAUDE.md. + 2. Push any fixes: `git push origin HEAD`. + 3. **Mark the PR ready for review** (exit draft): `gh pr ready` (or `gh pr ready ` if needed). + 4. Post a short comment on the PR summarizing: Scout routes targeted, key changes, validation status. + + If `gh pr ready` is not appropriate (already ready, or permission), report current PR state from `gh pr view`. + + Output: + - PR URL + - Draft vs open (ready) state + - Next steps for the human (optional) + depends_on: [simplify] + context: fresh diff --git a/.claude/skills/archon/guides/setup.md b/.claude/skills/archon/guides/setup.md index c12ba1649d..30c651d70c 100644 --- a/.claude/skills/archon/guides/setup.md +++ b/.claude/skills/archon/guides/setup.md @@ -119,8 +119,6 @@ If Bun was just installed in Prerequisites (macOS/Linux), use `~/.bun/bin/bun` i 3. Verify: `archon version` 4. Check Claude is installed: `which claude`, then `claude /login` if needed -> **Note — Claude Code binary path.** Archon does not bundle Claude Code. In compiled Archon binaries (quick install, Homebrew), the Claude Code SDK needs `CLAUDE_BIN_PATH` set to the absolute path of its `cli.js`. The `archon setup` wizard in Step 4 auto-detects this via `npm root -g` and writes it to `~/.archon/.env` — no manual action needed in the typical case. Source installs (`bun run`) don't need this; the SDK finds `cli.js` via `node_modules` automatically. - ## Step 4: Configure Credentials The CLI loads infrastructure config (database, tokens) from `~/.archon/.env` only. This prevents conflicts with project `.env` files that may contain different database URLs. @@ -160,7 +158,7 @@ Both paths are normal — the manual path is not an error. Wait for the user to confirm they've completed the setup wizard before proceeding. -### 4c: Verify Configuration +### 5c: Verify Configuration After the user confirms setup is complete: @@ -172,7 +170,7 @@ Should show: - `Database: sqlite` (default, zero setup) or `Database: postgresql` (if DATABASE_URL was configured) - No errors about missing configuration -### 4d: Run Database Migrations (PostgreSQL only) +### 5d: Run Database Migrations (PostgreSQL only) **SQLite users: skip this step.** SQLite is auto-initialized on first run with zero setup. diff --git a/.cursor/hooks/state/continual-learning-index.json b/.cursor/hooks/state/continual-learning-index.json new file mode 100644 index 0000000000..9d9eb2e7f6 --- /dev/null +++ b/.cursor/hooks/state/continual-learning-index.json @@ -0,0 +1,11 @@ +{ + "280d685f-a48a-46c6-833f-323dd405d054/280d685f-a48a-46c6-833f-323dd405d054.jsonl": { + "mtime": 1776270712 + }, + "d2ae91bc-63ac-4028-88d4-97ce68f614a8/d2ae91bc-63ac-4028-88d4-97ce68f614a8.jsonl": { + "mtime": 1776268070 + }, + "caf60f72-6726-464d-a2cf-d3e482e5d1a9/caf60f72-6726-464d-a2cf-d3e482e5d1a9.jsonl": { + "mtime": 1776259093 + } +} diff --git a/.cursor/hooks/state/continual-learning.json b/.cursor/hooks/state/continual-learning.json new file mode 100644 index 0000000000..5a75f06918 --- /dev/null +++ b/.cursor/hooks/state/continual-learning.json @@ -0,0 +1,8 @@ +{ + "version": 1, + "lastRunAtMs": 1776270702201, + "turnsSinceLastRun": 0, + "lastTranscriptMtimeMs": 1776270702140.7751, + "lastProcessedGenerationId": "10c60213-c8e3-462b-a77e-202f0bb589a2", + "trialStartedAtMs": null +} diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 0000000000..641de8700b --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "scout-apm": { + "command": "docker", + "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local:latest"], + "env": { + "SCOUT_API_KEY": "${env:SCOUT_API_KEY}" + }, + "envFile": "${workspaceFolder}/.env" + } + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..4277831adb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,6 @@ +## Learned User Preferences + +## Learned Workspace Facts + +- Run `bun install` from the repo root before `bun run dev` or per-package dev scripts; without a linked root `node_modules`, workspace packages are not resolved and common failures include missing `vite`/`astro` and failed `@archon/paths` subpath imports (for example `@archon/paths/strip-cwd-env-boot` from `@archon/server`). +- In the Web UI, Settings → Platform Connections hardcodes Slack, Telegram, Discord, and GitHub as not connected; only Web reflects live adapter state, so a working Slack bot can still show as not configured there until the UI is wired to real platform status.