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
  • 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
  • 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

Instruction Set page

Purpose

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

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

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.