Skip to content

t1455: add non-code routine execution guidance and helper #4251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 2 commits into from
Mar 12, 2026
Merged

t1455: add non-code routine execution guidance and helper #4251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8133e6b
feat: add scheduled ops routine workflow guidance
marcusquinn Mar 12, 2026
c2bb03f
fix: address routine workflow review feedback
marcusquinn Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .agents/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,16 @@ Subagent write restrictions: on `main`/`master`, subagents may ONLY write to `RE

---

## Operational Routines (Non-Code Work)

Not every autonomous task should use `/full-loop`. Use this decision rule:
- **Code change needed** (repo files, tests, PRs) → `/full-loop`
- **Operational execution** (reports, audits, monitoring, outreach, client ops) → run a domain agent/command directly, with no branch/PR ceremony

For setup workflow, safety gates, and scheduling patterns, use `/routine` or read `.agents/scripts/commands/routine.md`.

---

## Self-Improvement

Every agent session — interactive, worker, or supervisor — should improve the system, not just complete its task. This is a universal principle, not specific to any one command.
Expand Down
116 changes: 116 additions & 0 deletions .agents/scripts/commands/routine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
---
description: Design and schedule recurring non-code operational routines
agent: Build+
mode: subagent
---

Create a recurring operational routine (reports, audits, monitoring, outreach) without forcing `/full-loop`.

Arguments: $ARGUMENTS

## Goal

Build a reliable routine from three independent dimensions:

1. **SOP** - what to do
2. **Targets** - who/what to apply it to
3. **Schedule** - when to run

Keep these separate so each can evolve independently.

## Decision Rule

- If the routine needs repo code changes and PR traceability, use `/full-loop`
- If the routine is operational execution, run direct commands with `opencode run`

## Workflow

### Step 1: Define the SOP command

Create or select the command that performs one run for one target.

Examples:

```bash
/seo-export --account client-a --format summary
/keyword-research --domain example.com --market uk
/email-health-check --tenant client-a
```

Prefer deterministic helper/script commands over free-form prompts.

### Step 2: Validate quality and safety manually

Run ad-hoc before scheduling:

```bash
opencode run --dir ~/Git/<repo> --agent SEO --title "Routine dry run" \
"/seo-export --account client-a --format summary"
```

Required checks before rollout:

- Output format is stable and client-safe
- No cross-client data leakage
- Retry and timeout behavior are acceptable
- Human review exists for outbound communication

### Step 3: Pilot rollout

Roll out in this order:

1. Internal/self target
2. Single client
3. Small client cohort
4. Full target set

Do not skip stages for outbound client-facing routines.

### Step 4: Schedule the command

Use launchd/cron to run the proven command on a fixed cadence.

Use helper script (recommended):

```bash
~/.aidevops/agents/scripts/routine-helper.sh plan \
--name weekly-seo-rankings \
--schedule "0 9 * * 1" \
--dir ~/Git/aidev-ops-client-seo-reports \
--agent SEO \
--title "Weekly rankings" \
--prompt "/seo-export --account client-a --format summary"
```

```bash
# macOS launchd/cron wrapper style
# aidevops: weekly client rankings
opencode run --dir ~/Git/<repo> --agent SEO --title "Weekly rankings" \
"/seo-export --account client-a --format summary"
```

For queue-driven development work, use `/pulse`. For fixed-time routines, use scheduler entries.

## Routine Spec Template

Store routine definitions in your repo (for example `routines/seo-weekly.yaml`):

```yaml
name: weekly-seo-rankings
agent: SEO
repo_dir: ~/Git/aidev-ops-client-seo-reports
schedule: "0 9 * * 1"
targets_cmd: "wp-helper --list-category client --jsonl"
run_template: "/seo-export --account {{target.account}} --format summary"
```

`targets_cmd` should emit one JSON object per line so a scheduler can iterate targets.

Note: this template is architectural guidance. `routine-helper.sh` currently schedules a literal `--prompt` command and does not parse `targets_cmd` or `run_template` directly.

## Anti-Patterns

- Repeating TODO items for routine execution
- Running operational routines through `/full-loop`
- Skipping pilot stages for outbound content
- Mixing SOP logic, target selection, and schedule in one monolithic prompt
37 changes: 25 additions & 12 deletions .agents/scripts/commands/runners.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@ agent: Build+
mode: subagent
---

Dispatch one or more workers to handle tasks. Each worker runs `/full-loop` in its own session.
Dispatch one or more workers to handle tasks. Pick the execution mode per task type:

- **Code-change work** (repo edits, tests, PRs) -> `/full-loop`
- **Operational work** (reports, audits, monitoring, outreach) -> direct command execution (no PR ceremony)

Arguments: $ARGUMENTS

Expand All @@ -13,11 +16,12 @@ Arguments: $ARGUMENTS
The runners system is intentionally simple:

1. **You tell it what to work on** (task IDs, PR numbers, issue URLs, or descriptions)
2. **It dispatches `opencode run "/full-loop ..."` for each item** — one worker per task
3. **Each worker handles everything end-to-end** — branching, implementation, PR, CI, merge, deploy
2. **It dispatches `opencode run` for each item** — one worker per task
3. **Code workers** handle branch -> implementation -> PR -> CI -> merge
4. **Ops workers** execute the requested SOP/command and report outcomes
4. **No databases, no state machines, no complex bash pipelines**
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There's a minor typo in this numbered list. This item is numbered as 4., but the previous item is also 4.. This should be 5. to maintain the correct sequence.

Suggested change
4. **No databases, no state machines, no complex bash pipelines**
5. **No databases, no state machines, no complex bash pipelines**


The `/full-loop` command is the worker. It already works. Runners just launches it.
The supervisor handles dispatch. The worker command depends on the work type.

## Automated Mode: `/pulse`

Expand All @@ -27,7 +31,7 @@ For unattended operation, the `/pulse` command runs every 2 minutes via launchd.
2. Fetches open issues and PRs from managed repos via `gh`
3. Observes outcomes — files improvement issues for stuck/failed work
4. Uses AI (sonnet) to pick the highest-value items to fill available slots
5. Dispatches workers via `opencode run "/full-loop ..."`, routing to the right agent
5. Dispatches workers via `opencode run`, routing to the right agent and execution mode

See `scripts/commands/pulse.md` for the full spec.
Comment on lines +34 to 36
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Read-only consistency check: verify pulse docs for hard-coded /full-loop assumptions.
set -euo pipefail

fd pulse.md .agents/scripts/commands -t f | while read -r f; do
  echo "== $f =="
  rg -n --context 2 '/full-loop|WORKER_COUNT|opencode run' "$f"
done

Repository: marcusquinn/aidevops

Length of output: 7206

Clarify execution mode routing: runners.md describes flexible routing, but pulse.md hard-codes /full-loop throughout.

The runners.md description ("routing to the right agent and execution mode") implies a flexible routing model, but pulse.md consistently hard-codes /full-loop for all worker dispatches (lines 195, 578, 659, 711, 996, 1007, 1020, 1054) and worker counting (line 44: grep '/full-loop'). Either update runners.md to specify that pulse uses /full-loop dispatch, or document the general routing model more clearly to distinguish it from this specific implementation.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.agents/scripts/commands/runners.md around lines 34 - 36, The docs disagree:
runners.md implies flexible execution-mode routing but pulse.md hard-codes
dispatches to "/full-loop" (and counts workers via grep '/full-loop'); fix by
either (A) updating runners.md to explicitly state that the pulse implementation
currently always uses the "/full-loop" path for worker dispatch and counting, or
(B) make pulse.md follow the general routing model by replacing hard-coded
"/full-loop" dispatch targets and the worker-count grep with the generic routing
variable/interface used by runners.md (so functions/commands that call opencode
run use the common execution-mode variable instead of "/full-loop"). Locate
occurrences of "/full-loop", the worker-counting grep, and the dispatch command
invocations in pulse.md and update them accordingly, and update runners.md text
to reflect which behavior is implementation-specific.


Expand Down Expand Up @@ -172,17 +176,24 @@ gh issue view 42 --repo user/repo --json number,title,url

### Step 2: Dispatch Workers

For each resolved item, launch a worker. Route to the appropriate agent based on the task domain (see `AGENTS.md` "Agent Routing"):
For each resolved item, launch a worker. Route to the appropriate agent based on the task domain (see `AGENTS.md` "Agent Routing") and pick the execution mode:

```bash
# For code tasks (Build+ is default — omit --agent)
opencode run --dir ~/Git/<repo> --title "t083: <description>" \
"/full-loop t083 -- <description>" &

