Issue Viewer

AI Workflow Without Losing Your Mind


Michal Franc · 2026

This is me for the past few months

[ working.gif ]

Working with agents intensively...

There is definitely a visible change since Opus 4.6

🎮 Game (Godot)

Hobby project — roguelike / RPG, worked on evenings and weekends.

mfranc.com/game


🐸 Toadie

Personal assistant powered by Claude Code — available from phone, watch, voice.

mfranc.com/blog/toadie


Working with 5–6 agents simultaneously is...

context switching

re-explaining the same things over and over

keeping track of what each agent is doing

fixing what the previous agent broke

wondering if any of it is actually coherent


Brain Fry

This was the flow for a while

Evolution

GitHub Issues

API-dependent · online only · overkill for hobby projects

↓

Markdown files · locally hosted

Plain .md files with YAML frontmatter · no API · no internet · full control

issues/ combat/ 42.md pathfinding.md toadie/ watch-support.md voice-commands.md

each file = one issue · git tracked · agent readable

Agents could just modify the .md files directly — no API, no tooling, just plain text.

But this created new problems

No control

Agents could modify any .md file freely — change status, overwrite content, mark things done without actually doing them.

Still babysitting

I still had to watch every agent session. Without guardrails, mistakes were silent and hard to catch.

Power without structure = chaos

The freedom that made agents useful also made them unpredictable.

How to add control?

Well... skills. Sure thing.

Claude Code Skills

Reusable prompt templates that agents can invoke — with defined inputs, outputs, and guardrails built in.

Instead of free-form file edits, agents call a skill. The skill enforces the rules.


But just telling agents how to nicely modify .md files is not enough.

But... skills are non-deterministic

The bigger the context, the less predictable the agent gets.

Instruction overload

LLMs reliably follow ~150–200 instructions.

Claude Code's system prompt already uses ~50.

Every instruction you add competes for attention — and compliance decreases uniformly as count grows.

Lost in the Middle

LLMs have a U-shaped attention curve — they recall the beginning and end well, but miss the middle.

Your context file sits at the start — make every line count.

More instructions ≠ more control.

Is there a better way?

What if we stop fighting non-determinism — and contain it instead?

Mix

non-deterministic LLMs

+

deterministically behaving tools


Enter issue-cli

issue-cli in action

$ issue-cli done pathfinding ✗ unchecked items remain: [ ] add unit tests Complete checkboxes before marking done.
$ issue-cli check pathfinding "add unit tests" ✓ checked off $ issue-cli done pathfinding ✓ status → done · assignee cleared
$ issue-cli transition pathfinding --to testing ✓ status → testing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Next steps: 1. Run automated tests 2. Add ## Test Plan section (### Automated / ### Manual) 3. issue-cli comment pathfinding --text "tests: all passing" 4. issue-cli transition pathfinding --to documentation ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

But why hardcode the rules?

Projects define their own workflow — validations, prompts, side effects — in workflow.yaml

statuses: - name: "in design" prompt: | Turn the problem into checklists, assumptions, and open questions. Ask for backlog approval before attempting the transition. transitions: - from: "in design" to: "backlog" actions: - type: "validate" rule: "has_checkboxes" - type: "append_section" title: "Acceptance Criteria"

Per-status prompts

Each status tells the agent what to do — injected automatically at dispatch time.

Transition validations

Must have checkboxes? Body not empty? Blocks the move if rules aren't met.

Side effects

Auto-append sections, clear assignee, inject checklists on transition.

Workflow Designer

Managing statuses, transitions, validations, and side effects in YAML by hand gets painful.

Example flow

💡
idea
👤 I have an idea
🤖
in design
agent clarifies,
writes checkboxes
👤
backlog
I approve design,
agent unclaimed
🤖
in progress
agent implements,
checks off items
🤖
testing
agent writes
test plan
👤
human-testing
I play-test
the feature
🤖
documentation
agent updates
the docs
✅
done
shipped
🤖 agent 👤 human approves / verifies

Building Blocks

Base Prompt

Injected to every agent session. Defines who the agent is, project context, and global rules.

Loaded from CLAUDE.md

Status Prompt

Injected on each status. Tells the agent exactly what to do at this stage of the workflow.

Defined in workflow.yaml

Inject Prompt

Optional extra context injected at dispatch — issue body, metadata, related issues.

Per-issue override

Validate

Blocks a transition if conditions aren't met — has_checkboxes, body_not_empty, assignee set.

Hard stops, not suggestions

Append Sections

Automatically adds structured sections to the issue on transition — checklists, test plans, docs stubs.

Side effect on transition

Human Approval

Certain statuses require a human to approve before the agent can proceed. Agent waits.

backlog, human-testing

RogueTech examples

Real issue in the project:

title: "stress volume system redesign" status: in design system: MechLab version: 0.1 Replace slots+stress model with a visible internal-layout system. Hulls define shaped build space. Items occupy rectangular footprints (1x2, 2x2, 2x3). - [ ] Design layout grid system - [ ] Hull defines internal sections - [ ] Weapons have footprint costs - [ ] Mount/arc choices expand footprint

Status prompt injected to agent:

# in design prompt Review the relevant docs, code, and existing content before proposing changes. Turn requirements into explicit checklists. Surface assumptions, risks, edge cases, and required human input clearly. Keep the design focused on what will actually be implemented.

Validation on transition → backlog:

- type: validate rule: has_checkboxes - type: validate rule: body_not_empty

Base Prompt — issue-cli process

