automaton/ONBOARDING.md

# Onboarding a New Project

## Quick Checklist

- [ ] Create `.agent-framework/` directory in project root
- [ ] Create `AGENT.md` (project level)
- [ ] Create `RULES.md` (project level)
- [ ] Run exploration ritual with agent (fresh session)
- [ ] Agent reads global + project AGENT.md and RULES.md
- [ ] Agent reports back
- [ ] Create first `tasks/{task-name}/` folder
- [ ] Start research phase using `prompts/research.md`

This is the exact sequence to follow when bringing any new project into the framework.

## Prompt Rendering Convention

All prompts are stored as template files in `~/.agent-framework/prompts/`. They use `{placeholder}` syntax.

### Placeholders

| Placeholder | Example | Description |
|---|---|---|
| `{project}` | `/home/laptran/ai-env/projects/invest-copilot` | Absolute path to the project root |
| `{task-name}` | `fix-alert-test` | The task folder name (kebab-case) |
| `{task-description}` | `Fix the alert test and complete sector rotation` | Brief description of what to do |

### How It Works

When you ask me to run a phase, I will:
1. Read the template file (e.g., `~/.agent-framework/prompts/implement.md`)
2. Replace all `{placeholders}` with actual values
3. Execute the rendered prompt

You never need to copy-paste prompts. Just tell me what to do.

### Example

You say: *"Implement the sector rotation task"*

I do:
```
Read: ~/.agent-framework/prompts/implement.md
Replace: {project} → /home/laptran/ai-env/projects/invest-copilot
         {task-name} → fix-alert-test-and-complete-sector-rotation
         {task-description} → Fix alert test and complete sector rotation service
Execute: The rendered prompt
```

## Scenario A: Existing Project (Drop-In)

Use this when the project already exists with code, tests, and structure.

### 1. Create the Project Framework Directory

```bash
mkdir -p /path/to/project/.agent-framework
```

### 2. Create the Two Required Files

Create these two files inside `.agent-framework/`:

#### AGENT.md (project level)
```markdown
# AGENT.md (project-name)

This project uses the global framework at ~/.agent-framework/.

Additional project rules are in RULES.md.

Default mode: research → implement → optional verification.
```

#### RULES.md (project level)
Start with any hard constraints you already know for this project. Keep it short.

Example:
```markdown
# RULES.md (project-name)

- Always separate research from implementation in fresh sessions.
- Never assume existing code or schema — explore first.
- [Add any other non-negotiables]
```

### 3. Run the Initial Exploration Ritual

Give the agent this prompt in a fresh session:

```
You have been given a new project at this path:
/path/to/project/

Your first actions must be:

1. Explore the project root using ls and find.
2. Read .agent-framework/AGENT.md
3. Read .agent-framework/RULES.md
4. Read ~/.agent-framework/AGENT.md

Report back with:
- Confirmation the framework files were found and read
- Summary of the project rules
- What process this project expects
- Key observations from the project structure

Do not start any task yet.
```

### 4. If You Don't Know What Task to Do Next

Run a research phase whose goal is to discover the highest-value next task.

Tell me: *"Research the project and find the next task"*

I will:
1. Read `~/.agent-framework/prompts/research.md`
2. Replace `{project}` with the project path
3. Set `{task-description}` to "Explore the project and identify the highest-value next task"
4. Execute the rendered prompt

### 5. Pick the First Task

Once the agent has completed the exploration report (or discovery research), give me the first real task.

### 6. Create the First Task Folder

```bash
mkdir -p /path/to/project/tasks/first-task-name/
```

I will then produce `SPEC.md` inside that folder during the research phase.

## Scenario B: Starting From Scratch

Use this when you have an idea but no code yet.

### 1. Create the Project Framework Directory

```bash
mkdir -p /path/to/project/.agent-framework
```

### 2. Create the Two Required Files

#### AGENT.md (project level)
```markdown
# AGENT.md (project-name)

This project uses the global framework at ~/.agent-framework/.

Additional project rules are in RULES.md.

Default mode: research → implement → optional verification.
```

#### RULES.md (project level)
```markdown
# RULES.md (project-name)

- Always separate research from implementation in fresh sessions.
- Start with a minimal viable structure — no over-engineering.
- [Add any other non-negotiables]
```

### 3. Run the Discovery Research

Tell me: *"Help me design the initial architecture for a new project. Here's what I have in mind: {your idea}"*

I will:
1. Read `~/.agent-framework/prompts/research.md`
2. Replace `{project}` with the project path
3. Set `{task-description}` to "Help design the initial architecture and first implementation task for a new project"
4. Execute the rendered prompt

