Skip to content

Builder pages

This reference covers the main builder workspaces from implementation planning to build monitoring. Open it when you need page-level guidance while you are already in builder work and want a quick reminder of what each page is for. It matters because the builder-side UI contains several similarly named artifacts, and this reference helps you choose the right one before you create or run anything. You only need the usual product access, and most sections are quick one- or two-minute lookups.

Implementation workspace page

Purpose

Use the Implementation workspace as the simplified cockpit for one implementation. It summarizes Architecture readiness, Feature flow readiness, attention items, delivery setup, recent results, and one recommended next action.

Its Start here section follows the same visual contract as the AI, Specification, and Feature workspaces: compact KPIs, a numbered journey, and a slim recommended-action strip aligned with the highlighted journey stage. The journey remains implementation-specific: Architecture → Feature readiness → Delivery → Results. A thin amber line on the left edge of the corresponding section below repeats which area needs attention next.

Main actions

  • review Start here and follow the recommended next action
  • inspect Architecture and Feature flow readiness
  • review missing flows, stale alignment, missing guardrails, and failed results
  • check delivery target and prepared delivery status
  • open recent build and delivery outcomes
  • use AI can help with to open Architecture actions, Feature flow actions, and Implementation gap analysis in the existing advanced pages
  • use Advanced details to jump to Implementation, Feature, Architecture, Feature flow, Guardrails, Delivery package, Instruction Set, and Build pages

Notes

The workspace is intentionally task-oriented. It keeps delivery concepts such as Delivery package and Instruction Set available through advanced links, but does not make them the primary workflow vocabulary.

Feature workspace page

Purpose

Use the Feature workspace as the default guided journey for one Feature. It keeps the richer artifact model available through Detailed tools, while the main page follows Scope → Architecture and flow → Guardrails → Delivery → Results and shows one recommended next action.

The Start here section uses the same compact KPIs, numbered journey, highlighted stage, and aligned recommended-action strip as the other AIKOZO workspaces. Its stages link directly to the five Feature sections below, so the shared presentation does not replace Feature-specific actions. Controls in the recommended-action strip are navigation only; actions run from the destination section or from Detailed tools. The section for the recommended stage is repeated below with a thin amber line on its left edge.

The page verifies the Feature's Implementation, Project, Epic, and linked Use Case references before enabling actions that depend on them. If a required reference cannot be loaded, those actions remain unavailable and the page asks you to refresh instead of opening a link with a missing identifier. Delivery routing loads after the core workspace is visible; Prepare delivery becomes available only when that routing preview is ready.

Main actions

  • confirm the Feature, Epic, linked Use Cases, and human-readable context; each linked Use Case is shown with its human-readable key and name. A manually created or updated Feature requires at least one linked Use Case so Feature flows and generated work items retain specification traceability
  • generate a Feature flow from recommended Architecture scope and all linked Use Cases; the preferred or sole allowed Pattern is selected automatically
  • follow the recommended actions to review a generated Feature flow, select Apply to accept it, then open the accepted draft and make it final
  • use Realign at the top of the workspace to recheck the current Feature flow against its Architecture and Pattern dependencies; issues that still require content changes are reviewed in Detailed tools
  • review the automatically supplied default Guardrails, or use Customize guardrails to open that Guardrails record directly for advanced changes
  • choose Prepare delivery to create, resume, or reuse a matching Delivery package and queue generation without creating duplicates
  • choose routing only when a flow or work-item target is unresolved or ambiguous
  • after Delivery package generation, open the package, approve the next repository Instruction Set, and execute it as a build
  • review child Instruction Sets as Generated work items and inspect Feature-related build and downstream delivery outcomes under Results

The guided page maps detailed lifecycle values to Draft, Ready, Needs attention, Queued, Running, Done, or Failed. Delivery package generation remains Queued until its Celery worker starts, then changes to Running. Long-running action buttons change label and become disabled as soon as they are activated, and Feature-flow generation is polled through its terminal state. Archived artifacts are hidden. Artifact IDs, raw lifecycle values, fragment controls, and package internals remain in Detailed tools.

