Jon's agent skills, rules, and scripts

[j0ntz]

edge-dev-agents

Complete agent-assisted development workflow for Edge repositories:
slash skills, companion scripts, coding standards, review standards,
and meta-tooling for maintaining the workflow itself.

The distributable Cursor content lives under .cursor/. This repo is the
versioned home for those skills, rules, scripts, and docs.

The canonical local doc lives at ~/.cursor/README.md. During
/convention-sync, that file is mirrored to edge-dev-agents/README.md, and
the repo copy should not keep a second .cursor/README.md.

Installation

Fresh machine (one command): clone this repo and run the bootstrap — it
installs everything (cursor skills/rules, the orchestration system, and shared
memories) into your home dir, seeds credentials.json from the example, and
links skills + shared memory:

git clone <this-repo> ~/git/edge-dev-agents && cd ~/git/edge-dev-agents && ./bootstrap.sh
# then edit ~/.config/agent-watcher/credentials.json with your real asana_token

For incremental onboarding instead of the full bootstrap:

1. Set the required env var in your ~/.zshrc:

export GIT_BRANCH_PREFIX=yourname   # e.g. jon, paul, sam

This drives branch naming and PR discovery across the workflow.

2. Sync the repo copy into ~/.cursor/:

This repo treats ~/.cursor/ as the canonical working copy. Use
/convention-sync to move local changes into edge-dev-agents, or run the
companion script directly when onboarding:

~/.cursor/skills/convention-sync/scripts/convention-sync.sh \
  --repo-to-user --stage

3. Verify prerequisites:

• gh CLI: gh auth login
• jq: brew install jq
• ASANA_TOKEN env var for Asana-backed workflows

Table of Contents

• Architecture
• Orchestration & Memory
• Skills
• Companion Scripts
• Shared Modules
• Rules
• Design Principles

Orchestration & Memory

The orchestration system runs Asana tasks to PRs autonomously: a watcher picks up
Pending tasks, spawns one isolated agent session per task, and a watchdog tends
the live sessions. Post-hoc evals grade what each run did.

How a run flows

1. Watcher (agent-watcher/asana-watcher.js, launchd every 120s): polls the
   project for agent_status = Pending. It skips the tick when a resource
   guardrail trips (1-minute load over max_load_avg, or free RAM under
   min_free_ram_gb) or the concurrency cap (max_concurrent, default 4) is full.
   For each pickable task it refreshes the iOS-sim pool and allocates a slot (a git
   worktree, a cloned simulator, a Metro port). Before recloning the pool it runs
   refresh-master-build.sh: if develop has advanced and its native side
   (ios/Podfile.lock) changed, it rebuilds the master sim from develop and
   reclones so runs test against a current build instead of a pinned-stale one. A
   JS-only develop advance skips the rebuild (clones bundle JS live from Metro);
   the check is a cheap git fetch plus a SHA compare, and a build failure is
   non-fatal (provisioning continues on the last-good master). A NEVER-run task is spawned fresh:
   agent_status = Planning, a tmux session claude-asana-(gid) running
   /one-shot --yolo (task-url). A task with a PRIOR transcript (a revisit) is
   RESUMED instead (its conversation restored on the fresh slot, via resume-task).
   Note the resume answers the resume menu with "Resume from summary", which
   COMPACTS the conversation from a summary built before the re-arm, so a resumed
   agent's memory never includes the followup comment that triggered the re-arm.
   That is why finalize is gated on a live scope check: check-followup-scope.sh
   fetches the task's comments and attachments, lists every operator comment newer
   than the latest agent-run-report*.md watermark, and writes a marker; the
   require-followup-scope-on-complete.sh PreToolUse hook blocks
   update-status.sh (gid) Complete unless that marker exists and still matches
   the live newest comment. Recalled context never stands in for the fetch.
   So re-engaging a finished task is one signal: set it back to Pending and it
   continues with memory plus working resources, never a fresh session. This is the
   single re-engagement entry point. Both the fresh-spawn and the resume path route
   through spawn-test-session.sh, which pins the session's model and reasoning
   effort from the task's agent_model / agent_effort Asana fields: the selected
   agent_model option maps to a CLI model string (all 1M-context: Fable 5, Opus
   4.8, Opus 4.7, Sonnet 5, Sonnet 4.6), the agent_effort option is the CLI level directly
   (low/medium/high/xhigh/max). Unset falls back to the config defaults
   (.watcher.agent_model = Opus 4.8 1M, .watcher.agent_effort = high), so new
   tasks and follow-ups honor the same per-task overrides.
