Building Hope-Driven Products

A Two-Layer Project Structure for AI Coding Agents

2026-06-18T00:00:00Z

I have been using a two-layer project structure for AI coding agents.

The pattern is straightforward: keep the source code in focused repositories, but run the agent from a higher-level workspace that understands how those repositories fit together. That top-level folder operates above the source repositories and holds the work around the code: saved plans, internal notes, private instructions, and cross-repo context.

project-workspace/
  repo              # main repo, open source
  repo-devops       # server deployment stuff, closed source
  related-repo1
  related-repo2
  related-repo3
  ...
  AGENTS.md         # knowledge about how each sub-repo works
  plans/            # agent plans

Each sub-repo can still have its own AGENTS.md. But in practice, I rarely enter the individual repo folder to prompt the agent. Most of the time, I work from the workspace root and use it as the starting point.

Why the workspace exists

A project quickly grows beyond one codebase. A real product often has the main app, deployment scripts, infrastructure configuration, documentation, marketing material, support tools, experiments, and private operational notes. These pieces are connected, but they should not always live in the same public repository.

From the workspace, I can ask the agent something like:

/goal implement this feature, then write a blog post, and schedule a tweet about it

That request does not belong cleanly inside a single repo. The implementation may happen in the app repo, the deployment change in the DevOps repo, the product explanation in docs or a blog draft, and the launch message in a publishing plan.

From the workspace level, the agent can plan the sequence before dropping into any one folder.

What gets better

Project memory gets one place to live. Saved plans, internal notes, and workflow instructions can sit above the repos instead of being copied into each one.

Private context also stays private. For open-source projects, deployment details and internal planning notes do not need to sit inside the public codebase.

Cross-repo work feels more natural from this level. A feature may need code, deployment changes, docs, changelog entries, and launch notes. Starting from the workspace keeps those related tasks visible.

The prompt can start at the project level too. Instead of asking, "What file should I edit in this repo?", I can ask, "What needs to happen across the project?"

Tradeoff

The risk is that the agent can see too much. It may search across too many folders, pull in unrelated context, or treat every task as a whole-project problem.

That makes the workspace-level AGENTS.md important. It should describe what each sub-folder is for, which repos are public or private, where plans belong, and when the agent should stay inside a single repo instead of searching the whole workspace.

For example, a workspace-level AGENTS.md might look like this:

# Project Workspace Agent Notes

This directory is an operator workspace that groups multiple independent Git
repositories. Treat each child directory with its own `.git/` as a separate
repository, not as source owned by this root workspace repository.

## Workspace Shape

Known child repositories:

- `<app-repo>`: application codebase. Read `<app-repo>/AGENTS.md` before
  changing application, docs, package, job, or shared library code.
- `<deploy-repo>`: deployment and operations. Read `<deploy-repo>/AGENTS.md`
  before changing deployment, infrastructure, service, or production
  verification behavior.
- `<pipeline-repo>`: build and publish pipelines. Read
  `<pipeline-repo>/AGENTS.md` before changing pipeline scripts or YAML.
- Other child directories with their own `.git/`: independent repositories.
  Check for repo-local guidance before editing.
- `plans/`: workspace planning notes and cross-repo coordination material.

## Working Rules

- Do not add child repositories, their contents, or embedded repo gitlinks to
  the root workspace Git repository.
- Make source changes inside the owning child repository and use that
  repository's Git history for commits and branches.
- Use this root only for workspace-level guidance, notes, and coordination
  files.
- Before cross-repo changes, inspect the relevant child repo status with
  `git -C <repo> status --short` so unrelated local work is not disturbed.
- Never revert or overwrite changes in a child repository unless the user
  explicitly asks for that exact repo and change.
- Prefer repo-local commands from the repo root, for example
  `cd <repo> && npm test` or `cd <deploy-repo> && npm run verify`.

The exact names do not matter. What matters is that the agent understands the boundary between the root workspace and the child repositories: where instructions live, where plans belong, which Git history owns a change, and which local or secret state must not leak into public work.

Where this can go

A few directions are worth testing:

A workspace-level agent could act as an orchestrator instead of doing everything itself. It could pass a goal to a sub-agent running inside the relevant repo folder, then let that sub-agent handle the focused implementation.
The same structure could become a personal vault for loosely connected knowledge: notes, relationships, blog drafts, high-level projects, and other information that does not fit cleanly into one repo.
At the extreme, the workspace could become a project root for all projects: one local operating layer for many projects, with enough memory to understand how they relate.

