My workspace
I have a single workspace that almost all of my work with an agent goes through. It holds projects, what is known about the infrastructure, completed tasks, and instructions for repeatable operations.
It solves a simple problem: a new session does not know what happened in the previous one. Without saved context, the agent looks up the same server again, re-derives a command it already found, and repeats old mistakes. In the workspace, it first reads what is known about the task, and updates that knowledge once the work is done.
Documents here are not treated as truth on their own. If a card lists an old port, or a playbook no longer works, the agent fixes it within the same task. Otherwise the workspace quickly turns into an ordinary wiki that nobody trusts.
Workspace structure
workspace/
├── CLAUDE.md # the workspace constitution
├── projects/ # active projects
├── infra/ # map of servers, services, and people
│ ├── servers/
│ ├── services/
│ └── people/
├── journal/ # history of completed tasks
├── playbooks/ # repeatable scenarios
├── .vault/ # credentials and secrets, kept out of git
├── .claude/
│ └── skills/
│ └── ops-log/ # the task closing protocol
├── scripts/ # reusable automation
├── data/ # exports and generated results
├── templates/ # project and card templates
└── vault/ # my personal Obsidian, mounted inprojects/ is for active work. Once a result no longer fits into a single journal entry, it gets a folder with a brief, a spec, scripts, and instructions for running it. That may be a product, an analytics system, a process automation, or the agent’s own configuration.
infra/ answers my favourite set of questions: where do I connect, what is running there, and what has happened to it. A server card records its role, services, deployment, dependencies, diagnostic quirks, and change history. External services get their own cards. infra/people/ gradually accumulates a map of ownership: who owns a system, who to ask for a decision, and who to call during an incident.
journal/ is a short operational history. One file per month, newest entries on top. No musings about the state of the industry: where the work happened, what broke or needed doing, what was verified, and how it ended.
Repeatable operations go into playbooks/. That is where the field-tested scenarios live: how to find what filled up a disk, how to check a proxy chain, how to grant access, how to change a DNS record. A decent playbook contains commands, branches, and success criteria. “Check the logs and fix the problem” is not worth writing down.
Secrets live separately, in .vault/. Scripts, exports, and templates each get their own directory. On top of it all sits CLAUDE.md, the workspace constitution. The structure tells the agent where to look. CLAUDE.md tells it what it is allowed to do and what it must do before finishing a task.
The one condition
The workspace only becomes useful once you make it your primary working interface. Opening it occasionally, for tasks that happen to be convenient to hand to an agent, is not enough. Incidents, access requests, tickets, and ordinary operational work all have to go through it.
Otherwise the context stays scattered across a terminal, an issue tracker, chats, and one-off sessions. The agent sees only part of the work, and the workspace never accumulates enough to help with the next task.
What I actually do through it
I have gradually handed a significant part of my operational management work to the agent. It gathers incident data, grants access, checks stalled tasks and under-logged time, and drafts ticket replies. The management decisions stay with me; the agent takes on the lookups, the cross-checks, and the technical actions.
A separate large block is running the whole corporate infrastructure fleet. Before working, the agent reads the server and service cards, checks dependencies and change history. During an incident it runs the diagnosis, prepares a plan, and — after I confirm — applies the changes. Then it verifies the result and updates the documents. The next similar case starts from an accurate picture of the system, not from hunting for credentials and old chat threads.
One-off management tasks slowly grow into automations. Once I was working out why an employee had logged part of a day as idle time. It turned out their tasks were waiting on decisions from other people. Now a dedicated process finds tasks like that, groups them by owner, and flags the idle-time risk in advance.
After every task, the workspace is left with a journal entry, a new fact in a card, or a ready-made scenario to reuse.
How the agent learns on the job
“Let the agent remember things” changes nothing. What is needed is a mandatory protocol: what to save, where to put it, and when to check it.
For me, the ops-log skill handles that. It runs after every completed task, even when I have not separately asked to record anything.
By a completed task I mean work with a verifiable result: system state changed, a diagnosis finished, or knowledge appeared that the next session will need. An answer to a question or a small wording fix does not go into the journal on its own.
After a task like that, the journal is always updated. If the work touched a server, a service, or a person, the agent edits the cards. New access parameters go into .vault/. A recurring case gets proposed as a playbook. At the end it checks the lessons: where the old documents diverged from reality, and which corrections it received from me.
The core rule is short: the document lied — fix it now.
Say a card lists an old SSH user. The agent gets rejected, finds the current one, and connects successfully. If the card stays as it was after that, the task is only half closed. The next session starts from the wrong login again.
Port, command, path, API, service, or order of operations — it makes no difference. Found a discrepancy? Fix it in the same task.
Not every correction of mine is immediately turned into a general rule. First the agent records what exactly I asked to change, why, and in which tasks it applies. For example: do not open a task statement with a greeting; check permissions before changing them; treat a particular source as read-only.
A correction reaches CLAUDE.md only after it has recurred independently three times. Otherwise the file quickly fills up with stray wishes that were voiced once, in the wrong mood.
There is an automatic cross-check as well. Once a week, infra-verify validates the server cards against reachability, disks, services, containers, timers, and other measurable parameters. The discrepancies land in a drift report, which the agent reads before an infrastructure task.
The loop looks like this:
task
→ use the accumulated knowledge
→ check that knowledge against reality
→ do the work
→ journal, cards, and playbooks
→ fix the discrepancies
→ next taskIn an ordinary knowledge base, stale facts can sit there for years. Here they surface during the work and get fixed on the spot.
Assembling the loop
Three things are needed: a task closing skill, a mandatory rule in CLAUDE.md, and clear document formats.
A trimmed version of .claude/skills/ops-log/SKILL.md looks like this:
---
name: ops-log
description: Task closing protocol. Invoke automatically at the end of EVERY completed task, not only on the explicit words "log this" or "write it to the journal".
---
# Task closing protocol
Move the confirmed knowledge from the current session into the workspace.
Do not invent anything.
1. Journal — always:
- add an entry to `journal/YYYY-MM.md`;
- give the date, the place, the symptom or task, the actions, and the result.
2. Cards:
- update the cards of the servers, services, and people that were touched;
- fix outdated facts;
- add a link to the journal entry.
3. Vault:
- record new hosts, users, and ports in `.vault/inventory.yaml`;
- for keys, passwords, and tokens leave a reference to the secret manager;
- keep only `vault:` references in committed files.
4. Playbook:
- write up a recurring case as
`symptom → diagnosis → cause → fix → precedent`.
5. Lessons:
- if a card or playbook lied, verify that it has already been fixed;
- save the user's correction together with its reason and scope;
- after the third independent repetition, propose promoting it
into `CLAUDE.md` or a skill.For Claude Code, the most important line here is description: it is what helps the agent work out when to load the skill. That is why “run after every task” sits right there, rather than buried in the middle of a long file. Other agents may use a different mechanism.
I duplicate the same requirement in CLAUDE.md:
## Task closing protocol
A task is not complete until the `ops-log` skill has run.
Invoke it automatically at the end of every completed task.
- the journal is updated after a task with a verifiable result;
- cards, vault, and playbooks — if they were touched;
- if a document lied, fix it the moment you find it;
- save the user's correction with the "why" and the "when it applies";
- a third independent repetition of a correction is a candidate for a rule
in `CLAUDE.md` or a skill.The repetition is deliberate. The description helps the agent pick the skill; the constitution refuses to let a task close without it.
The journal format is as short as it gets:
## YYYY-MM-DD — short task title
- **Where:** links to the cards that were touched
- **What:** symptom or task → actions taken → verified result
- **Playbook:** a link, or "—"A playbook is more detailed, because its job is to walk the next person down an already proven path:
# Scenario name
## Symptom
What the human or the system observes.
## Diagnosis
```bash
# Concrete commands and checks
```
How to read the results and where to go next.
## Cause
The confirmed cause of the problem.
## Fix
The sequence of actions and how to verify the result.
## Precedents
- YYYY-MM-DD — short outcome and a link to the journal.That is enough to get started. There is no need to spend a week designing the perfect ontology only to heroically never use it. Below is a ready-made instruction you can hand to a file-system agent as is.
When a task becomes a project
Operational work is usually closed out by a journal entry and a playbook. Once a task acquires its own brief, an implementation, and several runs, I turn it into a project.
The base skeleton is small:
projects/<slug>/
├── README.md # what it is, what is inside, how to run it
├── brief.md # task, goals, context, deadline
├── spec.md # implementation spec
└── scripts/ # the project's scriptsbrief.md holds the original task. spec.md records the decision that was made. README.md shows the current state and how to run it, rather than retelling the whole history of its creation.
From there the project grows only as needed. The team process automation, for instance, is laid out like this:
projects/team-leads/
├── README.md
├── brief.md
├── spec.md
├── roadmap.md
├── processes/
│ ├── underlog-day/
│ ├── manager-blocked/
│ └── reminders/
├── runtime/
│ ├── run.py
│ ├── registry.yaml
│ └── api_clients/
├── deploy/
│ └── scheduler.plist
└── tests/processes/ holds the individual checks and actions. runtime/ runs them and holds the shared registry with the API clients. deploy/ owns the schedule. The tests pin down the rules already discovered, so the next edit does not break them.
Some projects are about the workspace itself: configuring the agent, reconciling infrastructure cards, closing tasks, and guarding against dangerous commands. Which makes for a funny result: the system builds itself the same way it builds everything else.
Secrets stay separate
The rule is simple: knowledge gets committed, credentials do not.
A server card can describe its purpose, services, deployment, dependencies, diagnostic commands, and incident history. Hosts, users, passwords, private keys, and tokens do not go in there.
What stays instead is a stable reference:
vault: servers.billing_prodThe values themselves live in .vault/inventory.yaml, which is excluded from git.
The card answers what is on the server and how to operate it. .vault/ is what gets you in. Thanks to the split, the instructions can be committed safely, and a rotation changes access in one place.
This is protection against an accidental commit, not a real secret store. Long-lived passwords, tokens, and keys are better kept in a password manager, the system keychain, or a secret manager, with .vault/ holding references and local connection parameters. A .gitignore file by itself neither encrypts anything nor protects against other processes on the machine.
Neighbouring repositories
The workspace can see other repositories, but the right to read is not the right to write.
My corporate repository is mounted through a symlink that is excluded from git. By default the agent uses it as a source of context. If a task requires changes, it moves from the same window into the mounted repository, reads that repository’s rules, and works within its boundaries. The entry point stays single — the workspace.
This is not bureaucracy. The two repositories have different owners, conventions, secrets, and boundaries of responsibility. Mixing them is convenient right up until the first unpleasant commit.
My personal Obsidian is mounted the same way, through vault/. The agent may read plans and notes as context, but must not mix them with project files and credentials.
For every mounted source, the mode is written down explicitly in CLAUDE.md: read-only, writing allowed, or work in a separate session only.
Where the rules came from
I did not come up with my CLAUDE.md in one evening. I went through 842 transcripts of my own sessions: 2,278 turns and 192 user corrections. I counted something as a correction when I explicitly changed the way the agent proposed to work, rather than merely clarifying the task. Only a correction that recurred independently three times made it into a global rule.
I tune the agent from accumulated data, not from impressions. A constitution should describe real mistakes and verified solutions. Wishes written in advance usually look excellent and rarely help.
Every new task uses what has accumulated, checks it, and leaves the workspace a little more accurate.
Instructions for your agent
Below is the full working prompt. It targets Claude Code first of all. Another file-system agent can be given the same structure, but the name of the rules file, the skills directory, and the mechanism for invoking them automatically will need adapting.
Copy the whole block and run the agent in an empty folder. It will lay out the base workspace, verify the structure, and create the first commit.
Prompt for the agent
You are in an empty folder. Set up a basic working workspace in it for a human and an AI agent to work together.
Do not stop at describing it: create every listed directory and file, verify the result, initialize a git repository, and make the first commit.
Do not write real secrets into the files you create. Use placeholders and documented test IP addresses only.
Copy every block of file content verbatim. Do not shorten it, do not paraphrase it, do not join lines, and do not change the formatting. After creating a file, read it back and compare it line by line with the corresponding block in these instructions. If you find a discrepancy, fix the file before verification and commit.
## 1. Create the structure
```text
.
├── CLAUDE.md
├── .gitignore
├── .claude/
│ └── skills/
│ └── ops-log/
│ └── SKILL.md
├── .vault/
│ ├── .gitkeep
│ └── inventory.yaml
├── projects/
├── infra/
│ ├── README.md
│ ├── servers/
│ ├── services/
│ └── people/
├── journal/
│ ├── README.md
│ └── YYYY-MM.md
├── playbooks/
│ └── README.md
├── scripts/
├── data/
│ └── .gitkeep
└── templates/
├── project-readme.md
├── project-brief.md
├── project-spec.md
└── server-card.md
```
Instead of `YYYY-MM.md`, use the current year and month from the system date.
Keep the empty directories `projects/`, `scripts/`, `infra/servers/`, `infra/services/`, `infra/people/`, `.vault/`, and `data/` in git using `.gitkeep` files. The contents of `.vault/` and `data/`, apart from those two `.gitkeep` files, must stay local.
## 2. Create .gitignore
Write this into `.gitignore`:
```gitignore
# Secrets and local credentials
.vault/*
!.vault/.gitkeep
# Exports, reports, and generated data
data/*
!data/.gitkeep
# Local environment
.env
.env.*
!.env.example
# System files
.DS_Store
```
Verify that `.vault/inventory.yaml` is actually ignored by git. The file must exist locally but must not land in the first commit.
## 3. Create CLAUDE.md
Write the following content:
```markdown
# Working workspace
## Purpose
This is the single entry point for a human and an AI agent working together.
Try to solve every task through this workspace first, even one that looks
like a one-off.
The workspace holds active projects, an infrastructure map, a task history,
repeatable scenarios, and verified rules. Use the existing knowledge, check it
against reality, and fix it whenever you find a discrepancy.
## Structure
- `projects/` — active work; one project lives in `projects/<slug>/`.
- `infra/servers/` — server cards: role, services, operations, and history.
- `infra/services/` — cards for external services and platforms.
- `infra/people/` — ownership map and working contacts.
- `journal/` — history of completed tasks, one file per month.
- `playbooks/` — repeatable diagnostic and routine procedures.
- `.vault/` — local access parameters; contents stay out of git,
except `.gitkeep`.
- `scripts/` — reusable automation.
- `data/` — exports and generated results; contents stay out of git,
except `.gitkeep`.
- `templates/` — project and card templates.
## Conventions
- Create every project in `projects/<slug>/`.
- Put general-purpose scripts in `scripts/`.
- Put exports and temporary reports in `data/`.
- Do not invent facts, credentials, command output, or system state.
- Before changing an existing object, read its documentation and history.
- After a change, verify the result in a way independent of the write command.
## Secrets
Keep hosts, real IP addresses, users, and other local connection parameters
only in `.vault/inventory.yaml`. Keep passwords, private keys, tokens, and API
keys in a password manager, the system keychain, or a secret manager. Store
only a reference to the secret in `.vault/inventory.yaml`.
In committed files, leave a stable reference:
`vault: servers.<name>`
or:
`vault: services.<name>`
The card describes what is in the system and how to work with it. The vault
describes how to get access.
Never add the contents of `.vault/` to git, except the empty
`.vault/.gitkeep`. Check staged files for secrets before committing.
## Task closing protocol
A task is not complete until the `ops-log` skill has run.
Invoke it automatically at the end of every completed task, not only after
the words "log this" or "write it to the journal".
- the journal is updated after any task with a verifiable result;
- `infra/` cards, the vault, and playbooks are updated if they were touched;
- if a card or playbook lied, fix it the moment you discover it;
- save the user's correction together with an explanation of why it is needed
and when it applies;
- if the same correction comes up independently for the third time, propose
promoting it into this rule or into a separate skill;
- do not commit changes without an explicit request from the user, except the
initial commit while setting up this workspace.
A purely conversational answer, where nothing was diagnosed, created, or
changed, needs no journal entry.
Do not journal the initial setup of an empty workspace: that is installing the
working environment, not a completed work task.
```
## 4. Create .claude/skills/ops-log/SKILL.md
Write:
```markdown
---
name: ops-log
description: Task closing protocol — record the result in journal/, infra/, playbooks/, and .vault, plus the "lessons" step. Invoke automatically at the end of EVERY completed task, not only on an explicit "log this", "write it to the journal", "add it to the knowledge base", or "turn it into a playbook".
---
# ops-log — task closing protocol
Move the confirmed knowledge from the current session into the workspace:
what was done, where, and how the task ended.
Do not invent anything. If a fact, command, or result did not appear in the
session, do not add it to the documents.
This is the mandatory finish of every completed task. A purely conversational
session, where nothing changed and nothing was diagnosed, needs no record.
## 1. Journal
Add an entry to `journal/YYYY-MM.md` in the format from `journal/README.md`.
- If this month's file does not exist, create it.
- Put the new entry on top, right after the month heading.
- Give the date and a short title.
- In "Where", link the cards or the project that were touched.
- In "What", fit the symptom or task, the actions taken, and the verified
result into 2–5 lines.
- In "Playbook", give a link or put `—`.
The journal is updated after a task with a verifiable result: system state
changed, a diagnosis was completed, or knowledge appeared that the next session
will need. An answer to a question or a small wording fix needs no entry.
## 2. Cards
For every server, external service, or person that was touched:
- if the card exists, add an entry to its "History" section and fix outdated
facts in the other sections;
- if there is no card, create one in `infra/servers/`, `infra/services/`,
or `infra/people/`;
- add the new card to the matching table in `infra/README.md`;
- link the history entry to the fresh journal entry.
A minimal server card must contain the role, the `vault:` reference, the set of
services, how it is operated, the checks, and the history.
## 3. Vault
If new access parameters appeared — host, real IP, user, port, or control
panel — add them to `.vault/inventory.yaml`. For a password, key, or token,
store only a reference to the secret manager.
In committed files, use only a reference of the form:
`vault: servers.<name>`
or:
`vault: services.<name>`
Never print secrets into the journal, cards, playbooks, completion messages,
or git history.
## 4. Playbook
If the case can recur — a diagnosis, a routine operation, or an error that has
already happened — propose creating or updating a playbook.
Once the user agrees, create the file in a suitable subdirectory of
`playbooks/` with this structure:
1. symptom;
2. diagnosis with concrete commands;
3. how to read the results, and the branches;
4. confirmed cause;
5. fix;
6. verification of the result;
7. precedent with a date and a link to the journal.
Add a link to the playbook in `playbooks/README.md`, in the journal, and in
the object's card.
For a genuinely one-off case, the journal is enough.
## 5. Lessons
Check both self-improvement loops.
### The knowledge lied
If a card or playbook turned out to be wrong — an outdated command, a changed
port, a moved path, a service that no longer exists — the document must be
fixed the moment you discover it.
Before finishing, make sure the fix has been applied. Do not leave a known
error for the next session.
### The user's correction
If the user corrected the way you work:
- record the correction itself;
- write down why it is needed;
- state the situations where it applies;
- pick the right destination: a card, a playbook, a project README, or a local
rule.
If the same correction comes up independently for the third time, propose
promoting it into `CLAUDE.md` or a separate skill. Do not turn a one-time
preference into a global rule.
## 6. Report
Show the user the list of changed files and explain each edit in one line.
Do not commit without an explicit request from the user. The only exception is
the first commit explicitly required by the workspace setup instructions.
```
## 5. Create journal/README.md
Write:
```markdown
# Task journal
The journal is a short history of completed work: what was done, where, and
how the task ended.
Each month uses a `YYYY-MM.md` file. New entries are added on top by the
`ops-log` skill.
## Entry format
## YYYY-MM-DD — short task title
- **Where:** links to the cards, projects, or services that were touched
- **What:** 2–5 lines: symptom or task → actions → verified result
- **Playbook:** link to a repeatable scenario, or "—"
Do not put passwords, tokens, private keys, real private addresses, or other
secrets into the journal. For credentials, use `vault:` references only.
```
Create the current month's file `journal/YYYY-MM.md`:
```markdown
# Journal — YYYY-MM
```
Substitute the actual current year and month. Do not add invented tasks.
## 6. Create playbooks/README.md
Write:
```markdown
# Playbooks
Playbooks are repeatable diagnostic and routine procedures.
Create a playbook if the case can recur, or if the error has happened before.
Record one-off work in the journal only.
## Playbook structure
# Scenario name
## Symptom
What the human or the system observes. State the verifiable signs.
## Before you start
Which permissions are needed, which `vault:` references, and the safety
conditions.
## Diagnosis
Concrete commands in execution order. For each check, explain:
- which result counts as normal;
- what a deviation means;
- which step to go to next.
## Cause
The confirmed cause. Do not list unconfirmed guesses as fact.
## Fix
Step-by-step change with commands, the limits of authority, and how to roll
back.
## Verification
How to confirm independently that the problem is gone and there are no side
effects.
## Precedents
- YYYY-MM-DD — short outcome and a link to the journal entry.
## Index
### Diagnosis
Empty for now.
### Routine work
Empty for now.
```
## 7. Create infra/README.md
Write:
```markdown
# Infrastructure
`infra/` is the map of servers, external services, and ownership: where the
agent goes, what is there, how to work with it, and what happened before.
Secrets live only in `.vault/inventory.yaml`. Cards reference them with the
key `vault: <section>.<name>`.
## Layers
- `infra/servers/` — machines and environments: role, services, deployment,
dependencies, checks, and history.
- `infra/services/` — clouds, DNS, control panels, SaaS, and other external
services.
- `infra/people/` — areas of ownership and working points of contact.
- `journal/` — task history.
- `playbooks/` — repeatable scenarios.
## Servers
| Card | Purpose | Vault |
|---|---|---|
## External services
| Card | Purpose | Vault |
|---|---|---|
## People and ownership
| Card | Area of ownership | Contact |
|---|---|---|
```
## 8. Create the server card template
Write this into `templates/server-card.md`:
```markdown
# {{Server name}}
- **Role:** {{what the machine is for}}
- **Environment:** {{production, staging, development, or other}}
- **Access:** `vault: servers.{{key}}`
- **Owner:** {{link to a card in infra/people, or "not assigned"}}
## What runs here
| Component | Purpose | How it runs |
|---|---|---|
| {{service}} | {{role}} | {{systemd, Docker, Kubernetes, manual}} |
## Operations
- **Deployment:** {{verified sequence or a link to a playbook}}
- **Logs:** {{paths or commands, without secrets}}
- **Configuration:** {{paths or configuration source}}
- **Dependencies:** {{other servers and external services}}
## Checks
Safe status-check commands. Describe the expected result of each one.
## Quirks and limits
- {{what is easy to get wrong}}
- {{what needs separate approval}}
- {{which actions are dangerous or irreversible}}
## Related playbooks
- None yet.
## History
- YYYY-MM-DD — card created.
```
When creating a real card, do not leave an invented history line: put the
actual date and the reason the card appeared.
## 9. Create .vault/inventory.yaml
The file must exist locally but stay excluded from git.
Write only a stub with comments and test values into it:
```yaml
# This file holds local connection parameters and references to secrets.
# It is excluded from git. Do not copy its values into committed documents.
# Keep passwords, private keys, and tokens in a secret manager, not here.
#
# In cards, use references:
# vault: servers.billing_prod
# vault: services.cloud_provider
servers:
billing_prod:
host: 203.0.113.10
user: deploy
credentials_ref: "password-manager://infrastructure/billing-prod"
panel: https://panel.example.com
notes: "example: access through a bastion, non-standard port"
ci_runner:
host: 203.0.113.20
auth: ssh-key
credentials_ref: "system-keychain://ssh/ci-runner"
services:
cloud_provider:
account: team@example.com
credentials_ref: "secret-manager://cloud/provider-api"
sheets:
planning_2026: https://docs.google.com/spreadsheets/d/EXAMPLE
own_ips:
vpn_exit: 198.51.100.5 # example: your own IP, for cross-checks during audits
```
Do not replace the test values with real connection parameters during the
initial setup.
## 10. Create the project templates
Write this into `templates/project-readme.md`:
```markdown
# {{Project name}}
{{One or two sentences: what this project is and why it exists}}
- `brief.md` — the original task, goals, and context.
- `spec.md` — the implementation spec.
- `scripts/` — the project's working scripts.
- export results go to `data/` in the workspace root.
## Contents
{{As they appear, list the additional directories and what they are for}}
## Running it
{{Requirements and verified commands}}
## Verification
{{How to make sure the result is correct}}
## Secrets
Credentials live in `.vault/inventory.yaml`. Only references of the form
`vault: services.<name>` are used here.
```
Write this into `templates/project-brief.md`:
```markdown
# {{Project name}}
## Task
{{What needs to be done and why}}
## Goals
- [ ] {{Measurable goal 1}}
- [ ] {{Measurable goal 2}}
## Context
- **Deadline:** {{date or "not set"}}
- **Stakeholders:** {{who cares about this}}
- **Constraints:** {{what matters}}
- **Dependencies:** {{systems, people, and decisions}}
## Result
{{What verifiable success looks like}}
## Out of scope
- {{An explicit boundary of the project}}
```
Write this into `templates/project-spec.md`:
```markdown
# Spec: {{Project name}}
## Overview
{{What exactly is being built}}
## Requirements
- {{Requirement 1}}
- {{Requirement 2}}
## Input
{{Sources, formats, and constraints}}
## Implementation
{{Architecture, algorithms, data structures, and key decisions}}
## Output
{{Result format and where it is saved}}
## Errors and edge cases
- {{Scenario and expected behaviour}}
## Verification
- [ ] {{Result check}}
- [ ] {{Check for absence of side effects}}
## Rollback
{{How to undo the change safely, where applicable}}
```
## 11. Verify the structure and safety
Before committing:
1. Print the tree of created files.
2. Verify that the current month's journal file exists.
3. Verify that `.vault/inventory.yaml` exists.
4. Create a temporary `data/ignore-probe` file, verify with `git check-ignore -v` that both it and `.vault/inventory.yaml` are ignored, then delete the probe.
5. Make sure `.vault/inventory.yaml` is not among the staged files.
6. Verify that no Markdown file is empty.
7. Review `git diff --cached --name-only` and `git diff --cached`. Look for passwords, tokens, private keys, real private addresses, and environment files. If gitleaks is installed, additionally scan the staged changes with findings redacted. Do not print possible secrets in your final answer.
8. Do not add local system files to the repository.
9. Make sure the created files match the blocks in these instructions and were not shortened or paraphrased.
If you find a problem, fix it before the commit.
## 12. Initialize git and make the first commit
Run:
```bash
git init
git add .
git status --short
git diff --cached --check
git config --get user.name
git config --get user.email >/dev/null
git commit -m "Initialize AI workspace"
```
If the commit is impossible only because `user.name` or `user.email` is missing, do not invent a human identity and do not change the global configuration. Ask the user for the values, set them locally for this repository, and then finish the first commit.
If the name and email are already configured, show the author name before committing and confirm that the email is set, without printing the address itself. Do not change an existing identity without being asked.
After the commit, check again:
```bash
git status --short
git ls-files
```
The working tree must be clean. `.vault/inventory.yaml` and the local contents of `data/` must not appear in `git ls-files`. The `.vault/.gitkeep` and `data/.gitkeep` files, on the contrary, must be there: they are what restores both directories after `git clone`.
## 13. Show the human a checklist
After a successful setup, print a short summary: which directories were created, which journal file is open for the current month, and the hash of the first commit.
Then show this checklist:
### Your first week with the workspace
1. Solve every work task through it, even one that looks like a one-off.
2. At the end of a task, check that the agent ran `ops-log`. If it forgot, tell it to run the closing protocol.
3. If a card or playbook lied, fix the document right away, in the same task.
4. Put local connection parameters in `.vault/inventory.yaml`, and passwords, keys, and tokens in a secret manager. Leave only `vault:` references in every other file.
5. Do not create playbooks for the sake of count. Create one when the scenario really can be repeated.
6. At the end of the week, read through the journal: pick the first recurring task to turn into an automation or a new playbook.