2. The run (/one-shot --yolo, a single agent turn): seven phases, status
   advanced via update-status.sh at each boundary. Planning (/asana-plan),
   Developing (/im), local verify (/build-and-test), Reviewing (/pr-create),
   Testing (CI watch + reviewer bots), Complete. The agent runs hands-off: no
   interactive prompts, no self-respawn, every wait a bounded blocking in-turn call.
3. Finalize gate: Complete is set only when every primary PR is CI-green,
   every reviewer bot is clean on HEAD, and there are zero unresolved bot review
   threads (bots matched by GraphQL __typename == "Bot", so Cursor's cursor and
   cursor[bot] logins both count).
4. Watchdog (agent-watcher/session-watchdog.js, launchd every 120s): tends
   live sessions. RC-bridge revive (only when the bridge is dead), completion sweep
   (Complete retires claude-asana-(gid) to done-asana-(gid), frees
   sim/Metro/slot, keeps claude alive for re-engagement), blocked sweep (sheds
   sim/Metro while a human is needed), GC (keep newest keep_completed_sessions /
   keep_completed_worktrees), orphan-Metro reap, idle-dirty-sim reclaim, and
   operator escalation for parked prompts or stuck sessions. It does NOT re-engage
   finished tasks: that is the watcher's job (Pending → resume), so the watchdog and
   watcher are decoupled.
5. Eval (post-hoc): /resolve-run builds an evidence manifest per run;
   /agent-eval grades process compliance and outcome honesty (A-dimensions),
   /orch-eval grades infrastructure health (O-dimensions), and /eval-run
   orchestrates a cohort.

flowchart TD
  A["Asana project (Pending tasks)"] -->|"watcher tick 120s"| B{"guardrail and cap OK?"}
  B -- no --> A
  B -- yes --> C["allocate slot: worktree + cloned sim + Metro port"]
  C --> D["spawn tmux claude-asana-GID (claude --rc --yolo /one-shot)"]
  D --> E["/one-shot 7 phases: Planning, Developing, Reviewing, Testing"]
  E --> F{"finalize-gate: CI green + bots clean + 0 unresolved threads"}
  F -- "not green" --> E
  F -- green --> G["agent_status = Complete"]
  G -->|"watchdog completion sweep"| H["retire to done-asana-GID; free sim, Metro, slot; claude kept alive"]
  H -->|"operator sets Pending (revisit resumes with memory)"| A
  H -->|"beyond keep_completed_sessions"| I["reaped"]

Loading

The hands-off contract is enforced by deterministic PreToolUse and Stop hooks
(active only when AGENT_TASK_GID is set), not merely documented:

flowchart LR
  AG["orchestrated agent (/one-shot --yolo)"]
  AG -->|"AskUserQuestion"| H1["no-interactive-prompt.sh: DENY, pick a default"]
  AG -->|"ScheduleWakeup, CronCreate, claude --resume, /loop"| H2["no-self-respawn.sh: DENY, wait in-turn"]
  AG -->|"blocked=Yes, or Complete on a wall"| H3["require-concession-validation.sh: needs validator verdict"]
  AG -->|"turn ends, not Complete or blocked"| H4["require-continuation-or-block.sh (Stop): force continue, stuck flag at K"]
  AG -->|"pr-create, Complete"| H5["require-test-evidence + finalize-gate: CI, bots, proof"]

Loading

Distribution (what syncs)

Beyond cursor skills/rules, this repo mirrors two more portable trees so a
second Mac is reproducible from a single clone + ./bootstrap.sh:

• agent-watcher/ — the autonomous agent orchestration system (Asana
  watcher daemon + worktree/iOS-sim pool helpers + watchdog). Canonical home is
  ~/.config/agent-watcher (XDG config; ~/.agents is not an established
  standard). Committed: scripts, *.js, asana-config.json, README.md,
  oom-repro/HANDOFF.md+scripts/, and credentials.example.json. Never
  committed: credentials.json (secret) and machine-local state
  (pool.json, slots.json, watchdog-state.json, *.state, *.log,
  oom-repro/forensics, oom-repro/logs).