Default Guardrails migration

New Features receive draft default Guardrails from tenant configuration. Before enabling the guided journey for existing data, preview and then apply the tenant-scoped backfill:

spec_kiln migrate default-guardrails --dry-run --tenant-id TEN:example
spec_kiln migrate default-guardrails --tenant-id TEN:example

Use --all-tenants instead of --tenant-id only for an intentional full database run. The command is idempotent, reports blockers and per-Feature failures, and prints the exact per-project spec_kiln backfill vectors commands needed to index newly created Guardrails. Missing tenant default content blocks creation; the migration never creates empty Guardrails.

Feature flow ownership migration

Before deploying the Feature-owned flow model over existing data, preview and apply the ownership migration:

spec_kiln migrate flow-design-feature-ownership --dry-run
spec_kiln migrate flow-design-feature-ownership

The command assigns a Flow Design or generation run only when one matching Feature can be proven, including a unique Action Pack reference. Ambiguous Epic-scoped records are reported as blockers and are not guessed. After a clean run, execute the printed vector-backfill commands before starting the new app.

Implementation page

Purpose

Use the Implementation page as the main coordination workspace for one implementation. It connects features, implementation-level architecture, delivery targets, and builds.

See also

Main actions

  • review the implementation context tree
  • run semantic search across related implementation artifacts
  • press Escape in the search field or click its transparent × button to clear the query and results
  • switch between Features, Architecture, Delivery targets, and Builds
  • run Gap analysis to infer missing runtime fragments for the implementation-level Architecture from final Feature flows
  • filter, sort, create, and open features; the compact control on the Features tab cycles through oldest, newest, and key order and preserves the selection in the URL
  • delete a Feature together with its packages, generated work items, Guardrails, its Feature flow, and its generation runs; sibling Features under the same Epic and their artifacts are not affected
  • open the current implementation-level Architecture
  • create the first Architecture, or create/generate a new draft Architecture version once a current Architecture exists
  • review older Architecture records under Version history
  • as a Builder or Manager, create and manage delivery targets, including adding or replacing the stored secret
  • keep a delivery target available only to the current project by default, or deliberately make it available to every project in the tenant
  • validate Delivery target connectivity before activation; if secure credential storage is unavailable, validation reports the missing EXECUTION_TARGET_ENCRYPTION_KEY configuration instead of attempting the provider connection
  • create and open builds

Gap analysis

Use the Gap analysis tab on the Implementation page to compare the current final implementation-level Architecture with all usable final Feature flows in that implementation. The analysis excludes final Feature flows marked with broken references and proposes additive runtime fragments only: modules, components, interfaces, and entities.

Each recommendation stays implementation-scoped and can be applied one by one. Applying a recommendation updates the analyzed implementation-level Architecture in place and first downgrades it from final to candidate.

Prompt selection follows tenant settings:

  • explicit prompt chosen on the run
  • tenant-scoped prompt default for design.gap_analysis.implementation
  • repository default prompt from config/prompts/implementation_gap_analysis_v1.md

Pop-up modals

  • New feature
  • New build
  • New architecture / New draft version
  • Generate architecture with AI / Generate draft version
  • Delivery target details: inspect one managed delivery target in detail. Validation refreshes its status, stored-secret information, validation details, usage and activation action. Validation leaves the target Inactive, even when successful; use Activate target separately. Activation is unavailable after failed validation. Unsaved edits and an unsuccessful replacement secret stay in the edit form. Path prefixes appear only for Scoped paths; repository-wide delivery does not submit hidden path restrictions.
  • Execution mapping: open the mapping modal from the Delivery targets tab when an implementation has at least two Git repository targets. Use Module mapping as the default routing layer and Component overrides (when one component belongs elsewhere) only for component-level exceptions to that module routing.

Feature page

Purpose

Use the Feature page to move one feature from architectural intent toward delivery-ready orchestration artifacts.

See also

Main actions

  • switch between Feature flow, Guardrails, and Delivery packages
  • use delivery-packages as the canonical Delivery packages URL; legacy instruction-sets and action-packs links are redirected to the same tab
  • follow the Feature context children or descendant back-links without losing the owning tab
  • treat — as not loaded; once loaded, each tab shows Missing, Draft, Ready, Needs attention, Broken, Running, Done, or Failed rather than interpreting an unopened tab as zero
  • review alignment summary for feature flows
  • create guardrails
  • open feature flows and delivery packages
  • retire a superseded Feature flow in any lifecycle state, including final, so it no longer participates in active implementation work
  • preserve Delivery packages, generated work items, and build history linked to a retired Feature flow for traceability
  • generate a new feature flow from a required pattern plus Recommended, All, or Manual architecture context
  • review a generated draft and apply, discard, or rerun it
  • see the latest generated draft in every browser tab after refresh; until it is applied, readiness is shown as Generated draft rather than as a missing accepted Feature flow or a completed artifact
  • create a delivery package from one feature flow and selected flows
  • when delivery is blocked, follow the contextual action to generate or review Feature flow, resolve alignment or broken references, or configure Delivery targets; the creation modal opens only when its prerequisites are usable

Architecture remains owned by the Implementation page. The advanced Feature page does not expose Feature-local Architecture creation or editing controls.

Pop-up modals

  • Create delivery package
  • New guardrails
  • Generate feature flow: create a feature-flow draft from an active, allowed pattern, source use cases, generation instructions, and architecture context preview; the server validates the pattern and assigns generated step identities

Architecture page

Purpose

Use the Architecture page to review and refine the authoritative implementation-level architecture artifact.

See also

Main actions

  • review status, description, prompt template, and context
  • switch between Overview, Modules, Components, Interfaces, Entities, Values, Processes, Events, Policies, and ADRs
  • inspect entity, module, and component-interface diagrams
  • filter fragment lists on each artifact tab
  • select fragments and run Validate, Align, or Enhance
  • use saved quick phrases in the architecture action modal
  • save allowed and preferred patterns
  • review enhancement history and apply, discard, or rerun previews
  • inspect Architecture YAML as either a navigable tree or complete source
  • copy or download Architecture YAML without opening the editor
  • preview, copy, or download a PlantUML export containing separate module, component-interface, and entity diagrams
  • edit raw YAML manually

Pop-up modals

  • Run architecture action
  • Patterns
  • Raw YAML
  • Edit architecture
  • fullscreen diagram modals for entities, modules, and component-interface relationships

Feature flow page

Purpose

Use the Feature flow page to review feature-level flows and keep them aligned to the current implementation architecture and patterns. The page always shows the flow owned by the selected Feature, never a flow shared implicitly through its Epic.

See also

Main actions

  • review status, alignment badge, and alignment details
  • recheck alignment
  • switch between Overview, Flows, and Raw YAML
  • inspect the flow-step overview diagram
  • select flows and run Validate, Align, or Enhance
  • review action history and follow-up recommendations
  • edit raw YAML manually
  • retire the Feature flow, including when its lifecycle state is final or its alignment is stale

Retirement changes the Feature flow to archived, hides it from active implementation views, and frees the feature to promote its corrected flow. Any existing Delivery packages, generated work items, builds, commits, pull requests, and delivery outcomes remain linked to the retired flow and available through their historical detail pages. A direct delete removes a flow with no delivery history; when delivery history exists, the same request safely retires it instead.

Pop-up modals

  • Run action
  • Edit feature flow
  • fullscreen overview modal for the flow overview diagram

Guardrails page

Purpose

Use the Guardrails page to define and refine the implementation guardrails for one feature.

See also

Main actions

  • review status, prompt template, and context
  • choose one focused architecture context and the read-only fragments to include
  • enter an enhancement query and queue a preview
  • review enhancement history
  • use default guardrails, clear the current set, or edit YAML directly
  • move the artifact between draft and final

Pop-up modals

  • Edit guardrails: update metadata or base settings for the constraint set

Delivery package page

Purpose

Use the Delivery package page to review one delivery orchestration package before or after instruction-set generation.

See also

Main actions

  • review status, execution-target count, child instruction-set count, and repository strategy
  • generate child instruction sets
  • confirm whether generated repository work is agent-bootstrap, repo-init, or feature implementation
  • open the current or last build when available
  • review included flows
  • review delivery targets
  • explore the Traceability map tab as a layered map from requirements and use cases through feature flows, action items, delivery artifacts, and changed files
  • open generated instruction sets

Generation preserves a selected Use Case's text and available requirement coverage when its older requirement links are missing, deferred, or outside the Feature's scope. Unavailable links are omitted from the resolved source inputs; the Specification is not changed. This also works when none of the Use Case's linked requirements remain available. Missing sources explicitly selected by a flow still block generation.

File lineage is limited to the current Project and tenant. When graph results are unavailable, recorded build changes provide the history for that Project. Older graph associations without verified ownership are excluded until an approved projection rebuild.

Instruction Set page

Purpose

Use the Instruction Set page to inspect the generated execution package that will drive build or delivery work.

Requirement and Use Case source badges and copied dependencies show their human KEYs (or available human IDs/names). The same labels apply to bootstrap source references and Delivery package lineage.

For both human and Codex instructions, artifact references in titles, body text, acceptance criteria, and previews use human-readable keys or names. Copy includes the acceptance criteria with the same resolved labels. Unavailable references show an artifact label, never a database ID; execution payloads retain their IDs.

For repository work, check the intent before executing. agent-bootstrap materializes markdown guidance only. repo-init creates the runnable baseline for an empty or guidance-only repository. Feature instruction sets can be reviewed while blocked, but they run only after repo-init has landed and the Delivery package has been regenerated.

Use the generated children in this order when they are present: agent-bootstrap, merge or land its Git output when it changed repository guidance, repo-init, merge or land the repo-init output, regenerate, feature instruction set, merge or land the feature output, then human review/task.

See also

Main actions

  • lock or unlock the instruction set
  • review metadata, intent badges, and execution state
  • inspect generation progress
  • show or hide the final prompt
  • review generated instructions
  • render skill.md and inspect rendered artifacts
  • open the current or last build

Build page

Purpose

Use the Build page to monitor the execution result of one instruction set or action-pack delivery run.

A new build remains queued while it waits on the dedicated sandbox-runner queue. It changes to running only after a runner claims it and starts execution.

The Repository link uses the repository snapshot resolved by the runner and the build's managed Execution Target. For an older build without that snapshot, the page derives the repository link from its GitHub pull-request or GitLab merge-request URL.

In the context tree, the Build item shows its start time in the browser's local time zone together with its current status instead of an internal database ID. If execution has not started yet, it shows the queued time.

See also

Main actions

  • review build status, repository, pull request, and errors
  • switch between Build log and Files
  • inspect streaming build output
  • inspect changed files after execution
  • retry Git push and review request creation after a push-only failure
  • navigate back to the related instruction set, delivery package, or implementation

The Build log reports automatic recovery from invalid AI responses, temporary provider failures, and correctable file conflicts. A response has at most three attempts. An instruction allows two additional edit corrections. Logs explain the reason, retry count, ignored no-op operations, skipped reads, and retained partial edits. Recovery diagnostics also appear in the build trajectory on success and failure.

Already applied edits remain in the workspace when a later operation needs correction. The AI receives refreshed file contents and instructions to avoid repeating those edits. Refusals, forbidden paths, unreadable required source, and exhausted recovery limits stop the build. Validation is advisory: failing or unavailable checks are reported honestly and do not prevent a PR by themselves.

Unresolved business decisions and remaining validation work become Developer follow-up entries, each with a description of at most five words in the Build log. The builder preserves coherent scoped changes and continues independent instructions without claiming the deferred behavior is implemented. Explicitly prohibited work remains separate.

