# Process & Workflow — defapp

Last updated: 2026-07-22

## Documentation manifest and viewer

- The docs viewer (`defapp.docs.php`) is the canonical entrypoint for project
  documentation.
- All docs under `docs/` that should appear in the viewer MUST be declared in
  `$docManifest` with:
  - `file`
  - `title`
  - `purpose`
  - `useWhen`
- When adding or removing docs:
  - Update `$docManifest`.
  - Run `php -l defapp.docs.php` and `php -d display_errors=stderr -f defapp.docs.php`
    to verify syntax before committing.

## AI-generated code — mandatory syntax testing

- Any code obtained from AI tools MUST be syntax-tested before use.
  - PHP:
    - `php -l file.php` for quick syntax validation.
    - `php -d display_errors=stderr -f file.php` for detailed error output.
  - Bash:
    - `bash -n script.sh` for syntax checking, plus shellcheck for deeper linting.
- Code that fails syntax tests MUST NOT be used until corrected and re-tested.
- For multi-file scaffolds, main scripts (e.g., `newapp.sh`) SHOULD provide a
  verify or lint mode that runs syntax checks on generated scripts and prints
  clear results.

## Build in verified layers

- Large PHP files (like `defapp.docs.php`) MUST be built in layers:
  - Start with a minimal stub that passes `php -l`.
  - Add small, self-contained functions or blocks.
  - Run `php -l` after each addition.
- If a new block causes a syntax error:
  - Inspect that block and the preceding lines for missing semicolons, unclosed
    braces, or comments.
  - Revert to the last passing version and retry with a smaller change.

## Wizards workflow

- Use wizards for multi-step tasks that change multiple files or concepts.
- Each wizard MUST:
  - Define a clear goal and steps in `docs/SPEC.md` or a dedicated wizard doc.
  - Log what it did in `docs/PROJECT_LOG.md`.
  - Trigger updates to `docs/CHANGELOG.md` when behaviour or standards change.
- Wizards should be inherently testable:
  - After running a wizard, there should be a simple command or check to confirm
    that the expected files and docs exist and pass syntax checks.

## When to update docs vs create new versions

- Update existing docs when:
  - You refine behaviour or clarify UX (e.g., updating `UX.md` to reflect the
    current docs viewer).
- Create a new version of standards or templates when:
  - You introduce breaking changes to how apps or docs are generated.
  - You change required files or manifest schema.

Record major changes in:

- `docs/SPEC.md` (requirements)
- `docs/ARCHITECTURE.md` (design)
- `docs/PROCESS.md` (workflow/standards)
- `docs/CHANGELOG.md` (what changed and why)