Skip to content

Working with workspaces

Your firm has a workspace — a version-controlled file tree that holds your QA governance: the constitution, your rules, your projects, and the agent briefs that shape how the QAQC Coordinator and specialists behave. It is the single source of truth the agents read every time they check a model. Change a file here and behavior changes on the next run — no software update needed.

You browse it in the app's Workspace panel (a file tree + viewer). Most changes are made for you by the Setup agent in conversation; this page explains the structure so you know what you're looking at and what's safe to change.

How it's organized

<your firm>/
├─ constitution.md          # Firm-wide QA principles, injected into every agent
├─ agents/
│  ├─ roster.yaml           # Maps each agent to its brief (managed)
│  ├─ coordinator.system.md # The Coordinator's brief
│  ├─ setup.system.md       # The Setup agent's brief
│  └─ <discipline>.system.md# One brief per specialist (Structural, MEP, …)
├─ templates/               # Starting point copied into each NEW project
└─ projects/
   └─ <project>/qaqc/
      ├─ project.yaml        # Project metadata + disciplines in scope
      ├─ constitution.md     # Project-level principles (override the firm's)
      ├─ rules/              # CANONICAL, active rules (one folder per rule)
      │  └─ _by-discipline/  # Which rules belong to which discipline
      ├─ rules-proposals/    # Draft/candidate rules awaiting promotion
      ├─ knowledge/          # Reusable notes the agents write & reuse
      └─ reports/            # Saved verification reports (generated)

The constitution

The constitution is your firm's QA charter in plain language — your standards, priorities, and house rules. It's injected into every agent, so it steers judgment across all checks. There's a firm-wide constitution and, optionally, a per-project one that refines it for a specific job.

Each constitution has two parts:

  • A managed section the Setup agent maintains. Don't hand-edit it — the Setup agent regenerates it.
  • A user-customized section that's yours to edit freely.

What you can change vs. what to leave alone

File / folder Edit it? Notes
constitution.md (user section) ✅ Yes Your house rules and priorities.
projects/<id>/qaqc/constitution.md (user section) ✅ Yes Project-specific overrides.
agents/<discipline>.system.md ✅ Yes Refine a specialist's brief (what it checks, how it reports). Keep the structure.
projects/<id>/qaqc/project.yaml ✅ Yes Disciplines in scope, metadata.
rules-proposals/ ✅ Yes Draft rules live here before promotion.
knowledge/ ✅ Append Reusable notes; add, don't rewrite history.
constitution.md (managed section) ⛔ No Regenerated by the Setup agent.
agents/roster.yaml ⚠️ Rarely Wiring of agents → briefs; the Setup agent maintains it.
rules/ and rules/_by-discipline/ ⛔ No Canonical rules. Only the Setup agent should change these (promotion keeps the index in sync). Hand-edits can break discipline routing.
reports/ ⛔ No Generated verification reports — read-only.
templates/ ⚠️ Careful Editing changes what new projects start from; existing projects are unaffected.
project.yaml/firm.yaml ids ⛔ No Identifiers and internal pointers.

Let the Setup agent drive structural changes

Adding rules, creating projects, and spinning up discipline specialists are best done by asking the Setup agent — it edits the right files, keeps the rule index consistent, and promotes drafts safely. Reserve hand-edits for prose (constitution, briefs).

How changes take effect

The workspace is git-backed. When you (or the Setup agent) save a change, it's committed and becomes the new source of truth. The next time an agent runs, it reads the latest state — so a refined constitution or a new rule is live on the next check. There's no deploy step and no restart.

Because it's versioned, the history of who changed what is preserved, and the Setup agent can update the managed parts without clobbering your edits.

See also