• memory-shared/ + bin/link-shared-memory.sh — cross-cutting Claude
  memory notes that should surface regardless of working directory. Canonical
  home ~/.claude/memory-shared; link-shared-memory.sh symlinks them into the
  per-project auto-memory dirs (~/.claude/projects/<project>/memory/) and
  maintains a managed block in each MEMORY.md. Claude auto-memory itself is
  machine-local (per Anthropic docs) and is intentionally NOT synced — only the
  shared store is. The only officially global Claude file is ~/.claude/CLAUDE.md
  (generated here from always-apply rules).

/convention-sync keeps all of the above in sync (home → repo); bootstrap.sh
does the reverse (repo → home) on a new machine.

Architecture

edge-dev-agents/
├── README.md          # Synced copy of ~/.cursor/README.md
└── .cursor/
    ├── skills/        # Slash skills (*/SKILL.md) + companion scripts
    ├── scripts/       # Shared portability and dashboard scripts
    ├── commands/      # Minimal command wrappers
    └── rules/         # Coding and workflow standards (.mdc)

Separation of concerns:

• Skills (SKILL.md) define workflows, rules, and step ordering.
• Companion scripts (.sh, .js) handle deterministic work like git,
  GitHub, Asana, and JSON processing.
• Rules (.mdc) provide persistent guidance that gets loaded by context.
• Repo docs describe the system and how the distribution copy fits
  together.

All GitHub API work uses gh CLI. Deterministic git operations should live in
scripts, not be re-described independently across skills.

Skills (Slash Skills)

Core Implementation

Skill	Description
/im	Implement an Asana task or ad-hoc feature/fix with clean, structured commits
/one-shot	Legacy-style task-to-PR flow built from planning, implementation, and PR creation
/pr-create	Create a PR from the current branch with repo-aligned title and body
/dep-pr	Create dependent Asana tasks and downstream PR work in another repo
/changelog	Update CHANGELOG entries using repo conventions

Planning and Context

Skill	Description
/asana-plan	Build an implementation plan from Asana or ad-hoc requirements
/task-review	Fetch and summarize Asana task context
/q	Answer questions before taking action

Review and Landing

Skill	Description
/pr-review	Review a PR against coding and review standards
/pr-address	Address PR feedback with fixup commits, replies, and optional autosquash
/pr-land	Land approved PRs, including prepare, merge, publish, GUI dep updates, staging cherry-picks, and Asana updates
/staging-cherry-pick	Cherry-pick landed staging-targeted commits onto the staging branch

Asana and Utility

Skill	Description
/asana-task-update	Generic Asana mutations such as attach PR, assign, unassign, and status updates
/standup	Generate daily standup notes from Asana and GitHub activity
/chat-audit	Audit Cursor chat sessions for waste, drift, and workflow gaps
/convention-sync	Sync ~/.cursor/ with this repo, mirror the local README to repo root, and update PR descriptions from README.md
/author	Create, revise, and debug skills, scripts, and rules
/fix-eslint	Apply documented fixes for recurring Edge React GUI ESLint warnings

Companion Scripts

PR Operations

Script	What it does	API
pr-create.sh	Create a PR for the current branch with standardized body formatting	gh pr create
pr-address.sh	Fetch unresolved feedback, reply, resolve threads, and mark items addressed	gh api REST + GraphQL
github-pr-review.sh	Fetch PR context and submit reviews	gh pr view + gh api
github-pr-activity.sh	Gather recent PR activity and CI context for standups	gh api graphql

PR Landing Pipeline (/pr-land)

Script	Phase	What it does
pr-land-discover.sh	Discovery	Find relevant PRs and approval state
pr-land-comments.sh	Comment check	Detect unresolved inline, review-body, and top-level comments
git-branch-ops.sh	Shared git ops	Run deterministic autosquash and push operations for multiple skills
pr-land-prepare.sh	Prepare	Autosquash, rebase, detect conflicts, and verify
pr-land-merge.sh	Merge	Rebase again, verify, and merge sequentially
pr-land-publish.sh	Publish	Version bump, changelog update, commit, and tag
pr-land-extract-asana-task.sh	Asana extraction	Pull task IDs from landed PR metadata
upgrade-dep.sh	GUI deps	Bump one package on the current branch, run yarn/prepare, commit lockfile updates. Caller must sync develop first.
staging-cherry-pick.sh	Staging	Cherry-pick staging-qualified commits onto staging
verify-repo.sh	Verification	Run changelog and code verification

Build, Lint, and Analysis

