Software Factory

Software Factory

Software Factory is an AI-native SDLC method for connecting product intent, technical intent, and implementation work in one traceable workflow.

This portable skill is for writing Software Factory records and executing Work Orders headlessly in any repository. It does not assume access to a hosted Software Factory service, private repository automation, or repository-specific review skills. When project tools are available, use them; otherwise, use the files and templates in this skill as the execution system of record.

Records

Requirements

Requirements describe the system from an external perspective.

• Product Overview Documents capture durable product-wide why and what: business problem, current state, product description, success metrics, technical requirements, and other framing.
• Feature Requirements Documents capture localized feature intent with user stories and acceptance criteria. User stories state who needs what and why; acceptance criteria define testable behavior.

Read guides/requirements-writing-guide.md when writing or revising requirements.

Blueprints

Blueprints describe the system from an internal perspective.

• Container Blueprints document separately deployable or runnable units and their runtime boundaries.
• Component Blueprints document reusable system capabilities. Structured component blocks define runtime nodes; relationship paragraphs describe data, contracts, and control flow.
• Feature Blueprints compose Component Blueprints and feature-specific components to satisfy a Feature Requirements Document.

Read guides/blueprint-writing-guide.md when writing or revising blueprints. During implementation, follow referenced Blueprints—including @… mentions and links resolved via MCP—before coding so the full component graph is understood.

Delivery

Work Orders describe delivery intent: implementable scope, exclusions, connected requirements, connected blueprints, and acceptance-test expectations.

Read guides/work-order-writing-guide.md when creating or updating Work Orders.

Routing

Work Order Execution

Work Order executions must follow the execution process every time. Every checklist item must be checked complete with `[x]` or explicitly marked `[SKIP]` with a skip reason. Do not treat an unchecked item as implied, optional, or complete.

Follow execution/execute-work-order.md for single Work Orders and multi-Work-Order queues. Read the related files in execution/ when that guide routes to them.

The checklist is intentionally a living harness-engineering artifact. Teams should evolve it with the exact commands, checks, screenshots, migrations, fixtures, seed data, CI gates, and review rituals that make agentic programming reliable in their codebase.

Version-control handoff is user-directed. Do not assume when to commit, push, open a PR, or merge unless the user or repository workflow specifies it.

Public Docs

• Requirements Writing Guide: https://8090.ai/docs/opinions/requirements-writing-guide
• Blueprint Writing Guide: https://8090.ai/docs/opinions/blueprint-writing-guide
• Work Orders: https://8090.ai/docs/modules/work-orders

Execute Work Order

Purpose

Execute one or more Work Orders end to end: gather context, plan, implement, review, verify, and hand off.

Single Work Order Execution

1. Resume or initialize the execution directory

First check whether .sw-factory/WO-<number>/ already exists.

• If it exists: resume from the existing execution files and continue from the current checklist phase.
• If it does not exist: initialize it using the bash script.

bash path/to/software-factory/execution/scripts/init-wo-execution.sh \
  --work-order-number "WO-<number>" \
  --work-order-title "<title>" \
  --work-order-id "<stable-id>"

Resolve path/to/software-factory relative to this skill directory. If the shell is already in the skill directory, use bash execution/scripts/init-wo-execution.sh ....

Initialization creates:

• checklist.md - execution checklist
• context.md - quick-reference links and notes for execution context
• implementation-plan.md - implementation plan
• review-log.md - review log

Do not re-run initialization for an existing Work Order directory unless the user explicitly approves replacing execution files, and commit .sw-factory/ with the rest of the change when Git is your execution-artifact system of record.

2. Follow the checklist protocol

CHECKLIST COMPLETION IS MANDATORY. EVERY ITEM MUST END IN ONE OF TWO STATES: CHECKED COMPLETE WITH `[x]`, OR MARKED `[SKIP]` WITH A SKIP REASON. UNCHECKED ITEMS ARE EXECUTION FAILURES, NOT TODOs TO IGNORE.