The workspace layer turns the project folder into more than a collection of repositories. It gives the agent one place to understand the product before choosing where to act.

AI Plan Mode Is Good. Saved Plans Make It Better.

2026-06-20T00:00:00Z

Plan mode forces the agent to slow down before coding. Before editing files, the agent has to understand the task, inspect the codebase, break the work into steps, surface risks, and ask for feedback.

That helps, but plan mode has one limitation: the plan usually lives inside the session.

For short tasks, that is enough. Longer work gets messy. I may switch machines. Another agent may need to continue the work. The original agent session is not always available, and even when it is, the transcript is rarely the clearest project artifact.

At that point, a plan inside a chat transcript is not enough. I want the plan to become part of the project.

Saved plans make plan mode better

A practical next step is to save the plan into the repo. That is why I made Planrock, a small agent skill and CLI that stores plans as Markdown files in a local plans/ folder.

A plan is just a Markdown file with frontmatter and a checklist:

---
title: Improve release workflow
state: open
priority: P1
created_at: 2026-06-20
agent_sessions:
  - codex:session-id
---

## Goal

Improve the release workflow so the agent can run tests, open a PR,
fix review comments, deploy after approval, verify production, and close the plan.

## Tasks

- [ ] Audit current release flow
- [ ] Update scripts
- [ ] Run lint and tests
- [ ] Open PR
- [ ] Address review comments
- [ ] Deploy after approval
- [ ] Verify shipped result

This is intentionally boring. The goal is durable planning without adding another project management system.

A saved plan is readable by humans and agents. Git tracks it. The CLI can list it. It becomes a small local memory layer for agent work.

In practice, it feels like a tiny repo-local GitHub Issues system for coding agents.

The agent can query open plans. I can review them. Another session can continue from them. When the work is done, the plan can be marked closed and committed with the implementation.

That is already a big improvement over a plan that only exists in a chat.

Why not use a spec framework?

There are more formal solutions for this problem. For example, OpenSpec is a spec-driven development workflow. It is designed to lock down intent before implementation and organize work through structured requirements, design notes, and task files.

That works when you want a real spec workflow. I do not always want to start from a formal spec.

Most of my agent sessions start much more casually:

Maybe the bug is here.
Can you inspect this module?
What if we split the deployment step?
Actually, make a plan from what we discussed.

That workflow needs a saved plan before it needs a full spec system.

The difference is roughly this:

OpenSpec:
Use a spec workflow to define and govern implementation.

Planrock:
Save the plan that came out of the agent conversation.

OpenSpec is better when the work is product-level, team-level, or behavior-driven. Planrock is better when I want a lightweight memory layer for personal or small-project agent work. It keeps the agent's plan alive outside the chat without enforcing a full process.

A quick Planrock demo

Install the Planrock skill:

npx skills add favoyang/planrock -g

Or simply ask your agent to install it for you:

Install the favoyang/planrock skill

After that, you can start with prompts like:

Create a saved plan to implement <feature prompt>.

Make a plan to <feature prompt>, and track it locally.

Summarize what we just discussed in a saved plan.

If you are already in plan mode, you can say:

Track this in a saved plan.

The skill will save the plan into the plans/ folder with unified frontmatter. During implementation, the agent can update the checklist, record progress, and mark the plan closed when the work is done.

Use the Planrock CLI

To see the progress of local open and closed plans, you can ask the agent to list them. You can also try the CLI manually.

npm install -g @favoyang/planrock
planrock

Or use npx:

npx @favoyang/planrock

A repo using Planrock may look like this:

my-project/
  AGENTS.md
  plans/
    improve-release-workflow.md
    fix-auth-callback.md

To check the current plan status:

planrock

Example output:

Working dir: /Users/alex/projects/my-project

Planrock Status
Open:   1
Closed: 1

Top Open Plans (top 10)
Priority  Title                      Created     Done/Total  Percent  Agent Sessions
--------  -------------------------  ----------  ----------  -------  --------------
P1        Improve release workflow   2026-06-20  3/7         43%      codex:7f3a9c21

Most Recent Closed Plans (top 10)
Closed      Created     Title
----------  ----------  -------------------------
2026-06-19  2026-06-19  Fix auth callback

To list open plans:

planrock open

To list completed plans:

planrock closed

