# ZPX Forge When a team builds software with Claude or Codex, its customer needs to know what was agreed and what shipped. Forge keeps the accepted scope revision, reads GitHub's run for the delivered commit and records the designated person's decision. Start with an idea or connect a repository. Before building, define the first outcome the customer can test. During development, the team reads the plan, reports blockers and records checks. At delivery, the customer can inspect evidence and accept the version or request a correction. Open the [quickstart](/docs/quickstart) to create your project. To onboard your agent, copy the [Instructions for Claude or Codex](/docs/agent-brief). --- # Quickstart ## 1. Create your account Open [Create account](/signup) and choose **Continue with GitHub**. Use a GitHub account with a verified email. If invited, use the account associated with the invited email. ## 2. Register your company In onboarding, enter the company name and what you will use ZPX Forge for. Your workspace is ready immediately. ## 3. Connect GitHub In **GitHub → Install on GitHub** pick the account or organization and the repos ZPX Forge can see. When you come back, the installation is linked to your company. > You must administer that GitHub account to install the app. This is how we prevent anyone from > linking repositories that are not theirs. ## 4. Create a project and add its code folders A project can have one or several repos: `front`, `back`, an `app` monorepo… One of them is the **spec home** (where SpecKit's `specs/` lives). With Pro, select a starter project in the architecture step. Its charter includes the reference design, suggested first delivery, acceptance test and signals to monitor. Claude or Codex reads the same design with `zpx context --json`. ## 5. Protect your branches On each project repo, **Protect develop and main** creates a GitHub rule: those branches only change through pull requests, with no deletion and no force-push. ## 6. Invite your team With Pro, in **Team** you invite people by email with a role. Each person can also have a different role in a specific project. From then on, every push, PR and check in your repos shows up in the project activity. ## Release assurance with Pro In Project → Hitos, agree on an outcome with the person receiving it. Select the repository, workflow, test file and exact job and step names. The workflow must run the agreed test on push to the production branch. Query GitHub CI from the milestone. Without a run for that commit the evidence remains pending. Create the release from the passing milestone, review risks and share the approved sheet. The designated person accepts that version or requests corrections on their private sheet. To work through this with your agent, open [Instructions for Claude or Codex](/docs/agent-brief). ## Example acceptance test in GitHub Actions For a Python project with an isolation test in unittest, this workflow runs one specific case. Substitute your production branch, test module and method, and install your project dependencies before the test step. Agree with the customer on the behavior this case demonstrates. ```yaml name: Acceptance on: push: branches: [main] jobs: acceptance: name: Customer acceptance runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - name: Verify customer isolation run: python -m unittest tests.test_isolation.IsolationTest.test_other_customer_cannot_read ``` Save the workflow as `.github/workflows/acceptance.yml`. In the milestone select this workflow, `tests/test_isolation.py`, job `Customer acceptance` and step `Verify customer isolation`. Forge can record an observed result once it finds the agreed commit and step in GitHub. ## Activate Pro Individual includes one company and up to two personal projects. Pro costs US$10 per member and includes unlimited companies, projects and team members, team feedback and release assurance with CI evidence. Sign in and open the company home to review the terms and activate Pro. --- # Concepts | Concept | What it is | |---|---| | **Company** | The customer. It has members, projects, GitHub installations and its own harness. A person can belong to several companies. | | **Project** | What is being built. It groups repos, specs, backlog, harness and autonomy level. | | **Repository** | A code folder of the project on GitHub (`front`, `back`, `infra`…). It has an integration branch (`develop`) and a production branch (`main`). | | **Spec home** | The repo where SpecKit's `specs/` lives for that project. | | **Spec** | A SpecKit feature: `spec.md` (what and why), `plan.md` (how) and `tasks.md` (tasks). | | **Harness** | The rules your agents follow in a project: standards (`AGENTS.md`), commands and which decisions require a person. | | **Agent** | Claude Code, Codex or another agent with CLI access, running on a developer's machine with their own subscription. | | **Phase / wave** | A phase is a milestone with value (MVP, v1…). A wave is a group of tasks that share no files and can run in parallel. | | **Task classification** | Every task has an **area** (`docs`, `ui`, `api`, `core`, `data`, `infra`, `security`), a **size** (XS–XL) and a **risk** (R0–R3). Risk decides how much documentation, review and approval it needs. | | **Subagent** | A short-lived helper an agent launches: `explorer` (reads), `verifier` (runs checks), `reviewer` and `challenger` (adversarial review). | | **Report** | Structured output an agent sends to ZPX Forge (spec, plan, progress, review, blocker, delivery). People read it as a view, not as a file. | | **Approval** | A decision that requires a person: spec, architecture, risky action or production release. | ## The life of a feature ``` Scope → spec.md → approval (PM/PO) → plan.md + tasks.md → backlog → a developer picks a task → their agent works in a worktree and a branch → PR to develop → review → approved release → main = production ``` ## Branches | Branch | Purpose | Who changes it | |---|---|---| | `main` | Production | Only through an approved release PR | | `develop` | Integration / staging | Through PRs from task branches | | `feat/-…` | One task, short-lived | The developer and their agent | ## Evidence and decisions Declared evidence comes from the team. Observed evidence includes the result Forge reads from GitHub for the commit and agreed test. Accepted risks identify the reason and owner. The release owner decides whether to share the sheet. The customer decides whether to accept that version. --- # Companies and roles ## Company registration Anyone with a GitHub account and a verified email can register a company. It is active immediately. Whoever registers it becomes its first **admin**. A company can never be left without an admin. ## Company roles | Role | Does | |---|---| | Company admin | Members, invitations, GitHub and settings | | Product Owner | Vision, priorities, approves specs and releases | | Project manager | Backlog, assignments, approves specs | | Tech lead | Architecture, repos, harness, risky actions | | Developer | Picks tasks and works with their agent | | Reviewer | Reviews pull requests | | QA | Validates on staging | | Observer | Only sees progress (for example, the end customer) | ## Project roles Each person has a company role and, optionally, **a different role in a specific project**. A developer can be the tech lead of one project without being it in the others. ## Current permissions | Action | Roles | |---|---| | Manage the company (members, invitations, GitHub, audit log) | Admin | | Create projects | Admin, Product Owner, Tech lead | | Adjust roles within a project | Admin, Product Owner, Tech lead | | Connect repos and protect branches | Admin, Tech lead | | See the company and its projects | Every member | ## Invitations With Pro, administrators invite team members by email. Invitations include a role and expire after 7 days. The link can also be copied and shared. ## Isolation Anyone who does not belong to a company gets *not found* everywhere: they cannot even tell it exists. ## External milestone customer The editor can designate a customer by email without inviting them to join the organization. With their verified email and private link, customers can review scope and decide on their delivery. Use the public link of an approved version to share a read-only sheet. --- # GitHub ZPX Forge connects to GitHub through a **GitHub App** that each company installs on its account or organization, choosing which repos it can see. ## Verified installation When you come back from GitHub, the installation is only linked if: 1. that same person started it, for that company; 2. they are a company admin in ZPX Forge; 3. they control the GitHub account: it is their own, or they are an admin of the organization. An installation belongs to a single company. ## Permissions the app requests | Permission | Why | |---|---| | Contents · read and write | Read `specs/`; propose specs through pull requests | | Pull requests · read and write | Track and open PRs | | Checks and statuses · read and write | Read or publish checks according to configuration | | Deployments · write | Approve or reject the commit for a production environment protected by Forge Pro | | Actions · read | See CI runs | | Administration · read and write | Protect `main` and `develop` (optional) | | Members · read | Match organization members | ## Branch protection From a project, **Protect develop and main** creates a *ruleset* named `ZPX Forge · ramas protegidas` in the repo: changes only through pull requests, no deletion and no force-push. If it already exists, it is updated. ## Webhooks and activity Every delivery is verified with its signature (`X-Hub-Signature-256`), stored only once even if GitHub retries it, and processed in the background. It becomes project activity: | GitHub event | Activity | |---|---| | `push` | `push` (flags whether `specs/` changed) | | `pull_request` | `pr.opened`, `pr.merged`, `pr.closed`, `pr.reopened` | | failed `check_suite` | `check.failed` | | failed `workflow_run` | `ci.failed` | | `installation`, `installation_repositories` | Syncs installations and repos | --- # Work with me in ZPX Forge Work in this repository with my agent and subscription. Use Forge to read the customer agreement, coordinate tasks and record the release. The team shares this history across sessions and agents. Stay within the scope I authorize in this chat. ## Identify the project 1. Run `zpx version` and `zpx doctor --json`. I can install the CLI with `uv tool install zpx` or update it with `uv tool upgrade zpx`. 2. If access is missing, ask me to enable CLI reports in Team → profile and authorize `zpx login` in my browser using my GitHub account. Keep credentials on my machine. 3. Use `zpx whoami` and `zpx projects` to identify my account and project. Once confirmed, bind the directory with `zpx use COMPANY/PROJECT --here`. Replace example identifiers with actual values. 4. Read `zpx context --json`. Check the project, responsibilities, plan and agreements under `milestones`. With permission to configure the repository, run `zpx skill install` and read the installed AGENTS.md and skills. If `harness.sync.required` indicates changes, sync and check the context again. Ask me about conflicts with locally edited files. ## Before building Starting from an idea, help me describe the first outcome we can demonstrate to the customer. Starting from an existing repository, CLI 0.2.4 provides `zpx audit --json` to identify tracked environment files and GitHub Actions workflows in the local index. This diagnostic inspects filenames only. In Project → Hitos, the editor proposes a testable criterion, demonstration, exclusions, due date and decision maker. That person receives a private sheet to accept the revision or request changes. Work against the last accepted revision. Propose a new revision when the promise changes. ## During development Read `zpx today` and `zpx plan`. Open the actual task with `zpx task show T003`. After I confirm the assignment, use `zpx task take T003` and `zpx task start T003 --agent codex --branch my-branch` with the actual agent and branch. Record progress with `zpx task progress T003 "tested outcome"`. Add `--check tests=pass` only after running those tests. Record the tested commit and open issues. Use `zpx task blocked T003 "reason"` for blockers. Consult `zpx can-publish BRANCH` before publishing and respect the authorization I gave. Keep credentials and customer data out of reports. ## Release assurance and acceptance (Pro) In the milestone, associate the repository and production branch push workflow with the test file and exact job and step names. A reviewer checks whether the test exercises the criterion. Forge queries GitHub for that commit. Each new commit needs its own run. Changing the agreed workflow or test requires renewing the agreement. Distinguish what the team **declared** from what Forge **observed** on GitHub. An **accepted risk** records the person taking responsibility and their reason. Mark missing CI as pending. A team member with delivery permission creates the release from the passing milestone. Its owner decides whether to publish a read-only snapshot valid for 30 days. The designated customer signs in with their verified email on the private sheet to accept that version or request corrections. Tell me which version and commit shipped, where I can inspect the evidence and who owns the next decision. Use `zpx help`, `zpx guide milestone` and `zpx guide evidence` for guidance. Full documentation is available at https://www.zpxforge.com/llms-full.txt. --- # Build with AI Open [Instructions for Claude or Codex](/docs/agent-brief), select **Copy instructions for Claude or Codex**, then paste into a session in your repository. The brief covers setup, project selection, harness, tasks and acceptance. Run `zpx doctor --json` to inspect the local environment and `zpx help` to explore commands. The full documentation is also available in [Markdown](/llms-full.txt). --- # API The API lives at `https://zpxforge.com/api/v1`. The full specification (OpenAPI) is at [`/api/v1/docs`](/api/v1/docs). ## Authentication Today the API uses the **browser session** (an `httpOnly` cookie). Requests that change data must come from the site itself (`Origin` header). The CLI uses a personal token authorized in the browser for supported endpoints. Customers record decisions in their verified web sessions. ## Endpoints | Method and path | What it does | |---|---| | `GET /v1/health` | Platform health (database, Redis, worker) | | `GET /v1/me` | The person, their companies and pending invitations | | `GET /v1/roles` | Available roles | | `POST /v1/orgs` | Register a company | | `GET /v1/orgs/{company}` | Company, your role and your permissions | | `GET /v1/orgs/{company}/members` | Members | | `PATCH /v1/orgs/{company}/members/{id}` | Change a member's role | | `POST /v1/orgs/{company}/invitations` | Invite by email | | `GET /v1/orgs/{company}/projects` | Projects | | `POST /v1/orgs/{company}/projects` | Create a project | | `PUT /v1/orgs/{company}/projects/{p}/roles/{id}` | A person's role within a project | | `GET /v1/orgs/{company}/github` | GitHub installations and repos | | `POST /v1/orgs/{company}/projects/{p}/repos` | Connect a repo to the project | | `POST /v1/orgs/{company}/projects/{p}/repos/{id}/protect` | Protect `develop` and `main` | | `GET /v1/orgs/{company}/audit` | Audit log (admins only) | ## Errors ```json { "detail": "Tu rol no permite esta acción", "code": "forbidden" } ``` Error messages are in Spanish for now; rely on `code` and the HTTP status. | HTTP status | Meaning | |---|---| | `401` | You need to sign in | | `403` | No permission, inactive company or origin not allowed | | `404` | It does not exist or you do not belong to that company | | `409` | Conflict (for example, the last admin) | | `429` | Too many attempts | --- # Security ## Your code ZPX Forge does not store code. Agents work on each developer's machine; the platform only keeps metadata (projects, tasks, events) and what GitHub exposes to the app you install. ## Isolated companies All business data belongs to a company and is queried through it. Anyone who is not a member gets *not found*. Automated tests verify this on every change. ## Accounts Web sign-in requires GitHub and a verified email. To accept an invitation or decide on a release, use the account associated with the designated email. Forge keeps the session in a protected cookie and checks the origin of requests that change data. ## GitHub - An installation is only linked if the person controls the GitHub account. - Webhooks are verified with their signature and processed only once. - The app's private key never leaves the server. ## Infrastructure ``` Browser → zpxforge.com (Vercel) → AWS load balancer (HTTPS) → private backend ``` The backend has no public IP and only accepts traffic that went through Vercel, identified with a shared key. ## Audit log Every relevant action (registration, approvals, invitations, roles, repos, GitHub) is recorded with who, when and from where. ## Shared sheets Anyone with the public link can view the snapshot for 30 days or until revocation. To decide on a delivery, an external customer opens the private link using the verified email account designated for the milestone. ## Pro security audit From a linked target repository, sign in with `zpx login`, select your project with `zpx use company/project`, then run `zpx audit`. Use CLI 0.3.0 for Pro. Use `zpx audit --pdf report.pdf` to save the PDF locally when recording a revision. The basic `zpx audit` still works without an account. Pro reads committed files, checks Python, JavaScript and TypeScript source, flags environment files and missing workflows, detects npm deprecations and looks up public npm and PyPI versions from package-lock.json and uv.lock in OSV. It compares direct public dependencies with registry releases and checks Kubernetes memory limits and readiness probes. It also checks synchronous requests without explicit timeouts and dynamic privileged messages. For a repository-owned JSON message template ending in `.prompt.json`, it inserts an inert sample at `{{document}}` and checks which message role receives it. The report records coverage. Runtime load and model behavior require separate evaluation. Add `--agent claude` or `--agent codex` to generate an executive interpretation with the Forge security auditor profile. The selected client receives totals, up to 15 prioritized findings and up to 10 coverage gaps. Its attributed commentary appears in the portal and PDF alongside severity, evidence and remediation tables. The responsible reviewer retains release authority. Open **Project → Auditoría de seguridad** for the private versioned PDF. Each finding generates a proposed specification. The spec owner can select individual findings or use **Seleccionar todas**. Approving the selection adds new tasks to the earliest open wave. Adding tasks to an approved or active wave also requires plan approval rights. If all waves are closed, the plan owner must explicitly choose where to continue. After committing fixes, run the command again to compare new, persistent and no-longer-detected findings. Incomplete coverage leaves earlier findings unverified. A release decision owner must approve the latest report for the exact commit. High, critical and unclassified risks and incomplete checks block approval. In **Plan → Gestión del plan**, choose **Revisiones de seguridad** to filter historical remediation by status. Open **Entregas → Auditoría de seguridad** for the audit report history. For actual deployment enforcement, enable the ZPX Forge custom protection rule on the GitHub production environment used by the deployment job. Grant the installation Deployments write permission and subscribe the app to the deployment_protection_rule event. After rejection, resolve findings, audit and approve the new revision, and rerun the workflow. The same command checks your subscription and project permissions. Pro enables the full report automatically. Individual runs the basic diagnostic. Requesting a PDF or AI interpretation without access returns an explanation that Pro is required.