Complete the checklist incrementally throughout execution. Check items off immediately after completing them and add notes in real time when evidence or skip reasons are needed. Do not defer checklist updates to the end. Each phase ends with a certification line that must be checked before proceeding to the next phase.

Skip protocol:

- [SKIP] E2E tests run/passing
  Skip reason: Backend-only service refactor with no user-facing flow.

3. Gather Software Factory context

Use the Software Factory MCP to gather work order context. Track each completed context step in checklist.md; do not duplicate checklist detail here.

1. Treat the Work Order description or task request as execution scope: in-scope deliverables, exclusions, linked records, and acceptance expectations. 2. Read all linked requirements and extract the acceptance criteria that must pass. 3. Read all linked blueprints and identify the architecture path: components, models, contracts, composition, and implementation boundaries. 4. CRITICAL: Follow all blueprint references in the documents you read, including @… mentions and markdown links to other blueprints (resolve and read those through MCP too). It is absolutely necessary to understand linked blueprints. 5. Explore analogous code in the repository before inventing new structure. Identify file structure, naming patterns, service patterns, error handling, dependency injection, reusable components, and conventions specific to the touched module. 6. Use subagents or parallel exploration when the environment supports it and the work can be separated cleanly. 7. Fill or update context.md using execution/scripts/update-context-index.sh when structured links are known. Rerun the script whenever new referenced blueprints or user-directed delivery links become known.

Example (you may pass --requirement, --blueprint, and --referenced-blueprint more than once):

bash path/to/software-factory/execution/scripts/update-context-index.sh \
  --work-order-number "WO-<number>" \
  --work-order-title "<title>" \
  --work-order-id "<stable-id>" \
  --status "in_progress" \
  --requirement "<requirement title>|<id-or-url>" \
  --requirement "<another requirement>|<id-or-url>" \
  --blueprint "<blueprint title>|<id-or-url>" \
  --blueprint "<another blueprint>|<id-or-url>" \
  --referenced-blueprint "<component blueprint title>|<id-or-url>" \
  --referenced-blueprint "<another referenced blueprint>|<id-or-url>" \
  --branch "<branch-name-if-applicable>" \
  --pull-request-url "<url-if-applicable>"

4. Write the implementation plan

Write the implementation plan to .sw-factory/WO-<number>/implementation-plan.md (see writing-implementation-plans.md for structure and guidance).

Do not create or modify implementation files until `implementation-plan.md` is written. The plan must exist before code changes begin.

5. Implement with context

Implement only the Work Order scope. The implementation must stay traceable to:

• Work Order deliverables and exclusions
• linked requirements and acceptance criteria
• linked blueprint architecture, contracts, component composition, and implementation boundaries
• local codebase conventions and reusable code discovered during context gathering

6. Review and verify

After implementation is complete, follow review-phase.md. The review phase owns review orchestration and writes to review-log.md.

After review approval, run or confirm all relevant verification:

• tests required by the Work Order, requirements, implementation risk, and changed code paths
• acceptance criteria satisfaction
• blueprint alignment
• checklist evidence and phase certifications

7. Complete the handoff

Before handoff, confirm:

• checklist.md has all phase certifications checked, every item is [x] or [SKIP], and every [SKIP] has a reason
• context.md has the Work Order entity line, connected requirements, connected blueprints, referenced blueprints, current status, and known delivery links filled in
• implementation-plan.md reflects the implementation that landed
• review-log.md final verdict is APPROVED

Using the Software Factory MCP update the Work Order status to in_review.

Follow the user's requested version-control handoff; do not assume commit, push, PR, or merge behavior.

Multiple Work Orders

Use this section when the user's request references more than one Work Order, for example:

• "implement WO-1740, WO-1741, WO-1742"
• "execute WO-1740 through WO-1758"
• "move all Work Orders in phase 23 to review"
• "run the epic for feature X" after listing its Work Orders

