Managed Files

Each spec should have a clear, well-defined scope — one module, one converter, one CLI tool. But sometimes implementing a spec requires touching files outside that scope. Managed files give you visibility and control over this.

How CodeSpeak tracks files

When you build a spec, CodeSpeak tracks which files it creates or takes over. These are managed files — files that belong to a specific spec and can be freely modified during builds. For example, if main.cs.md produces main.py, then main.py is a managed file for that spec.

Anything else — configuration files, shared dependencies, other modules — is not managed. If CodeSpeak needs to modify one of these files, it notifies you.

Example

Consider a simple CLI app with one spec:

main.cs.md (the spec):

# Hello World Module

## Overview

A simple program that outputs a message "Hello from test!" to console

main.py (generated, managed):

from hello import hello

def main():
    hello()

if __name__ == "__main__":
    main()

pyproject.toml (project config, not managed):

[project]
name = "hello"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = []

Now add a dependency on the rich library by updating the spec:

 # Hello World Module

 ## Overview

-A simple program that outputs a message "Hello from test!" to console
+A simple program that outputs a message "Hello, CodeSpeak!" to console
+
+## Dependencies
+
+Uses `rich` library for nice terminal UI.

codespeak build --skip-tests

The build succeeds — CodeSpeak rewrites main.py and adds rich to pyproject.toml. But after the success message, you'll see:

CodeSpeak modified 1 file not directly managed by the current spec:
  - pyproject.toml

To disallow modifications to non-managed files, add this to codespeak.json:
  "strictManagedFilesControl": true

To suppress this notification, add this to codespeak.json:
  "suppressNonManagedFilesNotification": true

To allow editing these files when working on the current spec, run:
  codespeak update-managed-files 'pyproject.toml'

To always allow editing these files, run:
  codespeak whitelist 'pyproject.toml'

Why the notification

The build worked correctly — CodeSpeak figured out that rich requires a dependency entry. But pyproject.toml affects the entire project. In a multi-spec project, you probably don't want one spec's build silently pulling in dependencies or modifying shared configs.

CodeSpeak doesn't block these changes by default — it makes sure you know they happened and gives you options.

Options

Suppress the notification

{ "suppressNonManagedFilesNotification": true }

Hides the notification. Non-managed files can still be modified.

Block modifications (strict mode)

{ "strictManagedFilesControl": true }

Prevents CodeSpeak from writing to non-managed files during builds. Use with care — if the spec genuinely requires modifying a non-managed file, the build may produce unexpected results.

codespeak update-managed-files — per-spec control

codespeak update-managed-files 'pyproject.toml'

Adds the file to managed files for the current spec only. Other specs still trigger the notification if they try to modify it.

codespeak whitelist — global allowance

codespeak whitelist 'pyproject.toml'

Adds the file to a project-wide whitelist in codespeak.json. Any spec can modify whitelisted files without notifications. Supports glob patterns:

codespeak whitelist 'config/*.yaml'

Summary