First Issue Walkthrough: Lifecycle

This page covers the lifecycle steps from issue detection through implementation. For the overview and prerequisites, see the main walkthrough page.

Step 1: Create the GitHub issue

The trigger is intentionally simple. Open the repository on GitHub, click New issue, and write a title and description that a senior engineer could act on. The agents read the issue body as the primary source of truth, so clarity matters.

Step 2: NEXUS detects the issue

NEXUS is the orchestrator. It polls the GitHub Issues API on a regular interval and also accepts webhook events. When it sees an open issue that has not yet been ingested, it creates a ticket in the SharedStore with status open.

[nexus] discovered issue #42: "Add rate-limiting middleware" -> ticket-42 (status: open)

NEXUS then runs reconcile(). This is the heart of the orchestrator's self-healing behavior: it checks for orphaned tickets, stale workers, unmerged PRs, and inconsistent state, and it resumes the correct phase.

Step 3: NEXUS provisions a workspace

Once a ticket is open, NEXUS looks for an idle FORGE worker. The worker is not a long-running process; it is a Coder workspace that is provisioned on demand.

The workspace contains:

• The repository clone.
• The openflows-harness binary for typed SharedStore access.
• The role-specific skills and MCP servers listed in registry.json v2.

The workspace does not contain:

• Any AI model software.
• Any LLM API keys.
• Any GitHub tokens or credentials.

[nexus] assigned ticket-42 to worker forge-7a3f
[nexus] provisioning workspace ws-forge-7a3f from template openflows-forge
[workspace] ws-forge-7a3f ready, harness installed

Step 4: FORGE writes PLAN.md and SENTINEL writes CONTRACT.md

This is the architecture-first checkpoint. FORGE enters the workspace, reads the issue, inspects the repository, and writes PLAN.md. The plan breaks the issue into numbered segments, each with a clear objective and acceptance criteria.

SENTINEL then reads PLAN.md and writes CONTRACT.md. The contract is either AGREED or CHANGES_REQUESTED. This cycle repeats until agreed.

# PLAN.md for ticket-42
## Segment 1: Data model
- Add `RateLimitConfig` struct with burst, period, and enabled fields.

## Segment 2: Middleware implementation
- Implement `RateLimitLayer` in `src/middleware/rate_limit.rs`.

## Segment 3: Tests
- Unit tests for token-bucket logic.
- Integration tests for HTTP middleware with mocked Redis.

## Acceptance criteria
- All existing tests pass.
- No secrets or tokens in logs.

[forge] writing PLAN.md for ticket-42
[sentinel] reviewing PLAN.md for ticket-42
[sentinel] CONTRACT.md: CHANGES_REQUESTED - segment 3 needs property-based tests
[forge] revising PLAN.md for ticket-42
[sentinel] CONTRACT.md: AGREED for ticket-42

Step 5: FORGE implements the segments

With the contract agreed, FORGE begins implementing the segments in order. Each segment is a small, reviewable unit of work. FORGE writes code, adds tests, and commits the segment to a branch named after the ticket.

After each segment, FORGE updates the ticket status in the SharedStore. The status is something like segment-1, segment-2, and so on.

[forge] starting segment-1 for ticket-42
[forge] committed segment-1: rate-limit data model
[forge] updating STATUS.json -> segment-1
[forge] starting segment-2 for ticket-42
[forge] committed segment-2: rate-limit middleware layer
[forge] updating STATUS.json -> segment-2