Batch execution is sequential by default. Expand ranges or phase/epic references into an ordered list before starting. If ordering is ambiguous, resolve by explicit dependency first, then phase/order metadata, then Work Order number or creation order.

For each Work Order in order:

1. Create or update a visible progress item for that Work Order. 2. Execute the Work Order using this file. 3. If the Work Order reaches handoff, record WO-<number>: COMPLETE - <summary> and continue. 4. If the Work Order fails permanently, record WO-<number>: FAILED - <reason> and stop the queue. The user decides whether to fix, retry, or skip.

Rules:

• One Work Order at a time unless the user explicitly authorizes parallel execution and the tasks are independent.
• Do not batch unrelated Work Orders into one execution directory.
• Do not skip failed Work Orders without user direction.
• Keep each Work Order's checklist, context, plan, and review log separate.

When the queue stops or finishes, report completed, failed, and not-started Work Orders.

Review Phase

Purpose

Run a full code review pass isolated from day‑to‑day implementation work. The review checks the change against the Work Order, linked requirements, blueprints, repository conventions, tests and build health, user‑visible behavior where relevant, and security when relevant — then records a structured round in review-log.md and yields a clear verdict.

Prefer routing this work through a dedicated review delegate (subagent) when your environment supports it, so context stays focused and findings stay consistent.

Workflow

1. Scope the change set

Review only the work on the checked-out line: use your VCS to list changes from the merge base of your current tip and the branch this work merges into through your current tip. That branch is the PR base when a PR exists for this work; otherwise the default branch your remote or host reports. Pass that changed-paths list into the review pass.

2. Run every applicable review dimension

Prefer delegated review (separate agents or subagents).

Split the changed-paths list into a few coherent buckets — e.g. by subsystem, layer, or top-level directory — so each bucket fits a single focused review pass. Spawn one review delegate per bucket. Once the reviews are complete, synthesize a combined review report in review-log.md.

Align each finding with the sections in your review-log.md (and your team’s templates):

• Requirements alignment — linked acceptance criteria satisfied or explicitly out of scope.
• Blueprint alignment — components, contracts, data flow, and boundaries match linked blueprints.
• Architecture and conventions — placement, naming, layering, dependencies, errors, logging, reuse.
• Tests and build health — unit, integration, E2E, lint, typecheck, and build as relevant; document unrelated baseline failures rather than hiding them.
• User-facing verification — when behavior is visible or externally observable (UI, exports, emails, CLI output, etc.): exploratory checks, screenshots, or other evidence as appropriate. For browser apps, use the Cursor browser if available, or ChromeDevTools/chrome-devtools-mcp if available; if no browser tool is available and browser behavior is relevant to the user's software, set up ChromeDevTools/chrome-devtools-mcp automatically, or ask the user only when automatic setup is not possible, before approving the review.
• Security, privacy, and data safety — when relevant: auth, validation, secrets, PII, migrations, destructive operations.

For codebase-specific dimensions — architecture and conventions, tests and tooling, security expectations, and similar — rely on skills and other documentation already in this repository to decide what “good” looks like and the best checks to run. Those sources override generic bullets here.

3. Record the review round

Append a new round to review-log.md. Do not overwrite earlier rounds.

Each finding should include:

• Severity: blocking or advisory
• File or area
• Review dimension — name the dimension from the list above that this finding belongs to, and briefly what failed within it

The review pass (or delegate) should synthesize one verdict for the round.

4. Handle the verdict

• `APPROVED` — no blocking findings; proceed per execute-work-order.md.
• `CHANGES_REQUESTED` — fix every blocking finding; then run another full review round (with a fresh delegate pass when you use delegation).

If a finding needs product or policy judgment, stop looping and surface the question to the user.

Rules

