disinto/formulas/run-architect.toml

# formulas/run-architect.toml — Architect formula
#
# Executed by architect-run.sh via cron — strategic decomposition of vision
# issues into development sprints.
#
# This formula orchestrates the architect agent's workflow:
#   Step 1: Preflight — validate prerequisites and identify target issue
#   Step 2: Research + pitch — analyze codebase and write sprint pitch
#   Step 3: Sprint PR creation with questions (issue #101)
#   Step 4: Answer parsing + sub-issue filing (issue #102)
#
# AGENTS.md maintenance is handled by the gardener (#246).

name        = "run-architect"
description = "Architect: strategic decomposition of vision into sprints"
version     = 1
model       = "opus"

[context]
files = ["VISION.md", "AGENTS.md"]
# Prerequisite tree loaded from ops repo (ops: prefix)
# Sprints directory tracked in ops repo

[[steps]]
id    = "preflight"
title = "Preflight: validate prerequisites and identify target vision issue"
description = """
This step performs preflight checks and identifies the most unblocking vision issue.

Actions:
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 (handled by #101/#102)
5. If open architect PRs exist, handle accept/reject responses (see Capability B below)
6. If no vision issues, signal PHASE:done

Skip conditions:
- If no vision issues are found, signal PHASE:done

Output:
- Sets ARCHITECT_TARGET_ISSUE to the issue number of the selected vision issue
- Exports VISION_ISSUES as a JSON array of issue objects

## Capability B: Handle accept/reject on existing pitch PRs

When open architect PRs exist on the ops repo:

1. Fetch comments on each open architect PR via Forgejo API
2. Look for human response:

   **ACCEPT** (case insensitive): Human wants to proceed
   - Architect does deep research for design forks (same as #100 research but now identifying decision points)
   - Formulates multiple-choice questions (Q1, Q2, Q3...)
   - Updates the sprint spec file on the PR branch:
     - Adds `## Design forks` section with fork options
     - Adds `## Proposed sub-issues` section with concrete issues per fork path
   - Comments on the PR with the questions formatted as multiple choice
   - Signal PHASE:done (answer processing is #102)

   **REJECT: <reason>** (case insensitive, reason after colon):
   - Journal the rejection reason via profile_write_journal (if .profile exists)
     — the architect learns what pitches fail
   - Close the PR via Forgejo API (do not merge — rejected pitches do not persist in sprints/)
   - Remove the branch via Forgejo API
   - Signal PHASE:done

   **No response yet**: skip silently, signal PHASE:done

All git operations use the Forgejo API (create branch, write/update file, create PR,
close PR, delete branch). No SSH.
"""

[[steps]]
id    = "research_pitch"
title = "Research + pitch: analyze codebase and write sprint pitch"
description = """
This step performs deep codebase research and writes a sprint pitch for the
selected vision issue.

Actions:

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

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?

3. Write sprint pitch to scratch file for PR creation step (#101):

# 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 sprint pitch to $SCRATCH_FILE (/tmp/architect-{project}-scratch.md)
- The pitch serves as input for sprint PR creation step (#101)
"""

[[steps]]
id    = "sprint_pr_creation"
title = "Sprint PR creation with questions (issue #101)"
description = """
This step creates a PR on the ops repo with the sprint proposal when no PR exists yet.

## Capability A: Create pitch PR (from research output)

If step 2 (research/pitch) produced a pitch and no PR exists yet:

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>

## 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>

3. Create PR on ops repo via Forgejo API:
   - Title: `architect: <sprint summary>`
   - Body: pitch content (what it enables, complexity, risks, cost)
   - Base branch: primary branch (main/master)
   - Head branch: architect/<sprint-slug>
   - Footer: "Reply `ACCEPT` to proceed with design questions, or `REJECT: <reason>` to decline."

4. Signal PHASE:done

## Forgejo API Reference

All operations use the Forgejo API with `Authorization: token ${FORGE_TOKEN}` header.

### Create branch
```
POST /repos/{owner}/{repo}/git/branches
Body: {"name": "architect/<sprint-slug>", "old_ref": "refs/heads/main", "new_ref": "<commit-sha>"}
```

### 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": "<pitch-content>", "head": "architect/<sprint-slug>", "base": "main"}
```

### Close PR
```
POST /repos/{owner}/{repo}/pulls/{index}/pull
Body: {"state": "closed"}
```

### Delete branch
```
DELETE /repos/{owner}/{repo}/git/branches/<branch-name>
```
"""

[[steps]]
id    = "answer_parsing"
title = "Answer parsing + sub-issue filing (issue #102)"
description = """
This step processes human answers to design questions and files sub-issues.

Actions:
1. Monitor PR comments for human responses to design questions
2. Parse answers and extract design decisions
3. File concrete sub-issues for each accepted design fork path
4. Close or update the sprint PR based on decisions

Output:
- Sub-issues filed in disinto repo with proper dependencies
- Sprint PR updated or closed based on design decisions
"""