[Phase 5] Unified CODEFRAME.md Workflow Config

[frankbria]

Summary

Consolidate CodeFrame's scattered configuration (AGENTS.md, CLAUDE.md, workspace config, CLI flags) into a single CODEFRAME.md file that combines runtime config, agent prompts, and execution settings — inspired by Symphony's WORKFLOW.md pattern.

Motivation

Currently CodeFrame configuration is spread across:

• AGENTS.md / CLAUDE.md — project preferences for the agent
• Workspace config in .codeframe/ — tech stack, workspace path
• CLI flags — engine selection, verbose mode, parallel limits
• Environment variables — API keys, rate limits

Symphony's WORKFLOW.md approach is elegant: one version-controlled Markdown file with YAML front matter for typed config and a Markdown body for the agent prompt template. This makes configuration discoverable, version-controlled, and team-shareable.

Design

A CODEFRAME.md file at the project root:

---
engine: react
tech_stack: "Python with uv, pytest, ruff"
batch:
  max_parallel: 4
  default_strategy: auto
gates:
  - ruff
  - pytest
hooks:
  before_task: "git checkout -b cf/{{task_id}}"
  after_task_success: "git add -A"
agent:
  max_iterations: 30
  verbose: false
---

# Project Agent Instructions

You are working on a Python REST API project using FastAPI...

## Coding Standards
- Use type hints everywhere
- Follow PEP 8
...

Backward Compatibility

• CODEFRAME.md takes precedence if present
• Falls back to AGENTS.md / CLAUDE.md if no CODEFRAME.md found
• cf init can generate a starter CODEFRAME.md from detected settings

Scope

This is a single-session task since it's primarily a config loading refactor:

1. Define CODEFRAME.md schema (YAML front matter + Markdown body)
2. Add parser in core/agents_config.py with precedence: CODEFRAME.md > AGENTS.md > CLAUDE.md
3. Extract typed config from front matter (engine, tech_stack, batch settings, gates, hooks)
4. Use Markdown body as agent system prompt supplement
5. Add cf init --generate-config to create starter CODEFRAME.md
6. Update documentation

Acceptance Criteria

• CODEFRAME.md parsed with YAML front matter + Markdown body
• Typed config extracted: engine, tech_stack, batch, gates, hooks, agent settings
• Markdown body used as agent prompt supplement
• Backward compatible: falls back to AGENTS.md/CLAUDE.md
• cf init --generate-config creates starter file from detected settings
• Existing tests still pass (no regression)
• Unit tests for new parser

Dependencies

• Benefits from [Phase 4] Workspace Lifecycle Hooks System #392 (workspace hooks) — hooks config would live here
• No hard dependencies on other issues

[coderabbitai]

🔗 Related PRs

#9 - Merge Sprint 4 Multi-Agent Coordination work into main [merged]
#10 - feat(frontend): Multi-Agent State Management with React Context [merged]
#30 - Review codebase against Claude SDK functionality [closed]
#32 - Fix Key Features section formatting in README [closed]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Plan

Observations

• codeframe/core/agents_config.py has AgentPreferences, load_preferences, and _parse_agents_md with a clear precedence chain and merge logic. pyyaml is already a listed dependency in pyproject.toml.
• codeframe/core/config.py uses pydantic, yaml, and dataclasses for typed config — a consistent pattern to follow for the new schema.
• The init command in codeframe/cli/app.py already handles --detect (calls _detect_tech_stack) and is the entry point for --generate-config.
• tests/core/test_agents_config.py follows the project's @pytest.mark.v2 convention with class-based test groups.

Approach

Extend agents_config.py with a CODEFRAME.md parser that splits YAML front matter from the Markdown body, maps the front matter into a new typed CodeframeConfig dataclass, and rewires load_preferences to check for CODEFRAME.md first. The init command gains a --generate-config flag that writes a starter file using the already-present _detect_tech_stack helper. This keeps all changes within the minimal surface dictated by the ticket.

---

Implementation Steps

1. Define the CodeframeConfig Typed Schema

In file:codeframe/core/agents_config.py, add a set of dataclasses that mirror the YAML front-matter schema:

• BatchConfig — max_parallel: int, default_strategy: str
• HooksConfig — before_task: str | None, after_task_success: str | None
• AgentConfig — max_iterations: int, verbose: bool
• CodeframeConfig — top-level container holding:
  • engine: str
  • tech_stack: str
  • batch: BatchConfig
  • gates: list[str]
  • hooks: HooksConfig
  • agent: AgentConfig
  • prompt_supplement: str — the Markdown body after the front-matter block
  • source_file: str