• When delegation is available, the review delegate owns running and synthesizing dimensions; the implementation agent acts on the verdict rather than re‑reviewing.
• Every round appends to review-log.md.
• User‑facing verification may need browser, device, or screenshot tooling when the change produces observable output. For browser apps, prefer the Cursor browser when available, use ChromeDevTools/chrome-devtools-mcp when that is the available browser tool, and set up ChromeDevTools/chrome-devtools-mcp automatically when browser behavior is relevant but no browser tool is available. Ask the user only when automatic setup is not possible. Only that dimension should change product code when fixes are layout or presentation — not business logic — unless the team’s review guide says otherwise.
• Unresolvable or out‑of‑scope findings go to the user instead of endless retry loops.
• Resolve blocking findings before handoff or status moves.

<!--lint disable no-undefined-references strong-marker-->

Work Order Execution Checklist: {{WORK_ORDER_LABEL}}

Work Order Number: {{WORK_ORDER_LABEL}} Work Order Title: {{WORK_ORDER_TITLE}} Initialized At (UTC): {{INITIALIZED_AT}}

Phase 1: Start / Context Gathering

Required Steps

• [ ] Review work order description provided by MCP tool output
• [ ] Identify linked requirements and blueprints
• [ ] Review every connected requirements document
• [ ] Review every connected blueprint document
• [ ] Follow @… mentions and links to other blueprints in linked documents and read each referenced blueprint via MCP
• [ ] Review every referenced blueprint discovered that way; add them to Referenced Blueprints in context.md
• [ ] Extract acceptance criteria from requirements
• [ ] Identify architecture path from blueprints (components, contracts, composition)
• [ ] context.md is filled or updated with execution/scripts/update-context-index.sh for Work Order, connected requirements, connected blueprints, referenced blueprints, and known delivery links

• [ ] Certification: Phase 1 complete. Proceeding to Phase 2.

Phase 2: Planning And Implementation

Implementation Plan

(see execution/writing-implementation-plans.md)

• [ ] Implementation plan documented in implementation-plan.md
• [ ] Testing section documented in implementation-plan.md

Implementation

• [ ] Implemented changes are scoped to the Work Order
• [ ] Tests added or updated for changed behavior
• [ ] Documentation, generated files, fixtures, migrations, or config updated where relevant

• [ ] Certification: Phase 2 complete. Proceeding to Phase 3.

Phase 3: Review And Verification

Review

• [ ] Review subagent spawned per execution/review-phase.md and returned a verdict
• [ ] All acceptance criteria from the Work Order and linked requirements are satisfied
• [ ] Architecture is aligned with linked blueprints, or documented drift is accepted
• [ ] Exploratory pass on user-visible or external behavior — not only automated tests; for browser apps, use browser-based testing if available. Brief notes in review-log.md or evidence.
• [ ] Latest review-log.md verdict is APPROVED

• [ ] Certification: Phase 3 complete. Proceeding to Final Completion.

Final Completion Check

• [ ] All phase certifications above are complete
• [ ] Checklist is fully filled out with evidence
• [ ] Review log is complete (review-log.md)
• [ ] Implementation plan was followed (implementation-plan.md)
• [ ] All intended files are present in the working tree
• [ ] Work order status updated to in_review

<!--lint disable strong-marker-->

Work Order Entity Index: {{WORK_ORDER_LABEL}}

Initialized At (UTC): {{INITIALIZED_AT}} Current Status:

Work Order

• {{WORK_ORDER_LABEL}}: {{WORK_ORDER_TITLE}} ({{WORK_ORDER_ID}})

Requirements

• {{REQUIREMENTS_DOCUMENT_TITLE}} ({{REQUIREMENTS_DOCUMENT_ID}})

Blueprints

• {{BLUEPRINT_DOCUMENT_TITLE}} ({{BLUEPRINT_DOCUMENT_ID}})

Referenced Blueprints

Blueprints reached through @… mentions and links while reading linked blueprints.

• {{REFERENCED_BLUEPRINT_DOCUMENT_TITLE}} ({{REFERENCED_BLUEPRINT_DOCUMENT_ID}})

Delivery