Script	What it does
lint-commit.sh	Run lint-assisted commits and autosquash fixups through the shared git helper
lint-warnings.sh	Auto-fix and summarize remaining TypeScript/ESLint warnings
install-deps.sh	Install dependencies and run project prepare steps
cursor-chat-extract.js	Parse Cursor chat exports into structured summaries

Asana and Portability

Script	What it does
asana-get-context.sh	Fetch task details, comments, subtasks, and attachments
asana-task-update.sh	Apply reusable Asana task mutations
asana-create-dep-task.sh	Create dependent Asana tasks
asana-whoami.sh	Return current Asana identity
convention-sync.sh	Sync ~/.cursor/ and edge-dev-agents in either direction, mirroring ~/.cursor/README.md to repo root README.md
generate-claude-md.sh	Regenerate ~/.claude/CLAUDE.md from always-apply rules
tool-sync.sh	Sync Cursor assets into OpenCode and Claude-compatible formats
port-to-opencode.sh	Convert Cursor files into OpenCode-friendly mirrors

Shared Modules

Module	Purpose
edge-repo.js	Shared repo resolution, git wrappers, conflict detection, verification, and gh helpers for the pr-land pipeline

Rules (.mdc files)

Rule	Purpose
workflow-halt-on-error.mdc	Stop skill execution on script failures and fix the workflow definition first
load-standards-by-filetype.mdc	Load language standards before editing or investigating file-specific issues
answer-questions-first.mdc	Answer user questions before editing or mutating state
no-format-lint.mdc	Avoid manual formatting and formatting-only lint work
typescript-standards.mdc	TypeScript and React editing standards
review-standards.mdc	Review-specific bug patterns and conventions
eslint-warnings.mdc	Documented fixes for recurring ESLint warnings
after_each_chat.mdc	Post-chat automation rule used in the local workflow

Design Principles

1. Scripts over duplicated reasoning. Deterministic git, API, and parsing
   work belongs in shared scripts.
2. gh over raw GitHub HTTP calls. Use the authenticated CLI for GitHub
   workflows.
3. Shared helpers over drift. Reusable mechanics like autosquash and push
   should live in one script and be consumed by multiple skills.
4. Rules before edits. Load the relevant standards before editing code or
   evaluating lint/type failures.
5. Workflow fixes before workarounds. If a skill is wrong, fix the skill or
   script instead of patching around it in an ad-hoc way.
6. Canonical local copy. ~/.cursor/ is the working source of truth;
   edge-dev-agents is the distribution and review copy.

[cursor]

Stale comment

Identified several concrete security issues in newly added workflow scripts/rules. Leaving inline comments on the affected lines only.

  

_{Sent by Cursor Security Review Agent: Security Reviewer}

[cursor]

🔒 Agentic Security Review
Severity: HIGH
<headRef> is inserted unquoted into a shell command (git fetch ... && git checkout ...) even though PR branch names are attacker-controlled input.

Impact: A crafted branch name containing shell metacharacters (for example command substitution) can execute arbitrary commands in the review agent environment.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
<BRANCH> is interpolated directly into git rev-parse origin/<BRANCH> in a shell command path that derives branch names from PR metadata.

Impact: Malicious branch names can trigger command injection during bugbot workflow execution, leading to arbitrary code execution in automation context.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
User/task-controlled content is embedded directly into inline Python source via triple-quoted interpolation ('''$TASK_NOTES''' / '''$TASK_NAME''') in python3 -c calls.

