Skip to content
Foundry
Esc
↑↓navigate↵open⌘Jpreview
On this page

Take an issue

Choose a ready issue and define what a successful change must prove.

Development takes one accepted issue through planning, implementation, review, and delivery. Follow these chapters in order to build the local workflow.

issue → plan → implement → test and review → approve → publish
                  ↑              │
                  └── revisions ─┘

Before you start

  • Complete the quickstart.
  • Use a clean local Git clone with an origin on GitHub. The sample publishes branches to that repository, so use one where you have permission to push.
  • Install and authenticate gh, plus Claude Code or Codex. Confirm that gh repo view identifies this checkout and Git can fetch and push origin.
  • Install zod@4.4.3 in the automation project.
  • Use a project with a committed bun.lock and a working bun test command. Change the verifier’s commands for another stack.

The first example uses GitHub Issues. Each helper lives under .foundry/marbles/_factory/; the launch modules beside that folder import it. Follow the chapters in order and replace factory.ts where instructed. Expand each complete module to copy its source; the short launch modules stay visible so you can follow the workflow.

Run one writer per issue at a time. The sample uses local artifacts and Git branches; it does not coordinate independent machines. Start manually, then enable the schedules after the cycle works in your repository.

marbles --dry-run list checks that the definitions load. A dry run of the workflow cannot exercise this cycle because it substitutes command output, including the issue JSON and Git commit IDs that these steps require.

Choose the issue

Choose one small GitHub issue. The issue needs a problem statement and acceptance criteria that a reviewer can check. For example:

## Problem
The README lists commands that no longer match package.json.

## Acceptance criteria
- [ ] Documented project scripts match package.json.
- [ ] A new contributor can install dependencies using the documented command.
- [ ] The README identifies the command that runs the test suite.

The example reads checkbox items under ## Acceptance criteria. Existing checkmarks do not waive verification. Each candidate must supply new evidence.

Read the issue before giving it to an agent:

gh issue view 42 --repo OWNER/REPOSITORY --json number,title,body,url,updatedAt,state

Replace the repository and issue number throughout the walkthrough. The GitHub CLI reference lists the available fields.

Decide whether it is ready

If the request lacks a reproduction, intended behavior, or acceptance criteria, clarify it in the issue first. Break unrelated requests into separate issues. For scheduled discovery, add a factory-ready label only after this review.

An incident can enter through on-call before anyone knows the fix. Investigation should produce evidence and a next action. Implementation starts once that work becomes a ready issue.

Next: Keep a work log captures this issue and gives every later stage the same record.

Was this page helpful?