• Branch:
• Pull Request URL:

<!--lint disable no-undefined-references strong-marker-->

Implementation Plan: {{WORK_ORDER_LABEL}}

Work Order: {{WORK_ORDER_LABEL}} — {{WORK_ORDER_TITLE}} Created At (UTC): {{INITIALIZED_AT}}

Summary

_1-3 sentences: what this work order delivers and the high-level approach._

Code Reuse And Package Structure

_List critical existing files/components/services/hooks/utilities/schemas/tests to reuse or import as dependencies. Note reuse/extract/follow-pattern decisions. Then list files/packages/directories intentionally created or modified by this plan, grouped by module or layer. Do not list incidental import-order, barrel export, formatting, generated-code, or mechanical follow-on edits._

Components And Flow

_Name Blueprint-defined components, supporting components, important interfaces/signatures, and call/data flow._

Steps

_Ordered implementation steps. Each step should produce a reviewable, preferably compilable intermediate state. Note parallelizable steps (touch different files, no dependency)._

1. [title] - _what to do, where_ 2. [title] - _what to do, where_

Testing

_Automated and manual tests: suites, new/changed test files, scenarios, and commands. Not for requirements/blueprint conformance—that belongs in review._

<!--lint disable strong-marker-->

Review Log: {{WORK_ORDER_LABEL}}

Work Order: {{WORK_ORDER_LABEL}} — {{WORK_ORDER_TITLE}} Initialized At (UTC): {{INITIALIZED_AT}}

This file records review and verification rounds. Append new rounds; do not overwrite prior rounds.

---

Round 1

Requirements Alignment

Blocking:

Advisory:

Blueprint Alignment

Blocking:

Advisory:

Architecture And Conventions

Blocking:

Advisory:

Tests And Build

Commands run:

Blocking:

Advisory:

User-Facing Verification

Skipped: _yes/no_ - _reason if yes_

Evidence:

Blocking:

Advisory:

Security, Privacy, And Data Safety

Skipped: _yes/no_ - _reason if yes_

Blocking:

Advisory:

Round 1 Verdict

• Total blocking:
• Total advisory:
• Files reviewed:
• Verdict: _APPROVED or CHANGES_REQUESTED_

---

<!-- Subsequent rounds: copy the structure above and increment the round number. -->

Writing Implementation Plans

Use this file to write .sw-factory/WO-<number>/implementation-plan.md.

The implementation plan is the bridge from Software Factory context to code. It translates the Work Order, linked requirements, and linked Blueprints into concrete repository changes.

Treat the Blueprint as the first-class architecture anchor. It defines required components and contracts; the implementation plan expands that model into package structure, supporting components, interfaces, control flow, and how you will test the change.

Filling in the file

implementation-plan.md is created from execution/scripts/implementation-plan-template.md. That file uses italic prompt lines and example step bullets as scaffolding only. You must replace all of that with substantive, work-order-specific content for every section below. The finished plan must not still contain instructional placeholder text (for example _1-3 sentences: …_), generic [title] step stubs, or any other template hints meant for the author.

Plan Structure

1. Summary - state what this Work Order delivers and the high-level implementation approach.

2. Code Reuse And Package Structure - identify the critical existing files, components, services, hooks, utilities, schemas, or tests that the implementation will reuse or import as dependencies. Note whether existing code will be reused directly, extracted into a shared component/utility, or followed as a proven pattern. Then list the files, packages, and directories intentionally created or modified by the plan, grouped by module or layer. Do not enumerate incidental files that may change because of import ordering, barrel exports, formatting, generated code, or other mechanical follow-on edits. Planned placement should follow the stack rules, codebase package conventions, sibling module patterns, and documented architecture.

3. Components And Flow - identify the Blueprint-defined components that must exist, then name supporting components needed to implement them cleanly: services, repositories, hooks, adapters, schemas, utilities, UI components, tests, and wiring code. Define public interfaces before bodies when they clarify boundaries: class/function/hook/component names, parameters, return types, request/response shapes, model fields, events, or API contracts. Translate Blueprint relationship paragraphs into code-level call flow: which component calls which, in what order, and what data crosses each boundary.