Use @dataclass with field(default_factory=...) to match the style of the existing AgentPreferences and EnvironmentConfig in config.py.

---

2. Add YAML Front-Matter Parser

Still in file:codeframe/core/agents_config.py, add a private function _parse_codeframe_md(content: str, source_path: str) -> tuple[CodeframeConfig | None, str]:

• Split on the --- delimiter. The file is valid only if it starts with --- and contains a second ---.
• Use yaml.safe_load (already imported via pyyaml dependency) on the extracted block.
• Deserialize into CodeframeConfig — handle missing optional keys gracefully using .get() with defaults.
• Return the CodeframeConfig and the remaining Markdown body (the prompt supplement).
• Return (None, content) if parsing fails (malformed YAML, missing delimiter, etc.) so the caller can fall back gracefully.

---

3. Add load_codeframe_config Function

Add a public function load_codeframe_config(workspace_path: Path) -> CodeframeConfig | None:

• Check for CODEFRAME.md at workspace_path / "CODEFRAME.md".
• Read it, call _parse_codeframe_md, and return the result.
• Return None if no file is found or parsing yields no result.

---

4. Update load_preferences to Honour CODEFRAME.md Precedence

Modify the existing load_preferences(workspace_path) function in file:codeframe/core/agents_config.py:

Precedence (highest → lowest):
  CODEFRAME.md  >  AGENTS.md  >  CLAUDE.md  >  parent dirs  >  ~/.codeframe/AGENTS.md  >  defaults

• At the very start of load_preferences, call load_codeframe_config(workspace_path).
• If a CodeframeConfig is found:
  • Use its prompt_supplement as the raw_content of the resulting AgentPreferences.
  • Propagate tech_stack, gates, hooks, batch, and agent settings onto the returned object or expose them as a parallel data structure (see step 5).
  • Still append source_files with the CODEFRAME.md path.
  • Skip the normal AGENTS.md/CLAUDE.md search for the workspace root — those files remain as fallback when CODEFRAME.md is absent.

---

5. Expose CodeframeConfig to Callers

To allow the CLI and other consumers to read structured config (engine, batch, gates, hooks, agent settings), expose load_codeframe_config as a public API from agents_config. Callers that currently call load_preferences for the system prompt can also call load_codeframe_config for the typed settings.

Update AgentPreferences docstring and source_files to document that CODEFRAME.md is now a valid source.

---

6. Add --generate-config to cf init

In file:codeframe/cli/app.py, inside the init command:

• Add a new Typer option: generate_config: bool = typer.Option(False, "--generate-config", help="Generate a starter CODEFRAME.md from detected settings")
• After the workspace is created/loaded and final_tech_stack is resolved (which may come from --detect), if --generate-config is set:
  • Check if CODEFRAME.md already exists at repo_path; if so, print a warning and skip (or prompt to overwrite).
  • Call a new helper _generate_codeframe_md(repo_path, tech_stack) (private, defined in the same file or in agents_config.py).
  • This helper builds the YAML front-matter from detected/provided settings and a default Markdown body template, then writes CODEFRAME.md to repo_path.
  • Print confirmation: CODEFRAME.md created at {repo_path}/CODEFRAME.md.

The generated file should follow the schema defined in step 1, e.g.:

---
engine: react
tech_stack: "<detected or provided value>"
batch:
  max_parallel: 4
  default_strategy: auto
gates:
  - ruff
  - pytest
hooks:
  before_task: null
  after_task_success: null
agent:
  max_iterations: 30
  verbose: false
---

# Project Agent Instructions

You are working on a project with the following tech stack: <tech_stack>.

## Coding Standards
- Follow existing conventions in the codebase
...

Use yaml.dump (already available) to serialize the front matter block programmatically so keys are consistent.

---

7. Wire CodeframeConfig Into Existing Consumers

Identify callers of load_preferences in the codebase (e.g. the ReAct agent, work start command path) — use grep_search for load_preferences if needed during implementation. For each caller that also needs the typed settings (engine, gates, etc.), update them to also call load_codeframe_config and read the structured fields instead of relying solely on the flat AgentPreferences.tooling dict.

---

8. Add Unit Tests

In file:tests/core/test_agents_config.py, following the existing @pytest.mark.v2 class-based convention, add:

Test Class	Key Tests
TestCodeframeConfig	Dataclass defaults, field presence
TestParseCODEFRAMEMd	Full file, front-matter only, body only, malformed YAML, missing delimiter
TestLoadCodeframeConfig	File found and parsed, file not found returns None, file with only front matter
TestLoadPreferencesWithCodeframeMd	CODEFRAME.md takes precedence over AGENTS.md; fallback to AGENTS.md when absent; prompt_supplement becomes raw_content

