Client Workspace Structure — Standard

Client Workspace Structure — Standard

Reference: CI-032 · Applied at Stage 6.0 (Packaging Manifest)

Rule

A client workspace must expose exactly three categories at the root:

Visible to client Purpose
CLAUDE.md Agent identity and rules (required by Claude Code)
README.md Quick-start and demandes index
{demandes}/ Active work folders (DAE-NNNN, tickets, projects, etc.)
docs/ User guides and skill reference

Everything else goes into _system/.

Convention: _system/

All internal infrastructure that the client does not need to see or touch:

_system/
├── memory/          ← Agent memory (AI-managed)
├── workflows/       ← Internal workflow definitions
├── templates/       ← Internal templates
├── tools/           ← Scripts and utilities
├── prompts/         ← System prompts
├── content-in/      ← Reference materials (if internal)
├── content-out/     ← Staging area (if internal)
└── *.md / *.ps1     ← Design docs, changelogs, build scripts

Why _system/ and not .system/: Dotfiles are hidden in Unix but not in Windows Explorer / OneDrive. The underscore prefix is visible on all platforms while signaling "internal" by convention.

Canonical Structure

{client-workspace}/
├── CLAUDE.md                      ← Always at root (Claude Code requirement)
├── README.md                      ← Short, client-facing
├── .claude/
│   ├── commands/                  ← Skills (visible to Claude Code)
│   └── settings.json              ← Permissions config
├── {demandes}/                    ← e.g. demandes-ae/, tickets/, projects/
│   └── {ID}-{slug}/
│       ├── notes/                 ← Raw notes and input
│       ├── intrants/              ← Collected reference documents
│       ├── out/                   ← Deliverables
│       └── decisions/             ← Architecture decisions
├── docs/                          ← User guide, quick-start, skill reference
└── _system/                       ← Internal — client does not touch
    ├── memory/
    ├── workflows/
    └── [all other internal folders and files]

Checklist (add to Stage 6.0 manifest)

  • Root contains only: CLAUDE.md, README.md, .claude/, {demandes}/, docs/, _system/
  • No design docs at root (ARCHITECTURE-*.md, TODO.md, CHANGELOG.md, etc.)
  • No scripts at root (.ps1, .sh, install-.)
  • No AI-internal files at root (MEMORY-*.md, WORKSPACE_RULES.md)
  • No unrelated files (verify every root item has a purpose)
  • _system/ exists and contains all internal infrastructure
  • docs/ contains at minimum: quick-start and skill reference

Exceptions

Exception Allowed? Notes
.gitignore at root Yes Git convention
.mcp.json at root Yes MCP server config (remove if unused)
agent-ea.code-workspace No → _system/ Dev tooling, not client-facing
feedback/ at root Yes For repo-based products with client feedback loop
index.html at root Yes Single-page-app talents (dashboard entry-point). See Agent-House precedent (WO-0009).

Requests pattern (mandatory)

Every talent — even single-client/single-project — exposes a {client}/requests/{PREFIX}-NNNN/ folder. The rule: an agent always accumulates multiple requests over time (a question, a mini-project, an épopée). Hiding them under generic out/ or pages/ loses traceability.

Canonical:

clients/{client-slug}/
├── shared/                    ← project-wide reference materials
├── decisions/                 ← project-level decisions
├── notes/                     ← brainstorms
└── requests/
    └── {PREFIX}-NNNN/         ← one folder per request
        ├── request.md         ← frontmatter (id, title, status, created, category) + objectif
        ├── input/             ← request-specific intrants
        ├── process/           ← intermediate analyses (optional)
        └── output/            ← livrables

{PREFIX} follows TFD-0026 (per-type 2-3 letter code, mandatory short slug ≤25 chars kebab-case). Examples:

  • DAE-0007-transgesco (client EA deliverable)
  • DH-0001-desjardins-financement (Agent-House house request)
  • New talents define their own prefix on first use.