Workspace State Schema

Markdown explains the work. Structured state runs active execution.

Use this schema only for active workspaces that need agent coordination, task tracking, QA, or recurring operations. Do not create it for passive ideas.

When To Create .company/

Create .company/ when at least one of these is true:

• Multiple execution roles are working on the same project.
• Dev, QA, research, writing, or design tasks need handoffs.
• Athena needs an auditable status ledger.
• There are recurring runs, bugs, quality gates, or scheduled deliverables.
• The project would lose momentum without structured state.

Do not create .company/ just because a workspace exists.

Folder Layout

Projects/{Workspace}/
  index.md
  decisions/
  logs/
  wiki/
  artifacts/
  raw/
  .company/
    manifest.json
    tasks.json
    bugs.json
    status.json
    agents.json
    context-cache/
    message-bus/
    artifacts/

State Files

File	Purpose	Owner
manifest.json	Project constitution: objective, scope, non-goals, milestones, risks	PM + Architect, approved by Athena
tasks.json	Work board with owners, dependencies, acceptance criteria, and status	PM
bugs.json	QA-discovered defects with evidence and verification status	QA
status.json	Current health, progress summary, blockers, next actions	Athena
agents.json	Recruited execution roles, assigned model/tooling, current status	Athena
context-cache/	Short handoff summaries, not raw dumps	All execution roles
message-bus/	Structured role-to-role messages when needed	Athena + roles

Required Status Values

Task status:

pending -> assigned -> in_progress -> review -> done
blocked

Bug status:

open -> triaged -> in_progress -> fixed -> verified
wont_fix
duplicate

Workspace health:

green
yellow
red
paused
dormant

Minimal manifest.json

{
  "project": "Project name",
  "objective": "What this workspace exists to produce",
  "non_goals": [],
  "milestones": [],
  "risks": [],
  "created": "YYYY-MM-DD",
  "updated": "YYYY-MM-DD"
}

Minimal tasks.json

{
  "tasks": [
    {
      "id": "task-001",
      "title": "Task title",
      "role": "researcher",
      "status": "pending",
      "priority": "high",
      "depends_on": [],
      "acceptance_criteria": []
    }
  ]
}

Minimal status.json

{
  "health": "green",
  "phase": "planning",
  "summary": "Short current state",
  "blocked": [],
  "next_actions": [],
  "updated": "YYYY-MM-DD"
}

Context Cache Rule

Agents do not hand off raw session history.

Every handoff should fit in a concise file:

.company/context-cache/task-001-dev-result.md
.company/context-cache/task-001-qa-report.md
.company/context-cache/research-brief-market.md

Each handoff should include:

• Task or decision.
• Files touched or sources used.
• What changed.
• Evidence.
• Open risks.
• Next recommended action.

Message Bus Rule

Use message-bus/ only when role-to-role coordination needs traceability. Otherwise, status and task files are enough.

Message types:

• task_assignment
• result
• bug_report
• review_feedback
• blocker
• status_update
• decision_request

Guardrail

If .company/ becomes heavier than the work, pause and simplify. The state system exists to reduce coordination cost, not create another job.