---

Flow Diagram

sequenceDiagram
    participant CLI as cf init / cf work
    participant LP as load_preferences()
    participant LC as load_codeframe_config()
    participant FM as _parse_codeframe_md()
    participant YAML as yaml.safe_load

    CLI->>LP: load_preferences(workspace_path)
    LP->>LC: load_codeframe_config(workspace_path)
    LC-->>FM: CODEFRAME.md content
    FM->>YAML: parse front matter
    YAML-->>FM: dict
    FM-->>LC: CodeframeConfig + prompt_supplement
    LC-->>LP: CodeframeConfig (or None)
    alt CODEFRAME.md found
        LP-->>CLI: AgentPreferences(raw_content=prompt_supplement, source_files=[CODEFRAME.md])
    else Fallback
        LP->>LP: search AGENTS.md / CLAUDE.md (existing logic)
        LP-->>CLI: AgentPreferences (merged from legacy files)
    end

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `codeframe/core/agents_config.py` has `AgentPreferences`, `load_preferences`, and `_parse_agents_md` with a clear precedence chain and merge logic. `pyyaml` is already a listed dependency in `pyproject.toml`.
- `codeframe/core/config.py` uses `pydantic`, `yaml`, and dataclasses for typed config — a consistent pattern to follow for the new schema.
- The `init` command in `codeframe/cli/app.py` already handles `--detect` (calls `_detect_tech_stack`) and is the entry point for `--generate-config`.
- `tests/core/test_agents_config.py` follows the project's `@pytest.mark.v2` convention with class-based test groups.

## Approach

Extend `agents_config.py` with a `CODEFRAME.md` parser that splits YAML front matter from the Markdown body, maps the front matter into a new typed `CodeframeConfig` dataclass, and rewires `load_preferences` to check for `CODEFRAME.md` first. The `init` command gains a `--generate-config` flag that writes a starter file using the already-present `_detect_tech_stack` helper. This keeps all changes within the minimal surface dictated by the ticket.

---

## Implementation Steps

### 1. Define the `CodeframeConfig` Typed Schema

In `file:codeframe/core/agents_config.py`, add a set of dataclasses that mirror the YAML front-matter schema:

- `BatchConfig` — `max_parallel: int`, `default_strategy: str`
- `HooksConfig` — `before_task: str | None`, `after_task_success: str | None`
- `AgentConfig` — `max_iterations: int`, `verbose: bool`
- `CodeframeConfig` — top-level container holding:
  - `engine: str`
  - `tech_stack: str`
  - `batch: BatchConfig`
  - `gates: list[str]`
  - `hooks: HooksConfig`
  - `agent: AgentConfig`
  - `prompt_supplement: str` — the Markdown body after the front-matter block
  - `source_file: str`

Use `@dataclass` with `field(default_factory=...)` to match the style of the existing `AgentPreferences` and `EnvironmentConfig` in `config.py`.

---

### 2. Add YAML Front-Matter Parser

Still in `file:codeframe/core/agents_config.py`, add a private function `_parse_codeframe_md(content: str, source_path: str) -> tuple[CodeframeConfig | None, str]`:

- Split on the `---` delimiter. The file is valid only if it starts with `---` and contains a second `---`.
- Use `yaml.safe_load` (already imported via `pyyaml` dependency) on the extracted block.
- Deserialize into `CodeframeConfig` — handle missing optional keys gracefully using `.get()` with defaults.
- Return the `CodeframeConfig` and the remaining Markdown body (the prompt supplement).
- Return `(None, content)` if parsing fails (malformed YAML, missing delimiter, etc.) so the caller can fall back gracefully.

---

### 3. Add `load_codeframe_config` Function

Add a public function `load_codeframe_config(workspace_path: Path) -> CodeframeConfig | None`:

- Check for `CODEFRAME.md` at `workspace_path / "CODEFRAME.md"`.
- Read it, call `_parse_codeframe_md`, and return the result.
- Return `None` if no file is found or parsing yields no result.

---

### 4. Update `load_preferences` to Honour `CODEFRAME.md` Precedence

Modify the existing `load_preferences(workspace_path)` function in `file:codeframe/core/agents_config.py`:

```
Precedence (highest → lowest):
  CODEFRAME.md  >  AGENTS.md  >  CLAUDE.md  >  parent dirs  >  ~/.codeframe/AGENTS.md  >  defaults
```

