[{"data":1,"prerenderedAt":42},["ShallowReactive",2],{"doc:en:docs-space":3},{"title":4,"lede":5,"html":6,"headings":7},"The Docs space","The Docs tab holds the product’s specification, by subject, with what sets it apart from the code; its decisions and its documents. Everything lives in the repository, and you share it with the team in one click.","\u003Ch2 id=\"the-tab\">The tab\u003C\u002Fh2>\n\u003Cp>The sidebar has three tabs: “Agents”, “Kanban” and “Docs”. Under “Docs”, “New discussion”, \u003Ca href=\"#the-discussions\">the discussions\u003C\u002Fa>, then three spaces:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Specification\u003C\u002Fstrong>: the pages of the spec, with the number of gaps with the code.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Decisions\u003C\u002Fstrong>: the register of the decisions on the product, numbered and dated.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Documents\u003C\u002Fstrong>: the files dropped for the project (requirements, minutes, mockups).\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Everything is written under \u003Ccode class=\"key\">.escouade\u002F\u003C\u002Fcode> of the \u003Ca href=\"#the-docs-branch\">docs branch\u003C\u002Fa>: \u003Ccode>.escouade\u002Fspec\u002F<subject>\u002F<page>.md\u003C\u002Fcode>, \u003Ccode class=\"key\">.escouade\u002Fdecisions\u002F\u003C\u002Fcode>, \u003Ccode class=\"key\">.escouade\u002Fdocuments\u002F\u003C\u002Fcode>. They are Markdown files you can also read and edit by hand.\u003C\u002Fp>\n\u003Ch2 id=\"the-specification\">The specification\u003C\u002Fh2>\n\u003Cp>The space opens on \u003Cstrong>the map of the subjects\u003C\u002Fstrong>: a card per subject, with where it stands against the code.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>“Up to date”: the last comparison with the code found nothing.\u003C\u002Fli>\n\u003Cli>“1 gap”: a page of the subject says something else than the code.\u003C\u002Fli>\n\u003Cli>“Draft”: all its pages are still drafts.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Each card also says how many pages, tickets and decisions the subject has. The last card, “What changed”, gives the last shared changes of the spec, and the pages changed here, not shared yet. At the head of the space: the pages up to date, the gaps, the drafts, and when the spec was last compared to the code.\u003C\u002Fp>\n\u003Cp>On the left, \u003Cstrong>the tree of the pages\u003C\u002Fstrong>, by subject as in a wiki: a click on a subject collapses or expands it, a click on a page opens it. A page marked “gap” says something else than the code; “to share”, it was changed here and not shared yet.\u003C\u002Fp>\n\u003Cp>“New page” creates a page: a subject (“Payment”) and a title (“In instalments”). It opens ready to be written.\u003C\u002Fp>\n\u003Ch2 id=\"a-page\">A page\u003C\u002Fh2>\n\u003Cp>A page shows its Markdown text formatted and, beside it, its sources (the documents, files or links it comes from), its tickets and decisions, and when it was last compared to the code.\u003C\u002Fp>\n\u003Cp>When the comparison found \u003Cstrong>gaps with the code\u003C\u002Fstrong>, they are at the top of the page, each with what differs and the files concerned:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>“Update the spec” opens a \u003Ca href=\"#the-discussions\">discussion\u003C\u002Fa> with the spec writer, told the gap: it reads the code and proposes the page that says what the code does; poured into the spec, the gap goes.\u003C\u002Fli>\n\u003Cli>“Open a ticket for the code” opens the window of a new ticket, its title and description already written from the gap: the code is what must follow the spec.\u003C\u002Fli>\n\u003Cli>“See the code” opens the file the gap names in the \u003Ca href=\"\u002Fen\u002Fdocs\u002Feditor\u002F\">editor\u003C\u002Fa>.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>“Edit” opens the page in a simple editor: its title and its text. “Save” writes the file, its header (sources, tickets, decisions, gaps) kept as it is. With the current branch, “Open in the editor” opens the page’s file in Escouade’s editor.\u003C\u002Fp>\n\u003Ch2 id=\"the-discussions\">The discussions\u003C\u002Fh2>\n\u003Cp>“New discussion”, at the top of the tab (Ctrl+B), lets you talk about the spec with an agent. You choose one of two:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Discussion\u003C\u002Fstrong>: the spec writer, to ask the spec or update it simply (“What does the spec say about paying in instalments?”, “Add that the tax receipt goes by email”).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Brainstorm\u003C\u002Fstrong>: a product agent, in the manner of BMAD, that matures an idea: uses and journeys, discovery, compliance and GDPR, what other trades do. It proposes features, spec pages, decisions, and tickets, which it names without making them.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>You give a subject. No need to choose documents: the agent has them all, through the index. You can \u003Cstrong>join new files\u003C\u002Fstrong>: they are filed and indexed by themselves in the Documents. The window’s footer shows the agent’s harness, account and model, the project’s by default, and lets you change them.\u003C\u002Fp>\n\u003Cp>They are agents of Escouade like the others: the same conversation, and their questions are answered from the list of agents too. They work in the folder of the docs branch, read the code without ever changing it and only write the docs, through Escouade’s docs tools. Their harness itself keeps them from it, in every mode: Claude Code has its tools that write taken away, Codex only reads in its sandbox, OpenCode, Copilot CLI and Antigravity CLI have their writes and commands refused. Cursor CLI and Mistral Vibe change files without going through Escouade: no discussion runs on them, and the window says so.\u003C\u002Fp>\n\u003Cp>The discussions are cards under “New discussion”, each marked “Brainstorm” or “Discussion”, with its state: “Question”, “Answering”, “Draft” (changes proposed not poured yet), “Poured”.\u003C\u002Fp>\n\u003Cp>A discussion open shows the conversation on the left, and on the right \u003Cstrong>“What will go in the spec”\u003C\u002Fstrong>: the changes proposed page by page (a new section, the sentences taken away struck through and the new ones in green) and the decisions proposed. A cross takes a proposal out. \u003Cstrong>“Pour into the spec”\u003C\u002Fstrong> writes the pages on the docs branch, and the decisions in the register, proposed: they are accepted in one click in the Decisions. Nothing is shared: the status bar says how many changes wait for “Share”.\u003C\u002Fp>\n\u003Cp>“Ask the spec”, at the top of the specification, opens a discussion with the spec writer. A project without a spec offers “Write a first spec from the code”: the spec writer reads the code and proposes a first version, filed by subject (it costs tokens, hence the gesture).\u003C\u002Fp>\n\u003Ch2 id=\"plan-tickets-from-the-spec-to-the-tickets\">Plan tickets: from the spec to the tickets\u003C\u002Fh2>\n\u003Cp>Once the spec changed, \u003Cstrong>“Plan tickets”\u003C\u002Fstrong> asks a planner for the tickets that will implement it. The button is on a discussion whose changes were poured, and at the top of the specification while changes have no tickets (“3 changes without tickets · Plan tickets”): the pages poured or written by hand, and the decisions proposed, since the last planning.\u003C\u002Fp>\n\u003Cp>The planner reads these changes and decisions, the code (the files the code index links to them, and the project’s folder, without changing anything) and the tickets of the board. It makes the tickets in “To do”, each with its description, its acceptance criteria, the tickets it comes after (“After”) and the pages and decisions it implements, which its description names for its agent. A ticket the board already has, even done, is not made again: it is said “On the board already”. The planner does not start the tickets: the autopilot and the board’s rules apply as to any ticket.\u003C\u002Fp>\n\u003Cp>What it made shows under the discussion, or on the map of the subjects, with \u003Cstrong>“Undo”\u003C\u002Fstrong>: the tickets not started yet are removed, and the changes are to plan again. A subject’s card shows the keys of its tickets, and a ticket’s card on the board the pages it implements, which open in one click in the Docs tab.\u003C\u002Fp>\n\u003Ch2 id=\"the-spec-always-up-to-date\">The spec always up to date\u003C\u002Fh2>\n\u003Cp>The spec follows the code in two ways.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>The tickets’ agents keep it.\u003C\u002Fstrong> Each ticket’s instructions ask its agent, when the ticket changes how the product behaves, to update the pages it touches and to leave a decision that says what changed and why, before handing it in. Nothing stops the approval: the review is where it shows. With the current branch, those changes go in the ticket’s branch and are merged with its code. With a \u003Ca href=\"#the-docs-branch\">fixed branch\u003C\u002Fa>, they wait in a copy Escouade keeps, and are poured on the docs branch \u003Cstrong>only when the ticket is approved\u003C\u002Fstrong>: the spec never tells of a behavior not merged yet. What the team wrote on the branch meanwhile stays.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>The comparison to the code.\u003C\u002Fstrong> After each ticket approved and merged, a short agent reads the code, changing nothing, and compares the pages the ticket touches: those it changed, those that name it, and those that talk of its files or their symbols (by the \u003Ca href=\"\u002Fen\u002Fdocs\u002Fcode-index\u002F\">code index\u003C\u002Fa> when it is on). What it finds shows on the map of the subjects (“1 gap”, “compared to the code 2 h ago”) and at the top of the page.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>“Compare to the code” does it on demand: at the top of the specification for every page (40 at most, those compared longest ago first), or at the top of a page for that page alone. Each page compared costs tokens, on the account and harness of “Model for written texts”.\u003C\u002Fp>\n\u003Ch2 id=\"the-decisions\">The decisions\u003C\u002Fh2>\n\u003Cp>The Decisions space is a register, not a document: a row per decision on the product, the latest first, with its number, its title, where it comes from (a brainstorm, a discussion, a ticket, a document), its state, what it changed in the spec and its date. On top: how many decisions are accepted, proposed and superseded. The “All” menu filters the register by state.\u003C\u002Fp>\n\u003Cp>A click on a row opens its detail on the right: the context, the decision, its consequences, the spec pages it changed (with the lines added and removed; a click opens the page), its links (tickets, origin, documents), and what it replaces or what replaces it.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Proposed\u003C\u002Fstrong>: an agent, or someone of the team, proposes it; it is a decision only once accepted. “Accept”, on its row or in its detail, accepts it in one click, in your name.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Accepted\u003C\u002Fstrong>: it is no longer rewritten. To go back on it, “Replace it” proposes a new decision that replaces it.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Superseded\u003C\u002Fstrong>: the new decision was accepted; the old one stays in the register, as it was, and says by which.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>“Propose a decision” writes one by hand: its title, its context, the decision, its consequences, and the accepted decision it replaces if there is one.\u003C\u002Fp>\n\u003Cp>The agents propose their decisions through the \u003Ca href=\"\u002Fen\u002Fdocs\u002Fmcp\u002F\">MCP server\u003C\u002Fa>. The one a ticket’s agent leaves is accepted when you approve the ticket: it goes in the same commit as its code. Each decision is a file of \u003Ccode class=\"key\">.escouade\u002Fdecisions\u002F\u003C\u002Fcode>, numbered (\u003Ccode class=\"key\">0014-family-rate.md\u003C\u002Fcode>), shared with the other docs.\u003C\u002Fp>\n\u003Ch2 id=\"importing-an-existing-spec\">Importing an existing spec\u003C\u002Fh2>\n\u003Cp>A project without a spec starts from an empty space. When Escouade finds a spec in the project (a \u003Ccode class=\"key\">SPEC.md\u003C\u002Fcode> at the root or in \u003Ccode class=\"key\">docs\u002F\u003C\u002Fcode>, a \u003Ccode class=\"key\">spec\u003C\u002Fcode> or \u003Ccode class=\"key\">specs\u003C\u002Fcode> folder, a \u003Ccode class=\"key\">docs\u002F\u003C\u002Fcode> folder of Markdown files), it offers it:\u003C\u002Fp>\n\u003Col>\n\u003Cli>“See how it would be cut” shows how Escouade would cut it, by its titles: a subject per main title, a page per section; in a folder, a subject per file. A lone title at the top of the file, the document’s name, becomes the introduction’s title.\u003C\u002Fli>\n\u003Cli>Untick the pages you don’t want.\u003C\u002Fli>\n\u003Cli>“Import” writes the pages. Each one cites the file it comes from and keeps its place in the order of the original spec.\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>Nothing is written before “Import”, and a page that already exists stays as it is. The original file is neither changed nor removed: removing it from the repository is up to you.\u003C\u002Fp>\n\u003Cp>Escouade keeps the imported paths with the docs, without duplicates, and shares them with the team. As soon as the project has a spec in Escouade, every agent Escouade launches on it (ticket, discussion, planner…), whatever its harness, is told that the spec and the project’s decisions are in Escouade and are the only ones to follow; the old file is named: it is no longer read as the spec nor updated.\u003C\u002Fp>\n\u003Ch2 id=\"the-documents\">The documents\u003C\u002Fh2>\n\u003Cp>The Documents space is the project’s drive: requirements, meeting notes, mockups and legal papers, in folders under \u003Ccode class=\"key\">.escouade\u002Fdocuments\u002F\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>On the left, \u003Cstrong>the folders\u003C\u002Fstrong>, with how many files each holds; “All documents” shows them all. A folder that holds others unfolds.\u003C\u002Fli>\n\u003Cli>On the right, \u003Cstrong>the files\u003C\u002Fstrong> of the folder open, each with who added it, its size, its date, and what the agents did with it: “✓ read by the agents” once an agent read it, “cited 3 times” when pages of the spec or decisions cite it.\u003C\u002Fli>\n\u003Cli>A click on a file shows the text Escouade read of it.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>\u003Cstrong>Dropping files.\u003C\u002Fstrong> Drag files onto the space, or “Drop files”. Each file is \u003Cstrong>read and indexed on your machine\u003C\u002Fstrong>: nothing goes to the Internet. Escouade reads the text of PDFs, Word (\u003Ccode class=\"key\">.docx\u003C\u002Fcode>) and OpenDocument (\u003Ccode class=\"key\">.odt\u003C\u002Fcode>) files, Markdown and text; of an image, it keeps its format and size only. The text read stays in Escouade’s folder, never in the repository; the file itself goes into the repository, on the docs branch.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Filing.\u003C\u002Fstrong> A file dropped in an open folder stays there. Dropped on “All documents”, Escouade files it by itself, in this order:\u003C\u002Fp>\n\u003Col>\n\u003Cli>the folder whose name its name or its title bears (“Meeting notes workshop” goes into “Meeting notes”);\u003C\u002Fli>\n\u003Cli>the folder of its nature, when the drive has one: meeting notes, requirements, a mockup, a legal paper, a quote or an invoice, a presentation, a planning;\u003C\u002Fli>\n\u003Cli>the folder whose files are nearest to it by the meaning, when the \u003Ca href=\"\u002Fen\u002Fdocs\u002Fshared-memory\u002F\">vectors’ model\u003C\u002Fa> is downloaded, then by the words;\u003C\u002Fli>\n\u003Cli>otherwise, a \u003Cstrong>new folder\u003C\u002Fstrong>, made for it: the one of its nature (“Planning”), “Images” for an image, or “Other”.\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>Escouade says where it filed it and why; “Move to” puts it in another folder. You can also drag a card onto a folder on the left. “New folder” makes a folder in the one open.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Search the documents\u003C\u002Fstrong> searches the names and the text of all the documents, by the meaning and the words when the vectors’ model is there, by the words otherwise, and shows the passage that answers.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Heavy files.\u003C\u002Fstrong> When the repository has Git LFS rules (\u003Ccode class=\"key\">.gitattributes\u003C\u002Fcode>) that take the file, they apply: nothing to do. Otherwise, past 50 MB, Escouade warns before adding it, because git keeps every version in full and everyone on the team downloads it: “Add anyway” or “Don’t add them”.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>The agents\u003C\u002Fstrong> search and read the documents through Escouade’s tools (\u003Ccode class=\"key\">search_documents\u003C\u002Fcode>, \u003Ccode class=\"key\">read_document\u003C\u002Fcode>), whatever their harness, and cite the ones what they write comes from in the sources of a page of the spec. A private project’s documents are seen by its own agents only.\u003C\u002Fp>\n\u003Ch2 id=\"sharing-the-docs\">Sharing the docs\u003C\u002Fh2>\n\u003Cp>While the Docs tab is open, or while the docs have changes, the status bar says “Docs on the branch main · 2 changes to share”. The changes are the files of \u003Ccode class=\"key\">.escouade\u002Fspec\u003C\u002Fcode>, \u003Ccode class=\"key\">decisions\u003C\u002Fcode> and \u003Ccode class=\"key\">documents\u003C\u002Fcode> changed and not sent yet.\u003C\u002Fp>\n\u003Cp>“Share” first brings in what the others shared, then saves (commits) the files of the docs, and them alone, and sends them (push). The code you change meanwhile is left alone.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>When the branch also has commits of code not sent yet, Escouade tells you first: “Share everything” sends them with the docs, “Cancel” does nothing.\u003C\u002Fli>\n\u003Cli>When two people changed the same pages, the status bar names them: “The agent resolves” hands the conflict to a writer agent, who keeps what each one meant; “Cancel” puts the docs back as they were. You share again once it is done.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"callout note\">\u003Cp class=\"callout-title\">Note\u003C\u002Fp>\u003Cp>Escouade never shares by itself: nothing is committed or pushed without a click on “Share”.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"the-docs-branch\">The docs branch\u003C\u002Fh2>\n\u003Cp>Settings › Projects › Git, “Docs branch”:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>The current branch\u003C\u002Fstrong> (by default): the docs live in the branch of each folder. Those of a ticket follow its branch and are merged with its code.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A fixed branch\u003C\u002Fstrong> (\u003Ccode class=\"key\">docs\u003C\u002Fcode>, for instance): the docs always live on that branch, which Escouade keeps in a worktree of its own, in its system folder. Escouade makes it when needed, from the remote branch when there is one, and never merges it anywhere: that is up to the team.\u003C\u002Fli>\n\u003C\u002Ful>\n",[8,12,15,18,21,24,27,30,33,36,39],{"id":9,"text":10,"depth":11},"the-tab","The tab",2,{"id":13,"text":14,"depth":11},"the-specification","The specification",{"id":16,"text":17,"depth":11},"a-page","A page",{"id":19,"text":20,"depth":11},"the-discussions","The discussions",{"id":22,"text":23,"depth":11},"plan-tickets-from-the-spec-to-the-tickets","Plan tickets: from the spec to the tickets",{"id":25,"text":26,"depth":11},"the-spec-always-up-to-date","The spec always up to date",{"id":28,"text":29,"depth":11},"the-decisions","The decisions",{"id":31,"text":32,"depth":11},"importing-an-existing-spec","Importing an existing spec",{"id":34,"text":35,"depth":11},"the-documents","The documents",{"id":37,"text":38,"depth":11},"sharing-the-docs","Sharing the docs",{"id":40,"text":41,"depth":11},"the-docs-branch","The docs branch",1793278986685]