---
title: Output Directory Structure
description: >-
  Describes the reports/ and work/ directory structure used by NexusArchitect,
  and the role of every folder and file in detail
seo:
  image: /ogp.png
---
NexusArchitect uses the following directory structure (created by `init-output`-family Skills if it does not already exist).

<FileTree>
- reports/ Product-planning, design, and review deliverables
- work/ Progress, traceability, and cost records
- generated/ Actually-runnable code
- design-system/ The design system
</FileTree>

`reports/` is the single source of truth, while `work/` is a set of files that record the pipeline's state. `generated/` (frontend/backend/infrastructure code) and `design-system/` (tokens and the component inventory) are managed separately from `reports/`.

<Panel title="What's inside reports/ depends on where you started">
NexusArchitect has three entry points that write to `reports/`. **The same-numbered folder can mean something different depending on which entry point you used** — keep that in mind before anything else.

1. **Starting from `/product:start` (most common)** — the `product` pipeline, which plans everything from Vision through Architecture. Uses `reports/00_core/` through `reports/05_adaptation/` and `reports/report/`. Most projects then hand off to `reports/backlog/` via `export-backlog`.
2. **Using `architect` directly as the entry point for new development (greenfield path)** — a path that goes from requirements definition to architecture design and implementation specs without going through product planning. Uses `reports/00_requirements/`, `reports/03_design/`, `reports/06_implementation/`, and others.
3. **Using `architect` directly as the entry point for modifying an existing system (legacy path)** — a path that re-investigates and re-evaluates existing code. Uses `reports/before/`, `reports/01_analysis/`, `reports/02_evaluation/`, and others.

This page follows that order: [1] the product entry point → the shared `backlog/` and `work/` → [2][3] the standalone architect entry points.
</Panel>

