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.

chore: Jul 13 housekeeping — STATE.md log, Amazon Q appendix (#227) (#266)

Cobus Greyling0eadd54c6536
diff --git a/STATE.md b/STATE.md
index 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.md
index b4de59e..08f7c06 100644
--- a/docs/primitives-matrix.md
+++ b/docs/primitives-matrix.md
@@ -260,3 +260,64 @@ A Gemini CLI daily triage loop:
### Official Documentation
https://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