Feature Development Workflow

Feature Development Workflow

Beez features are implemented vertically: from user story through tests and all affected layers to a green make all. Avoid changing only one layer (for example core models with no DSL binding or tests).

What "vertical" means

User story + acceptance criteria
↓
Tests first (unit → integration → system) ← TDD
↓
Core (models, registry, orchestrator)
↓
Plugins (Lua DSL, shell executor)
↓
CLI (when user-visible behavior changes)
↓
Documentation (wiki, CHANGELOG, in-repo docs)
↓
Refactor + make all (coverage ≥ 85% on src/)

Not vertical: extend Registry with no Lua parser change and no tests.

Vertical: the user can use the feature via build.lua or CLI, and every applicable test level passes.

Step 1: Define the user story

Before coding, write down:

• What the user should be able to do
• Acceptance criteria (concrete, testable)
• Affected layers (core, lua plugin, orchestrator, CLI)

Example:

As a user, I want tasks to declare depends_on so that execution order respects dependencies.

Layers: Task model, Registry, Lua DSL, Orchestrator, unit + integration + system tests.

Step 2: TDD (Red → Green → Refactor)

Red

1. Pick the smallest testable slice of an acceptance criterion
2. Write the test at the appropriate level (unit first)
3. Register the file in CMakeLists.txt
4. Run tests and confirm failure (compile error or assertion)

Green

1. Implement the minimum code to pass
2. Work inside-out: core → plugins → orchestrator/CLI
3. Re-run tests until green

Refactor

1. Clean naming, remove duplication
2. Run tests after each change
3. Run make format and make lint-stale as needed

Repeat for each acceptance criterion.

Step 3: Choose test levels

Change type	Minimum tests
Pure function / model	Unit
DSL field or syntax	Unit (lua) + integration
Run behavior / exit codes	Integration + system fixture
Parser grammar change	Unit + fuzz seed

See Testing for directory conventions.

Step 4: Implementation order

Core

1. Types in include/beez/core/
2. Logic in src/core/
3. Update src/core/CMakeLists.txt

Plugins

• Lua (src/plugins/lua/lua_dsl.cpp, lua_settings.cpp): parse new DSL keys
• Shell (src/plugins/shell/): only when command execution changes

Orchestrator

• src/core/orchestrator.cpp when scheduling, cache, or progress behavior changes

CLI

• src/cli/ and rarely src/app/main.cpp for new flags or commands

Step 5: DSL / parser changes

When lua_dsl.cpp or DSL syntax changes:

1. Add a descriptive seed: tests/fuzz/corpus/lua_dsl/<name>.lua
2. Run make fuzzer-smoke
3. Never commit fuzzer hash artifacts

Step 6: Documentation

Documentation is part of the vertical slice, not a follow-up PR.

Wiki

Update the wiki when users see different behavior. Common pages:

Area	Pages
CLI	CLI Flag Reference, CLI Overview, Quick Reference
Config	Config Reference, Configuration Overview
DSL	DSL Overview, declaration pages
Cache	Caching chapter
UI	UI and Output chapter
Contributors	Feature Development Workflow, Code Quality, Building and Setup

The wiki is a separate git repository on GitHub. Push wiki updates before or immediately after merging code.

In-repository

• CHANGELOG.md for user-visible changes
• README.md for quick start and install changes
• docs/ for developer workflow (repo docs/README.md)

Step 7: Finish with QA

make all

Do not mark a feature done until the full pipeline passes. Line coverage on src/ must be ≥ 85% (make coverage, enforced in CI). If CI fails, fix and rerun.

Per-feature checklist

Copy into a PR description:

[ ] User story and acceptance criteria documented
[ ] Failing tests written first (Red)
[ ] Minimum implementation (Green)
[ ] Refactor pass, tests still green
[ ] Core updated
[ ] Plugins updated (if DSL/execution affected)
[ ] Orchestrator/CLI updated (if needed)
[ ] CMakeLists.txt updated for new files
[ ] Unit tests (positive + negative)
[ ] Integration tests (if components interact)
[ ] System fixture + scenario (if end-to-end)
[ ] Fuzz seed (if DSL/parser changed)
[ ] Wiki updated (if user-visible behavior changed)
[ ] CHANGELOG.md / README / docs updated (as appropriate)
[ ] make coverage ≥ 85% on src/
[ ] make all green

Prompt template (for AI-assisted work)

Implement feature: <short description>
User story:
As a <role>, I want <action> so that <benefit>.
Acceptance criteria:
- ...
- ...
Implement vertically with TDD (Red → Green → Refactor).
Update wiki and CHANGELOG for user-visible changes.
Run make all before finishing (coverage ≥ 85% on src/).

Anti-patterns

• Production code before tests
• Tests deferred to a follow-up PR
• Only make test while skipping format, lint, fuzz, sanitizers, or coverage
• User-visible merge without wiki or CHANGELOG update
• Line coverage on src/ below 85%
• New .cpp files not added to CMake
• Nested module directories under src/

Related pages

• Repository Layout - file placement
• Testing - test types and fuzz corpus
• Code Quality - make all breakdown
• Submitting Changes - PR and CI