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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
chore: Jul 13 housekeeping — STATE.md log, Amazon Q appendix (#227) (#266)
Cobus Greyling0eadd54c6536
diff --git a/STATE.md b/STATE.mdindex 49532c2..08fbf5c 100644--- a/STATE.md+++ b/STATE.md@@ -10,9 +10,18 @@ Last run: 2026-07-13T07:07:30Z (automated daily-triage workflow)## Watch List-- Collect a production story for Post-Merge Cleanup.+- Contributor failure stories — [#119](https://github.com/cobusgreyling/loop-engineering/issues/119) (PR Babysitter), [#221](https://github.com/cobusgreyling/loop-engineering/issues/221) (Post-Merge Cleanup).+- Feature PRs awaiting maintainer review — [#256](https://github.com/cobusgreyling/loop-engineering/pull/256) (loop-cost orchestration), [#258](https://github.com/cobusgreyling/loop-engineering/pull/258) (loop-context budget resolver; stacks on #256).- Validate `loop-init` scaffolds on fresh projects across all patterns.+## Housekeeping (2026-07-13)++- Merged doc PRs: [#248](https://github.com/cobusgreyling/loop-engineering/pull/248)–[#252](https://github.com/cobusgreyling/loop-engineering/pull/252), [#257](https://github.com/cobusgreyling/loop-engineering/pull/257), [#259](https://github.com/cobusgreyling/loop-engineering/pull/259), [#263](https://github.com/cobusgreyling/loop-engineering/pull/263), [#247](https://github.com/cobusgreyling/loop-engineering/pull/247) (closes #222–#228, #230, #225, #226, #231).+- Landed Amazon Q appendix from [#250](https://github.com/cobusgreyling/loop-engineering/pull/250) via maintainer rebase (closes #227); fixed official-doc link.+- Closed invalid [#260](https://github.com/cobusgreyling/loop-engineering/pull/260) (main→main) and duplicate [#255](https://github.com/cobusgreyling/loop-engineering/pull/255) (superseded by #263).+- Approved pending fork workflow runs (`audit` + `validate`) for external contributor PRs.+- Pruned merged automated `star-history` remote branches.+## Recent Noise (ignored this run)—diff --git a/docs/primitives-matrix.md b/docs/primitives-matrix.mdindex b4de59e..08f7c06 100644--- a/docs/primitives-matrix.md+++ b/docs/primitives-matrix.md@@ -260,3 +260,64 @@ A Gemini CLI daily triage loop:### Official Documentationhttps://github.com/google-gemini/gemini-cli++## Appendix: Amazon Q Developer CLI++Amazon Q Developer CLI (`q chat`) is a terminal-based agent, AWS-native, with custom agent+profiles and MCP support. Map the same loop primitives onto `q chat`, custom agent configs,+context resources, and external schedulers.++| Primitive | Amazon Q Developer CLI mapping |+|-----------|--------------------------------|+| Scheduling | No native cron-style scheduler. Use external schedulers (cron, systemd timers, GitHub Actions) to invoke `q chat` non-interactively, or `q chat --resume` to continue a saved per-directory conversation on the next scheduled run. |+| Rules / Context files | Define a custom agent in `.amazonq/agents/<name>.json` (project) or `~/.aws/amazonq/cli-agents/<name>.json` (personal), and list always-on context in its `resources` field (e.g. `file://STATE.md`, `file://.amazonq/rules/**/*.md`). Use `hooks.agentSpawn` to inject fresh context (like `git status`) at session start. |+| State | Keep `STATE.md` at the repo root, referenced in the custom agent's `resources` field so it's loaded every session; each run should read then update only the relevant section. |+| Maker/checker split | No native subagent/reviewer primitive. Workaround: define two custom agents (e.g. `daily-triage.json` with write tools, `loop-verifier.json` restricted to `fs_read`/`@git` only) and run the verifier agent over the diff in a separate `q chat --agent loop-verifier` session. |+| Connectors | Configure MCP servers in `.amazonq/mcp.json` (project) or `~/.aws/amazonq/mcp.json` (global); scope tool trust per agent via `allowedTools`. Treat workspace `.amazonq/mcp.json` files from untrusted repos with caution — review before opening, since auto-loaded MCP configs have been a real attack vector for this class of tool. |+| Honest gaps | No first-class scheduler, no built-in maker/checker separation, no dedicated state-file convention — these are all manual conventions layered on top of `q chat`, same as most terminal agents without a purpose-built loop scheduler. |++Minimal transfer recipe:++```bash+mkdir -p .amazonq/agents .amazonq/rules+cp templates/SKILL.md.loop-triage .amazonq/rules/loop-triage.md+cp starters/minimal-loop/STATE.md.example STATE.md+```++`.amazonq/agents/daily-triage.json`:++```json+{+ "name": "daily-triage",+ "description": "Report-only daily triage agent",+ "prompt": "Run loop-triage. Update STATE.md with High Priority and Watch List only. Do not edit source code in week one.",+ "tools": ["fs_read", "fs_write"],+ "resources": [+ "file://STATE.md",+ "file://.amazonq/rules/loop-triage.md"+ ]+}+```++### Week-one Daily Triage prompt (report-only, copy-paste)++```bash+q chat --agent daily-triage --no-interactive \+ "Run loop-triage. Read STATE.md first. Update only High Priority and Watch List sections. Do not edit source code in week one."+```++Verifier pass for later L2 work — a separate, read-only-scoped agent:++```bash+git diff > diff.patch+q chat --agent loop-verifier --no-interactive \+ "Act as loop-verifier. Review diff.patch against STATE.md goals. Report PASS/FAIL and do not edit files."+```++After copying: map scheduling to cron/systemd/GitHub Actions until Q has a first-class+loop scheduler. Use `.amazonq/rules/` for always-on repo guidance, separate custom agents+for maker/checker separation, and `.amazonq/mcp.json` for external tools.++### Official Documentation++https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html