Using Workspaces

What the Workspace Is

The workspace folder is the project's memory system, with information, that can be accessed on demand. It has three purposes:

1. Project definition

A human-readable record of what the project is, what exists, and where it is going. The source of truth about scope and goals.

2. Agent memory

The context, rules, and conventions that agents read before doing any work. An agent that reads the workspace can usually start because the bigger context should be clear.

3. Usage documentation

The outline, boards, guides and actions explaini how to work with this project and its tools.

The workspace describes the features and their reason and understanding. Code shows what was built. The workspace explains what it is, why it exists, and how to work with it.

What Goes Where

index.page

Entry point for agents and humans: Project name, a two-sentence description, links to everything else.

outline

Big picture. Scope, goals, what exists now, key technical decisions, what is next.

boards

Active work. Organized in kan-ban boards: To-Dos, backlog, bugs.

guides

Rules. Agents must follow guides, they define the workflow, conventions and expectations.

actions

Named repeatable procedures. Detailed step-by-step processes for reoccuring agent tasks.

history

Session log. What happened each session, what was decided, and why. Usually at the end of every working session.

reference

Code doc. For complicated or/and often used code.

The Memory Rule

Anything a future agent needs to understand or know about the project belongs in the workspace.

Decisions and their reasons belong in the history. Rules and constraints belong in the guides. Current tasks belong in the boards. The big picture belongs in outline. For complex or unusual code Implementations, details can be in the reference.

Agents should after a task think about, whether there was unusal information coming up, which would be helpfull for a next session.

Keeping It Current

The workspace is most useful when it is up to date. An outdated outline misleads agents. An empty task board means lost context. A history with no recent entries means nobody knows where things were left.

Besides, actions, which users can execute to keep organized, agents should actively help keeping things update to date. That usually means to create proposals what should be udpated.