Skip to content

SPEC.md

Latest commit

 

History

History
53 lines (33 loc) · 6.72 KB

SPEC.md

File metadata and controls

53 lines (33 loc) · 6.72 KB
Raw

The Framework: autonomous AI programming. Humans make the important decisions; coding agents work the user's registered repos unattended and hand the result off as pull requests. The product never makes model calls of its own — it drives a coding-agent CLI the user already pays for (Claude Code or Codex) as a black box, on the user's own subscription.

Six top-level pieces, one product:

  • packages/framework — the product itself, published as the npm package framework: one CLI (the-framework) that runs a foreground daemon, the agent lifecycle it orchestrates, and the browser dashboard it serves — the product's only user interface.
  • packages/agent-data — a branch of the project's repository used as a file store, published as @gemstack/agent-data: the shared agent-data branch every skill keeps its files on, written through one sync → commit → push cycle that re-applies the change when the push loses a race, from a long-lived process through a persistent checkout or one-shot from any clone. A library, not a skill — read by code, never by an agent. Every skill depends on it, and so does the product; it depends on nothing.
  • packages/skill-branches — the git conventions and operations behind an agent's own checkout, as an API, as the branches command every agent the daemon starts on its machine gets on its PATH, and as the skill (SKILL.md) every agent's built-in system prompt carries, published as @gemstack/skill-branches: the first of the skills the product is being split into. The product depends on it; it depends on agent-data and on nothing of the product.
  • packages/skill-tickets — the project's tickets and its agent queue, on the tickets branch of the project's own repository, published as @gemstack/skill-tickets: the same three faces — an API, the tickets command every agent the daemon starts gets on its PATH, and the skill (SKILL.md) every such agent finds in its checkout — over reading tickets, writing them, claiming one so two agents never work the same, and keeping the queue. The second of the skills. The product depends on it, and it depends on agent-data for the branch it stores everything on.
  • packages/agent-driver — the driver seam as its own package, published as agent-driver: one contract for driving a coding-agent CLI as a black box — a session in a directory, one full turn per prompt, a stream of what the agent did — and the implementations for Claude Code and Codex on this device, Claude Code on a GitHub Actions runner, and a scripted fake. The product depends on it and adds the one implementation that needs the product, the hand-off to a Claude Code cloud session; it depends on nothing of the product.
  • packages/chrome-extension — the Claude web bridge, a companion Chrome extension: when an agent's task was handed to a Claude Code cloud session on claude.ai, it carries the question that session is parked on into the local dashboard, and types the answer picked there back into the session.
  • packages/the-framework.ai — the marketing website at https://the-framework.ai.

Every user-facing feature is enumerated in FEATURES-SPEC.md.

User story

  • A developer registers a repo, states what they want built or fixed, and gets a reviewable pull request without babysitting: the agent stops to ask only when a real decision is needed, and otherwise finishes on its own.
  • A developer walks away entirely; the daemon keeps spending the account's leftover quota productively — draining the confirmed-task queue, triaging and planning tickets, fixing red CI on the pull requests it opened, merging them once checks pass — and stands down before unattended work could eat into the quota the human will want.
  • The developer's own checkout is never touched: every agent works a throwaway checkout, and anything The Framework removes on its own initiative already exists on the git remote.

Business logic — TL;DR

  • One daemon, one dashboard - a single foreground framework process per machine serves the dashboard; the CLI itself has four options and no verbs, and every other decision lives in the dashboard.
  • The agent is the unit of work - one task, in its own git worktree on its own branch, streaming everything it does as events; finished work is pushed and leaves as a pull request.
  • Black-box driving - the framework prompts the wrapped coding-agent CLI, lets the CLI's own loop run a full turn, and learns everything from the turn's final message: the session name the agent invented, the questions it stops to ask, and the ready-for-merge signal.
  • Autonomy bounded by the account's own quota - unattended work runs only while the account is under its pro-rated quota boundary; work a human asks for is never blocked, and a running agent is never interrupted over quota.
  • Nothing bookkeeping-shaped on a code branch - the tickets and the agent queue live on the tickets branch, which is the tickets skill's; The Framework's own records of its runs — the agent archives, the routine locks — live on the agents-logs branch. The default branch stays 100% code.

Business logic

From a prompt to a pull request

User story

See ## User story: a stated intent becomes a reviewable pull request without babysitting.

Business logic

The user starts an agent from the dashboard. The daemon gives it a fresh worktree and branch, frames the wrapped CLI with the built-in system prompt, and sends the task. The agent names its task (the session name; its branch is renamed to match), works turn by turn, and may park on a gate — a question with options the dashboard renders and the user answers (autopilot answers it automatically after a delay). When the agent signals ready for merge and the work settles, the handoff publishes it: by default, push the branch and open a pull request. How far the handoff goes is one ladder — keep it local, push, open a pull request, or merge — set per repo, per user, or per agent.

Unattended operation

User story

See ## User story: the daemon keeps working while nobody is around, within the account's own quota.

Business logic

On a shared clock the daemon runs its background jobs: Auto PM works the agent queue down and refills it by triaging tickets and planning the ones without plans; the CI watch merges the framework's pull requests once their checks pass and starts a fix agent when checks go red; sweeps reclaim finished agents' checkouts (only what is already on the remote) and keep bookkeeping healthy, and a routine that must not run twice is guarded by a routine lock on the agents-logs branch. Each unattended start checks the quota boundary first.

Before modifying/creating SPEC.md files

You must always read and respect https://raw.githubusercontent.com/brillout/sdd/refs/heads/main/sdd.md