Working on a company

The review loop is how a change gets decided. This page is where the change lives until then: a work. Five steps — start, propose, decide, finish, adopt — and you can come in at any of them.

A work is three things that always travel together:

• a branch, work/<you>/<slug>;
• a record on that branch, .structure/work/<slug>.md: the title, who opened it, when, what it was cut from, and whether it is open or closed. You never write it; the commands do;
• a checkout of its own, in a folder beside the company: .structure-worktrees/<company>-work-<slug>.

Your company's own folder stays on its one copy, main. The work happens next to it.

Everything here is a command. Where a build carries the IDE (see Install and first run), its Home shows the same works and offers the same steps as buttons; the steps below say what Home shows where it matters. A build without the IDE does all of it from the terminal.

1. Start

structure work start "tighten the pricing page"

This cuts work/<you>/tighten-the-pricing-page from main, writes the record, opens the checkout and prints its path on the last line. cd there and work in whatever editor you like. It also adds the push gate, .githooks/pre-push, which refuses to push a work branch that has no record. Arm it once per clone with git config core.hooksPath .githooks.

structure work status

Run from inside the checkout, it shows the record and where the work stands on this machine: entered (here and current), behind (a coworker pushed more to it), or closed.

A work someone else started shows up on your Home as new from origin. Enter makes the checkout on your machine; Update brings a checkout current with what they pushed, and only when you have no unsent edits. Neither moves anything of yours.

structure work start refuses, and says why, when the title has no letter or digit in it, when that branch already exists (here or at origin, started on another device), or when there is nothing to cut from.

2. Propose it

In the checkout, propose the way you always do:

structure propose company/pricing.md -m "what changed and why"

A proposal is a step of the work: it is filed on it. The work's record lists the proposal, and the work's branch is shared so whoever decides can see the work it belongs to. Nothing about the proposal itself changes. It is still the same card, the same check, the same approval.

You do not have to start a work first. Propose from your company folder, or save a change in the IDE to a document the company gates, and Structure starts the work for you (work/<you>/<slug>, with its record, and no checkout) and files the proposal on it. You will see a line saying so.

3. Decide

structure queue
structure approve <id>

On Home a work with a proposal on it reads in the proposal's state:

• waiting on you — the decision is yours. Decide opens the proposal right in its row: its documents, then Approve and Discard. It is the card from the review loop.
• suggesting · waits on Miranda — someone else decides. You can read it; there is no button. Who decides follows the rule you set for that kind of document: if a role gates it, the people who hold that role.

Approving your own proposal is the ratification, as it always was.

A proposal that was made before works existed has no work. It is listed by its own title, in the same two states, and nothing invents a record for it.

4. Finish

structure work finish

finish runs structure check on the checkout and refuses on any error, printing the check's own line. It also refuses while the checkout has changes you have not committed, because it pushes what is committed and nothing else. When both are clean it closes the record and pushes the branch.

A work stays open after its proposal is approved. Closing it is finish.

5. Adopt a branch you cut by hand

Branches that were not made this way are outside the contract. structure check says so with one quiet line per branch:

site-fixes is outside the work contract — run: structure work adopt site-fixes

It is information, not a failure. To bring one in:

structure work adopt site-fixes

That writes the record and renames the branch to work/<owner>/<slug>, here and at origin, in one step. The branch's commits are untouched; adopting adds one commit, the record. It refuses, and renames nothing, when a checkout of the branch has unsaved changes, when it has commits origin does not, or when the new name is taken. --owner <segment> names someone other than you.

On Home, outside branches are one line below your work: N branches outside the contract · Review. Review lists each with who last touched it and when. Adopt does the same as the command. Close deletes the branch, here and at origin, after you confirm; it refuses while a checkout of it has unsaved changes.

A whole company at once

For a company with a pile of old branches, print the plan first:

structure work adopt --all --dry-run

It reads every branch at origin and gives each one a disposition: delete (cut by hand and already merged into main), adopt (not merged: renamed into a work, owned by whoever made its last commit, or by --owner <branch>=<segment>), hold (it needs a better name first, and the row says so), or leave (the company's main, proposals, works already in shape, and the branches Structure keeps for its own records). Then:

structure work adopt --all --yes

does it, one line per branch, and ends moved — N of N. The branches Structure keeps for its own records are never listed, counted, or offered for adoption.

When something's off

• structure work status — the record and presence of the work you are standing in.
• structure check — a work branch with no record is a warning with the command that fixes it; a record that does not parse is an error, and structure work adopt <branch> rewrites it.
• A rename that stops — unsaved changes, unpushed commits — says which and renames nothing. Commit or push, then adopt again.

A work is a branch, its record is a file on it, and finishing is a push with the check passing — Structure never makes you say it that way.