What is Blueprint?#

Blueprint is the control plane for AI-assisted software delivery at Atos. It separates the work of thinking — requirements, architecture, governance, compliance — from the work of building — code, tests, documentation. Two surfaces, one source of truth.

The portal you log into is where Product Managers, Architects, Reviewers, and Practice Leads operate. They converse with named AI agents, produce versioned artifacts (PRD, architecture, epics, stories, sprints, assessments, compliance), and route them through formal review gates. Developers never see the portal. They work in their IDE — Cursor, VS Code, Claude Code — through a token-gated MCP server that pulls the same agents, the same standards, and the same context the portal uses.

The platform's job is to make the upstream decisions explicit, versioned, reviewable, and traceable — and to make the downstream execution feel like an extension of those decisions, not a fresh interpretation of them.

The 5-minute tour#

If you have five minutes, here is the entire shape of the platform.

1. Tenancy. Clients live under Business Units. Projects live under Clients. Your scope as a user — BU, client, or project — defines what you see.
2. Project workbench. Every project opens to a tabbed page: Overview · Documents · Planning · Team Activity · Members & SDK · Compliance. Documents is where context goes in; Planning is where the artifacts live; Team Activity is where the pipeline and the dev board live.
3. Agents. Each artifact is driven by a named agent: Clara writes the PRD, Tomás the architecture, Inês decomposes work, Hugo plans releases, Diogo assesses brownfield code, Gaspar governs the delivery methodology, Íris plans the cloud landing zone, Sofia drafts use cases, Lena writes tests, Dante writes docs. Maestro builds new agents when the sixteen that ship aren't enough.
4. Status flow. Every artifact moves through draft → in_review → approved. Approval is only granted via a formal review record — never by toggling a status.
5. Cascades. Editing an approved PRD auto-resets the architecture to draft. Editing the architecture resets epics. Editing epics resets sprints. The system warns you before you do it.
6. SDK. When the upstream is approved, the developer in the IDE picks up the same project context through the MCP server and starts shipping. Their PRs link back to stories. Their telemetry reports back to the portal.

That's it. Everything else in this manual is depth on those six facts.

The three planes#

It helps to picture Blueprint as three planes stacked on top of each other.

You can be a specialist in one plane and a visitor in the others. The role playbooks in Part 3 show you exactly which plane you live in.

Tenancy: Clients & Business Units#

Business Units are the organisational containers (e.g. BU Portugal, BU Iberia). Clients are the customers a BU serves (e.g. Banco Central, Iberdrola). Projects belong to clients.

Permission scope flows top-down: a user scoped to BU Portugal automatically inherits access to every client and every project under that BU. A user scoped to a single client sees only that client's projects. A user scoped to a project sees only that project. This means you almost never need to manage per-project access by hand — assign a sensible scope once and let inheritance do the rest.

Each client carries its own custom standards, LLM restrictions (e.g. EU-only models), and PII mode. Those choices propagate into every project under that client and into every agent conversation those projects launch.

Projects & modes#

A project is the unit of delivery. It has a name, a stack, a domain, a client, a team size, a timeline, and a mode:

A project also carries a workflow — the ordered sequence of agents it will run. You pick a preset (Full Project, Modernization, Test Gen, Documentation, Feature Addition, Use Cases) or build a custom pipeline by drag-dropping agent cards. The Full Project and Modernization presets include the DevOps Methodology step (Gaspar) by default; the Infrastructure Plan step (Íris) is in no preset — add it deliberately from the pipeline builder or the What's Next? panel.

Living artifacts#

Every artifact in Blueprint — PRD, architecture, epic, story, sprint, assessment, model card, AI Act checklist — is versioned. Every save creates a new row; old versions are never overwritten. You can diff any two versions and see line-by-line changes with a +/- count. You can scroll the audit trail and see who edited what, who reviewed it, and what they said.

Artifacts are also structured. PRDs are parsed into 12 sections; architectures into decisions; assessments into findings and a system component map. Sections and decisions are individually editable, traceable, and reviewable.

Knowledge & grounding#

Agents don't work from vibes — they work from what you gave them. There are three distinct knowledge channels, and users conflate them constantly:

Grounding is a tool call, not a prayer. Agents reach the project index live through four tools — list_sources, rag_search, file_list, file_read — and are instructed to cite the paths they read. Clara and Tomás are the heaviest users: both carry an explicit "ground yourself before you answer" discipline, so asking the operator something the uploaded brief already answers is treated as a defect. Inês, Diogo, Mateus, Hugo, Sofia, Dante and Lena also search the index. Gaspar, Íris, Helena, Victor and Maestro deliberately do not — their inputs are the artifacts themselves.

Grounding is only as good as the index: until every document on the Documents tab shows ✓ Ready, agent-launch buttons across the Planning tab turn amber with the warning that the agent "may not see everything yet". It's a heads-up, not a block — but generating a PRD against a half-indexed brief is a self-inflicted wound.

Status flow & cascades#

Every reviewable artifact lives in one of three states:

The cascade rule is the most important rule in the platform. When you edit an approved PRD, the architecture resets to draft. When you edit an approved architecture, the epics reset to draft. When you edit approved epics, the sprints reset to draft. The downstream pages show an orange "upstream changed" banner so the team can review the impact before re-approving.

Stories are the exception: they live in a delivery lane, not a review lane — backlog → ready → in_progress → review → done, plus blocked — and their transitions are gated by dependencies, not reviewers. See Epics & Stories.

Reviews & AI cross-model review#

A review is a record. It captures the reviewer's name, role, decision, comments, and optionally per-section comments with severity. Reviews live forever; they're the spine of the audit trail.

AI cross-model review is a power feature: with one click you can ask a different model — for example Opus — to review the artifact that Sonnet produced. The output is a structured review with scores (completeness, clarity, feasibility, standards compliance), strengths, and severity-tagged findings. It's saved as a formal review record alongside the human ones, so it shows up in the audit trail.

Agents#

An agent is a named role with a system prompt, a workflow of steps, a context source list, a preferred model, and a personality theme. Sixteen ship by default — fourteen in the portal, two in the SDK. Their definitions live as YAML files on disk (frontend/agent-defs/agents/), are seeded into the database, and are editable in the Agent Studio; Settings → Maintenance → Reload Default Agents re-seeds from disk without touching forks or client-specific agents.

Agents resolve through a chain: project-specific override → client-specific override → Atos default. So you can fork Clara for one client without touching anyone else's Clara. Forking now has two doors: the classic Editor (raw fields) and Customise with Maestro, where Maestro interviews you and writes the customised prompt. Personality themes are a lighter-weight customisation: swap names and voice (the "Simpsons" theme renames Clara to Marge, Tomás to Homer, etc.) without changing workflows.

Conversations are durable and shared. Every agent chat is a first-class database record, keyed per (project, agent) and shared by every project member — each message shows its author, and two colleagues can work the same thread. Close the panel, refresh, come back next week: the transcript re-hydrates, with a Load earlier messages link for older pages. Tool calls the agent makes (rag_search, file_read…) render as collapsible cards inside the transcript, and the same record replays read-only in each artifact's Conversation tab — evidence that a human directed the agent, not the model alone. ↻ Restart discovery starts a fresh thread; the old one is kept, not deleted.

Streams are resilient: AgentChat auto-continues on truncation up to ten times and extracts tagged output (<prd>…</prd>) for you. And because turns run server-side, closing the chat mid-answer doesn't lose the answer.

Pipelines#

