feat(96b): architect formula — research + design fork identification #100

New issue

Closed

opened 2026-04-01 08:39:45 +00:00 by dev-bot · 0 comments

dev-bot commented

2026-04-01 08:39:45 +00:00

Collaborator

Parent

Part of #96 — architect agent.

What to do

Implement the first two steps of formulas/run-architect.toml: preflight and research + pitch creation.

Step 1: preflight

Pull latest code and ops repo
Read prerequisite tree from $OPS_REPO_ROOT/prerequisites.md
Fetch open issues labeled vision from Forgejo
Check for open architect PRs on ops repo (handled by #101/#102 — skip if any exist)
If open architect PRs exist or no vision issues, signal PHASE:done

Step 2: research + pitch

Pick the most unblocking vision issue (prerequisites blocking the most downstream objectives). If multiple vision issues share a subsystem, group into one sprint.

For the selected vision issue(s):

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

Do NOT include design forks or questions yet. The pitch is a go/no-go decision for the human. Questions come only after accept.

Affected files

formulas/run-architect.toml (update — add preflight + research/pitch steps)

Acceptance criteria

Formula identifies most-unblocking vision issue from prerequisite tree
Formula reads codebase and assesses existing interfaces
Pitch includes: what it enables, complexity, risks, new infra cost
Pitch does NOT include design forks or questions
Research output written to scratch file
Skips cleanly when no vision issues or open PRs exist
CI green

Dependencies

Depends on #99 (scaffold).

## Parent Part of #96 — architect agent. ## What to do Implement the first two steps of `formulas/run-architect.toml`: preflight and research + pitch creation. ### Step 1: preflight 1. Pull latest code and ops repo 2. Read prerequisite tree from `$OPS_REPO_ROOT/prerequisites.md` 3. Fetch open issues labeled `vision` from Forgejo 4. Check for open architect PRs on ops repo (handled by #101/#102 — skip if any exist) 5. If open architect PRs exist or no vision issues, signal PHASE:done ### Step 2: research + pitch Pick the most unblocking vision issue (prerequisites blocking the most downstream objectives). If multiple vision issues share a subsystem, group into one sprint. For the selected vision issue(s): 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): ```markdown # 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> ``` **Do NOT include design forks or questions yet.** The pitch is a go/no-go decision for the human. Questions come only after accept. ## Affected files - `formulas/run-architect.toml` (update — add preflight + research/pitch steps) ## Acceptance criteria - [ ] Formula identifies most-unblocking vision issue from prerequisite tree - [ ] Formula reads codebase and assesses existing interfaces - [ ] Pitch includes: what it enables, complexity, risks, new infra cost - [ ] Pitch does NOT include design forks or questions - [ ] Research output written to scratch file - [ ] Skips cleanly when no vision issues or open PRs exist - [ ] CI green ## Dependencies Depends on #99 (scaffold).