4. Steps - list concrete implementation steps that produce reviewable, preferably compilable intermediate states. Note dependencies or parallelizable steps when useful, especially when steps touch different files or layers.

5. Testing - specify automated and manual tests you will rely on to validate this work: suites to run or extend (unit, integration, E2E, contract, etc.), new or changed test files and cases, important scenarios to cover, and the commands or workflows to execute them. Prefer concrete file paths and commands when you know them. Do not use this section to rehash whether the change satisfies requirements or blueprints; that traceability is handled in the review phase and checklist. Use repository-local testing guidance for flags, ordering, and environment setup.

Rules

• Prefer reuse over net-new code. If existing code almost fits, plan whether to reuse directly, extract shared code, or follow it as a pattern.
• Prefer mature, extensible component and package structure over a direct but brittle implementation path.
• Do not plan out-of-scope improvements. Capture them as follow-up notes only when they affect delivery risk.

Blueprint Writing Guide

Source: https://8090.ai/docs/opinions/blueprint-writing-guide

Use when writing or revising Software Factory Blueprints. Requirements say what must be true; Blueprints say how the system is structured and behaves to make it true. Blueprints are written diagrams: structured blocks define nodes, and prose relationship paragraphs define edges. They should trace up to Requirements and down to code symbols, contracts, and runtime interactions.

Categories

Container Blueprint: one C4 container, meaning a separately deployable or runnable unit such as a web app, API server, database, background worker, or build pipeline. Documents technology stack, runtime characteristics, authentication/error/observability concerns, entry points, and boundaries. Create when establishing or documenting a deployable/runtime unit, especially one referenced by multiple Component Blueprints.

Component Blueprint: reusable system capability made of services, controllers, hooks, strategies, providers, persistence components, and other runtime pieces. It is a written component diagram: structured component blocks are nodes, relationship paragraphs are edges. Feature-agnostic; often spans containers. Create when two or more features depend on a capability, reuse is expected, internal structure warrants a document, or shared contracts need a home. Do not create for one helper, feature-only logic, or infrastructure better covered by a Container Blueprint.

Feature Blueprint: composition of Component Blueprints plus feature-specific components to satisfy one FRD. Create when a feature has structured Requirements and needs technical composition, configuration, or feature-only glue. Feature components may later move into Component Blueprints when reuse emerges.

Expected flow: Container Blueprints establish the runtime foundation; Component Blueprints define reusable capabilities within/across containers; Feature Blueprints compose those capabilities for Requirements.

Syntax

component block = runtime node that does work.

````markdown

name: NotificationDeliveryService
container: API Server
responsibilities:
	- Selecting delivery channels from `NotificationPreference`
	- Rendering channel payloads from `NotificationTemplate`

````

Rules: name is PascalCase and matches code identity; container names C4 container(s), comma-separated if needed; responsibilities are tab-indented - bullets and may mention elements or components.

model block = canonical data/domain model central to implementation but not itself a runtime component.

````markdown

name: CustomerOrder
store: Postgres
description: Canonical persisted order model.
fields:
	- id: UUID (required)
constraints:
	- unique `order_number`

````

Rules: include name, store, description, fields, and constraints when a model block is used. Mention models as elements.

Mentions

• ` #ComponentName : runtime component that does work; defined by a component` block in any Blueprint.
• ` ElementName : schema, config, domain type, enum, request/response model, exception, feature flag, permission matrix, or model` block.
• @SystemEntity: Software Factory entity such as a Requirement, Blueprint, Work Order, or Artifact.

Relationships

Relationship paragraphs are graph edges between component nodes.