A pipeline is an ordered sequence of agents that runs end-to-end. The Full Project preset runs Clara → Tomás → Inês → Hugo, then Lena and Dante in parallel. The Modernization preset starts with Mateus, who extracts behavior from the uploaded legacy codebase, then runs Clara (modernization PRD) → Tomás (target + cutover) → Inês → Hugo. The System Rescue preset runs Diogo alone for "what's the state, should we keep it?" decisions where rebuilding isn't the goal. The Custom mode lets you drag agent cards into any sequence — including the optional Compliance Audit (Victor) and Design Review (Helena) steps that read the artifacts produced upstream.

Today, pipelines run interactively — one human-in-the-loop step at a time. The roadmap (the "Red Pill" path) lets you trigger the pipeline once and review only the final output. Same agents, same governance, different cadence.

The pipeline is also the agent management surface. It lives on the project's Team Activity tab. Each card shows the live agent assigned to that step (with a (forked) badge if the project has customised it), plus a real-status badge — ✓ approved, ◐ in review, ! draft, or ● in progress. Click any card to expand its actions inline: a Run this step with dropdown (choose Auto (client / default) or any agent classified for that step — an agent can only be offered for the one pipeline step it belongs to), Customise with Maestro or Editor (both fork the global into a project-scoped copy), and for existing forks Edit, History, Resync, and Remove. All agents are forkable per project, including the SDK-side Miguel and Beatriz — a fork flows through the SDK so the developer's IDE serves the project's customised instructions, not the global default.

Pipelines are reusable. On New Project, once you've assembled a pipeline, ★ Save this pipeline as a reusable flow stores it under a name, scoped This client only or Global. Saved flows then appear as chips next to the built-in presets, for anyone creating the next project.

Traceability & impact#

Every PRD section, every architecture decision, every story is linked. The link types are implements, addresses, depends_on, validates, and derived_from. So when a PRD section changes, the platform can tell you which architecture decisions and which stories are affected — and how severely.

Coverage metrics show, per project, the percentage of PRD sections with an architectural answer, the percentage of architecture decisions with a story, and the count of orphan items. Colour-coded thresholds make the gaps obvious. Coverage is computed by matching titles across artifact versions, so edits that re-parse PRD/architecture content don't drop a project's coverage to zero overnight.

Orphan trace suggestions. The orphan-stories alert is click-through. Expanding a story exposes a Suggest traces button: an agent reads the story content against the current PRD sections and architecture decisions and proposes 0–3 candidate links per side, each with a one-line rationale that cites a concrete element (an FR-NNN id, a stack name, a fallback chain). Apply creates the explicit link; Skip hides it locally. Backfills the gap that older trace-generators left behind without the human typing UUIDs.

Impact preview. When a PRD or architecture is edited, downstream artifacts get reset to draft as usual — but the upstream banner now also auto-loads an impact summary: a one-sentence headline, a per-section change list with informational / review_needed / breaking severity, and a list of downstream artifacts likely affected with reasons. Results are cached per (current, against) artifact pair so subsequent viewers and reloads don't re-burn tokens. The cache misses naturally on the next upstream edit.

Cascade Helper. Below the impact preview on the Work Breakdown banner, Generate proposals walks traceability links from the changed PRD/architecture parts to affected stories and dispatches an agent (Inês) to propose a per-story patch. Each proposal renders as a side-by-side base→proposed diff with Accept (applies the patch directly to the live story) and Reject (dismisses). Inês is told NOT to pad with low-value suggestions: when a story is genuinely unaffected she returns needs_change=false and nothing is stored.

Close the loop. Both the architecture and the epics-stories upstream banners carry a Keep as-is action. The decision is yours: clicking it restores the affected artifact's status / clears the epic flags / rejects any still-pending cascade proposals, with an audit-trail entry recording who acknowledged and when. The banner self-hides; new upstream edits re-flag affected artifacts and the banner reappears for genuine new changes. Companion action Address with Tomás on the architecture banner opens the architect chat with the impact summary auto-sent as the first user message.

Needs-attention strip. A pinned strip at the top of every project page surfaces all pending traceability/cascade items as click-to-scroll chips: cascade proposals, upstream resets, orphan stories, legacy corrupt links. Hidden when there's nothing pending.

The Requirements model (opt-in). Projects can adopt a stronger spine: a first-class requirement set extracted from the PRD, each with a stable key. From then on, changes are proposed — you describe the change, Clara drafts requirement deltas (create / update / retire) as reviewable diffs, and each accepted delta flags exactly the stories it affects, which Inês then offers to rewrite one approval at a time. A small edit no longer regenerates everything. See Requirements.

SDK & MCP#

The SDK is how a developer's IDE talks to Blueprint. It's an MCP server — a small process the IDE launches over stdio that exposes resources (knowledge, standards, templates) and tools (validate, log decision, scan PII, claim story, link PR, log tokens).

The MCP server is a thin client. It doesn't ship intelligence in a binary; it fetches a knowledge bundle from the backend on startup and refreshes every fifteen minutes. Revoking a token kills the developer's access on the next refresh — no need to re-deploy anything.

