Builder flow

This is the recommended path for a builder who turns validated analysis into implementation-ready delivery packages, instruction sets, and build output. Use it when you want to move from analysis artifacts into delivery without losing traceability. It matters because the builder-side artifacts depend on each other in a deliberate order: architecture before guardrails, guardrails before delivery packages, and delivery packages before builds. Before you start, make sure you already have access to the correct implementation and any linked analyst artifacts you depend on. A first walkthrough usually takes 15 to 25 minutes, then less once the artifact names feel familiar.

Read the concept definitions first when the artifact names are still unfamiliar: Implementation, Feature, Architecture, Pattern, Feature flow, Guardrails, Delivery target, Delivery package, Instruction Set, and Build.

Flow overview

1. Open or create the implementation.
2. Create the feature and connect it to the right epic and use cases.
3. Create or generate the architecture.
4. Review and finalize the architecture.
5. Create and refine the guardrails.
6. Create the delivery package.
7. Generate instruction sets and rendered artifacts.
8. Review the generated instruction sets and launch a build.
9. Review the build result.

Page guides used in this flow

• Start context: Implementations page, Project page, and Implementation page
• Feature planning: Feature page
• Architecture work: Architecture page, Feature flow page, and Guardrails page
• Delivery orchestration: Delivery package page and Instruction Set page
• Execution review: Build page

1. Open the implementation workspace

Pages used: Implementations page, Project page, and Implementation page

Go to Implementations or open the implementation list from the project page. Use Workspace on the implementation row when you want a guided overview before entering the advanced Implementation page. The Implementation workspace shows the recommended next action, Architecture readiness, Feature flow status, delivery setup, and latest results.

Create a new implementation when needed and connect it to the relevant specification. If repository-backed execution is enabled, make sure the repository details are valid before you depend on build automation.

2. Create the feature

Pages used: Implementation page and Feature page

Inside the implementation, create a Feature and connect it to:

• the implementation container
• the epic that defines the business scope
• optional use cases that provide behavioral detail

This step is the main traceability bridge from analyst output to builder work.

3. Create or generate the architecture

Pages used: Implementation page, Feature page, Architecture page, and Feature flow page

Use the implementation page for the implementation-level Architecture and the feature page for the feature-level Feature flow.

When FEATURE_FLOW_DESIGN_MODEL is enabled, think in two layers:

• create or refine the implementation-level Architecture from the implementation page
• create or refine the feature-level Feature flow from the feature flow workspace

The Architecture stays authoritative. The Feature flow should reference Architecture concepts and one concrete Pattern instead of redefining the architecture locally.

Each Feature flow belongs to exactly one Feature. Sibling Features under the same Epic have independent flows, generation history, and delivery packages; deleting a Feature removes only that Feature's flow artifacts.

When FEATURE_FLOW_DESIGN_GENERATION is enabled, the feature workspace also lets you generate a Feature flow draft from one required Pattern, source Use Cases, optional generation instructions, and an Architecture context preview. The context can be Recommended, All, or Manual. The result is queued asynchronously and reviewed before apply. Failed runs retain a structured failure stage and error code so the workspace can distinguish prompt configuration, AI response shape, Architecture-scope, and upstream AI-request failures.

Architecture context modes:

• Recommended asks AI to propose the focused Architecture fragments before generation; the preview must be current before the draft is queued
• All includes every fragment from the current Architecture
• Manual lets you select specific Architecture fragments in one search picker

The Pattern choice for feature flows comes from the implementation-level Architecture:

• only active patterns listed as Allowed on the Architecture can be selected in the feature flow workspace
• patterns marked Preferred are shown first as recommendations
• preferred does not mean required; any allowed pattern can still be selected
• each generated or manual Feature flow still stores exactly one concrete pattern_ref per flow
• generation submits the Pattern's stable key or code, resolves it once, and rejects unknown, inactive, or disallowed Patterns before creating a run
• every run snapshots that canonical Pattern reference and a content revision; step identifiers in AI-generated drafts are assigned deterministically by the server rather than accepted from model output

You have two practical paths:

• Manual architecture when you already know the structure
• AI-generated architecture when you want a structured starting point from the requirement and Ubiquitous Language context

The Implementation page shows one Current Architecture by default. If a final Architecture exists, that is current; otherwise the newest non-archived draft is current. Other implementation-level Architecture records stay available under Version history. If no current Architecture exists, use New architecture or Generate architecture with AI to create the first one. Once a current Architecture exists, use New draft version to branch from its content, or Generate draft version to create a new AI-generated draft from accepted Ubiquitous Language.

The AI architecture path depends on accepted Ubiquitous Language terms for the underlying specification. Accepted entities, values, processes, events, policies, relationships, and context hints seed generated Architecture so the draft starts from governed business vocabulary rather than exploratory clustering.

Requirements marked deferred are excluded from these implementation-side inputs, so they do not shape generated architecture, instruction context, or build supporting requirement sets.

If you start AI architecture generation and the modal closes immediately, click the AIKOZO logo in the top bar and use the Background jobs popup to track whether the job is queued, running, completed, or failed.

When the implementation semantic-search panel is available, you can also use it to jump directly to the closest matching architecture, flow, or guardrail fragment before you refine the architecture manually.

4. Review and finalize the architecture

Pages used: Implementation page, Architecture page, and Feature flow page

On the implementation-level Architecture page, review:

• the context tree above the workspace for project, implementation, feature, architecture, and fragment-count context
• key, name, and description
• prompt template reference
• the Overview tab for entity, module, and component-interface graphs
• the Patterns workspace button when your implementation needs reusable architectural templates
• the Modules, Components, Interfaces, Entities, Values, Processes, Events, Policies, and ADRs tabs for fragment-level review
• the enhancement history and preview before applying AI output
• the Raw YAML workspace button for manual correction

In the Patterns modal:

• Allowed patterns define which patterns feature-level Feature flows may use under this Architecture
• Preferred patterns are the recommended subset of the allowed set
• marking a pattern as preferred makes it appear first in flow planning and generation, but it does not block the other allowed patterns
• removing a pattern from Allowed also removes it from the feature flow picker

Architecture AI refinement is selective and review-driven. Choose one artifact tab, select one or more fragments of the same kind, choose Validate, Align, or Enhance, and queue a preview action. Use Select all or Deselect all on the active artifact tab when you want to change the whole visible selection quickly. In the enhancement-history panel, review the action, artifact-kind, and status badges, then open Validation, Before, and After as needed. The history list is scoped to the active artifact tab, and the After section shows the full enhanced fragment set for the selected artifact kind. Use Re-run when you want another variant, then Apply or Discard the preview. Use Edit only when the YAML needs manual correction.

The Optional query field also shows up to three saved quick phrases for the active architecture form bucket. These phrases are remembered separately per action and artifact tab, so Validate -> Modules suggestions stay distinct from Align -> Modules or Enhance -> Entities. Click a saved phrase to fill the query field immediately instead of retyping it.

Requirement, Use case, and Test case detail pages use the same quick-phrase pattern for Enhance guidance. Those phrases are kept in separate Specification workspace buckets so artifact-specific guidance does not mix with Architecture guidance.

For a deeper explanation of when to use each AI action, how review loops work, and how to use findings as follow-up actions, read the Architecture AI guide. Finalize only after the architecture is coherent enough to support guardrails and delivery-package generation.

If the new model is enabled, also review the feature-level Feature flow:

• key, name, and description
• draft, candidate, final, or archived status
• the alignment badge showing whether references are still valid
• the Overview, Flows, and Raw YAML tabs
• whether every referenced concept resolves to the implementation-level Architecture
• whether the selected pattern_ref and flow step roles still fit the Architecture

Use final sparingly. Only one implementation-level Architecture can be final per implementation, and only one Feature flow can be final per epic. Promoting a draft Architecture version to final makes it the current Architecture; older drafts and archived records remain available in Version history.

Once the implementation has a current final Architecture and usable final Feature flows, return to the Implementation page and use Gap analysis to compare the implementation-level Architecture against the final Feature flows. Review the additive runtime-fragment recommendations there before applying them one by one.

5. Create and refine the guardrails

Pages used: Feature page and Guardrails page

Open Guardrails from the feature page and create guardrails linked to the selected architecture. Use the Guardrails when you need delivery guardrails, not architecture structure.

Use the guardrails page to:

• queue a preview enhancement from a focused query
• optionally choose one feature-local Feature flow, or a legacy feature architecture in compatibility mode, and select the architecture fragments that should be used as read-only context
• use the focused-context fragment list to include only the most relevant modules, components, interfaces, entities, or ADRs
• review Validation, Before, and After before applying the preview
• use Re-run when you want another variant of the generated preview
• edit the YAML directly
• revert to default guardrails when needed
• move the artifact from draft to final when the guardrails are clear

Guardrails quality matters because it shapes Delivery package output and, later, build output.

5a. Configure delivery targets when delivery routing is needed

Pages used: Implementation page

When CAP_EXECUTION_TARGET_MANAGEMENT is enabled, open the implementation workspace Delivery targets tab before creating Delivery packages that will be routed to repositories or JIRA. Use the Delivery target to manage the destination, not the work content itself.

Typical builder actions there are:

• create GitHub, GitLab, or JIRA targets
• choose whether each target is available only to the current project (the default) or to every project in the tenant
• open target details to inspect usage and last validation
• run Validate target from the details modal
• activate or deactivate an existing target
• edit or delete unused targets
• open Execution mapping when you have at least two Git repository targets and need to route modules to different repos

For JIRA targets, choose the auth method explicitly. Atlassian service-account tokens need the site URL plus the Jira Cloud ID and validate through the api.atlassian.com/ex/jira/{cloudId} gateway instead of the site-local REST URL.

Inside the Execution mapping modal, use Module mapping for the normal repo assignment and Component overrides (when one component belongs elsewhere) only when one component must be delivered to a different repo than its module.

Keep delivery targets clean before you rely on Delivery package routing. A target that is still referenced by mappings or generated artifacts cannot be deleted.

For GitHub targets that will execute builds, confirm the selected token can push branches and open pull requests. If generated output may add or change GitHub Actions workflows under .github/workflows/, the token also needs GitHub workflow permission. See GitHub and GitLab token setup.

6. Create the delivery package

Pages used: Feature page, Feature flow page, and Delivery package page

From the feature page, create a Delivery package from one Feature flow and the selected flows that should move into delivery.

When the Delivery package is created, the system snapshots:

• alignment status for the Feature flow
• the resolved implementation Architecture and Pattern versions
• execution-target mapping for the referenced modules, components, and interfaces
• source traceability back to flows, requirements, and use cases

The Delivery package is the parent orchestration artifact. It generates child instruction_sets underneath for the current build runner and detail pages.

7. Generate instruction sets and rendered artifacts

Pages used: Delivery package page and Instruction Set page

Open the Delivery package and use Generate.

Review:

• generation progress
• generated child instruction sets per target partition
• generated child intent: agent-bootstrap, repo-init, feature work, or human review
• codex-ready and human-readable output
• rendered artifacts such as skill.md on the child instruction-set page
• delivery targets and source traceability

Generation follows the repository state:

• Empty repository: generates agent-bootstrap, repo-init, a blocked feature instruction set, and a human review/task set.
• Guidance-only repository: generates repo-init, a blocked feature instruction set, and a human review/task set. It also generates agent-bootstrap when scoped agent guidance such as AGENTS.md is missing.
• Runnable repository: generates a feature instruction set and human review/task set. It also generates agent-bootstrap when scoped agent guidance is missing.
• Unverified repository: generation stops. Validate the execution target connection and regenerate.

agent-bootstrap creates markdown guidance for humans and agents. It does not make the repository runnable. repo-init creates the runnable baseline. Feature instruction sets can be reviewed before that baseline exists, but execution stays blocked until repo-init has landed and the Delivery package is regenerated.

This is the point where AI output becomes most operational. Review it carefully before any execution step.

For longer runs, click the AIKOZO logo in the top bar. The Background jobs popup is the quickest place to confirm current job state and open the related page again.

8. Review generated instruction sets and launch a build

Pages used: Instruction Set page

From the Delivery package, open the generated child instruction set that should drive the next repository step, then launch the build from that instruction set. Use this order:

1. Execute agent-bootstrap first when it was generated.
2. Execute repo-init next when it was generated.
3. Review the repository output from each build like a normal Git change. If the build opened a pull request, review it, wait for the required checks, and merge or land it into the target branch before starting the next dependent repository instruction set.
4. repo-init is the required dependency for feature work. Do not execute the feature instruction set against an unmerged repo-init pull request. Merge or land the repo-init output first.
5. If agent-bootstrap produced guidance changes such as AGENTS.md, merge or land that output before repo-init when possible so the repo-init agent sees the current repository guidance.
6. Regenerate the Delivery package so the feature instruction set is reclassified as executable.
7. Execute the feature instruction set.
8. Review and merge or land the feature build output before treating the delivery as complete or starting follow-up work that depends on those changes.
9. Create or complete the human review/task item according to the delivery workflow.

Independent target repositories can move in parallel, but each repository still needs its own Git landing point before the next dependent instruction set uses that repository state.

The Instruction Set is the package you review. The Build is the record of what happened when you executed it.

The build inherits the repository context from the implementation settings. Use the build page to monitor:

• execution status
• build log
• changed files
• pull request reference
• error details when execution fails

Build dispatch uses a dedicated Celery queue consumed only by sandbox runners. The build is queued while waiting and becomes running when a runner atomically claims it immediately before execution.

9. Review the build result and close the builder loop

Pages used: Build page

A builder flow is complete only when the implementation output is reviewed against the original analysis.

Good final checks:

• the feature still aligns with the epic and use cases
• the architecture and guardrails explain the build result
• the generated files are useful, not just syntactically present
• issues found during build review are fed back into analysis or architecture rather than ignored

Selective AI still applies here. AI helps produce architecture, Delivery package, and instruction-set drafts, but the builder remains responsible for the quality of what gets executed.