README.md

Cursor propose-only automation

This workflow is intentionally isolated under automation/cursor_propose_only/ so orchestration sources are not mixed with production runtime code, main docs, or the primary test suite.

Commands

From repository root:

• .venv/bin/python automation/cursor_propose_only/cli.py prepare ...
• .venv/bin/python automation/cursor_propose_only/cli.py evaluate ...
• .venv/bin/python automation/cursor_propose_only/execute.py ...
• .venv/bin/python automation/cursor_propose_only/autopilot.py ...

Select specific proposals

If you only want a subset, pass --proposal multiple times:

.venv/bin/python automation/cursor_propose_only/cli.py prepare \
  --repo-root . \
  --proposal-dir propose \
  --output-dir .agents/reports/propose_automation_selected \
  --proposal HTTP-ROUTE-METHOD-ENUM-PROPOSE.md \
  --proposal ENHANCED-ROLE-RECOGNITION-PROPOSE.md \
  --rounds 3 \
  --min-severity medium

Notes:

• --proposal paths may be absolute or relative to --proposal-dir
• when --proposal is provided, --glob is ignored
• add --include-completed if selected files can come from propose/completed/ or propose/stale/

Generate a propose-only workflow bundle

.venv/bin/python automation/cursor_propose_only/cli.py prepare \
  --repo-root . \
  --proposal-dir propose \
  --output-dir .agents/reports/propose_automation \
  --rounds 3 \
  --min-severity medium

Generated artifacts:

• .agents/reports/propose_automation/workflow.json
• .agents/reports/propose_automation/jobs/<job-id>/planner_prompt.md
• .agents/reports/propose_automation/jobs/<job-id>/reviewer_prompt_round1.md
• .agents/reports/propose_automation/jobs/<job-id>/reviewer_prompt_round2.md
• .agents/reports/propose_automation/jobs/<job-id>/reviewer_prompt_round3.md

Evaluate each reviewer response

Use one fresh reviewer session per round. Save each reviewer response to a file, then evaluate it with severity gating.

.venv/bin/python automation/cursor_propose_only/cli.py evaluate \
  --workflow .agents/reports/propose_automation/workflow.json \
  --job-id <job-id> \
  --round 1 \
  --review-file /path/to/review_round1.md \
  --min-severity medium \
  --write

Status transitions:

• actionable issue found -> needs_fixes
• approved with no actionable issues -> ready_to_merge
• final round still failing -> blocked_after_reviews

Automate implementation after plans are ready

When plans/AGENT-PROMPTS-<TOPIC>.md exists, run execute.py to iterate PR sections in order, run implementation command(s), run review loops, and mark tasks as ready_to_merge / merged.

.venv/bin/python automation/cursor_propose_only/execute.py \
  --repo-root . \
  --workflow .agents/reports/propose_automation/workflow.json \
  --rounds 3 \
  --min-severity medium \
  --implementation-command 'cursor-agent run --model auto --prompt-file {task_prompt_file}' \
  --review-command 'cursor-agent run --model auto --prompt-file {review_prompt_file}' \
  --merge-command 'gh pr merge {pr_url} --squash --delete-branch' \
  --run

Notes:

• without --run, execute.py performs a dry-run and only stages prompts/state
• command templates support placeholders such as {task_prompt_file}, {review_prompt_file}, {pr_url}, {branch}, {base}, {round}
• workflow state is persisted in .agents/reports/propose_automation/workflow.json

Fully automated (single command)

If you want: "I provide propose(s), workflow runs, I come back to ready PRs", use autopilot.py.

.venv/bin/python automation/cursor_propose_only/autopilot.py \
  --repo-root . \
  --proposal-dir propose \
  --output-dir .agents/reports/propose_automation_selected \
  --proposal ENHANCED-ROLE-RECOGNITION-PROPOSE.md \
  --planning-rounds 2 \
  --planning-min-severity medium \
  --implementation-rounds 2 \
  --implementation-min-severity medium \
  --planner-command 'cursor-agent run --model auto --prompt-file {planner_prompt_file}' \
  --planning-review-command 'cursor-agent run --model auto --prompt-file {review_prompt_file}' \
  --implementation-command 'cursor-agent run --model auto --prompt-file {task_prompt_file}' \
  --implementation-review-command 'cursor-agent run --model auto --prompt-file {review_prompt_file}' \
  --merge-command 'gh pr merge {pr_url} --squash --delete-branch' \
  --run

Behavior:

1. Generates workflow bundle (prepare equivalent)
2. Runs planner command for each selected proposal
3. Runs planning review rounds with severity gating and planner-fix loops
4. Parses generated plans/AGENT-PROMPTS-*.md
5. Runs implementation and implementation-review loops per PR section
6. Marks tasks ready_to_merge or merged (if merge command is provided)

Reviewer format convention

For consistent parsing, reviewer findings should follow:

• [CRITICAL] ...
• [HIGH] ...
• [MEDIUM] ...
• [LOW] ...
• [TRIVIAL] ...

When no actionable issues remain, reviewer should return:

• APPROVED