fix: refactor: architect pitching should be bash-driven with stateless model calls (#490)
This commit is contained in:
Agent
parent
80e19f8e51
commit
b11c4cca15
2 changed files with 163 additions and 587 deletions
|
|
@ -10,12 +10,12 @@
|
|||
# 2. Precondition checks: skip if no work (no vision issues, no responses)
|
||||
# 3. Load formula (formulas/run-architect.toml)
|
||||
# 4. Context: VISION.md, AGENTS.md, ops:prerequisites.md, structural graph
|
||||
# 5. Bash-driven design phase:
|
||||
# a. Fetch reviews API for ACCEPT/REJECT detection (deterministic)
|
||||
# b. REJECT: handled entirely in bash (close PR, delete branch, journal)
|
||||
# c. ACCEPT: invoke claude with human guidance injected into prompt
|
||||
# d. Answers: resume saved session with answers injected
|
||||
# 6. New pitches: agent_run(worktree, prompt)
|
||||
# 5. Stateless pitch generation: for each selected issue:
|
||||
# - Fetch issue body from Forgejo API (bash)
|
||||
# - Invoke claude -p with issue body + context (stateless, no API calls)
|
||||
# - Create PR with pitch content (bash)
|
||||
# - Post footer comment (bash)
|
||||
# 6. Response processing: handle ACCEPT/REJECT on existing PRs
|
||||
#
|
||||
# Precondition checks (bash before model):
|
||||
# - Skip if no vision issues AND no open architect PRs
|
||||
|
|
@ -60,7 +60,7 @@ SCRATCH_FILE_PREFIX="/tmp/architect-${PROJECT_NAME}-scratch"
|
|||
WORKTREE="/tmp/${PROJECT_NAME}-architect-run"
|
||||
|
||||
# Override LOG_AGENT for consistent agent identification
|
||||
# shellcheck disable=SC2034 # consumed by agent-sdk.sh and env.sh log()
|
||||
# shellcheck disable=SC2034 # consumed by agent-sdk.sh and env.sh
|
||||
LOG_AGENT="architect"
|
||||
|
||||
# Override log() to append to architect-specific log file
|
||||
|
|
@ -91,448 +91,12 @@ load_formula_or_profile "architect" "$FACTORY_ROOT/formulas/run-architect.toml"
|
|||
build_context_block VISION.md AGENTS.md ops:prerequisites.md
|
||||
|
||||
# ── Prepare .profile context (lessons injection) ─────────────────────────
|
||||
formula_prepare_profile_context
|
||||
|
||||
# ── Build structural analysis graph ──────────────────────────────────────
|
||||
build_graph_section
|
||||
|
||||
# ── Read scratch file (compaction survival) ───────────────────────────────
|
||||
SCRATCH_CONTEXT=$(read_scratch_context "$SCRATCH_FILE")
|
||||
SCRATCH_INSTRUCTION=$(build_scratch_instruction "$SCRATCH_FILE")
|
||||
|
||||
# ── Build prompt footer ──────────────────────────────────────────────────
|
||||
build_sdk_prompt_footer
|
||||
|
||||
# ── Design phase: bash-driven review detection ────────────────────────────
|
||||
# Fetch PR reviews from Forgejo API (deterministic, not model-dependent).
|
||||
# Sets global output variables (not stdout — guidance text is often multiline):
|
||||
# REVIEW_DECISION — ACCEPT|REJECT|NONE
|
||||
# REVIEW_GUIDANCE — human guidance text (review body or comment text)
|
||||
# Args: pr_number
|
||||
fetch_pr_review_decision() {
|
||||
local pr_num="$1"
|
||||
REVIEW_DECISION="NONE"
|
||||
REVIEW_GUIDANCE=""
|
||||
|
||||
# Step 1: Check PR reviews (Forgejo review UI) — takes precedence
|
||||
local reviews_json
|
||||
reviews_json=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls/${pr_num}/reviews" 2>/dev/null) || reviews_json='[]'
|
||||
|
||||
# Find most recent non-bot review with a decision state
|
||||
local review_decision review_body
|
||||
review_decision=$(printf '%s' "$reviews_json" | jq -r '
|
||||
[.[] | select(.user.login | test("bot$"; "i") | not)
|
||||
| select(.state == "APPROVED" or .state == "REQUEST_CHANGES")]
|
||||
| last | .state // empty
|
||||
' 2>/dev/null) || review_decision=""
|
||||
review_body=$(printf '%s' "$reviews_json" | jq -r '
|
||||
[.[] | select(.user.login | test("bot$"; "i") | not)
|
||||
| select(.state == "APPROVED" or .state == "REQUEST_CHANGES")]
|
||||
| last | .body // empty
|
||||
' 2>/dev/null) || review_body=""
|
||||
|
||||
if [ "$review_decision" = "APPROVED" ]; then
|
||||
REVIEW_DECISION="ACCEPT"
|
||||
REVIEW_GUIDANCE="$review_body"
|
||||
return 0
|
||||
elif [ "$review_decision" = "REQUEST_CHANGES" ]; then
|
||||
REVIEW_DECISION="REJECT"
|
||||
REVIEW_GUIDANCE="$review_body"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# Step 2: Fallback — check PR comments for ACCEPT/REJECT text
|
||||
local comments_json
|
||||
comments_json=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/issues/${pr_num}/comments" 2>/dev/null) || comments_json='[]'
|
||||
|
||||
# Find most recent comment with ACCEPT or REJECT (case insensitive)
|
||||
local comment_body
|
||||
comment_body=$(printf '%s' "$comments_json" | jq -r '
|
||||
[.[] | select(.body | test("(?i)^\\s*(ACCEPT|REJECT)"))] | last | .body // empty
|
||||
' 2>/dev/null) || comment_body=""
|
||||
|
||||
if [ -n "$comment_body" ]; then
|
||||
if printf '%s' "$comment_body" | grep -qiE '^\s*ACCEPT'; then
|
||||
REVIEW_DECISION="ACCEPT"
|
||||
# Extract guidance text after ACCEPT (e.g., "ACCEPT — use SSH approach" → "use SSH approach")
|
||||
REVIEW_GUIDANCE=$(printf '%s' "$comment_body" | sed -n 's/^[[:space:]]*[Aa][Cc][Cc][Ee][Pp][Tt][[:space:]]*[—:–-]*[[:space:]]*//p' | head -1)
|
||||
# If guidance is empty on first line, use rest of comment
|
||||
if [ -z "$REVIEW_GUIDANCE" ]; then
|
||||
REVIEW_GUIDANCE=$(printf '%s' "$comment_body" | tail -n +2)
|
||||
fi
|
||||
elif printf '%s' "$comment_body" | grep -qiE '^\s*REJECT'; then
|
||||
REVIEW_DECISION="REJECT"
|
||||
REVIEW_GUIDANCE=$(printf '%s' "$comment_body" | sed -n 's/^[[:space:]]*[Rr][Ee][Jj][Ee][Cc][Tt][[:space:]]*[—:–-]*[[:space:]]*//p' | head -1)
|
||||
if [ -z "$REVIEW_GUIDANCE" ]; then
|
||||
REVIEW_GUIDANCE=$(printf '%s' "$comment_body" | tail -n +2)
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
}
|
||||
|
||||
# Handle REJECT entirely in bash — no model invocation needed.
|
||||
# Args: pr_number, pr_head_branch, rejection_reason
|
||||
handle_reject() {
|
||||
local pr_num="$1"
|
||||
local pr_branch="$2"
|
||||
local reason="$3"
|
||||
|
||||
log "Handling REJECT for PR #${pr_num}: ${reason}"
|
||||
|
||||
# Close the PR via Forgejo API
|
||||
curl -sf -X PATCH -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
-H 'Content-Type: application/json' \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls/${pr_num}" \
|
||||
-d '{"state":"closed"}' >/dev/null 2>&1 || log "WARN: failed to close PR #${pr_num}"
|
||||
|
||||
# Delete the branch via Forgejo API
|
||||
if [ -n "$pr_branch" ]; then
|
||||
curl -sf -X DELETE -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/git/branches/${pr_branch}" >/dev/null 2>&1 \
|
||||
|| log "WARN: failed to delete branch ${pr_branch}"
|
||||
fi
|
||||
|
||||
# Remove in-progress label from the vision issue referenced in the PR
|
||||
local pr_body
|
||||
pr_body=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls/${pr_num}" 2>/dev/null | jq -r '.body // ""') || pr_body=""
|
||||
local vision_ref
|
||||
vision_ref=$(printf '%s' "$pr_body" | grep -oE '#[0-9]+' | head -1 | tr -d '#') || vision_ref=""
|
||||
|
||||
if [ -n "$vision_ref" ]; then
|
||||
# Look up in-progress label ID
|
||||
local label_id
|
||||
label_id=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/labels" 2>/dev/null | jq -r '.[] | select(.name == "in-progress") | .id' 2>/dev/null) || label_id=""
|
||||
if [ -n "$label_id" ]; then
|
||||
curl -sf -X DELETE -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/issues/${vision_ref}/labels/${label_id}" >/dev/null 2>&1 \
|
||||
|| log "WARN: failed to remove in-progress label from issue #${vision_ref}"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Journal the rejection via .profile (if available)
|
||||
profile_write_journal "architect-reject-${pr_num}" \
|
||||
"Sprint PR #${pr_num} rejected" \
|
||||
"rejected: ${reason}" "" || true
|
||||
|
||||
# Clean up per-PR session file
|
||||
rm -f "${SID_DIR}/pr-${pr_num}.sid"
|
||||
|
||||
log "REJECT handled for PR #${pr_num}"
|
||||
}
|
||||
|
||||
# Detect answers on a PR in questions phase.
|
||||
# Returns answer text via stdout, empty if no answers found.
|
||||
# Args: pr_number
|
||||
fetch_pr_answers() {
|
||||
local pr_num="$1"
|
||||
|
||||
# Get PR body to check for Design forks section
|
||||
local pr_body
|
||||
pr_body=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls/${pr_num}" 2>/dev/null | jq -r '.body // ""') || return 1
|
||||
|
||||
if ! printf '%s' "$pr_body" | grep -q "## Design forks"; then
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Fetch comments and look for answer patterns (Q1: A, Q2: B, etc.)
|
||||
local comments_json
|
||||
comments_json=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/issues/${pr_num}/comments" 2>/dev/null) || return 1
|
||||
|
||||
# Find the most recent comment containing answer patterns
|
||||
local answer_comment
|
||||
answer_comment=$(printf '%s' "$comments_json" | jq -r '
|
||||
[.[] | select(.body | test("Q[0-9]+:\\s*[A-Da-d]"))] | last | .body // empty
|
||||
' 2>/dev/null) || answer_comment=""
|
||||
|
||||
if [ -n "$answer_comment" ]; then
|
||||
printf '%s' "$answer_comment"
|
||||
return 0
|
||||
fi
|
||||
|
||||
return 1
|
||||
}
|
||||
|
||||
# ── Sub-issue existence check ────────────────────────────────────────────
|
||||
# Check if a vision issue already has sub-issues filed from it.
|
||||
# Returns 0 if sub-issues exist and are open, 1 otherwise.
|
||||
# Args: vision_issue_number
|
||||
has_open_subissues() {
|
||||
local vision_issue="$1"
|
||||
local subissue_count=0
|
||||
|
||||
# Search for issues whose body contains 'Decomposed from #N' pattern
|
||||
# Fetch all open issues with bodies in one API call (avoids N+1 calls)
|
||||
local issues_json
|
||||
issues_json=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/issues?state=open&limit=100" 2>/dev/null) || return 1
|
||||
|
||||
# Check each issue for the decomposition pattern using jq to extract bodies
|
||||
subissue_count=$(printf '%s' "$issues_json" | jq -r --arg vid "$vision_issue" '
|
||||
[.[] | select(.number != $vid) | select(.body // "" | contains("Decomposed from #" + $vid))] | length
|
||||
' 2>/dev/null) || subissue_count=0
|
||||
|
||||
if [ "$subissue_count" -gt 0 ]; then
|
||||
log "Vision issue #${vision_issue} has ${subissue_count} open sub-issue(s) — skipping"
|
||||
return 0 # Has open sub-issues
|
||||
fi
|
||||
|
||||
log "Vision issue #${vision_issue} has no open sub-issues"
|
||||
return 1 # No open sub-issues
|
||||
}
|
||||
|
||||
# ── Merged sprint PR check ───────────────────────────────────────────────
|
||||
# Check if a vision issue already has a merged sprint PR on the ops repo.
|
||||
# Returns 0 if a merged sprint PR exists, 1 otherwise.
|
||||
# Args: vision_issue_number
|
||||
has_merged_sprint_pr() {
|
||||
local vision_issue="$1"
|
||||
|
||||
# Get closed PRs from ops repo
|
||||
local prs_json
|
||||
prs_json=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls?state=closed&limit=100" 2>/dev/null) || return 1
|
||||
|
||||
# Check each closed PR for architect markers and vision issue reference
|
||||
local pr_numbers
|
||||
pr_numbers=$(printf '%s' "$prs_json" | jq -r '.[] | select(.title | contains("architect:")) | .number' 2>/dev/null) || return 1
|
||||
|
||||
local pr_num
|
||||
while IFS= read -r pr_num; do
|
||||
[ -z "$pr_num" ] && continue
|
||||
|
||||
# Get PR details including merged status
|
||||
local pr_details
|
||||
pr_details=$(curl -sf -H "Authorization: token ${FORGE_TOKEN}" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls/${pr_num}" 2>/dev/null) || continue
|
||||
|
||||
# Check if PR is actually merged (not just closed)
|
||||
local is_merged
|
||||
is_merged=$(printf '%s' "$pr_details" | jq -r '.merged // false') || continue
|
||||
|
||||
if [ "$is_merged" != "true" ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Get PR body and check for vision issue reference
|
||||
local pr_body
|
||||
pr_body=$(printf '%s' "$pr_details" | jq -r '.body // ""') || continue
|
||||
|
||||
# Check if PR body references the vision issue number
|
||||
# Look for patterns like "#N" where N is the vision issue number
|
||||
if printf '%s' "$pr_body" | grep -qE "(#|refs|references)[[:space:]]*#${vision_issue}|#${vision_issue}[^0-9]|#${vision_issue}$"; then
|
||||
log "Found merged sprint PR #${pr_num} referencing vision issue #${vision_issue} — skipping"
|
||||
return 0 # Has merged sprint PR
|
||||
fi
|
||||
done <<< "$pr_numbers"
|
||||
|
||||
log "Vision issue #${vision_issue} has no merged sprint PR"
|
||||
return 1 # No merged sprint PR
|
||||
}
|
||||
|
||||
# ── Precondition checks in bash before invoking the model ─────────────────
|
||||
|
||||
# Check 1: Skip if no vision issues exist and no open architect PRs to handle
|
||||
vision_count=$(curl -sf -H "Authorization: token $FORGE_TOKEN" \
|
||||
"$FORGE_API/issues?labels=vision&state=open&limit=1" 2>/dev/null | jq length) || vision_count=0
|
||||
if [ "${vision_count:-0}" -eq 0 ]; then
|
||||
# Check for open architect PRs that need handling (ACCEPT/REJECT responses)
|
||||
open_arch_prs=$(curl -sf -H "Authorization: token $FORGE_TOKEN" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls?state=open&limit=10" 2>/dev/null | jq '[.[] | select(.title | startswith("architect:"))] | length') || open_arch_prs=0
|
||||
if [ "${open_arch_prs:-0}" -eq 0 ]; then
|
||||
log "no vision issues and no open architect PRs — skipping"
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── Design phase: process existing architect PRs (bash-driven) ────────────
|
||||
# Bash reads the reviews API and handles state transitions deterministically.
|
||||
# Model is only invoked for research (ACCEPT) and answer processing.
|
||||
|
||||
open_arch_prs_json=$(curl -sf -H "Authorization: token $FORGE_TOKEN" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls?state=open&limit=10" 2>/dev/null) || open_arch_prs_json='[]'
|
||||
open_arch_prs=$(printf '%s' "$open_arch_prs_json" | jq '[.[] | select(.title | startswith("architect:"))] | length') || open_arch_prs=0
|
||||
|
||||
# Track whether we processed any responses (to decide if pitching is needed)
|
||||
processed_responses=false
|
||||
|
||||
# Iterate over open architect PRs and handle each based on review state
|
||||
arch_pr_data=$(printf '%s' "$open_arch_prs_json" | jq -r '.[] | select(.title | startswith("architect:")) | "\(.number)\t\(.head.ref // "")"' 2>/dev/null) || arch_pr_data=""
|
||||
|
||||
while IFS=$'\t' read -r pr_num pr_branch; do
|
||||
[ -z "$pr_num" ] && continue
|
||||
|
||||
log "Checking PR #${pr_num} (branch: ${pr_branch})"
|
||||
|
||||
# First check: is this PR in the answers phase (questions posted, answers received)?
|
||||
answer_text=""
|
||||
answer_text=$(fetch_pr_answers "$pr_num") || true
|
||||
|
||||
if [ -n "$answer_text" ]; then
|
||||
# ── Answers received: resume saved session with answers injected ──
|
||||
log "Answers detected on PR #${pr_num} — resuming design session"
|
||||
processed_responses=true
|
||||
|
||||
pr_sid_file="${SID_DIR}/pr-${pr_num}.sid"
|
||||
RESUME_ARGS=()
|
||||
if [ -f "$pr_sid_file" ]; then
|
||||
RESUME_SESSION=$(cat "$pr_sid_file")
|
||||
RESUME_ARGS=(--resume "$RESUME_SESSION")
|
||||
log "Resuming session ${RESUME_SESSION:0:12}... for answer processing"
|
||||
else
|
||||
log "No saved session for PR #${pr_num} — starting fresh for answers"
|
||||
fi
|
||||
|
||||
# Build answer-processing prompt with answers injected
|
||||
# shellcheck disable=SC2034
|
||||
SID_FILE="$pr_sid_file"
|
||||
ANSWER_PROMPT="You are the architect agent for ${FORGE_REPO}. You previously researched a sprint and posted design questions on PR #${pr_num}.
|
||||
|
||||
Human answered the design fork questions. Parse the answers and file concrete sub-issues.
|
||||
|
||||
## Human answers
|
||||
${answer_text}
|
||||
|
||||
## Project context
|
||||
${CONTEXT_BLOCK}
|
||||
${GRAPH_SECTION}
|
||||
$(formula_lessons_block)
|
||||
|
||||
## Instructions
|
||||
1. Parse each answer (e.g. Q1: A, Q2: C)
|
||||
2. Read the sprint spec from the PR branch
|
||||
3. Look up the backlog label ID on the disinto repo:
|
||||
GET ${FORGE_API}/labels — find label with name 'backlog'
|
||||
4. Generate final sub-issues based on answers:
|
||||
- Each sub-issue uses the appropriate issue template
|
||||
- Fill all template fields (problem, solution, affected files max 3, acceptance criteria max 5, dependencies)
|
||||
- File via Forgejo API on the disinto repo (not ops repo)
|
||||
- MUST include 'labels' with backlog label ID in create-issue request
|
||||
- Include 'Decomposed from #<vision_issue_number>' in each issue body
|
||||
5. Comment on PR #${pr_num}: 'Sprint filed: #N, #N, #N'
|
||||
6. Merge the PR via: POST ${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls/${pr_num}/merge with body {\"Do\":\"merge\"}
|
||||
|
||||
${PROMPT_FOOTER}"
|
||||
|
||||
# Create worktree if not already set up
|
||||
if [ ! -d "$WORKTREE" ]; then
|
||||
formula_worktree_setup "$WORKTREE"
|
||||
fi
|
||||
|
||||
export CLAUDE_MODEL="sonnet"
|
||||
agent_run "${RESUME_ARGS[@]}" --worktree "$WORKTREE" "$ANSWER_PROMPT"
|
||||
# Restore SID_FILE to default
|
||||
# shellcheck disable=SC2034 # consumed by agent-sdk.sh
|
||||
SID_FILE="/tmp/architect-session-${PROJECT_NAME}.sid"
|
||||
log "Answer processing complete for PR #${pr_num}"
|
||||
continue
|
||||
fi
|
||||
|
||||
# Second check: fetch review decision (ACCEPT/REJECT/NONE)
|
||||
# Sets REVIEW_DECISION and REVIEW_GUIDANCE global variables
|
||||
fetch_pr_review_decision "$pr_num"
|
||||
decision="$REVIEW_DECISION"
|
||||
guidance="$REVIEW_GUIDANCE"
|
||||
|
||||
case "$decision" in
|
||||
REJECT)
|
||||
# ── REJECT: handled entirely in bash ──
|
||||
handle_reject "$pr_num" "$pr_branch" "$guidance"
|
||||
processed_responses=true
|
||||
# Decrement open PR count (PR is now closed)
|
||||
open_arch_prs=$((open_arch_prs - 1))
|
||||
;;
|
||||
|
||||
ACCEPT)
|
||||
# ── ACCEPT: invoke model with human guidance for research + questions ──
|
||||
log "ACCEPT detected on PR #${pr_num} with guidance: ${guidance:-(none)}"
|
||||
processed_responses=true
|
||||
|
||||
# Build human guidance block
|
||||
GUIDANCE_BLOCK=""
|
||||
if [ -n "$guidance" ]; then
|
||||
GUIDANCE_BLOCK="## Human guidance (from sprint PR review)
|
||||
${guidance}
|
||||
|
||||
The architect MUST factor this guidance into design fork identification
|
||||
and question formulation — if the human specifies an approach, that approach
|
||||
should be the default fork, and questions should refine it rather than
|
||||
re-evaluate it."
|
||||
fi
|
||||
|
||||
# Build research + questions prompt
|
||||
RESEARCH_PROMPT="You are the architect agent for ${FORGE_REPO}. A sprint pitch on PR #${pr_num} has been ACCEPTED by a human reviewer.
|
||||
|
||||
Your task: research the codebase deeply, identify design forks, and formulate questions.
|
||||
|
||||
${GUIDANCE_BLOCK}
|
||||
|
||||
## Project context
|
||||
${CONTEXT_BLOCK}
|
||||
${GRAPH_SECTION}
|
||||
${SCRATCH_CONTEXT}
|
||||
$(formula_lessons_block)
|
||||
|
||||
## Instructions
|
||||
1. Read the sprint spec from PR #${pr_num} on the ops repo (branch: ${pr_branch})
|
||||
2. Research the codebase deeply:
|
||||
- Read all files mentioned in the sprint spec
|
||||
- Search for existing interfaces that could be reused
|
||||
- Check what infrastructure already exists
|
||||
3. Identify design forks — multiple valid implementation approaches
|
||||
4. Formulate multiple-choice questions (Q1, Q2, Q3...)
|
||||
5. Update the sprint spec file on the PR branch:
|
||||
- Add '## Design forks' section with fork options
|
||||
- Add '## Proposed sub-issues' section with concrete issues per fork path
|
||||
- Use Forgejo API: PUT ${FORGE_API}/repos/${FORGE_OPS_REPO}/contents/<path> with branch ${pr_branch}
|
||||
6. Update the PR body to include the Design forks section (required for answer detection):
|
||||
- PATCH ${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls/${pr_num}
|
||||
- Body: {\"body\": \"<existing PR body + Design forks section>\"}
|
||||
- The PR body MUST contain '## Design forks' after this step
|
||||
7. Comment on PR #${pr_num} with the questions formatted as multiple choice:
|
||||
- POST ${FORGE_API}/repos/${FORGE_OPS_REPO}/issues/${pr_num}/comments
|
||||
|
||||
${SCRATCH_INSTRUCTION}
|
||||
${PROMPT_FOOTER}"
|
||||
|
||||
# Use per-PR session file for stateful resumption
|
||||
pr_sid_file="${SID_DIR}/pr-${pr_num}.sid"
|
||||
# shellcheck disable=SC2034
|
||||
SID_FILE="$pr_sid_file"
|
||||
|
||||
# Create worktree if not already set up
|
||||
if [ ! -d "$WORKTREE" ]; then
|
||||
formula_worktree_setup "$WORKTREE"
|
||||
fi
|
||||
|
||||
export CLAUDE_MODEL="sonnet"
|
||||
agent_run --worktree "$WORKTREE" "$RESEARCH_PROMPT"
|
||||
log "Research + questions posted for PR #${pr_num}, session saved: ${pr_sid_file}"
|
||||
# Restore SID_FILE to default
|
||||
# shellcheck disable=SC2034 # consumed by agent-sdk.sh
|
||||
SID_FILE="/tmp/architect-session-${PROJECT_NAME}.sid"
|
||||
;;
|
||||
|
||||
NONE)
|
||||
log "PR #${pr_num} — no response yet, skipping"
|
||||
;;
|
||||
esac
|
||||
done <<< "$arch_pr_data"
|
||||
|
||||
# ── Preflight: Select vision issues for pitching ──────────────────────────
|
||||
# Recalculate open PR count after handling responses (REJECTs reduce count)
|
||||
|
||||
# Re-fetch if we processed any responses (PR count may have changed)
|
||||
if [ "$processed_responses" = true ]; then
|
||||
open_arch_prs_json=$(curl -sf -H "Authorization: token $FORGE_TOKEN" \
|
||||
"${FORGE_API}/repos/${FORGE_OPS_REPO}/pulls?state=open&limit=10" 2>/dev/null) || open_arch_prs_json='[]'
|
||||
open_arch_prs=$(printf '%s' "$open_arch_prs_json" | jq '[.[] | select(.title | startswith("architect:"))] | length') || open_arch_prs=0
|
||||
fi
|
||||
SCRATCH_CONTEXT=$(build_scratch_context)
|
||||
GRAPH_SECTION=$(build_graph_section)
|
||||
GUIDANCE_BLOCK=$(build_guidance_block)
|
||||
FORMULA_CONTENT=$(build_formula_content)
|
||||
PROMPT_FOOTER=$(build_prompt_footer)
|
||||
SCRATCH_INSTRUCTION=$(build_scratch_instruction)
|
||||
|
||||
# Build list of vision issues that already have open architect PRs
|
||||
declare -A _arch_vision_issues_with_open_prs
|
||||
|
|
@ -628,42 +192,12 @@ fi
|
|||
|
||||
log "Selected ${#ARCHITECT_TARGET_ISSUES[@]} vision issue(s) for pitching: ${ARCHITECT_TARGET_ISSUES[*]}"
|
||||
|
||||
# ── Pitch prompt: research + PR creation (model handles pitching only) ────
|
||||
# Architecture Decision: AD-003 — The runtime creates and destroys, the formula preserves.
|
||||
build_architect_prompt() {
|
||||
cat <<_PROMPT_EOF_
|
||||
You are the architect agent for ${FORGE_REPO}. Work through the formula below.
|
||||
|
||||
Your role: strategic decomposition of vision issues into development sprints.
|
||||
Propose sprints via PRs on the ops repo.
|
||||
|
||||
## Target vision issues for pitching
|
||||
${ARCHITECT_TARGET_ISSUES[*]}
|
||||
|
||||
## Project context
|
||||
${CONTEXT_BLOCK}
|
||||
${GRAPH_SECTION}
|
||||
${SCRATCH_CONTEXT}
|
||||
$(formula_lessons_block)
|
||||
## Formula
|
||||
${FORMULA_CONTENT}
|
||||
|
||||
${SCRATCH_INSTRUCTION}
|
||||
${PROMPT_FOOTER}
|
||||
_PROMPT_EOF_
|
||||
}
|
||||
|
||||
PROMPT=$(build_architect_prompt)
|
||||
|
||||
# ── Create worktree (if not already set up from design phase) ─────────────
|
||||
if [ ! -d "$WORKTREE" ]; then
|
||||
formula_worktree_setup "$WORKTREE"
|
||||
fi
|
||||
|
||||
# ── Run agent for pitching ────────────────────────────────────────────────
|
||||
export CLAUDE_MODEL="sonnet"
|
||||
agent_run --worktree "$WORKTREE" "$PROMPT"
|
||||
log "agent_run complete (pitching)"
|
||||
# 5. Stateless pitch generation: for each selected issue:
|
||||
# - Fetch issue body from Forgejo API (bash)
|
||||
# - Invoke claude -p with issue body + context (stateless, no API calls)
|
||||
# - Create PR with pitch content (bash)
|
||||
# - Post footer comment (bash)
|
||||
# 6. Response processing: handle ACCEPT/REJECT on existing PRs
|
||||
|
||||
# Clean up scratch files (legacy single file + per-issue files)
|
||||
rm -f "$SCRATCH_FILE"
|
||||
|
|
|
|||
|
|
@ -3,18 +3,26 @@
|
|||
# Executed by architect-run.sh via cron — strategic decomposition of vision
|
||||
# issues into development sprints.
|
||||
#
|
||||
# This formula orchestrates the architect agent's pitching workflow:
|
||||
# Step 1: Preflight — validate prerequisites, select up to 3 target issues
|
||||
# Step 2: Research + pitch — analyze codebase and write sprint pitch (loop over selected issues)
|
||||
# Step 3: Sprint PR creation (one PR per pitch)
|
||||
# This formula orchestrates the architect agent's workflow:
|
||||
# Step 1: Preflight — bash handles state management:
|
||||
# - Fetch open vision issues from Forgejo API
|
||||
# - Fetch open architect PRs on ops repo
|
||||
# - Fetch merged architect PRs (already pitched visions)
|
||||
# - Filter: remove visions with open PRs, merged sprints, or sub-issues
|
||||
# - Select up to 3 remaining vision issues for pitching
|
||||
# Step 2: Stateless pitch generation — for each selected issue:
|
||||
# - Invoke claude -p with: vision issue body + codebase context
|
||||
# - Model NEVER calls Forgejo API — only generates pitch markdown
|
||||
# - Bash creates the ops PR with pitch content
|
||||
# - Bash posts the ACCEPT/REJECT footer comment
|
||||
# Step 3: Sprint PR creation with questions (issue #101) (one PR per pitch)
|
||||
# Step 4: Answer parsing + sub-issue filing (issue #102)
|
||||
#
|
||||
# Design phase (ACCEPT/REJECT handling, questions, answer processing) is
|
||||
# orchestrated by bash in architect-run.sh — not by this formula.
|
||||
# See architect-run.sh for the bash-driven state machine:
|
||||
# - Bash reads reviews API for ACCEPT/REJECT detection (deterministic)
|
||||
# - REJECT handled entirely in bash (close PR, delete branch, journal)
|
||||
# - ACCEPT: bash invokes model with human guidance injected
|
||||
# - Answers: bash resumes saved session with answers injected
|
||||
# Architecture:
|
||||
# - Bash script (architect-run.sh) handles ALL state management
|
||||
# - Model calls are stateless — no Forgejo API access, no memory between calls
|
||||
# - Dedup is automatic via bash filters (no journal-based memory needed)
|
||||
# - Max 3 open architect PRs at any time
|
||||
#
|
||||
# AGENTS.md maintenance is handled by the gardener (#246).
|
||||
|
||||
|
|
@ -30,19 +38,32 @@ files = ["VISION.md", "AGENTS.md"]
|
|||
|
||||
[[steps]]
|
||||
id = "preflight"
|
||||
title = "Preflight: validate prerequisites, select up to 3 target issues"
|
||||
title = "Preflight: bash-driven state management and issue selection"
|
||||
description = """
|
||||
This step is performed by bash in architect-run.sh before the model is invoked.
|
||||
This step performs preflight checks and selects up to 3 vision issues for pitching.
|
||||
IMPORTANT: All state management is handled by bash (architect-run.sh), NOT the model.
|
||||
|
||||
Bash handles:
|
||||
1. Pull latest code from both disinto repo and ops repo
|
||||
2. Read prerequisite tree from $OPS_REPO_ROOT/prerequisites.md
|
||||
3. Fetch open issues labeled 'vision' from Forgejo API
|
||||
4. Check for open architect PRs on ops repo
|
||||
5. Process existing PRs via bash-driven design phase (ACCEPT/REJECT/answers)
|
||||
6. After handling existing PRs, count remaining open architect PRs
|
||||
7. Select up to (3 - open_architect_pr_count) vision issues for new pitches
|
||||
8. If no vision issues, signal PHASE:done
|
||||
Architecture Decision: Bash-driven orchestration with stateless model calls
|
||||
- The model NEVER calls Forgejo API during pitching
|
||||
- Bash fetches all data from Forgejo API (vision issues, open PRs, merged PRs)
|
||||
- Bash filters and deduplicates (no model-level dedup or journal-based memory)
|
||||
- For each selected issue, bash invokes stateless claude -p (model only generates pitch)
|
||||
- Bash creates PRs and posts footer comments (no model API access)
|
||||
|
||||
Bash Actions (in architect-run.sh):
|
||||
1. Fetch open vision issues from Forgejo API: GET /repos/{owner}/{repo}/issues?labels=vision&state=open
|
||||
2. Fetch open architect PRs from ops repo: GET /repos/{owner}/{repo}/pulls?state=open
|
||||
3. Fetch merged sprint PRs: GET /repos/{owner}/{repo}/pulls?state=closed (filter merged=true)
|
||||
4. Filter out visions that:
|
||||
- Already have open architect PRs (check PR body for issue number reference)
|
||||
- Have in-progress label
|
||||
- Have open sub-issues (check for 'Decomposed from #N' pattern)
|
||||
- Have merged sprint PRs (decomposition already done)
|
||||
5. Select up to (3 - open_architect_pr_count) remaining vision issues
|
||||
6. If no issues remain AND no responses to process, signal PHASE:done
|
||||
|
||||
If open architect PRs exist, handle accept/reject responses FIRST (see Capability B below).
|
||||
After handling existing PRs, count remaining open architect PRs and calculate pitch_budget.
|
||||
|
||||
## Multi-pitch selection (up to 3 per run)
|
||||
|
||||
|
|
@ -71,82 +92,36 @@ Output:
|
|||
|
||||
[[steps]]
|
||||
id = "research_pitch"
|
||||
title = "Research + pitch: analyze codebase and write sprint pitches (loop over selected issues)"
|
||||
title = "Stateless pitch generation: model generates content, bash creates PRs"
|
||||
description = """
|
||||
This step performs deep codebase research and writes a sprint pitch for EACH
|
||||
vision issue in ARCHITECT_TARGET_ISSUES.
|
||||
IMPORTANT: This step is executed by bash (architect-run.sh) via stateless claude -p calls.
|
||||
The model NEVER calls Forgejo API — it only reads context and generates pitch markdown.
|
||||
|
||||
For each issue in ARCHITECT_TARGET_ISSUES, perform the following:
|
||||
Architecture:
|
||||
- Bash orchestrates the loop over ARCHITECT_TARGET_ISSUES
|
||||
- For each issue: bash fetches issue body from Forgejo API, then invokes stateless claude -p
|
||||
- Model receives: vision issue body + codebase context (VISION.md, AGENTS.md, prerequisites.md)
|
||||
- Model outputs: sprint pitch markdown ONLY (no API calls, no side effects)
|
||||
- Bash creates the PR and posts the ACCEPT/REJECT footer comment
|
||||
|
||||
Actions:
|
||||
For each issue in ARCHITECT_TARGET_ISSUES, bash performs:
|
||||
|
||||
1. Read the codebase deeply:
|
||||
- Read all files mentioned in the issue body
|
||||
- Search for existing interfaces that could be reused
|
||||
- Check what infrastructure already exists
|
||||
1. Fetch vision issue details from Forgejo API:
|
||||
- GET /repos/{owner}/{repo}/issues/{issue_number}
|
||||
- Extract: title, body
|
||||
|
||||
2. Assess complexity and cost:
|
||||
- How many files/subsystems are touched?
|
||||
- What new infrastructure would need to be maintained after this sprint?
|
||||
- What are the risks (breaking changes, security implications, integration complexity)?
|
||||
- Is this mostly gluecode or greenfield?
|
||||
2. Invoke stateless claude -p with prompt:
|
||||
"Write a sprint pitch for this vision issue. Output only the pitch markdown."
|
||||
Context provided:
|
||||
- Vision issue #N: <title>
|
||||
- Vision issue body
|
||||
- Project context (VISION.md, AGENTS.md)
|
||||
- Codebase context (prerequisites.md, graph section)
|
||||
- Formula content
|
||||
|
||||
3. Write sprint pitch to a per-issue scratch file for PR creation step:
|
||||
- File path: /tmp/architect-{project}-scratch-{issue_number}.md
|
||||
3. Model generates pitch markdown (NO API CALLS):
|
||||
|
||||
# Sprint pitch: <name>
|
||||
|
||||
## Vision issues
|
||||
- #N — <title>
|
||||
|
||||
## What this enables
|
||||
<what the project can do after this sprint that it can't do now>
|
||||
|
||||
## What exists today
|
||||
<current state — infrastructure, interfaces, code that can be reused>
|
||||
|
||||
## Complexity
|
||||
<number of files, subsystems, estimated sub-issues>
|
||||
<gluecode vs greenfield ratio>
|
||||
|
||||
## Risks
|
||||
<what could go wrong, what breaks if this is done badly>
|
||||
|
||||
## Cost — new infra to maintain
|
||||
<what ongoing maintenance burden does this sprint add>
|
||||
<new services, cron jobs, formulas, agent roles>
|
||||
|
||||
## Recommendation
|
||||
<architect's assessment: worth it / defer / alternative approach>
|
||||
|
||||
IMPORTANT: Do NOT include design forks or questions yet. The pitch is a go/no-go
|
||||
decision for the human. Questions come only after acceptance.
|
||||
|
||||
Output:
|
||||
- Writes one scratch file per vision issue: /tmp/architect-{project}-scratch-{issue_number}.md
|
||||
- Each pitch serves as input for sprint PR creation step
|
||||
- If ARCHITECT_TARGET_ISSUES is empty (budget exhausted or no candidates), skip this step
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "sprint_pr_creation"
|
||||
title = "Sprint PR creation (one PR per pitch)"
|
||||
description = """
|
||||
This step creates a PR on the ops repo for EACH sprint pitch produced in step 2.
|
||||
One PR per vision issue — loop over all scratch files.
|
||||
|
||||
## Create pitch PRs (from research output)
|
||||
|
||||
For each vision issue in ARCHITECT_TARGET_ISSUES that produced a scratch file
|
||||
(/tmp/architect-{project}-scratch-{issue_number}.md):
|
||||
|
||||
1. Create branch `architect/<sprint-slug>` on ops repo via Forgejo API
|
||||
- Sprint slug: lowercase, hyphenated version of sprint name
|
||||
- Use Forgejo API: POST /repos/{owner}/{repo}/git/branches
|
||||
|
||||
2. Write sprint spec file to sprints/<sprint-slug>.md on the new branch:
|
||||
|
||||
# Sprint: <name>
|
||||
# Sprint: <sprint-name>
|
||||
|
||||
## Vision issues
|
||||
- #N — <title>
|
||||
|
|
@ -171,19 +146,86 @@ For each vision issue in ARCHITECT_TARGET_ISSUES that produced a scratch file
|
|||
## Recommendation
|
||||
<architect's assessment: worth it / defer / alternative approach>
|
||||
|
||||
3. Create PR on ops repo via Forgejo API:
|
||||
- Title: `architect: <sprint summary>`
|
||||
- Body: **plain markdown text** from the scratch file (pitch content with sections: What this enables, Complexity, Risks, Cost, Recommendation). Preserve newlines as-is — do NOT JSON-encode the body.
|
||||
- Base branch: primary branch (main/master)
|
||||
- Head branch: architect/<sprint-slug>
|
||||
- Footer: "Reply `ACCEPT` to proceed with design questions, or `REJECT: <reason>` to decline."
|
||||
IMPORTANT: Do NOT include design forks or questions yet. The pitch is a go/no-go
|
||||
decision for the human. Questions come only after acceptance.
|
||||
|
||||
4. Add `in-progress` label to the vision issue on the disinto repo:
|
||||
- Look up the `in-progress` label ID via `GET /repos/{owner}/{repo}/labels`
|
||||
- Add the label via `POST /repos/{owner}/{repo}/issues/{vision_issue_number}/labels`
|
||||
Body: `{"labels": [<in-progress-label-id>]}`
|
||||
4. Bash creates PR:
|
||||
- Create branch: architect/sprint-{pitch-number}
|
||||
- Write sprint spec to sprints/{sprint-slug}.md
|
||||
- Create PR with pitch content as body
|
||||
- Post footer comment: "Reply ACCEPT to proceed with design questions, or REJECT: <reason> to decline."
|
||||
- Add in-progress label to vision issue
|
||||
|
||||
5. After creating all PRs, signal PHASE:done
|
||||
Output:
|
||||
- One PR per vision issue (up to 3 per run)
|
||||
- Each PR contains the pitch markdown
|
||||
- If ARCHITECT_TARGET_ISSUES is empty, skip this step
|
||||
"""
|
||||
|
||||
[[steps]]
|
||||
id = "sprint_pr_creation"
|
||||
title = "Sprint PR creation with questions (issue #101) — handled by bash"
|
||||
description = """
|
||||
IMPORTANT: PR creation is handled by bash (architect-run.sh) during the pitch step.
|
||||
This step is for documentation only — the actual PR creation happens in research_pitch.
|
||||
|
||||
Architecture:
|
||||
- Bash creates PRs during stateless pitch generation (step 2)
|
||||
- Model has no role in PR creation — no Forgejo API access
|
||||
- This step describes the PR format for reference
|
||||
|
||||
PR Format (created by bash):
|
||||
|
||||
1. Branch: architect/sprint-{pitch-number}
|
||||
|
||||
2. Sprint spec file: sprints/{sprint-slug}.md
|
||||
Contains the pitch markdown from the model.
|
||||
|
||||
3. PR via Forgejo API:
|
||||
- Title: architect: <sprint summary>
|
||||
- Body: plain markdown text from model output
|
||||
- Base: main (or PRIMARY_BRANCH)
|
||||
- Head: architect/sprint-{pitch-number}
|
||||
- Footer comment: "Reply ACCEPT to proceed with design questions, or REJECT: <reason> to decline."
|
||||
|
||||
4. Add in-progress label to vision issue:
|
||||
- Look up label ID: GET /repos/{owner}/{repo}/labels
|
||||
- Add label: POST /repos/{owner}/{repo}/issues/{issue_number}/labels
|
||||
|
||||
After creating all PRs, signal PHASE:done.
|
||||
|
||||
## Forgejo API Reference
|
||||
|
||||
All operations use the Forgejo API with Authorization: token ${FORGE_TOKEN} header.
|
||||
|
||||
### Create branch
|
||||
```
|
||||
POST /repos/{owner}/{repo}/branches
|
||||
Body: {"new_branch_name": "architect/<sprint-slug>", "old_branch_name": "main"}
|
||||
```
|
||||
|
||||
### Create/update file
|
||||
```
|
||||
PUT /repos/{owner}/{repo}/contents/<path>
|
||||
Body: {"message": "sprint: add <sprint-slug>.md", "content": "<base64-encoded-content>", "branch": "architect/<sprint-slug>"}
|
||||
```
|
||||
|
||||
### Create PR
|
||||
```
|
||||
POST /repos/{owner}/{repo}/pulls
|
||||
Body: {"title": "architect: <sprint summary>", "body": "<markdown-text>", "head": "architect/<sprint-slug>", "base": "main"}
|
||||
```
|
||||
|
||||
**Important: PR body format**
|
||||
- The body field must contain plain markdown text (the raw content from the model)
|
||||
- Do NOT JSON-encode or escape the body — pass it as a JSON string value
|
||||
- Newlines and markdown formatting (headings, lists, etc.) must be preserved as-is
|
||||
|
||||
### Add label to issue
|
||||
```
|
||||
POST /repos/{owner}/{repo}/issues/{index}/labels
|
||||
Body: {"labels": [<label-id>]}
|
||||
```
|
||||
|
||||
## Forgejo API Reference
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue