Purpose and working model¶

AIKOZO is built for teams that need Requirements discipline, delivery traceability, and practical AI support in one workspace.

Read this page when you want the vocabulary behind the rest of the guide. It explains what the main artifacts mean, why they exist, and how they fit together before you follow the analyst or builder flows. You do not need any special setup beyond access to the product, and a first read usually takes about ten minutes.

Product purpose¶

The platform connects the "what" side of delivery with the "how" side:

Specification work captures business intent as specifications, Epics, Requirements, and Use Cases.
Planning work turns validated specification scope into accepted planning baselines, readiness signals, rough effort ranges, and allocation guidance.
Implementation work turns that intent into features, architecture, guardrails, delivery packages, instruction sets, and build jobs.

The value is not just generation. The real value is that the generated outputs stay attached to the project structure, can be reviewed, linked, revised, and reused later.

Core working model¶

Entity	Purpose
Project	The main workspace boundary for analysis and implementation work.
Specification	The specification-level grouping for Epics.
Epic	A business capability area inside a specification.
Requirement	A reviewable Requirement item, typically enhanced and finalized before downstream use.
Use Case	A structured scenario that covers one or more Requirements.
Test Case	A reviewable validation scenario linked to a Use Case and one or more Requirements.
Plan	A spec-scoped planning container that groups Planning Scopes for selected Epics.
Planning Scope	The planning unit for one Epic inside a Plan. It owns assessments, accepted baseline state, and effort allocation.
Scope Assessment	A generated and reviewable planning estimate with readiness, effort, confidence, drivers, missing information, and scope item classifications.
Effort Allocation	A distribution of an accepted Scope Assessment estimate across linked specification artifacts.
Implementation	The implementation-side container for features and builds.
Feature	A delivery slice linked back to Epic and optional Use Cases.
Architecture	The authoritative implementation-level architecture artifact, usually represented and reviewed in YAML.
Pattern	A reusable architectural template assigned at Architecture level to guide feature-level flows.
Feature flow	The feature-level flow artifact. It contains flows only and references Architecture concepts instead of redefining them.
Guardrails	The delivery boundaries that shape the implementation solution.
Delivery target	The managed delivery destination used to route generated work to repositories or work-management systems.
Delivery package	The parent execution unit created from Feature flow selection, target mapping, and traceability snapshots.
Instruction set	The generated child execution artifact used to drive implementation generation, rendered artifacts, and build execution.
Build	The executable run, with logs and changed files.

When FEATURE_FLOW_DESIGN_MODEL is enabled, Architecture and Feature flow become separate artifacts. Some routes and API payloads may continue to use legacy internal names during rollout, but the user-facing vocabulary should use the names in the table above.

Builder-side concepts¶

The builder flow becomes easier to read once you separate container artifacts, architecture artifacts, delivery artifacts, and execution artifacts.

Implementation¶

An Implementation is the builder-side container for one planned solution. It groups the features, implementation-level Architecture, managed delivery targets, and related builds for the same delivery effort.

Use it when you want one place that ties the "how" side of work back to the source specification.

Feature¶

A Feature is the delivery slice inside an Implementation. It is the point where builder work reconnects to analyst artifacts such as the source Epic and selected Use Cases.

Use it when you want to shape one coherent piece of delivery scope without mixing unrelated flows and guardrails together.

See also: Builder flow step 2 and Feature page.

Architecture¶

An Architecture is the authoritative implementation-level architecture artifact. It defines the reusable structural concepts that feature work is allowed to depend on: modules, components, interfaces, entities, ADRs, and Patterns.

Use it to describe the stable implementation structure. Do not use it to write feature-specific execution steps.

Pattern¶

A Pattern is a reusable architectural template assigned at Architecture level. It describes the preferred structural style for a flow or feature, such as the kind of components and interfaces that should participate.

Use it to guide Feature flow shape and generation. A Pattern is not the flow itself, and it is not executable delivery output.

Feature flow¶

A Feature flow is the feature-level flow artifact. It defines the sequence of steps, actors, and referenced Architecture concepts needed for one feature while staying aligned to the implementation-level Architecture.

Use it when you want to describe how the feature should work. Do not use it to redefine the architecture already owned by the Architecture.

Guardrails¶

A Guardrails artifact captures the limits, rules, and non-goals that should shape downstream generation and delivery.

Use it to make boundaries explicit before you generate Delivery packages or instruction content.

See also: Builder flow step 5 and Guardrails page.

Delivery target¶

A Delivery target is a managed delivery destination such as a GitHub repository, a GitLab repository, or a JIRA project. It stores routing metadata and validation state so delivery artifacts can be sent to the right place.

Delivery targets are project-scoped by default. A tenant-scoped target can be selected when the same managed destination should be available to every project in the tenant.

Use it when delivery needs to be scoped to a repository or work-management system. It is routing configuration, not the generated work itself.

Delivery package¶

A Delivery package is the parent delivery orchestration artifact created from a Feature flow and selected flows. At creation time it snapshots the relevant Architecture and Pattern versions, traceability links, and resolved delivery-target mapping.

Use it when you want a stable, reviewable delivery package before generation or execution starts.

Instruction Set¶

An Instruction Set is a generated child execution package under a Delivery package. It contains the concrete output prepared for a specific delivery path, such as codex-ready instructions, rendered artifacts, and build input.

Use it when you want to inspect the actual generated execution payload before a build or delivery action.

Repository instruction sets have different intents. agent-bootstrap writes markdown guidance, repo-init creates the runnable scaffold for a new or guidance-only repository, and feature instruction sets implement selected flow work after the scaffold exists. A generated feature instruction set can be visible before repo-init lands, but execution remains blocked until the repo-init output is merged or otherwise landed on the target branch and the Delivery package is regenerated.

Build¶

A Build is the execution record for a generated delivery run. It captures runtime status, logs, changed files, and pull-request outcomes where relevant.

Use it to monitor execution and confirm what changed after the Instruction Set was launched.

Selective AI, not hands-off automation¶

AIKOZO uses AI intentionally. The aim is to reduce manual drafting effort, not to replace accountable engineering decisions.

Use AI when you want a strong first draft, vocabulary analysis, discovery help, or assisted transformation between artifacts. Stay manual when precision, policy, or business nuance needs direct control.

Typical pattern:

Generate or enhance a draft.
Review the result critically.
Edit the wording, links, and coverage.
Finalize only when the artifact is trustworthy.

Status discipline¶

The common working statuses are:

Badge	Meaning
new	Fresh, unreviewed items.
draft	Edited or AI-improved items that still need review.
final	Artifacts the team accepts as ready.
deferred	Still valid, but intentionally set aside for later, handed off to a third party, or kept around as currently non-relevant context.
...	An in-progress state usually covering `generating`, `enhancing`, `building`, or similar background work.
error	The item or job ended in an error state.
failed	The item or job failed to complete successfully.

The bookmarked marker is separate, not a lifecycle status. Use it for items you want to revisit later without losing whether they are new, draft, final, or deferred.

Color intent in the current UI:

gray for new
amber for draft
green for final
dark graphite with black text for deferred
blue for in-progress ...
red for error and failed

Finalization matters because later steps assume that finalized artifacts are stable enough to drive downstream generation and delivery work.

Architecture and Feature flows use the lifecycle states draft, candidate, final, and archived. Only one final Architecture is allowed per implementation, and only one final Feature flow is allowed per Epic. Flow Feature flows also track alignment state so you can see whether their references are still up_to_date, needs_alignment, or broken_reference.

Deferred Requirements remain visible and searchable, including semantic search, but they are excluded from downstream generation and delivery aids such as Use Case generation, Ubiquitous Language analysis, gap analysis, and implementation inputs.

Many AI actions run asynchronously. Typical examples are:

Requirement or Use Case enhancement
Epic, Use Case, architecture, delivery-package, or instruction-set generation
Ubiquitous Language analysis
gap analysis and similar long-running support jobs

To monitor them, open the Background jobs popup by clicking the AIKOZO logo in the top bar.

The popup shows:

whether the job is queued, running, completed, or failed
when it was last updated and how long it has been running
a concise, actionable summary when a job fails; structured diagnostics and internal identifiers are not shown
a link back to the related page when direct navigation is available

Use it whenever you start an operation and the page closes immediately or the artifact stays in the blue ... state for a while.

Bilingual projects¶

Projects can be configured for English or Slovak end-user input. Requirements and Use Cases support bilingual persistence:

localized user-facing text is preserved
canonical English remains the internal reference for reasoning and semantic processing

For end users this means:

you can work in the project language
you should still review AI output carefully
finalized text should be clear in both the local language and the canonical English representation when bilingual output is involved

Role-oriented usage¶

Three practical role perspectives matter most:

Analyst focuses on business intent, Requirement quality, Use Cases, and coverage.
Builder focuses on implementation structure, guardrails, delivery packages, instruction sets, and build execution.
Manager focuses on project setup, access boundaries, tenant-level visibility, and operational oversight.

The same project can move across all three roles without losing traceability.