The CLI is not the most important part. The Markdown files are. There is no hidden database, no remote service, and no heavy workflow to learn. The agent can read and update normal files in the repo.

Human-in-the-Loop, Not Human-as-the-Loop

2026-06-21T00:00:00Z

In AI Plan Mode Is Good. Saved Plans Make It Better, I introduced Planrock as a small saved-plan layer for coding agents. The core distinction is:

Plan mode gives structure.
Planrock gives memory.

Once the plan exists as a file, the next question is whether the agent can execute it without me typing "continue" again and again. That is where /goal fits.

My manual loop before `/goal`

In my normal workflow, the agent often already knows the next step. I even have this rule in AGENTS.md:

When working from a plan, after finishing any item, always state the next
concrete step. Continue doing this until the plan is genuinely complete so
the user does not need to ask "what's next?".

This helps. After finishing one item, the agent states what it will do next. If it stops, I type:

go

For me, go is just a short alias for:

continue

And the agent continues. This works, but it reveals the weakness of the workflow: if the agent already knows the next step, and my only contribution is typing go, I am not supervising. I am keeping the loop alive.

In that setup, the human keeps the loop running instead of supervising it.

What `/goal` changes

/goal keeps the agent focused on the objective. Instead of stopping after each local task, the agent can re-check the objective and continue until the work is done or blocked.

In my test, /goal reduced a lot of dumb pauses.

The session still stopped, but the stops made sense:

1. Missing auth blocked progress.
2. I manually interrupted it because it was going in the wrong direction.
3. My AGENTS.md policy required manual approval before deployment.

Those are reasonable pauses. I do not expect the agent to ignore real blockers. I just do not want it to stop when the next step is already clear.

Why saved plans pair well with `/goal`

A short /goal prompt can work for small tasks. The human gives up some control over detailed planning in exchange for a more autonomous run at the objective.

For larger tasks, I still want to provide more context:

goal
constraints
tasks
approval boundaries
test expectations
deployment rules
current state

A saved plan already contains that context:

Planrock stores the plan.
/goal keeps execution moving.

The saved plan gives the agent durable memory. /goal gives the agent momentum.

Workflow A: `/goal` first, saved plan during execution

This works when the task is clear.

/goal Implement X. Create and maintain a saved plan while working.

The agent can create the plan, save it, execute it, update the checklist, run tests, and close the plan when the work is done. This fits implementation tasks where the agent can mostly plan and execute alone.

For example:

/goal Add GitHub login to this app. Create and maintain a saved plan while working. Run tests, update docs if needed, and mark the plan closed only after the implementation is verified.

This gives the agent the objective and the instruction to keep a durable plan.

Workflow B: saved plan first, `/goal` second

This is the workflow I prefer when the task needs discussion first:

1. Use plan mode or normal chat to design the approach.
2. Save the result as a saved plan.
3. Turn the saved plan into a /goal command.
4. Let the agent execute while referencing the plan.

This fits my natural workflow because I do not always start with a clean objective. Sometimes I start with messy exploration:

Maybe the bug is here.
Can you inspect this module?
What if we split the deployment step?
Actually, make a plan from what we discussed.

Once that discussion becomes clear enough, I save it as a saved plan. Then I can use the saved plan as the execution source.

Planrock can generate the /goal command. It scans the plan, pulls the ## Goal section, and constructs a /goal command.

planrock goal plans/improve-release-workflow.md

The generated command can look like this:

/goal Follow plans/improve-release-workflow.md and complete the implementation. Keep the plan updated, run lint and tests, open a PR, address review comments, deploy only after approval, verify the shipped result, and mark the plan closed when complete.

This is the bridge I wanted: the saved plan keeps the context durable, and /goal keeps the execution loop running.

The human role changes

I still want human involvement. I want to review architectural decisions, approve risky changes, and keep final shipping control when it matters. I do not want to be the person typing go forever.

That is the distinction:

Without /goal:
The human keeps the loop alive.

With Planrock plus /goal:
The human defines or reviews the plan.
The agent runs the loop.
The human steps in for judgment.

Plan mode helps the agent think before coding. Planrock saves that thinking as repo-local memory. /goal uses that memory to keep execution moving, without taking away review, control, or shipping boundaries.

Loop Engineering Reduced to Two Patterns

2026-07-01T00:00:00Z

From prompting to loop engineering

Prompting has been moving toward longer-running loops.