Validation commands run through the runner's sandbox. The file editor uses those results and records failed, unavailable or unexecuted checks for the developer. The TODO entry includes known commands and working directories, actual outcomes or missing execution, and suggested fixes or reruns. Missing fresh validation results do not by themselves stop delivery or count as passing checks.

The PR includes TODO-<FEATURE-CODE>.md with a checklist of unresolved items, affected instruction codes, what needs attention, and suggested next steps. For builds without a Feature, the filename is TODO-<INSTRUCTION-SET-CODE>.md. The file is placed at the repository root or inside the allowed target directory for scoped builds. Later builds append their follow-ups while preserving existing developer notes. The Files tab records its lineage; the PR description names the file and lists the short items. Push retries preserve the file and follow-up metadata without regenerating them.

Developers review and finalize the remaining implementation using this checklist. These follow-ups use the normal PR review, merge and CI reconciliation; they do not create a permanent forbidden-work remediation condition. Failed builds do not automatically publish a review request. A Builder can explicitly publish retained partial output as described below; incomplete functionality is never reported as fully implemented.

Publish partial output after a failed build

Open the failed build's AI Delivery artifacts tab. When the build produced changes that pass repository and scope checks, Publish partial PR lets a user with the Builder role publish them for developer review. Admin alone does not grant Builder permissions. The tab shows how this works and the deadline for publishing the retained output.

  1. Inspect the Build log, Files, and original failure before publishing.
  2. Select Publish partial PR. AI is not rerun: the runner pushes the retained commit and creates a PR/MR against the repository's default branch.
  3. Open the PR from AI Delivery artifacts. Its title marks it as partial; its description records the failure and unfinished work. The included TODO-<FEATURE-CODE>.md gives the developer follow-up directions. Builds without a Feature use TODO-<INSTRUCTION-SET-CODE>.md.
  4. Review every changed file, finish incomplete behavior and TODO items, and run the appropriate checks before merging. Publication does not mean the code is complete or validated. The build remains failed, and its original failure and trajectory remain available alongside publication diagnostics.
  5. Merge through your normal repository review process. If you start another build, it clones the current default branch and must adapt to the merged code and developer changes. An unmerged partial PR is not included in that build.

The output is retained for up to 24 hours. Publication rechecks the approved Action Item, managed execution target, repository, scope and retained commit. It does not bypass these checks or merge the PR for you. If publication itself fails, the tab offers the same action while the output remains available; the Build log records the publication error. An already published PR is not republished.

If there were no usable changes, the workspace was removed or expired, or output could not be prepared safely, start a new build. Older failed builds whose output was already deleted cannot be recovered by this action. Retry push remains the action for a build that finished code generation but failed during normal delivery.

If a GitHub build fails while pushing changes under .github/workflows/, check that the selected GitHub token includes workflow permission before retrying the push. See GitHub and GitLab token setup.

Assistant and shared Implementation summaries

The Implementation and Feature workspaces use the same backend summaries as the AI Assistant. Counts include explicit totals; a partial-summary notice means that additional records are available in the detailed lists. Current Architecture and Feature flow are separate from historical versions. Generated work items means Instruction Sets for the current final Feature flow, not a separate artifact type. AI action shortcuts exclude archived Feature flows even when those flows appear in the historical catalog.

The AI Assistant is also available on Feature workspace, Delivery package and Build pages. It reads the current page first, resolves its authorized parent context, then uses scoped catalogs and focused content. It can explain delivery readiness, routing blockers, approval, bootstrap requirements, Build execution, review, CI and closure. Successful execution alone does not mean review, CI or closure is complete. Disabled capabilities are reported as unavailable, rather than missing setup. Recorded target validation is distinct from local preparation readiness; summaries never inspect live repositories.

Delivery information is read-only for the Assistant. Existing reviewed proposal permissions are unchanged. Credentials, connections, external identifiers, URLs, repository and file locations, runner configuration, prompts and logs are excluded from assistant evidence, including previews and error messages.