# File Organization — CleverAgents Project

> ⚠️ Rules here override `cleverthis-guidelines`. Apply these exactly.

---

## Directory Map (canonical — no variations permitted)

```
cleveragents/                   ← repository root
│
├─ src/
│   └─ cleveragents/            ← ALL production source code
│       ├─ __init__.py
│       └─ ...                  ← Python packages and modules
│
├─ features/                    ← ALL Behave BDD unit tests
│   ├─ *.feature                ← Gherkin feature files
│   ├─ steps/                   ← step definition files
│   │   └─ *_steps.py
│   └─ mocks/                   ← ALL mocks, fakes, stubs, test doubles
│       └─ ...
│
├─ robot/                       ← ALL Robot Framework tests (integration + e2e)
│   ├─ *.robot
│   └─ *.resource
│
├─ docs/                        ← ALL documentation (MkDocs format)
│   ├─ specification.md         ← authoritative architecture spec
│   └─ *.md
│
├─ config/                      ← configuration files
├─ scripts/                     ← utility scripts (e.g. setup-dev.sh)
├─ examples/                    ← example code
├─ k8s/                         ← Kubernetes Helm chart
├─ benchmarks/                  ← ASV benchmark files
│
├─ pyproject.toml               ← ALL project configuration (root-level standard)
├─ noxfile.py                   ← ALL nox session definitions (root-level standard)
├─ .pre-commit-config.yaml      ← pre-commit hooks (root-level standard)
├─ robot.cfg                    ← Robot Framework config (root-level standard)
├─ README.md
├─ CONTRIBUTING.md
├─ LICENSE
├─ CHANGELOG
└─ CONTRIBUTORS.md
```

---

## Rules Per Directory

### `/src/cleveragents/` — Production Source Only

✅ Permitted:
- Python packages, modules, and subpackages
- Application logic, services, models, utilities

❌ Strictly prohibited:
- Test files of any kind
- Mock, fake, or stub implementations
- Test data or fixtures
- Documentation files
- Example code

**Violation = the import will pollute production in unexpected ways.
Zero exceptions.**

### `/features/` — Behave BDD Unit Tests Only

✅ Permitted:
- Gherkin `.feature` files
- Step definition files in `features/steps/`
- Mock implementations in `features/mocks/`

❌ Strictly prohibited:
- Production source code
- Robot Framework files
- End-to-end test logic

#### `/features/mocks/` — The ONLY place for mocks

This subdirectory is the **exclusive** location for all mocks, fakes, stubs,
fixtures, and test doubles in the entire project.

**Never put mocks in:**
- `src/cleveragents/`
- `scripts/`
- `robot/`
- Anywhere else

### `/robot/` — Robot Framework Tests Only

✅ Permitted:
- `.robot` test files
- `.resource` keyword files

❌ Strictly prohibited:
- Any kind of mocking
- Production source code

**Real services only.** Integration tests exercise actual endpoints,
real databases, real message queues. No test doubles permitted.

### `/docs/` — Documentation (MkDocs Format)

✅ Permitted:
- Markdown files in MkDocs-compatible format
- Images, diagrams, and supporting assets

#### `docs/specification.md` — Authoritative Architecture Spec

This file is **the authoritative source of truth** for all architectural and
design decisions. Rules:

- Read the relevant sections **before beginning any task**
- When code contradicts specification → **fix the code, not the spec**
- Spec changes → ADR process required first; approved ADR → spec update → code update
- Never edit `docs/specification.md` to match broken code

### `/config/` — Configuration Files

Configuration files that are not widely recognized root-level conventions.
Do not put application configuration in root.

### `/scripts/` — Utility Scripts

✅ Permitted:
- Shell scripts and automation utilities (e.g. `setup-dev.sh`)

❌ Strictly prohibited:
- Mock code or test data
- Production source code
- Build artifacts

### `/examples/` — Example Code

Standalone example code demonstrating project usage. Not production code,
not test code — just illustrative examples.

### `/k8s/` — Kubernetes / Helm

Kubernetes Helm chart for server deployment.

### Root Level

Only **widely recognized root-level conventions** belong here:

| File | Why it's at root |
|------|-----------------|
| `pyproject.toml` | Standard Python project manifest |
| `noxfile.py` | Standard nox configuration |
| `.pre-commit-config.yaml` | Standard pre-commit configuration |
| `robot.cfg` | Standard Robot Framework configuration |
| `README.md` | Universal convention |
| `CONTRIBUTING.md` | Universal convention |
| `LICENSE` | Universal convention |
| `CHANGELOG` | Universal convention |
| `CONTRIBUTORS.md` | Universal convention |
| `.forgejo/` | CI/CD workflow definitions |
| `.gitignore` | Universal convention |
| `.gitattributes` | Universal convention |

**Anything else belongs in a subdirectory.**

---

## Placement Decision Table

| What you have | Where it goes |
|---------------|---------------|
| A `.py` module with application logic | `src/cleveragents/` |
| A `.feature` file with Gherkin scenarios | `features/` |
| A `*_steps.py` step definition file | `features/steps/` |
| A mock class, fake, or stub | `features/mocks/` |
| A `.robot` or `.resource` file | `robot/` |
| A markdown doc for MkDocs | `docs/` |
| A config file (not pyproject.toml) | `config/` |
| A shell utility script | `scripts/` |
| Example usage code | `examples/` |
| A Helm chart or k8s manifest | `k8s/` |
| An ASV benchmark module | `benchmarks/` |

---

## BDD Step File Naming Rules (Behave-specific)

1. **Check existing files first.** Before creating any new step file, verify
   whether an existing step file already covers the same behavior. Extend it.

2. **Feature-specific steps** — steps used ONLY by `foo.feature`:
   ```
   features/steps/foo_steps.py
   ```

3. **Shared steps** — steps used by multiple feature files:
   ```
   features/steps/<purpose>_steps.py   # name it after the domain, not a feature
   ```
   Update existing shared files before creating new ones.

4. **Complete implementations only.** Every feature file must be committed
   with all its step definitions fully implemented. Never commit a `.feature`
   file whose steps are not yet implemented.