• Mention both components early.
• State direction: who calls, depends on, owns, emits, stores, renders, or transforms.
• Name data/contracts crossing the boundary.
• Explain why the interaction exists.
• One relationship per paragraph; 2-4 sentences.
• Do not restate component responsibilities.
• If adjacency already makes direction, data flow, and intent obvious, the paragraph is optional.

Required Sections

Container Blueprint:

• ## Container Summary
• ## Infrastructure
• ## Entry Points and Boundaries
• ## System Contracts
• ## Architecture Decision Records

Component Blueprint:

• ## Capability Summary: 2-3 sentences naming the capability and key elements.
• ## Core Components: component blocks grouped logically.
• ## System Contracts
• ## Architecture Decision Records

Feature Blueprint:

• ## Feature Summary: 2-3 user-centered sentences referencing the corresponding Requirements document.
• ## Component Blueprint Composition: referenced capabilities, configuration, scope, composition paragraphs, @... document mentions, and #... concrete component mentions.
• ## Feature-Specific Components: full component blocks for panels, pages, hooks, services, or extensions that only exist for this feature.
• ## System Contracts
• ## Architecture Decision Records

Do not redefine referenced Component Blueprint components inside a Feature Blueprint. Describe how the feature uses them. Feature-specific components get full blocks.

Contracts And ADRs

## System Contracts captures guarantees and boundary interfaces.

• ### Key Contracts: invariants, correctness rules, idempotency, ordering, consistency, retry behavior.
• ### Integration Contracts: events, APIs, webhook payloads, composition expectations.
• ### Integration Boundaries: ownership and separation of concerns when boundary clarity matters more than payload detail.

## Architecture Decision Records captures non-obvious decisions. Use ### ADR-NNN: Title, then labeled Context, Decision, and Consequences paragraphs. Number ADRs sequentially within the Blueprint.

Checklist

• Choose category: Container, Component, or Feature.
• Use required sections for that category.
• Define runtime nodes with component blocks; define central domain models with model blocks only when useful.
• Use mentions correctly: #... components, ` ... elements, @...` Software Factory entities.
• Write relationship/composition paragraphs for non-obvious edges.
• Write System Contracts and ADRs.
• For Feature Blueprints, read the corresponding Requirements and ensure each major requirement theme has a technical path.

Requirements Writing Guide

Source: https://8090.ai/docs/opinions/requirements-writing-guide

Use this guide when drafting or revising Product Overview Documents or Feature Requirements Documents (FRDs). Requirements capture product intent: what the product must do and why it matters.

Document Types

Product Overview Documents: product-wide why and what. The why is business motivation: problems, unmet KPIs, North Star goals. The what is product description: what the product is and how its parts fit together. Default documents:

• Business Problem: the pain points the product addresses and why they matter.
• Current State: the status quo the product improves.
• Personas: users, goals, and success conditions.
• Product Description: what the product is and how its parts fit together.
• Success Metrics: the metrics used to measure product success.
• Technical Requirements: product-level technical constraints and requirements.

Write overview documents in plain language for the whole company. Focus on motivation and durable context.

Feature Requirements Documents (FRDs): localized feature why and what. The why is the user story; the what is acceptance criteria. FRDs use the project template from Project Settings > Requirements > Feature Requirements Template. FRDs can be nested when a child feature enhances a parent feature but is not required for the parent to function.

FRD Structure

Use three sections:

1. ## Overview

• Write 1-2 narrative paragraphs.
• Explain what the feature does and why users need it.
• Focus on problem and value, not implementation.

2. ## Terminology

• Define only feature-specific ambiguous terms.
• Use brief, precise definitions.

3. ## Requirements

• Each requirement is one cohesive, independently testable capability.
• Use IDs: REQ-[PREFIX]-NNN: Requirement Name.
• Child feature IDs append a suffix, for example REQ-AUTH-PR-001.
• User story format: As a [role], I want to [action], so that I can [outcome].
• Acceptance criteria use IDs: AC-[PREFIX]-NNN.N.
• Acceptance criteria format: When [condition], the system shall [behavior].