With human in the loop, the human stayed close to the model, reviewed outputs, corrected mistakes, and decided the next step. This gave control, but it also created many interruptions.

With goal-driven prompting, we stop asking the model to do one small step at a time. We give it a clearer goal: what to achieve, what constraints to follow, and when to ask for help. The point is to reduce unnecessary interruptions without removing the human.

With loop engineering, we design the cycle around the prompt. The model takes an action, checks the result, updates what it knows, and tries again. This repeats until the goal is reached or something blocks progress.

Filter and improve

Most loops I care about reduce to two patterns: filter and improve.

A filter loop reduces many possibilities into a smaller set of stronger candidates.

It starts with a list, processes each item, evaluates the results, and keeps only the best ones. For example, a loop may collect high-performing thumbnail examples, analyze each one, score their visual patterns, keep the top few, then use those patterns to generate and score new caption ideas.

In short: many items go in, only the strongest few come out.

An improve loop makes one thing good enough.

It starts with a current artifact, applies a change, verifies the result, and repeats until it passes. For example, a coding loop runs tests, reads the failure, edits the code, runs tests again, and continues until all tests pass. An SEO loop runs a speed test, optimizes the website, reruns the test, and repeats until the score is above 95.

In short: keep changing one thing until it passes.

Most practical loops are one of these two shapes, or a combination of both. A content workflow may filter many ideas down to a few strong candidates, then improve the best one until it meets a clear quality standard.

Loop engineering gets easier when you reduce the workflow to filter or improve.

Short Automation Prompts, Long-Lived Skills

2026-07-04T00:00:00Z

When I schedule an automation, I can paste a long prompt into the schedule, with every rule, preference, example, and edge case spelled out there. That works, but it makes the automation feel like a hidden little program. If I want to improve it later, I have to find the schedule, edit the prompt, and hope I did not break the parts that already worked.

For anything I expect to maintain, I increasingly prefer a shorter shape:

Use the $personal-skill-maintenance skill.

The automation prompt stays small. The skill carries the real behavior.

That matters because a skill is a file. I can version it. I can review diffs. I can keep it in ~/.agents/skills when it is personal, or move it into a repo when the workflow belongs to that project. The root skill set stays cleaner, and the scope is easier for the agent to understand.

The bigger benefit is self-improvement. If the automation runs a retrospective and learns a better way to do the work, it can update the skill itself. The next run uses the improved behavior without me rescheduling the automation or copying a new wall of text into a cron entry.

I think of it like this:

Cron prompt: short and stable.
Skill file: specific, versioned, and improvable.

Verbose prompts are fine for one-off jobs. If I expect the automation to live for a while, I would rather maintain a skill than maintain a paragraph trapped inside a scheduler.

agentsnippet: Reuse AGENTS.md and CLAUDE.md instructions

2026-07-19T00:00:00Z

Most reusable coding-agent instructions should be packaged as skills, but AGENTS.md still has a job. It tells the agent which skills the project expects it to use and when to use them. A repository may have a rule like this:

Before committing, use the `$branch-review-subagent-loop` skill to review the
complete branch diff.

The skill holds the review workflow. AGENTS.md connects that workflow to the repository's delivery policy. When the same rule applies to several projects, I end up copying it into each instruction file. The duplication grows when repositories share several skill invocations and approval rules.

That works until one copy changes. I improve the rule in one project, forget the others, and eventually have several versions of what was supposed to be the same instruction.

Plain Markdown is part of the appeal of AGENTS.md and CLAUDE.md, but Markdown has no standard include mechanism. I wanted to reuse source text while keeping the instruction files that coding agents already understand.

Generate instruction files from snippets

I made agentsnippet for this job. It reads AGENTS.template.md and CLAUDE.template.md, expands snippet directives, and writes ordinary AGENTS.md and CLAUDE.md files beside the templates.

The template holds the source text, while the coding agent reads the generated file. agentsnippet uses the template itself instead of a separate configuration file. The coding agent needs no special support for includes.

A small example using the magic folder

Create a personal snippet at ~/.agents/agentsnippets/review.md:

## Review gate

Before committing, use the `$branch-review-subagent-loop` skill to review the
complete branch diff.

Then create AGENTS.template.md:

# Project instructions

This repository contains the application source.

<!-- @agentsnippet "@/review.md" -->

The @/ prefix points to the agentsnippet magic folder at ~/.agents/agentsnippets, so the same personal snippet can be included from templates in different projects.

