<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Westley Rotolo on Medium]]></title>
        <description><![CDATA[Stories by Westley Rotolo on Medium]]></description>
        <link>https://medium.com/@westleyrotolo?source=rss-9f220ecb5bb6------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*mhubqfYQ6bOt0UIu9r5cWg.jpeg</url>
            <title>Stories by Westley Rotolo on Medium</title>
            <link>https://medium.com/@westleyrotolo?source=rss-9f220ecb5bb6------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 23:21:01 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@westleyrotolo/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[How I Built Memento’s Agent Harness]]></title>
            <link>https://medium.com/@westleyrotolo/how-i-built-mementos-agent-harness-f8d8d80ccaac?source=rss-9f220ecb5bb6------2</link>
            <guid isPermaLink="false">https://medium.com/p/f8d8d80ccaac</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[ai-coding]]></category>
            <category><![CDATA[agent-harness]]></category>
            <category><![CDATA[xcode]]></category>
            <dc:creator><![CDATA[Westley Rotolo]]></dc:creator>
            <pubDate>Wed, 11 Nov 2026 17:03:51 GMT</pubDate>
            <atom:updated>2026-11-11T17:31:52.330Z</atom:updated>
            <content:encoded><![CDATA[<p>How I hand off work between agents, give them the right context, and review what comes back.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*9upkAAiOIH3Ozo4w.png" /></figure><p>When I moved a task to a new AI chat, I had to explain what had already been done and where to pick up. When I stayed in the same chat, I often had to bring it back to the original requirements or remind it of a decision we’d already made.</p><p>I built a project-specific harness on top of Codex so I could hand over a goal and let the coordinator manage the work between agents.<br>It breaks the goal into assignments and gives each specialist the skills and acceptance criteria they need. <br>The repository holds the shared rules. <br>Decisions and check results travel with the work.</p><p>I put the harness to work by building Memento. The first assignment was market research.</p><figure><img alt="The apple-growth-operations agent uses apple-customer-reviews to identify recurring problems in audio apps and return a shortlist of product opportunities backed by review evidence." src="https://cdn-images-1.medium.com/max/1024/1*XbUQ7X3MRgwkalYAkdZ7JQ.png" /></figure><h3>How I delegated competitor research</h3><p>I also left it to the harness to decide which apps to study. It picked six competitors that approached the same problem in different ways.</p><ul><li><strong>Otter and Fireflies</strong> covered meeting assistants, including team integrations.</li><li><strong>Notta</strong> covered multilingual transcription and translation.</li><li><strong>PLAUD</strong> represented dedicated recording hardware and AI notes.</li><li><strong>Aiko and Just Press Record</strong> covered on-device transcription and one-tap recording, respectively.</li></ul><p>The coordinator turns the question into a research assignment. The apple-growth-operations profile is configured for that work. The apple-customer-reviews skill specifies what the report should contain, including source provenance, sampling limits, and a distinction between observations and recommendations. Once the apps were selected, apple-reviews.sh collected and normalized <strong>458 unique reviews</strong> across 12 feeds, one per app in each of the Italian and US storefronts.</p><p>Interrupted and lost recordings were among the most serious complaints. The report proposed incremental saving and recovery after interruption as priorities for the mobile beta. It also recommended checking the quality of on-device Italian transcription, making uncertain passages easy to replay and correct, keeping the original audio accessible, and linking summary items to the source audio.</p><p>The feeds covered different time periods. The report kept those limits attached to the recommendations, so I could assess each proposal before deciding whether it belonged on the roadmap. On a coding assignment, the same handoff structure produces a diff and the evidence needed to review it.</p><h3>Giving agents the context they need</h3><p>Each assignment carries the relevant paths and decisions. The reusable instructions live in the repository.</p><ul><li><strong>Repository rules.</strong> AGENTS.md defines shared constraints, and DESIGN.md gives UI work common acceptance criteria.</li><li><strong>Agent profiles.</strong> The TOML files in .codex/agents/ define a role’s instructions, model, and reasoning effort.</li><li><strong>Skills.</strong> A SKILL.md gives an agent a reusable procedure for a specific domain, along with the references and outputs it needs.</li><li><strong>Roadmap and tasks.</strong> The coordinator turns dependencies and priorities into assigned files, invariants, and verification steps.</li></ul><p>I use AGENTS.md for rules that apply across assignments. The excerpt below requires agents to trace the data path before editing and prepare reference fixtures before moving a Swift definition used to read or write persisted data into a different module. <a href="https://learn.chatgpt.com/docs/agent-configuration/agents-md">OpenAI’s guide to AGENTS.md</a>.</p><pre>1. Trace the entry point, state owner, service boundary, platform APIs and tests before editing.<br>4. Preserve compatibility of `.session.json`, `transcript.json`, summary/profile JSON and media naming. Add golden decode/encode fixtures before moving versioned types.</pre><p>DESIGN.md gives design, implementation, and review the same criteria. The recovery path in the fourth rule becomes an explicit check when reviewing an error state.</p><pre>Every screen or focused region must have:<br>1. one primary user task;<br>2. one visually dominant action or content focal point;<br>3. supporting information ordered by consequence;<br>4. a recovery path for blocked or failed states.</pre><p>The role defines the result I expect from the agent. The skill gives it a procedure for the problem at hand. A test writer and a reviewer can both use apple-testing-quality. One uses it to build assertions, while the other uses it to identify gaps in the evidence. <a href="https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agents">OpenAI’s guide to custom agents in Codex</a>.</p><p>The apple-core skill asks the agent to trace state ownership and cancellation before editing, then report those decisions and the checks it actually ran.</p><pre>3. Trace state ownership and concurrency boundaries before editing. Identify the main actor, cancellation owner and any value crossing actors.<br><br>## Required outcome<br>Report platform scope, state/concurrency decision, changed boundary, commands run, evidence and unverified destinations.</pre><p>I assign a primary skill and add a second when the task crosses another technical boundary. <a href="https://learn.chatgpt.com/docs/build-skills">OpenAI’s guide to building skills</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*7BP_c3dek_wupi6O.png" /></figure><h3>How our skills use scripts and sources</h3><p>In apple-customer-reviews, the agent reads references/review-sources.md before collecting or interpreting reviews. That file points to Apple’s App Store Connect documentation for reviews of an app we own. It also records the limits of the public feed used for competitor sampling. The skill assigns two repeatable steps to scripts. collect_reviews.py normalizes the inputs, and analyze_reviews.py produces rating and keyword counts. The agent uses those outputs to write the report and explain what the sample can support. <a href="https://developer.apple.com/documentation/appstoreconnectapi/customer-reviews">Apple’s App Store Connect customer reviews documentation</a>.</p><p><strong>Skill excerpt · </strong><strong>apple-customer-reviews/SKILL.md</strong></p><pre>## Scripts<br>- Run `scripts/collect_reviews.py` to normalize an authorized App Store Connect export or explicitly sample the non-contractual Apple RSS feed.<br>- Run `scripts/analyze_reviews.py` to create deterministic rating and keyword-theme summaries.<br>- Keep network collection opt-in. Tests must use local fixtures.</pre><p>The apple-shared-code-decoupling skill gives the agent a check to run after extracting shared Swift code. The wrapper calls the skill’s audit_platform_imports.py script. With the core profile, the audit flags imports such as AppKit or UIKit in the shared core. I pair that check with builds for the affected targets.</p><p><strong>Skill excerpt · </strong><strong>apple-shared-code-decoupling/SKILL.md</strong></p><pre>4. Move Foundation-only contracts/use cases before UI or persistence. Preserve Codable bytes/semantics with golden fixtures.<br>5. Run `scripts/audit_platform_imports.py` for every extracted shared root. Add the audit to a gate only after that root exists.<br>6. Prove the macOS shell after each step; prove iOS/watchOS only when concrete schemes and destinations exist.</pre><p>The harness exposes that check through a wrapper.</p><pre>bash scripts/apple-shared-audit.sh --profile core src/shared/MementoCore</pre><p>The same skill’s references/shared-boundaries.md records how to use each source. Apple’s multiplatform guide documents target configuration, and Apple’s Food Truck repository provides sample code. <br>The file lists Point-Free’s Swift Dependencies as an optional reference for design patterns. Adding it as a dependency would be a separate decision. <a href="https://developer.apple.com/documentation/xcode/configuring-a-multiplatform-app-target">Apple’s multiplatform guide</a> · <a href="https://github.com/apple/sample-food-truck">Apple’s Food Truck sample</a> · <a href="https://github.com/pointfreeco/swift-dependencies">Swift Dependencies</a>.</p><p><strong>Source excerpt · </strong><strong>apple-shared-code-decoupling/references/shared-boundaries.md</strong></p><pre>## Primary and upstream sources<br>- [Configuring a multiplatform app](https://developer.apple.com/documentation/xcode/configuring-a-multiplatform-app-target)<br>- [SupportedPlatform](https://developer.apple.com/documentation/packagedescription/supportedplatform)<br>- [Food Truck sample](https://github.com/apple/sample-food-truck)<br>- [Swift Dependencies](https://github.com/pointfreeco/swift-dependencies) — optional pattern reference, not an approved dependency.</pre><h3>Choosing a model and reasoning effort</h3><p>I set the model policy once in AGENTS.md. When I give the coordinator an objective, it chooses a role for each assignment and uses the model and effort configured in that role’s profile. I can hand off a change that involves both a complex review and a narrowly specified test without picking a model for either step.</p><p>For a unit test on behavior we have already defined, the coordinator can assign apple-unit-test-writer, which uses Luna at low effort. A complex review goes to apple-quality-reviewer, which uses Terra at high effort. Terra at medium is the default for work such as planning and scoped implementation. This keeps the reasoning budget for bounded tasks low and gives harder assignments more room to reason. <a href="https://developers.openai.com/api/docs/guides/reasoning">OpenAI’s reasoning guide</a>.</p><p><strong>Model policy excerpt · </strong><strong>AGENTS.md</strong></p><pre>- Luna `low`: exact mechanical code, deterministic unit tests, approved localization changes and explicit accessibility remediation. Batch related work sharing a target and fixtures into one invocation.<br>- Terra `medium`: default for planning, review and bounded non-trivial implementation. Use Terra `high` only for complex review, concurrency, integration or data-design failures.</pre><p>The implementer profile below shows how one of those choices is recorded. Output verbosity has its own setting.</p><pre>name = &quot;apple-code-implementer&quot;<br>model = &quot;gpt-5.6-terra&quot;<br>model_reasoning_effort = &quot;medium&quot;<br>model_verbosity = &quot;low&quot;<br>sandbox_mode = &quot;workspace-write&quot;<br>tool_output_token_limit = 6000<br>[tools]<br>web_search = false</pre><h3>Coordinating work in parallel</h3><p>The TOML config sets the defaults and thread limit for subagents. The coordinator decides which assignments can proceed together by checking file ownership and dependencies.</p><pre>[agents]<br>default_subagent_model = &quot;gpt-5.6-terra&quot;<br>default_subagent_reasoning_effort = &quot;medium&quot;<br>max_concurrent_threads_per_session = 3</pre><p><strong>Three concurrent subagent threads, with at most two parallel writers.</strong> The writer limit comes from the delegation rules in AGENTS.md. The coordinator assigns two writers only when they own disjoint files and their contracts are independent. <a href="https://learn.chatgpt.com/docs/agent-configuration/subagents">OpenAI’s guide to delegation with subagents</a>.</p><p>The feature workflow records how to hand off the work and review it after integration. Two assignments can touch separate files and still depend on the same unresolved behavior. In that case, the coordinator settles the contract first.</p><pre>3. Keep trivial single-file work in the parent. Otherwise freeze one compact handoff with intent, destinations, owned paths/symbols, contracts, ownership, success/failure behavior, constraints and acceptance command; do not attach file dumps or full logs.<br>5. Use no more than two parallel writers, only with disjoint files and independent contracts. Sequence overlapping work and batch related leaf edits into one invocation.<br>6. Have the parent integrate once, inspect the combined diff, add one batched Luna pass for deterministic tests/localization/accessibility when applicable, then use one combined quality review and the narrowest credible gates.</pre><h3>Inspecting the runner</h3><p>harness.json records roles, skills, commands, and which paths the harness manages. The validator checks the inventory against the files on disk. The lists below are abbreviated.</p><pre>{<br>  &quot;schemaVersion&quot;: 1,<br>  &quot;version&quot;: &quot;0.9.0&quot;,<br>  &quot;mode&quot;: &quot;project-local&quot;,<br>  &quot;skills&quot;: [&quot;apple-core&quot;, &quot;apple-testing-quality&quot;],<br>  &quot;codexAgents&quot;: [&quot;apple-code-implementer&quot;, &quot;apple-quality-reviewer&quot;],<br>  &quot;commands&quot;: {<br>    &quot;runSkill&quot;: &quot;bash scripts/run-apple-skill.sh&quot;,<br>    &quot;validate&quot;: &quot;bash scripts/validate-harness.sh&quot;<br>  },<br>  &quot;managedEntries&quot;: [&quot;.agents/skills&quot;, &quot;.codex/agents&quot;],<br>  &quot;excludedApplicationEntries&quot;: [&quot;src/macOS&quot;, &quot;src/shared&quot;]<br>}</pre><p>The runner includes the role and skill in the prompt and assembles the arguments for the Codex process.</p><pre>skill_prompt=&quot;Use \$$skill. $prompt&quot;<br>if [[ -n &quot;$agent&quot; ]]; then <br>  skill_prompt=&quot;Use the project Codex role &#39;$agent&#39; with its assigned model. $skill_prompt&quot;<br>fi<br>command=(&quot;$codex_bin&quot;)<br>[[ &quot;$search&quot; == true ]] &amp;&amp; command+=(--search)<br>command+=(exec -C &quot;$root_dir&quot; --sandbox &quot;$sandbox&quot;)<br>[[ &quot;$ephemeral&quot; == true ]] &amp;&amp; command+=(--ephemeral)<br>[[ -n &quot;$model&quot; ]] &amp;&amp; command+=(--model &quot;$model&quot;)<br>[[ -n &quot;$output&quot; ]] &amp;&amp; command+=(--output-last-message &quot;$output&quot;)<br>command+=(&quot;$skill_prompt&quot;)</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*VIH3IeTt_XeoAq9H.png" /></figure><p>The task asks for reproducible defects in a diff. The reviewer profile defines its mandate, and the testing skill guides the checks and the evidence it reports. I can inspect the invocation before launching it.</p><pre>bash scripts/run-apple-skill.sh --dry-run \<br>  --agent apple-quality-reviewer apple-testing-quality \<br>  &quot;Review the requested diff and report reproducible defects.&quot;</pre><p>Here is the generated command with the repository path and prompt shortened.</p><pre>codex exec -C &lt;repository&gt; --sandbox read-only --ephemeral --model gpt-5.6-terra &lt;prompt&gt;</pre><p>The wrapper reads the model from the reviewer’s TOML profile and passes it with --model. It passes the effective sandbox with --sandbox, which defaults to read-only in the runner. I check how Codex loads the role separately when I need to confirm which instructions and reasoning effort reach the session.</p><h3>From a UI brief to a review decision</h3><p>When I added DESIGN.md to the harness, I updated the UI skill and the experience architect role so implementation and review could start from the same criteria. Here is how the workflow hands off a UI change.</p><ol><li><strong>Define the outcome.</strong> The coordinator gives apple-experience-architect the screen and the desired behavior. The architect uses apple-ui-design and DESIGN.md to specify the primary action, the states to cover, and the visual evidence to collect.</li><li><strong>Assign the change.</strong> The coordinator gives apple-code-implementer the brief, the files it owns, and the required check. The implementer returns the diff, the evidence it gathered, and any deviations.</li><li><strong>Review the integrated diff.</strong> The coordinator sends apple-quality-reviewer the combined diff, the original criteria, and the evidence. The reviewer returns reproducible findings and checks that remain open.</li></ol><p>An assignment for an error state could read like this.</p><pre>Expected outcome   The error state shows a retry action.<br>Assigned files     The affected view and its preview.<br>Constraint         Keep the retry service unchanged.<br>Required evidence  Screenshot of the error state on the assigned target.<br>Deliverable        Diff, collected evidence, and any open checks.</pre><p>If the diff shows the retry action and the required screenshot is missing, the coordinator can reopen that specific check using the same brief and diff. I can decide whether to integrate once the evidence is there.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*cmFMsuPq_1c4IO5y.png" /></figure><p>The harness also has a test for the UI workflow’s references. The excerpt checks that the design contract is registered and that the skill points to the expected guides. Visual acceptance still depends on the evidence collected for the assignment.</p><pre>def test_ui_design_contract_is_managed_and_routed(self) -&gt; None:<br>    manifest = json.loads((ROOT / &quot;harness.json&quot;).read_text(encoding=&quot;utf-8&quot;))<br>    self.assertIn(&quot;DESIGN.md&quot;, manifest[&quot;managedEntries&quot;])<br>    design = (ROOT / &quot;DESIGN.md&quot;).read_text(encoding=&quot;utf-8&quot;)<br>    self.assertIn(&quot;## Mobile contract&quot;, design)<br>    self.assertIn(&quot;## Visual acceptance evidence&quot;, design)<br>    skill = (ROOT / &quot;.agents/skills/apple-ui-design/SKILL.md&quot;).read_text(encoding=&quot;utf-8&quot;)<br>    self.assertIn(&quot;references/memento-mobile-design.md&quot;, skill)<br>    self.assertIn(&quot;references/visual-review.md&quot;, skill)</pre><h3>Improving the process</h3><p>When an assignment goes wrong, I can change how I delegate or verify it. That correction becomes part of the harness and carries forward to later assignments.</p><p>The local AI tester makes that feedback loop concrete. I set the comparison criteria, such as transcription quality and runtime on the same recording. The agent can try different engines on the device, compare the results, and use those measurements to choose its next attempt. When it finds an improvement against the agreed criteria, it brings me the evidence and a proposal. I decide whether to integrate it.</p><h3>The agent and skill map</h3><p>The coordinator is at the center. The map includes all <strong>14 agent roles and 33 skills</strong>, with model and reasoning effort beside each role. The lower panel lists skills selected to match the task’s domain. Implementation, mechanical edits, tests, localization, and accessibility fixes use profiles intended for workspace writes. The other roles are designed for read-only work. The invocation determines the effective sandbox.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*DF1JoKYRSEkoCp7u.png" /></figure><h3>Agent profiles at a glance</h3><p>Terra is gpt-5.6-terra and Luna is gpt-5.6-luna. The sandbox column describes the intended access for each role. The invocation determines the effective sandbox.</p><p><a href="https://memento.leyro.it/medium/#agent-profiles-at-a-glance">Open the scrollable agent profiles table</a></p><figure><img alt="Table of all 14 specialist agents, with their model and reasoning effort, intended sandbox, and when each role is used." src="https://cdn-images-1.medium.com/max/1024/1*mlO7YqFxK3t95qzNZz399g.png" /></figure><h3>The result is Memento</h3><p>The work took shape in Memento, a Mac and iPhone app with an interface guided by Apple conventions and features informed by what users reported in reviews. <br>Mac and iPhone share data contracts and parts of the audio and AI pipeline. <br>Each platform handles its native integrations.</p><figure><img alt="Memento on Mac shows a searchable transcript and audio controls. Memento on iPhone shows a recording summary with copy and edit options." src="https://cdn-images-1.medium.com/max/1024/1*Wmq3ce1EbwFsRPEb71_YKQ.png" /></figure><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2Fy8niRsHmiBE%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3Dy8niRsHmiBE&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2Fy8niRsHmiBE%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/412c5cf976a5332accda35841f439b15/href">https://medium.com/media/412c5cf976a5332accda35841f439b15/href</a></iframe><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FpfY05uV61q8%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DpfY05uV61q8&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FpfY05uV61q8%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/3855111e7ad0442da0240faf31232949/href">https://medium.com/media/3855111e7ad0442da0240faf31232949/href</a></iframe><p><a href="https://memento.leyro.it/">Explore Memento</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f8d8d80ccaac" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>