AGENTS.md · plasma-ai/fractal

Sections

1. Overview
2. Build & Development
3. Consistency
4. Templates
5. Scope Discipline
6. Principled Solutions
7. Communication
8. Pushing Back
9. Thinking Before Coding
10. Testing
11. Wiki Maintenance
12. Code Style

First lines (shown under the repo's Apache-2.0 license)

# AGENTS

This file provides guidance to coding agents (Claude Code, Codex) when working
with code in this repository. If you are not Claude Code (which already reads
parent directories), also check the parent directory for `AGENTS.md`.

Especially important points to keep in mind (each expanded in its section
below):

- **Questions are not edit requests.** When a message asks a question without
  explicitly requesting a change, answer and stop (Communication).
- **Write clear and concise English.** Write clear, concise, plain English which
  can be quickly and easily parsed by the user — answer questions directly in
  short form unless elaboration is requested (Writing Style).
- **Seek the best solution, not agreement.** When you think the user is wrong,
  don't be afraid to say so — the right answer matters more than the path of
  least resistance (Pushing Back).
- **Choose solutions that generalize.** Define the requirement before choosing
  an approach. Consider alternatives and base each choice on the problem and
  known constraints. Do not choose an approach for convenience or overfit it to
  the cases tried during development (Principled Solutions).

## Overview

`plasma-fractal` is a standalone plugin providing the **fractal** skill.

The `fractal/` package is organized into `cli/` (typer app), `core/` (business
logic), `tui/` (Textual app), `impl/` (provider backends), `skills/` (the plugin
skill), `util/` (shared utilities), and the node machinery seeds — `_assets/`,
`_node/`, and `_scripts/` — with the pytest suite in `tests/`.

`shim/` holds the metadata-only `fractal` pointer dist for PyPI: no code, just
an exact `plasma-fractal==<version>` pin that bumps in lockstep with every
release surface. The build workflow gates and builds it alongside the main
package, and the publish job uploads both dists — both PyPI projects must trust
that workflow (same repository, workflow file, and environment) as their
publisher.

`Node` delegates lifecycle operations to the `_scripts/` shell scripts via
`subprocess.run()`. The iteration loop is in-process Python: `start.sh` execs
`fractal node _loop` inside the tmux session, and `Loop`
(`fractal/core/loop.py`) drives each iteration end to end — prompt assembly,
agent launches, run/iter/step row accounting through `node.record`, and the
work-product commit pipeline in `fractal/core/commit.py`.

Agent invocation is a core/impl seam: `fractal/core/agent.py` defines the
`Agent` base class (invocation argv, stream parsing, cost and logging hooks)
plus the name registry (`resolve`/`register`/`supported`), and
`fractal/impl/{claude,codex,grok,opencode,omp}.py` are the provider backends — a
new provider slots in as one new `impl/` module registered in `core/agent.py`.

## Build & Development

```bash
# install dev dependencies (creates a .venv if none is active)
./install.sh --all-extras --groups=test,lint,type

# or set up the environment manually
uv sync --all-extras --group test --group lint --group type
uv run pre-commit install

# run tests
uv run --no-sync pytest

# run pre-commit
uv run --no-sync pre-commit run [--all-files]

# run type check (not enforced)
uv run --no-sync pyright

# run security scan (not enforced)
uv sync --inexact --group security
uv run --no-sync safety scan
```

The test suite uses `pytest` with `--doctest-modules` enabled. Integration tests
create real git repos and worktrees — session-scoped to avoid repeated
`fractal node init` overhead.

- **No edits to the tree while its tests run.** A session guard digests the
  package's seed trees (`_assets/`, `_node/`, `_scripts/`, `skills/`) before and
  after the run and fails on any drift, naming each added, removed, and changed
  path. It cannot tell a test writing through a package path from an edit made
  mid-run, so an edit during the run fails the suite as if a test had made it —
  wait for the run to end.

## Consistency

The single most important pattern in this codebase is the pattern of **adhering
to patterns**. Every convention documented here exists so that the code reads as
if one person wrote it. This matters more than any individual style preference
because it enables:

- **Fast visual scanning** — when code follows predictable shapes, deviations
  jump out immediately
- **Regex-based refactoring** — consistent patterns mean find-and-replace works
  across the codebase
- **Trustworthy AI-generated code** — the user must be able to review the
  agent's output and have it look indistinguishable from their own

When writing or modifying code:

1. **Read the surrounding code first.** Match its patterns exactly — variable
   names, comment style, line breaking, method ordering, everything.
2. **Do not silently "improve" patterns.** If the existing code uses a
   particular structure, use that same structure in your current task. But if
   you see a genuinely better convention — clearer, safer, more idiomatic —
   **propose it explicitly.** The priority is consistency, not preservation of
   the status quo. Consistently good beats consistently bad, so make the case
   for why a change is worth the churn and the user will adopt it.
3. **Do not rename variables** that shadow outer scopes if it is sensible to
   reuse that variable name (and is unlikely to become a bug).
4. **Do not reformat** existing comments, reorder methods, or restructure
   working code unless specifically asked.
5. **Do not remove comments.** Line-by-line comments are intentional — they help
   the user maintain order and scan code quickly. Emulate existing comment
   patterns in new code.
6. **When in doubt, emulate.** Find the nearest analogous code in the codebase
   and mirror its structure.
7. **End files with a trailing newline.** Every committed file ends with one —
   the `end-of-file-fixer` hook enforces it.

### Adapting to the Codebase

The patterns documented here are a starting point, not an exhaustive rulebook.
The codebase is the authoritative style guide — these docs just accelerate your
ramp-up.

- **Pattern discovery over pattern memorization.** When working in a file, treat
  the local code as the authority. If a file uses a pattern not documented here,
  adopt it — don't introduce the documented pattern as a "correction."
- **Resolve conflicts in favor of local code.** If a documented pattern
  conflicts with what you see in the file you're editing, follow the file. Flag
  the discrepancy but don't "fix" it unilaterally.
- **New patterns propagate by observation.** The codebase evolves. When you
  encounter a pattern that's clearly intentional but not documented, follow it
  in your new code. The user will correct you if it's a mistake.
- **Scan before writing.** Before adding a new method, class, or module, find a
  few analogous examples in the codebase and mirror their structure. This
  applies to everything: error handling shape, docstring phrasing, test
  organization, import style, comment density.
- **Keep these docs up to date.** When you discover conventions or patterns
  through the user's feedback or codebase observation that aren't yet
  documented, add them to the appropriate `AGENTS.md`: repo-specific conventions
  belong in the repo's own file; org-wide conventions belong in the shared
  sections, which are maintained at the organization level — make shared-section
  changes at the org root (or flag them for promotion) and propagate them to
  repo copies.

**Propose better conventions.** If you see a pattern that could be improved
across the codebase — a more readable structure, a safer error handling
approach, a cleaner naming convention — say so. Explain *why* it's worth the
migration cost. The user values consistency over any particular style, and will
always prefer being consistently good over consistently familiar. The rule is:
don't deviate silently, but do advocate openly.

## Templates

When updating boilerplate files like build configs, linter configs, CI configs,
etc. (e.g. `pyproject.toml`, `.pre-commit-config.yaml`), always check whether