First Issue Walkthrough
This page is a frame-by-frame walkthrough of what happens when you create a GitHub issue in a repository that OpenFlows is watching. It follows the architecture-first flow from the first line of the issue body to the final workspace teardown, with the expected logs at each step and the exact commands you can run to watch the process in real time.
By the end of this guide you will understand how NEXUS detects work, how FORGE plans and implements it, how SENTINEL reviews every segment adversarially, how VESSEL merges green pull requests, and how LORE documents the outcome.
Architecture-first means plan before code
CONTRACT.md. The plan is the product. The code is the consequence.
Prerequisites
Before you create an issue, ensure the OpenFlows stack is running and the tenant is linked to the target repository.
- Coder, Redis, and the OpenFlows orchestrator are running.
- The orchestrator has a valid
CODER_SESSION_TOKENand GitHub OAuth App configured. - You have run the bootstrap command and added the tenant:
bash
./scripts/prod.sh bootstrap ./scripts/prod.sh tenant owner/repo --name my-team
- The
orchestration/agent/registry.jsonv2 file defines roles, skills, and model routing.
Lifecycle overview
The lifecycle of a single issue is a deterministic sequence of phases. Each phase is owned by a specific agent, and each phase writes a well-known artifact into the workspace or the SharedStore.
| Step | Phase | Owner | What happens | Artifact / state change |
|---|---|---|---|---|
| 1 | Trigger | You | Create a GitHub issue describing the change, bug, or feature. | GitHub issue #N opened. |
| 2 | Detection | NEXUS | Polls the GitHub Issues API or receives a webhook event. | Ticket created in SharedStore with status open. |
| 3 | Assignment | NEXUS | Selects an idle FORGE worker and binds the ticket. | SharedStore worker_slots updated; ticket status becomes assigned. |
| 4 | Workspace provisioning | NEXUS + Coder | Provisions an ephemeral Coder workspace from the openflows-forge template. | Workspace URL reported; harness installed; no AI keys or GitHub tokens inside. |
| 5 | Planning | FORGE | Reads the repository, issue, and context; writes PLAN.md. | STATUS.json reports planning; PLAN.md contains segments and acceptance criteria. |
| 6 | Plan review | SENTINEL | Reviews PLAN.md and writes CONTRACT.md (AGREED or CHANGES_REQUESTED). | If changes requested, FORGE revises plan. |
A good issue contains
- Context - why the change is needed, links to related issues or ADRs.
- Goal - a single sentence describing what success looks like.
- Constraints - non-functional requirements such as performance or security.
- Acceptance criteria - a checklist that the reviewer can verify against.
You do not need to write a plan. FORGE will write PLAN.md. You do not need to write tests.
SENTINEL will insist on them. You do not need to assign the issue. NEXUS does that automatically.
Labels and milestones are optional hints
good first issue or bug label may
influence routing decisions, especially if the registry.json routing table maps labels to specialized worker templates.
Continue reading