{"id":51619163,"url":"https://github.com/loopworx/forge","last_synced_at":"2026-07-12T18:00:40.919Z","repository":{"id":363657373,"uuid":"1264330792","full_name":"loopworx/forge","owner":"loopworx","description":"A lean software delivery skill framework for AI agents — from inception to production. ATDD-first, multi-agent, trunk-based.","archived":false,"fork":false,"pushed_at":"2026-07-10T23:00:04.000Z","size":793,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-10T23:03:33.314Z","etag":null,"topics":["agent","ai","atdd","llm","loop-language","skills","tdd"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/loopworx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T19:34:17.000Z","updated_at":"2026-07-10T22:59:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/loopworx/forge","commit_stats":null,"previous_names":["yaman/forge","loopworx/forge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/loopworx/forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopworx%2Fforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopworx%2Fforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopworx%2Fforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopworx%2Fforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loopworx","download_url":"https://codeload.github.com/loopworx/forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loopworx%2Fforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35398566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","atdd","llm","loop-language","skills","tdd"],"created_at":"2026-07-12T18:00:24.221Z","updated_at":"2026-07-12T18:00:40.902Z","avatar_url":"https://github.com/loopworx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Forge\n\n[![Pipeline](https://github.com/loopworx/forge/actions/workflows/pipeline.yml/badge.svg)](https://github.com/loopworx/forge/actions/workflows/pipeline.yml)\n[![npm version](https://img.shields.io/npm/v/@loopworx/forge.svg)](https://www.npmjs.com/package/@loopworx/forge)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![lint: oxlint](https://img.shields.io/badge/lint-oxlint-4B9CD3.svg)](https://oxc.rs)\n\n**Forge** is an AI-driven software delivery orchestrator that coordinates seven specialized AI agents through a lean delivery pipeline — from inception to production. It uses Linear as the single source of truth and runs as a [pi.dev](https://pi.dev) extension with a deterministic workflow engine.\n\n---\n\n## Why Forge — Removing AI Slop\n\nForge is an attempt to create the perfect product team — a team of agents with\nenforced roles, gated handoffs, and a feedback loop where every piece of work\nis verifiable, gated, and recoverable. Seven agents — PO, UX, Architect,\nDeveloper, QA, DevOps, SecOps — each own a defined slice of the delivery\npipeline and are blocked from operating outside it.\n\nThe outer acceptance test goes RED before any implementation code is written;\nTDD inner loops drive each sub-slice green (FE then BE); a QA desk check\ninspects every acceptance criterion through the UI exactly as a customer would;\na scoped regression suite guards adjacent flows; and PO acceptance verifies\nshipped behavior against the original story intent. State lives in Linear —\nvisible and human-readable — never in plan files or conversation summaries,\nwhich \"lie.\" Loop pre-flights, failsafe auto-advance, crash recovery, and\ncommit-per-AC guarantee nothing is silently lost.\n\n---\n\n## How It Works\n\nForge is a pi.dev extension that registers custom tools (`forge_claim_story`,\n`forge_complete_ac`, `forge_handoff`, `forge_create_artifact`,\n`forge_log_progress`) callable by the LLM. A deterministic workflow engine\nvalidates every state transition, serializes via FIFO queue, and writes to\nLinear — ensuring agents can never skip steps or operate out of order.\n\n1. **Install** — `forge init` drops the pi.dev extension, 7 agent profiles, 24 skills, and configures Linear auth\n2. **Start** — Run `pi` in your project — the extension auto-loads, registers forge tools, and starts polling Linear\n3. **Deliver** — The engine polls Linear for stories, claims them, creates agent sessions, and coordinates the delivery pipeline\n\nThere is no separate process or daemon. The extension loads when you start `pi`\nand stops when you exit.\n\n### Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                    pi.dev runtime                    │\n│                                                      │\n│  ┌──────────────┐    ┌───────────────────────────┐  │\n│  │  LLM Agent   │───▶│   Forge Extension (TS)    │  │\n│  │  (glm-5.2)   │    │                            │  │\n│  │              │◀───│  ┌──────────────────────┐ │  │\n│  │  Calls forge │    │  │  Workflow Engine      │ │  │\n│  │  tools       │    │  │  • State machine     │ │  │\n│  └──────────────┘    │  │  • Claim queue (FIFO) │ │  │\n│                      │  │  • Git proof validator│ │  │\n│                      │  │  • Session manager    │ │  │\n│                      │  └──────────┬───────────┘ │  │\n│                      └─────────────┼─────────────┘  │\n│                                    │                 │\n│                      ┌─────────────▼─────────────┐  │\n│                      │    Linear (GraphQL API)    │  │\n│                      │    Stories, states, docs   │  │\n│                      └───────────────────────────┘  │\n└─────────────────────────────────────────────────────┘\n```\n\n### The Seven Agents\n\n| Agent | Owns |\n|---|---|\n| **po-agent** | Inception, story writing, backlog, story acceptance |\n| **ux-agent** | Empathy mapping, UX specs, design system |\n| **architect-agent** | Architecture Decision Records, service boundaries, tech debt |\n| **developer-agent** | ATDD loops, TDD inner loops, contract tests, feature flags |\n| **qa-agent** | Acceptance test authoring, desk checks, regression suite |\n| **devops-agent** | CI/CD, environments, feature flags, deployments |\n| **secops-agent** | Threat modeling, security ACs, SAST/DAST pipeline gates |\n\nEach agent loads its assigned skills at session start. Roles are enforced by\nthe workflow engine — the developer agent doesn't make architecture decisions,\nand the architect agent doesn't write production code.\n\n### Forge Tools\n\nThe extension registers five tools callable by the LLM:\n\n| Tool | Purpose |\n|------|---------|\n| `forge_claim_story` | Pull and claim the next available story for an agent role |\n| `forge_complete_ac` | Mark an acceptance criterion as complete with git proof |\n| `forge_handoff` | Hand off a story to the next stage with context summary |\n| `forge_create_artifact` | Create a document artifact in Linear |\n| `forge_log_progress` | Log progress on the current story |\n\n---\n\n## Installation\n\n### Prerequisites\n\n- [pi.dev](https://pi.dev) v0.80+ installed (`curl -fsSL https://pi.dev/install | sh`)\n- [Bun](https://bun.sh) runtime\n- A [Linear](https://linear.app) account with API access\n\n### Quick Start\n\n```bash\n# Install globally\nbun add -g @loopworx/forge\n# or: npm install -g @loopworx/forge\n\n# Initialize in your project\ncd my-project\nforge init\n\n# Start pi.dev — the forge extension auto-loads\npi\n```\n\n### What `forge init` installs\n\n| Path | Contents |\n|------|----------|\n| `.pi/extensions/forge.ts` | Forge extension entry point (imports from dist/) |\n| `.forge/` | Persistence directory (sessions.json, auth.json) |\n| `templates/agents/` | 7 agent profile definitions with skill assignments |\n| `templates/skills/` | 24 skills (SKILL.md + LOOP.md each) |\n| `templates/forge.yaml` | Config template — poll interval, concurrency, states |\n| `forge.yaml` | Project config (created from template) |\n\n### Configuration\n\n`forge.yaml` supports both camelCase and snake_case:\n\n```yaml\n# Polling\npollInterval: 30        # seconds between Linear polls\npullStates:             # states to pull stories from\n  - ready-for-dev\n  - ready-for-qa\n\n# Concurrency\nmaxConcurrentStories: 3\n\n# Linear\nlinear:\n  teamId: \"team-abc123\"\n  teamName: \"Engineering\"\n\n# Workflow states (all 14)\nstates:\n  unstarted: unstarted\n  inAnalysis: in-analysis\n  readyForDev: ready-for-dev\n  # ... etc\n```\n\n---\n\n## Delivery Pipeline\n\nStories flow through Linear workflow states:\n\n```\nin-analysis → ready-for-dev → in-dev → ready-for-qa → in-qa\n  → ready-for-acceptance → in-acceptance → ready-to-deploy → done\n```\n\n- **Stories are pulled, not assigned** — the engine polls for stories in pull states, claims them (pull → active), and creates agent sessions\n- **Handoff comments** — agents post compact summaries to Linear; the next agent reads them as context\n- **Failsafe** — if an agent forgets to update Linear state but posted a handoff comment, the engine auto-advances; if no comment, it halts as `halted-ambiguous`\n- **Crash recovery** — on startup, the engine checks `.forge/sessions.json` for orphaned sessions and re-claims active ones\n- **Commit per AC** — after each acceptance criterion goes green, the developer agent commits with `feat({STORY-ID}): AC{n} — {summary}` before desk check\n\n### Delivery Lifecycle\n\n1. **Inception** (8 phases) — PO, UX, and Architect agents facilitate structured discovery\n2. **Story Refinement** — Four-gate review: PO drafts → UX value gate → developer feasibility → QA testability\n3. **Iteration Zero** — CI/CD, environments, test harness scaffold, feature flags\n4. **ATDD Loops** — Outer Acceptance Test RED → sub-slice TDD (FE + BE) → GREEN → desk check\n5. **Kanban Flow** — Stories move through the Linear state machine independently\n6. **Feature Flags + Trunk-Based CD** — Everything on trunk; unfinished stories behind flags\n\n---\n\n## Skills Library (24 skills)\n\n**Meta**\n- `using-forge` — precedence rules, agent roles, session start protocol\n- `resuming-sessions` — query Linear + read CONTEXT.md before anything else\n\n**Discovery** (8-phase inception)\n- `facilitating-inception`, `facilitating-event-storming`, `establishing-ubiquitous-language`, `designing-ux`, `writing-stories`, `building-iteration-map`\n\n**Architecture**\n- `selecting-tech-stack`, `establishing-architecture`, `deciding-architecture`\n\n**Iteration Zero**\n- `bootstrapping-project`, `validating-test-harness`\n\n**Development (L1 Rigid)**\n- `running-atdd-sessions`, `running-tdd-loops`, `managing-feature-flags`\n\n**Quality \u0026 Acceptance**\n- `running-desk-checks`, `writing-acceptance-tests`, `running-regression-suite`\n- `approving-stories`, `finishing-stories`\n\n**Security**\n- `modeling-threats`, `securing-pipeline`, `guarding-loops`\n\nEach skill has a `SKILL.md` (instructions) and `LOOP.md` (loop protocol). All 24 are validated by 10 template tests.\n\n---\n\n## Development\n\n```bash\n# Clone\ngit clone https://github.com/loopworx/forge\ncd forge\nbun install\n\n# Checks\nbun run lint       # oxlint — 0 warnings, 0 errors\nbun run typecheck  # tsc --noEmit\nbun test           # 217 tests, 591 expect calls\nbun run build      # bundle → dist/pi-bridge.js + dist/forge-bridge.js\n\n# Test forge init locally\nmkdir /tmp/forge-test \u0026\u0026 cd /tmp/forge-test\nbun run /path/to/forge/bin/forge.ts init\n```\n\n### Project Structure\n\n```\nsrc/\n├── engine/          # Deterministic workflow engine\n│   ├── types.ts         # All types (WorkflowState, AgentRole, Story, etc.)\n│   ├── interfaces.ts    # 13 interfaces (StoryRepository, AgentRuntime, etc.)\n│   ├── events.ts        # EngineEventBus + 11 event types\n│   ├── state-machine.ts # 14-state Linear workflow state machine\n│   ├── claim-queue.ts   # FIFO serialization for concurrent claims\n│   ├── workflow-engine.ts  # Main engine: claimStory, completeAc, handoff\n│   ├── file-persistence.ts # .forge/ state persistence\n│   ├── memory-persistence.ts\n│   ├── system-clock.ts / fake-clock.ts\n│   ├── config-loader.ts    # YAML config with camelCase/snake_case\n│   ├── session-manager.ts\n│   └── git-proof-validator.ts\n├── bridge/          # pi.dev bridge layer\n│   ├── pi-bridge.ts           # Main extension entry point\n│   ├── forge-bridge.ts        # opencode bridge (alternative runtime)\n│   ├── pi-dev-runtime.ts      # AgentRuntime impl wrapping ExtensionAPI\n│   ├── pi-dev-session-manager.ts\n│   ├── create-pi-composition.ts  # Dependency wire-up + tool registration\n│   ├── harness-detector.ts\n│   ├── claude-bridge.ts       # Claude bridge (stub)\n│   └── opencode-bridge.ts     # opencode bridge (stub)\n├── linear/          # Linear integration\n│   ├── linear-story-repository.ts    # GraphQL + OAuth\n│   └── linear-document-repository.ts\n├── dashboard/       # TUI dashboard components\n│   ├── forge-layout.ts       # Orchestrator with auto-cycling\n│   ├── split-layout.ts       # SplitLayout + Sidebar + AgentPanel\n│   ├── forge-sidebar.ts\n│   ├── forge-agent-panel.ts\n│   ├── forge-chat-bar.ts\n│   └── dashboard-event-bridge.ts\n├── config/          # Config management\n│   └── config-loader.ts\n├── prompts/         # Agent prompt builder\n│   └── prompt-builder.ts\n└── cli/             # CLI commands\n    └── project-initializer.ts\n```\n\n### Pipeline\n\nEvery push to main runs a single sequential pipeline:\n\n```\nbuild → (typecheck ‖ lint) → test → release\n```\n\nThe release job auto-increments the npm version, publishes, creates a git tag,\nand generates a GitHub Release with commit history as release notes.\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Ensure `bun run lint \u0026\u0026 bun run typecheck \u0026\u0026 bun test \u0026\u0026 bun run build` pass\n4. Submit a PR\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopworx%2Fforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floopworx%2Fforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floopworx%2Fforge/lists"}