Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

docs: opencode constraints example (#183)

Anushka Kawalkarbf1c22458c3c
diff --git a/examples/opencode/README.md b/examples/opencode/README.md
index b47f454..e3cfca3 100644
--- a/examples/opencode/README.md
+++ b/examples/opencode/README.md
@@ -8,6 +8,7 @@ Open-source coding agent that runs from the CLI, can run headlessly via `opencod
| [constraints.md](./constraints.md) | Constraints (binding rules loaded before every loop run) |
| [ci-sweeper.md](./ci-sweeper.md) | CI Sweeper (cron/systemd + `opencode run` for short cadences) |
| [pr-babysitter.md](./pr-babysitter.md) | PR Babysitter (long-running PR shepherd with worktree isolation) |
+| [Constraints Example](constraints-example.md) – Minimal loop-triage skill with recommended guardrails. |
> **Starter kit:** [../../starters/minimal-loop-opencode/](../../starters/minimal-loop-opencode/) — clone-and-run scaffold for L1 daily triage.
>
diff --git a/examples/opencode/constraints-example.md b/examples/opencode/constraints-example.md
new file mode 100644
index 0000000..5f917de
--- /dev/null
+++ b/examples/opencode/constraints-example.md
@@ -0,0 +1,42 @@
+# Opencode Constraints Example
+
+This example shows how to define simple guardrails for a CLI-first workflow using Opencode.
+
+It pairs with:
+
+```bash
+loop-init --tool opencode
+```
+
+After initialization, you can customize the generated skill with project-specific constraints.
+
+## Example
+
+```text
+skills/
+└── loop-triage/
+ └── SKILL.md
+```
+
+```markdown
+# Loop Triage
+
+## Constraints
+
+- Read-only during the first week of onboarding.
+- Never force-push to any branch.
+- Only modify files directly related to the assigned issue.
+- Request confirmation before deleting or renaming files.
+- Do not expose secrets, tokens, or internal URLs.
+```
+
+## Why use constraints?
+
+Constraints help make automated workflows predictable and reduce the chance of accidental or unsafe actions.
+
+They are especially useful for new contributors or shared repositories.
+
+## Related documentation
+
+- See `docs/safety.md` for general safety guidance.
+- Compare this with the Cursor constraints example for an editor-focused workflow.
\ No newline at end of file
diff --git a/stories/multi-loop-coordination.md b/stories/multi-loop-coordination.md
new file mode 100644
index 0000000..d4295ba
--- /dev/null
+++ b/stories/multi-loop-coordination.md
@@ -0,0 +1,78 @@
+# Multi-Loop Coordination: Daily Triage + PR Babysitter
+
+## Overview
+
+I experimented with running two automation loops at the same time:
+
+- **Daily Triage** – reviews new issues and labels or prioritizes them.
+- **PR Babysitter** – monitors pull requests and reminds contributors about reviews or requested changes.
+
+Running both loops together helped distribute responsibilities, but it also introduced coordination challenges.
+
+---
+
+## Patterns and tools used
+
+### Loops
+
+- Daily Triage
+- PR Babysitter
+
+### Coordination patterns
+
+- Separation of responsibilities
+- Independent state tracking
+- Scheduled execution
+- Clear ownership of resources
+
+---
+
+## Separating state, schedules, and budgets
+
+To avoid conflicts, each loop maintained its own resources.
+
+### State files
+
+- Daily Triage → `triage-state.json`
+- PR Babysitter → `pr-state.json`
+
+Each loop only updated its own state file.
+
+### Schedules
+
+Daily Triage ran every morning.
+
+PR Babysitter ran later in the day after new pull requests were likely to appear.
+
+Staggering schedules reduced overlap.
+
+### Budgets
+
+Each loop had its own execution budget and context window.
+
+This prevented one loop from consuming resources intended for the other.
+
+---
+
+## Failure mode
+
+One issue occurred when both loops reacted to the same pull request.
+
+Daily Triage labeled the PR as needing attention while PR Babysitter generated a reminder at nearly the same time.
+
+This resulted in duplicate notifications.
+
+Another risk was context bleed, where one loop accidentally reused information that belonged to another workflow.
+
+---
+
+## Lesson learned
+
+Running multiple loops works best when every loop has:
+
+- a clearly defined responsibility,
+- separate state,
+- independent schedules,
+- and dedicated resource limits.
+
+Treat each loop as an independent worker that communicates only through well-defined shared information instead of sharing internal state.
\ No newline at end of file