Companies, Projects, and Repos: How They Fit Together

4 min read Updated Oct 2026

New HQ users who see three container-like concepts and aren't sure which holds which.

~/HQ · how they connect

companies/acme/├─ knowledge/ what HQ knows about Acme├─ projects/ PRD-tracked work, e.g. dashboard-refresh/│ └─ points at → repos/private/acme-app/└─ settings/ Acme credentials, never visible to other companies

Projects live under a company and point at repos

HQ organizes work with three nested-feeling ideas that are actually three different things:

A company is a business or team you work with, a sealed compartment holding everything HQ knows about it.
A project is a piece of work with a goal and a finish line, like "redesign the pricing page" or "migrate the billing database".
A repo is an actual git code repository on your disk.

One line to remember: companies own context, projects own goals, repos own code.

What lives where#

shell

HQ/
├── companies/
│   ├── manifest.yaml            ← the master list of companies
│   └── acme/
│       ├── knowledge/           ← what HQ knows about Acme
│       ├── policies/            ← standing rules for Acme work
│       ├── projects/            ← Acme's active projects (goals + plans)
│       ├── workers/             ← Acme's AI specialists
│       └── repos/               ← shortcuts (links) to Acme's code
├── personal/
│   └── projects/                ← your projects that belong to no company
└── repos/
    ├── public/                  ← open-source code
    └── private/                 ← private code

A project folder (for example companies/acme/projects/pricing-redesign/) typically contains a PRD (a plan file listing the goal and the individual tasks) created by /prd. The project's plan records which repo the code changes happen in, which is how projects and repos connect.

The beginner questions, answered directly#

Can I have a project without a company?

Yes. Personal projects live in personal/projects/ and work exactly like company projects. /prd, /execute-task, and /run-project all understand them. Use a personal project for anything that isn't tied to a business: your website, a side experiment, learning HQ itself.

Where does a cloned repo go?

All code goes under repos/. Use repos/public/ for open-source and repos/private/ for everything else. It never goes inside a company folder. If you want HQ to properly learn a repo (not just clone it), say "discover this repo" or run /discover with the repo URL: HQ pulls it to the right place under repos/ and builds structured knowledge about it under the owning company.

How do projects and repos connect?

By reference. When /prd creates a project, the plan records the path of the repo the work targets. When you later run /execute-task or /run-project, HQ reads the plan, opens that repo, and makes the changes there. One repo can be the target of many projects over time, and a project can exist before any code does.

How do companies and repos connect?

Also by reference. The master list at companies/manifest.yaml records which repos each company owns, and each company folder has a repos/ directory containing shortcuts to the real code under repos/. The code lives in one place; companies just point at it.

Why are companies isolated from each other?

Because most HQ users work with more than one business, and Company A's private information must never end up in Company B's work. Each company keeps its own knowledge, credentials, policies, and settings in its own compartment. When you work on Acme, HQ loads Acme's context and only Acme's context, so an email drafted for one client can't accidentally quote another client's numbers, and Company A's API keys are never used on Company B's systems. HQ treats any cross-company leak as its most serious class of bug. Isolation is also what makes team sharing safe: you can give a teammate access to one company without exposing anything else. See Champion guide: rolling out to your team.

A concrete walk-through#

Say you consult for Acme and want to ship a new FAQ page on their site:

Acme already exists as a company (created with /onboard).
Their website code was pulled in with /discover and sits at repos/private/acme-site/.
You type /prd acme faq page. HQ interviews you briefly and writes a project to companies/acme/projects/faq-page/ with the plan pointing at repos/private/acme-site/.
You run /execute-task (one task) or /run-project faq-page (the whole plan). The code changes land in the repo, guided by Acme's knowledge and policies.

Company held the context, project held the goal, repo held the code.

Common questions#

I only work with one business. Do I still need a company?

Yes, make one with /onboard. It takes a minute. Everything HQ learns about that business needs a home, and a company folder is that home.

Can two companies share a repo?

Repos live centrally under repos/ and aren't tied to a company in companies/manifest.yaml (that file maps each company to its cloud vault, not to repos). If two businesses genuinely share code, keep the one repo and grant the other team access at the git level.

What's the difference between a project and an idea?

An idea is a one-liner captured with /idea for later. A project has a real plan. The path from one to the other is covered in From idea to shipped.

Do companies cost anything?

Creating companies is part of HQ itself. Cloud features for a company (team sync, shared vault) come with HQ Cloud. A company works fully offline and solo until you choose to cloud-back it.

If you get stuck#

If HQ puts work in the wrong company or can't find a repo, check companies/manifest.yaml. It is the source of truth for what exists and who owns what. For anything odd, start with the I'm stuck guide or report it with /hq-bug.