One server per project. The portal compiles a per-project MCP binary (atos / atos.exe) on demand and serves it directly; running it once with --install from the project root writes the IDE configs into the workspace. Cursor gets .cursor/mcp.json + .cursorrules; Copilot gets .vscode/mcp.json + .github/copilot-instructions.md plus one slash-command per agent; Claude Code gets CLAUDE.md. Install now runs the browser auth flow automatically and hands you a --doctor readiness grid at the end — exit 0 means the install actually works. The whole programmatic surface sits behind one path pattern, /api/sdk/*.

Tokens & heartbeat#

Tokens are minted per developer, per project, by the developer's own atos --auth browser flow — never embedded in a binary or a config file. Each token is bound to (project, user) and stored at ~/.atos/tokens/<projectId> (Windows: %APPDATA%\atos\tokens\<projectId>), so two projects on one machine no longer clobber each other. Every fifteen minutes (or when the developer triggers an action) the SDK pings the backend with a heartbeat; the portal surfaces token health on the SDK Packages page (/sdk): active (heartbeat < 1h ago), stale (no heartbeat in 24h), revoked (manual kill), expired. Every MCP tool call re-validates membership server-side; a removed member gets not_a_member within a minute.

Token usage telemetry — model, input tokens, output tokens, cost — flows in via POST /api/token-usage. You see it aggregated per project, per agent, and per model on the Telemetry page.

Roles & permissions#

Blueprint uses a permission matrix. Roles are bags of permissions; permissions are atomic verbs (prd.generate, architecture.review, platform.users.manage). The five system roles are:

Admins can fork system roles into custom ones (e.g. QA Lead, Compliance Officer) with any subset of permissions. Permissions are checked in the UI via the can(...) hook and enforced server-side by middleware — there is no UI-only enforcement. New permission families since May: devops.* and infra.* (Gaspar's and Íris's artifacts), stories.override (act on a story claimed by someone else), epics.delete / stories.delete, platform.settings.github, and platform.knowledge.manage.

Roles are only one of three axes. What a developer can actually do on a project is the conjunction of role/scope (RBAC — "what can you do, where"), project membership (the allowlist on Members & SDK — "are you on this project"), and, for GitHub operations specifically, a GitHub account explicitly ticked on your membership row. A perfect role with no membership installs nothing.

For Product Managers PM#

Your day, end to end

1. Kick off the project. Go to Projects → New. Pick the client, name the project, choose mode (greenfield/brownfield), pick the workflow preset (Full Project is the safe default), and set a stack hint and team size.
2. Upload context. In the project's Documents tab, drop in any client-supplied PDFs, Word docs, markdown, or a codebase ZIP. Each document is indexed into the project's knowledge base — watch the status pill walk from Queued through Embedding to ✓ Ready. Until everything reads Ready, agent-launch buttons show an amber ⚠ warning: the agent may not see everything yet.
3. Open Clara. The PRD tab launches a streaming chat with Clara. She walks you through twelve structured steps: discovery, classification, vision, success criteria, user journeys, domain reqs, scoping, functional reqs, NFRs, polish, generation. Don't try to skip them — answer each one. The depth of your answers is the depth of your PRD.
4. Save, edit, iterate. When Clara emits the PRD, save it. The page renders sections as collapsible cards. Click any section to edit in place — every save is a new version. Open the Versions tab to diff with a previous draft.
5. Submit for review. Click Submit for Review. The PRD enters in_review; the project phase advances to prd_review. Notify the reviewer (out of band — Blueprint doesn't email yet).
6. Address feedback. If the reviewer requests changes, edit the affected sections. Each edit creates a new version; nothing is lost. When you're done, ask the reviewer to re-review.
7. Decompose into work. Once the architecture is approved, open the Epics & Stories tab and chat with Inês. She produces epics first, then stories per epic. Save them. Re-generate stories for a single epic with the per-epic Generate stories button if you want tighter control.
8. Plan the first sprint. Move to the Sprints tab and chat with Hugo. He proposes a sprint based on team capacity and dependencies. Adjust, save, lock.

Your gotchas

For Architects Architect#

Your day on greenfield

1. Read the approved PRD first. Open the project, scroll the PRD's section cards, note which sections need architectural answers. The traceability indicators on each section show whether a decision already covers it.
2. Open Tomás. The Architecture tab launches Tomás. He has read the PRD, the project documents, the client's standards, and the client's LLM restrictions. Spend the first message stating your real constraints — preferred stack, regulatory boundaries, anti-patterns to avoid. He'll push back where the constraints conflict.
3. Walk the 10 steps. PRD review · stack decisions · architecture pattern · data model · integration design · observability/security · implementation patterns · project structure · validation · generation. He emits an <architecture> block plus a <traceability> JSON linking each decision to PRD sections.
4. Save and review coverage. The Architecture page renders decisions as cards. The Coverage view shows which PRD sections still have no architectural answer. Close the gaps before you submit. For a targeted fix, every section heading carries ✦ Edit with AI — the architect rewrites just that section.
5. Submit for review. Same flow as the PM — Submit for Review, wait for a reviewer, address feedback. Architecture cannot be approved until the PRD is approved.
6. Hand off to delivery governance. Once the architecture is approved, Gaspar can govern the DevOps methodology (branching, quality gates, environments — auto-tiered to the project's real size), and Íris can plan the concrete cloud landing zone. Both are governed artifacts with the same review flow as yours.

Your day on brownfield

Different entry point depending on intent. The Modernization preset starts with Mateus extracting behavior. The System Rescue preset starts with Diogo assessing health. Both can run together if the project genuinely needs both lenses.

Modernization (replatforming a legacy system)

1. Upload the codebase. Connect a GitHub repo or upload a ZIP. The scanner walks the tree, samples representative source files per detected language (COBOL, RPG, .NET, Java, anything), and extracts text from PDF/DOCX functional specs alongside the source.
2. Run Mateus. The Functional Archaeologist's six-step workflow produces a versioned functional spec with structured extraction: capabilities (what the system does), business rules (validations and constraints quoted from source), data entities (what each table/file represents), external dependencies (programs referenced but not present in the upload — explicit migration risks), migration verdicts per capability (carry_forward / redesign / drop / replace_with_external), and unresolved questions (what Mateus could not extract from the available source).
3. Run Clara in modernization mode. When she sees a functional spec in context, she writes a modernization PRD that maps verdicts to artifact sections: carry_forward → FRs verbatim with citations; redesign → outcome-preserving FRs with rationale; drop → Out of Scope with the reason; replace_with_external → External Integrations; missing externals → "Legacy Dependencies to Replace"; unresolved questions → her Open Questions block.
4. Run Tomás in migration mode. He designs two shapes: the target architecture and the interim/cutover shape (strangler, parallel run, anti-corruption layer, dual-write window). Stack-fit reasoning shifts — the existing stack is the legacy itself, the cost of staying is "we keep running this forever". Cutover plan, audit-trail continuity, regulatory carry-forward, rollback, and parallel-run window are part of the architecture, not an afterthought.
5. Decompose and sequence. Inês breaks the modernization PRD into epics and stories with explicit dependencies on the cutover shape. Hugo risk-sequences so the highest-risk migrations (data, audit continuity, missing externals) land first.

System Rescue (stabilise the existing system)

1. Connect or upload the codebase. Same as above.
2. Run Diogo. His seven-step workflow produces the assessment narrative, the findings table (category · severity · evidence · remediation · effort), and the system component map. He's calibrated to admit what he cannot see — confidence drops when source bodies aren't in context.
3. Review findings. Decide: stabilise this system, modernise it, or accept the risk. The decision is yours; Diogo informs, doesn't dictate. If the answer is modernise, the modernization flow above takes over from here with the assessment as additional context.

Your gotchas

For Reviewers / Design Authority Reviewer#

How to review an artifact

1. Open the Governance tab. The Status Hero at the top shows the current state, the version, and who submitted it.
2. Diff against the previous version. The Version Comparison widget lets you select any two versions and see a unified diff. Always diff before you read the full content — diffs answer "what changed since I last looked" in seconds.
3. Run AI cross-model review (optional). One click. It returns scored findings. Treat them as noise reduction, not as truth — they save you time finding the obvious issues.
4. Add a formal review. Pick a decision (approved, changes_requested, rejected), write comments, optionally add per-section comments with severity. Submit.
5. Watch the cascade. If you approve, the project advances to the next phase. If you request changes, the artifact stays in in_review and your comments appear inline on the artifact page for the owner to address.

Your gotchas

For BU Leads BU Lead#

Your week

1. Monday: scan the Dashboard. Active projects, total LLM spend this week, average PRD/architecture cycle times, projects awaiting review. Red flags surface as colour-coded cards.
2. Tuesday: onboard new accounts. Create the client in Clients → New. Set its custom standards, LLM restriction (EU-only is the safe default), PII mode, and assign it to your BU.
3. Wednesday: balance the team. Open Team. Add or remove members, adjust capacity hours, assign people to projects. The portal warns when a person is overloaded across projects.
4. Thursday: spend review. Open Telemetry. Look at cost-per-project and cost-per-agent. Spot the outliers. If Clara is burning Opus tokens on small projects, retune the model preference in Agent Studio (or escalate to the admin). On each project's Planning tab, the Cost estimate card splits actual upstream agent spend from a forecast of dev-controlled downstream spend — use it before committing a fixed price.
5. Friday: compliance pulse. Open Compliance. See AI Act checklist completion per project. For high-risk classifications, ensure a model card exists.

Your gotchas

For Platform Admins Admin#

Your responsibilities

• Users. Create accounts at /users (+ New User), assign roles and scopes, link or sync Clerk identities, deactivate when people leave. In SAML-only deployments there are no invitation emails — accounts activate on first SSO sign-in.
• Auth. Settings → Auth: identity providers ("Sign in with X" buttons), SP metadata for the IdP admin, SAML options and events. The deployment mode itself (Clerk-mode / SAML-only / gateway) is env-var driven — the tab shows which is active.
• Roles. The Roles editor at /roles lets you fork system roles into custom ones with any permission subset. System roles are non-deletable but their permission set is editable.
• Agent Studio. Edit agent system prompts, fork client-specific variants, build new agents with Maestro, classify every agent to a pipeline step, manage personality themes.
• Model catalogue. Settings → Catalogue: endpoints (Anthropic, OpenAI, Azure, Gemini, Voyage, self-hosted OpenAI-compatible, mock), the LLM and embedding models on each, per-model pricing, and the three defaults (LLM, code-chunk embedding, doc-chunk embedding). These rates drive every cost figure in the product.
• Knowledge. Settings → Knowledge: the global markdown bundle every developer's IDE fetches. Drag-drop .md files or re-import from disk.
• GitHub. Settings → GitHub: GitHub App credentials (env or session override), a "Test now" probe, and a read-only API playground for debugging.
• Tokens & builds. Token health lives on /sdk (SDK Packages); revocation bites on the next tool call (≤60 s). Settings → SDK Builds shows the shared binary build cache with cancel/invalidate/prune actions.
• Reseed. If the platform's default agents drift after manual edits, Settings → Maintenance → Reload Default Agents re-seeds from the on-disk YAML definitions. Forks and client-specific agents are never clobbered.

Your gotchas

For Developers Developer#

Your install

1. Be a member. Your PM adds you on the project's Members & SDK tab. No membership, no download, no auth — nothing to troubleshoot until this is true.
2. Download the binary. On the project's Members & SDK tab (or /sdk), pick OS (Linux / Windows) and IDE (Cursor, VS Code Copilot, Claude Code, or All). The button walks Checking cache… → Building binary… → Starting download… and hands you a single atos / atos.exe.
3. Run it from your project root. chmod +x atos && ./atos --install (Windows: .\atos.exe --install in PowerShell). It writes the IDE configs, then opens your browser to authorize — click Authorize and the CLI mints your personal token, stored at ~/.atos/tokens/<projectId>. Tokens are per-developer, per-project; two projects on one machine coexist.
4. Verify. ./tools/mcp-server/atos --doctor — seven [OK]/[FAIL] checks ending in "All checks passed — SDK is ready." Restart your IDE; the agent slash-commands appear (/dev, /review, /test, /docs).

Your day

1. Pick a story. Use the MCP tool get_my_queue — your claimed/assigned stories plus ready, unassigned stories whose dependencies are met. Each shows a short ID (e.g. PROJ-42), title, and acceptance criteria.
2. Claim it. claim_story atomically takes the story to in_progress under your name. Claiming only works from backlog/ready, and never on a story whose dependencies aren't done — the portal enforces the same rule, so no one can jump the graph.
3. Cut a branch. Convention is story/PROJ-42-short-name. The MCP server auto-detects orphan branches and warns if you're about to leave one.
4. Code. Use Miguel (/dev) for an implementation pass. He has the story acceptance criteria, the architecture, the project standards, and any reference code from the project documents.
5. Review. Use Beatriz (/review) before you push. She produces structured review output that surfaces issues you can fix before a human ever looks.
6. Open a PR. Push the branch and open the PR. Link it back to the story: story_actions(action: "link_pr", shortId: "PROJ-42", prNumber: 137, repo: "owner/repo"). The portal now shows the PR link on the story card.
7. Stay validated. Run validate_output on documents you generate; scan_pii if you're touching customer data; log_decision when you make a non-trivial call so the audit trail captures it.

Your gotchas

For Compliance Officers Compliance#

Your workflow per project

1. Open the project's Compliance tab. Two artifacts: the EU AI Act checklist (23 items) and the Model Card (intent, training data, evaluation, limitations, mitigations).
2. Classify risk. minimal · limited · high · unacceptable. The classification drives which fields are mandatory.
3. Complete the checklist. Each item supports comments. Save as you go; the percentage indicator on the dashboard updates live.
4. For high-risk systems, complete the model card. The model card moves through the same draft/in_review/approved flow as a PRD.
5. Export the audit pack. The Compliance page has a one-click "Export audit report" that produces a markdown bundle: AI Act checklist, model card, every approval, every reviewer, every version with timestamps. Hand it to the regulator.

Your gotchas

Dashboard#

Where: / · Who: everyone with project scope.

Cross-project rollup. Active projects, LLM cost with call count, average PRD/architecture cycle time, projects awaiting review, compliance status. Clicking any tile drills into the source page. Admins additionally see an LLM Cost ⚠ variant when usage rows exist that aren't tied to any project.

Projects index#

Where: /projects · Who: PMs and above.

List of all projects in your scope. Filter by client, BU, phase. Each row shows latest PRD version, latest architecture version, sprint count, current phase. New Project takes you to the pipeline builder.

Project workbench#

Where: /projects/[id] · Who: anyone scoped to the project.

The core page. Six tabs: Overview · Documents · Planning · Team Activity · Members & SDK · Compliance. Sticky project header with name, client, phase badge, stack chip, and inline editing on the project name. Overview is the summary with the What's Next? panel; Documents is where all context enters the project (see Documents & indexing — the old Integrations tab folded into it); Planning holds the artifact sections — Requirements, PRD, Architecture, DevOps Methodology, Infrastructure Plan, Epics & Stories, Sprints, Traceability — as collapsible cards; Team Activity is the pipeline tracker plus the live dev board and dependency graph; Members & SDK bundles the member roster and the SDK download, gated by membership.

Documents & indexing#

Where: project page → Documents tab · Who: anyone scoped to the project (uploads need edit permission).

The single entry point for project context, in five blocks:

• Documents. Drag-drop or + Add: ZIPs, markdown, PDF, DOCX (single-file cap 100 MB). Each row shows a kind badge, size, a live status pill, a Reindex link, and a remove action.
• Agent outputs. Read-only: the PRD, architecture, stories and other agent artifacts are mirrored into the index automatically, so agents can search their own prior work.
• Repositories. Link existing GitHub repos by URL or create new ones (see GitHub integration); linked repos are cloned and indexed like uploads.
• RAG status. Rollup tiles: embeddings (per model), uploads indexed x/y, repos indexed x/y.
• Filter rules. Platform-wide ignore rules (read-only) plus per-project overrides in gitignore syntax.

The status pill is the contract. A document walks ⏳ Queued → live stages (Unzipping, Scanning files, Chunking, Embedding…) → ✓ Ready, or ⚠ indexed (N failed) / ✗ failed (hover for the error). Under each run: file/chunk/embedding/token counters and a durable "12 files · 318 chunks · indexed <date>" summary. Until everything is Ready, every agent-launch button on the Planning tab carries the amber ⚠ warning — generate anyway and the agent simply may not see the un-indexed material.

PRD section#

Three tabs once a PRD exists: Document · Conversation (the read-only record of the exchanges that shaped each version) · Governance. Document import dropzone for client-supplied drafts (PDF, DOCX, TXT, Markdown — max 20 MB). Per-section editing creates new versions.

Four ways to change a PRD, smallest hammer first:

• Inline edit a section by hand — new version, done.
• ✦ Edit with AI on any section heading — describe the change, Clara rewrites that section, you Accept or Discard the diff.
• ✦ Propose a change at document level — a conversational flow that identifies the affected sections and rewrites only those. If the system can't determine which sections a request touches, it stops and asks you to rephrase — it never falls back to regenerating everything.
• ↻ Restart discovery with Clara — the full interview again, publishing a new version on the same artifact: history, downstream links and epics are kept, and epics affected by the new content get flagged for review rather than orphaned.

Pending AI edits show ✦ AI edits pending — save to publish a new version. Export as .docx / .pdf / .md from the document header.

Architecture section#

Same shape as PRD, but driven by Tomás. Adds a Decisions view (architecture decisions as cards with their PRD-section traceability) and a Coverage view that flags PRD sections without an architectural answer. Blocked until the PRD is approved.

The same editing ladder as the PRD applies: per-section ✦ Edit with AI, document-level ✦ Propose a change, and full regeneration. Tomás's guided discovery is persisted server-side — abandon it at step 7 of 10 and the section offers Resume / Discard on your return. Interrupted generations offer Resume generation / Regenerate failed sections; saving an approved architecture warns exactly which epics and sprints it will reset.

Requirements#

Where: Planning tab, above the PRD · Who: adopt needs project.edit; proposing changes needs prd.edit.

Opt-in per project. On a classic project the card offers Adopt the requirements model: it extracts a requirement baseline from the PRD — each requirement with a stable key, kind, and rationale — and links your stories to it.

Once adopted, change management inverts. You type a change request ("auth must support SAML, not just OAuth"); Clara proposes requirement deltas — create / update / retire, each rendered as a word-level diff with Accept / Reject. Every accepted delta flags exactly the stories it affects; Propose updates (N) then asks Inês to draft story rewrites, each arriving as its own reviewable diff. A decision log records every accept/reject.

Epics & Stories#

Driven by Inês (+ Generate Work Breakdown; later, + Extend Work Breakdown for new requirements when an approved PRD outruns the existing epics). Click into a story to see acceptance criteria, complexity, dependencies, traceability links, and (when claimed) the dev who has it and any linked PR. Per-epic Generate stories re-runs Inês on a single epic. Export the whole work breakdown — epics plus sprint plan — as .docx / .pdf / .md; individual stories export the same three ways.

Story lifecycle & dependencies

Stories move through backlog → ready → in_progress → review → done (plus blocked). Dependencies are authored by Inês during generation and reconciled in a cross-epic pass afterwards ("✓ Cross-story dependencies reconciled — N of M stories updated", with a viewable before/after per story). Each card carries two chips: a deps chip (green when all met; amber "waiting"; red when a dependency is itself blocked) and a reverse chip (prereq for N / enables N / blocks N).

Dependencies gate status — everywhere. While any dependency isn't done, the story can only sit in backlog; the portal select disables every other option ("Blocked — finish first: …") and the SDK refuses with the same rule. When the last dependency lands, waiting stories are promoted to ready automatically; if an upstream story reopens, its dependents drop back to backlog. Claiming happens through the SDK (claim_story) — there is no claim button in the portal. Someone else's claimed story can only be touched by holders of stories.override, which also frees the claim.

Editing & destructive actions

✦ Ask Inês to edit this story (on the expanded card) takes a plain-language instruction and returns a whole-story rewrite as a diff — Accept, Try again, or Discard. Deleting a story or epic, and ↻ redo stories on an epic, all warn precisely what goes (dependency links, trace links, reviews) and are refused while any affected story has dev activity — a linked PR, a started status, or recorded git events. There is no undo; the pre-flight blocker check is the safety net.

Sprints & release planning#

Driven by Hugo (Release Planner — reframed May 2026). Hugo no longer plays Scrum Master. In an agentic platform where developers claim stories autonomously through MCP, "the Scrum Master assigns N stories to sprint 1" doesn't match how work flows. Hugo produces a multi-sprint release plan: capacity verdict ("at this team, this velocity, here's how many sprints to land scope"), dependency-aware sequencing, migration risk pull-forward (when the project has a functional spec, capabilities marked redesign or with missing externals become early-sprint constraints), milestone callouts (cutover, parallel-run start, MVP), and open questions to resolve. Sprint windows become calendar frames; the story-to-developer assignment happens at MCP claim time. The UI labels the action "Plan Release with Hugo" and lists sprints as forecast buckets — what actually completed in a window may diverge from what Hugo forecast, and that's expected. Cross-project sprints view at /sprints for portfolio-level planning.

Below the work breakdown, the Cost estimate card splits money into two honest halves: Upstream (actual) — what the platform's agents have really spent on this project, per agent and model — and Downstream · dev-controlled forecast — a token-based range for implementation, calibrated from past projects when enough history exists (badge: Calibrated from past projects vs Rough estimate (no history yet)), re-priceable against any active model.

DevOps Methodology#

Driven by Gaspar (DevOps Methodology Engineer) · Where: Planning tab, after Architecture · Gate: the architecture must be approved first · Permissions: devops.generate/edit/review.

Gaspar decides how the project ships: an 11-step interview (mode: Generate, Adopt & Audit when existing pipeline files are in context, or Document-only) covering branching, quality gates, environments & promotion, definition of done, and DORA targets — then a sectioned, versioned document with live Mermaid diagrams, exportable as .docx/.pdf/.md, and the same draft → in_review → approved governance as a PRD.

The Configuration tab is the point. "The document describes; this config governs." It holds the Proportionality Tier (0/1/2), derived from real signals — story count and complexity, team size, sprints, brownfield health, whether the pipeline has a compliance step — with a raise-only override that demands a written reason; the compliance flag (regulated / non-regulated — emission stays blocked while unconfirmed); the Quality Gates table (Build & smoke, Lint, Coverage, SAST, DAST, secret/container/IaC scans, SBOM…), where gates required by the tier are locked on; branching rules; environments & promotion edges with the CI/CD platform; DoD; and DORA targets. Every config change mints a new version and resets review status.

If the project later grows past its tier — more stories, a compliance step added — a banner warns that live signals demand a higher tier and asks for regeneration. Note: emitting an actual CI pipeline to the repo (devops.emit) is scaffolded but not yet available in this release; the methodology is the governed source of truth humans and tooling read.

Infrastructure Plan#

Driven by Íris (Infrastructure & Delivery Engineer) · Where: Planning tab, after DevOps Methodology · Gate: none — but see below · Permissions: infra.generate/edit/review; infra.deploy is reserved to admins and BU leads (and is scaffold-only in this release).

Íris decides where the project lands: a 6-step interview (cloud, accounts/subscriptions, compute shape, registry, secrets locations, OIDC identity, named approvers per gated environment) producing a versioned plan — Cloud Topology, Identity & OIDC Federation, Registry & Artifacts, Per-Environment Resources, Secrets & Configuration, and a Deployment Runbook — with Mermaid diagrams for the topology and trust chain. The Configuration tab makes provider, compute, registry, OIDC identity, secrets location and per-environment resources editable, validated on save.

Governance coupling: when an approved DevOps methodology exists, its environment list is law — Íris consumes it verbatim, and if the two ever drift, infra config saves are rejected until the plan is regenerated (the methodology's Governance tab warns reviewers before an approval will cause that). Without a methodology, Íris runs standalone with self-declared environments, clearly labelled ungoverned. Íris is in no preset — add the step deliberately.

Team Activity#

Where: project page → Team Activity tab (also standalone at /projects/[id]/team-activity).

Three things live here:

• The pipeline tracker — one card per pipeline step with live artifact status, the Run this step with agent selector, and the fork actions (Customise with Maestro / Editor / History / Resync / Remove). This is where the project's agent lineup is managed.
• The live board — auto-refreshing every 15s: Active right now, In review (with PR numbers), Blocked, Ready, unassigned, Orphan branches, Hotfixes.
• The dependency graph — every story as a node coloured by status, arrows from prerequisite to dependent. The picture that explains why nothing is moving.

Developers also get a personal cut at /projects/[id]/my-work: Yours (N) and Ready & unblocked (N).

System Assessment#

Driven by Diogo. Three artifacts: assessment narrative, findings table (category · severity · evidence · remediation · effort), and a system component map. Source: connected GitHub repo or uploaded ZIP. Diogo's prompt enforces an Evidence Discipline — he distinguishes observed source content (which he can quote) from observed metadata (which he cannot infer schemas from), and he calibrates confidence accordingly. The full technical assessment renders as a collapsible card; click the header to fold it once you're past the assessment phase. Export as .docx, .pdf, or .md from the assessment header.

Functional Specification (Modernization)#

Driven by Mateus. The artifact that turns "we have a legacy codebase" into "we have a modernization PRD". Mateus reads the uploaded source — COBOL, RPG, .NET Framework, classic ASP, old Java, anything — and extracts the system's actual behavior: capabilities (what the system does), business rules (validations and constraints, quoted from source where possible), data entities (what each table/file represents and how it's used), external dependencies (programs CALLed but not present in the upload), and per-capability migration verdicts (carry_forward / redesign / drop / replace_with_external) with rationale. Each finding cites a specific file path; confidence is calibrated by what's actually in his context. Versioned per project, exportable as .docx / .pdf / .md. Where Diogo measures the system's health, Mateus reconstructs its behavior — different concerns, often run together.

Compliance#

Where: /compliance + per-project tab. EU AI Act checklist (23 items, risk classification), model cards (versioned), PII scan results from the SDK. Victor (Compliance Auditor) reads the project's PRD, architecture, and model card and produces a versioned audit report with per-item verdicts (pass / fail / insufficient evidence), citations for every claim, recommended risk classification, and remediation. The audit is substantive, not procedural — Victor refuses to mark anything as "pass" without naming the artifact and section that supports the verdict. Export each audit version as .docx, .pdf, or .md from its card header.

Design Review#

Driven by Helena (Design Authority). Reads PRD and architecture together and pushes back on incoherence — internal contradictions, scale mismatch, scope drift, undecided central risks, stack-fit gaps, NFR-to-FR coverage holes. She names problems, not solutions. Versioned per project, with verdicts (pass / weak / fail / undecided) and citations. Helena is intentionally separate from Victor: compliance is about regulatory posture, design review is about whether the artifacts the team is about to commit to actually hold together.

Clients & Business Units#

Where: /clients · /business-units. CRUD for tenants. Each client carries custom standards, LLM restriction, PII mode, and a BU assignment. Projects under that client inherit all four.

Agent Studio#

Where: /agents (sidebar label: Agents; page title: Agent Studio). List of all agents with system prompt, context sources, model preference, and client/project availability. Fork to create client-specific overrides. Personality themes (e.g. Simpsons) live alongside.

Two ways to make an agent. + New Agent opens the editor with a Maestro | Editor mode switch. Maestro is a conversation: a 6-step interview (purpose, output, context, behaviour, constraints, preview) after which he drafts the full definition into a live Agent Preview pane — name, slug, output tag, context sources, model preference, system prompt — with validation errors that block save and warnings that don't. Switch to Editor pre-fills the classic form from his draft. The Editor is the same object typed by hand.

Classification matters. Every agent needs a pipeline step to be selectable anywhere — the Editor enforces it; Maestro-built agents can land unclassified and wear an amber unclassified badge until an admin classifies them. Availability is separate: Available to (a client, or all) and Available in projects decide where the agent is offered; the per-project choice still happens on the pipeline card's Run this step with.

Pipeline builder#

Where: /projects/new. Visual drag-and-drop. Six presets plus Custom, joined by your saved flows (★ chips, scoped Global or This client only). Drag agents from the palette, drop into the pipeline lane, reorder, remove; then ★ Save this pipeline as a reusable flow if the shape is worth keeping. Hover any card for a tooltip with the agent's role, output, and prerequisites.

Tokens & SDK#

Where: /sdk (sidebar: SDK Packages) for the admin token list (health: active/stale/revoked/expired, last heartbeat) and per-project downloads, with a filter box for finding projects by name or client. SDK download also lives on the project page's Members & SDK tab; both are gated by project membership.

The download is a live build. The Configure SDK Package modal asks for OS (Linux / Windows) and IDE (Cursor, VS Code Copilot, Claude Code, All IDEs), then the button walks Checking cache… → Building binary… → Starting download… — a cold compile is visible, not a hung button. The result is a single atos[.exe] per project. No agent definitions, knowledge files or system prompts are bundled; the MCP server fetches those from the portal at runtime.

Install (--install): run from the project root. Writes the IDE config files (.cursor/mcp.json, .vscode/mcp.json, CLAUDE.md, agent files) plus the GitHub Actions link workflow, appends an Atos-tagged section to .gitignore, self-copies into tools/mcp-server/atos[.exe] — and then runs the auth flow automatically.

Per-member auth (--auth): the binary opens /cli/authorize in the developer's browser and waits for the callback. The portal verifies the signed-in user is a member of the project and issues a one-time code; the CLI exchanges it for an atk_… token bound to (project, user) and persists it at ~/.atos/tokens/<projectId> (Windows: %APPDATA%\atos\tokens\<projectId>) — per-project files, so installing a second project no longer clobbers the first. Tokens are never embedded in IDE config files. A workspace/token project mismatch is refused with an explicit error naming the fix.

Per-call identity validation: every MCP tool call hits the backend to verify the token's user against the project's member list. A 60-second cache + 5-minute grace window absorb repeated tool calls and tolerate transient outages.

Verification (--doctor): a readiness grid — config present, env vars set, persisted token, dev identity, portal reachable + auth ok, encrypted agent cache, and the bundled CA (for deployments behind a private certificate authority). Exit 0 means the install actually works.

Revocation: removing a member from the project revokes all of their project tokens, drops them from the project's GitHub repos (where bound), and the next MCP tool call returns not_a_member.

Project members#

Where: project page Members & SDK tab. What: an explicit allowlist of who can install the SDK and act as a developer on the project. A member is a platform user (create them at /users first) plus an optional selection of their linked GitHub accounts.

+ Add member opens a user picker; picking someone reveals GitHub accounts to include — one checkbox per account the user has linked on their profile, each tagged with its provenance (oauth / pat-only / backfill). A member with no GitHub account is fine ("Member will be added without a GitHub-side collaborator grant"), they just can't exercise GitHub-side credentials. Removal revokes the member's project tokens and drops their repo collaborator grants.

Why this matters: every tool call is attributed to a specific portal user, and an admin can yank one person's access without rotating anyone else's tokens.

GitHub integration#

Repo binding is explicit and per-project now — no more auto-created repo on every project. On the Documents tab's Repositories block, a project holds any number of repos, added two ways:

• Link existing — paste a repo URL. The platform test-fetches it through your credentials before saving. Works without any server-side GitHub configuration.
• Create new — creates <client-slug>-<name> via the platform's GitHub App installation. Disabled (with an explanatory tooltip) when the deployment has no App credentials.

Whose credentials are used, in order: (1) your personal PATs, (2) your OAuth token — both only if your GitHub account is ticked on your project membership row — then (3) the platform's GitHub App installation as fallback. Two structured errors coach the fix: "No credential covers {owner}" → add a PAT on your profile; "Your GitHub identity is not bound to this project" → tick your account on Members & SDK.

Personal credentials live on /profile → Linked GitHub accounts: link via OAuth or paste a Personal Access Token (encrypted at rest; scope repo or a fine-grained equivalent with Contents: Read). Each account shows its provenance (OAuth / PAT only / backfill) with re-link, verify, unlink and delete actions.

Admin side — Settings → GitHub (permission platform.settings.github): the GitHub App credentials (from env, with an in-memory session override for debugging — never paste production keys there), a Test now probe, and a read-only API playground (whoami, list repos, PRs, check runs) for diagnosing integration issues with live credentials.

Users & sign-in#

Where: /users (admin) · /profile (everyone) · Settings → Auth (admin).

Sign-in is deployment-shaped. Three modes, chosen at deploy time: Clerk-mode (password + MFA + invitations, plus SAML SSO), SAML-only (SSO buttons only — Clerk is fully optional now), and gateway mode (an upstream OIDC gateway, e.g. Keycloak, signs users in before the portal). The sign-in page renders one "Sign in with {IdP}" button per configured identity provider; in Clerk-mode an email/password form sits below them.

Users admin. + New User creates the account (email, name, role) — in Clerk-mode you choose whether to send an invitation email; in SAML-only the account simply activates on first SSO sign-in. Each row shows linked sign-in identities, invitation state (pending login / expires in N days / expired, with resend), role, status, and scopes. Admins can Link / create Clerk login per user or run the bulk Sync Clerk logins; unlinking an identity is self-service on the user's own profile, guarded against locking yourself out.

Profile. Sign-in methods with last-used timestamps and unlink; Email preferences — let the IdP manage your email (the field locks with a "Managed by …" badge); and Linked GitHub accounts (see GitHub integration).

Settings → Auth is the admin surface: the active mode badge, SP metadata / ACS URLs to hand to the IdP admin, identity providers (metadata URL or manual cert, per-IdP display name that becomes the button label), SAML options, state maintenance, and an SSO event feed for debugging denied logins.

Search & theme#

Search: ⌘K / Ctrl+K anywhere (or the header search box) opens the command palette. It finds Projects, Clients, Epics, Stories, Agents — typo-tolerant, scoped to what you can see — and deep-links straight to the hit (a story lands on its project's Planning tab with the story focused). Arrow keys + Enter to navigate.

Theme: the sun/moon toggle in the header switches between the dark theme and the Atos-brand light theme. Per-browser, persistent, defaults to dark.

Team & capacity#

Where: /team. Team roster with capacity hours per week. Project-team assignments roll up to overload warnings. Hugo uses these numbers when proposing sprints.

Telemetry#

Where: /telemetry. Per-agent and per-model cost breakdown with progress bars and token counts. Project-level filter. The page where you justify (or rebut) the LLM bill. Costs are priced by the per-model rates the admin sets in Settings → Catalogue; each project page also shows its own LLM Cost stat and the Cost estimate card's upstream/downstream split.

Roles editor#

Where: /roles. Permission matrix UI grouped by category (Platform · Client · Project · PRD · Architecture · Epics & Stories · Pipeline · Documents · Compliance). Fork roles, edit permissions, save. System roles are editable in their permission set but cannot be deleted.

Settings#

Where: /settings (admins only). Ten tabs:

• Catalogue — LLM + embedding endpoints and models, per-model pricing, the three defaults (LLM, code-chunk embedding, doc-chunk embedding), model discovery per endpoint. Presets cover Anthropic, OpenAI, Azure OpenAI, Gemini, Voyage, self-hosted OpenAI-compatible (Ollama/vLLM/NIM…), and a dev-only mock.
• Limits — LLM spend and rate controls: platform-default monthly coin budgets and requests-per-minute, per-tenant overrides with the effective value and its source shown per row, the billing policy, and the treatment of tenantless calls.
• Agent Themes — personality skins.
• Knowledge — the global markdown bundle served to every developer's IDE; drag-drop .md upload with slug review, or re-import from disk.
• Maintenance — Reload Default Agents / Agent Themes / Everything from the on-disk definitions; forks and client agents are preserved.
• SDK Builds — the shared binary build cache (one row per OS/version/CA identity) with cancel, invalidate, prune, delete.
• GitHub — App credentials, test probe, API playground.
• RAG — platform-wide indexing filter rules and embedding behaviour.
• Auth — identity providers, SP metadata, SAML options and events.
• Developer — gated diagnostics: a live server log viewer (filter, copy, download), CSP reports, and — only when the deployment explicitly enables it — a raw SQL console that warns, accurately, "Runs any SQL — writes and DDL included — and commits. No safety net."

Recipe · Ship a greenfield project#

Personas: PM (Jose), Architect, Reviewer (Ana), Developer.

1. BU Lead creates the client (if it doesn't exist) and assigns it to the BU.
2. PM creates the project at /projects/new, picks Full Project preset, sets stack and team size, mode = greenfield.
3. PM uploads any client-supplied context (decks, transcripts, briefs) to the project's Documents tab and waits until every document shows ✓ Ready — the agents can only ground on what's indexed.
4. PM works through Clara's 12 steps, saves the PRD, submits for review.
5. Reviewer diffs against draft (none — this is v1), runs AI cross-model review, adds a formal review with decision approved.
6. Architect opens Tomás, walks the 10 steps, saves architecture, submits for review.
7. Reviewer approves the architecture.
8. Gaspar governs the DevOps methodology (the Full Project preset includes the step): interview, generate, review, approve. Add Íris's Infrastructure Plan if this project needs a landing zone decision.
9. PM opens Inês, generates the work breakdown; the cross-story dependency reconcile pass runs automatically.
10. PM opens Hugo, plans the release.
11. PM adds the developers on Members & SDK, ticking their GitHub accounts.
12. Developer downloads the SDK binary from Members & SDK, runs ./atos --install (auth happens in the browser automatically), verifies with --doctor.
13. Developer runs get_my_queue, claims a ready story via claim_story, codes, opens a PR, links it.
14. Cycle continues. Telemetry surfaces in real time on the dashboard.

Recipe · Modernise a legacy system#

1. PM creates the project with mode = brownfield, pipeline preset = Modernization. Names the target stack (e.g. "Java/Spring Boot + Next.js"). Adds Compliance Audit and Design Review to the pipeline if the system is regulator-facing.
2. Architect uploads the legacy codebase on the Functional Specification tab — connect the GitHub repo or upload a ZIP. The scanner samples representative source per detected language and extracts text from any PDF/DOCX functional specs in the upload.
3. Architect runs Mateus. The 6-step extraction produces a versioned functional spec: capabilities (with confidence + verdict), business rules (with quoted source), data entities, external dependencies (flagged when not present in the upload), and unresolved questions naming what Mateus could not extract from the available source. Iterate: if unresolved_questions point at missing copybooks, master DDL, or specs that didn't extract — upload them and re-run. The next pass usually moves several capabilities from "inferred" to "verified".
4. Optional: Architect runs Diogo in parallel for the system-state lens (test coverage, observability gaps, dependency risks). Mateus and Diogo can both be in the pipeline; they cover different concerns.
5. PM runs Clara. With a functional spec in context she writes a modernization PRD, not a greenfield one — verdicts map to FRs / Out of Scope / External Integrations, missing externals become a "Legacy Dependencies to Replace" section, unresolved questions become her Open Questions block.
6. Architect runs Tomás. With a functional spec in context he produces a migration architecture: target shape (the destination state) and cutover shape (strangler / parallel run / anti-corruption layer / dual-write window). Cutover plan, audit-trail continuity, regulatory carry-forward, rollback, and parallel-run window are part of the architecture.
7. Optional review gates: Helena reads PRD + architecture together and flags incoherence (scale mismatch, scope drift, undecided risks); Victor audits against the EU AI Act if the system handles AI decisions or PII at scale.
8. Inês decomposes the modernization PRD into epics and stories with explicit dependencies on the cutover shape. Hugo risk-sequences so the highest-risk migrations land first (data, audit continuity, missing externals).
9. From here, the flow matches greenfield: review gates, SDK provisioning, story claiming.

Recipe · Onboard a new client#

1. Admin or BU Lead opens /clients/new.
2. Set name, BU assignment, custom standards (paste markdown), LLM restriction (default: EU-only), PII mode (default: warn).
3. Save. The client now exists with zero projects.
4. Add team members and assign their scope to this client.
5. Create the first project under the client.

Recipe · Rotate an SDK token#

Since the May 2026 wave, SDK tokens are per-member and minted by the developer's own atos --auth flow. Rotation is normally driven by the developer, not the admin. The admin path below revokes existing tokens; the developer path mints a fresh one.

1. Admin (revoke): opens the SDK Packages page (/sdk), finds the token, clicks Revoke. Per-call MCP identity validation will start returning token rejected within 60 seconds (the client-side cache TTL).
2. Developer (mint a new one): from the project root, run ./tools/mcp-server/atos --auth --project-id=<uuid>. The default browser opens /cli/authorize; click Authorize. The CLI completes the exchange and overwrites ~/.atos/tokens/<projectId> (or %APPDATA%\atos\tokens\<projectId> on Windows). No IDE restart needed — the next tool call picks up the new token automatically.
3. Verify: run ./tools/mcp-server/atos --doctor. The Identity validation block at the bottom should read Authenticated as <github-username>. If it doesn't, the doctor output names the failing check.

Recipe · Run a compliance review#

1. Compliance Officer opens the project's Compliance tab.
2. Pick risk classification. For high-risk, the model card becomes mandatory.
3. Walk the 23-item AI Act checklist. Add comments per item. Save.
4. Complete the model card if required. Submit for review.
5. Reviewer approves.
6. Click Export audit report. A markdown bundle downloads with the checklist, model card, every artifact approval, every reviewer name, and every version timestamp.

Recipe · Govern delivery (Gaspar → Íris)#

Scenario: architecture approved; the project needs its CI/CD rules and a cloud landing zone before developers start.

1. Confirm the pipeline has the DevOps Methodology step (Full Project preset includes it); drag in Infrastructure Plan from the pipeline builder or add it from What's Next? — it's in no preset.
2. Open + Create DevOps Methodology with Gaspar. Walk the 11-step interview; if the repo already has pipeline files in context, Gaspar switches to Adopt & Audit and produces a gap analysis.
3. Generate. Check the Configuration tab: the derived proportionality tier and its signals, the quality-gate table (tier-required gates are locked on), environments & promotion. Raise the tier with a written reason if the client demands more rigour — it can't be lowered below the derived floor.
4. Resolve the compliance flag (regulated / non-regulated with a note) — it blocks emission while unconfirmed.
5. Submit for review; the reviewer approves in the Governance tab. From approval on, the methodology's environment list is law.
6. Open + Plan Infrastructure with Íris. She consumes the approved environments verbatim and interviews you for cloud, accounts, compute, registry, identity and secrets locations (never values), plus named approvers per gated environment.
7. Generate, review the topology and OIDC diagrams, adjust the Configuration tab, submit, approve.
8. If either artifact is later edited into disagreement, the drift gate rejects infra config saves until the plan is regenerated with Íris — the warning tells you exactly which environments diverged.

Recipe · Recover from a PRD rework#

Scenario: PRD v1 was approved. Client comes back with a scope change to section 4.

1. PM opens the PRD section, edits section 4. The system warns: "this will reset the architecture to draft and cascade to 3 stories." PM confirms.
2. PRD becomes v2, status draft. Architecture status flips to draft. Affected stories show an upstream-changed banner.
3. PM submits PRD v2 for review. Reviewer compares v1 vs v2 in the diff view, approves.
4. Architect opens Tomás with the context "PRD section 4 changed from X to Y; review affected decisions." Tomás proposes revised decisions. Architect saves new architecture version, submits.
5. Reviewer approves. Affected stories' upstream banner clears once the architecture is re-approved.
6. If any stories are now invalid, PM regenerates them with Inês on a per-epic basis — or, better, uses the Cascade Helper's per-story proposals.

Permission matrix#

The default permission assignment per system role. Custom roles can mix and match any subset.

Always treat this table as the shipped default. The live source of truth is the database — Admins can override any permission per role at /roles.

Agent glossary#

Status & cascade rules#

• draft → in_review: via Submit for Review. Logged.
• in_review → approved: only via formal review with decision approved.
• in_review → draft: via Send back to draft (requires reason).
• approved / in_review → draft: automatic on content edit. Cascades downstream.

Cascade chain: PRD → Architecture → Epics & Stories → Sprints. Each downstream artifact resets to draft when its upstream is edited; banners appear; nothing is lost. DevOps methodologies and infrastructure plans follow the same three-state review flow; the infra plan is additionally gated by the approved methodology's environment list (the drift rule).

Story lane (separate from the review flow): backlog → ready → in_progress → review → done, plus blocked. Transitions are dependency-gated: a story whose dependencies aren't all done can only sit in backlog; completions auto-promote waiting stories to ready; reopening an upstream story drops its dependents back to backlog. Moving a story back to backlog/ready releases its claim.

Glossary#

FAQ#

Why can't I just set status to approved?

Because the audit trail must always have a review record behind every approval. Allowing direct status edits would break that. Add a formal review with decision approved instead.

What happens to old versions when I edit?

Nothing — they stay. Every save is a new row. You can diff any two versions and see exactly what changed.

Can I undo a cascade?

Not as one action. The cascade reset itself is logged, so you can see what changed and restore from a prior version diff. In practice: re-approve the upstream after your edit, then walk the downstream artifacts and re-approve each one.

Why doesn't editing a PRD re-run Tomás?

Because the system can't know whether your edit invalidates the architecture. The cascade resets the status and shows the banner; the human decides whether to reopen Tomás.

Can two devs claim the same story?

No. story_actions(action: "claim") rejects if the story is already claimed.

Where do agent prompts live?

In the database, seeded from YAML definitions on disk (frontend/agent-defs/agents/). The Agent Studio is the canonical edit surface; Settings → Maintenance → Reload Default Agents re-seeds the stock personas from disk without touching forks.

Why is my story stuck in backlog?

Its dependencies aren't all done. Hover the disabled status select — it names the stories to finish first — or open the dependency graph on Team Activity. When the last prerequisite lands, the story promotes to ready by itself.

Why doesn't Clara know what's in my document?

Either it isn't indexed yet (check the status pill on the Documents tab — only ✓ Ready counts) or it never made it through the pipeline (✗ failed, hover for the error). Agents ground on the index, not on the raw upload.

I closed the browser during a generation. Did I lose it?

No. Generations and chat turns run server-side. Reopen the section: a running generation reattaches with live progress (including runs a colleague started), a failed one offers Resume generation, and finished work is simply there.

What's the cheapest way to onboard a new BU?

Create the BU. Create one Admin user with that BU as scope, plus permission to create clients and projects. Let them seed their own clients and team. Two minutes of setup.

Troubleshooting#