@buildifyx/specflow 0.4.3

SpecFlow is a specification-first CLI for using Chat AI, repository agents, or manual development without losing scope, architecture consistency, verification, checkpoints, or traceability.

Version 0.4.3 keeps the architecture-once, repository-aware just-in-time vertical-slice model introduced in 0.4.0 and hardens Result Pack validation, optional control files, focused retry state, large-Slice context handling, post-import Run consistency, stale Run reconciliation, and Agentic AI operation. It keeps the existing specification, README, Blueprint, official scaffold, transactional import, and verification workflow, but removes the need to generate hundreds of capability contracts, future tasks, test work items, and implementation prompts before coding begins.

Install

npm install -g @buildifyx/[email protected]
sf --version

A local package can be installed with:

npm install -g ./buildifyx-specflow-0.4.3.tgz

Node.js 20 or newer is required.

Why the execution model changed

Planning every future function, import, test, and filename before source code exists causes drift. One task may plan an exported function named add, while a later pre-generated task assumes plus. The later task was written against a predicted repository rather than the repository that actually exists.

SpecFlow 0.4.3 plans in two levels:

approved specification
→ one system architecture
→ one vertical slice generated from the latest repository
→ import, test, verify, checkpoint
→ rescan repository
→ next vertical slice

A large single prompt for the whole product is also avoided. Architecture is created from the complete system context once, while implementation remains bounded, reviewable, retryable, and verifiable one observable slice at a time.

What remains unchanged

• sf init for new projects and sf adopt for existing projects.
• The approved *-spec.md remains the source of requirements.
• README is generated from the approved specification.
• Blueprint and official framework/tool initializers remain required.
• Explicit repository paths in the specification remain authoritative; out-of-scope technology names cannot invent extra workspaces.
• Docker policy, allowed paths, forbidden paths, transactional import, verification, checkpoints, receipts, and traceability remain.
• Chat, Agent, and Manual execution modes remain.
• Low-level sf next and sf done remain for diagnostics and compatibility.

New project workflow

sf init
→ create/apply <project>-spec.md
→ create/apply README.md
→ Blueprint
→ official scaffolds and foundation work
→ WI-SYSTEM-ARCHITECTURE
→ canonical registries and SLICE_INDEX
→ vertical Slice Packs
→ sf verify final

Typical commands:

sf init
sf spec create
sf spec apply
sf readme create
sf readme apply
sf blueprint check
sf scaffold check
sf use chat
sf run

When the architecture Run completes:

sf architecture check
sf slices check
sf run estimate
sf run

Existing project workflow

sf adopt
sf update project
sf doctor --fix
sf run

SpecFlow scans the current repository and generates:

.specflow/repository/REPO_FACTS.json
.specflow/repository/EXPORTS.json
.specflow/repository/IMPORTS.json

The architecture classifies each slice:

• ADOPTED_COMPLETE — repository evidence supports the complete slice;
• ADOPTED_PARTIAL — some implementation exists but the slice is incomplete;
• NEW — the slice has not been implemented;
• AMBIGUOUS — evidence is insufficient or conflicts.

File existence alone is not proof of behavior. Architecture receives prior checkpoints and import receipts as migration evidence.

System architecture

The first AI planning work after foundations is WI-SYSTEM-ARCHITECTURE. It reads the full approved specification, README, Blueprint, current repository facts, and migration evidence. It creates:

.specflow/architecture/
├── REQUIREMENTS.json
├── ARCHITECTURE.json
├── MODULE_REGISTRY.json
├── INTERFACE_REGISTRY.json
├── DATA_MODEL.json
├── HTTP_API_CONTRACT.json
├── SOCKET_CONTRACT.json
├── NAMING_POLICY.json
├── DECISIONS.json
└── SLICE_INDEX.json

Stable IDs are used throughout:

REQ-*    atomic requirement
MOD-*    module owner
INT-*    canonical interface
SLICE-*  observable vertical slice
AC-*     acceptance criterion

INTERFACE_REGISTRY.json prevents caller/callee naming drift:

{
  "id": "INT-CALCULATOR-ADD",
  "ownerModuleId": "MOD-CALCULATOR",
  "kind": "function",
  "canonicalName": "add",
  "file": "src/calculator.js"
}

Every later slice must use add unless an explicit architecture change is approved.

Architecture validation checks unique IDs, dependency cycles, module ownership, interface ownership, portable paths, slice dependencies, acceptance-criteria coverage, and requirement coverage.

Vertical slices

A vertical slice delivers one observable outcome across all necessary layers. A login slice may include:

frontend login popup
backend login endpoint
session use case
cookie policy
Redis session state
acceptance tests
integration verification