== AI-Native Project Viewer == You are working with a markdown-based issue tracker. Issues are .md files in issues/<System>/ directories. == Rules == - Always use 'start' to begin work - Never skip statuses - Always update docs before marking done - Use checkboxes [x] to track subtasks == IMPORTANT: Command output == - NEVER suppress stderr (no 2>/dev/null) - ALWAYS read the full output — it contains next steps - If a command fails, fix it, don't retry
== When you pick up an issue == 1. issue-cli start <slug> claims it, moves to in-progress 2. Do the work, check off items 3. Add ## Test Plan section 4. issue-cli transition <slug> --to testing 5. issue-cli comment <slug> "tests: ..." 6. issue-cli transition <slug> --to docs 7. issue-cli done <slug> == Quick start == issue-cli next --version 0.1 issue-cli start <slug> issue-cli done <slug>

Agent runs issue-cli process first — sets rules, workflow, and step-by-step guidance for the whole session.

Three Prompts, Three Roles

Base Prompt — always injected
Who the agent is, how the project works, global rules, tooling conventions. Sets the foundation for every session regardless of what issue is being worked on.
issue-cli process
Status Prompt — injected per status
What to do right now at this stage. Changes with every status transition. Keeps the agent focused on the current phase without re-explaining the whole workflow.
defined in workflow.yaml · injected at dispatch
Inject Prompt — defined in workflow.yaml
Injects additional actions or instructions at a specific transition point. Used to tell the agent to do something extra — append a section, run a check, follow a specific pattern for this transition.
type: inject_prompt · fires on transition

Base Workflow vs Subsystem Overlay

Base Workflow

Defines statuses, transitions, validations, and prompts for the whole project. Every issue follows this by default.

statuses: idea → in design → backlog → in progress → testing → human-testing → done transitions: - from: backlog → in progress validate: has_assignee validate: human_approved

Subsystem Overlay

Per-system overrides that add extra instructions for specific domains — injected on top of the base workflow.

systems: Combat: transitions: - from: backlog → in progress inject_prompt: "Build a reproducible shooter-vs-target scenario and validate outcomes statistically." Campaign: transitions: - from: in design → backlog inject_prompt: "Identify ALL code paths that create or modify UnitData..."

Base handles the generic flow · subsystem overlays inject domain expertise at the right moment

Composed, Just-in-Time Prompt

Every agent dispatch assembles a fresh, precise context from its parts.

Base Prompt
who, what, rules
+
Status Prompt
what to do now
+
Subsystem Overlay
domain expertise
+
Inject Prompt
extra actions
+
Issue Content
the actual task
↓
Composed Context
Precise · minimal · assembled at dispatch time
Agent knows exactly what to do, in this project, at this status, for this issue.

No re-explaining. No guessing. No babysitting.

Validations & Human Approval

Not just rules — a signal to the agent that something went wrong.

Validations

Block a transition when the agent missed something — no checkboxes, empty body, test plan absent.

The CLI returns a clear error. The agent reads it, self-corrects, and retries. No human needed.

Human Approval

Hard stops at key gates — backlog, human-testing. Agent cannot proceed until a human explicitly approves in the UI.

Catches non-deterministic drift before it compounds.

Why this matters

LLMs are non-deterministic. They will occasionally skip steps, hallucinate progress, or mark things done prematurely.

Validations and approvals are checkpoints that surface undeterministic behavior before it causes damage — without requiring you to watch every session.

The system catches the agent. Not you.

But wait... there is more

If agents already use issue-cli as their primary tool — why not extend it?

🐛 Bug Reports

Agent hits an unexpected failure during implementation? It files a bug issue itself.

issue-cli report-bug "description"

No context lost. Filed with full context while it's fresh.

📓 Retros

Agent reflects on what went wrong, what was unclear, what slowed it down — and writes it up.

issue-cli retrospective <slug> --body "..."

Structured feedback loop from the agent back to you.


The agent isn't just a worker — it becomes a participant in the workflow.

A Self-Reinforcing System

A bot reviews retros and bugs — and feeds findings back into the workflow.

🤖
Agent works
implements issues
→
🐛 📓
Files bugs & retros
via issue-cli
→
🤖
Bot reviews
reads retros & bugs
→
⚙️
Updates workflow
prompts, validations
→
🤖
Agent improves
better context next time

The system gets smarter over time — without you manually tuning it.

Real Retros from RogueTech

stress-volume-system-redesign idea · 2026-04-07

Tooling friction: issue-cli start is listed as step 1 in generic instructions, but it cannot work from idea status — the workflow should branch earlier for idea issues and direct the agent to gather clarification first.

weapon-mount-types-with-firing-arcs in progress · Equipment

Subsystem gap: Equipment guidance should explicitly direct agents to current arc/stress/chassis seams and existing structure family files earlier so design work starts from the real implementation surface.

Tooling bug: issue-cli check reported success for multiple items but issue-cli checklist remained stale immediately afterward — hard to know when status is truly ready for transition.

Agent surfaces its own blind spots → feeds directly into workflow and tooling improvements.

issue-cli — Agent First

Designed for AI consumption. If we notice agents want to do things a certain way — we just add it and get out of the way.

Aliases — because agents use natural names:

context <slug> alias: show → agents naturally say "show me the issue" start <slug> *** USE THIS TO BEGIN WORK *** claims + transitions in one command → agents kept doing claim + transition separately, so we merged it
check <slug> "text match" → agents would grep for checkbox text and edit .md files directly, so we gave them a proper command

AI-native design principles:

Every output contains next steps

Commands tell the agent exactly what to do next. No silence after success.

Errors are actionable

Failures explain why and what to fix — not just exit code 1.

Never get in the way

If an agent finds a workaround, that workaround becomes a command.

This tool will likely end up with tens of commands doing similar things in slightly different ways — and that's completely fine.

Launch agents from UI

Approve an issue, pick Claude or Codex — spins up a terminal, pastes the composed prompt, agent starts immediately.