Develop: Spec-Driven Feature Loop

# Title: Develop: Spec-Driven Feature Loop
#
# Public workflow: turn a feature spec into a finished, verified change through a
# developer/evaluator refine loop with a real build/test gate inside the loop.
# Showcases the loop pattern. Public roles only.

name        = "develop"
description = "Gathers context for a feature spec, then iterates a developer/evaluator loop with a real build/test gate until the evaluator approves, then summarizes the change."

# ── 1. Spec → context ────────────────────────────────────────────────────────
[[steps]]
name    = "context"
role    = "developer:context"
session = "fresh"
retries = 1
prompt  = """
Take the user spec and gather the most important context to begin development.

<spec>
{{input}}
</spec>

Locate the exact files, functions, and line ranges to touch and the existing
patterns to reuse. Identify the project's verification command (test / build /
lint) so the developer can prove the change works. State what is out of scope.

Output only the refined task with its <context> pinpoints — no implementation plan.
"""

# ── 1b. Upstream research (reported issues) ──────────────────────────────────
[[steps]]
name    = "upstream"
role    = "assistant:researcher"
session = "fresh"
retries = 1
prompt  = """
The spec below may be a reported issue (bug report / feature request) against a
project with a public home. If so, locate the upstream issue, its linked
discussion, and any existing fix or merged change, and produce implementation
contract notes: the chosen approach; exact API names, signatures, parameter
names and call conventions; which layer owns the primitive; and EVERY file the
upstream change touches. Cite what you found. If the project is private or
nothing public exists, reply exactly: NO UPSTREAM FOUND.

<spec>
{{input}}
</spec>
"""

# ── 2. Developer/evaluator refine loop ───────────────────────────────────────
[[steps]]
name           = "development"
loop           = true
max_iterations = 3
exit_when      = { output = "evaluator", matches = '(?m)^VERDICT: APPROVED' }

  [[steps.run]]
  name    = "developer"
  role    = "developer:general"
  session = "continue"
  retries = 1
  prompt  = """
We are working on the following spec:
<spec>
{{input}}
</spec>

Pinpoints and verification command from context:
<context>
{{context}}
</context>

Upstream contract notes — when present, mirror them exactly (names, signatures,
call conventions, owning layer, every touched surface):
<upstream>
{{upstream}}
</upstream>

Implement the change fully autonomously. Fix causes, not symptoms — no
workarounds, suppressed errors, or skipped tests unless the spec explicitly
sanctions one. Then run the project's verification command (tests / build /
lint / typecheck) and iterate until it passes.

End your response with the exact command you ran and its output as evidence the
check passes. Output only the work and that evidence — no preamble.
"""

  [[steps.run]]
  name    = "brief"
  role    = "developer:brief"
  session = "fresh"
  retries = 1
  prompt  = """
Read the original spec and the current unstaged git changes, then produce a
brief of what the diff actually does versus what the spec asked for.

<spec>
{{input}}
</spec>

Developer evidence (verification command + output):
<evidence>
{{developer}}
</evidence>

Output only the brief.
"""

  [[steps.run]]
  name    = "evaluator"
  role    = "developer:general"
  session = "fresh"
  prompt  = """
You are grading a code-generation run in a fresh session. You see only the spec,
the developer's verification evidence, and an independent brief of the diff — not
the developer's reasoning. Judge conformance to the spec.

User spec:
<spec>
{{input}}
</spec>

Developer evidence (verification command + output):
<evidence>
{{developer}}
</evidence>

Independent brief of the diff:
<brief>
{{brief}}
</brief>

Check each stated spec requirement: is it met by the diff, and does the
verification command actually pass in the evidence? Flag ONLY gaps that affect
correctness or a stated spec requirement, or a missing/failing check. Do not
request style changes, speculative robustness, or criteria the spec never stated.

If a requirement is unmet or the check did not pass, list the concrete gaps —
this goes directly to the developer with all original context.

End with exactly one line: VERDICT: APPROVED or VERDICT: REVISE. Nothing after it.
"""

# ── 3. Outcome — honest branch on the loop's final verdict ───────────────────
[[steps]]
name        = "outcome"
conditional = true
condition   = { output = "evaluator", matches = '(?m)^VERDICT: APPROVED' }
on_match    = ["summary"]
on_no_match = ["stalled"]

  [[steps.run]]
  name    = "summary"
  role    = "developer:brief"
  session = "fresh"
  prompt  = """
Read the user spec and the implementation in the current unstaged git changes,
then produce a concise briefing of spec-versus-diff for the human reviewer.

<spec>
{{input}}
</spec>

Output only the briefing.
"""

  [[steps.run]]
  name    = "stalled"
  role    = "developer:brief"
  session = "fresh"
  prompt  = """
The development loop hit its iteration cap WITHOUT evaluator approval — do not
present this as success. Read the spec and the current unstaged changes, then
report for a human decision: what was implemented and verified, and every gap
the evaluator still flags.

<spec>
{{input}}
</spec>

<last_evaluation>
{{evaluator}}
</last_evaluation>

Start with exactly: `DID NOT CONVERGE — human review required.`
"""