It is not divided into unrelated file-by-file prompts.

Before every Slice Pack, SpecFlow rescans the repository and writes a fresh context under:

.specflow/slices/<slice>/CURRENT_CONTEXT.json

The Pack includes current architecture registries, repository facts, actual exports/imports, relevant existing files, acceptance criteria, required tests, required implementation files, and verification commands.

Repository truth and actual exports are fresher than old generated assumptions, while the approved canonical interface registry remains the public contract.

Context strategy in 0.4.3

Chat and Agent modes intentionally use different context transports:

Chat mode
→ required context is measured before Pack creation
→ the budget can expand automatically up to the hard safety limit
→ large source context is written as indexed chunks
→ CONTEXT_MAP.json records every source and chunk

Agent mode
→ registered files remain in the repository
→ RUN_ITEM.md contains targeted paths and a compact objective preview
→ the agent opens only the required sections on demand
→ no Chat Pack character budget applies

Required Chat context is never silently discarded. If even the hard safety limit is exceeded, SpecFlow reports SF_RUN_PROMPT_CONTEXT_TOO_LARGE and removes the incomplete active Run directory.

Chat mode

Set Chat mode once:

sf use chat
sf run

The current Pack is published to a visible folder:

specflow-handoff/send-to-chat/CHAT_PACK-001.zip

The AI returns exactly:

RESULT_PACK.zip

Place it at:

specflow-handoff/return-from-chat/RESULT_PACK.zip

Then run:

sf run inspect
sf run import --dry-run
sf run import

The required result tree remains:

RESULT_PACK/
└── WORK_ITEMS/
    └── <EXACT_WORK_ID>/
        └── files/
            └── <exact repository-relative paths>

For a vertical slice, all required acceptance-test and implementation files must be present. Missing files, unsafe paths, unknown Work IDs, path collisions, out-of-scope files, invalid architecture JSON, or stale Run ownership fail before repository writes.

After successful import, the submitted ZIP is archived beside IMPORT_RECEIPT.json and the visible input is consumed. On failure, the ZIP remains available until sf run retry; retry then archives it under .specflow/runs/active/retries/<timestamp>/, clears the return inbox, and publishes a focused repair Pack containing all captured errors.

Agent mode

The package includes a dedicated Agentic AI handbook:

README_AGENT.md                 distributable Agent README
AGENT_GUIDE.md                  package-level operational guide
.specflow/AGENT_GUIDE.md        installed project guide

Repository agents must read .specflow/AGENT_GUIDE.md before editing. Start with:

sf use agent
sf run

Give the generated AGENT_RUN.md to the repository agent once. The agent loops internally:

sf run item next
sf run item done --agent <agent-name>

Every slice keeps its own allowed paths, verification, checkpoint, and history.

Run reconciliation

A Work Item can finish successfully while preparation of the following Pack fails. In 0.4.3 the completed checkpoint and receipt remain valid, the submitted Result Pack is consumed, and the Run becomes BLOCKED_NEXT_PACK instead of pointing back to finalized work.

Recover with:

sf run reconcile

Reconciliation can also clear stale finalized Pack references and safely retire accidental placeholder Architecture revisions created by the old sf reopen ... --reason "Describe the correction" guidance. sf reopen is now blocked while a Run is active and cannot create duplicate unresolved revisions.

Doctor checks these inconsistent states and preflights whether the next Ready Work Item can generate a usable Chat or Agent context.

Contract-change protocol

A normal slice cannot silently rename or alter an approved INT-* interface. When a change is truly required, the AI returns only the optional request path declared in the Pack, for example:

.specflow/changes/slice-member-session.json

The request identifies:

{
  "sliceId": "SLICE-MEMBER-SESSION",
  "interfaceId": "INT-AUTH-REFRESH",
  "currentCanonicalName": "refreshSession",
  "requestedCanonicalName": "renewSession",
  "reason": "...",
  "impactedFiles": ["..."]
}

SpecFlow reports SF_RUN_CONTRACT_CHANGE_REQUESTED and performs no project write. The change must be approved through architecture revision or rejected before implementation continues.

Specification changes

After editing the approved specification:

sf sync

In the 0.4.x execution model, sf sync:

1. updates the specification index and Blueprint;
2. archives the previous architecture;
3. preserves source code, completed checkpoints, receipts, and imported output;
4. marks old slices for reconciliation;
5. creates one WI-SYSTEM-ARCHITECTURE-R# revision;
6. regenerates and reconciles the Slice Index after the revision is imported.

It does not recreate hundreds of legacy Contract/Task/Test/Implementation items.

Migration from 0.3.x

Install 0.4.3, then run:

sf update project
sf doctor --fix
sf status
sf run

Migration creates:

.specflow/migrations/0.4.0/
├── legacy-execution-plan-<timestamp>.json
└── MIGRATION_EVIDENCE.json

It also archives an active legacy Run when present. Completed legacy work remains completed evidence. Unfinished legacy planning artifacts are retired from the active plan and recorded in MIGRATION_EVIDENCE.json. They are not sent to Chat again. The new architecture uses the current source, checkpoints, receipts, and requirements to decide which slices are complete, partial, new, or ambiguous.

Do not reimport archived SUBMITTED_RESULT_PACK.zip files one by one.

0.4.3 Result Pack validation and retry recovery

Optional control files are now distinct from normal output files. A vertical Slice may allow a contract-change request, but the AI must omit that path unless a real interface change is requested. Empty files, blank JSON objects, and template-only requests are ignored and never written to the repository.

requiredFiles  → must be returned
allowedFiles   → may be returned within scope
optionalFiles  → return only for a real control action; never as a template

A non-empty but incomplete optional request is a real validation failure. sf run inspect and sf run import --dry-run now record that failure on the active Run without changing project files:

WAITING_FOR_RESULT_PACK
→ validate returned archive
→ BLOCKED
→ sf run retry
→ archive invalid result
→ clear managed return inbox
→ publish focused repair Pack

Repeated inspect or resume calls do not re-enter the same loop. They report SF_RUN_BLOCKED and point to sf run retry. The archive SHA-256 fingerprint prevents the same invalid file from incrementing attempts or duplicating failure records more than once.

For a Result Pack supplied by explicit path, retry archives a copy as evidence but preserves the external source file. Managed visible/internal inbox copies are archived and removed.

Doctor now reports this state as unhealthy and recommends:

sf run retry

Architecture Result Packs still receive aggregate semantic preflight in both:

sf run inspect
sf run import --dry-run

All detectable Architecture errors are included in one focused repair context instead of being revealed one retry at a time.

Commands

Preparation

sf init
sf adopt
sf spec create|apply|check
sf readme create|apply|check
sf blueprint create|prompt|apply|check
sf scaffold show|run|check

Architecture and slices

sf architecture create
sf architecture check
sf architecture status
sf architecture approve
sf slices create
sf slices check
sf slices status
sf slices estimate
sf repository scan

sf architecture create prepares or reports the system-architecture work item; the actual AI output still flows through sf run and sf run import.

Run orchestration

sf run
sf run status
sf run estimate
sf run export
sf run inspect [RESULT_PACK.zip]
sf run import [RESULT_PACK.zip] [--dry-run] [--consume]
sf run retry
sf run pause
sf run resume
sf run reconcile
sf run cancel --confirm
sf run reveal
sf run cleanup [--force]

Project state

sf status
sf doctor [--fix]
sf inspect <WORK_ID>
sf history [WORK_ID]
sf reopen <WORK_ID> --reason "..."
sf sync
sf update check
sf update project
sf verify final
sf verify final --runtime

Run estimates

sf run estimate

Known architecture slices are estimated as one Chat Pack per remaining slice. Focused retries and future specification revisions add extra Packs. Unlike 0.3.x, the estimate is not inflated by separate Contract, Tasks, Test, and Implementation work for every capability.

Final verification

sf verify final is appropriate only when all foundation, architecture, and slice work is complete or explicitly skipped. It checks execution completion, architecture validity, Slice Index synchronization, traceability, acceptance tests, README/Spec/Blueprint readiness, project structure, configured builds/tests, Compose configuration/builds, and optional runtime startup.

A completed Run wave is not the same as a completed project.

Docker policy

When Docker is selected:

• root docker-compose.yml is the complete production stack;
• root docker-compose.dev.yml is the complete development stack;
• service Dockerfiles stay inside owning workspaces;
• no docker-compose.prod.yml or generic root docker/ directory is generated unless explicitly approved;
• MongoDB/Prisma replica-set infrastructure is generated only when the Blueprint requires it.

Safety and portability

The built-in ZIP implementation uses Node.js and does not require operating-system zip or unzip commands. It normalizes separators and rejects traversal, absolute paths, drive paths, symlinks, encrypted entries, Windows device names, case/Unicode collisions, unsafe compression ratios, unknown Work IDs, and ambiguous nested archives.

One harmless platform wrapper containing exactly one Result Pack and known OS metadata can be removed automatically.

Low-level compatibility

sf next, sf use chat|agent|manual, and sf done remain available for one-item debugging and compatibility. The primary 0.4.3 workflow is sf run. Do not mix low-level commands with items owned by an active Run.

License

MIT