### 4. Review and Approve the Spec

Review the SPEC.md. If it looks good, proceed to implementation. If not, iterate.

### 5. Create the Task Folder and Implement

```bash
mkdir -p /path/to/project/tasks/01-initial-setup/
```

Then tell me: *"Implement the first task"* and I'll run the implementation phase.

### 6. Iterate

After the first task is complete, create the next task folder and repeat:

```bash
mkdir -p /path/to/project/tasks/02-next-feature/
```

## Phase Prompts (Template Files)

All phase prompts are stored as template files. I render them automatically.

### Phase 1: Research

**Template**: `~/.agent-framework/prompts/research.md`
**Output**: `SPEC.md`

**Trigger**: *"Research {task-description}"*

### Phase 2: Implementation

**Template**: `~/.agent-framework/prompts/implement.md`
**Output**: Code changes + test results

**Trigger**: *"Implement the {task-name} task"*

### Phase 3: Bug Finding (Optional)

**Template**: `~/.agent-framework/prompts/bug_finder.md`
**Output**: `BUG_REPORT.md`

**Trigger**: *"Find bugs in the {task-name} task"*

### Phase 4: Referee (Optional)

**Template**: `~/.agent-framework/prompts/referee.md`
**Output**: `VERDICT.md`

**Trigger**: *"Review the {task-name} task"*

## Core Principles (From the Original Article)

These principles underpin the entire framework. Internalize them.

### 1. Context Is Everything
- Ruthlessly minimize what the agent sees. Irrelevant history, old notes, or too many skills destroys performance.
- Separate research from implementation. Don't make one agent both figure out *what* to build and *how* to implement it in the same session.
- Use fresh contexts/sessions per major task or "contract."

### 2. Handle Sycophancy (The "Desire to Please")
Agents are optimized to be helpful and agreeable. This leads to a common failure mode: if you say "find me a bug," it will often find (or invent) one because it wants to deliver.

**Solutions:**
- Use **neutral prompts** ("Search through the database, follow the logic of each component, and report all your findings") instead of leading ones.
- Exploit it productively with a **multi-agent validation loop**:
  - Agent A (Bug Finder): Scored +1 / +5 / +10 based on severity. It becomes hyper-aggressive at finding issues.
  - Agent B (Adversarial): Gets points for every bug it successfully disproves, but loses double if wrong. It aggressively tries to shoot them down.
  - Agent C (Referee): Told you have ground truth; scores both previous agents. This yields very high-fidelity results.

### 3. Define Clear End States ("How to End a Task")
Agents know how to start but not when to stop (they'll implement stubs and declare victory).

**Fixes:**
- Heavy use of tests as milestones ("Task is not complete until these X tests pass. You are not allowed to delete or modify the tests.")
- Create a **{TASK}_CONTRACT.md** that explicitly lists all acceptance criteria, tests, screenshots, etc. Make this the single source of truth for completion.
- Use stop-hooks that prevent the agent from ending the session until the contract is satisfied.

### 4. Rules + Skills (The Actual Memory System)
Treat your CLAUDE.md (or equivalent) as a lightweight router/directory, not a massive dump.

- **Rules**: Encode preferences and prohibitions ("If coding, read coding-rules.md first"). Make them conditional and nested.
- **Skills**: Encode repeatable *recipes* ("This is exactly how we implement authentication" or "This is our research process").
- Start minimal. Iteratively add rules/skills as you observe unwanted behavior.
- When performance degrades (contradictions or bloat), have the agent consolidate, de-duplicate, and ask you to resolve conflicts.

### 5. Long-Running Agents
24/7 autonomous agents often fail due to context accumulation and drift.

**Better pattern:**
- One focused session per contract/task.
- An orchestration layer that spawns new clean sessions.
- Avoid throwing everything into one forever-running context.

### 6. Stay Current Without Chasing
Just update your CLI regularly and read the release notes. If Anthropic/OpenAI add or acquire something (skills, memory, planning, etc.), pay attention. Most "new hot harness" hype becomes obsolete quickly.

## Notes

- Only create the two files in step 2. Do not copy the entire global framework.
- The global `~/.agent-framework/` already contains the prompts and contracts.
- Keep project RULES.md short and specific to this project.
- Always start with a fresh agent session for each phase.
- Phase 3 and 4 are optional but recommended for critical features.
- Use `{task-name}_CONTRACT.md` for critical tasks to define explicit acceptance criteria.