academy-software-factory
Public
Pull mirror status: ok
E
Merge pull request #1 from vercel-labs/solution-remi
.agents
.github
agent
docs
evals
fixtures
packages
scripts
.env.example
.gitignore
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
tsconfig.json
vitest.config.ts

Academy Software Factory

This is the project for the Vercel Academy course Creating a Software Factory.

This implementation

solution-remi implements the course in 14 ordered lesson commits, followed by focused fixes and tests. See the commit-by-commit guide and verification record. Local validation, build, and fast live routing evaluations pass; repository-backed and deployed checks still need a configured target.

Branches

  • main is the deployable course starter. It includes GitHub intake, repository sandbox infrastructure, the notification SDK, and four case fixtures. Learners build the factory from this branch.
  • solution-remi is this locally implemented course solution.
  • solution is the upstream-documented completed reference, but upstream did not expose that branch when checked on 2026-09-10. It includes five root tools, Investigator, Builder, and Verifier subagents, approval gates, draft pull request policy, traces, and evaluations.

A fresh clone should remain on main.

Repository map

agent/                         # eve agent, channels, policies, and stations
fixtures/issues/               # prompts for the four course cases
fixtures/runs/                 # recorded outcomes used before live model calls
packages/notification-sdk/     # sample TypeScript product the factory maintains
evals/                         # regression evaluations on the solution branch

The upstream repository is the course template. Your personal fork is the factory's target: it is cloned into sandboxes, receives factory/* branches, and hosts draft pull requests.

Setup

Clone your personal fork and install dependencies:

git clone https://github.com/YOUR_GITHUB_NAME/signalworks-software-factory.git
cd signalworks-software-factory
git switch main
pnpm install
pnpm exec eve link

Use the latest Vercel CLI to create and attach a managed GitHub connector:

vercel connect create github --name signalworks-factory --triggers
vercel connect attach github/signalworks-factory --triggers --trigger-path /eve/v1/github
vercel connect list

During GitHub App installation, grant access only to the personal course repository. Vercel Connect supplies short-lived installation tokens, so the project does not need a personal access token, webhook secret, or GitHub App private key.

Add the course configuration to the linked Vercel project, then pull it and the local OIDC token into .env.local:

vercel env add FACTORY_REPO --value YOUR_GITHUB_NAME/signalworks-software-factory
vercel env add FACTORY_LABEL --value factory
vercel env add FACTORY_BRANCH_PREFIX --value factory/
vercel env add FACTORY_SETUP_COMMAND --value "pnpm install --frozen-lockfile"
vercel env add GITHUB_CONNECTOR --value github/signalworks-factory
vercel env pull .env.local

Confirm that .env.local contains the non-secret course values below. Do not remove the OIDC values pulled by Vercel:

FACTORY_REPO=YOUR_GITHUB_NAME/signalworks-software-factory
FACTORY_LABEL=factory
FACTORY_BRANCH_PREFIX=factory/
FACTORY_SETUP_COMMAND=pnpm install --frozen-lockfile
GITHUB_CONNECTOR=github/signalworks-factory

GITHUB_CONNECTOR must match the UID printed by vercel connect list.

Validate the current branch

pnpm install
pnpm validate

The starter reports zero authored tools and zero subagents. This implementation reports five authored root tools and three subagents.

Invoke locally

After the course has added the root tools and instructions, invoke a fixture without the TUI:

pnpm exec eve invoke "$(cat fixtures/issues/bug-example.md)"

For an interactive run, use pnpm exec eve dev and paste the fixture into the TUI.

Inspect the solution

git switch solution-remi
pnpm validate
pnpm trace
pnpm exec eve eval --list

Return to the starter before beginning the course:

git switch main