Architecture-First Development

OpenFlows treats the plan as the primary deliverable. Before any implementation code is written, a FORGE agent produces a PLAN.md document and a SENTINEL agent reviews it into a CONTRACT.md. Only when the contract is AGREED does FORGE start writing code. This is the architecture-first philosophy in practice: engineering goes into the system, and software comes out.

The reason is pragmatic. Large language models are excellent at producing correct syntax and idiomatic boilerplate, but they are unreliable at deciding what to build and how the pieces should fit together. A vague prompt yields a plausible-looking program that is subtly wrong at the architectural level. A detailed plan - reviewed by a second model with a different provider - makes the hidden assumptions visible before they become bugs in the codebase.

Why OpenFlows Plans Before Executing

In a traditional workflow, the human engineer writes a plan inside their head, translates it into code, and submits a PR for review. The reviewer then tries to reverse-engineer the plan from the diff. OpenFlows inverts that order. The plan is externalised, reviewed, and agreed upon before the first commit. This has several consequences:

• Cheaper review: reviewing a two-page plan is faster than reviewing a two-hundred-file refactor. SENTINEL can reject a bad direction before any code is written.
• Traceability: every later decision can be traced back to PLAN.md. When a segment evaluation fails, the reason is usually that the implementation drifted from the plan.
• Parallelisation: once the plan is agreed, multiple FORGE workers can implement independent segments in parallel, each in its own Coder workspace.
• Recovery: if a workspace is destroyed or a node crashes, NEXUS can resume from the last completed segment because the plan and the state are both explicit.

PLAN.md and CONTRACT.md

PLAN.md is written by FORGE inside the ticket workspace. It is designed to be readable by both humans and the reviewing agent. A good plan includes the goal, constraints, a segment breakdown, the files and dependencies that will be touched, and any risks or open questions that need human escalation. The plan is the input to the rest of the pipeline.

# PLAN.md

## Goal
Add idempotency retries to the PocketFlow executor so that a node that transiently fails can be retried
without corrupting the SharedStore.

## Constraints
- The retry count must be persisted in the store, not in memory, so that a restarted node resumes from
the correct count.
- No node may be retried more than max_retries (default 3).
- A retry must be visible in the event ring for TUI observers.

## Segments
1. Add a retry_count field to NodeState in the SharedStore contract.
2. Update Flow::run() to increment the counter and short-circuit when max_retries is exceeded.
3. Emit a node_retry event on each retry and a node_failed event on exhaustion.
4. Add unit tests for the three retry paths: success-on-retry, exhaustion, and idempotency.

## Files touched
- src/flow.rs
- src/store/state.rs
- src/events.rs
- tests/flow_retries.rs

## Risks / open questions
- Should we back off between retries? If so, what policy? Default to immediate retry for now.

SENTINEL reads the plan and writes CONTRACT.md. The contract is not a commentary; it is a decision. The status is one of AGREED, CHANGES_REQUESTED, or REJECTED. If changes are requested, the feedback must be specific enough that FORGE can rewrite the plan without asking for clarification. If the plan is rejected, SENTINEL escalates to NEXUS, which marks the ticket AwaitingHuman.

# CONTRACT.md

## Status: CHANGES_REQUESTED

## Reasoning
The plan is directionally correct but under-specifies the retry policy. "Default to immediate retry"
is a hidden operational risk for external API calls.

## Required changes
1. Choose a backoff policy. Suggested: exponential backoff with jitter, capped at 30 seconds, or a
   configurable policy string in registry.json.
2. Add a test case that proves the store counter is not incremented twice for the same failure.
3. Document the event schema for node_retry and node_failed in the ADR that LORE will write.

## Approval criteria
SENTINEL will re-evaluate after FORGE updates PLAN.md with the backoff policy and the idempotency test.

The Artifacts of the Pipeline

Why Specs Matter When Models Make Boilerplate Cheap

The cost of writing boilerplate has collapsed. A model can generate a REST handler, a database migration, a React component, or a Terraform module in seconds. That speed is valuable, but it is also dangerous: it makes it easy to build the wrong thing quickly. The bottleneck in modern software engineering is no longer typing speed; it is decision quality.

A specification is a compressed decision. It captures the intent, the constraints, the trade-offs, and the success criteria. When FORGE writes PLAN.md, it is doing the expensive work: translating a vague issue into a concrete design. The code that follows is, in a sense, a rendering of the spec. SENTINEL's job is to make sure the rendering is faithful, not to invent the design on the fly.

This division of labour mirrors the best human engineering teams. Architects produce a design; implementers build to it; reviewers verify conformance. OpenFlows simply encodes that division into a repeatable, observable machine process. The human team retains control over the design; the agents handle the execution and the mechanical review.

The Architecture-First Flow

Design Principles

When the Plan is Wrong

No plan survives contact with implementation. OpenFlows handles this by reviewing every segment. If FORGE discovers during segment 3 that segment 2's design is unworkable, it does not silently change direction. It updates PLAN.md, asks SENTINEL to re-approve the affected segments, and only then continues. The contract is a living document, but it is always explicit.

When the issue itself is ambiguous - the user story is incomplete, the acceptance criteria conflict, or the change touches a security boundary - OpenFlows does not guess. It writes a STATUS.json with status: AwaitingHuman and stops. The escalation is visible, auditable, and recoverable. Once a human clarifies the requirement, NEXUS resumes the pipeline at the planning phase.