public realm, not as the canonical store.
Flow Map
| Goal | Use this flow |
|---|---|
| Ordinary agent work | The Standard Agent Loop |
| Human approval before landing | Human Review Before Publication |
| Two or more agents coordinating | Multiple Agents On Related Work |
| Same project on another device | Cross-Device Handoff |
| Docs-only updates | Documentation-Only Work |
| CLI changes and release binaries | Release Binary Workflow |
| Validate what GitHub will see | Public Projection Validation |
| Push the public mirror | GitHub Mirror Workflow |
| Experiment without publishing | Local Exploration Without Publication |
| Fix broken CI or export state | Emergency Fix Workflow |
| Keep work outside the public mirror | Maintainer-Only Work |
| Deploy these docs | Deployment Workflow For This Docs Site |
The Standard Agent Loop
Use this when an agent is doing ordinary source work.- The agent has a named work context instead of an implicit dirty tree.
- Each write carries a reason.
- Checkpoints preserve progress without turning every step into public history.
- Publication is a clear visibility transition.
- Remote sync validates the public projection before GitHub receives it.
Human Review Before Publication
Use this when the agent should prepare work but a human decides whether it lands.Multiple Agents On Related Work
Use claims and dependencies when two agents are active.Cross-Device Handoff
Use GitHub when another device only needs the public project:.glyph/ while nothing is writing to it:
.glyph/store.db at the same time.
Documentation-Only Work
Use this for docs updates.Release Binary Workflow
Use this when changing the CLI in a way that should produce downloadable binaries.main push and creates GitHub Releases on v* tags.
For a release:
Public Projection Validation
Use this before any operation where the exported public tree matters.glyph.yaml:
public, the check fails locally before GitHub Actions sees the broken export.
GitHub Mirror Workflow
Use this when publishing public-compatible work to GitHub.remote sync does four things:
- Runs public export checks unless
--skip-checksis passed. - Materializes the
publicrealm. - Creates a clean Git repository from that projection.
- Pushes the generated Git commit to the configured remote.
--skip-checks sparingly:
Local Exploration Without Publication
Use this when an agent needs to experiment.Emergency Fix Workflow
Use this when a public build or docs deploy is broken.Maintainer-Only Work
Use a non-public realm when the content should not be exported.public.
Deployment Workflow For This Docs Site
For this repository:- Runs
npx mintlify@latest validate. - Runs
npx mintlify@latest broken-links --check-anchors --check-redirects. - Exports the docs to a zip file.
- Unpacks the static export.
- Refuses to deploy if the export contains Glyph store files or Go source.
- Deploys to Cloudflare Pages with Wrangler.
Choosing squash Or preserve
Use squash for most public work:
preserve when the sequence matters:
- Security-sensitive review history.
- Multi-agent handoff.
- A design investigation where the path matters.
- Auditable maintainer-only decisions.
- Documentation cleanup.
- Simple CLI changes.
- Routine bug fixes.
- Generated artifact updates.