Complete agent-assisted development workflow for Edge repositories: slash skills, companion scripts, coding standards, an autonomous Asana-to-PR orchestration system with deterministic enforcement hooks, a post-hoc eval suite, and meta-tooling for maintaining the workflow itself.

The distributable content lives under .cursor/. This repo is the versioned home for those skills, rules, scripts, and docs, plus the portable orchestration trees a second machine bootstraps from.

The .cursor/ path is historical, not a commitment: the system is built to sync across agent harnesses, not just Cursor. Claude Code is the primary consumer today (~/.claude/skills symlinks to the canonical tree, ~/.claude/CLAUDE.md is generated from the always-apply rules, and the enforcement hooks are Claude Code hooks); OpenCode gets generated mirrors via tool-sync.sh. Other harnesses are untested, but the content is plain markdown and shell, so most of it should carry in theory; the hook layer is the Claude-specific part.

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.

Fresh machine (one command): clone this repo and run the bootstrap. It installs everything (cursor skills/rules, the orchestration system, hook registrations, workflows, 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
• claude CLI (the orchestration spawns Claude Code sessions; the prose judge also shells out to it)

• Orchestration & memory
• Enforcement hooks
• Prose standards & enforcement
• Testing infrastructure
• Evals
• Distribution (what syncs)
• Architecture
• Skills
• Companion scripts
• Rules
• Design principles

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.

At a glance:

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"]

agent-watcher/asana-watcher.js, launchd every 120s, polls the project for agent_status = Pending.

• Tick gate. The tick is skipped when a resource guardrail trips (1-minute load over max_load_avg, free RAM under min_free_ram_gb) or the concurrency cap is full (max_concurrent, default 4).
• Provisioning. Each pickable task gets a slot: a git worktree, a cloned simulator from the pool, and a Metro port. Before recloning the pool the watcher runs refresh-master-build.sh: if develop advanced AND its native side (ios/Podfile.lock) changed, the master sim is rebuilt from develop and the pool recloned, so runs test against a current build. A JS-only advance skips the rebuild (clones bundle JS live from Metro). The check is a cheap git fetch plus SHA compare; a build failure is non-fatal (provisioning continues on the last-good master).
• Fresh vs revisit. A never-run task spawns fresh: agent_status = Planning, a tmux session claude-asana-(gid) running /one-shot --yolo (task-url). A task with a prior transcript is RESUMED instead, on a fresh slot, via resume-task. Re-engaging a finished task is therefore one signal: set it back to Pending.
• Resume memory, and why finalize is gated. A resumed session's memory is never trusted for scope decisions: long runs auto-compact mid-flight, and the summary a compaction runs on predates whatever re-armed the task, so "the newest comment is my own Complete note" recalled from context is exactly the stale claim that has re-Completed past real followups. (Resumes themselves answer the resume menu with a FULL resume; the lossier summary-resume tier is retired, and a transcript past the degradation threshold fresh-spawns from artifacts instead.) The counter is mechanical: check-followup-scope.sh live-fetches comments and attachments, lists every operator comment newer than the latest agent-run-report*.md watermark, diffs the task's fields against the previous segment's snapshot, fetches GitHub-side scope across parent AND subtask-attached PRs (unresolved review threads, reviewer-bot completeness on owned ready HEADs, unanswered top-level review bodies and PR comments), and writes a marker; the require-followup-scope-on-complete.sh hook blocks Complete unless that marker exists, still matches the live newest comment, records zero blocking threads and bot gaps, and shows the report attachment as the newest agent-authored event (a 🥋-marked agent comment after the report means the watermark is stale and the report must be re-attached). Recalled context never stands in for the fetch.
• Per-task model and effort. Both spawn and resume route through spawn-test-session.sh, which pins the session model and reasoning effort from the task's agent_model / agent_effort Asana fields (models all 1M-context; effort low through max). Unset falls back to config defaults (currently .watcher.agent_model = Opus 5 1M, .watcher.agent_effort = high).
• Version stamp. Every spawn and resume segment records which orch version governs it: stamp-orch-version.sh appends content digests of the governing trees (skills, rules, watcher, hooks, settings hooks) plus repo head, CLI version, model, and effort to versions/(gid).jsonl, and exports AGENT_ORCH_VERSION for the run report. Evals slice findings by the version actually in force per segment.

/one-shot --yolo, a single agent turn: seven phases with agent_status advanced via update-status.sh at each boundary. Planning (/asana-plan), Developing (/im), Testing (/build-and-test, on-sim verification), Reviewing (/pr-create through the CI + reviewer-bot watch), Complete. Status LEADS the work: the phase status is set when that kind of work starts, never as a side effect of a terminal action. The agent runs hands-off: no interactive prompts, no self-respawn, every wait a bounded blocking in-turn call. The full decision graph, including followup, concession, landing, and cheese branches, is in the /one-shot decision flowchart below.

Complete requires the finalize gate: every primary PR CI-green, every reviewer bot run-and-concluded clean on the ready HEAD, zero unresolved review threads. At green, landability is decided FIRST: a PR with a human APPROVED review (or the task's Force Land field) lands via /pr-land and the Build field is ignored. Only a non-landable green run kicks a cheese build, pinning the task's own unpublished dep PRs when the deliverable requires them.

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 = blocked COMPLETION (Complete --blocked yes): retires via the completion sweep; the shed-on-block branch is a legacy net for stray mid-run blocks
• GC: keep newest keep_completed_sessions / keep_completed_worktrees (currently 20 / 5)
• 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 resumes), so watchdog and watcher stay decoupled.

Every agent is an INTERACTIVE claude --rc process in a detached tmux session, never a headless claude -p. The pane is part of the machinery, not just a viewport.

• Naming is state. claude-asana-<gid> is a live run; the watchdog's completion sweep renames it to done-asana-<gid> at retirement (resources freed, claude kept alive); chat-<slug> sessions are discussion forks of past transcripts (resume-agent.sh --chat: talk to a finished run from anywhere, no slot, original conversation untouched); long-lived operator anchors keep their own names. Hooks and the watchdog read the name to decide context: the 🥋 authorship boundary is "pane name is exactly claude-asana-<gid>", so a retired session's text counts as operator instruction.
• Spawn. spawn-test-session.sh writes a wrapper script (slot env baked in: worktree cwd, AGENT_SIM_UDID, AGENT_METRO_PORT, task gid, model and effort flags) and launches it with tmux new-session -d. When claude exits the wrapper prints the exit time and drops to a shell, so the pane and its scrollback survive for diagnosis.
• Resume poking. claude --resume on a prior transcript shows an interactive menu that would wedge a hands-off session, so the spawner polls the pane and answers it with send-keys (Down+Enter: FULL resume; the summary tier is retired). This is the general pattern: the session is driven through its terminal exactly as an operator would drive it, which means every interactive surface the CLI grows is automatable without new APIs.
• Remote-control keepalive. Each session arms a remote-control bridge at startup, so the operator can steer any run from the desktop or phone app. Bridge liveness is read from the pane footer (the /rc token, or the "Remote Control active" line on older builds). The watchdog revives ONLY a verified-dead bridge on a verified-alive claude: kill the pane's process, confirm death, relaunch in place with --remote-control <name> --resume <live-id> and the preserved flags, under a per-session cooldown. A half-open bridge is left for the operator to reconnect, and the revive never adds a second process (the count goes 1 to 0 to 1).
• No self-respawn. A session never kills or relaunches its own pane; resume-task.sh and resume-agent.sh are watcher/operator tools and refuse to run from inside their target. The no-self-respawn.sh hook enforces the agent side.
• The host must not idle-sleep. All of this dies with the machine, so the box runs a keep-awake LaunchAgent (machine-local, not synced; an idle-sleep default once killed every bridge in the fleet after hours of quiet).

Every run ends by attaching ONE structured run report to the Asana task (agent-run-report-NN-<slug>.md). The report is more than documentation: its attachment timestamp is the followup-scope WATERMARK. Comments newer than the newest report are undischarged scope for the next run, so every comment a run owes posts BEFORE the attach, and a comment that must land later forces a re-attach so the watermark is last again. The attach boundary is gated (see require-clean-run-report.sh below): template form, prose lint, traceability frontmatter, one report doc per segment, and resolvable GitHub citations are all checked mechanically.

Post-hoc, per run or per cohort. See Evals.

The full decision flow of an orchestrated /one-shot --yolo run, including the followup, concession, landing, and cheese branches. Rule ids in brackets name the governing one-shot/cheese/build-and-test rules.

flowchart TD
  START["/one-shot --yolo task-url"] --> REFIRE{"re-fire? task already
  ran in this session"}
  REFIRE -- "no (fresh or resumed-new)" --> PLAN
  REFIRE -- "yes, still mid-run" --> CONT["continue current phase
  [ignore-refired-one-shot]"]
  REFIRE -- "yes, previously FINISHED" --> SCOPE["LIVE scope check:
  check-followup-scope.sh
  (never from memory)"]
  SCOPE -- "operator asks newer
  than report watermark" --> FOLLOWUP["deliver the new scope
  [followup-scope-is-the-deliverable]"]
  FOLLOWUP --> DEV
  SCOPE -- "0 newer comments" --> GATE

  PLAN["Planning: /asana-plan, plan doc
  (confirmation waived in yolo)"] --> DEV
  DEV["Developing: /im contract
  (lint-warnings, lint-commit,
  clean history)"] --> TEST
  TEST["Testing: slot-preflight -> obey PLAN/INVOKE
  -> build -> drive the REAL action on sim
  (log-attempt every drive, pixel-verify proofs)
  [preflight-before-build-decisions]"] --> WALL{"hit a wall?"}
  WALL -- no --> PR
  WALL -- yes --> ATTEMPT["log the attempt
  (failed:/blocked:/loss:)"] --> VALID{"concession-validator
  verdict [yolo-true-blockers]"}
  VALID -- "legitimate: true" --> BLOCKED["blocked completion:
  Complete --blocked yes (one-line
  comment, report attached as normal)"]
  VALID -- "legitimate: false" --> RETRY["do what_to_try, continue"] --> TEST

  PR["Reviewing: /pr-create (verify green, clean tree,
  template, evidence; Asana attach; multi-repo
  subtasks; draft dep PRs excluded from gate)"] --> WATCH
  WATCH["watch-pr bounded poll; bots must be
  SUCCESS (NEUTRAL = findings -> /bugbot);
  fixes via amend + force-with-lease"] --> GATE
  GATE{"finalize-gate green:
  CI + every bot clean +
  0 unresolved bot threads
  on EVERY primary PR"}
  GATE -- "not green" --> WATCH
  GATE -- green --> LAND{"landable? human APPROVED
  review (any point in history)
  OR Force Land field
  [land-on-approval]"}

  LAND -- yes --> PRLAND["/pr-land with TASK URL
  (dep ordering: merge dep -> publish ->
  bump -> gui; npm OTP parks at
  operator boundary). Build field IGNORED
  -> NO cheese push"] --> REPORT
  LAND -- no --> BUILDF{"Build field?
  [cheese-build-on-green]"}
  BUILDF -- none --> REPORT
  BUILDF -- staging --> REPORT
  BUILDF -- "cheese (feta/gouda/...)" --> PINQ{"gui deliverable requires
  unpublished dep PRs?"}
  PINQ -- yes --> PINNED["/cheese --pin each dep
  at ITS PR head
  [cheese:orch-pins-required]"] --> REPORT
  PINQ -- no --> POINTER["/cheese pointer reset
  test-branch -> PR head"] --> REPORT

  REPORT["RE-READ report template -> write report
  -> require-clean-run-report lint at attach
  -> set tested field from THIS run's evidence"] --> COMPLETE
  COMPLETE["agent_status = Complete
  (gated: fresh followup-scope check
  required by hook)"]

Status discipline throughout: the phase status is set when that KIND of work starts (status leads the work), never as a side effect of a terminal action.

The hands-off contract and the quality bars are enforced by deterministic Claude Code hooks, not merely documented. Registrations live in ~/.claude/settings.json and are distributed as the claude-settings/hooks.json projection (see Distribution); the scripts live in agent-watcher/hooks/. Hook BODIES are re-read from disk on every fire, so a script fix reaches every live session immediately; only registration changes need a session restart or settings reload.

Most gates no-op unless AGENT_TASK_GID is set (orchestrated sessions only). The prose gates and the Asana authorship marker run everywhere, because interactive sessions post PRs and Slack messages too.

The dominant compliance failure across audited runs is cross-file-read skipping: rules INSIDE the prompt a session holds are followed almost universally, while obligations that require reading ANOTHER skill file mid-flow get skipped or satisfied with a partial slice. The enforcement stack therefore never trusts "go read X". A contract reaches a run's context in exactly one of three ways, all of which stamp the same per-segment marker, and the marker is what the read-gate checks before letting any companion script execute:

1. Injected at the boundary — every fresh segment gets the planning contracts (asana-plan + task-review) pushed in whole by inject-run-context.sh.
2. Read whole by the agent — strict marking: a full Read (no offset/limit), a bare cat, or a Skill-tool invocation. A sed slice or cat | head earns nothing, because partial credit would suppress delivery.
3. Delivered by the gate itself — a script call with no marker is DENIED, and the deny message IS the full SKILL.md body (marker written at delivery). The uneducated call never executes; the retry arrives with the complete contract. This is one round-trip cheaper than the old block→read→retry loop.

Markers are evidence about what is IN CONTEXT, so they expire when the context does: startup/resume (a new segment) kills all of them plus the ingestion marker; compact/clear kills the read markers, because compaction keeps a paraphrase and drops the rules; headless claude -p children (the no-slop judge) inherit the gid but are ignored entirely. Re-arming is cheap by design — the gate re-delivers lazily, only for skills the run actually touches again.

flowchart TB
    SPAWN["segment boundary:<br/>planning contracts injected whole"]
    READ["agent reads it whole:<br/>full Read / bare cat / Skill tool<br/>(sed slices earn nothing)"]
    GATE["gate denies, message = full SKILL.md<br/>(deny-with-body)"]
    M[("per-segment marker<br/>/tmp/agent-skill-read-&lt;gid&gt;-&lt;skill&gt;")]
    CALL{"companion-script call:<br/>owning skill's marker present?"}
    RUN["script executes"]
    PTR["deny with read-in-full pointer,<br/>no marker until the full read"]
    EXP["expiry: startup/resume → all markers;<br/>compact/clear → read markers;<br/>claude -p children ignored"]
    SPAWN --> M
    READ --> M
    GATE --> M
    M -.attests.-> CALL
    CALL -->|yes| RUN
    CALL -->|"no, body ≤ 50KB"| GATE
    GATE -->|retry| CALL
    CALL -->|"no, body > 50KB (one-shot, pr-land)"| PTR
    EXP -.expires.-> M

The gate closes one half of the substitution failure class (a sanctioned script run contract-blind); the raw-API blocks (block-raw-asana-api.sh, block-raw-gh-writes.sh, block-raw-thread-resolve.sh) close the other half (an improvised replacement for the script), and the status gates check outcome evidence at phase boundaries regardless of how the work was done.

require-block-validation.sh is an unregistered legacy kept for history; the concession gate replaced it.

All outward prose (PR bodies and comments, commit messages, Asana text, run reports, Slack, docs that leave the team, and chat replies) follows the /no-slop rules: banned vocabulary, no em dashes, no courtesy enders, no structure announcements, no count-announcement openers, plain copulas. The full pattern list is published with this repo, so review comments can cite it instead of private config paths.

Enforcement is layered, one shared implementation per rule class (no-slop/scripts/no-slop-lint.sh is the single lint every boundary calls):

• Mechanical tier (regex-decidable): em dashes, banned vocabulary, Claude session links, decorative loudness, count-announcement shapes including trailing count-appositions. Exit 1 on HARD findings.
• Semantic tier (--semantic): a haiku judge (no-slop-judge.sh) for the rules regexes cannot decide: courtesy enders, forward references, validation preambles. A wide regex net nominates candidate sentences, one batched claude -p call rules on them, verdicts cache by sentence hash, and every infra failure fails open. Calibrated on violation and look-alike corpora before being made blocking.
• Fragment mode (--fragment): position-independent checks only, for Edit fragments and heredoc command text where sentence-shape checks would false-positive.

Where each tier runs:

The file-write hook exists because posted prose travels as --body-file/$(cat file) per the file-over-args convention, so a command-string hook literally cannot see it; the bytes are visible when the file is written and when the poster script assembles the final body, and both points are covered. Known residuals: raw gh api posting that bypasses the scripts is unlinted, and Asana comments get the authorship marker but no prose lint today.

/build-and-test owns verification. For edge-react-gui and its dependency repos, verification means driving the REAL user action on a booted simulator (maestro), not just green unit tests: a dep change is not done until it runs in the app.

• Sim slots. Each orchestrated run gets a cloned simulator from a pool, its own Metro port, and a worktree. Pool management, cloning, and restoration live in agent-watcher/ (ensure-sim-pool.sh, clone-ios-sim.sh, restore-sim-app-container.sh).
• The sim-testing playbook (build-and-test/references/sim-testing-playbook.md) carries the working knowledge runs need: funded test accounts and rosters, per-provider drive recipes, known gotchas with their continue-workarounds, the corePlugins working-set trim (filter to the assets the task needs, with a funding carve-out: filtering is a convenience, never a constraint), and the fallback gates. The drive gate blocks the first maestro drive until it is read.
• Flow library (build-and-test/maestro/common/): parameterized, reusable maestro flows (login, wallet find, send-to-address, swap pair selection, ramp region/fiat, throwaway-account lifecycle, slider confirm). Task-specific flows an agent writes mid-run stay local and are excluded from sync; recurring sequences get promoted into the library through eval curation.
• Attempt log. Every value-moving action and drive logs through log-attempt.sh with a truthful result; the log is the ground truth evals and the concession gate read. Proof screenshots are pixel-verified, and hack-forced frames must carry the 🪓 marker.
• Cheese builds (/cheese): push a test-* branch so testers get a build of the PR head; the orchestration pins unpublished dep PRs when the deliverable needs them. The task's Build field routes this at finalize.
• Tested field. Each run sets the task's tested multi-select (iOS Sim, Android Sim, Android Device, Unit Tests, Untested) from that run's own evidence via set-tested.sh.

The eval suite grades finished runs against explicit rubrics, with every BAD finding carrying a citation an auditor can open.

• /resolve-run builds the evidence manifest per run: transcript path, PRs, Asana state, attempt log, friction block (hook blocks, tool errors, compactions), version stamps, release receipt.
• /agent-eval grades process compliance and outcome honesty against the agent-behavior rubric (dimensions A1-A32: status hygiene, completion honesty, report discipline, testing depth, tested-field accuracy, deferral validity, and more).
• /orch-eval grades infrastructure health (fork storms, memory pressure, liveness, resource accounting, gate coverage) against the O-dims.
• /eval-run orchestrates cohorts through a background multi-agent workflow. Two eval types, never conflated: the default REPORT-EVAL grades what a run claimed (report vs live GitHub/Asana APIs; transcripts never opened; ceiling REPORT_CLEAN), and the heavier TRANSCRIPT-EVAL (the only path to GOLD) runs the full process pass plus orch-eval on named or escalated runs. Every BAD is adversarially re-verified before it lands in a report. Cohort reports end in a typed Actions checklist (re-runs, field corrections, infra fixes, playbook and flow promotions) that the operator approves row by row; nothing executes unapproved.
• Coverage ledger (eval-coverage.sh): which runs have been evaluated under which lens, and which are STALE (new segments since their last eval) or NEVER-evaluated. Default cohort scope comes from this queue, not date guessing.
• Rubric drift (rubric-drift.sh): every rubric row anchors to the rule and script content it grades against, by content digest. A changed anchor means dimensions may grade against stale expectations; CHANGED/UNCOVERED findings block until reconciled, and rubric rows carry dated era notes so runs are graded against the rules in force when they ran.
• Friction scorecard (friction-scorecard.sh): a zero-LLM trend table between cohorts (hook blocks, tool errors, builds, compactions, drives, attempt walls) straight from manifests.

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

• agent-watcher/: the autonomous orchestration system (Asana watcher daemon, session watchdog, worktree/iOS-sim pool helpers, the enforcement hooks, status/attempt/tested scripts). Canonical home is ~/.config/agent-watcher. Committed: scripts, *.js, asana-config.json, docs, and credentials.example.json. Never committed: credentials.json (secret) and machine-local state (pool.json, slots.json, watchdog-state.json, *.state, *.log, forensics).
• claude-settings/hooks.json: a PROJECTION of the .hooks key of ~/.claude/settings.json. Hook scripts ship in the agent-watcher tree; without this projection they would be installed but never fire. User-to-repo sync exports the key; repo-to-user and bootstrap.sh merge it back replacing ONLY .hooks, so model/theme and other machine-local settings stay put, and an unconfigured machine can never blank the canonical registrations.
• claude-workflows/: multi-agent Workflow scripts installed to ~/.claude/workflows (currently code-review-sonnet.js, the deep multi-agent PR review harness /pr-review launches).
• memory-shared/ + bin/link-shared-memory.sh: cross-cutting Claude memory notes that should surface regardless of working directory. Canonical home ~/.claude/memory-shared; the link script symlinks them into each per-project auto-memory dir and maintains a managed block in each MEMORY.md. Claude auto-memory itself is machine-local and intentionally NOT synced. The only officially global Claude file is ~/.claude/CLAUDE.md, generated here from always-apply rules.
• .cursor/.syncignore: permanent sync exclusions, read from the REPO copy so every machine honors the same list. Currently: WIP commands, task-specific maestro flows (dev artifacts, not conventions), and the third-party banana image-generation skill (local-only by request).

/convention-sync keeps all of the above in sync (home to repo) and hard-blocks staging when the remote is ahead, the branch is wrong, or the sync would delete or revert canonical files authored elsewhere (the fix is a repo-to-user pass first). bootstrap.sh does the reverse (repo to home) on a new machine.

The repo's remote side is plain git (normal pull/push on the checkout). The sync machinery exists for the other hop, home to checkout, and the honest rationale splits into structural reasons and historical ones:

• The canonical "tree" is not one tree, and not all files (structural). It spans ~/.cursor, ~/.config/agent-watcher, ~/.claude/memory-shared, and the .hooks KEY inside ~/.claude/settings.json, whose sibling keys (model, theme) are machine-local. Git versions whole files; the settings projection needs a key-level merge step under any design, and no checkout layout absorbs it.
• Both machines operate unattended (structural). The home tree has concurrent uncoordinated writers: anchor sessions editing skills, agent runs appending to skill references (the throwaway-account registry rows are written by runs mid-task), eval tooling rewriting rubric-drift.lock.json. A checkout of home would be perpetually dirty, and a pull that conflicts needs a human at the keyboard that these boxes do not have. The sync's content-hash staleness blocks and mtime skippedNewer protection are cruder than git merge but never require interactive resolution; the prescribed recovery (repo-to-user pass, then re-push) is a command, not a conflict editor.
• Secrets are NOT a real justification. credentials.json and state files are kept out by hardcoded rsync excludes, but a .gitignore would do the same job in a checkout model. The excludes are a gitignore in different clothing.
• The deletion guards compensate for rsync, not for git. Mirror-style sync from a stale machine would delete files it never had; git pull/push ordering prevents that class natively. Those guards are a cost of this design, not a benefit over the alternative.
• Path dependence (historical). ~/.cursor grew as a live config dir first; the repo came later as a distribution copy, and nothing has forced the relocation cost since: a checkout-plus-symlinks redesign means touching every launchd plist, hook registration, and absolute path in scripts, and it still keeps a merge step for the settings projection.

Net: the settings-key projection and unattended conflict handling are why the scripts stay; the file-copying part is the replaceable bit if the relocation cost is ever paid.

edge-dev-agents/
├── README.md          # Synced copy of ~/.cursor/README.md
├── bootstrap.sh       # Fresh-machine installer (repo -> home)
├── agent-watcher/     # Orchestration system incl. hooks/ (-> ~/.config/agent-watcher)
├── claude-settings/   # hooks.json registration projection (-> ~/.claude/settings.json .hooks)
├── claude-workflows/  # Workflow scripts (-> ~/.claude/workflows)
├── memory-shared/     # Shared Claude memory notes (-> ~/.claude/memory-shared)
├── bin/               # link-shared-memory.sh
└── .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.
• Hooks enforce the contracts deterministically at tool-call time.
• 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.

The banana image-generation skill exists locally but is excluded from sync (third-party, local-only by request).

Scripts live beside the skill that owns them (<skill>/scripts/); shared scripts live at skills/ top level. The ones most worth knowing:

1. Scripts over duplicated reasoning. Deterministic git, API, and parsing work belongs in shared scripts.
2. Enforcement over prose. A rule that matters gets a deterministic gate (hook, script exit code, lint) at the boundary where violations ship; documentation alone does not survive compaction or a skipped file read.
3. One shared implementation per rule class. The prose lint, the commit path, the status write, the trigger-precision helper: every boundary calls the shared implementation, so there is no per-surface copy to drift.
4. gh over raw GitHub HTTP calls. Use the authenticated CLI.
5. Rules before edits. Load the relevant standards before editing code or evaluating lint/type failures.
6. Workflow fixes before workarounds. If a skill is wrong, fix the skill or script instead of patching around it.
7. Canonical local copy. ~/.cursor/ is the working source of truth; edge-dev-agents is the distribution and review copy.
8. Evals close the loop. Runs are graded against anchored rubrics, findings become gates, and rubric era notes keep old runs graded by the rules in force when they ran.
9. Interactive sessions over headless. Every agent runs as an interactive claude in tmux, never claude -p. The pane is an interface: the operator can attach or remote-control any run mid-flight and steer it by typing; the watchdog reads it (bridge footer, parked prompts, menus) and drives it with send-keys; a run survives watcher restarts and stays alive after Complete for followups with full context. It also future-proofs billing: provider terms have singled out headless/programmatic usage for separate metering (announced, so far unenforced), and interactive sessions stay on the plan surface either way.