Output Directory Structure
Describes the reports/ and work/ directory structure used by NexusArchitect, and the role of every folder and file in detail
NexusArchitect uses the following directory structure (created by init-output-family Skills if it does not already exist).
- reports/ Product-planning, design, and review deliverables
- work/ Progress, traceability, and cost records
- generated/ Actually-runnable code
- design-system/ The design system
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/.
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.
- 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
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 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). It can ingest the numbered reports/ folders (product side) regardless of which entry point created them.
- 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
- backlog/
| 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 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. 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 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) |
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, the live dashboard, and thinking about 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 |
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 (greenfield / legacy).
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/) |
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 |
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 covering build, tests, SAST, dependency scanning, coverage/mutation scores, and more |