Impact: An input containing ''' can break out of the string literal and inject executable Python statements, resulting in code execution in the automation runtime.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
Attachment filename name is treated as a trusted path segment via os.path.join(download_dir, name) before writing downloaded content.

Impact: Filenames containing traversal segments (for example ../) can write files outside the intended task download directory, enabling workspace boundary bypass and arbitrary file overwrite in reachable paths.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
[Privacy Guard] This rule mandates forwarding the complete chat response every turn to an external Telegram sink without user confirmation or selective minimization.

Impact: Sensitive content (credentials, proprietary code, internal data) can be exfiltrated outside the expected trust boundary by policy.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
[Privacy Guard] The script stages and commits env.json updates after accepting raw secret values as direct inputs.

Impact: Secret material can become durable plaintext in git history and propagate through clones/backups, creating long-lived credential exposure risk.

[cursor]

Stale comment

Net-new security findings on current head after deduplication against prior automation comments and threads.

  

_{Sent by Cursor Security Review Agent: Security Reviewer}

[cursor]

🔒 Agentic Security Review
Severity: HIGH
repo is interpolated into a shell command string passed to execSync (git clone git@github.com:EdgeApp/${repo}.git ...) without validation or argument separation.

Impact: A crafted repo value can trigger shell command injection and arbitrary code execution in the automation environment.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
fetchPrBody() builds a shell command string with untrusted repo (gh api "repos/EdgeApp/${repo}/pulls/${prNumber}" ...) and executes it via execSync.

Impact: Malicious input can exploit shell expansion and execute arbitrary commands while extracting PR metadata.

[cursor]

🔒 Agentic Security Review
Severity: MEDIUM
The secret value is passed as a positional CLI argument ("$VALUE") into ssh ... bash -s -- ..., which exposes it in process arguments and often shell history.

Impact: Sensitive credentials can be disclosed to local observers or process-monitoring tooling on the calling host.

[cursor]

Stale comment

Net-new security findings on current head after module triage, severity filtering, and duplicate suppression against existing automation threads/comments.

  

_{Sent by Cursor Security Review Agent: Security Reviewer}

[cursor]

🔒 Agentic Security Review
Severity: HIGH
checkNpmPublished builds an execSync shell string using packageName and version from package.json (npm view ${packageName}@${version} version) without argument-safe execution.

Impact: A crafted package name/version can trigger command injection and arbitrary code execution in automation environments running this publish flow.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
verify-repo.sh builds an eslint command string from git-derived filenames and executes it via execSync; wrapping paths in quotes is not sufficient shell escaping.

Impact: A malicious filename in a branch can break command quoting and execute arbitrary shell commands during repository verification.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
runVerification/related helpers interpolate derived repo/path values into execSync shell strings instead of passing argument arrays.

Impact: If attacker-influenced repo/path metadata reaches these call sites, command injection can occur during pr-land preparation/verification operations.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
The standup workflow templates externally sourced task/PR text directly into markdown and then requires uploading the rendered output to a persistent GitHub gist, without a mandatory scrub/redaction step.

Impact: Sensitive code-adjacent content (paths, snippets, internal details) from source systems can be durably exfiltrated to an external artifact.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
The HUDL flow maps GitHub-derived PR text fields into a generated markdown report and uploads it to a gist, but does not require sanitization/minimization of potentially sensitive content.

Impact: Code-related or sensitive operational details can leak into externally stored summaries.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
sync_file copies directly to destination paths without rejecting symlink destinations or enforcing canonical containment.

Impact: A pre-positioned symlink under the sync tree can redirect writes to unintended files, enabling arbitrary file overwrite as the current user.

[cursor]

🔒 Agentic Security Review
Severity: HIGH
Cleanup uses rm -rf on globbed skill directories without symlink validation.

Impact: A symlinked directory entry can cause deletion outside the intended sync root, leading to destructive data loss in attacker-chosen paths.

[cursor]

Stale comment

[cursor]

🔒 Agentic Security Review
Severity: MEDIUM
err.message from execSync is rethrown verbatim here. In Node, that message includes the failed command string, which in this call contains Authorization: Bearer ${TOKEN}.

Impact: if this error is logged or surfaced, the Asana PAT can be exposed to logs/observers and used for API impersonation.

 

^{Reviewed by Cursor Security Reviewer for commit 50180c1. Configure here.}

[cursor]

Stale comment

[cursor]

🔒 Agentic Security Review
Severity: HIGH
This watcher launches unattended --yolo sessions and then auto-accepts the permissions-bypass dialog before injecting /one-shot --yolo from Asana task content.

Impact: anyone who can move/create tasks in the watched project can trigger autonomous privileged command execution on the runner without a human confirmation boundary.

 

^{Reviewed by Cursor Security Reviewer for commit 6f8419f. Configure here.}

[cursor]

Stale comment

Security review rerun on current head completed.

Net-new finding identified (not duplicate of existing automation threads):

• MEDIUM: Unbounded attachment processing in .cursor/skills/asana-get-context.sh can enable resource-exhaustion (large ZIP/PDF attachments are downloaded, extracted, and converted without hard limits), risking automation availability.

Inline anchoring could not be posted in this run because GitHub rejected diff-position operations on this PR due diff size (PullRequest.diff too_large).

  

_{Sent by Cursor Security Agent: Security Reviewer}