- At the very start of `load_preferences`, call `load_codeframe_config(workspace_path)`.
- If a `CodeframeConfig` is found:
  - Use its `prompt_supplement` as the `raw_content` of the resulting `AgentPreferences`.
  - Propagate `tech_stack`, `gates`, `hooks`, `batch`, and `agent` settings onto the returned object or expose them as a parallel data structure (see step 5).
  - Still append `source_files` with the `CODEFRAME.md` path.
  - **Skip** the normal `AGENTS.md`/`CLAUDE.md` search for the workspace root — those files remain as fallback when `CODEFRAME.md` is absent.

---

### 5. Expose `CodeframeConfig` to Callers

To allow the CLI and other consumers to read structured config (engine, batch, gates, hooks, agent settings), expose `load_codeframe_config` as a public API from `agents_config`. Callers that currently call `load_preferences` for the system prompt can also call `load_codeframe_config` for the typed settings.

Update `AgentPreferences` docstring and `source_files` to document that `CODEFRAME.md` is now a valid source.

---

### 6. Add `--generate-config` to `cf init`

In `file:codeframe/cli/app.py`, inside the `init` command:

- Add a new Typer option: `generate_config: bool = typer.Option(False, "--generate-config", help="Generate a starter CODEFRAME.md from detected settings")`
- After the workspace is created/loaded and `final_tech_stack` is resolved (which may come from `--detect`), if `--generate-config` is set:
  - Check if `CODEFRAME.md` already exists at `repo_path`; if so, print a warning and skip (or prompt to overwrite).
  - Call a new helper `_generate_codeframe_md(repo_path, tech_stack)` (private, defined in the same file or in `agents_config.py`).
  - This helper builds the YAML front-matter from detected/provided settings and a default Markdown body template, then writes `CODEFRAME.md` to `repo_path`.
  - Print confirmation: `CODEFRAME.md created at {repo_path}/CODEFRAME.md`.

The generated file should follow the schema defined in step 1, e.g.:

```
---
engine: react
tech_stack: "<detected or provided value>"
batch:
  max_parallel: 4
  default_strategy: auto
gates:
  - ruff
  - pytest
hooks:
  before_task: null
  after_task_success: null
agent:
  max_iterations: 30
  verbose: false
---

# Project Agent Instructions

You are working on a project with the following tech stack: <tech_stack>.

## Coding Standards
- Follow existing conventions in the codebase
...
```

Use `yaml.dump` (already available) to serialize the front matter block programmatically so keys are consistent.

---

### 7. Wire `CodeframeConfig` Into Existing Consumers

Identify callers of `load_preferences` in the codebase (e.g. the ReAct agent, `work start` command path) — use `grep_search` for `load_preferences` if needed during implementation. For each caller that also needs the typed settings (engine, gates, etc.), update them to also call `load_codeframe_config` and read the structured fields instead of relying solely on the flat `AgentPreferences.tooling` dict.

---

### 8. Add Unit Tests

In `file:tests/core/test_agents_config.py`, following the existing `@pytest.mark.v2` class-based convention, add:

| Test Class | Key Tests |
|---|---|
| `TestCodeframeConfig` | Dataclass defaults, field presence |
| `TestParseCODEFRAMEMd` | Full file, front-matter only, body only, malformed YAML, missing delimiter |
| `TestLoadCodeframeConfig` | File found and parsed, file not found returns `None`, file with only front matter |
| `TestLoadPreferencesWithCodeframeMd` | `CODEFRAME.md` takes precedence over `AGENTS.md`; fallback to `AGENTS.md` when absent; `prompt_supplement` becomes `raw_content` |

---

### Flow Diagram

```mermaid
sequenceDiagram
    participant CLI as cf init / cf work
    participant LP as load_preferences()
    participant LC as load_codeframe_config()
    participant FM as _parse_codeframe_md()
    participant YAML as yaml.safe_load

    CLI->>LP: load_preferences(workspace_path)
    LP->>LC: load_codeframe_config(workspace_path)
    LC-->>FM: CODEFRAME.md content
    FM->>YAML: parse front matter
    YAML-->>FM: dict
    FM-->>LC: CodeframeConfig + prompt_supplement
    LC-->>LP: CodeframeConfig (or None)
    alt CODEFRAME.md found
        LP-->>CLI: AgentPreferences(raw_content=prompt_supplement, source_files=[CODEFRAME.md])
    else Fallback
        LP->>LP: search AGENTS.md / CLAUDE.md (existing logic)
        LP-->>CLI: AgentPreferences (merged from legacy files)
    end
```

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.