# Installing Workspace Foundation Package `workspace-foundation`, version 1.4.0. Apex Instruments is fictional and so is everything in this guide, but the steps are real ones. This is the guide for somebody who has not done this before. It assumes you know how to make a folder and how to add somebody to a group, and it assumes nothing else. Read it once through before you start. It takes about ninety five minutes if nothing is in your way, and about three hours if the permissions part is in your way, which it usually is. If you get stuck, the answer is almost never to skip a step. It is to go back one step and check the thing that step told you to check. --- ## Before you start Three things have to be true. If any of them is not, stop and fix it, because every one of them will block you halfway through and you will have to undo work. **1. You have picked where the workspace lives.** A shared drive, a document library, an object store, or a git repository. It does not matter which one for this guide. What matters is that the decision is made and everybody has an account there. Write the decision down in one sentence somewhere people will see it. **2. One named person can create a folder at the top level and set permissions on it.** This is the step that quietly blocks installs for a fortnight while somebody waits on an IT ticket. Confirm it now, by actually creating a throwaway folder and setting a group on it, then deleting it. If you cannot do that, you are not ready to start. Go and get that access first. **3. You have a list of people and roles.** One file. Name, role, and what each person owns. Five rows is enough. You will use this in step 6 and step 10, and half the other packages read it later. You do not need the assistant set up yet. That is step 10 and this guide covers it. ### Words this guide uses - **Folder** means whatever your provider calls a container. On an object store it is a prefix. In a git repository it is a directory. The shape is the same everywhere. - **Group** means whatever your provider calls a set of people you grant access to as a unit. A permission level, a policy, a code owner rule. Same idea. - **The scheme** means the folder layout this package installs. It is a written document. Read it before step 2, not during. - **A stage** is one of the five folders every person's work passes through: intake, in progress, for review, approved, archived. --- ## Step 1. Decide where it lives and write that down Write one sentence in a place people will find it: "The Apex workspace is on X, and Morgan Reyes owns it." **Why this is a step.** In six months somebody will ask where the real version of a document is, and the answer needs to exist in writing rather than in a person. This sentence is the smallest possible version of that answer. **Check:** you can point at the sentence. --- ## Step 2. Create the root folder and the five shared folders Make one folder to hold everything. Call it something dull and permanent. Inside it, make exactly these five, spelled exactly like this: facts approved templates knowledge plans Do not add a sixth. Do not rename one because your company has a different word for it. Other packages look for these names, and the whole point of a scheme is that it is the same everywhere. **Why this is a step.** These five are the answer to "where does this go". `facts` holds the numbers everything quotes. `approved` holds the current version of anything anyone may send out. `templates` holds the frames work starts from. `knowledge` holds how things are done here. `plans` holds what we intend to do. Every piece of work is one of those five things or it is somebody's work in progress, which gets its own place in step 6. **Check:** all five folders exist, spelled correctly, and there is nothing else at the top level. --- ## Step 3. Create the six permission groups and put people in them Make these six groups: everyone operations marketing sales success leadership Put every person in `everyone`. Put each person in the one group that matches their role. Somebody who genuinely spans two roles can be in two. Nobody should be in all of them. **Why this is a step.** Permissions get set on groups, never on people. The first time you set a permission on a person by name, you have created a thing that breaks silently when that person leaves. **Check:** every person is in `everyone` plus at least one role group, and nobody is in all six. **If your provider does not do groups:** on an object store, these are policy names. In a git repository, these are the teams your code owner rules refer to. Make the six anyway, under whatever they are called. --- ## Step 4. Set read on the whole root to everyone Give the `everyone` group read access to the root folder and let it inherit down. **Why this is a step.** Wide read is the load-bearing decision in the whole scheme. If people cannot see each other's work, they make copies, and copies are the thing this whole system exists to stop. There is nothing in this workspace that a colleague should not be able to read. **Check:** sign in as the person with the fewest permissions and open every one of the five shared folders. If you cannot, the inheritance did not take. Fix it before you go on. **This is the check people skip.** Do not skip it. Inheritance is silent on most providers, and if it did not take you will find out in step 12 instead, after you have built forty more folders on top of it. --- ## Step 5. Set write on each shared folder to the group named in the scheme From the scheme: | Folder | Who may write | |--------------|-----------------------------------| | `facts` | operations | | `approved` | nobody, only the approval route | | `templates` | operations, marketing | | `knowledge` | everyone | | `plans` | leadership, marketing, operations | `approved` is the odd one. For now, set its write access to a group with nobody in it. You will hand that group to the approval route when you install that package. If you set `approved` to be writable by a person now "just until the route is in", it will still be writable by that person in a year. `knowledge` being writable by everyone is deliberate. An untidy knowledge folder costs less than nobody writing anything down. **Check:** run the permission check that ships with this package. It reads the effective permission on every folder and compares it to that table. It should pass on all five. --- ## Step 6. Create the work folder and one zone per person Make a sixth top level folder called `work`. Inside it, make one folder per person in your people list. Use a consistent naming style: all lowercase, first name and last name joined by a hyphen, is what the scheme uses. work/morgan-reyes work/sami-torres work/jordan-vale work/avery-kellen work/dana-whitfield **Why this is a step.** Work has an owner before it has a category. Somebody is always responsible for a piece, and the zone is where you look to find out who. **Check:** one folder per name in the people list, and no folders for anybody who is not on it. --- ## Step 7. Create the five stage folders inside every zone Inside every single zone, make these five, spelled exactly like this: intake in-progress for-review approved archived Yes, in every zone. Yes, even for the person who says they do not need stages. **Why this is a step.** The identical shape is the feature. Anybody can find anything in anybody else's zone without being told where to look, because there is only one place it could be. The moment one person's zone is different, everyone has to ask. **Check:** five folders per zone, spelled the same way in every one. Count them. If you have five people you should have exactly twenty five stage folders. **A note on spelling.** `in-progress` with a hyphen, not `in progress` with a space and not `inprogress`. The skills match on these names. --- ## Step 8. Lock the approved stage so only the route can write to it Inside every zone, set the `approved` stage folder's write access to the same empty group you used in step 5. **Why this is a step.** This is the rule the entire scheme rests on. `approved` means a named person signed this off. If anybody can drag a file into it, then `approved` stops meaning that, and within two months nobody trusts it, and everybody goes back to asking which copy is current. **Check:** try to put a file in one of the approved folders as yourself. It should be refused. If it is not refused, the permission did not take and you should stop and fix it now. --- ## Step 9. Put a readme in each top level folder Copy the folder readme template into `facts`, `approved`, `templates`, `knowledge`, `plans`, and `work`, and fill each one in. The template asks four things: 1. What belongs here. 2. What does not belong here, with an example. 3. Who may write here. 4. Why the boundary is there, in one sentence. Answer all four. The fourth one is the one people skip and the one that stops the argument in six months. **Why this is a step.** A folder scheme with no readmes is a folder scheme that gets misused politely by everybody, because nobody wants to ask an obvious question. The readme answers the obvious question. **Check:** run the readme check. Every top level folder has one and none of them is empty. --- ## Step 10. Give the assistant its own account Create an account for the assistant. Not a shared login. Not a person's credentials. Its own. Put it in: - `everyone`, so it can read the same things a person can read. - Nothing else, for now. Then grant it write access to every `intake` folder and every `in-progress` folder. It needs those two and no others. **Why this is a step.** Two reasons, both worth the ten minutes. First, if the assistant signs in as a person, the activity record can no longer tell you who did what, and the record is most of the value of having one. Second, an assistant with its own identity can be given exactly the access it needs, which turns out to be much less than a person's. **Check:** ask the assistant to read a file from `facts` (it should be able to) and to write a file into `approved` (it should be refused). --- ## Step 11. Install the three skills and the two agents The skills: - **Where does this go.** Give it a piece of work, it names the one folder that piece belongs in. If two folders are plausible it says so rather than picking. - **Open a work item.** Creates an intake entry with an owner, a kind, and a due date. It refuses an item with no owner, which is the point. - **Move a stage.** Moves a piece between the five stages and writes the move to the activity record. The agents: - **Stage keeper.** Runs nightly. Flags anything sitting in one stage longer than its kind allows. It reports. It never moves anything. - **Orphan finder.** Runs weekly. Lists files that are not in any stage, and any folder that is not in the scheme. Install them wherever your assistant reads its skills from. The package ships them as files; put the files there. **Check:** ask the assistant where a spec sheet goes. It should name one folder, and it should be `approved/collateral` if the sheet is finished or the owner's `in-progress` if it is not. If it names two, or invents a folder, the skill did not load. --- ## Step 12. Run all three checks and fix what they report Run: - **Scheme check.** Every folder in the scheme exists, and nothing exists that is not in the scheme. - **Permission check.** The effective permission on every folder matches the published rule. - **Readme check.** Every top level folder has a readme and none is empty. Fix what they report. **Some of it you will decide not to fix.** That is allowed. Write down each one you are leaving and why, in `knowledge/decisions`. A known exception with a reason is fine. An unknown exception is how a scheme rots. **Check:** three green results, or a written reason for every one that is not green. --- ## How you know it worked Not "the checks passed". These three: 1. **A person who has never seen the workspace can find where a proposal goes without asking.** Test it on somebody. Do not tell them anything. Watch where they look. 2. **Nobody can write into `approved` by hand.** Test it yourself, as the most privileged person you have. 3. **The assistant reads the same paths a person does.** Ask it for something and ask a person for the same thing. The path should be identical. If all three are true, this package is installed. If the checks pass but a person still cannot find anything, the checks passed and the install did not. --- ## What usually goes wrong **The permission in step 4 did not inherit.** Most common failure by a distance. Inheritance is silent on most providers, so nothing tells you. Symptom: somebody says "I cannot see the templates folder" in week two. Fix: re-run the permission check, which reads the effective permission rather than the one you think you set. **Somebody renamed a stage folder.** Symptom: the move-a-stage skill starts failing for one person. Fix: rename it back. Do not teach the skill the new name. The whole value is that they are the same. **`approved` is writable "just for now".** Symptom: files in `approved` with no record beside them. Fix: move them out to their owner's `in-progress`, close the permission, and put them through the route when you install it. This is annoying and it is much less annoying now than in a year. **Somebody added a sixth top level folder.** Usually called `misc` or `shared` or a year. Symptom: the scheme check names it. Fix: work out which of the five it actually belonged in. It is always one of the five. **The people list was out of date.** Symptom: a zone for somebody who left, or no zone for somebody who joined. Fix the list first, then re-run step 6. Do not fix the folders and leave the list wrong. --- ## What to install next Nothing else in the registry works properly until this one is in. Once it is: - **Facts Register** next, always. It is the cheapest one and it is what makes every other package worth having. - **Brand Kit** before anything that produces an output, or the outputs will be wrong and you will fix them by hand. - **Approval Route** before you start relying on `approved` meaning anything. The plan builder in the package browser will work the order out from the dependency graph if you tell it what you want. --- ## If you have to undo this Everything this package does is folders and permissions. Nothing is destructive. To back out: 1. Turn the two agents off. 2. Remove the three skills. 3. Leave the folders. They are not hurting anybody, and somebody has probably already put work in them. There is no uninstall script, on purpose. A script that deletes folders is a script that deletes work.