<Panel title="Reading reports/ in a browser">
`tools/docs-site.sh` turns `reports/` into a local, searchable documentation site with [Blume](https://useblume.dev), as-is. One page per report, with Mermaid diagrams rendered and OpenAPI/AsyncAPI specs served as an API reference; `full-report.html` is served as-is. It never modifies `reports/` itself, and has `sync`/`dev`/`build`/`preview`/`validate`/`clean` subcommands.
</Panel>

## 1. Output of the product pipeline (`reports/00_core/` through `reports/report/`)

These are the numbered folders created by `/product:start`. The folder numbers directly represent phase order.

<FileTree>
- reports/
  - 00_core/ Vision, Scope, Success Metrics, Revenue Model, Assumptions
  - 01_ux/ Persona, Journey, Positioning, Domain Stories
  - 02_spec/ UI Mocks, Feature List, Data Model
  - 03_domain/ Bounded Contexts, API Design, Architecture, Tech Fitness
  - 04_quality/ SLA, NFR
  - 05_adaptation/ Output from adapt-change (on demand)
  - report/ Consolidated HTML report, review results
</FileTree>

### `00_core/` — Business direction

| File | Skill that writes it | Contents |
|---|---|---|
| `vision-mission-value.md` | `define-vision` | A diagram summarizing Vision/Mission/Value (Vision Board) |
| `pr-faq.md` | `define-vision` | A PR-FAQ in the Amazon Working Backwards format (a hypothetical press release plus Q&A) |
| `success-metrics.md` | `define-success-metrics` | The North Star Metric, 3–5 input metrics that support it, and guardrail metrics |
| `market-landscape.md` | `research-landscape` (optional) | TAM/SAM/SOM, a competitive matrix, Kano classification, PoD/PoP strategy |
| `revenue-model.md` | `design-revenue` | Lean Canvas, the revenue model |
| `benefit-evaluation.md` | `design-revenue` | A recomputable unit-economics template (LTV/CAC, etc.) |
| `constraints.md` | `define-scope` | Classified constraints |
| `scope-definition.md` | `define-scope` | Scope definition via MoSCoW and RICE scoring |
| `product-name.md` | `name-product` (optional) | Acronym product-name candidates and the rationale derived from the Vision's own vocabulary |
| `assumptions.md` | `validate-assumptions` (validation gate) | A list of hypotheses ordered by how damaging it would be if each one turned out false |
| `validation-plan.md` | `validate-assumptions` (validation gate) | How to test each hypothesis, its kill threshold, and the Go/No-Go verdict |

`validate-assumptions`, which writes `assumptions.md` and `validation-plan.md`, is the [validation gate](/concepts/validation-gate) itself. The verdict is also recorded in `gates` inside `work/pipeline-progress.json`.

### `01_ux/` — Who uses it, and how

| File | Skill that writes it | Contents |
|---|---|---|
| `personas.md` | `generate-persona` | JTBD personas, proto-personas |
| `journey-maps.md` | `map-journey` | A stage × layer journey map, Moments of Truth |
| `positioning.md` | `design-positioning` | The Dunford 5-component canvas, the Hook model, a touchpoint matrix |
| `domain-stories/domain-story-{slug}.md` | `create-domain-story` (optional) | Domain Storytelling. Becomes the skeleton of the screen flow that `generate-ui-mock` reads next |

### `02_spec/` — Implementation-grade specs

| File | Skill that writes it | Contents |
|---|---|---|
| `ui-mocks/` | `generate-ui-mock` | A set of self-contained, clickable HTML screens |
| `feature-list.md` | `define-features` | A feature list converting on-screen actions into Commands, plus MoSCoW and a User Story Map (journey × MoSCoW, a second view) |
| `data-model.md` | `define-data-model` | Entities extracted in two passes (explicit, then implicit via a CRUD matrix) |

The optional `generate-frontend` skill uses everything up to this point to generate a React/Storybook implementation into `generated/frontend/` (outside this folder).

### `03_domain/` — Domain decomposition and API design

| File | Skill that writes it | Contents |
|---|---|---|
| `domain-map.md` | `map-domains` | Core/Supporting/Generic subdomain classification |
| `bounded-contexts.md` | `map-domains` | Bounded context definitions and a context map |
| `ubiquitous-language.md` | `map-domains` | A bilingual domain-vocabulary table (later folded into `shared-context/` as well) |
| `api-design.md` | `design-api` | API design across three layers: System/Process/Experience |
| `architecture.md` | `design-architecture` (synthesis phase) | Runtime diagrams, the critical-path sequence, deployment diagrams |
| `tech-stack-fitness.md` | `design-architecture` (synthesis phase) | Technology fitness assessment for Kong/ScalarDB/ScalarDB Analytics/ScalarDB Saga/ScalarDL |

### `04_quality/` — Quality requirements

| File | Skill that writes it | Contents |
|---|---|---|
| `sla.md` | `design-sla` | SLI/SLO/SLA, error budgets, criticality tiers |
| `nfr.md` | `define-nfr` | Measurable NFRs derived from the SLOs |

### `05_adaptation/` — Reflecting change (on demand)

| File | Skill that writes it | Contents |
|---|---|---|
| `change-log.md` | `adapt-change` | A record of what changed and why |
| `impact-analysis.md` | `adapt-change` | An impact-scope analysis (which phases need to re-run) computed from `work/traceability.json` |

Unlike the other phases, `adapt-change` doesn't wait its turn — it runs on its own whenever a market shift or constraint change occurs.

### `report/` — Review and the consolidated report (Phase R)

| File | Skill that writes it | Contents |
|---|---|---|
| `review.md` | `review` (optional) | Review results across four lenses: Consistency/Traceability/Extensibility/Strategy |
| `full-report.html` | `report` (optional) | A self-contained consolidated HTML report that leads with "Key Assumptions & Validation Status" |

## 2. `reports/backlog/` — Output of backlog operations

This is the folder written by the four skills used most often in real projects — `export-backlog` → `implement-backlog` → `review-issue` → `merge-issue` ([Backlog Operations](/skills/backlog/export)). It can ingest the numbered `reports/` folders (product side) regardless of which entry point created them.

<FileTree>
- reports/
  - backlog/
    - backlog-plan.md A human-readable plan (pre-approval)
    - backlog-manifest.json The tree structure and impl.status a program reads
    - backlog-export-result.md The result of the Issues actually created
    - backlog-status.md A Markdown export of the dashboard (optional)
    - followup-queue.md A queue of not-yet-filed follow-up items
    - followup-result.md The result of Issues created from the queue
    - shared-context/ The shared knowledge pack loaded on every implementation
    - reviews/ Detailed record of each review round
    - impl-log/ Per-Issue implementation log
    - epic-review-\<epic\>.md Result of an Epic roll-up review
</FileTree>

| File / folder | Skill that writes it | Contents |
|---|---|---|
| `backlog-plan.md` | `export-backlog` | A human-readable plan showing the Epic/Sub-Epic/Issue hierarchy. No Issue is created until this is approved via `AskUserQuestion` |
| `backlog-manifest.json` | Created by `export-backlog`; updated by `implement-backlog` / `review-issue` / `merge-issue` / `capture-followup` | Each Epic/Sub-Epic/Issue's `impl.status` and the `remote.url` of created Issues. What [resume](/concepts/resume) reads |
| `backlog-export-result.md` | `export-backlog` | A list and result summary of the Issues actually created |
| `backlog-status.md` | `report-backlog-status --md` (optional) | A Markdown snapshot of the live dashboard |
| `followup-queue.md` | `capture-followup` | A queue of follow-up items not yet turned into Issues. Markdown, so a human can edit it directly |
| `followup-result.md` | `capture-followup --flush` | The result of Issues actually created from the queue |
| `reviews/review-<issue>-round<N>.md` | `review-issue` | A detailed record of the findings ([B]/[S]/[Q]) found in that review round |
| `impl-log/<issue>.md` | `implement-backlog` | A per-Issue implementation log — a mirror of progress comments and decisions |
| `epic-review-<epic>.md` | `implement-backlog --review-epic` | The result of a roll-up review of the whole Epic |

### `shared-context/` — The shared knowledge pack loaded on every implementation

This is the actual content of the [Shared-Context pack](/concepts/shared-context). `implement-backlog` builds it first and consults it on every implementation after that.

| File | Contents | Source |
|---|---|---|
| `architecture-guardrails.md` | Package boundaries, transaction boundaries, banned technology choices | `architecture.md`, `tech-stack-fitness.md` |
| `coding-standards.md` | Naming conventions, exception-handling patterns, test policy | Language/framework decisions |
| `ubiquitous-language.md` | A bilingual domain-vocabulary table | `ubiquitous-language.md` from both product and architect |
| `data-contracts.md` | Table definitions, aggregate boundaries, enum conversion rules | `data-model.md` |
| `nfr-budgets.md` | A quick reference for NFR/SLA targets | `nfr.md`, `sla.md` |
| `decisions.md` | An ADR-lite log of cross-cutting decisions (**append-only**) | Accumulated during implementation |
| `review-knowledge.md` | A distilled catalog of lessons found during review (**append-only**) | `review-issue`'s review rounds |

`decisions.md` and `review-knowledge.md` are append-only logs — unlike the other files, they are never rebuilt. `review-knowledge.md` in particular exists as **a mechanism to keep the same problem from being implemented twice** (see [the review-issue page](/skills/backlog/review) for real examples).

## 3. `work/` — Progress and state-management files

Where `reports/` holds "deliverables," `work/` holds a record of "how far things have gotten." Both the product and architect pipelines share the same files.

| File | Who writes it | Contents |
|---|---|---|
| `pipeline-progress.json` | `/product:start` and `/architect:init-output`, plus each phase | Each phase's status (`pending`/`in_progress`/`completed`/`failed`/`skipped`), the validation-gate verdict, and output locations. Phases from both product and architect land in this same file, distinguished by a `plugin` field |
| `traceability.json` | Each phase (**append-only**) | The full graph of traceability IDs — `VIS-`, `FEAT-`, `ENT-`, `CTX-`, `API-`, `NFR-`, `KN-`, and others. The source data `adapt-change` uses to compute impact scope |
| `context.md` | Each phase (**append-only**) | Notes on decisions carried across phases. Holds the "Open Questions" table shared by product and architect |
| `version-decisions.json` | `implement-backlog` and other skills that resolve dependency versions | A record of the real versions looked up in a registry, why they were chosen, and which versions were rejected (see [the implement-backlog page](/skills/backlog/implement)) |
| `token-usage.json` | The token-usage-recording hook | Aggregated cost per phase/model (USD, with input/output/cache-read/cache-write breakdown) |
| `token-usage.jsonl` | Same as above | An append-only audit log, one record per hook firing |
| `token-cost-debug.log` | `report-token-cost --debug` (optional) | Debug information from rendering the dashboard |

[Resume](/concepts/resume), the [live dashboard](/concepts/live-dashboard), and [thinking about token cost](/concepts/token-cost) all operate by reading files in this folder.

## 4. Outputs kept outside `reports/`

Generated "code" and "design system" artifacts are a different kind of thing from planning/design documents, so they live in their own folders outside `reports/` and are version-controlled separately.

| Folder | Skill that writes it | Contents |
|---|---|---|
| `generated/frontend/` | `generate-frontend` (product, optional) | A React + TypeScript + Vite + Storybook scaffold that runs as-is via `npm install && npm run dev` |
| `generated/{service}/` | `generate-scalardb-code` (architect) | Java source, a per-repository Fake implementation (`**/fakes/`), transaction-scenario integration tests, `build.gradle`, `Dockerfile`, `scalardb.properties` |
| `generated/infrastructure/{k8s,terraform,helm,ci}/` | `generate-infra-code` (architect) | Kubernetes manifests, Terraform modules, Helm values, CI workflows |
| `design-system/{name}/` | `design-system` (product, optional, run standalone) | `tokens.json` (DTCG), `tokens.css`, `components.md`, `guidelines.md`, `manifest.json`, `preview.html` |

<Panel title="Why keep these separate?">
`reports/` is "a record of decisions" — reference material meant to be read back later. `generated/` and `design-system/` are meant to actually run or be used. `design-system/` in particular is something you reuse across multiple products and version up and down, so it's managed independently rather than as part of the planning phase.
</Panel>

## 5. Output when using the architect pipeline standalone

When `architect` is used directly as the entry point, bypassing the product pipeline, it creates a different set of numbered folders. These correspond to the two paths described in [the Architect pipeline page](/skills/architect-pipeline) (greenfield / legacy).

:::warning[Folder numbers are independent per entry point]
For example, `reports/03_domain/` (from the product entry point) and `reports/03_design/` (from the standalone architect entry point) are both "the third folder," but they are different things. A single project normally uses only one entry point, so both are not expected to coexist in practice.
:::

**Greenfield path**

The path used when building a brand-new product from scratch.

| File | Skill that writes it | Contents |
|---|---|---|
| `reports/00_requirements/requirements-definition.md` | `define-requirements` | Requirements definition |
| `reports/00_requirements/data-transaction-requirements.md` | `define-requirements` | Data and transaction requirements |
| `reports/00_requirements/open-questions.md` | `define-requirements` | A rendered view of the Open Questions in `work/context.md` |
| `reports/00_requirements/scalardb-applicability.md` | `define-requirements` (only when ScalarDB is used) | Whether ScalarDB applies |
| `reports/03_design/domain-analysis.md` | `map-domains` | Domain analysis |
| `reports/03_design/api-style-decisions.md` / `.json` | `design-api` | API style decisions (REST/GraphQL/gRPC, etc.) |
| `reports/03_design/api-specifications/` | `design-api` (+ `design-graphql`) | OpenAPI/GraphQL/gRPC/AsyncAPI specifications |
| `reports/06_implementation/*.md`, `api-contract-map.json` | `design-implementation` | Implementation specs for the API layer, domain services, repositories, and value objects |
| `generated/{service}/`, `generated/infrastructure/` | `generate-scalardb-code`, `generate-infra-code` | Implementation and infrastructure code (see [outputs kept outside reports/](#4-outputs-kept-outside-reports)) |

**Legacy path**

The path used to re-investigate an existing system and carry out modification or redesign.

| File | Skill that writes it | Contents |
|---|---|---|
| `reports/before/{project}/technology-stack.md` + 3–4 more files | `investigate` | Technology stack, codebase structure, technical debt, DDD readiness (and a security assessment where applicable) |
| `reports/01_analysis/system-overview.md` + 3 more files | `analyze` | System overview, existing vocabulary mapping, actors/permissions, domain-to-code mapping |
| `reports/01_analysis/data-model-analysis.md`, `er-diagram-current.md` | `analyze-data-model` (optional) | Analysis of the existing data model, a current-state ER diagram |
| `reports/02_evaluation/mmi-*.md` | `evaluate-mmi` (parallel) | Module Maturity Index (MMI) evaluation |
| `reports/02_evaluation/ddd-*.md` | `evaluate-ddd` (parallel) | DDD strategic/tactical evaluation |
| `reports/02_evaluation/integrated-evaluation.md`, `unified-improvement-plan.md` | `integrate-evaluations` | An improvement plan integrating both evaluations |
| `reports/03_design/bounded-contexts-redesign.md`, `context-map.md` | `redesign` | Redesigned bounded contexts |
| `reports/03_design/target-architecture.md`, `transformation-plan.md` | `design-microservices` | Target architecture and a migration plan |
| `reports/04_stories/domain-story-{domain}.md` | `create-domain-story` (optional) | Domain Storytelling |
| `reports/03_design/scalardb-*.md` or `data-layer-design.md` | `design-scalardb` / `design-data-layer` (conditional) | Data-layer design |
| `reports/review/individual/review-*.json` (up to 7 kinds) | `review-consistency` and others (parallel) | Results from each lens in [the review family](/skills/architect-pipeline) |
| `reports/review/review-synthesis.md` / `.json` | `review-synthesizer` | A Go/No-Go verdict synthesizing every lens |
| `reports/00_summary/full-report.html` | `report` | The consolidated HTML report |
| `reports/review/report-quality-review.md` | `review-report` | A quality review of the report itself |

Regardless of which path is used, the following folders are created as needed by manually-invoked skills common to both:

| Folder | Skill that writes it | Contents |
|---|---|---|
| `reports/03_design/aggregates/aggregate-manifest.json` | `design-aggregate` (optional) | Aggregate design (roots, invariants, commands, repositories) |
| `reports/03_design/state-machines/state-machine-manifest.json` | `design-state-machine` (optional) | State transition design (every cell of the state × event matrix decided) |
| `reports/03_design/domain-event-catalog.json` / `.md` | `design-aggregate` (writes it), `design-microservices` (completes the consumer side) | Publishers, consuming contexts, and delivery contracts for each event (the context map's Published Language) |
| `reports/03_design/adr/adr-NNN-<slug>.md`, `index.md` | `redesign` (opens the log), `design-microservices`/`design-scalardb`/`design-data-layer`/`design-api` (append) | Architecture Decision Records (a cross-cutting decision log, append-only) |
| `reports/05_estimate/` | `estimate-cost`, `estimate-token-cost` | Cloud/ScalarDB-license/operating cost estimates, and token-cost estimates (`token-cost-estimate.md`) |
| `reports/07_test-specs/` | `generate-test-specs`, `generate-characterization-tests` (legacy path), `generate-acceptance-tests` | Unit/integration/contract/performance test specs, BDD scenarios, characterization-test coverage (`characterization-test-coverage.md`), acceptance-test coverage (`acceptance-test-coverage.md`) |
| `reports/08_infrastructure/` | `design-security`, `design-observability`, `design-disaster-recovery` | Security design, observability design, disaster-recovery design, a deployment guide |
| `reports/09_verification/` | `verify-implementation --gate` | Results from the [8-stage quality gate](/skills/backlog/implement) covering build, tests, SAST, dependency scanning, coverage/mutation scores, and more |

<Panel title="Why this structure matters">
`reports/` is the single source of truth — the one place you always consult to ensure information stays consistent. All downstream skills operate by reading from this directory. For that reason, it is important not to break the meaning of the numbered directories (which represent phase order). Breaking that order makes it impossible to maintain consistency across the entire pipeline. See [Core Concepts](/concepts) for details.
</Panel>