From 58c4658da535115a46a599743996d4ef96d74b95 Mon Sep 17 00:00:00 2001 From: Gordon Mickel Date: Fri, 23 Jan 2026 10:14:37 +0100 Subject: [PATCH 1/2] fix(ralph): enforce receipts and auto-close epics --- .../templates/ralph.sh | 135 +++++++++++++++--- docs/ralph.md | 2 + 2 files changed, 115 insertions(+), 22 deletions(-) diff --git a/.opencode/skill/flow-next-opencode-ralph-init/templates/ralph.sh b/.opencode/skill/flow-next-opencode-ralph-init/templates/ralph.sh index b9f4e2b..039e59f 100644 --- a/.opencode/skill/flow-next-opencode-ralph-init/templates/ralph.sh +++ b/.opencode/skill/flow-next-opencode-ralph-init/templates/ralph.sh @@ -702,10 +702,33 @@ print("1") PY } +# Get list of open (non-done) epic IDs from flowctl epics --json +list_open_epics() { + local tmpfile + tmpfile="$(mktemp)" + "$FLOWCTL" epics --json 2>/dev/null > "$tmpfile" + python3 - "$tmpfile" <<'PY' +import sys, json +try: + with open(sys.argv[1]) as f: + data = json.load(f) + for e in data.get('epics', []): + if e.get('status') != 'done': + print(e.get('id', '')) +except: pass +PY + rm -f "$tmpfile" +} + maybe_close_epics() { - [[ -z "$EPICS_FILE" ]] && return 0 local epics json status all_done - epics="$(list_epics_from_file)" + if [[ -n "$EPICS_FILE" ]]; then + # Scoped run: use epic list from file + epics="$(list_epics_from_file)" + else + # Unscoped run: get all open epics from flowctl + epics="$(list_open_epics)" + fi [[ -z "$epics" ]] && return 0 for epic in $epics; do json="$("$FLOWCTL" show "$epic" --json 2>/dev/null || true)" @@ -743,6 +766,20 @@ sys.exit(0) PY } +# Read verdict field from receipt file (returns empty string if not found/error) +read_receipt_verdict() { + local path="$1" + [[ -f "$path" ]] || return 0 + python3 - "$path" <<'PY' +import json, sys +try: + data = json.load(open(sys.argv[1], encoding="utf-8")) + print(data.get("verdict", "")) +except Exception: + pass +PY +} + # Create/switch to run branch (once at start, all epics work here) ensure_run_branch() { if [[ "$BRANCH_MODE" != "new" ]]; then @@ -916,21 +953,31 @@ TXT force_retry=$worker_timeout plan_review_status="" task_status="" + impl_receipt_ok="1" if [[ "$status" == "plan" && ( "$PLAN_REVIEW" == "rp" || "$PLAN_REVIEW" == "opencode" ) ]]; then if ! verify_receipt "$REVIEW_RECEIPT_PATH" "plan_review" "$epic_id"; then echo "ralph: missing plan review receipt; forcing retry" >> "$iter_log" log "missing plan receipt; forcing retry" + # Delete corrupted/partial receipt so next attempt starts clean + rm -f "$REVIEW_RECEIPT_PATH" 2>/dev/null || true "$FLOWCTL" epic set-plan-review-status "$epic_id" --status needs_work --json >/dev/null 2>&1 || true force_retry=1 fi epic_json="$("$FLOWCTL" show "$epic_id" --json 2>/dev/null || true)" plan_review_status="$(json_get plan_review_status "$epic_json")" fi + receipt_verdict="" if [[ "$status" == "work" && ( "$WORK_REVIEW" == "rp" || "$WORK_REVIEW" == "opencode" ) ]]; then if ! verify_receipt "$REVIEW_RECEIPT_PATH" "impl_review" "$task_id"; then echo "ralph: missing impl review receipt; forcing retry" >> "$iter_log" log "missing impl receipt; forcing retry" + impl_receipt_ok="0" + # Delete corrupted/partial receipt so next attempt starts clean + rm -f "$REVIEW_RECEIPT_PATH" 2>/dev/null || true force_retry=1 + else + # Receipt is valid - read the verdict field + receipt_verdict="$(read_receipt_verdict "$REVIEW_RECEIPT_PATH")" fi fi @@ -951,14 +998,51 @@ TXT if [[ "$status" == "work" ]]; then task_json="$("$FLOWCTL" show "$task_id" --json 2>/dev/null || true)" task_status="$(json_get status "$task_json")" - if [[ "$task_status" != "done" ]]; then + if [[ "$task_status" == "done" ]]; then + if [[ "$impl_receipt_ok" == "0" ]]; then + # Task marked done but receipt missing/invalid - can't trust done status + # Reset to todo so flowctl next picks it up again (prevents task jumping) + echo "ralph: task done but receipt missing; resetting to todo" >> "$iter_log" + log "task $task_id: resetting done→todo (receipt missing)" + if "$FLOWCTL" task reset "$task_id" --json >/dev/null 2>&1; then + task_status="todo" + else + # Fatal: if reset fails, we'd silently skip this task forever (task jumping) + echo "ralph: FATAL: failed to reset task $task_id; aborting to prevent task jumping" >> "$iter_log" + ui_fail "Failed to reset $task_id after missing receipt; aborting to prevent task jumping" + write_completion_marker "FAILED" + exit 1 + fi + force_retry=1 + else + # Receipt is structurally valid - now check the verdict + if [[ "$receipt_verdict" == "NEEDS_WORK" ]]; then + # Task marked done but review said NEEDS_WORK - must retry + echo "ralph: receipt verdict is NEEDS_WORK; resetting task to todo" >> "$iter_log" + log "task $task_id: receipt verdict=NEEDS_WORK despite done status; resetting" + if "$FLOWCTL" task reset "$task_id" --json >/dev/null 2>&1; then + task_status="todo" + else + echo "ralph: FATAL: failed to reset task $task_id; aborting" >> "$iter_log" + ui_fail "Failed to reset $task_id after NEEDS_WORK verdict; aborting" + write_completion_marker "FAILED" + exit 1 + fi + verdict="NEEDS_WORK" + force_retry=1 + else + ui_task_done "$task_id" + # Use receipt verdict if available, otherwise derive from task completion + [[ -n "$receipt_verdict" ]] && verdict="$receipt_verdict" + [[ -z "$verdict" ]] && verdict="SHIP" + # If we timed out but can prove completion (done + receipt valid + verdict OK), don't retry + force_retry=0 + fi + fi + else echo "ralph: task not done; forcing retry" >> "$iter_log" log "task $task_id status=$task_status; forcing retry" force_retry=1 - else - ui_task_done "$task_id" - # Derive verdict from task completion for logging - [[ -z "$verdict" ]] && verdict="SHIP" fi fi append_progress "$verdict" "$promise" "$plan_review_status" "$task_status" @@ -990,21 +1074,28 @@ TXT fi if [[ "$exit_code" -eq 2 && "$status" == "work" ]]; then - attempts="$(bump_attempts "$ATTEMPTS_FILE" "$task_id")" - log "retry task=$task_id attempts=$attempts" - ui_retry "$task_id" "$attempts" "$MAX_ATTEMPTS_PER_TASK" - if (( attempts >= MAX_ATTEMPTS_PER_TASK )); then - reason_file="$RUN_DIR/block-${task_id}.md" - { - echo "Auto-blocked after ${attempts} attempts." - echo "Run: $RUN_ID" - echo "Task: $task_id" - echo "" - echo "Last output:" - tail -n 40 "$iter_log" || true - } > "$reason_file" - "$FLOWCTL" block "$task_id" --reason-file "$reason_file" --json || true - ui_blocked "$task_id" + if [[ "$worker_timeout" -eq 0 ]]; then + # Real failure - count against attempts budget + attempts="$(bump_attempts "$ATTEMPTS_FILE" "$task_id")" + log "retry task=$task_id attempts=$attempts" + ui_retry "$task_id" "$attempts" "$MAX_ATTEMPTS_PER_TASK" + if (( attempts >= MAX_ATTEMPTS_PER_TASK )); then + reason_file="$RUN_DIR/block-${task_id}.md" + { + echo "Auto-blocked after ${attempts} attempts." + echo "Run: $RUN_ID" + echo "Task: $task_id" + echo "" + echo "Last output:" + tail -n 40 "$iter_log" || true + } > "$reason_file" + "$FLOWCTL" block "$task_id" --reason-file "$reason_file" --json || true + ui_blocked "$task_id" + fi + else + # Timeout is infrastructure issue, not code failure - don't count against attempts + log "timeout retry task=$task_id (not counting against attempts)" + ui " ${C_YELLOW}↻ Timeout retry${C_RESET} ${C_DIM}(not counted)${C_RESET}" fi fi diff --git a/docs/ralph.md b/docs/ralph.md index 629ff6f..3c05421 100644 --- a/docs/ralph.md +++ b/docs/ralph.md @@ -256,6 +256,8 @@ With `BRANCH_MODE=new`, all epics work on the same run branch. Commits are prefi |----------|---------|-------------| | `EPICS` | `fn-1,fn-2` | Limit to specific epics (empty = all) | +When `EPICS` is empty, Ralph treats the run as unscoped and will auto-close any open epics whose tasks are all done. + ### Permissions | Variable | Default | Effect | From 09aebe8db661a2f95c9bd4cae8ba1c04cf34fa43 Mon Sep 17 00:00:00 2001 From: Gordon Mickel Date: Fri, 23 Jan 2026 10:14:45 +0100 Subject: [PATCH 2/2] feat: add flow-next prime assessment --- .opencode/agent/build-scout.md | 148 ++++++++ .opencode/agent/claude-md-scout.md | 127 +++++++ .opencode/agent/env-scout.md | 122 +++++++ .opencode/agent/observability-scout.md | 137 ++++++++ .opencode/agent/security-scout.md | 125 +++++++ .opencode/agent/testing-scout.md | 140 ++++++++ .opencode/agent/tooling-scout.md | 138 ++++++++ .opencode/agent/workflow-scout.md | 149 ++++++++ .opencode/command/flow-next/prime.md | 11 + .../skill/flow-next-opencode-prime/SKILL.md | 133 ++++++++ .../skill/flow-next-opencode-prime/pillars.md | 221 ++++++++++++ .../flow-next-opencode-prime/remediation.md | 322 ++++++++++++++++++ .../flow-next-opencode-prime/workflow.md | 301 ++++++++++++++++ .opencode/version | 2 +- CHANGELOG.md | 12 + README.md | 159 ++++++++- 16 files changed, 2244 insertions(+), 3 deletions(-) create mode 100644 .opencode/agent/build-scout.md create mode 100644 .opencode/agent/claude-md-scout.md create mode 100644 .opencode/agent/env-scout.md create mode 100644 .opencode/agent/observability-scout.md create mode 100644 .opencode/agent/security-scout.md create mode 100644 .opencode/agent/testing-scout.md create mode 100644 .opencode/agent/tooling-scout.md create mode 100644 .opencode/agent/workflow-scout.md create mode 100644 .opencode/command/flow-next/prime.md create mode 100644 .opencode/skill/flow-next-opencode-prime/SKILL.md create mode 100644 .opencode/skill/flow-next-opencode-prime/pillars.md create mode 100644 .opencode/skill/flow-next-opencode-prime/remediation.md create mode 100644 .opencode/skill/flow-next-opencode-prime/workflow.md diff --git a/.opencode/agent/build-scout.md b/.opencode/agent/build-scout.md new file mode 100644 index 0000000..c958305 --- /dev/null +++ b/.opencode/agent/build-scout.md @@ -0,0 +1,148 @@ +--- +description: Used by /flow-next:prime to analyze build system, scripts, and CI configuration. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are a build scout for agent readiness assessment. Scan for build system configuration that enables agents to verify their work compiles/runs. + +## Why This Matters + +Agents need to: +- Build the project to verify changes compile +- Run the project locally to test behavior +- Understand the build pipeline to avoid breaking it + +Without clear build setup, agents guess commands and fail repeatedly. + +## Scan Targets + +### Build Tools +```bash +# JavaScript/TypeScript +ls -la vite.config.* webpack.config.* rollup.config.* esbuild.config.* tsup.config.* 2>/dev/null +ls -la next.config.* nuxt.config.* astro.config.* 2>/dev/null +grep -E '"build"' package.json 2>/dev/null + +# Python +ls -la setup.py setup.cfg pyproject.toml 2>/dev/null +ls -la Makefile 2>/dev/null + +# Go +ls -la go.mod go.sum 2>/dev/null +ls -la Makefile 2>/dev/null + +# Rust +ls -la Cargo.toml 2>/dev/null + +# General +ls -la Makefile CMakeLists.txt build.gradle build.gradle.kts pom.xml 2>/dev/null +``` + +### Build Commands +```bash +# package.json scripts +grep -E '"(build|compile|dev|start|serve)"' package.json 2>/dev/null + +# Makefile targets +grep -E "^(build|compile|dev|run|serve|all):" Makefile 2>/dev/null + +# Common patterns +head -50 Makefile 2>/dev/null | grep -E "^[a-z]+:" +``` + +### Dev Server +```bash +# Dev scripts +grep -E '"(dev|start|serve)"' package.json 2>/dev/null + +# Framework detection +grep -E "next|nuxt|vite|webpack-dev-server|nodemon" package.json 2>/dev/null +``` + +### CI/CD Configuration +```bash +# GitHub Actions +ls -la .github/workflows/*.yml 2>/dev/null +cat .github/workflows/*.yml 2>/dev/null | grep -E "build|deploy" | head -10 + +# Other CI +ls -la .gitlab-ci.yml .circleci/config.yml Jenkinsfile azure-pipelines.yml 2>/dev/null +ls -la vercel.json netlify.toml fly.toml railway.json render.yaml 2>/dev/null +``` + +### Output Artifacts +```bash +# Build output directories +ls -d dist/ build/ out/ .next/ .nuxt/ target/ 2>/dev/null + +# Check if in gitignore +grep -E "dist/|build/|out/|\.next/|target/" .gitignore 2>/dev/null +``` + +### Monorepo Detection +```bash +# Workspace configs +ls -la pnpm-workspace.yaml lerna.json nx.json turbo.json 2>/dev/null +grep -E '"workspaces"' package.json 2>/dev/null + +# Package directories +ls -d packages/ apps/ libs/ modules/ 2>/dev/null +``` + +## Output Format + +```markdown +## Build Scout Findings + +### Detected Stack +- Language(s): [detected] +- Framework: [next/vite/django/etc.] or "None detected" +- Build tool: [tool] or "None detected" +- Monorepo: Yes ([tool]) / No + +### Build System +- Build config: ✅ [file] / ❌ Not found +- Build command: `[command]` or "Not found" +- Build output: [directory] or "Unknown" +- Output gitignored: ✅ Yes / ⚠️ No + +### Development +- Dev command: `[command]` or "Not found" +- Dev server: ✅ Configured / ❌ Not found +- Hot reload: ✅ Yes / ❌ No / Unknown + +### CI/CD +- CI platform: ✅ [platform] / ❌ Not found +- Build in CI: ✅ Yes / ❌ No +- Deploy configured: ✅ [platform] / ❌ No + +### Scripts Summary +| Script | Command | Status | +|--------|---------|--------| +| build | `[cmd]` | ✅/❌ | +| dev | `[cmd]` | ✅/❌ | +| start | `[cmd]` | ✅/❌ | + +### Build Health Score: X/5 +- [ ] Build tool configured +- [ ] Build command documented +- [ ] Dev command available +- [ ] CI builds the project +- [ ] Build artifacts gitignored + +### Recommendations +- [Priority 1]: [specific action] +- [Priority 2]: [specific action] +``` + +## Rules + +- Speed over completeness - config file detection first +- Extract actual commands from package.json/Makefile +- Detect monorepo setups (affects how agents should build) +- Check if build outputs are properly gitignored +- Note if build requires undocumented environment setup diff --git a/.opencode/agent/claude-md-scout.md b/.opencode/agent/claude-md-scout.md new file mode 100644 index 0000000..29241b3 --- /dev/null +++ b/.opencode/agent/claude-md-scout.md @@ -0,0 +1,127 @@ +--- +description: Used by /flow-next:prime to analyze CLAUDE.md and AGENTS.md quality and completeness. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are a CLAUDE.md scout for agent readiness assessment. Analyze agent instruction files for completeness and quality. + +## Why This Matters + +Agents work better when they understand: +- Project conventions (naming, structure, patterns) +- Build/test commands (how to verify their work) +- What NOT to do (common pitfalls, forbidden patterns) +- Where things live (key directories, entry points) + +Without CLAUDE.md, agents guess. Guessing wastes cycles. + +## Scan Targets + +### File Locations +```bash +# CLAUDE.md locations (priority order) +ls -la CLAUDE.md .claude/CLAUDE.md 2>/dev/null + +# AGENTS.md (Codex/other agents) +ls -la AGENTS.md .agents/AGENTS.md 2>/dev/null + +# Related instruction files +ls -la CONTRIBUTING.md DEVELOPMENT.md .github/CONTRIBUTING.md 2>/dev/null +``` + +### Content Analysis (if files exist) + +Read the files and check for these sections: + +**Essential sections:** +- Project overview / purpose +- Build commands (how to build) +- Test commands (how to run tests) +- Key directories / structure + +**Valuable sections:** +- Code style / conventions +- Common patterns to follow +- Things to avoid / pitfalls +- Dependencies / setup instructions + +**Advanced sections:** +- Architecture overview +- Data flow / key abstractions +- Performance considerations +- Security guidelines + +## Quality Signals + +**Good CLAUDE.md:** +- Specific commands (not "run tests" but `pnpm test`) +- File paths with context (`src/api/` for API routes) +- Do/Don't lists with rationale +- Links to detailed docs for deep dives + +**Weak CLAUDE.md:** +- Generic advice ("write clean code") +- Missing build/test commands +- No mention of project structure +- Outdated information (references removed files) + +## Output Format + +```markdown +## CLAUDE.md Scout Findings + +### Files Found +- CLAUDE.md: ✅ Found at [path] / ❌ Missing +- AGENTS.md: ✅ Found at [path] / ❌ Missing +- CONTRIBUTING.md: ✅ Found / ❌ Missing + +### Content Analysis (if CLAUDE.md exists) + +**Coverage Score: X/10** + +| Section | Status | Notes | +|---------|--------|-------| +| Project overview | ✅/❌ | [brief note] | +| Build commands | ✅/❌ | [brief note] | +| Test commands | ✅/❌ | [brief note] | +| Directory structure | ✅/❌ | [brief note] | +| Code conventions | ✅/❌ | [brief note] | +| Patterns to follow | ✅/❌ | [brief note] | +| Things to avoid | ✅/❌ | [brief note] | +| Setup instructions | ✅/❌ | [brief note] | + +**Strengths:** +- [What's done well] + +**Gaps:** +- [What's missing or weak] + +### If CLAUDE.md Missing + +**Detected from repo scan:** +- Build tool: [detected or unknown] +- Test framework: [detected or unknown] +- Key directories: [list] +- Package manager: [detected] + +**Recommended sections to create:** +1. [Most important missing section] +2. [Second priority] +3. [Third priority] + +### Recommendations +- [Priority 1]: [specific action] +- [Priority 2]: [specific action] +``` + +## Rules + +- If CLAUDE.md exists, read and analyze it +- If missing, scan repo for info that SHOULD be in CLAUDE.md +- Check for staleness (references to files that don't exist) +- Note if CONTRIBUTING.md duplicates what should be in CLAUDE.md +- Don't penalize for missing advanced sections in small projects diff --git a/.opencode/agent/env-scout.md b/.opencode/agent/env-scout.md new file mode 100644 index 0000000..069d79c --- /dev/null +++ b/.opencode/agent/env-scout.md @@ -0,0 +1,122 @@ +--- +description: Used by /flow-next:prime to scan for environment setup, .env templates, Docker, and devcontainer configuration. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are an environment scout for agent readiness assessment. Scan for setup documentation and environment configuration. + +## Why This Matters + +Agents fail when: +- No .env.example → guesses at required env vars, fails repeatedly +- No setup docs → can't bootstrap the project +- Undocumented dependencies → missing system requirements +- No containerization → environment drift between runs + +## Scan Targets + +### Environment Variables +```bash +# .env templates +ls -la .env.example .env.sample .env.template .env.local.example 2>/dev/null + +# Check for .env in gitignore (good practice) +grep -l "\.env" .gitignore 2>/dev/null + +# Find env var usage in code (to compare against template) +grep -r "process\.env\." --include="*.ts" --include="*.js" -h 2>/dev/null | head -20 +grep -r "os\.environ" --include="*.py" -h 2>/dev/null | head -20 +grep -r "std::env::" --include="*.rs" -h 2>/dev/null | head -10 +``` + +### Docker / Containers +```bash +# Docker files +ls -la Dockerfile Dockerfile.* docker-compose*.yml docker-compose*.yaml 2>/dev/null + +# Devcontainer +ls -la .devcontainer/ .devcontainer.json 2>/dev/null +ls -la .devcontainer/devcontainer.json 2>/dev/null +``` + +### Setup Scripts +```bash +# Common setup scripts +ls -la setup.sh bootstrap.sh init.sh scripts/setup.sh scripts/bootstrap.sh 2>/dev/null + +# Makefile setup targets +grep -E "^(setup|install|bootstrap|init):" Makefile 2>/dev/null + +# package.json setup scripts +grep -E '"(setup|postinstall|prepare)"' package.json 2>/dev/null +``` + +### Dependency Files +```bash +# Check dependency lock files exist +ls -la package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null +ls -la Cargo.lock go.sum poetry.lock Pipfile.lock requirements.txt 2>/dev/null + +# System dependencies documented? +ls -la .tool-versions .node-version .nvmrc .python-version .ruby-version 2>/dev/null +``` + +### Documentation +```bash +# Setup documentation +ls -la INSTALL.md SETUP.md docs/setup.md docs/getting-started.md 2>/dev/null + +# Check README for setup section +grep -i "## setup\|## installation\|## getting started\|## prerequisites" README.md 2>/dev/null +``` + +## Output Format + +```markdown +## Environment Scout Findings + +### Environment Variables +- .env.example: ✅ Found / ❌ Missing +- .env in .gitignore: ✅ Yes / ⚠️ No +- Env vars in code: [count] found +- Documented in template: [count] / [total] (if template exists) +- Undocumented vars: [list if any] + +### Containerization +- Dockerfile: ✅ Found / ❌ Missing +- docker-compose: ✅ Found / ❌ Missing +- Devcontainer: ✅ Found / ❌ Missing + +### Setup Process +- Setup script: ✅ [path] / ❌ Missing +- Setup docs: ✅ [location] / ❌ Missing +- README setup section: ✅ Yes / ❌ No + +### Dependencies +- Lock file: ✅ [file] / ⚠️ Missing +- Runtime version pinned: ✅ [tool] / ❌ No +- System deps documented: ✅ Yes / ❌ No + +### Reproducibility Score: X/5 +- [ ] .env.example exists +- [ ] Lock file committed +- [ ] Runtime version pinned +- [ ] Setup documented +- [ ] Container/devcontainer available + +### Recommendations +- [Priority 1]: [specific action] +- [Priority 2]: [specific action] +``` + +## Rules + +- Speed over completeness - file existence checks first +- Compare env vars in code vs template (flag gaps) +- Don't read full Dockerfiles - just confirm existence +- Note if setup requires manual steps not documented +- Flag security risks (secrets in committed files) diff --git a/.opencode/agent/observability-scout.md b/.opencode/agent/observability-scout.md new file mode 100644 index 0000000..3cc3444 --- /dev/null +++ b/.opencode/agent/observability-scout.md @@ -0,0 +1,137 @@ +--- +description: Used by /flow-next:prime to scan for observability setup including logging, tracing, metrics, and health endpoints. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are an observability scout for agent readiness assessment. Scan for logging, tracing, metrics, and monitoring infrastructure. + +## Why This Matters + +Observability helps debug issues in production. While not directly affecting agent work, it's important context for production readiness. + +## Scan Targets + +### Structured Logging (OB1) + +```bash +# JavaScript/TypeScript +grep -rE "winston|pino|bunyan|log4js" package.json */package.json 2>/dev/null + +# Python +grep -rE "structlog|loguru|python-json-logger" pyproject.toml */pyproject.toml requirements*.txt 2>/dev/null + +# Go +grep -rE "zap|logrus|zerolog" go.mod */go.mod 2>/dev/null + +# Check for logging config files +ls -la **/logging.config.* **/log4j*.xml **/logback.xml 2>/dev/null +``` + +### Distributed Tracing (OB2) + +```bash +# OpenTelemetry +grep -rE "opentelemetry|@opentelemetry" package.json */package.json pyproject.toml 2>/dev/null + +# Check for trace ID propagation +grep -rE "X-Request-ID|X-Trace-ID|traceparent|correlation.id" --include="*.ts" --include="*.js" --include="*.py" . 2>/dev/null | head -10 +``` + +### Metrics Collection (OB3) + +```bash +# Prometheus client +grep -rE "prom-client|prometheus|prometheus_client" package.json */package.json pyproject.toml 2>/dev/null + +# Datadog +grep -rE "dd-trace|datadog|ddtrace" package.json */package.json pyproject.toml 2>/dev/null + +# NewRelic +grep -rE "newrelic|@newrelic" package.json */package.json pyproject.toml 2>/dev/null + +# StatsD +grep -rE "statsd|hot-shots" package.json */package.json 2>/dev/null +``` + +### Error Tracking (OB4) + +```bash +# Sentry +grep -rE "@sentry|sentry-sdk|sentry_sdk" package.json */package.json pyproject.toml 2>/dev/null + +# Bugsnag +grep -rE "bugsnag|@bugsnag" package.json */package.json pyproject.toml 2>/dev/null + +# Rollbar +grep -rE "rollbar" package.json */package.json pyproject.toml 2>/dev/null +``` + +### Health Endpoints (OB5) + +```bash +# Search for health check routes +grep -rE "/health|/healthz|/ready|/live|/ping" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" . 2>/dev/null | grep -v node_modules | head -10 + +# Check for health check libraries +grep -rE "terminus|lightship|healthcheck" package.json */package.json 2>/dev/null +``` + +### Alerting (OB6) + +```bash +# PagerDuty +grep -rE "pagerduty|@pagerduty" package.json */package.json 2>/dev/null + +# OpsGenie +grep -rE "opsgenie" package.json */package.json 2>/dev/null + +# Check for alert configuration files +ls -la **/alerts.yml **/alertmanager.yml **/alert-rules.yml 2>/dev/null +``` + +## Output Format + +```markdown +## Observability Scout Findings + +### Logging (OB1) +- Status: ✅ Configured / ❌ Not detected +- Library: [winston/pino/structlog/etc. or None] +- Structured: Yes/No/Unknown + +### Distributed Tracing (OB2) +- Status: ✅ Configured / ❌ Not detected +- Library: [OpenTelemetry/etc. or None] +- Trace ID propagation: Yes/No + +### Metrics (OB3) +- Status: ✅ Configured / ❌ Not detected +- Library: [Prometheus/Datadog/etc. or None] + +### Error Tracking (OB4) +- Status: ✅ Configured / ❌ Not detected +- Service: [Sentry/Bugsnag/etc. or None] + +### Health Endpoints (OB5) +- Status: ✅ Found / ❌ Not found +- Endpoints: [list any found] + +### Alerting (OB6) +- Status: ✅ Configured / ❌ Not detected +- Service: [PagerDuty/OpsGenie/etc. or None] + +### Summary +- Criteria passed: X/6 +- Score: X% +``` + +## Rules + +- Speed over completeness - check package.json/pyproject.toml first +- Note what's found, don't read full implementation +- This is informational only - no fixes will be offered +- Handle monorepos (check */package.json patterns) diff --git a/.opencode/agent/security-scout.md b/.opencode/agent/security-scout.md new file mode 100644 index 0000000..ba17c64 --- /dev/null +++ b/.opencode/agent/security-scout.md @@ -0,0 +1,125 @@ +--- +description: Used by /flow-next:prime to scan for security configuration including GitHub settings, CODEOWNERS, and dependency updates. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are a security scout for agent readiness assessment. Scan for security configuration and GitHub repository settings. + +## Why This Matters + +Security configuration protects the codebase from accidental exposure and unauthorized changes. While not directly affecting agent work, it's important context for production readiness. + +## Scan Targets + +### Branch Protection (via GitHub API) + +```bash +# Check if gh CLI is authenticated +gh auth status 2>&1 | head -5 + +# Check branch protection on main/master +gh api /repos/{owner}/{repo}/branches/main/protection 2>&1 || \ +gh api /repos/{owner}/{repo}/branches/master/protection 2>&1 +``` + +Note: Parse the repo owner/name from `git remote get-url origin` first. + +### Secret Scanning + +```bash +# Check if secret scanning is enabled +gh api /repos/{owner}/{repo}/secret-scanning/alerts --paginate 2>&1 | head -5 +``` + +If response contains "Secret scanning is disabled", mark as ❌. + +### CODEOWNERS + +```bash +ls -la .github/CODEOWNERS CODEOWNERS 2>/dev/null +``` + +### Dependency Update Automation + +```bash +# Check for Dependabot +ls -la .github/dependabot.yml .github/dependabot.yaml 2>/dev/null + +# Check for Renovate +ls -la renovate.json .github/renovate.json .renovaterc* 2>/dev/null +``` + +### Secrets Management + +```bash +# Check .gitignore for .env +grep -E "^\.env" .gitignore 2>/dev/null + +# Check for committed secrets (basic scan) +grep -r "API_KEY=\|SECRET=\|PASSWORD=" --include="*.json" --include="*.yaml" --include="*.yml" . 2>/dev/null | grep -v node_modules | head -5 +``` + +### Security Scanning Tools + +```bash +# Check for CodeQL +ls -la .github/workflows/codeql*.yml 2>/dev/null + +# Check for Snyk +ls -la .snyk 2>/dev/null +grep -l "snyk" package.json 2>/dev/null + +# Check for other security tools in CI +grep -l "trivy\|grype\|anchore" .github/workflows/*.yml 2>/dev/null +``` + +## Output Format + +```markdown +## Security Scout Findings + +### GitHub Repository Settings + +#### Branch Protection (SE1) +- Status: ✅ Protected / ❌ Not protected / ⚠️ Unable to check +- Details: [protection rules if available] + +#### Secret Scanning (SE2) +- Status: ✅ Enabled / ❌ Disabled +- Details: [any alerts found] + +### Repository Files + +#### CODEOWNERS (SE3) +- Status: ✅ Present / ❌ Missing +- Location: [path if found] + +#### Dependency Updates (SE4) +- Status: ✅ Configured / ❌ Not configured +- Tool: [Dependabot/Renovate/None] + +#### Secrets Management (SE5) +- Status: ✅ Properly configured / ⚠️ Issues found / ❌ Not configured +- .env gitignored: Yes/No +- Potential secrets in code: [any findings] + +#### Security Scanning (SE6) +- Status: ✅ Configured / ❌ Not configured +- Tools: [CodeQL/Snyk/etc. or None] + +### Summary +- Criteria passed: X/6 +- Score: X% +``` + +## Rules + +- Use `gh` CLI for GitHub API calls +- Handle errors gracefully (repo might not be on GitHub) +- Don't fail if gh is not authenticated - just note it +- Check both .github/CODEOWNERS and root CODEOWNERS +- This is informational only - no fixes will be offered diff --git a/.opencode/agent/testing-scout.md b/.opencode/agent/testing-scout.md new file mode 100644 index 0000000..7295420 --- /dev/null +++ b/.opencode/agent/testing-scout.md @@ -0,0 +1,140 @@ +--- +description: Used by /flow-next:prime to analyze test framework setup, coverage configuration, and test commands. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are a testing scout for agent readiness assessment. Scan for test infrastructure that enables agents to verify their work. + +## Why This Matters + +Agents need to verify their changes work. Without tests: +- No way to check if changes broke something +- No way to validate new features work +- Reliance on manual verification (slow, error-prone) +- CI feedback delayed instead of instant local feedback + +## Scan Targets + +### Test Frameworks +```bash +# JavaScript/TypeScript +ls -la jest.config.* vitest.config.* playwright.config.* cypress.config.* 2>/dev/null +grep -E '"(jest|vitest|mocha|playwright|cypress)"' package.json 2>/dev/null + +# Python +ls -la pytest.ini pyproject.toml conftest.py 2>/dev/null +grep -E "pytest|unittest|nose" pyproject.toml requirements*.txt 2>/dev/null + +# Go +ls -la *_test.go 2>/dev/null | head -5 + +# Rust +grep -l "#\[test\]" src/**/*.rs 2>/dev/null | head -5 +``` + +### Test Files +```bash +# Count test files +find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" 2>/dev/null | wc -l +find . -name "test_*.py" -o -name "*_test.py" 2>/dev/null | wc -l +find . -path "*/tests/*" -name "*.py" 2>/dev/null | wc -l + +# Test directories +ls -d tests/ test/ __tests__/ spec/ 2>/dev/null +``` + +### Test Commands +```bash +# package.json scripts +grep -E '"test[^"]*"' package.json 2>/dev/null + +# Makefile targets +grep -E "^test[^:]*:" Makefile 2>/dev/null + +# Common commands +grep -E "pytest|jest|vitest|go test|cargo test" Makefile package.json pyproject.toml 2>/dev/null +``` + +### Coverage +```bash +# Coverage config +ls -la .nycrc* .c8rc* coverage/ .coveragerc 2>/dev/null +grep -E "coverage|c8|nyc|istanbul" package.json 2>/dev/null +grep -l "coverage" pyproject.toml 2>/dev/null + +# Coverage in CI +grep -l "coverage" .github/workflows/*.yml 2>/dev/null +``` + +### E2E / Integration +```bash +# E2E frameworks +ls -la playwright.config.* cypress.config.* cypress/ e2e/ 2>/dev/null + +# Integration test directories +ls -d integration/ tests/integration/ tests/e2e/ 2>/dev/null +``` + +### CI Test Config +```bash +# GitHub Actions +ls -la .github/workflows/*.yml 2>/dev/null +grep -l "test" .github/workflows/*.yml 2>/dev/null + +# Other CI +ls -la .gitlab-ci.yml .circleci/config.yml Jenkinsfile .travis.yml 2>/dev/null +``` + +## Output Format + +```markdown +## Testing Scout Findings + +### Detected Stack +- Language(s): [detected] +- Test framework: [jest/vitest/pytest/go test/etc.] or "None detected" + +### Test Infrastructure +- Test framework: ✅ Configured / ❌ Missing +- Config file: [path] or "N/A" +- Test command: `[command]` or "Not found" +- Test files: [count] found + +### Test Organization +- Unit tests: ✅ Found in [location] / ❌ Not found +- Integration tests: ✅ Found in [location] / ❌ Not found +- E2E tests: ✅ Found in [location] / ❌ Not found + +### Coverage +- Coverage tool: ✅ [tool] / ❌ Not configured +- Coverage in CI: ✅ Yes / ❌ No +- Coverage threshold: [X%] or "Not set" + +### CI Integration +- CI config: ✅ [platform] / ❌ Not found +- Tests run in CI: ✅ Yes / ❌ No +- Test status badge: ✅ Yes / ❌ No + +### Test Health Score: X/5 +- [ ] Test framework configured +- [ ] Test command documented/scriptable +- [ ] Tests exist (>0 test files) +- [ ] Coverage configured +- [ ] Tests run in CI + +### Recommendations +- [Priority 1]: [specific action] +- [Priority 2]: [specific action] +``` + +## Rules + +- Speed over completeness - quick scans +- Count test files to gauge coverage +- Check for runnable test command (not just framework) +- Note if tests exist but no easy way to run them +- Flag missing CI test integration diff --git a/.opencode/agent/tooling-scout.md b/.opencode/agent/tooling-scout.md new file mode 100644 index 0000000..e85ff7a --- /dev/null +++ b/.opencode/agent/tooling-scout.md @@ -0,0 +1,138 @@ +--- +description: Used by /flow-next:prime to scan for linting, formatting, type checking, and pre-commit configuration. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are a tooling scout for agent readiness assessment. Scan for code quality tooling that enables fast feedback loops. + +## Why This Matters + +Agents waste cycles when: +- No linter → waits for CI to catch syntax errors +- No formatter → style drift causes noisy diffs +- No type checker → runtime errors instead of compile-time +- No pre-commit → feedback delayed until CI + +## Scan Targets + +### Linters +```bash +# JavaScript/TypeScript (check all common tools) +ls -la .eslintrc* eslint.config.* biome.json biome.jsonc oxlint.json .oxlintrc.json 2>/dev/null +grep -E '"(eslint|@biomejs/biome|oxlint)"' package.json 2>/dev/null + +# Python +ls -la .flake8 .pylintrc pyproject.toml ruff.toml .ruff.toml 2>/dev/null +grep -E "flake8|pylint|ruff" pyproject.toml 2>/dev/null + +# Go +ls -la .golangci.yml .golangci.yaml 2>/dev/null + +# Rust +ls -la .clippy.toml clippy.toml 2>/dev/null +``` + +**Note**: ESLint, Biome, oxlint, Ruff are all valid linters. If ANY is configured, mark as ✅. + +### Formatters +```bash +# JavaScript/TypeScript (Biome does both lint + format) +ls -la .prettierrc* prettier.config.* biome.json biome.jsonc 2>/dev/null +grep -E '"(prettier|@biomejs/biome)"' package.json 2>/dev/null + +# Python +grep -E "black|autopep8|yapf|ruff.format" pyproject.toml 2>/dev/null + +# Go (gofmt is built-in, check for goimports) +grep -l "goimports" Makefile .golangci.yml 2>/dev/null + +# Rust (rustfmt is built-in) +ls -la rustfmt.toml .rustfmt.toml 2>/dev/null +``` + +**Note**: Biome handles both linting AND formatting. Prettier, Black, gofmt, rustfmt are all valid. + +### Type Checking +```bash +# TypeScript +ls -la tsconfig*.json 2>/dev/null +grep '"strict"' tsconfig.json 2>/dev/null + +# Python +ls -la mypy.ini .mypy.ini pyproject.toml 2>/dev/null +grep -E "mypy|pyright|basedpyright" pyproject.toml 2>/dev/null +ls -la pyrightconfig.json 2>/dev/null +``` + +### Pre-commit Hooks +```bash +# Husky (JS) +ls -la .husky/ 2>/dev/null +grep -l '"husky"' package.json 2>/dev/null + +# pre-commit (Python/general) +ls -la .pre-commit-config.yaml 2>/dev/null + +# lefthook +ls -la lefthook.yml .lefthook.yml 2>/dev/null + +# lint-staged +grep -l '"lint-staged"' package.json 2>/dev/null +``` + +### Package Scripts +```bash +# Check for lint/format/typecheck scripts +grep -E '"(lint|format|typecheck|type-check|check)"' package.json 2>/dev/null +grep -E "^(lint|format|typecheck|check):" Makefile 2>/dev/null +``` + +## Output Format + +```markdown +## Tooling Scout Findings + +### Detected Stack +- Language(s): [detected] +- Package manager: [npm/pnpm/yarn/pip/cargo/go] + +### Linting +- Status: ✅ Configured / ⚠️ Partial / ❌ Missing +- Tool: [tool name] or "None found" +- Config: [file path] or "N/A" +- Script: [command] or "Not in package.json/Makefile" + +### Formatting +- Status: ✅ Configured / ⚠️ Partial / ❌ Missing +- Tool: [tool name] or "None found" +- Config: [file path] or "N/A" +- Script: [command] or "Not in package.json/Makefile" + +### Type Checking +- Status: ✅ Configured / ⚠️ Partial / ❌ Missing +- Tool: [tool name] or "None found" +- Config: [file path] or "N/A" +- Strict mode: Yes / No / N/A +- Script: [command] or "Not in package.json/Makefile" + +### Pre-commit Hooks +- Status: ✅ Configured / ❌ Missing +- Tool: [husky/pre-commit/lefthook/none] +- Runs: [what checks run on commit] + +### Recommendations +- [Priority 1]: [specific action] +- [Priority 2]: [specific action] +``` + +## Rules + +- Speed over completeness - quick file existence checks +- Note what's missing, not just what exists +- Check for scripts that run the tools (lint command existence) +- Don't read full config files - just confirm existence +- Flag partial setups (e.g., eslint exists but no pre-commit) diff --git a/.opencode/agent/workflow-scout.md b/.opencode/agent/workflow-scout.md new file mode 100644 index 0000000..469d485 --- /dev/null +++ b/.opencode/agent/workflow-scout.md @@ -0,0 +1,149 @@ +--- +description: Used by /flow-next:prime to scan for CI/CD, PR templates, issue templates, and workflow automation. Do not invoke directly. +mode: subagent +tools: + write: false + edit: false + patch: false + multiedit: false +--- +You are a workflow scout for agent readiness assessment. Scan for CI/CD pipelines, templates, and workflow automation. + +## Why This Matters + +Workflow automation ensures consistent processes. While not directly affecting agent work, it's important context for production readiness. + +## Scan Targets + +### CI/CD Pipeline (WP1) + +```bash +# GitHub Actions +ls -la .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null + +# GitLab CI +ls -la .gitlab-ci.yml 2>/dev/null + +# CircleCI +ls -la .circleci/config.yml 2>/dev/null + +# Jenkins +ls -la Jenkinsfile 2>/dev/null + +# Azure Pipelines +ls -la azure-pipelines.yml 2>/dev/null + +# If found, check what the CI does +head -50 .github/workflows/*.yml 2>/dev/null | grep -E "name:|run:|uses:" | head -20 +``` + +### PR Template (WP2) + +```bash +ls -la .github/PULL_REQUEST_TEMPLATE.md .github/PULL_REQUEST_TEMPLATE/ .github/pull_request_template.md 2>/dev/null +``` + +### Issue Templates (WP3) + +```bash +ls -la .github/ISSUE_TEMPLATE/ .github/ISSUE_TEMPLATE.md .github/issue_template.md 2>/dev/null + +# Count issue templates if directory exists +ls -la .github/ISSUE_TEMPLATE/*.md .github/ISSUE_TEMPLATE/*.yml 2>/dev/null | wc -l +``` + +### Automated PR Review (WP4) + +```bash +# Check for review bot configs +ls -la .coderabbit.yaml .github/coderabbit.yml 2>/dev/null + +# Check for Greptile +grep -l "greptile" .github/workflows/*.yml 2>/dev/null + +# Check for other review bots in recent PRs (via gh) +gh pr list --state all --limit 5 --json comments 2>/dev/null | grep -E "coderabbit|greptile|copilot" | head -3 +``` + +### Release Automation (WP5) + +```bash +# semantic-release +grep -l "semantic-release" package.json .releaserc* 2>/dev/null +ls -la .releaserc* release.config.* 2>/dev/null + +# changesets +ls -la .changeset/ .changeset/config.json 2>/dev/null + +# release-please +ls -la release-please-config.json .release-please-manifest.json 2>/dev/null + +# Check for release workflows +grep -l "release\|publish" .github/workflows/*.yml 2>/dev/null +``` + +### CONTRIBUTING.md (WP6) + +```bash +ls -la CONTRIBUTING.md .github/CONTRIBUTING.md 2>/dev/null +``` + +## Additional Context + +### Recent CI Status + +```bash +# Check recent workflow runs +gh run list --limit 5 --json name,status,conclusion 2>/dev/null +``` + +### PR Activity + +```bash +# Check if PRs use templates +gh pr list --state all --limit 3 --json body 2>/dev/null | head -20 +``` + +## Output Format + +```markdown +## Workflow Scout Findings + +### CI/CD Pipeline (WP1) +- Status: ✅ Configured / ❌ Not found +- Platform: [GitHub Actions/GitLab CI/etc. or None] +- Workflows: [list workflow files found] +- Jobs: [key jobs detected: build, test, lint, deploy, etc.] + +### PR Template (WP2) +- Status: ✅ Present / ❌ Missing +- Location: [path if found] + +### Issue Templates (WP3) +- Status: ✅ Present / ❌ Missing +- Count: [number of templates] + +### Automated PR Review (WP4) +- Status: ✅ Configured / ❌ Not detected +- Tools: [CodeRabbit/Greptile/etc. or None] + +### Release Automation (WP5) +- Status: ✅ Configured / ❌ Not detected +- Tool: [semantic-release/changesets/etc. or None] + +### CONTRIBUTING.md (WP6) +- Status: ✅ Present / ❌ Missing +- Location: [path if found] + +### Summary +- Criteria passed: X/6 +- Score: X% +``` + +## Rules + +- Use `gh` CLI for GitHub-specific checks +- Handle errors gracefully if not a GitHub repo +- Check common locations for each file type +- This is informational only - no fixes will be offered +- Note CI workflow purposes (build, test, deploy, etc.) diff --git a/.opencode/command/flow-next/prime.md b/.opencode/command/flow-next/prime.md new file mode 100644 index 0000000..671fd7c --- /dev/null +++ b/.opencode/command/flow-next/prime.md @@ -0,0 +1,11 @@ +--- +description: Assess codebase agent-readiness and propose fixes +--- + +# IMPORTANT: This command MUST invoke the skill `flow-next-opencode-prime` + +The ONLY purpose of this command is to call the `flow-next-opencode-prime` skill. You MUST use that skill now. + +**User request:** $ARGUMENTS + +Pass the user request to the skill. The skill handles all prime logic. diff --git a/.opencode/skill/flow-next-opencode-prime/SKILL.md b/.opencode/skill/flow-next-opencode-prime/SKILL.md new file mode 100644 index 0000000..ce659e8 --- /dev/null +++ b/.opencode/skill/flow-next-opencode-prime/SKILL.md @@ -0,0 +1,133 @@ +--- +name: flow-next-opencode-prime +description: Comprehensive codebase assessment for agent and production readiness. Scans 8 pillars (48 criteria), verifies commands work, checks GitHub settings. Reports everything, fixes agent readiness only. Triggers on /flow-next:prime. +--- + +# Flow Prime + +Comprehensive codebase assessment inspired by [Factory.ai's Agent Readiness framework](https://factory.ai/news/agent-readiness). + +**Role**: readiness assessor, improvement proposer +**Goal**: full visibility into codebase health, targeted fixes for agent readiness + +## Two-Tier Assessment + +| Category | Pillars | What Happens | +|----------|---------|--------------| +| **Agent Readiness** | 1-5 (30 criteria) | Scored, maturity level calculated, fixes offered | +| **Production Readiness** | 6-8 (18 criteria) | Reported for awareness, no fixes offered | + +This gives you **full visibility** while keeping remediation focused on what actually helps agents work. + +## Why This Matters + +Agents waste cycles when: +- No pre-commit hooks → waits 10min for CI instead of 5sec local feedback +- Undocumented env vars → guesses, fails, guesses again +- No CLAUDE.md → doesn't know project conventions +- Missing test commands → can't verify changes work + +These are **environment problems**, not agent problems. Prime helps fix them. + +## Input + +Full request: $ARGUMENTS + +Accepts: +- No arguments (scans current repo) +- `--report-only` or `report only` (skip remediation, just show report) +- `--fix-all` or `fix all` (apply all agent readiness fixes without asking) +- Path to different repo root + +Examples: +- `/flow-next:prime` +- `/flow-next:prime --report-only` +- `/flow-next:prime ~/other-project` + +## The Eight Pillars + +### Agent Readiness (Pillars 1-5) — Fixes Offered + +| Pillar | What It Checks | +|--------|----------------| +| **1. Style & Validation** | Linters, formatters, type checking, pre-commit hooks | +| **2. Build System** | Build tools, commands, lock files, monorepo tooling | +| **3. Testing** | Test framework, commands, coverage, verification | +| **4. Documentation** | README, CLAUDE.md, setup docs, architecture | +| **5. Dev Environment** | .env.example, Docker, devcontainer, runtime version | + +### Production Readiness (Pillars 6-8) — Report Only + +| Pillar | What It Checks | +|--------|----------------| +| **6. Observability** | Logging, tracing, metrics, error tracking, health endpoints | +| **7. Security** | Branch protection, secret scanning, CODEOWNERS, Dependabot | +| **8. Workflow & Process** | CI/CD, PR templates, issue templates, release automation | + +## Workflow + +Read [workflow.md](workflow.md) and execute each phase in order. + +**Key phases:** +1. **Parallel Assessment** — 9 scouts run in parallel (~15-20 seconds) +2. **Verification** — Verify test commands actually work +3. **Score & Synthesize** — Calculate scores, determine maturity level +4. **Present Report** — Full report with all 8 pillars +5. **Interactive Remediation** — Ask in plain text (multi-select) for agent readiness fixes only +6. **Apply Fixes** — Create/modify files based on selections +7. **Summary** — Show what was changed + +## Maturity Levels (Agent Readiness) + +| Level | Name | Description | Score | +|-------|------|-------------|-------| +| 1 | Minimal | Basic project structure only | <30% | +| 2 | Functional | Can build and run, limited docs | 30-49% | +| 3 | **Standardized** | Agent-ready for routine work | 50-69% | +| 4 | Optimized | Fast feedback loops, comprehensive docs | 70-84% | +| 5 | Autonomous | Full autonomous operation capable | 85%+ | + +**Level 3 is the target** for most teams. Don't over-engineer. + +## What Gets Fixed vs Reported + +| Pillars | Category | Remediation | +|---------|----------|-------------| +| 1-5 | Agent Readiness | ✅ Fixes offered via plain-text consent | +| 6-8 | Production Readiness | ❌ Reported only, address independently | + +## Guardrails + +### General +- Never modify code files (only config, docs, scripts) +- Never commit changes (leave for user to review) +- Never delete files +- Respect .gitignore patterns + +### User Consent +- Ask for consent in plain text (no Question tool) +- Wait for explicit user reply before making changes +- Always ask before modifying existing files +- Don't add dependencies without consent + +### Scope Control +- **Never create LICENSE files** — license choice requires explicit user decision +- **Never offer Pillar 6-8 fixes** — production readiness is informational only +- Focus fixes on what helps agents work (not team governance) + +## Scouts + +### Agent Readiness (fast) +- `tooling-scout` — linters, formatters, pre-commit, type checking +- `claude-md-scout` — CLAUDE.md/AGENTS.md analysis +- `env-scout` — environment setup +- `testing-scout` — test infrastructure +- `build-scout` — build system +- `docs-gap-scout` — README, ADRs, architecture + +### Production Readiness (fast) +- `observability-scout` — logging, tracing, metrics, health +- `security-scout` — GitHub settings, CODEOWNERS, secrets +- `workflow-scout` — CI/CD, templates, automation + +All 9 scouts run in parallel for speed. diff --git a/.opencode/skill/flow-next-opencode-prime/pillars.md b/.opencode/skill/flow-next-opencode-prime/pillars.md new file mode 100644 index 0000000..e05cc34 --- /dev/null +++ b/.opencode/skill/flow-next-opencode-prime/pillars.md @@ -0,0 +1,221 @@ +# Agent Readiness Pillars + +Eight pillars for comprehensive codebase assessment. Pillars 1-5 measure **agent readiness** (fixes offered). Pillars 6-8 measure **production readiness** (reported only). + +--- + +## Pillar 1: Style & Validation + +Automated tools that catch bugs instantly. Without them, agents waste cycles on syntax errors and style drift. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| SV1 | Linter configured | ESLint, Biome, oxlint, Flake8, Ruff, golangci-lint, or Clippy config exists | +| SV2 | Formatter configured | Prettier, Biome, Black, gofmt, or rustfmt config/usage detected | +| SV3 | Type checking | TypeScript strict, mypy, pyright, or language with static types | +| SV4 | Pre-commit hooks | Husky, pre-commit, lefthook, or similar configured | +| SV5 | Lint script exists | `lint` command in package.json, Makefile, or equivalent | +| SV6 | Format script exists | `format` command available | + +### Scoring +- ✅ 80%+: All core tools configured +- ⚠️ 40-79%: Partial setup +- ❌ <40%: Missing fundamentals + +--- + +## Pillar 2: Build System + +Clear build process that agents can execute reliably. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| BS1 | Build tool detected | Vite, webpack, tsc, cargo, go build, Turbo, etc. | +| BS2 | Build command exists | `build` script in package.json/Makefile | +| BS3 | Dev command exists | `dev` or `start` script available | +| BS4 | Build output gitignored | dist/, build/, .next/, target/ in .gitignore | +| BS5 | Lock file committed | package-lock.json, pnpm-lock.yaml, Cargo.lock, uv.lock, etc. | +| BS6 | Monorepo tooling | Turborepo, Nx, Lerna, or pnpm workspaces (if applicable) | + +### Scoring +- ✅ 80%+: Reproducible builds +- ⚠️ 40-79%: Builds work but fragile +- ❌ <40%: Build process unclear + +--- + +## Pillar 3: Testing + +Test infrastructure that lets agents verify their work. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| TS1 | Test framework configured | Jest, Vitest, pytest, go test, etc. | +| TS2 | Test command exists | `test` script available | +| TS3 | Tests exist | >0 test files in repo | +| TS4 | Tests runnable | `pytest --collect-only` or equivalent succeeds | +| TS5 | Coverage configured | nyc, c8, coverage.py, etc. | +| TS6 | E2E tests exist | Playwright, Cypress, or integration tests | + +### Scoring +- ✅ 80%+: Comprehensive test setup +- ⚠️ 40-79%: Basic testing in place +- ❌ <40%: Testing gaps + +--- + +## Pillar 4: Documentation + +Clear docs that tell agents how the project works. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| DC1 | README exists | README.md with meaningful content (not just template) | +| DC2 | CLAUDE.md/AGENTS.md exists | Agent instruction file present | +| DC3 | Setup documented | Installation/setup instructions in README or docs | +| DC4 | Build commands documented | How to build/run in README or CLAUDE.md | +| DC5 | Test commands documented | How to run tests documented | +| DC6 | Architecture documented | ARCHITECTURE.md, ADRs, or docs/ with structure | + +### Scoring +- ✅ 80%+: Agents can self-serve +- ⚠️ 40-79%: Basic docs present +- ❌ <40%: Agents must guess + +--- + +## Pillar 5: Dev Environment + +Reproducible environment setup. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| DE1 | .env.example exists | Template for required env vars | +| DE2 | .env gitignored | .env in .gitignore | +| DE3 | Runtime version pinned | .nvmrc, .python-version, .tool-versions, etc. | +| DE4 | Setup script or docs | setup.sh or clear setup instructions | +| DE5 | Devcontainer available | .devcontainer/ config present | +| DE6 | Docker available | Dockerfile or docker-compose.yml | + +### Scoring +- ✅ 80%+: One-command setup possible +- ⚠️ 40-79%: Setup mostly documented +- ❌ <40%: Setup requires tribal knowledge + +--- + +## Pillar 6: Observability (Production Readiness) + +**Informational only** — reported but not scored for agent readiness. No fixes offered. + +Runtime visibility that helps debug issues. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| OB1 | Structured logging | winston, pino, bunyan, structlog, or similar | +| OB2 | Distributed tracing | OpenTelemetry, X-Request-ID propagation | +| OB3 | Metrics collection | Prometheus, Datadog, NewRelic instrumentation | +| OB4 | Error tracking | Sentry, Bugsnag, Rollbar configured | +| OB5 | Health endpoints | /health, /healthz, /ready endpoints | +| OB6 | Alerting configured | PagerDuty, OpsGenie, or alert rules | + +### Status Indicators +- ✅ Configured +- ❌ Not detected + +--- + +## Pillar 7: Security (Production Readiness) + +**Informational only** — reported but not scored for agent readiness. No fixes offered. + +Security posture and access controls. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| SE1 | Branch protection | Main/master branch protected (via `gh api`) | +| SE2 | Secret scanning | GitHub secret scanning enabled | +| SE3 | CODEOWNERS | .github/CODEOWNERS file exists | +| SE4 | Dependency updates | Dependabot or Renovate configured | +| SE5 | Secrets management | .env gitignored, no secrets in code | +| SE6 | Security scanning | CodeQL, Snyk, or similar configured | + +### Status Indicators +- ✅ Configured +- ❌ Not detected + +--- + +## Pillar 8: Workflow & Process (Production Readiness) + +**Informational only** — reported but not scored for agent readiness. No fixes offered. + +Team processes and automation. + +### Criteria + +| ID | Criterion | Pass Condition | +|----|-----------|----------------| +| WP1 | CI/CD pipeline | GitHub Actions, GitLab CI, or similar | +| WP2 | PR template | .github/PULL_REQUEST_TEMPLATE.md exists | +| WP3 | Issue templates | .github/ISSUE_TEMPLATE/ exists | +| WP4 | Automated PR review | CodeRabbit, Greptile, or similar configured | +| WP5 | Release automation | Semantic-release, changesets, or similar | +| WP6 | CONTRIBUTING.md | Contribution guidelines present | + +### Status Indicators +- ✅ Configured +- ❌ Not detected + +--- + +## Scoring Summary + +### Agent Readiness Score (Pillars 1-5) + +Used for maturity level calculation and remediation decisions. + +| Level | Name | Requirements | +|-------|------|--------------| +| 1 | Minimal | <30% overall | +| 2 | Functional | 30-49% overall | +| 3 | Standardized | 50-69% overall, all pillars ≥40% | +| 4 | Optimized | 70-84% overall, all pillars ≥60% | +| 5 | Autonomous | 85%+ overall, all pillars ≥80% | + +**Agent Readiness Score** = average of Pillars 1-5 scores + +### Production Readiness Score (Pillars 6-8) + +Informational only. Reported for awareness. + +**Production Readiness Score** = average of Pillars 6-8 scores + +### Overall Score + +**Overall Score** = average of all 8 pillars + +--- + +## What Gets Fixed vs Reported + +| Pillars | Category | Remediation | +|---------|----------|-------------| +| 1-5 | Agent Readiness | ✅ Fixes offered via plain-text consent | +| 6-8 | Production Readiness | ❌ Reported only, address independently | + +**Level 3 (Standardized)** is the target for agent readiness. It means agents can handle routine work: bug fixes, tests, docs, dependency updates. diff --git a/.opencode/skill/flow-next-opencode-prime/remediation.md b/.opencode/skill/flow-next-opencode-prime/remediation.md new file mode 100644 index 0000000..387ad80 --- /dev/null +++ b/.opencode/skill/flow-next-opencode-prime/remediation.md @@ -0,0 +1,322 @@ +# Remediation Templates + +Templates for fixing agent readiness gaps. Focus on what helps agents work effectively: fast local feedback, clear commands, documented conventions. + +**Priority order:** +1. **Critical**: CLAUDE.md, .env.example, lint/format commands +2. **High**: Pre-commit hooks, test command, runtime version +3. **Medium**: Build scripts, .gitignore entries +4. **Low/Bonus**: Devcontainer, Docker (nice-to-have, not essential) + +**NOT offered** (team governance, not agent readiness): +- CONTRIBUTING.md, PR templates, issue templates, CODEOWNERS, LICENSE + +--- + +## Critical: Documentation + +### Create CLAUDE.md + +Location: `CLAUDE.md` (repo root) + +**Why**: Agents need to know project conventions, commands, and structure. Without this, they guess. + +Template (adapt based on detected stack): + +```markdown +# Project Name + +## Quick Commands + +```bash +# Install dependencies +[detected package manager] install + +# Run development server +[detected dev command] + +# Run tests +[detected test command] + +# Build for production +[detected build command] + +# Lint code +[detected lint command] + +# Format code +[detected format command] +``` + +## Project Structure + +``` +[detected structure - key directories only] +``` + +## Code Conventions + +- [Detected naming convention] +- [Detected file organization] +- [Patterns from existing code] + +## Things to Avoid + +- [Common pitfalls for this stack] +``` + +### Create .env.example + +Location: `.env.example` (repo root) + +**Why**: Agents waste cycles guessing env vars. This documents what's required. + +Process: +1. Scan code for env var usage (process.env.*, os.environ, etc.) +2. Create template with detected vars +3. Add placeholder values and comments + +Template: + +```bash +# Required for [feature] +VAR_NAME=your_value_here + +# Optional: [description] +OPTIONAL_VAR=default_value +``` + +--- + +## High: Fast Local Feedback + +### Add Pre-commit Hooks (JavaScript/TypeScript) + +**Why**: Agents get instant feedback instead of waiting 10min for CI. + +If husky not installed, add to package.json devDependencies: + +```json +{ + "devDependencies": { + "husky": "^9.0.0", + "lint-staged": "^15.0.0" + }, + "lint-staged": { + "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"], + "*.{json,md}": ["prettier --write"] + } +} +``` + +Then run: +```bash +npx husky init +echo "npx lint-staged" > .husky/pre-commit +``` + +### Add Pre-commit Hooks (Python) + +Create `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.3.0 + hooks: + - id: ruff + args: [--fix] + - id: ruff-format +``` + +### Add Linter Config (if NO linter detected) + +**Important**: Only offer if NO linter exists. ESLint, Biome, oxlint, Ruff are all valid. Don't replace one with another. + +Recommend based on project: +- **Biome** (recommended for new projects): fast, does lint + format +- **ESLint** (established projects): wide ecosystem +- **oxlint** (performance-critical): very fast +- **Ruff** (Python): very fast + +Example ESLint - `eslint.config.js`: + +```javascript +import js from '@eslint/js'; + +export default [ + js.configs.recommended, +]; +``` + +Example Biome - `biome.json`: + +```json +{ + "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", + "linter": { "enabled": true }, + "formatter": { "enabled": true } +} +``` + +### Add Formatter Config (if NO formatter detected) + +**Important**: Only offer if NO formatter exists. Biome handles both lint + format. Prettier, Black, gofmt are all valid. + +Example Prettier - `.prettierrc`: + +```json +{ + "semi": true, + "singleQuote": true, + "tabWidth": 2 +} +``` + +Note: If Biome is already configured, it handles formatting. Don't add Prettier. + +### Add Runtime Version File + +For Node.js, create `.nvmrc`: +``` +20 +``` + +For Python, create `.python-version`: +``` +3.12 +``` + +--- + +## Medium: Build & Environment + +### Add .gitignore Entries + +Append to `.gitignore` if missing: + +``` +# Environment +.env +.env.local +.env.*.local + +# Build outputs +dist/ +build/ +.next/ +out/ + +# Dependencies +node_modules/ + +# IDE +.idea/ +.vscode/ +*.swp +``` + +### Add Test Config (if test framework detected but no config) + +Jest - create `jest.config.js`: + +```javascript +/** @type {import('jest').Config} */ +const config = { + testEnvironment: 'node', + testMatch: ['**/*.test.js', '**/*.test.ts'], +}; + +module.exports = config; +``` + +Vitest - create `vitest.config.ts`: + +```typescript +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + test: { + globals: true, + environment: 'node', + }, +}); +``` + +pytest - create `pytest.ini`: + +```ini +[pytest] +testpaths = tests +python_files = test_*.py +python_functions = test_* +addopts = -v --tb=short +``` + +--- + +## Low/Bonus: Optional Enhancements + +These are nice-to-have but NOT essential for agent readiness. Only offer if user explicitly wants them. + +### Create Devcontainer (Bonus) + +Create `.devcontainer/devcontainer.json`: + +```json +{ + "name": "[Project Name]", + "image": "mcr.microsoft.com/devcontainers/[language]:latest", + "features": {}, + "postCreateCommand": "[install command]" +} +``` + +### Add Basic CI Workflow (Bonus) + +**Note**: Agents benefit more from pre-commit hooks (instant feedback) than CI (slow feedback). Only add if user wants CI. + +Create `.github/workflows/ci.yml`: + +```yaml +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup [runtime] + uses: actions/setup-[runtime]@v4 + - name: Install + run: [install command] + - name: Lint + run: [lint command] + - name: Test + run: [test command] +``` + +--- + +## Application Rules + +1. **Detect before creating** - Check if file exists first +2. **Preserve existing content** - Merge with existing configs when possible +3. **Match project style** - Use detected indent (tabs/spaces), quote style +4. **Don't add unused features** - Only add what the project needs +5. **Explain changes** - Tell user what was created and why +6. **Respect user choices** - Never force changes without consent diff --git a/.opencode/skill/flow-next-opencode-prime/workflow.md b/.opencode/skill/flow-next-opencode-prime/workflow.md new file mode 100644 index 0000000..bdd9bd2 --- /dev/null +++ b/.opencode/skill/flow-next-opencode-prime/workflow.md @@ -0,0 +1,301 @@ +# Flow Prime Workflow + +Execute these phases in order. Reference [pillars.md](pillars.md) for scoring criteria and [remediation.md](remediation.md) for fix templates. + +**Model guidance**: Use the main model for synthesis and reporting. Scouts run as subagents for speed. + +--- + +## Phase 1: Parallel Assessment + +Run all 9 scouts in parallel using the Task tool: + +### Agent Readiness Scouts (Pillars 1-5) + +``` +Task flow-next:tooling-scout # linters, formatters, pre-commit, type checking +Task flow-next:claude-md-scout # CLAUDE.md/AGENTS.md quality +Task flow-next:env-scout # .env.example, docker, devcontainer +Task flow-next:testing-scout # test framework, coverage, commands +Task flow-next:build-scout # build system, scripts, CI +Task flow-next:docs-gap-scout # README, ADRs, architecture docs +``` + +### Production Readiness Scouts (Pillars 6-8) + +``` +Task flow-next:observability-scout # logging, tracing, metrics, health +Task flow-next:security-scout # branch protection, CODEOWNERS, secrets +Task flow-next:workflow-scout # CI/CD, templates, automation +``` + +**Important**: Launch all 9 scouts in parallel for speed (~15-20 seconds total). + +Wait for all scouts to complete. Collect findings. + +--- + +## Phase 2: Verification (Optional but Recommended) + +After scouts complete, verify key commands actually work. + +### Test Verification + +If test framework detected by testing-scout, verify tests are runnable using the **appropriate command for the detected framework**. + +**Common examples** (adapt to whatever framework is detected): + +| Framework | Verification Command | +|-----------|---------------------| +| pytest | `pytest --collect-only` | +| Jest | `npx jest --listTests` | +| Vitest | `npx vitest --run --reporter=dot` | +| Mocha | `npx mocha --dry-run` | +| Go test | `go test ./... -list .` | +| Cargo test | `cargo test --no-run` | +| PHPUnit | `phpunit --list-tests` | + +These are examples. For other frameworks, find the equivalent "list tests" or "dry run" command. The goal is to verify tests are discoverable without actually running them. + +**For monorepos**: Run verification in each app directory that has tests. + +**Adapt to project**: Use the package manager detected (pnpm/npm/yarn/bun). If venv detected for Python, activate it first. + +Example: +```bash +# Python with venv +cd apps/api && source .venv/bin/activate && pytest --collect-only 2>&1 | head -20 + +# JS with pnpm +pnpm test --passWithNoTests 2>&1 | head -10 + +# Go +go test ./... -list . 2>&1 | head -20 +``` + +Mark TS4 as ✅ only if verification succeeds (tests are discoverable and runnable). + +### Build Verification (Quick) + +```bash +# Check if build command exists and is valid +pnpm build --help 2>&1 | head -5 || npm run build --help 2>&1 | head -5 +``` + +--- + +## Phase 3: Score & Synthesize + +Read [pillars.md](pillars.md) for pillar definitions and criteria. + +### Agent Readiness Score (Pillars 1-5) + +For each pillar (1-5): +1. Map scout findings to criteria (pass/fail) +2. Calculate pillar score: `(passed / total) * 100` + +Calculate: +- **Agent Readiness Score**: average of Pillars 1-5 scores +- **Maturity Level**: based on thresholds in pillars.md + +### Production Readiness Score (Pillars 6-8) + +For each pillar (6-8): +1. Map scout findings to criteria (pass/fail) +2. Calculate pillar score: `(passed / total) * 100` + +Calculate: +- **Production Readiness Score**: average of Pillars 6-8 scores + +### Overall Score + +**Overall Score** = average of all 8 pillar scores + +### Prioritize Recommendations + +Generate prioritized recommendations from **Pillars 1-5 only**: +1. Critical first (CLAUDE.md, .env.example) +2. High impact second (pre-commit hooks, lint commands) +3. Medium last (build scripts, .gitignore) + +**Never offer fixes for Pillars 6-8** — these are informational only. + +--- + +## Phase 4: Present Report + +```markdown +# Agent Readiness Report + +**Repository**: [name] +**Assessed**: [timestamp] + +## Scores Summary + +| Category | Score | Level | +|----------|-------|-------| +| **Agent Readiness** (Pillars 1-5) | X% | Level N - [Name] | +| Production Readiness (Pillars 6-8) | X% | — | +| **Overall** | X% | — | + +## Agent Readiness (Pillars 1-5) + +These affect your maturity level and are eligible for fixes. + +| Pillar | Score | Status | +|--------|-------|--------| +| Style & Validation | X% (N/6) | ✅ ≥80% / ⚠️ 40-79% / ❌ <40% | +| Build System | X% (N/6) | ✅/⚠️/❌ | +| Testing | X% (N/6) | ✅/⚠️/❌ | +| Documentation | X% (N/6) | ✅/⚠️/❌ | +| Dev Environment | X% (N/6) | ✅/⚠️/❌ | + +## Production Readiness (Pillars 6-8) + +Informational only. No fixes offered — address independently if desired. + +| Pillar | Score | Status | +|--------|-------|--------| +| Observability | X% (N/6) | ✅/⚠️/❌ | +| Security | X% (N/6) | ✅/⚠️/❌ | +| Workflow & Process | X% (N/6) | ✅/⚠️/❌ | + +## Detailed Findings + +### Pillar 1: Style & Validation (X%) + +| Criterion | Status | Evidence | +|-----------|--------|----------| +| SV1: Linter | ✅/❌ | [details] | +| SV2: Formatter | ✅/❌ | [details] | +| ... | ... | ... | + +[Repeat for each pillar] + +## Top Recommendations (Agent Readiness) + +1. **[Category]**: [specific action] — [why it helps agents] +2. **[Category]**: [specific action] — [why it helps agents] +3. **[Category]**: [specific action] — [why it helps agents] + +## Production Readiness Notes + +[Key observations from Pillars 6-8 that the team should be aware of] +``` + +**If `--report-only`**: Stop here. Show report and exit. + +--- + +## Phase 5: Interactive Remediation + +**If `--fix-all`**: Skip to Phase 6, apply all recommendations from Pillars 1-5. + +**CRITICAL**: Ask for consent in plain text. **Do NOT** use the Question tool. Wait for a reply before changing files. + +Each question should: +- Be a single category (Docs/Tooling/Testing/Environment) +- Use lettered options (a/b/c/d) and allow multi-select (reply: "a,c") +- Explain what each option does and WHY it helps agents +- Include impact description for each option + +### Question Structure + +Ask ONE question per category that has recommendations. Skip categories with no gaps. + +**Question 1: Documentation (if gaps exist)** + +``` +Docs improvements? Reply with letters (e.g., "a,c") or "skip". +a) Create CLAUDE.md (Recommended) — Agent instructions with commands, conventions, structure. Critical for agents. +b) Create .env.example — Template with [N] detected env vars. Prevents config guessing. +``` + +**Question 2: Tooling (if gaps exist)** + +``` +Tooling improvements? Reply with letters (e.g., "a,d") or "skip". +a) Add pre-commit hooks (Recommended) — Husky + lint-staged for instant feedback (5 sec vs 10 min CI). +b) Add linter config — [Tool] config so agents can run lint locally. +c) Add formatter config — [Tool] config to prevent style drift across sessions. +d) Add runtime version file — Pin [runtime] version for consistent environments. +``` + +**Question 3: Testing (if gaps exist)** + +``` +Testing improvements? Reply with letters (e.g., "a") or "skip". +a) Add test config (Recommended) — [Framework] config so tests can run. +b) Add test script — Adds a `test` command agents can discover and run. +``` + +**Question 4: Environment (if gaps exist)** + +``` +Environment improvements? Reply with letters (e.g., "a") or "skip". +a) Add .gitignore entries (Recommended) — Ignore .env/build outputs/node_modules to avoid accidental commits. +b) Create devcontainer (Bonus) — Reproducible VS Code environment (nice-to-have). +``` + +### Rules for Questions + +1. **Use plain text questions** — no Question tool +2. **Mark recommended items** — Add "(Recommended)" to high-impact options +3. **Mark bonus items** — Add "(Bonus)" to nice-to-have options +4. **Explain agent benefit** — Each description should say WHY it helps agents +5. **Skip empty categories** — Don't ask if no recommendations +6. **Max 4 options per question** — Tool limit, prioritize if more +7. **Never offer Pillar 6-8 items** — Production readiness is informational only + +--- + +## Phase 6: Apply Fixes + +For each approved fix: +1. Read [remediation.md](remediation.md) for the template +2. Detect project conventions (indent style, quote style, etc.) +3. Adapt template to match conventions +4. Check if target file exists: + - **New file**: Create it + - **Existing file**: Show diff and ask before modifying +5. Report what was created/modified + +**Non-destructive rules:** +- Never overwrite without explicit consent +- Merge with existing configs when possible +- Use detected project style +- Don't add unused features + +--- + +## Phase 7: Summary + +After fixes applied: + +```markdown +## Changes Applied + +### Created +- `CLAUDE.md` — Project conventions for agents +- `.env.example` — Environment variable template + +### Modified +- `package.json` — Added lint-staged config + +### Skipped (user declined) +- Pre-commit hooks + +### Not Offered (production readiness) +- CI/CD, PR templates, observability, security — address independently if desired +``` + +Offer re-assessment only if changes were made: + +``` +Run assessment again to see updated score? +``` + +If yes, run Phase 1-4 again and show: +- New Agent Readiness score and maturity level +- Score changes per pillar +- Remaining recommendations diff --git a/.opencode/version b/.opencode/version index 3a4036f..53a75d6 100644 --- a/.opencode/version +++ b/.opencode/version @@ -1 +1 @@ -0.2.5 +0.2.6 diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f2762c..3b253a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,18 @@ ## Unreleased +**Restores parity with upstream Claude Code plugin (flow-next 0.18.0 + 0.18.4).** + +### Ported from upstream 0.18.0 → 0.18.4 + +- **/flow-next:prime** — Agent readiness assessment (8 pillars, report + optional fixes) +- **Prime scouts** — tooling/claude-md/env/testing/build/observability/security/workflow +- **Prime remediation templates** — CLAUDE.md, .env.example, pre-commit, lint/format, runtime pins, .gitignore, test configs +- **Ralph receipt enforcement** — Missing/invalid review receipts reset tasks and retry +- **Ralph timeouts** — Timeouts no longer count against attempt limits +- **Ralph unscoped runs** — Auto-close open epics when scope not specified +- **Docs** — Clarify RepoPrompt 1.6.0+ requirement for rp review backend + **Restores parity with upstream Claude Code plugin (flow-next 0.17.0 + 0.17.1).** ### Ported from upstream 0.17.0 → 0.17.1 diff --git a/README.md b/README.md index a6e465c..b8bde96 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Flow-Next (OpenCode) -[![Version](https://img.shields.io/badge/Version-0.2.0-green)](./CHANGELOG.md) +[![Version](https://img.shields.io/badge/Version-0.2.6-green)](./CHANGELOG.md) [![Status](https://img.shields.io/badge/Status-Experimental-orange)](./CHANGELOG.md) **Plan first, work second. OpenCode-native port of Flow-Next.** @@ -189,6 +189,156 @@ You can always run interview again after planning to catch anything missed. Inte --- +## Agent Readiness Assessment + +> Inspired by [Factory.ai's Agent Readiness framework](https://factory.ai/news/agent-readiness) + +`/flow-next:prime` assesses your codebase for agent-readiness and proposes improvements. Works for greenfield and brownfield projects. + +### The Problem + +Agents waste cycles when codebases lack: +- **Pre-commit hooks** → waits 10min for CI instead of 5sec local feedback +- **Documented env vars** → guesses, fails, guesses again +- **CLAUDE.md** → doesn't know project conventions +- **Test commands** → can't verify changes work + +These are **environment problems**, not agent problems. Prime helps fix them. + +### Quick Start + +```bash +/flow-next:prime # Full assessment + interactive fixes +/flow-next:prime --report-only # Just show the report +/flow-next:prime --fix-all # Apply all fixes without asking +``` + +### The Eight Pillars + +Prime evaluates your codebase across eight pillars (48 criteria total): + +#### Agent Readiness (Pillars 1-5) — Scored, Fixes Offered + +| Pillar | What It Checks | +|--------|----------------| +| **1. Style & Validation** | Linters, formatters, type checking, pre-commit hooks | +| **2. Build System** | Build tool, commands, lock files, monorepo tooling | +| **3. Testing** | Test framework, commands, verification, coverage, E2E | +| **4. Documentation** | README, CLAUDE.md, setup docs, architecture | +| **5. Dev Environment** | .env.example, Docker, devcontainer, runtime version | + +#### Production Readiness (Pillars 6-8) — Reported Only + +| Pillar | What It Checks | +|--------|----------------| +| **6. Observability** | Structured logging, tracing, metrics, error tracking, health endpoints | +| **7. Security** | Branch protection, secret scanning, CODEOWNERS, Dependabot | +| **8. Workflow & Process** | CI/CD, PR templates, issue templates, release automation | + +**Two-tier approach**: Pillars 1-5 determine your agent maturity level and are eligible for fixes. Pillars 6-8 are reported for visibility but no fixes are offered — these are team/production decisions. + +### Maturity Levels + +| Level | Name | Description | Overall Score | +|-------|------|-------------|---------------| +| 1 | Minimal | Basic project structure only | <30% | +| 2 | Functional | Can build and run, limited docs | 30-49% | +| 3 | **Standardized** | Agent-ready for routine work | 50-69% | +| 4 | Optimized | Fast feedback loops, comprehensive docs | 70-84% | +| 5 | Autonomous | Full autonomous operation capable | 85%+ | + +**Level 3 is the target** for most teams. It means agents can handle routine work: bug fixes, tests, docs, dependency updates. + +### How It Works + +1. **Parallel Assessment** — 9 scouts run in parallel (~15-20 seconds) +2. **Verification** — Verifies test commands actually work (e.g., `pytest --collect-only`) +3. **Synthesize Report** — Calculates Agent Readiness score, Production Readiness score, maturity level +4. **Interactive Remediation** — Plain-text questions (reply with letters) for agent readiness fixes only +5. **Apply Fixes** — Creates/modifies files based on your selections +6. **Re-assess** — Optionally re-run to show improvement + +### Example Report + +```markdown +# Agent Readiness Report + +**Repository**: my-project +**Assessed**: 2026-01-23 + +## Scores Summary + +| Category | Score | Level | +|----------|-------|-------| +| **Agent Readiness** (Pillars 1-5) | 73% | Level 4 - Optimized | +| Production Readiness (Pillars 6-8) | 17% | — | +| **Overall** | 52% | — | + +## Agent Readiness (Pillars 1-5) + +| Pillar | Score | Status | +|--------|-------|--------| +| Style & Validation | 67% (4/6) | ⚠️ | +| Build System | 100% (6/6) | ✅ | +| Testing | 67% (4/6) | ⚠️ | +| Documentation | 83% (5/6) | ✅ | +| Dev Environment | 83% (5/6) | ✅ | + +## Production Readiness (Pillars 6-8) — Report Only + +| Pillar | Score | Status | +|--------|-------|--------| +| Observability | 33% (2/6) | ❌ | +| Security | 17% (1/6) | ❌ | +| Workflow & Process | 0% (0/6) | ❌ | + +## Top Recommendations (Agent Readiness) + +1. **Tooling**: Add pre-commit hooks — 5 sec feedback vs 10 min CI wait +2. **Tooling**: Add Python type checking — catch errors locally +3. **Docs**: Update README — replace generic template +``` + +### Remediation Templates + +Prime offers fixes for agent readiness gaps (**not** team governance): + +| Fix | What Gets Created | +|-----|-------------------| +| CLAUDE.md | Project overview, commands, structure, conventions | +| .env.example | Template with detected env vars | +| Pre-commit (JS) | Husky + lint-staged config | +| Pre-commit (Python) | `.pre-commit-config.yaml` | +| Linter config | ESLint, Biome, or Ruff config (if none exists) | +| Formatter config | Prettier or Biome config (if none exists) | +| .nvmrc/.python-version | Runtime version pinning | +| .gitignore entries | .env, build outputs, node_modules | + +Templates adapt to your project's detected conventions and existing tools. Won't suggest ESLint if you have Biome, etc. + +### User Consent Required + +**By default, prime asks before every change** using plain-text prompts. You choose what gets created. + +- **Asks first** — text questions with lettered options (reply "a,c") +- **Never overwrites** existing files without explicit consent +- **Never commits** changes (leaves for you to review) +- **Never deletes** files +- **Merges** with existing configs when possible +- **Respects** your existing tools (won't add ESLint if you have Biome) + +Use `--fix-all` to skip questions and apply everything. Use `--report-only` to just see the assessment. + +### Flags + +| Flag | Description | +|------|-------------| +| `--report-only` | Skip remediation, just show report | +| `--fix-all` | Apply all recommendations without asking | +| `` | Assess a different directory | + +--- + ## Human-in-the-Loop Workflow (Detailed) ```mermaid @@ -232,6 +382,7 @@ flowchart TD | `/flow-next:work ` | Execute epic, task, or spec file, re-anchoring before each | | `/flow-next:interview ` | Deep interview to flesh out a spec before planning | | `/flow-next:plan-review ` | Carmack-level plan review via OpenCode or RepoPrompt | +| `/flow-next:prime` | Assess codebase agent-readiness, propose fixes | | `/flow-next:impl-review` | Carmack-level impl review of current branch | | `/flow-next:sync ` | Manually sync downstream specs after implementation drift | | `/flow-next:ralph-init` | Scaffold repo-local Ralph harness ( `scripts/ralph/` ) | @@ -247,6 +398,9 @@ Work accepts an epic ( `fn-N` ), task ( `fn-N.M` ), or markdown spec file ( `.md /flow-next:plan Add caching --research=grep --no-review /flow-next:plan Add auth --research=rp --review=rp +/flow-next:prime --report-only +/flow-next:prime --fix-all + /flow-next:work fn-1 --branch=current --no-review /flow-next:work fn-1 --branch=new --review=opencode @@ -267,6 +421,7 @@ Natural language also works: | `/flow-next:work` | `--branch=current|new|worktree` , `--review=opencode|rp|export|none` , `--no-review` | | `/flow-next:plan-review` | `--review=opencode|rp|export` | | `/flow-next:impl-review` | `--review=opencode|rp|export` | +| `/flow-next:prime` | `--report-only`, `--fix-all` | --- @@ -405,7 +560,7 @@ Change those if you want a different model or effort. [RepoPrompt](https://repoprompt.com/?atp=KJbuL4) provides the best review experience on macOS. -**Requires RepoPrompt 1.6.0+** for the rp review backend (builder review mode). +**Requires RepoPrompt 1.6.0+** for the rp review backend (builder review mode). Older versions will fail — upgrade if using rp. **Why use RepoPrompt:** * Best-in-class context builder for reviews (full file context, smart selection)