Use shall for mandatory behavior, should for recommended behavior, and may for optional behavior.

Quality Bar

• User-centered: describe user and business outcomes, not internal mechanisms.
• Testable: every acceptance criterion should be clear enough to turn into a test.
• Atomic: each acceptance criterion covers one behavior.
• Specific: avoid generic roles, vague actions, and phrases like "handled appropriately."
• Structured: preserve requirement and AC IDs exactly once assigned.

Split, Merge, Or Nest Features

• Split features when each passes the feature unit definition independently or different roles own different parts.
• Keep one feature when the requirements break without each other, complete one task together, or can be described in one sentence.
• Nest a child feature when the parent already delivers value, the child enhances the parent, and the child is meaningless without the parent.

Work Order Writing Guide

Source: https://8090.ai/docs/opinions/work-order-writing-guide

Use this guide when creating or updating Work Orders. A Work Order is an implementation task that delivers requirements while following blueprint specifications. A good Work Order connects the correct context, states what needs to be done, defines what is out of scope, and explains how completion will be verified.

The top priority when creating any Work Order is connecting the right Software Factory context. Work Orders can have different types (for example build, fix, requirements, blueprint, artifact, or other), but for every type the first objective is the same: link the correct requirements and blueprints so the implementer can read the source records directly. Do not restate details that already live in connected Requirements or Blueprints; reference the relevant records and describe the specific delivery responsibility for this Work Order.

Description Structure

Every Work Order description must include six sections:

1. ## Summary 2. ## In Scope 3. ## Out of Scope 4. ## Requirements 5. ## Blueprints 6. ## E2E Acceptance Tests

Summary

Answer: "What is being built or changed?"

• State the outcome this Work Order enables.
• Focus on value and system impact.
• Keep it to 2-3 sentences.
• Do not include broad background explanation.

In Scope

List the responsibilities owned by this Work Order.

• Define functional boundaries.
• Do not restate acceptance criteria verbatim.
• Avoid low-level implementation steps unless they are essential constraints.
• Make clear what this Work Order owns.

Out Of Scope

List what is excluded or deferred.

• Clarify boundaries with adjacent Work Orders.
• Prevent scope creep by making exclusions explicit.

Requirements

Name the connected Requirements that define this Work Order's scope.

• Include the relevant Requirements document title and IDs.
• Identify which requirement or acceptance-criteria IDs are in scope.
• Do not restate requirement prose that the connected document already contains.
• Add commentary only when it narrows what this Work Order owns.

Blueprints

Name the connected Blueprints that inform implementation.

Keep this section minimal because the implementer will read the full Blueprints directly. Use one line per Blueprint:

- {Blueprint Name} - {one-line summary of what it covers}

E2E Acceptance Tests

Describe the E2E coverage that validates the acceptance criteria. Use structured test specifications that follow the e2e-validator conventions.

For each requirement group, include:

• COV_ ID mapped to the relevant REQ- ID.
• test.describe block name.
• Test file path.
• Tags and priority.
• Individual @COV_... test cases mapped to acceptance criteria.
• Step-level user actions and assertions.
• Selectors or target UI elements where relevant.
• Data preconditions.
• Persistence verification patterns when state must survive close/reopen or navigation.

Template:

### COV_{PREFIX}_{NNN}: {Requirement Group Name}

**File:** `e2e-validator/tests/{module}/{area}/{spec-file-name}.spec.ts`

**Tags:** {tag list} | **Priority:** {P0/P1/P2}

**@COV_{PREFIX}_{NNN}.1 - should {description matching the AC}**

1. Sign in and navigate to {module}.
2. {User action}.
3. Assert {expected visible result}.
4. {Next action}.
5. Assert {state change or persistence}.

Quality Bar

• Precise enough to execute without clarifying questions.
• Narrow enough to prevent scope drift.
• Grounded in connected Requirements and Blueprints.
• Verification-focused: the E2E section proves how acceptance criteria will be validated.