# For domain-specific tasks (route to specialist agent)
# For code tasks in a specialist domain
opencode run --dir ~/Git/<repo> --agent SEO --title "t084: <description>" \
"/full-loop t084 -- <description>" &

# For non-code operational tasks (no /full-loop)
opencode run --dir ~/Git/<repo> --agent SEO --title "Weekly rankings" \
"/seo-export --account client-a --format summary" &

# For recurring operations, schedule this command via launchd/cron
# instead of queueing repeating TODO items

# For PRs
opencode run --dir ~/Git/<repo> --title "PR #382: <title>" \
"/full-loop Fix PR #382 (https://github.com/user/repo/pull/382) -- <what needs fixing>" &
Expand All @@ -196,9 +207,11 @@ opencode run --dir ~/Git/<repo> --title "Issue #42: <title>" \
- Use `--dir ~/Git/<repo-name>` matching the repo the task belongs to
- Use `--agent <name>` to route to a specialist (SEO, Content, Marketing, etc.)
- Omit `--agent` for code tasks — defaults to Build+
- Do NOT add `--model` — let `/full-loop` use its default (opus)
- Use `/full-loop` only when the task needs repo code changes and PR traceability
- For non-code operations, run the task command directly (for example `/seo-export ...`)
- Do NOT add `--model` unless escalation is required by workflow policy
- **Background each dispatch with `&`** so multiple workers launch concurrently
- Workers handle everything: branching, implementation, PR, CI, merge, deploy
- Code workers handle branch/PR lifecycle; ops workers execute and report outcomes

### Step 3: Monitor

Expand All @@ -224,11 +237,11 @@ The supervisor (whether `/pulse` or `/runners`) NEVER does task work itself:
- **Never** reads source code or implements features
- **Never** runs tests or linters on behalf of workers
- **Never** pushes branches or resolves merge conflicts for workers
- **Always** dispatches workers via `opencode run "/full-loop ..."`
- **Always** dispatches workers via `opencode run` with the command chosen by task type
- **Always** routes to the right agent — not every task is code

If a worker fails, the fix is to improve the worker's instructions (`/full-loop`),
not to do the work for it. Each failure that gets fixed makes the next run more reliable.
If a worker fails, improve the worker instructions/command definition,
not the supervisor role. Each fixed failure improves the next run.

**Self-improvement:** The supervisor observes outcomes from GitHub state (PRs, issues, timelines) and files improvement issues for systemic problems. See `AGENTS.md` "Self-Improvement" for the universal principle. The supervisor never maintains separate state — TODO.md, PLANS.md, and GitHub are the database.

Expand Down
Loading
Loading