Run agentsnippet from the project directory:

npx agentsnippet

It writes AGENTS.md with the directive replaced by the contents of review.md:

# Project instructions

This repository contains the application source.

## Review gate

Before committing, use the `$branch-review-subagent-loop` skill to review the
complete branch diff.

The same command also handles CLAUDE.template.md. If both templates exist in a directory, it generates both outputs in one run.

For a repository with templates in several folders, use recursive discovery:

npx agentsnippet -r

You can also check whether generated files are current without changing them:

npx --yes agentsnippet@latest --check -r

In CI, that command catches a changed template or snippet whose generated instruction file was not updated.

Let your coding agent manage agentsnippet

The repository also has an optional agentsnippet skill for coding agents. Install it globally for Codex:

npx skills add favoyang/agentsnippet -g -a codex -y

The skill teaches the agent to work from authoritative templates, generate the output files, and verify that they are current. When setting up agentsnippet in a repository, the agent can use the skill to decide whether an instruction belongs in the local template, the magic folder, or a remote source. It also checks for direct edits before generation so existing work is preserved.

Choose where shared snippets live

Use a relative path such as ./.agents/testing.md when the snippet belongs to the repository. agentsnippet resolves it from the file containing the include. Absolute paths and paths beginning with ~/ point to snippets elsewhere on the same machine, while the @/ magic folder gives personal snippets a shorter name. If the instructions need to travel with a team or across machines, use an HTTP or Git source. Snippets can include other snippets too.

The agentsnippet README documents installation, source formats, recursive discovery, CI checks, and the optional agent skill. The v1 specification covers the exact directive grammar, limits, error behavior, and security model.

Each project keeps a plain AGENTS.md or CLAUDE.md that compatible coding agents can read. The shared instructions have one home in reusable Markdown snippets. When a rule changes, I regenerate the ordinary instruction files instead of hunting down every copy by hand.

When the Model Eats the Harness

2026-07-25T00:00:00Z

This is a reading note on Thariq Shihipar's article, The new rules of context engineering for Claude 5 generation models.

Anthropic removed over 80% of Claude Code's system prompt for its newest models without a measurable loss on coding evaluations. Rules that once kept older models out of trouble had become constraints that newer models had to reason around. The new advice is looser: let the model use judgment, make tool interfaces expressive enough that they explain themselves, and load detailed guidance only when the work calls for it.

The obvious lesson is to simplify prompts. I think there is a stranger lesson for skills.

A skill library should sometimes shrink. Once a capability becomes common enough, the model may already know the routine. A long skill can collapse into a short phrase that wakes up behavior learned during training. At that point, the old instructions are scaffolding the model has to climb through before doing something it already knows how to do.

This is good for users. Nobody wants to remember a wall of prompt text just to trigger a familiar workflow. It also changes the competitive value of the harness.

A strong harness makes models easier to swap. If the shell handles the planning, tools, memory, and verification, the model underneath can be treated more like a component. A thinner harness moves more of the product's behavior into the model's weights. Competitors can inspect the shell, but they cannot see which habits the model learned or which plain words reliably bring those habits out.

That makes benchmarking harder too. An open-weight model can be tested inside a popular harness today, then look worse tomorrow because the harness was simplified around abilities that another model has absorbed. Part of the benchmark has moved behind the API, where competitors cannot inspect it.

From a model vendor's point of view, that is an attractive result. Users get shorter prompts and fewer conflicting rules. The vendor gets a product whose best behavior is harder to reproduce by swapping in another model. I do not know whether this is the strategy behind Anthropic's changes, but it is a useful side effect.

The awkward part is compatibility. Instructions that get in Claude 5's way may still be doing real work for an older Sonnet model. A short trigger that frees the new model could leave the older one guessing. Pruning skills therefore needs the same discipline as adding them: delete something, run the evaluations again, and keep a model-specific layer when the results still depend on it.

OpenAI has taken a somewhat different route. The open-source Codex CLI supports custom model providers, so the harness still has value when the model changes. It works more like an agent operating layer than a shell for one specific model. If native model judgment keeps improving, I still expect parts of that layer to get simpler.

My rule for skills is becoming clearer. Keep the ones that carry taste, private knowledge, or an important safety boundary. Cut the ones that merely explain a popular capability the model has already absorbed. The model may eat a popular harness the same way it eats a popular skill: by absorbing its familiar patterns until a much simpler trigger is enough.